docs(actions): GitHub Actions setup and usage guide, generated tables, docs-sync rule

.github/pull_request_template.md

@@ -12,4 +12,6 @@ Closes #
 - [ ] `scripts/ci-local.sh` passes (`TOOLCHAIN=1.94 scripts/ci-local.sh`)
 - [ ] Tests added or updated (`tests/cli.rs`, fixtures, golden files)
 - [ ] Docs regenerated if directives or flags changed (`scripts/gen-docs.sh`)
+- [ ] Docs updated in this PR for every behaviour change (mapping in `AGENTS.md`: `actions/*` → `docs/GITHUB_ACTIONS.md` + `scripts/gen-actions-docs.sh`, CLI → `README.md`, release process → `docs/RELEASING.md`)
+- [ ] `CHANGELOG.md` has a line under `## [Unreleased]` if users will notice the change
 - [ ] No secrets in code, fixtures or output

.github/workflows/actions-selftest.yml

@@ -26,7 +26,7 @@ jobs:
   release-setup-smoke:
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install from release
         uses: ./actions/setup
         with:
@@ -43,7 +43,7 @@ jobs:
       matrix:
         os: [ubuntu-24.04, macos-15]
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Check (setup + drift + lint)
         uses: ./actions/check
         with:
@@ -74,7 +74,7 @@ jobs:
   drift-failure:
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: ./actions/setup
         with:
           version: source
@@ -107,7 +107,7 @@ jobs:
       matrix:
         version: [source, v0.1.0-rc.3]
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: annotate-src
       - name: Create consumer fixture repo

.github/workflows/ci.yml

@@ -35,6 +35,8 @@ jobs:
         run: cargo test --locked --test gateway_policies
       - name: docs are up to date
         run: scripts/gen-docs.sh --check
+      - name: GitHub Actions docs match action.yml
+        run: scripts/gen-actions-docs.sh --check
 
   audit:
     runs-on: ubuntu-latest

AGENTS.md

