[freeqaz]

Problem

Four console pages sat at the 2,500-word docs cap (scripts/docs-site/word-count.mjs), so console fixes had to trim reference and flow text to fit: reference/console.md (2478), reference/console/create-and-deploy.md (2491), flows/platform-console.md (2497) and flows/platform-console/agent-editing.md (2491).

Change

Mechanical splits along existing seams. Moved text is verbatim apart from relative link paths, and existing heading anchors stay on the original pages.

• reference/console.md: "Inspect detail, versions, and channel drafts" moves to reference/console/versions-and-channel-drafts.md. The heading and its inspect-detail-revisions-and-channel-drafts alias stay, with a pointer.
• reference/console/create-and-deploy.md: repository discovery, access levels, policy checks and repository recovery, plus "Use repositories and Slack on the same Agent", move to reference/console/repository-access.md. The general creation-recovery paragraphs stay, and so does the Slack heading, with a pointer.
• flows/platform-console.md: the Create Agent form trace from step 3 (plugin fields and discovery, model choices, starter template, repository options, provisioning, ordinary drafts, Secret grants, harness authentication) moves to flows/platform-console/agent-creation.md.
• flows/platform-console/agent-editing.md: steps 7 and 8 (stop, deletion), their diagram edges and their debugging bullets move to flows/platform-console/agent-stop-and-deletion.md. The step headings and their span IDs stay, with links.
• The new pages are registered in docs.json (hidden, next to their siblings) and contributing/runtime-flows.md. Direct links in the guides, the Slack integration page, repository credentials and the Storybook workflows now point at the new pages.
• Text trimmed on 10-19 that is still accurate is restored: the build commit is baked into the console HTML; Create Agent step 3's model Secret choice (scoped to the methods that show the picker) and "Other settings remain"; the Backends empty-list wording.
• One correction in moved text: the plugin discovery trace now names agents/plugin-discovery.mjs:createPluginDiscovery (loadCatalog, loadTools). The old create.mjs:loadPluginCatalog does not exist.

Word counts after: console 1566, versions-and-channel-drafts 977, create-and-deploy 2095, repository-access 496, platform-console 2109, agent-creation 673, agent-editing 2033, agent-stop-and-deletion 648.

Verification

• node scripts/docs-site/word-count.mjs: ok.
• node scripts/docs-site/build.mjs --check: validated 269 pages and 4253 links.
• node scripts/check-specs.mjs: ok.
• prettier --check on the touched Markdown; git diff --check clean.
• Removed lines were compared with the new pages: every one is present verbatim, ignoring link targets. The only exceptions are the intended restorations above.
• An internal review found no blockers. Its follow-ups are applied: the recovery paragraph stays in create-and-deploy, the module name is corrected, and the step and anchor wording is clarified.
• Docs only: no tests added.

Risks

Open PRs that edit moved paragraphs will conflict and need the same edit applied in the new page. #2833 touches the "Ordinary drafts" paragraph, which now lives in flows/platform-console/agent-creation.md. #2999, #2268 and #1605 add no new conflicted file beyond what they already have against main (git merge-tree).

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

This PR splits four console reference and flow pages into focused child pages and updates navigation and incoming links.

Example: A reader opens the console reference at #inspect-detail-revisions-and-channel-drafts.

• Before: The section contains the full Agent detail and channel reference.
• After: The same anchor resolves to a pointer to console/versions-and-channel-drafts.md.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Useful, focused documentation maintenance with no actionable findings; reported documentation checks were not independently rerun under the read-only review boundary.
Proof confidence	🌊 off-meta tidepool	Not applicable: Documentation-only changes are exempt from runtime proof; the author reports documentation validation, while this review inspected source, links, anchors, and history without running builds or tests.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Console documentation repeatedly approaches the hard word limit, forcing unrelated feature work to trim useful guidance.
Reason: The collaborator-authored direction follows repository documentation policy and an existing split pattern while keeping the material discoverable.

Merge readiness

✅ Ready for maintainer review

Keep this PR open: the documentation split provides useful room for console changes, preserves existing section links, and introduces no actionable defect found in review.

Priority: P3
Reviewed head: 6250046311804540a20e9a92d5cf8c76153a1a78

Before merge

None.

Findings

None.

Agent review details

How this fits together

Markdown reference and flow pages enter the documentation renderer through docs.json; readers receive linked console guidance and source execution traces.

flowchart TD
  A[Console documentation] --> B[Reference child pages]
  A --> C[Runtime flow child pages]
  B --> D[Documentation navigation]
  C --> D
  D --> E[Reader]

Loading

Technical review

Best possible solution:

Land the focused documentation split with preserved section URLs and one owning page for each moved topic.

Do we have a high-confidence way to reproduce the issue?

This is documentation maintenance; the pinned base pages and prior word-cap trims establish the stated maintenance problem without a runtime reproduction.

Is this the best way to solve the issue?

The splits follow existing topic boundaries, preserve consequential guidance and old anchors, and update navigation; the remaining longer pages each retain a coherent reference or execution trace.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 52c1a20a792d.

Provenance checked

• Console reference organization and section URLs keeps the original intent (69097a7: The terminology update distinguished deployment versions from AgentRevision resources and preserved historical heading links.)
• Word-cap maintenance changes intended behavior with a stated reason (245d170: Earlier prose trimming kept the platform console flow below the hard word limit; this PR explains replacing repeated trimming with focused child pages.)
• Stop and deletion execution guidance keeps the original intent (48ec47c: Deletion guidance documents confirmation, exact authorization, asynchronous cleanup, and uncertain-outcome recovery; the extracted page preserves those boundaries.)

Security

None.

Evidence

What I checked:

• Pinned introduced change: The introduced diff changes only documentation and navigation; the extracted sections retain their permission, uncertainty, credential, and recovery guidance. (625004631180)
• Existing reference URL retained: The historical revisions alias and current versions heading remain beside the link to the extracted reference. (docs/reference/console.md:96, 625004631180)
• Stop and deletion anchors retained: The original stop anchor, deletion aliases, and numbered headings remain with links to the new trace. (docs/flows/platform-console/agent-editing.md:272, 625004631180)
• Navigation registration: The new reference pages are registered beside their existing siblings; the flow pages are also registered and linked from the runtime-flow index. (docs/docs.json:246, 625004631180)
• Restored source claims: The build metadata script embeds the checked-out source commit in console HTML; create.mjs controls the model Secret picker, and plugin-discovery.mjs owns loadCatalog and loadTools. (scripts/build-console-metadata.mjs:3, 625004631180)
• Established documentation pressure: Earlier merged work trimmed the platform flow specifically to restore compliance with the word cap; docs(console): split agent detail tabs and storybook agent workflows into own pages #3005 established the adjacent split-and-preserve-anchors pattern. (docs/flows/platform-console.md, 245d17083cad)

Labels

Label changes:

• add P3: Documentation organization reduces repeated word-cap maintenance without changing runtime behavior.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: Documentation organization reduces repeated word-cap maintenance without changing runtime behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 20, 2026, 1:47 AM ET / 05:47 UTC.