diff --git a/.pan/continues/PAN-5504.xbrief.json b/.pan/continues/PAN-5504.xbrief.json new file mode 100644 index 00000000000..1e3495d509c --- /dev/null +++ b/.pan/continues/PAN-5504.xbrief.json @@ -0,0 +1,568 @@ +{ + "version": "1", + "issueId": "PAN-5504", + "created": "2026-11-19T07:15:41.251Z", + "updated": "2026-11-19T08:03:19.874Z", + "gitState": {}, + "decisions": [], + "hazards": [], + "resumePoint": null, + "sessionHistory": [ + { + "reason": "feedback", + "note": "[2026-11-19T08:03Z] coderabbit → FINDINGS — seq 1", + "timestamp": "2026-11-19T08:03:19.874Z" + } + ], + "items": { + "troubleshooting-a": { + "status": "completed", + "doneAt": "2026-11-19T07:15:41.251Z" + }, + "troubleshooting-a.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:15:41.251Z" + }, + "troubleshooting-a.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:15:41.251Z" + }, + "troubleshooting-a.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:15:41.251Z" + }, + "troubleshooting-a.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:15:41.251Z" + }, + "troubleshooting-b": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:15:47.304Z", + "doneAt": "2026-11-19T07:17:09.450Z" + }, + "troubleshooting-b.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:17:09.450Z" + }, + "troubleshooting-b.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:17:09.450Z" + }, + "troubleshooting-b.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:17:09.450Z" + }, + "troubleshooting-b.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:17:09.450Z" + }, + "troubleshooting-c": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:17:14.270Z", + "doneAt": "2026-11-19T07:18:23.098Z" + }, + "troubleshooting-c.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:18:23.098Z" + }, + "troubleshooting-c.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:18:23.098Z" + }, + "troubleshooting-c.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:18:23.098Z" + }, + "troubleshooting-c.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:18:23.098Z" + }, + "prompts-a": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:19:55.013Z", + "doneAt": "2026-11-19T07:21:38.327Z" + }, + "prompts-a.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:21:38.327Z" + }, + "prompts-a.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:21:38.327Z" + }, + "prompts-a.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:21:38.327Z" + }, + "prompts-a.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:21:38.327Z" + }, + "prompts-b": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:21:42.362Z", + "doneAt": "2026-11-19T07:23:01.547Z" + }, + "prompts-b.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:23:01.547Z" + }, + "prompts-b.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:23:01.547Z" + }, + "prompts-b.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:23:01.547Z" + }, + "prompts-b.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:23:01.547Z" + }, + "prompts-c": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:23:05.731Z", + "doneAt": "2026-11-19T07:24:32.343Z" + }, + "prompts-c.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:24:32.343Z" + }, + "prompts-c.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:24:32.343Z" + }, + "prompts-c.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:24:32.343Z" + }, + "prompts-c.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:24:32.343Z" + }, + "harness-landscape-a": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:24:36.415Z", + "doneAt": "2026-11-19T07:25:48.035Z" + }, + "harness-landscape-a.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:25:48.035Z" + }, + "harness-landscape-a.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:25:48.035Z" + }, + "harness-landscape-a.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:25:48.035Z" + }, + "harness-landscape-a.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:25:48.035Z" + }, + "harness-landscape-b": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:25:51.965Z", + "doneAt": "2026-11-19T07:27:40.672Z" + }, + "harness-landscape-b.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:27:40.672Z" + }, + "harness-landscape-b.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:27:40.672Z" + }, + "harness-landscape-b.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:27:40.672Z" + }, + "harness-landscape-b.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:27:40.672Z" + }, + "harness-landscape-c": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:27:45.554Z", + "doneAt": "2026-11-19T07:29:18.236Z" + }, + "harness-landscape-c.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:29:18.236Z" + }, + "harness-landscape-c.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:29:18.236Z" + }, + "harness-landscape-c.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:29:18.236Z" + }, + "harness-landscape-c.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:29:18.236Z" + }, + "audit-lanes": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:29:22.794Z", + "doneAt": "2026-11-19T07:30:33.738Z" + }, + "audit-lanes.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:30:33.738Z" + }, + "audit-lanes.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:30:33.738Z" + }, + "audit-lanes.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:30:33.738Z" + }, + "audit-lanes.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:30:33.738Z" + }, + "audit-workers": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:30:38.180Z", + "doneAt": "2026-11-19T07:31:44.572Z" + }, + "audit-workers.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:31:44.572Z" + }, + "audit-workers.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:31:44.572Z" + }, + "audit-workers.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:31:44.572Z" + }, + "audit-workers.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:31:44.572Z" + }, + "audit-architecture": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:31:49.105Z", + "doneAt": "2026-11-19T07:33:34.844Z" + }, + "audit-architecture.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:33:34.844Z" + }, + "audit-architecture.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:33:34.844Z" + }, + "audit-architecture.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:33:34.844Z" + }, + "audit-architecture.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:33:34.844Z" + }, + "audit-state-model": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:33:39.309Z", + "doneAt": "2026-11-19T07:34:28.946Z" + }, + "audit-state-model.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:34:28.946Z" + }, + "audit-state-model.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:34:28.946Z" + }, + "audit-state-model.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:34:28.946Z" + }, + "audit-state-model.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:34:28.946Z" + }, + "audit-god-view": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:34:33.402Z", + "doneAt": "2026-11-19T07:35:10.714Z" + }, + "audit-god-view.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:35:10.714Z" + }, + "audit-god-view.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:35:10.714Z" + }, + "audit-god-view.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:35:10.714Z" + }, + "audit-settings": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:35:15.227Z", + "doneAt": "2026-11-19T07:36:20.810Z" + }, + "audit-settings.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:36:20.810Z" + }, + "audit-settings.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:36:20.810Z" + }, + "audit-settings.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:36:20.810Z" + }, + "audit-settings.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:36:20.810Z" + }, + "audit-docker-setup": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:36:29.905Z", + "doneAt": "2026-11-19T07:37:50.798Z" + }, + "audit-docker-setup.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:37:50.798Z" + }, + "audit-docker-setup.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:37:50.798Z" + }, + "audit-docker-setup.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:37:50.798Z" + }, + "audit-docker-setup.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:37:50.798Z" + }, + "audit-legacy-codebases": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:37:55.420Z", + "doneAt": "2026-11-19T07:38:49.518Z" + }, + "audit-legacy-codebases.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:38:49.518Z" + }, + "audit-legacy-codebases.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:38:49.518Z" + }, + "audit-legacy-codebases.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:38:49.518Z" + }, + "audit-legacy-codebases.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:38:49.518Z" + }, + "audit-operating": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:38:56.168Z", + "doneAt": "2026-11-19T07:39:42.000Z" + }, + "audit-operating.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:39:42.000Z" + }, + "audit-operating.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:39:42.000Z" + }, + "audit-operating.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:39:42.000Z" + }, + "audit-operating.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:39:42.000Z" + }, + "audit-skill-pack-authoring": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:39:46.546Z", + "doneAt": "2026-11-19T07:40:47.910Z" + }, + "audit-skill-pack-authoring.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:40:47.910Z" + }, + "audit-skill-pack-authoring.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:40:47.910Z" + }, + "audit-skill-pack-authoring.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:40:47.910Z" + }, + "audit-skill-pack-authoring.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:40:47.910Z" + }, + "audit-stitch-integration": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:40:52.872Z", + "doneAt": "2026-11-19T07:41:46.321Z" + }, + "audit-stitch-integration.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:41:46.321Z" + }, + "audit-stitch-integration.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:41:46.321Z" + }, + "audit-stitch-integration.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:41:46.321Z" + }, + "audit-stitch-integration.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:41:46.321Z" + }, + "audit-posthog-agents": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:41:51.521Z", + "doneAt": "2026-11-19T07:42:45.174Z" + }, + "audit-posthog-agents.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:42:45.174Z" + }, + "audit-posthog-agents.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:42:45.174Z" + }, + "audit-posthog-agents.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:42:45.174Z" + }, + "audit-template-conversations": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:42:50.004Z", + "doneAt": "2026-11-19T07:44:34.055Z" + }, + "audit-template-conversations.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:44:34.055Z" + }, + "audit-template-conversations.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:44:34.055Z" + }, + "audit-template-conversations.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:44:34.055Z" + }, + "audit-template-conversations.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:44:34.055Z" + }, + "audit-agents-directory": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:44:38.405Z", + "doneAt": "2026-11-19T07:45:28.982Z" + }, + "audit-agents-directory.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:45:28.982Z" + }, + "audit-agents-directory.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:45:28.982Z" + }, + "audit-agents-directory.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:45:28.982Z" + }, + "audit-agents-directory.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:45:28.982Z" + }, + "audit-token-spend-report": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:45:33.240Z", + "doneAt": "2026-11-19T07:46:36.607Z" + }, + "audit-token-spend-report.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:46:36.607Z" + }, + "audit-token-spend-report.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:46:36.607Z" + }, + "audit-token-spend-report.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:46:36.607Z" + }, + "audit-token-spend-report.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:46:36.607Z" + }, + "validate-and-pr-body": { + "status": "completed", + "claimedBy": "agent-pan-5504", + "claimedAt": "2026-11-19T07:46:41.971Z", + "doneAt": "2026-11-19T07:48:59.577Z" + }, + "validate-and-pr-body.ac1": { + "status": "completed", + "doneAt": "2026-11-19T07:48:59.577Z" + }, + "validate-and-pr-body.ac2": { + "status": "completed", + "doneAt": "2026-11-19T07:48:59.577Z" + }, + "validate-and-pr-body.ac3": { + "status": "completed", + "doneAt": "2026-11-19T07:48:59.577Z" + }, + "validate-and-pr-body.ac4": { + "status": "completed", + "doneAt": "2026-11-19T07:48:59.577Z" + } + }, + "feedback": [ + { + "seq": 1, + "specialist": "coderabbit", + "outcome": "findings", + "timestamp": "2026-11-19T08:03:19Z", + "markdownBody": "# CodeRabbit findings for PAN-5504 (PR #5584)\n\nCodeRabbit posted 8 inline finding(s). CodeRabbit is advisory: nothing waits for these,\nbut each one gets an answer, either a fix or a reply with your reason.\n\n- Thread 4625882776 · guides/legacy-codebases.mdx:130 [Minor]: Include the required memory fact id.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882776\n- Thread 4625882789 · guides/operating.mdx:75 [Minor]: Documented backup ordering does not hold for legacy skill removal.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882789\n- Thread 4625882799 · reference/prompts.mdx:161 [Minor]: Limit the `PromptError` guarantee to validated failures.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882799\n- Thread 4625882807 · reference/prompts.mdx:646 [Minor]: Declare the variable before passing it from the caller.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882807\n- Thread 4625882818 · reference/state-model.mdx:69 [Minor]: Add conversation triage state to the database-only exceptions.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882818\n- Thread 4625882826 · reference/state-model.mdx:97 [Major]: The state reference claims a rebuild that the command does not perform.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882826\n- Thread 4625882869 · reference/template-conversations.mdx:286 [Minor]: Scope the \"not sandboxed\" statement to Overdeck's container isolation.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882869\n- Thread 4625882886 · reference/workers.mdx:69 [Minor]: Limit the `--cwd` restriction to remote placement.\n https://github.com/eltmon/overdeck/pull/5584#discussion_r4625882886\n\n## What to do\n\n1. Read each thread (open its link, or the code at the path and line).\n2. If you agree with a finding, fix it.\n3. If you reject a finding, reply on its thread with your reason:\n `gh api repos/eltmon/overdeck/pulls/5584/comments//replies -f body=\"\"`\n4. If you changed code: run the quality gates on what you touched, commit, push, then run `pan review request PAN-5504 -m \"CodeRabbit : \"`.\n If you only replied, you are done.\n5. If PR #5584 has already merged when you read this, stop: after the merge Overdeck files a follow-up issue\n for every thread with no reply, no later commit to its file, and no re-review request naming its thread id." + } + ] +} diff --git a/.pan/drafts/PAN-5504.md b/.pan/drafts/PAN-5504.md new file mode 100644 index 00000000000..cba3e4a8d8d --- /dev/null +++ b/.pan/drafts/PAN-5504.md @@ -0,0 +1,3138 @@ +# PAN-5504: accuracy audit of the Guides and Reference docs groups + +**Issue:** https://github.com/eltmon/overdeck/issues/5504 (part of epic #5467, docs overhaul) +**Priority:** P1. Docs-only change. No code changes, no `changelog.d` entry. +**Base:** `main` at `574a6be2c29` (v0.89.1 plus later merges), 2026-11-19. Both prerequisite PRs named in the issue +have merged, and their commits are in the history of the page they edited: PAN-5472 (#5535, `94f8a78502d`) on +`reference/god-view.mdx`, and PAN-5482 (#5558, `0558b4ab739`) on `reference/template-conversations.mdx`. No open PR +touches `guides/*.mdx` or `reference/*.mdx` (checked with `gh pr list --state open --json files`). So this audit works +on top of both. + +## Summary + +The issue asks for a line-by-line accuracy audit of every published page in the **Guides** and **Reference** navigation +groups. The planning session already did the audit. Eight research passes read all 18 pages (4,709 lines) against the +code on the base. The planner then checked the change tables by script: each grep anchor matches its page exactly once, +and each evidence quote written as `path:line "quote"` greps in its file (about 670 quotes; citations written as a +command and its result, or as a bare description, were not machine-checked). The planner re-ran the evidence by hand for +every section deletion and every "no match" claim that a row depends on: + +- the deleted stale-check re-trigger service (`src/dashboard/server/main.ts:300` "PAN-3917: the merge-blocker, + review-status, and stale-check reconcilers are gone"); +- the corrupted-workspace dashboard UI (`git grep -i 'Workspace Corrupted\|Clean & Recreate' -- src/dashboard/frontend/src` + prints nothing); +- no prompt cache (`git grep clearPromptCache -- src` prints nothing), eleven templates in `src/lib/cloister/prompts/` + including `uat-agent.md` and `work-deft.md`, and exactly four production `renderPrompt(` callers; +- the old Deacon loop in `src/lib/health.ts`, reached only from `pan show --health` (`src/cli/commands/show.ts:17-18`); +- `.planning/` survives only as a legacy check in `src/cli/commands/release.ts:441`; +- no "frozen after done" lane rule (`git grep -i frozen -- src/lib/lanes src/cli/commands/lane.ts` prints nothing); +- no code creates the `state-final` tag (`git grep state-final -- src scripts` prints nothing); +- `.claude/skills/` is in Overdeck's project gitignore entries (`src/lib/workspace-sync-paths.ts:18`); +- `pan restart` and `pan reload` treat auto-resume differently (`src/cli/commands/restart.ts:257`, `src/cli/commands/reload.ts:463`); +- the token report figures (76,462 calls, $15,552, data through 2026-07-06, "deliberately not imported") all appear in + `docs/token-spend-report/index.html`; +- the omp MCP claim (see Decision D10, which the planner narrowed after this check). This PRD lists every wrong, stale or removed +claim per page, with the exact current text, the replacement text and the code evidence (Appendices A to H). + +The implementation agent applies those changes, removes every en and em dash, fixes frontmatter, fixes the one broken +anchor, checks links, runs the Mintlify validators, and writes a PR body with one note per page. It does not need to +re-research. It re-checks a claim only when a grep anchor no longer matches. + +## Glossary + +- **Guides group**: the `"group": "Guides"` block in `docs.json` (line 175 on the base, under the `Guides` tab). It lists + five pages: `guides/operating`, `guides/legacy-codebases`, `guides/skill-pack-authoring`, `guides/stitch-integration`, + `guides/docker-setup`. +- **Reference group**: the `"group": "Reference"` block in `docs.json` (line 190, under the `Reference` tab). It lists + twelve pages: `reference/architecture`, `reference/settings`, `reference/god-view`, `reference/agents-directory`, + `reference/workers`, `reference/lanes`, `reference/state-model`, `reference/harness-landscape`, + `reference/posthog-agents`, `reference/prompts`, `reference/troubleshooting`, `reference/token-spend-report`. +- **Roadmap group**: the `"group": "Roadmap"` block in the same tab. It lists `vision` (audited by #5499, not here) and + `reference/template-conversations` (listed in this issue, so audited here). +- **Listed pages**: the 16 pages named in the issue body. **Added pages**: `guides/operating` (added by PAN-5482 on + 2026-11-18) and `reference/settings` (added by PAN-5477 on 2026-11-18). See Decision D1. +- **Claim**: any statement on a page a reader could act on: a command, subcommand or flag, a config key or default, a UI + label or location, a file path, a port, a behavior, a limit, a list of supported harnesses, trackers or platforms, or a + maturity label. +- **Primary source**: the code on the base (`git grep`), the Commander definitions under `src/cli/`, + `pan [sub] --help` (the installed `pan` is 0.89.1 and matches this tree), `src/lib/config-yaml/defaults.ts` and + `schema.ts`, the dashboard source under `src/dashboard/frontend/src/` and `src/dashboard/server/`, and `changelog.mdx`. + Other `.mdx` pages, `docs/*.md`, `README.md` and skills are never proof. One exception: when a page describes a + skill's own content (the Stitch skills, the `token-spend-report` dev skill), that skill file counts. +- **Grep anchor**: the quoted current text in each change table. Line numbers drift as earlier edits land, so find the + text with `grep -n -F '' `, not by line number. An anchor is the text inside the outer backticks of the + "Grep anchor" cell. Where a cell holds `\|`, the page has a plain `|`. Where a replacement holds `` \` ``, type a plain + backtick. +- **Dash rule**: no U+2013 (en dash) or U+2014 (em dash) anywhere in a touched page, frontmatter and body. Check: + `grep -nP '[\x{2013}\x{2014}]' ` prints nothing. Replace a dash with a comma, colon, period, parentheses, or the + word "to" for a range. A dash that stands alone in a table cell to mean "nothing here" becomes `none`. Arrows (`→`) and + box-drawing characters (`─`, `│`, `├`) are not dashes. A plain ASCII hyphen-minus `-` is not a dash. The change tables + do not list each dash; the executor removes them mechanically, except where a row gives specific wording. +- **Frontmatter rule**: `title` is specific and searchable. `description` is 50 to 160 characters, counting the text + between the quotes. Neither contains a dash. A value containing `: ` is double-quoted. When this PRD retitles a page it + also adds `sidebarTitle: ""`, unless the page already has one, so the navigation label stays short. +- **Experimental**: a dashboard view hidden unless Settings → Experimental → **Experimental features** is on. The gated + tab ids are in `EXPERIMENTAL_TAB_IDS` (`src/dashboard/frontend/src/lib/experimentalFeatures.ts:4`): `agents`, + `autopreso`, `resources`, `sessions`, `metrics`, `costs`, `health`, `god-view`. Wording at a page's first mention of such + a view: "(experimental: turn on Settings → Experimental → **Experimental features** to show it)". Later mentions on the + same page may say "(experimental)". +- **Follow-ups**: code bugs or out-of-scope doc problems found during the audit. They go in a `## Follow-ups` list in the + PR body. This issue changes no code. +- **PR note**: a one-line summary of what changed on a page, or "verified, no change". Each page's last item puts its note + in its commit message as a line `PR-note: .mdx: `. The validation item collects them into the PR body. +- **Help sentence**: "Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a + [GitHub Issue](https://github.com/eltmon/overdeck/issues)." + + +## Background and evidence + +- **Scope grew from 16 to 18 pages.** The issue lists 16 pages. Since it was filed, two pages joined these groups: + `guides/operating` (PAN-5482, #5558) and `reference/settings` (PAN-5477, #5570). No other audit issue covers them: + `gh issue view --json body | grep -E 'reference/settings|guides/operating'` prints nothing for #5499, #5500, #5501, + #5502 and #5503, and none of their PRDs audits either page. The issue's scope sentence is "every published page in the + Guides and Reference nav group". PAN-5501, PAN-5502 and PAN-5503 made the same call for their groups. Decision D1 + includes them. Both were written on 2026-11-18, so their tables are short. +- **Before-state per page** (dash lines counted with the dash-rule grep; description length without quotes): + +| Page | Lines | Dash lines | Title | Description chars | sidebarTitle | Change rows | +| --- | --- | --- | --- | --- | --- | --- | +| guides/operating | 88 | 0 | Operating Overdeck: stop, restart, recover and back up | 140 | Operating Overdeck | 9 | +| guides/legacy-codebases | 134 | 0 | Legacy Codebase Support | 52 | none | 8 | +| guides/skill-pack-authoring | 205 | 18 | Authoring a Skill Pack | 55 | none | 8 | +| guides/stitch-integration | 188 | 0 | Google Stitch Integration | 143 | none | 14 | +| guides/docker-setup | 352 | 0 | Docker & HTTPS Setup | 134 | none | 21 + V2 (row 22 replaced) | +| reference/architecture | 331 | 7 | Overdeck architecture | 143 | Architecture | 23 | +| reference/settings | 45 | 0 | Settings reference: every section of the Overdeck Settings page | 105 | Settings reference | 11 | +| reference/god-view | 91 | 0 | God View | 114 | none | 4 | +| reference/agents-directory | 151 | 8 | Agents page | 101 | none | 6 | +| reference/workers | 317 | 6 | Delegate to worker agents | 96 | Workers | 15 | +| reference/lanes | 383 | 6 | Gauntlet lanes | 82 | none | 16 | +| reference/state-model | 102 | 0 | State Model | 94 | none | 13 | +| reference/harness-landscape | 666 | 139 | Harness Landscape | 108 | none | 31 | +| reference/posthog-agents | 119 | 0 | PostHog for coding agents | 75 | none | 3 | +| reference/template-conversations | 312 | 36 | Template Conversations | 115 | none | 21 | +| reference/prompts | 631 | 42 | Prompt Templates | 152 | none | 47 | +| reference/troubleshooting | 629 | 14 | Troubleshooting Overdeck | 145 | Troubleshooting | 22 + V1 | +| reference/token-spend-report | 95 | 6 | Token Spend Report | 79 | none | 9 | + + Total: 4,839 lines, 282 dash lines, 282 change rows (plus the two planner rows V1 and V2 below). +- **Row verification.** The planner ran a script over every change table. Each grep anchor matches its page exactly once + (`grep -c -F '' ` is 1), and every `path:line "quote"` evidence citation greps in its file. Some anchors + contain an em dash copied from the page (prompts rows 4, 18, 28, 31; troubleshooting rows 4 and 9). That is why the + Common procedure applies rows before the dash pass. +- **Validators on the base.** `npx -y mint@4.3.49 broken-links --check-anchors` reports exactly one broken link, and it + is in this group: `guides/docker-setup.mdx` → `/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces`. + The target section exists as `## Slow Vite/React Frontend with Multiple Workspaces` (`reference/troubleshooting.mdx:214`). + Mintlify keeps the `/` in that slug (a research pass confirmed `#slow-vite/react-frontend-with-multiple-workspaces` + passes the local checker), but a slash in a URL fragment is fragile. Decision D9 renames the heading instead. +- **What breaks the validators** (`.overdeck/context/codebase/concerns.md`, the "`npx mint validate` and + `npx mint broken-links` pass on `main`" entry): a bare `` in prose outside backticks (MDX reads it as a JSX tag), + an unquoted frontmatter value containing `: `, an `import ... from "react"` line in a snippet, and relative links to + files that `.mintignore` excludes. `npm run lint:docs` (`scripts/lint-docs.js`) catches only `$` in prose and `<` before + a digit. Never run `mint validate --fix`: it rewrites files that sibling issues edit. +- **Tests that read these pages.** Two tests constrain the edits: + - `src/lib/__tests__/agent-text-cli-verbs.test.ts:55-57` lists `reference/template-conversations.mdx` in + `PROPOSAL_DOCS` because it "sketches `pan bundle` / `pan template` and says they do not exist yet". The page must keep + saying both verbs do not exist (`pan --help` lists neither on the base). Run this test after editing the page. + - `tests/unit/telemetry-docs.test.ts:120-122` requires `reference/posthog-agents` in `docs.json` and the file to exist. + The page is edited, never deleted or moved. +- **Inbound anchor links** to these pages from other files (`git grep -nE "/(guides|reference)/#"`): + - `/reference/lanes#lanes-on-other-machines`: `anywhere.mdx:206`, `configuration/linked-machines.mdx:291`, `:648`. + - `/reference/workers#externally-spawned-agents`: `configuration/harnesses.mdx:1105`, `reference/agents-directory.mdx:129`. + - `/reference/troubleshooting#wsl2-stability-issues-windows-users`: `guides/docker-setup.mdx:326`. + - `/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces`: `guides/docker-setup.mdx:345` (broken). + Those first three headings keep their text (NFR-2). `docs.json` redirects `/configuration/state-branch` to + `/reference/state-model`; the slug stays. +- **Help sections.** `guides/operating`, `reference/settings` and `reference/troubleshooting` already link the Discord and + GitHub Issues. Three pages have a troubleshooting section without them: `guides/docker-setup`, + `guides/stitch-integration` and `reference/prompts`. Their rows add the help sentence (D3). +- **No generator owns these pages.** `git grep` for each page path across `scripts/`, `src/`, `sync-sources/`, `.github/` + and `tests/` finds only skill pointers (`pan-skill-creator`, `pan-skill-installer`, `pan-lane` skills link the pages) and + the two tests above. The `token-spend-report` dev skill regenerates `docs/token-spend-report/index.html`, not the + `.mdx` page. So hand edits are safe and nothing regenerates them. + +## Requirements + +- **FR-1**: Every wrong, stale or removed claim listed in the work items and appendices is replaced with the listed text + or deleted as listed. Wording may be adjusted for flow; the fact may not. +- **FR-2**: For any claim on a page that this PRD does not list, the executor applies the residual rule (Common procedure + step 3). It verifies the claim against a primary source only if the claim looks doubtful. If the code disagrees, it + fixes the page to match the code. It never changes code. +- **FR-3**: Every page in scope satisfies the dash rule. +- **FR-4**: Every page in scope satisfies the frontmatter rule. The titles and descriptions named in the work items + change; each retitled page gets a `sidebarTitle` holding the old title (unless it already has one). +- **FR-5**: Every internal link on every page resolves to an existing page, and to an existing heading for an anchor, + counting `docs.json` redirects. `npx -y mint@4.3.49 broken-links --check-anchors` reports no broken link in a `guides/` + or `reference/` page, which includes fixing the docker-setup Vite anchor (D9). +- **FR-6**: `guides/docker-setup`, `guides/stitch-integration` and `reference/prompts` end their troubleshooting section + with the help sentence. `reference/troubleshooting` carries the help sentence under `### Resources`. + `guides/operating` and `reference/settings` keep both links. +- **FR-7**: Every place a page names an experimental view says it is experimental and names the switch (Glossary, + "Experimental"). The rows that do this are marked in the appendices' "Labels needed" lists: God View (`reference/god-view`, + `reference/architecture`), Metrics (`reference/architecture`, `reference/token-spend-report`), Costs + (`reference/token-spend-report`), AutoPreso (`reference/settings`), the Agents page (`reference/agents-directory`, + `reference/lanes`, `reference/workers`), Resources (`guides/operating`, `reference/troubleshooting`) and Health (`reference/troubleshooting`). + `reference/god-view` already carries the label in its opening ``. +- **FR-8**: Wrong screenshot alt text is rewritten. These `` blocks show UI the code no longer renders and + are deleted: the god-view and metrics images on `reference/architecture` (Appendix E, architecture rows 3 and 13), + `reference/troubleshooting` Health image (row 19, plus its now-unused import, row 20), and + `reference/token-spend-report` metrics image (row 5). Image files stay in `images/`. +- **FR-9**: The PR body ticks all 18 pages with a one-line note each. It pastes the clean output of the dash loop, + `npm run lint:docs`, `npx -y mint@4.3.49 validate` and `npx -y mint@4.3.49 broken-links --check-anchors`. It lists the + Follow-ups. +- **FR-10**: `reference/template-conversations.mdx` still states that `pan bundle` and `pan template` do not exist, and + `npx vitest run src/lib/__tests__/agent-text-cli-verbs.test.ts` passes. +- **NFR-1**: No file outside the 18 pages changes, except the PR body. No code, test, rule, image, `docs.json`, + `CLAUDE.md` or `changelog.d` change. Image files are not deleted even when a page stops using them. +- **NFR-2**: No heading text changes except where a row says so. The rows that change, delete or add a heading are: + troubleshooting V1 (Vite heading), 4 and 9 (dash in heading); docker-setup 6 (deletes `### Using mkcert` and + `### For Custom Domains`) and 11 (`### Via Dashboard` → `### With pan up`); stitch 8 (`## STATE.md Integration` → + `## Recording designs in the PRD draft`); template-conversations 5 (`## Why today's model is not enough` → + `## Why this was proposed`); harness-landscape 16 (the pi heading) and the dash pass over its `### —