Convert the runbooks to AsciiDoc, and fix all 116 inbound references

[stephane-segning]

Replaces #305 (auto-closed when its stacked base branch was deleted — see #306 for the full explanation).

Merge #306 first. This branch is built on top of it, so until #306 lands this PR's diff also shows the docs-pdf/docs-drift commits. It targets main directly, so merging it can never land in the wrong branch — but merging it before #306 would bring all three changes in at once.

Summary

The 12 runbooks move from Markdown to AsciiDoc, and every one of the 116 inbound references across 40 files is rewritten to match.

Intent

The conversion is the easy half. What pointed at the runbooks is the story: these are the most-referenced documents in the repo (deployment alone had 22 inbound references), and many references are not editorial:

• deploy/prometheus/alerts.yml annotations an on-call engineer clicks during a live incident — including five #fragment links
• deploy/charts/vsms/values.yaml, .env.example, Caddyfile, compose files
• Rust doc comments, and a string printed to an operator mid-restore in backup-tool/src/restore.rs

Verification

• cargo xtask docs-drift passes — the guard from Add cargo xtask docs-pdf and cargo xtask docs-drift #306, added specifically to police this change. All 116 references resolve.
• All 12 render under asciidoctor --failure-level=WARN with zero warnings
• Every fenced code block byte-identical to its Markdown original (operators copy-paste these)
• Prose word counts within 1.4%
• just lint and all five guards pass; docs-pdf still produces the 196-page book from the converted sources

Anchor IDs were the sharp edge. Asciidoctor's default idprefix turns ## SM001 into _sm001, silently breaking every fragment in alerts.yml — a failure discovered at 3am by a link that scrolls nowhere. Each file sets :idprefix:/:idseparator: -; verified by rendering alerting.adoc and diffing its real generated IDs against the fragments referenced repo-wide. All five present.

Scope

AGENTS.md and CLAUDE.md stay Markdown permanently — CLAUDE.md is a symlink to AGENTS.md, loaded as Markdown by tooling every session. (I broke that symlink once during development with a careless sed -i, which is how I know it matters; restored, and the final pass skips symlinks explicitly.)

Risk Assessment

Highest blast radius of this series. A missed reference means an operator following a dead link during an incident — which is why #306's guard exists and runs in just all-checks. Residual risk is a semantic break the guard cannot see: a fragment resolving to the wrong section. Checked by hand for the five alert fragments.

This is the most reasonable PR of the set to decline. #302 (already merged) and #306 deliver the tiny-Rust and single-PDF goals outright and don't depend on it. Runbooks are procedural docs, where asciidoc's advantages are smallest and the operational blast radius is largest.

AI Usage Declaration

• A human directed this change and is accountable for it.
• Verified against rendered output and a real link sweep, not assumed.

Reviewer Focus

Whether this should land at all. If yes: the anchor mapping in alerting.adoc, the one place a silent break has an on-call consequence.

---

Checklist

• docs/roadmap.md checked — no edit needed.
• No R1 exceptions touched.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 89c274d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[lightbridge-assistant]

🅵 Fast automated pass — SAST + a quick, diff-scoped look (no repo-wide retrieval). For a deeper, repo-aware review, mention @lightbridge-assistant on this PR.

Clean verdict, confirmed by direct investigation rather than memory. I opened the substantive files (docs_drift.rs, docs_pdf.rs, xtask main.rs, sms-fake-orange Dockerfile, sms-gateway/src/main.rs, sms-metrics/lib.rs, backup-tool/src/restore.rs) and reviewed every remaining hunk from its full diff content. The PR (a) migrates runbooks doc references .md→.adoc, with every target added in this same PR and .md originals still present, so all pointers resolve and the new docs-drift guard enforces this at CI; and (b) adds two well-tested xtask subcommands whose docker mounts, digest pin, link rewriter, and path-resolution logic all hold. The sole SAST flag (Dockerfile:81, missing USER) is on a line this diff does not touch and the runtime stage is non-root distroless. Zero provable defects on any changed line. NOT reviewed (exceeded prompt budget): docs/runbooks/{alerting,backup-restore,e2e-integration,getting-started,local-development,releasing-sdks}.adoc and justfile.

Notes on changed files

Findings on this PR's changes that couldn't be pinned to a diff line.

• 

  🔍 opengrep: By not specifying a USER, a program in the container may run as 'root'. This is a security hazard. If an attacker can c… — backends/apps/sms-fake-orange/Dockerfile:81

  By not specifying a USER, a program in the container may run as 'root'. This is a security hazard. If an attacker can control a process running as root, they may have control over the container. Ensure that the last USER in a Dockerfile is a USER other than 'root'.

  Detected by opengrep rule opt.opengrep-rules.dockerfile.security.missing-user-entrypoint — a deterministic static-analysis match. Verify before acting; suppress a false positive with an opengrep-ignore comment.

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).