@ebalzan/ci 0.0.0-stage → 3.0.0

package/docs/CLI.md

@@ -0,0 +1,229 @@
+# CLI reference
+
+```text
+npx @ebalzan/ci <command> [options]
+```
+
+Install it as a devDependency (`npm install --save-dev @ebalzan/ci`) and the
+binary is `ebalzan-ci` in npm scripts and husky hooks. Without installing,
+prefix with `npx @ebalzan/ci`. From a git checkout of this repo, `node
+bin/cli.mjs <command>` and the scripts in `bin/` work the same way.
+
+The commands that change GitHub (`onboard`, `bootstrap`, `reset`) are bash
+scripts and need [`gh`](https://cli.github.com) logged in as an **admin** of
+the target repo. Each one prints a plan and asks before changing anything, and
+each has `--dry-run`.
+
+| Command                         | Summary                                                   |
+| ------------------------------- | --------------------------------------------------------- |
+| [`onboard`](#onboard)           | Bring a repo under the shared rules in one step           |
+| [`bootstrap`](#bootstrap)       | Sync variables, secrets, settings and rulesets onto repos |
+| [`reset`](#reset)               | Delete Actions variables/secrets on a repo                |
+| [`commit-msg`](#commit-msg)     | Validate a commit message (husky hook)                    |
+| [`path`](#path)                 | Print the package directory                               |
+| [`sync-managed`](#sync-managed) | Deprecated: refresh local copies of managed files         |
+| `version`, `help`               | Print the version / the command list                      |
+
+---
+
+## onboard
+
+Adds everything a repo needs, on a branch, and opens it for review.
+
+```bash
+ebalzan-ci onboard [-C DIR] [options]
+```
+
+| Option                  | Default                   | Effect                                                                                                                                                  |
+| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-C, --repo-dir DIR`    | `.`                       | Checkout of the repo to onboard                                                                                                                         |
+| `-R, --repo OWNER/REPO` | from the git remote       | Its slug                                                                                                                                                |
+| `--runs-on LABEL`       | `ubuntu-latest`           | Runner label written into every caller (e.g. `self-hosted`)                                                                                             |
+| `--ref REF`             | `v<major of the package>` | Ref the callers pin. Keep the major tag (`v2`); an exact version only freezes the workflow files ([why](ARCHITECTURE.md#9-versions-what-a-pin-freezes)) |
+| `--branch NAME`         | `ci/onboard-ebalzan-ci`   | Branch the files are committed on                                                                                                                       |
+| `--force`               | off                       | Replace files that already exist (default: keep them)                                                                                                   |
+| `--no-npm`              | off                       | Do not install packages, even with a `package.json` (files and `package.json` fields are still written)                                                 |
+| `--no-config`           | off                       | Do not wire `@ebalzan/config` (Prettier, ESLint)                                                                                                        |
+| `--no-push`             | off                       | Stop after the local commit: GitHub is not touched at all                                                                                               |
+| `-n, --dry-run`         | off                       | Print the plan; change nothing                                                                                                                          |
+| `-y, --yes`             | off                       | No confirmation prompts (also for the bootstrap it runs)                                                                                                |
+
+What it does, in order:
+
+1. Checks the tree is clean and the branch does not exist yet.
+2. Branches from `origin/dev`, or from the default branch when `dev` does not
+   exist yet.
+3. Writes the [templates](../templates/) with `__CI_REPO__`, `__CI_REF__` and
+   `__RUNS_ON__` filled in. Existing files are kept unless `--force`. The husky
+   hook and `eslint.config.mjs` are only written for a repo with `package.json`
+   (and `eslint.config.mjs` only when it has no ESLint config of its own);
+   `renovate.json` is skipped when the repo has its own Renovate config.
+4. Appends the `.github/secrets*.env` ignore lines to `.gitignore`, unless those
+   files are already ignored.
+5. Node repos, code style (unless `--no-config`): sets `package.json`
+   `"prettier": "@ebalzan/config/prettier"` when the repo has no Prettier config
+   of its own. A `tsconfig.json` that does not extend
+   `@ebalzan/config/tsconfig/*` is reported, never edited.
+6. Node repos, installs (unless `--no-npm`): `@ebalzan/ci@^<major>` and husky (if
+   missing), `scripts.prepare = "husky"` when there is no prepare script, and
+   `@ebalzan/config` with its peers `eslint` and `prettier` (if missing), at
+   exact versions. A failure here only warns.
+7. Commits as `ci: onboard ebalzan/ci shared workflows and rules`.
+8. Unless `--no-push`, after one confirmation: creates `dev` on GitHub from the
+   default branch if missing, adds the `REPOS_TOPIC` topic, runs
+   [`bootstrap`](#bootstrap), pushes the branch. The `auto-pr.yml` just added
+   runs on that push and opens the issue and the PR into `dev`.
+
+Walkthrough: [ONBOARDING.md](ONBOARDING.md).
+
+---
+
+## bootstrap
+
+Applies the merged shared + repo config to GitHub. Idempotent: run it as often
+as you like.
+
+```bash
+ebalzan-ci bootstrap                      # the repo in the current directory
+ebalzan-ci bootstrap -C ../my-repo        # a local checkout
+ebalzan-ci bootstrap -R owner/my-repo     # no checkout: remote mode
+ebalzan-ci bootstrap --all --dry-run      # every managed repo, plan only
+```
+
+| Option                  | Effect                                                                                                                       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `-C, --repo-dir DIR`    | Checkout whose `.github/` holds the repo layer (default: `.`)                                                                |
+| `-R, --repo OWNER/REPO` | Target repo. Alone: remote mode, unless the current directory is a checkout of it. With `-C`: push DIR's config to that slug |
+| `-a, --all`             | Every repo `config/repos.env` selects (topic + list), each from its local checkout when there is one                         |
+| `--skip LIST`           | Comma-separated sections to leave alone: `vars`, `secrets`, `settings`, `rulesets`                                           |
+| `--prune`               | Also delete what no file defines: variables, secrets, and rulesets named `ci: …` (asks first)                                |
+| `-n, --dry-run`         | Print the merged plan and, when gh is logged in, the settings diff and ruleset actions; change nothing                       |
+| `-y, --yes`             | No confirmation prompts                                                                                                      |
+
+Sections, in the order they are applied:
+
+| Section    | From                                                                                                        | To GitHub                                                 |
+| ---------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `vars`     | the repo's `.github/actions.env` only (shared ones are read at run time)                                    | repository variables                                      |
+| `secrets`  | shared `secrets.env` + the repo's `secrets.env`, and `secrets.<env>.env` (from the repo secrets dir, below) | repository secrets; environment `<env>` (created) secrets |
+| `settings` | `config/repo-settings.json` deep-merged with `.github/repo-settings.json`                                   | `PATCH /repos/{repo}` (only changed keys are listed)      |
+| `rulesets` | each `config/rulesets/X.json` deep-merged with `.github/rulesets/X.json`                                    | created, or updated by `name`                             |
+
+**Where the shared secrets come from:** `$CI_SECRETS_DIR` if set; otherwise
+`config/` when running from a git checkout of this repo; otherwise
+`~/.config/ebalzan-ci/` (or `$XDG_CONFIG_HOME/ebalzan-ci/`). A missing file is
+simply no shared secrets.
+
+**Where a repo's own secrets come from:** `repos/<owner>/<repo>/` inside the
+shared secrets dir when that folder exists (matched case-insensitively; the
+checkout's `secrets*.env` are then ignored, with a warning); otherwise the
+checkout's gitignored `.github/`. Keeping them in the shared secrets dir is
+recommended: one folder for every repo, usable without checkouts
+([ARCHITECTURE §7](ARCHITECTURE.md#7-where-you-run-commands)).
+
+**Remote mode** (`-R` without a checkout) reads the repo's committed
+`.github/actions.env`, `bootstrap.conf`, `repo-settings.json` and `rulesets/`
+from its default branch, and its secrets from `repos/<owner>/<repo>/`. Without
+that folder its secrets are unknown: only shared secrets are synced, and
+secrets are never pruned.
+
+**Guards:** empty and placeholder secret values (`xxxx`, `sk-ant-xxx`,
+`github_pat_xxx`) are refused before anything is sent; a `_FILE` key sets the
+secret from a file's contents; `LOCAL_ONLY_KEYS` in `.github/bootstrap.conf`
+are never pushed. Details: [GITHUB_ACTIONS_SETUP.md §4](GITHUB_ACTIONS_SETUP.md#4-file-mechanics).
+
+**Rulesets on a private repo** need GitHub Pro/Team. On the free plan GitHub
+answers "Upgrade to GitHub Pro or make this repository public", and the step
+warns and moves on.
+
+---
+
+## reset
+
+Deletes Actions variables (default) and/or secrets on one repo, after showing
+them and asking you to type the repo name. Prefer `bootstrap --prune` to remove
+only what no file defines any more.
+
+```bash
+ebalzan-ci reset --dry-run                              # what would go
+ebalzan-ci reset -R owner/repo --include-secrets
+ebalzan-ci reset --match '^AUTO_'
+ebalzan-ci reset --env production --secrets-only --dry-run
+```
+
+| Option                  | Effect                                              |
+| ----------------------- | --------------------------------------------------- |
+| `-C, --repo-dir DIR`    | Checkout whose remote picks the repo (default: `.`) |
+| `-R, --repo OWNER/REPO` | Target repo                                         |
+| `-e, --env NAME`        | Act on environment `NAME` instead of the repository |
+| `--include-secrets`     | Also delete secrets                                 |
+| `--secrets-only`        | Delete secrets only                                 |
+| `-m, --match REGEX`     | Only names matching this extended regex             |
+| `-n, --dry-run`         | List; delete nothing                                |
+| `-y, --yes`             | Skip the typed confirmation (dangerous)             |
+
+It never touches settings or rulesets.
+
+---
+
+## commit-msg
+
+```bash
+ebalzan-ci commit-msg <message-file | subject>
+```
+
+Exits 0 when the first non-comment line is a Conventional Commit subject with
+one of the [allowed types](COMMIT_GUIDE.md#allowed-types), 1 (with an example)
+otherwise. Subjects git writes itself (`Merge …`, `Revert "…"`, `fixup! …`,
+`squash! …`, `amend! …`) pass. The rule is
+`managed/scripts/release/validate-conventional-subject.sh` — the same file the
+PR-title check runs in CI.
+
+The hook `onboard` writes (`.husky/commit-msg`):
+
+```sh
+if [ -x node_modules/.bin/ebalzan-ci ]; then
+  exec node_modules/.bin/ebalzan-ci commit-msg "$1"
+fi
+# …falls back to a checkout of ebalzan/ci at ${CI_DIR:-../ci}, else warns and
+# lets the commit through (CI still checks the PR title).
+```
+
+---
+
+## path
+
+Prints the installed package directory, for scripts that want the shared shell
+helpers or config:
+
+```bash
+source "$(npx --no-install ebalzan-ci path)/bin/_lib.sh"   # info/ok/warn/die, env_get, detect_repo, …
+```
+
+---
+
+## sync-managed
+
+**Deprecated.** Before 2.0, repos could keep a verbatim copy of the validator
+at `scripts/release/validate-conventional-subject.sh`; the PR-title check fails
+when such a copy drifts. This refreshes those copies (`--install` creates them,
+`--check` only reports). Prefer deleting the copy and using the hook above.
+
+---
+
+## Environment variables
+
+| Variable                    | Used by                                 | Meaning                                                                                                        |
+| --------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `CI_SECRETS_DIR`            | `bootstrap`                             | Directory with the shared `secrets.env` / `secrets.<env>.env`, and `repos/<owner>/<repo>/` for each repo's own |
+| `CI_REPOS_ROOT`             | `bootstrap --all`, `sync-managed --all` | Where local checkouts live: `<root>/<repo name>` (default: next to this package's checkout)                    |
+| `CI_DIR`                    | the husky hook                          | A checkout of this repo, used when the package is not installed (default `../ci`)                              |
+| `XDG_CONFIG_HOME`           | `bootstrap`                             | Base of the default shared secrets dir                                                                         |
+| `NO_COLOR` / non-TTY output | all                                     | Plain output without colours                                                                                   |
+
+The pre-2.0 name `TRACEBIM_REPOS_ROOT` is still honoured.
+
+## Exit codes
+
+`0` success (including a completed dry run) · `1` a check failed, invalid
+input, or the user aborted · `127` bash/sh not found.

package/docs/COMMIT_GUIDE.md

@@ -0,0 +1,133 @@
+# Commit Guide
+
+## Purpose
+
+This guide defines the commit conventions every repo using ebalzan/ci follows and how
+commits fit into the branch workflow. The full pipeline, stage by stage, is in
+[CI_FLOW.md](CI_FLOW.md).
+
+## Workflow Context
+
+- The model is work branch → `dev` → `main`. Both `dev` and `main` are long-lived.
+- Work happens on short-lived branches (`feat/*`, `fix/*`, `docs/*`, …) cut from `dev`.
+- Work PRs target `dev` and are squash-merged.
+- `main` only receives the automated `dev` → `main` promotion PR.
+- Every push to `main` creates a release (and the repo ships it), then
+  force-points `dev` at the release commit.
+
+## Commit Message Format
+
+Use Conventional Commits:
+
+```text
+<type>(<scope>): <description>
+```
+
+Examples:
+
+```bash
+feat(auth): add oauth login
+fix(uploads): reject invalid status changes
+docs(readme): update setup section
+ci(actions): add pr checks workflow
+```
+
+The rule is `managed/scripts/release/validate-conventional-subject.sh` in
+ebalzan/ci. Each Node repo's husky `commit-msg` hook runs it through the npm
+package (`ebalzan-ci commit-msg`), and the shared PR-title check runs it on
+every PR in CI — so repos without the hook are checked too, at PR time.
+
+## Allowed Types
+
+- `feat`: new feature
+- `fix`: bug fix
+- `docs`: documentation changes
+- `style`: formatting/style-only changes
+- `refact`: code restructuring without behavior change (there is no `refactor`)
+- `perf`: performance improvement
+- `test`: tests added/updated
+- `build`: build/tooling changes
+- `ci`: CI/CD changes
+- `chore`: maintenance tasks
+- `revert`: revert previous commit
+
+Branch prefixes are the same types (`refact/…`); there is no `feature/` or
+`hotfix/`.
+
+## Practical Rules
+
+1. Keep `type` and `scope` lowercase.
+2. Use imperative description (`add`, `fix`, `update`).
+3. Do not end description with a period.
+4. Prefer specific scope names: the module or area touched (`auth`,
+   `uploads`, `api`, `db`, `actions`, `deps`).
+5. Keep the header at 72 characters or fewer.
+
+## Typical Developer Flow
+
+```bash
+# 1) Branch from dev
+git switch dev
+git pull origin dev
+git switch -c feat/your-change
+
+# 2) Commit with conventional format
+git add .
+git commit -m "feat(search): add result filters"
+
+# 3) Push: the work-items workflow opens a PR into dev with a tracking issue
+git push -u origin feat/your-change
+```
+
+## Release Notes and Versioning
+
+Release notes and semantic versioning are automatic.
+
+- A push to `main` runs the repo's `release.yml`, which calls this repo's
+  reusable `release.yml`.
+- The bump is computed by scanning every Conventional Commit since the previous
+  tag. Branch names don't affect it, and if no commit is conventional the release
+  fails.
+- With a `package.json`, it updates it (and the lockfile) to the release
+  version and commits `chore(release): <version>`. The workflow skips commits
+  with that prefix, so the release commit doesn't trigger another release.
+  Without one, the release is the tag alone.
+- It creates tag `vX.Y.Z` and a GitHub Release; the repo then ships that tag.
+- It force-points `dev` at the release commit. If a later `git pull` on `dev`
+  conflicts, run `git reset --hard origin/dev` and branch from there.
+- `PR Checks` validates PR titles so squash merges always produce a conventional commit.
+
+Never bump the version, create a tag, or write a `chore(release):` commit by hand.
+
+Version impact by commit convention:
+
+- `feat` -> `minor`
+- `fix`, `perf`, `docs`, `style`, `refact`, `test`, `build`, `ci`, `chore`, `revert` -> `patch`
+- `BREAKING CHANGE` (or `!`) -> `major`
+
+## PR Titles and Squash Merges
+
+GitHub squash merge uses the PR title as the commit title.
+
+- keep PR titles in Conventional Commit format
+- make the PR title match the release impact implied by the branch type (`feat` -> `minor`; every other supported type -> `patch`)
+- if the change is breaking, mark the PR title with `!` to force a `major` release, for example `feat(api)!: remove legacy endpoint`
+- the `dev` → `main` promotion PR is titled automatically from the promoted commits; it only needs to stay a valid Conventional Commit
+
+## Troubleshooting
+
+### Invalid commit message
+
+Use the required format:
+
+```text
+type(scope): description
+```
+
+### Committed to wrong branch
+
+Prefer safe history-preserving fixes:
+
+- `git cherry-pick` to move commit
+- `git revert` to undo shared commits
+- Avoid `git reset --hard` on shared branches

package/docs/CONFIGURATION.md

@@ -0,0 +1,177 @@
+# Configuration reference
+
+Every knob, its default, and who reads it. For _where_ a value should live
+(variable or secret, repository or environment) read
+[GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md); for settings and rulesets,
+[REPO_RULES.md](REPO_RULES.md).
+
+- [The layers](#the-layers)
+- [Actions variables](#actions-variables)
+- [Secrets](#secrets)
+- [Workflow inputs](#workflow-inputs)
+- [Config files](#config-files)
+
+---
+
+## The layers
+
+```text
+                     SHARED (lower precedence)                  REPO (wins)
+Actions variables    config/actions.env                    +    .github/actions.env
+repository secrets   <shared secrets dir>/secrets.env      +    <repo secrets dir>/secrets.env
+environment secrets  <shared secrets dir>/secrets.<env>.env +   <repo secrets dir>/secrets.<env>.env
+repository settings  config/repo-settings.json             +    .github/repo-settings.json
+branch rulesets      config/rulesets/<file>.json           +    .github/rulesets/<file>.json
+```
+
+- **Variables** — the shared file is part of this package and is read **at run
+  time** by the actions, from the version the caller pins (`@v2`). Only the
+  repo's own keys are pushed to GitHub, by `ebalzan-ci bootstrap`.
+- **Secrets** — merged at sync time by `bootstrap`. The shared secrets dir is
+  `$CI_SECRETS_DIR`, else `config/` in a git checkout of this repo, else
+  `~/.config/ebalzan-ci/`. A repo's secrets dir is `repos/<owner>/<repo>/`
+  inside it when that folder exists (recommended), else the checkout's
+  `.github/`.
+- **Settings and rulesets** — JSON, deep-merged by `bootstrap`: objects merge
+  key by key, arrays are replaced whole. Top-level keys starting with `$` are
+  comments.
+
+A repo **inherits** a shared key by not mentioning it, **overrides** it by
+setting the same key, and **adds** any key of its own. An empty repo variable
+counts as unset, so it cannot blank out a shared value — override it with a
+real one.
+
+---
+
+## Actions variables
+
+All optional. Set them in a repo's `.github/actions.env` (then `ebalzan-ci
+bootstrap`), or for every repo in `config/actions.env` (then a release of this
+repo). The workflows pass the caller's variables whole
+(`REPO_VARS_JSON: ${{ toJSON(vars) }}`), so a new key needs no workflow edit;
+only `AUTO_*` keys are read.
+
+### Project board
+
+| Variable                       | Default          | Read by             | Meaning                                                                                                                               |
+| ------------------------------ | ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `AUTO_PROJECT_NUMBER`          | unset → no board | work items, promote | Projects (v2) board number (the `N` in `/users/me/projects/N`). One board per repo is typical.                                        |
+| `AUTO_PROJECT_OWNER`           | the repo owner   | work items, promote | Account or organization owning the board.                                                                                             |
+| `AUTO_STRICT_METADATA`         | `true`           | work items          | With a board configured: fail the run when the board, a field or an option is missing. `false` only warns. No effect without a board. |
+| `AUTO_START_DATE_OFFSET_DAYS`  | `0`              | work items          | `Start date` = today + N days.                                                                                                        |
+| `AUTO_TARGET_DATE_OFFSET_DAYS` | `7`              | work items          | `Target date` = today + N days.                                                                                                       |
+
+The board needs the fields `Start date`, `Target date`, `Priority`
+(single-select with options `P0`…`P4`), `Estimate` and `Size` (looked up by
+name, case-insensitive). See [AUTO_WORK_ITEMS_WORKFLOW.md](AUTO_WORK_ITEMS_WORKFLOW.md#project-v2-behavior).
+
+### Priority, size, estimate
+
+| Variable                 | Default (shared file)                                                                               | Meaning                                                                 |
+| ------------------------ | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `AUTO_PRIORITY_MAP_JSON` | unset → per type: `fix perf revert` P1, `feat refact` P2, `docs test build ci` P3, `style chore` P4 | `{"<type>": "P<n>"}` override per branch type.                          |
+| `AUTO_DEFAULT_PRIORITY`  | unset                                                                                               | Priority for types the map does not list (before the per-type default). |
+| `AUTO_SIZE_MAP_JSON`     | `feat refact perf` M, the rest S                                                                    | `{"<type>": "<size option>"}`.                                          |
+| `AUTO_DEFAULT_SIZE`      | `M`                                                                                                 | Size for types the map does not list.                                   |
+| `AUTO_ESTIMATE_MAP_JSON` | `feat` 3, `fix refact perf` 2, the rest 1                                                           | `{"<type>": "<number>"}`.                                               |
+| `AUTO_DEFAULT_ESTIMATE`  | `1`                                                                                                 | Estimate for types the map does not list.                               |
+
+### Labels and milestone
+
+| Variable                | Default | Meaning                                                                                                |
+| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `AUTO_ISSUE_LABELS`     | unset   | Extra labels for every tracking issue (comma-separated). Type labels are reserved and filtered out.    |
+| `AUTO_PR_LABELS`        | unset   | Extra labels for every work PR.                                                                        |
+| `AUTO_MILESTONE_TITLE`  | unset   | Milestone (exact title, case-insensitive) put on work issues/PRs and the promotion PR.                 |
+| `AUTO_MILESTONE_NUMBER` | unset   | Milestone by number; takes precedence over the title for work items (the promotion PR uses the title). |
+
+### Descriptions
+
+| Variable               | Default             | Meaning                                                                            |
+| ---------------------- | ------------------- | ---------------------------------------------------------------------------------- |
+| `AUTO_DESCRIBE_MODEL`  | `claude-sonnet-5-5` | Claude model that writes issue/PR descriptions from the branch's commits and diff. |
+| `AUTO_DESCRIBE_EFFORT` | `low`               | `low` · `medium` · `high` · `xhigh` · `max`. Ignored for Haiku models.             |
+
+Needs the `ANTHROPIC_API_KEY` secret; without it the body is a fixed template.
+
+### This repo only
+
+| Variable      | Default | Meaning                                                                                                              |
+| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `NPM_PUBLISH` | `false` | `true` makes `self-release.yml` publish every release to npm ([CONTRIBUTING](../CONTRIBUTING.md#publishing-to-npm)). |
+
+---
+
+## Secrets
+
+| Secret              | Needed by           | Required?   | What                                                                                                                                                                                                                                       |
+| ------------------- | ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GH_PROJECT_TOKEN`  | work items, promote | recommended | **Classic** PAT, scopes `repo` + `project`. Lets the bots write to Projects (v2) boards and makes the PRs they open trigger PR Checks. Falls back to `GITHUB_TOKEN` (no board writes; bot PRs do not start checks until you push to them). |
+| `ANTHROPIC_API_KEY` | work items          | optional    | Writes the issue/PR descriptions. <https://console.anthropic.com/settings/keys>                                                                                                                                                            |
+
+`GITHUB_TOKEN` is provided by Actions; never set it. Secrets are passed by name
+in the caller (`secrets: inherit` is only guaranteed within one organization).
+
+Why a classic PAT: a fine-grained token only has a Projects permission under
+_organization_ permissions, so it cannot reach a board owned by a personal
+account. The cost is that `repo` cannot be narrowed to selected repos — keep
+the expiry short. Details: [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md#fill-in-the-secrets).
+
+---
+
+## Workflow inputs
+
+Set in the caller's `with:`. Everything else is a variable, so callers stay
+four lines long.
+
+| Workflow              | Input         | Default         | Meaning                                                                                |
+| --------------------- | ------------- | --------------- | -------------------------------------------------------------------------------------- |
+| all four              | `runs-on`     | `ubuntu-latest` | Runner label (e.g. `self-hosted`).                                                     |
+| `auto-work-items.yml` | `base-branch` | `dev`           | Branch the work PRs target.                                                            |
+| `release.yml`         | `sync-dev`    | `true`          | Point `dev` at the release commit afterwards. Keep it on unless the repo has no `dev`. |
+
+`release.yml` outputs `tag` (`vX.Y.Z`, empty when nothing was released) and
+`sha` (the release commit).
+
+---
+
+## Config files
+
+### In each repo (`.github/`)
+
+| File                   | Committed?          | Contents                                                                                                                                                 |
+| ---------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions.env`          | yes                 | The repo's own variables (dotenv).                                                                                                                       |
+| `secrets.env`          | **no** (gitignored) | The repo's own repository secrets, when they are not in `repos/<owner>/<repo>/` of the shared secrets dir. `secrets.env.example` beside it is committed. |
+| `secrets.<env>.env`    | **no**              | Secrets for GitHub environment `<env>`, created by bootstrap. Same fallback rule.                                                                        |
+| `bootstrap.conf`       | yes                 | `LOCAL_ONLY_KEYS=A B C` — secret keys only local tools read; never pushed.                                                                               |
+| `repo-settings.json`   | yes                 | Overrides of `config/repo-settings.json`.                                                                                                                |
+| `rulesets/<file>.json` | yes                 | Overrides of the shared ruleset with the same file name, or extra rulesets.                                                                              |
+
+### In this repo (`config/`)
+
+| File                           | Published to npm?                      | Contents                                                                                    |
+| ------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `actions.env`                  | yes                                    | Shared variables (above).                                                                   |
+| `repo-settings.json`           | yes                                    | Shared repository settings.                                                                 |
+| `rulesets/*.json`              | yes                                    | Shared branch rulesets.                                                                     |
+| `repos.env`                    | yes                                    | `REPOS_TOPIC`, `REPOS_OWNER`, `REPOS` — what `--all` selects; `CI_REPO` — this repo's slug. |
+| `secrets.env.example`          | yes                                    | Template for the shared secrets.                                                            |
+| `secrets.env`, `secrets.*.env` | **never** (gitignored, not in `files`) | Shared secrets, when you run the tools from a checkout.                                     |
+
+`repos.env` keys:
+
+| Key           | Default      | Meaning                                                                                 |
+| ------------- | ------------ | --------------------------------------------------------------------------------------- |
+| `REPOS_TOPIC` | `ebalzan-ci` | `--all` includes every repo of `REPOS_OWNER` with this topic. Empty disables discovery. |
+| `REPOS_OWNER` | the gh user  | Account searched for the topic.                                                         |
+| `REPOS`       | empty        | Extra `OWNER/REPO` slugs (space-separated), e.g. repos of an organization.              |
+| `CI_REPO`     | `ebalzan/ci` | The slug the callers `uses:`. Change it only in a fork.                                 |
+
+### dotenv format
+
+`KEY=VALUE` per line; `#` comments and blank lines are ignored; one pair of
+surrounding quotes is stripped. No interpolation, no `export`. A secret whose
+key ends in `_FILE` is set from that file's contents under the stripped name
+(for multi-line values such as SSH keys); a relative path is relative to the
+env file.