@@ -26,3 +26,19 @@ subprocesses; add directives with reasons; run `scan`, `generate`, `lint`, `drif
 - Human output: `src/report.rs` renders lint; `src/render.rs` renders `scan`, `diff-logs` and the `generate` summary in the same
   style (shared `Style`, icons, `--format/--color/--no-icons`). `--format compact` and `--format json` must stay byte-stable
   and `generate` must never put anything but the policy on stdout. Snapshots live in `tests/golden` (`UPDATE_GOLDEN=1 cargo test`).
+
+## Docs must be updated in the same PR
+A change is not done until the docs that describe it match. Update them in the same pull request:
+
+| When you change | Update |
+| --- | --- |
+| `actions/*` (inputs, outputs, behaviour) or `actions/lib/*` | `docs/GITHUB_ACTIONS.md`: run `scripts/gen-actions-docs.sh` for the tables, then fix the prose, recipes and troubleshooting; the README snippet if usage changed |
+| CLI commands, flags, exit codes or output | `README.md` and `scripts/gen-docs.sh` (regenerates `docs/CLI.md`); `docs/DEVELOPING.md` if a workflow changes |
+| Directives or attributes (`src/directive.rs`, `src/spec.rs`, `src/generate.rs`) | `scripts/gen-docs.sh` (regenerates `docs/DIRECTIVES.md`) and `skills/annotate-openshell-policy/SKILL.md` if authoring guidance changes |
+| Release process (`scripts/release.sh`, `release.yml`, `install.sh`, packaging) | `docs/RELEASING.md` |
+| Pinned OpenShell version (`Cargo.toml`) | every doc that names the version (`git grep -n 'v0\.1\.[0-9]'`) |
+| Branch, issue or CI rules | `CONTRIBUTING.md`, `docs/DEVELOPING.md`, `.github/pull_request_template.md` |
+| Anything user-visible | a line under `## [Unreleased]` in `CHANGELOG.md` |
+
+CI enforces the generated parts (`scripts/gen-docs.sh --check`, `scripts/gen-actions-docs.sh --check`); the rest is on
+the author and the reviewer.

CHANGELOG.md

@@ -7,6 +7,7 @@ version section and adds the squash-merged PR titles since the previous tag. Ver
 
 - chore(audit): ignore RUSTSEC-2026-0459 (`libsqlite3-sys` 0.37.0, pinned by OpenShell v0.1.7 through `sqlx` 0.9.0) in `.cargo/audit.toml` until OpenShell upgrades it (#76)
 - chore(deps): build against OpenShell v0.1.7 (`openshell-policy-schema`, `openshell-policy`); docs and generated policy headers now name v0.1.7
+- docs(actions): `docs/GITHUB_ACTIONS.md` is now a setup and usage guide (versions, recipes, troubleshooting); its inputs/outputs tables are generated from `action.yml` by `scripts/gen-actions-docs.sh` and checked in CI
 - fix(diff-logs): ignore OCSF Network Activity Refuse records (policy DNS `policy_dns_ineligible`) that have no port, so OCSF JSON and shorthand logs report the same denials
 
 ## [0.1.0-rc.3] - 2026-11-09

CONTRIBUTING.md

@@ -42,6 +42,10 @@ GitHub issues are how we track all work: bugs, features and follow-ups.
   `tests/fixtures/`). If generated output changes, review `tests/fixtures/sample/policy.expected.yaml` by hand (its header carries `@VERSION@`, which the tests replace with the crate version).
 - Never emit a field that the pinned `openshell-policy-schema` rejects.
 - No secrets in code, fixtures or test output.
+- Update the docs in the same pull request. The table in [AGENTS.md](AGENTS.md#docs-must-be-updated-in-the-same-pr)
+  maps code areas to docs: `actions/*` to `docs/GITHUB_ACTIONS.md`, CLI flags and commands to `README.md` and the
+  generated `docs/CLI.md`, directives to the generated `docs/DIRECTIVES.md`, the release process to `docs/RELEASING.md`,
+  and user-visible changes to `CHANGELOG.md`.
 
 ## Checks (CI runs the same)
 
@@ -52,6 +56,7 @@ cargo fmt --check
 cargo clippy --all-targets --locked -- -D warnings
 cargo test --locked
 scripts/gen-docs.sh --check      # regenerate with scripts/gen-docs.sh when directives or flags change
+scripts/gen-actions-docs.sh --check   # regenerate with scripts/gen-actions-docs.sh when an action.yml changes
 ```
 
 ## Developer Certificate of Origin (DCO)

README.md

@@ -15,15 +15,22 @@ Status: early prototype (version 0.1.0). Targets OpenShell policy schema v1
 
 Downstream repositories can run drift, lint, generate, and diff-logs in CI with composite actions under
 [`actions/`](actions/). Pin a release tag on every `uses:` line (same ref for all steps). See
-[docs/GITHUB_ACTIONS.md](docs/GITHUB_ACTIONS.md) for inputs, outputs, and copy-paste workflows.
+[docs/GITHUB_ACTIONS.md](docs/GITHUB_ACTIONS.md) for setup, choosing a version, inputs and outputs, recipes and
+troubleshooting.
 
 ```yaml
-- uses: ilanh/openshell-annotate/actions/check@v0.1.0-rc.3
+- uses: ilanh/openshell-annotate/actions/setup@v0.1.0-rc.3
+- uses: ilanh/openshell-annotate/actions/drift@v0.1.0-rc.3
   with:
     policy: openshell/policy.yaml
     providers: openshell/providers.json
+- uses: ilanh/openshell-annotate/actions/lint@v0.1.0-rc.3
+  with:
+    policy: openshell/policy.yaml
 ```
 
+The combined `check` action works from other repositories on `main` and in releases after `v0.1.0-rc.3` (#65).
+
 ## Install
 
 Prebuilt binaries (Linux and macOS, x86_64 and arm64) and a container image are attached to each

actions/check/action.yml

@@ -6,7 +6,7 @@ branding:
 
 inputs:
   version:
-    description: Release tag for setup (`latest`, a tag, or `source` to build this repository).
+    description: CLI version, as for `setup` (a release tag, `latest` for the newest stable release, or `source` to build the action's own ref).
     required: false
     default: v0.1.0-rc.3
   root:
@@ -21,7 +21,7 @@ inputs:
     required: false
     default: ""
   profiles-dir:
-    description: Provider profiles directory.
+    description: Provider profiles directory for drift (`--profiles-dir`).
     required: false
     default: ""
   failure-threshold:
@@ -52,7 +52,7 @@ runs:
     - name: Restore cache
       if: inputs.version != 'source'
       id: cache
-      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.2
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
       with:
         path: ${{ steps.dir.outputs.dir }}/openshell-annotate
         key: openshell-annotate-${{ runner.os }}-${{ runner.arch }}-${{ inputs.version }}

actions/generate/action.yml

@@ -74,7 +74,7 @@ runs:
 
     - name: Upload artifact
       if: inputs.upload-artifact == 'true'
-      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v4.6.2
+      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
       with:
         name: ${{ inputs.artifact-name }}
         path: |

actions/setup/action.yml

@@ -7,20 +7,20 @@ branding:
 inputs:
   version:
     description: >
-      Release tag to install (e.g. v0.1.0-rc.3), `latest`, or `source` to build from the checked-out
-      repository with cargo (Rust 1.94+ required; for this repo's CI only).
+      Release tag to install (e.g. v0.1.0-rc.3), `latest` (newest stable release only), or `source` to build
+      the openshell-annotate sources at the action's own ref with cargo (Rust 1.94+).
     required: false
     default: v0.1.0-rc.3
   install-dir:
-    description: Directory for the openshell-annotate binary (added to PATH).
+    description: Directory for the openshell-annotate binary (added to PATH); empty means `$RUNNER_TOOL_CACHE/openshell-annotate`.
     required: false
     default: ""
   verify-attestation:
     description: Run `gh attestation verify` after download (needs GitHub CLI + contents:read).
     required: false
     default: "false"
   cache:
-    description: Cache the installed binary between runs.
+    description: Cache the installed binary between runs (keyed on OS, arch and `version`; not used for `source`).
     required: false
     default: "true"
 
@@ -45,7 +45,7 @@ runs:
     - name: Restore cache
       if: inputs.cache == 'true' && inputs.version != 'source'
       id: cache
-      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.2
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
       with:
         path: ${{ steps.dir.outputs.dir }}/openshell-annotate
         key: openshell-annotate-${{ runner.os }}-${{ runner.arch }}-${{ inputs.version }}

docs/DEVELOPING.md

@@ -47,7 +47,7 @@ Expected: four result lines, all `ok` (26 unit tests, 30 CLI tests in `tests/cli
 ## 4. Run what CI runs
 
 CI (`.github/workflows/ci.yml`) runs `cargo fmt --check`, `cargo clippy --all-targets --locked -- -D warnings`,
-`cargo test --locked` and `scripts/gen-docs.sh --check`, plus `cargo audit`. All but the audit are one command:
+`cargo test --locked`, `scripts/gen-docs.sh --check` and `scripts/gen-actions-docs.sh --check`, plus `cargo audit`. All but the audit are one command:
 
 ```
 TOOLCHAIN=1.94 scripts/ci-local.sh     # pinned like CI; omit TOOLCHAIN to use your default toolchain
@@ -60,6 +60,8 @@ separate commit (CI will keep using 1.94 until the pin is bumped on purpose in `
 
 `docs/CLI.md` and `docs/DIRECTIVES.md` are generated from the code. After changing a flag, directive or attribute run
 `scripts/gen-docs.sh` and commit the result; `scripts/gen-docs.sh --check` (and `cargo test`) fail when they are stale.
+The inputs/outputs tables in `docs/GITHUB_ACTIONS.md` are generated from `actions/*/action.yml` the same way
+(`scripts/gen-actions-docs.sh`). Which docs to update for which change is listed in `AGENTS.md`.
 
 ### Upstream compatibility (OpenShell schema changes)
 
@@ -202,5 +204,6 @@ public repo or a paid plan).
 | `error: failed to select a version` / git fetch of `OpenShell` fails | the schema crate comes from github.com; check network or proxy; `--locked` needs the tag commit recorded in `Cargo.lock` |
 | clippy errors that CI does not show | newer toolchain; run with `TOOLCHAIN=1.94` or fix the new lint |
 | `docs are stale` | run `scripts/gen-docs.sh` and commit `docs/` |
+| `docs/GITHUB_ACTIONS.md is out of date with actions/*/action.yml` | run `scripts/gen-actions-docs.sh` and commit it; add a `BEGIN/END actions-docs <name>` section for a new action |
 | sandbox probes get `403` from `api.github.com` | unauthenticated GitHub API rate limit (60 requests per hour per IP), not a policy decision; wait for the reset or use another host |
 | `openshell-prover: not found` in `flow.sh` | install the OpenShell 0.1.7 tools; the static commands (`scan`, `generate`, `lint`, `drift`, `diff-logs`) do not need them |