docs: document the v1 workflow interface

.coderabbit.yaml

@@ -84,12 +84,9 @@ reviews:
 
     - path: "examples/**"
       instructions: |
-        Examples are copied into calling repositories. `examples/deb` and
-        `examples/npm` show the v1 interface: flag a call to a legacy workflow
-        or an `@main` pin there, and a `pr.yml` whose `status` job does not
-        need every other job. `examples/cockpit-apt` shows the legacy
-        workflows and `examples/docs-repo` still pins `@main` until the v1
-        documentation work in issue 54 replaces them; do not flag either.
+        Examples are copied into calling repositories. Flag a call to a
+        legacy workflow, a pin other than `@v1`, and a `status` job that does
+        not need every other job in its file.
 
 knowledge_base:
   code_guidelines:

AGENTS.md

@@ -14,7 +14,11 @@ A caller depends on:
 
 - workflow filenames under `.github/workflows/`
 - `workflow_call` inputs, secrets, and outputs
-- the repo-local actions a caller must provide (`.github/actions/run-tests`, `build-deb`, `check-versions`)
+- the repo-local actions a caller provides: `.github/actions/run-tests`, `build-deb` for Debian packages, and the optional `check-versions`
+- the arguments passed to optional `.github/scripts/` overrides, and the files they must write
+- the permissions a calling job must grant
+- the `concurrency` group with `cancel-in-progress: false` that a caller's `main.yml` must set, because `release-version.yml` computes the revision from existing tags
+- the `VERSION` file and the `v<upstream>+<N>` and `v<upstream>+<N>_pre` tag formats
 
 Changing any of these incompatibly is a breaking change and ships as a new major version.
 

examples/docs-repo/.github/workflows/translation-status.yml

@@ -25,17 +25,16 @@ concurrency:
 
 jobs:
   translation-status:
-    uses: halos-org/shared-workflows/.github/workflows/translation-status.yml@main
+    uses: halos-org/shared-workflows/.github/workflows/translation-status.yml@v1
 
   # A reusable-workflow call reports as `<caller job> / <called job>`, so the
   # check name is not the caller's to choose and changes if the called job is
   # ever renamed. Carrying the required context on a plain job of your own
-  # decouples branch protection from both. Drop this job if you would rather
-  # require `translation-status / translation-status` directly.
+  # decouples branch protection from both.
   status:
     needs: translation-status
-    # always(), or a failed gate leaves this skipped, and a skipped required
-    # check never reports either. GitHub waits on a required context forever.
+    # always(), or a failed gate skips this job, and GitHub counts a skipped
+    # required check as passing.
     if: always()
     permissions: {}
     runs-on: ubuntu-latest