docs: clarify Dependabot workflow permissions

README.md

@@ -47,11 +47,13 @@ For a GitHub-based setup, the repository should add:
 - a Dependabot-only gate such as `if: github.event.pull_request.user.login == 'dependabot[bot]'`
 - a metadata step such as `dependabot/fetch-metadata` to map the pull request to `--ecosystem`, `--package`, `--current`, and `--candidate`
 
+If you use `dependabot/fetch-metadata`, grant the job `pull-requests: read`. For a minimal working example and the full CI guidance, see `docs/guide/ci-and-deploy.md` and `examples/ci/README.md`.
+
 The safest default is to run Limier in the unprivileged `pull_request` context and keep any commenting, labeling, or auto-merge behavior in a separate privileged follow-up workflow if needed. Avoid checking out and running pull request code from `pull_request_target`.
 
 For GitHub-hosted runners, assume Docker is available but full host-signal capture is not. A stock hosted runner should therefore use a CI-specific scenario with `capture_host_signals: false`, or you should run Limier on a self-hosted Linux runner with `bpftrace` installed when full host telemetry is required.
 
-The sample runner in `examples/ci/run-sample.sh` is intentionally hardcoded to a repository-owned demo dependency upgrade. It is a runnable example, not the Dependabot glue layer.
+The sample runner in `examples/ci/run-sample.sh` and the sample workflow in `examples/ci/github-actions.yml` are intentionally hardcoded to a repository-owned demo dependency upgrade. They are runnable examples, not a drop-in Dependabot glue layer.
 
 ## Container Image
 

docs/guide/ci-and-deploy.md

@@ -10,7 +10,7 @@ The report is the source of truth. Rendered outputs are just alternate presentat
 
 ## Minimal GitHub Actions Example
 
-This repository includes a small sample workflow:
+This repository includes a small sample workflow for manually running the repository-owned demo assets:
 
 ```yaml
 name: limier
@@ -53,8 +53,9 @@ For GitHub, the usual setup is:
 - trigger a workflow on `pull_request`
 - gate the job with `github.event.pull_request.user.login == 'dependabot[bot]'`
 - use PR metadata to fill in `--ecosystem`, `--package`, `--current`, and `--candidate`
+- grant `pull-requests: read` if you use `dependabot/fetch-metadata`
 
-A minimal gate looks like this:
+A minimal gate and permission set looks like this:
 
 ```yaml
 on:
@@ -64,9 +65,12 @@ on:
 jobs:
   limier:
     if: github.event.pull_request.user.login == 'dependabot[bot]'
+    permissions:
+      contents: read
+      pull-requests: read
 ```
 
-That read-only review job is a good default, but remember that `pull_request` runs from forks and Dependabot PRs get a read-only `GITHUB_TOKEN`, so comment, label, merge, or other write-back actions should happen in a separate privileged follow-up workflow such as `workflow_run`.
+That read-only review job is a good default. If it uses `dependabot/fetch-metadata`, remember that once a GitHub Actions `permissions` block is present, omitted scopes default to `none`, so `pull-requests: read` must be declared explicitly. Also remember that `pull_request` runs from forks and Dependabot PRs get a read-only `GITHUB_TOKEN`, so comment, label, merge, or other write-back actions should happen in a separate privileged follow-up workflow such as `workflow_run`.
 
 ::: warning Avoid `pull_request_target` for the review run
 The safest default is to run Limier in the unprivileged `pull_request` context and keep commenting, labeling, or auto-merge behavior in a separate privileged follow-up workflow if you need it.

examples/ci/README.md

@@ -24,7 +24,7 @@ Docker is still required at runtime because Limier executes fixtures in containe
 
 ## Dependabot Usage
 
-The files in this directory are sample wrappers around the repository-owned demo assets. They are useful for proving out the CI contract, but they are not a drop-in Dependabot integration.
+The files in this directory are sample wrappers around the repository-owned demo assets. They are useful for proving out the CI contract, but they are not a drop-in Dependabot integration. You still need to add Dependabot-specific triggers, metadata wiring, and permissions in your own repository workflow.
 
 For a real Dependabot workflow, the repository should usually add:
 
@@ -33,7 +33,7 @@ For a real Dependabot workflow, the repository should usually add:
 3. A metadata step such as `dependabot/fetch-metadata` so the workflow can pass the dependency name, ecosystem, previous version, and new version into `limier run`.
 4. A CI-specific scenario when running on GitHub-hosted runners, because hosted runners should not be assumed to have `bpftrace` available.
 
-A minimal Dependabot gate looks like this:
+A minimal Dependabot gate and permission set looks like this:
 
 ```yaml
 on:
@@ -43,6 +43,11 @@ on:
 jobs:
   limier:
     if: github.event.pull_request.user.login == 'dependabot[bot]'
+    permissions:
+      contents: read
+      pull-requests: read
 ```
 
+If that job uses `dependabot/fetch-metadata`, `pull-requests: read` is required. Once a GitHub Actions `permissions` block is present, any omitted scopes default to `none`.
+
 If you want Limier to post comments, add labels, or enable auto-merge, keep that behavior in a separate privileged follow-up workflow rather than running pull request code from `pull_request_target`.