docs(analyze): bound the forge pass by quota share and a short CI window

src/content/docs/cli/ci-cd/granular-actions.md

@@ -109,6 +109,8 @@ rules:
 
 A scanner with no gate reports and never fails its job. There is no baseline, so turn a gate on once a run is clean at that level.
 
-On a pull request the rendered jobs do not spend the repository's GitHub API quota. Every scanner step gets `github-token: ${{ github.event_name != 'pull_request' && github.token || '' }}`, so a pull-request scan runs without the job token and does not resolve unknown licences through the GitHub API, and the `analyze` job adds `--no-forge`, so it skips the pass that reads every pull request and issue. That quota is shared with every other job in the repository, CodeQL's SARIF upload among them, and a large repository's scans used to spend it in minutes. The push to the default branch keeps the token and the forge pass, and is the run that publishes.
+On a pull request the rendered jobs do not spend the repository's GitHub API quota. Every scanner step gets `github-token: ${{ github.event_name != 'pull_request' && github.token || '' }}`, so a pull-request scan runs without the job token and does not resolve unknown licences through the GitHub API, and the `analyze` job adds `--no-forge`, so it skips the pass that reads every pull request and issue. That quota is shared with every other job in the repository, CodeQL's SARIF upload among them, and a large repository's scans used to spend it in minutes. The push to the default branch keeps the token and is the run that publishes.
+
+The forge pass is bounded on every other run too. On a push or a release the `analyze` job passes `--forge-window-days=7`, so it reads only the last week of pull requests, issues and commit reviews from GitHub. The git history window stays at a year. Only a manual run (`workflow_dispatch`) reads the full window from GitHub. Whatever the window, `analyze` stops the forge pass while half the token's hourly limit is still left, and the report carries a warning when it stopped early. A push lands on every merge, and an auto-versioned repository publishes a release on every merge too. A year-long forge pass on each of them used to spend the repository's quota until CodeQL's upload and the release dispatch failed with `API rate limit exceeded for installation`.
 
 `vulnetix gha init --check` writes nothing and exits 1 when the workflow differs from what the policy renders. It ignores action refs, so a [locked](/cli/ci-cd/actions-lockfile/) workflow stays current.

src/content/docs/cli/commands/analyze.md

@@ -30,6 +30,8 @@ On success it prints, for example, `GitHub authentication: ok (octocat via gh CL
 
 `--no-forge` skips GitHub: those metrics are then `not measured`. A repository whose remote is not GitHub skips the check by itself.
 
+**The GitHub quota is shared.** In GitHub Actions, the job token's hourly quota belongs to the whole repository, and every job shares it. So `analyze` stops reading from GitHub while half the token's hourly limit is still left (never less than 100 requests). When that happens, the report carries a `forge` warning saying so. Each pull request costs several requests. `--forge-window-days` reads a shorter window from GitHub than `--window-days` reads from git, so the run makes fewer requests.
+
 **A clone or a worktree.** Both work: a worktree's history is read from the main repository's git directory, so history metrics match the main checkout. A shallow clone has less history; increase the fetch depth for the window you want.
 
 **Vulnetix credentials (optional).** Dependency staleness needs registry metadata from Vulnetix. Without credentials those metrics are `null` with a reason, and the report is not uploaded.
@@ -40,6 +42,7 @@ On success it prints, for example, `GitHub authentication: ok (octocat via gh CL
 |---|---|---|
 | `[path]`, `--path <dir>` | `.` | Repository to analyse. The positional argument wins. |
 | `--window-days <n>` | `365` | How far back to walk history |
+| `--forge-window-days <n>` | `0` (same as `--window-days`) | How far back to read pull requests, issues and commit reviews from GitHub |
 | `--max-commits <n>` | `20000` | Cap on commits walked; the report says when it was hit |
 | `--complexity-threshold <n>` | `15` | Cyclomatic complexity at which a file counts as highly complex |
 | `--no-git` | off | Skip the history walk: activity, contributor and ownership metrics are absent |