Operational runbook index — capture what a session cost you to discover

The discovery entry point for "how do I configure / operate / debug X on iterion". Each entry names when to read it, which is its whole value: an agent that does not know the runbook exists cannot look it up. The detail lives in the target doc, never here.

Routed from the tree. Extend the index in the same change that adds the runbook.

Operational-knowledge reflex

When a session burns real time discovering how to configure or operate iterion, that discovery MUST land back in the repo, across three surfaces by role: the runbook's content in docs/, its "read it when" line in the index below (same change), and — only if an agent would never find it otherwise — a discovery trigger skill. The root, AGENTS.md, takes at most one line. Ground every addition in the commands/paths that actually worked.

Credentials & spend

• cloud-llm-credentials — provisioning a cloud run's LLM credential: BYOK vs OAuth-forfaits, org/platform tiers, --keys-first/--facade-default, connecting a Claude forfait, "which key paid for a run", credentials preview. Read on 401/429 on cloud runs.
• usage-caps — capping a subscription below the provider's wall; runtime-mutable caps; a reading is trusted 3 h, not until its reset instant, and usage-readings clear cuts it. Read when bots eat the operator's forfait or runs are refused at admission; shared walk semantics distinguish a node's own end from a cap wall.
• credential-pool — mutualising contributors' unused quota: the pledge, the audience policy, why max_cost_usd enforces.
• web-search — sovereign search tiers and the ITERION_WEB_SEARCH resolver.
• models — the model registry, launch-time overrides, the studio assistant's model.
• current-bot-models — catalog defaults, CLI pins, live rollout of bot model vars.

Merge, CI & gate

• gitops-warden-rollout — binding the gitops merge gate to a repository, authoring the per-repo policy, the dry-run calibration criteria, flipping to enforce and the emergency disarm. Read when binding gitops-warden, before flipping any repo to enforce, or when a warden verdict looks wrong.

• merge-policy — the queue, required checks, admin bypass; on "nobody can merge", first try the CI_SELF_HOSTED=off repo variable. See also measuring the queue (task ci:queue-stats) and releases and the queue.

• merge-gate — the required check's full life; read when a gate looks stuck or a repair posts nothing.

• revi-rollout — binding Revi to GitHub with an App, proving permissions, reviewer requests and delivery → run → review → gate; read before the first same-repo test PR or enabling a required check.

• revi-billy-loop — the Revi → Billy loop, paused on this repo (why); read before a deliberate pass or a re-arm.

• auto-maintenance — dependency loops nobody watches; read before arming arm_automerge, or when a loop "is configured" and merges nothing.

• Revi's positive/negative audit — when a clean review looks suspicious.

Cloud ops

• cloud-deployment — how a build reaches a deployment: prod pins the server, the runner and the sandbox: auto image BY DIGEST in the GitOps values, so deploying = resolve the release digest and commit it (:edge is dev-only; image.requireDigest refuses a tag at render; the DB setting sandbox.default_image sits outside that guard and only warns); verify by Deployment generation, never pods.
• cloud-backup — the Mongo dump and the off-cluster artifact copy (backup.*: rclone tiers, the check that proves a copy, the alerts, deletions kept under current-deleted/), the recovery objectives (RPO 24 h / RTO 8 h), the JetStream reseed, the restore drill and its log. Read before enabling the copy, on a backup alert, or before any restore.
• cloud-deployment § spreading the replicas — the scheduling.* knobs, the honest PDB rule (never on a single replica), and task chart:gate to judge ANY rendered manifest — the GitOps repository's too — for an anti-affinity, spread or budget selector that names no pod. Read before touching affinity or PDB values anywhere.
• probes-and-graceful-shutdown — /healthz//readyz promises, the lame-duck window, why only Mongo gates readiness. Read on 502s during a deploy or a CrashLoop at boot.
• platform-bots — iterating a bot on cloud without an image rollout; the engine contract requires:; read on "version drift" or a refused push.
• bot-bundle-snapshots — cloud bundle/subbot resolution; read before changing it.
• outcome-router — the terminal-run routing contract; read before flipping ITERION_OUTCOME_ROUTER.
• url-layout — which paths answer at the origin root vs /studio; read when a link lands somewhere unexpected.
• observability — logs, error tracking, tracing: what a Sentry/GlitchTip project receives, the smoke tests.
• sentry-feedback-loop — reading prod errors back from Sentry; triaging a crash, wiring an agent to live errors.

Security & tenancy

• browser-security — the studio's browser-side protections; the gouv.fr public-suffix fact behind the origin gate; refusals log at info, not warn. Read before touching auth cookies, origins or headers.
• forge-security-read — org-wide Dependabot read for a bot; the coverage trap and the watch-only App. Read when wiring vuln-watch or on "no Dependabot token".
• ticket-context — tracker tickets in a review, plus org/team governance: provisioning approval, team lifecycle, "an account signs in and sees nothing", moving a repo between teams.

Board & dispatch

• board-epics — epics on the GitHub board: which view answers what, membership carried twice; re-sending options without their id silently clears them.
• github-board-sync — GitHub Projects v2 ↔ native board; on a card moved on one side only: unmapped state, terminal card, or issue sync that never ran.
• dispatcher — the claim lease + watchdog (ADR-096), and the lossy-inotify index fallback. Read on a stuck in_progress card or a card the board never shows.

Local runtime & discovery

• repo-map-and-graph — "where is… / what breaks if…" before grepping; the committed maps and iterion map.

• state-of-the-art — how proven each surface is.

• worktree-pool — where a long-lived store's disk goes (worktree: auto parks a full checkout per run, 355 MB each here); read on "the disk is full" or before pointing --store-dir.

• resume — final-bank retries and recovery evidence.

• connector-identities — connector regeneration identity locks and recovery after an interrupted replacement.

• mcp-server — driving iterion from an MCP client; --read-only, the remote_api escape hatch.

• assistant-dock — which bot answers the studio assistant where (Nexie owns /whats-next, Copi the dock).

• brand — the mascot assets and which forge identity gets the avatar how.

• groups-iteration-subbots — child skills/devbox missing or leaking into a parent.

• Admission maintenance and local contracts — durable event/slot intentions, per-schedule fenced persistence, atomic one-shot receipts, and admission before predecessor cancellation; preserve resumes and inspect binary contracts offline.