docs: add RESTORE.md disaster-recovery runbook

[yihanzhu]

Closes #1

What changed

• Add top-level RESTORE.md — a disaster-recovery runbook that walks a human through rebuilding the whole team from this repo, ordered top to bottom: prerequisites → recreate Faber (manager) → recreate the three routines (with triggers) → recreate the Codex reviewer (read-only/comments-only) → labels + branch protection + CI per target repo → smoke test → safety rails → troubleshooting/gotchas.
• Update README.md Layout section to list RESTORE.md.

Why

Goal #2 in CLAUDE.md is full backup — everything needed to reconstruct the team if the live setup is lost. That promise was implicit; this makes it an explicit, followable runbook so no one has to reverse-engineer the wiring from scattered files.

How verified

• Docs only — no scripts, no prompt/routine edits (out of scope per the issue).
• No dangling links — verified every path referenced by RESTORE.md exists (manager/CLAUDE.md, routines/*.md, reviewer/codex-review.md, templates/repo-setup.md, .github/workflows/ci.yml, CLAUDE.md, README.md).
• References, not duplicates — links the gh label create loop / branch-protection / CI steps in templates/repo-setup.md and ci.yml instead of copying them.
• CI scope — no new *.sh files (shellcheck scope unchanged); structure-check required files all present; RESTORE.md contains no executed shell snippets.
• Personal values kept parameterized (<owner>/<repo>) per the reusability rule.

Note: this is a docs-only change — no live routine/prompt behavior changes.

[yihanzhu]

Reviewer (Codex-role) review — PR #4 docs: add RESTORE.md

Solid runbook. I verified every referenced path exists, every trigger matches the actual routines/*.md headers, all 8 acceptance criteria in #1 are met, parameterization is clean (<owner>/<repo>, no hardcoded personal values), and scope is docs-only / one concern. The accuracy is genuinely good — no dangling links, no wrong triggers, no mis-ordered core steps. A few real gaps and nits below.

Blocking

• None.

Suggestion

1. claude.yml workflow + its secret are invisible to a from-scratch restorer. .github/workflows/ contains two workflows — ci.yml and claude.yml (the anthropics/claude-code-action@v1 @claude-mention bot, which requires a CLAUDE_CODE_OAUTH_TOKEN repo secret). RESTORE §4 only ever names ci.yml and says restore is just "having this repo's .github/workflows/ present on main." Re-checking out the dir does restore the file, but the CLAUDE_CODE_OAUTH_TOKEN secret is exactly the kind of thing lost in a disaster — it lives only in GitHub repo settings, not in any file here. A restorer following this runbook ends up with a silently-broken @claude bot and no clue why. Given the PR's stated premise ("no one has to reverse-engineer the wiring from scattered files"), either (a) add a line in §4 noting claude.yml needs the CLAUDE_CODE_OAUTH_TOKEN secret re-created, or (b) explicitly scope it out ("the @claude action workflow is separate from the team loop and out of scope here"). Right now it's neither — it's just unmentioned.

2. Smoke-test step order implies Codex review precedes CI. §5 lists "Confirm Codex posts review comments" (step 4) before "Confirm CI runs and goes green" (step 6). Per the README loop, CI fires on PR-open in parallel with the review — they're not sequential. Minor, but a literal-minded restorer waiting for Codex before checking CI could misdiagnose a silent stage. Consider noting CI and the reviewer both trigger on PR open.

3. Branch-protection caveat missing. §4 says "reuse [templates/repo-setup.md], do not re-derive" for branch protection — but that section of repo-setup.md is a UI checkbox checklist with no command (unlike the labels loop), and branch protection isn't available on free private repos. The runbook never warns the restorer of this. A one-line note ("branch protection requires a paid plan or public repo; CI is still the hard gate without it") would save a confused restorer.

Nit

4. "your fork of this repo" (§4, last paragraph). Restoring Fabrica itself isn't a fork — it's the same repo. Suggest "your clone/copy of this repo" or just "this repo."
5. Coder-revision's fallback trigger isn't surfaced. routines/coder-revision.md notes a secondary issue_comment.created handler "if your trigger can't filter." The RESTORE trigger table lists only pull_request_review.submitted. Accurate to the primary, but the table says "set the trigger exactly as the file's header specifies" — and the file specifies a conditional second one. A pointer ("see the file for the fallback trigger") would close the gap.

Nothing here blocks merge — the runbook is followable and faithful to the repo. (1) is the one I'd most want addressed before calling the backup promise complete.

— Posted as comments only; no approve-to-merge, no merge, no code changes.

[yihanzhu]

Coder — round-1 (addressed review feedback)

Thanks for the thorough review. All five findings addressed; nothing pushed back on. Docs-only, scope unchanged, all referenced paths verified to exist, no shell scripts added (CI structure check + shellcheck stay green).

Suggestion 1 (claude.yml / CLAUDE_CODE_OAUTH_TOKEN) — most important. Scoped claude.yml out honestly in §4 as the optional, non-core @claude-mention helper that is not part of the team loop. Added the explicit caveat that if you do want it back it needs a CLAUDE_CODE_OAUTH_TOKEN repo secret, which lives only in GitHub repo settings (no file) and must be re-created by hand. This is your option (b), which matches our design (it's the optional mention helper).

Suggestion 2 (smoke-test ordering). Reworked §5 so CI and the Codex reviewer are shown firing in parallel on PR open (not sequential), with an explicit "don't wait for one before checking the other."

Suggestion 3 (branch-protection caveat). Added a one-liner in §4: branch protection is a UI-only checklist with no command and is unavailable on free private repos (needs a paid plan or public repo); if you can't enable it, CI is still the hard gate, you just lose server-side enforcement.

Nit 4 ("your fork"). Fixed to "your clone/copy of this repo (restoring Fabrica is the same repo, not a fork)."

Nit 5 (coder-revision fallback trigger). Surfaced the conditional issue_comment.created fallback in the §2 trigger table, pointing back to the file's header.

Label bumped round-0 → round-1. Not merging — leaving that to the human front gate.

[yihanzhu]

Reviewer (Codex-role) follow-up — round-1 verification

Re-checked all five prior findings against the actual files (not just the coder's summary). Every one is genuinely addressed and accurate. Verified item by item:

1. claude.yml / CLAUDE_CODE_OAUTH_TOKEN (the important one) — RESOLVED. §4 now has an explicit "Out of scope: claude.yml" sub-bullet that (a) names it as the optional @claude-mention helper (anthropics/claude-code-action@v1), (b) scopes it out of the team-loop restore, and (c) warns that re-enabling it needs a CLAUDE_CODE_OAUTH_TOKEN repo secret living only in GitHub settings, re-created by hand. Cross-checked .github/workflows/claude.yml: the action ref and the secrets.CLAUDE_CODE_OAUTH_TOKEN reference match exactly. This is clean option (b).

2. Smoke-test ordering — RESOLVED. §5 step 4 now shows "CI and the Codex reviewer both trigger in parallel on PR open (they are not sequential — don't wait for one before checking the other)" with the Codex/CI confirmations nested under it. Matches the README role table (Reviewer + CI both on "PR opened/updated"). No longer implies review precedes CI.

3. Branch-protection caveat — RESOLVED. §4 branch-protection bullet now states it's a UI-checkbox checklist with no command, unavailable on free private repos (needs a paid plan or public repo), and that CI remains the hard gate without it. Verified against templates/repo-setup.md §2 — accurate (it is indeed checkboxes, no gh command, unlike the labels loop).

4. "your fork" nit — RESOLVED. Now reads "your clone/copy of this repo (restoring Fabrica is the same repo, not a fork)."

5. coder-revision fallback trigger — RESOLVED. §2 trigger table now surfaces the conditional issue_comment.created fallback and points back to the file header. Verified against routines/coder-revision.md — it does specify that exact secondary handler "if your trigger can't filter."

Fresh adversarial pass on the new content

• All referenced paths still exist (ci.yml, claude.yml, all routines/*.md, templates/*, manager/CLAUDE.md, CLAUDE.md, README.md). No dangling links introduced.
• No executed shell snippets added — the only gh command is a link-reference to repo-setup.md, not inlined. CI structure-check + shellcheck stay green; structure check's required-file list is unaffected.
• Scope unchanged: diff is README.md (+1 index line) and RESTORE.md only. No scope creep.
• New caveats are factually consistent with the source files — no new inaccuracy.

Verdict

Prior findings are fully resolved, no new issues found. No remaining blocking comments — this is ready for the human merge gate.

— Posted as comments only; no approve-to-merge, no merge, no code changes.