Summary

Sweep through the published docs site fixing stale claims across roadmap, operator-facing pages, role-authoring pages, and contributor-facing internals pages. Every change was cross-checked against the live source tree. No code or schema changes.

The PR has two layers:

1. Roadmap re-bake (2026-05-18) of the Codebase Readability program, one day after the previous 2026-05-17 bake. Production Rust grew from ~93K → ~97K LOC, files > 1000 lines from 25 → 28, and runtime/launch.rs from 7593L → 7966L. Tier B in the Phase 2 split plan gains seven entries that crossed the 1000L line in the last day; Tier C shrinks from 10 to 5. The three Phase 2 split proposals (split-app-mod, split-input-editor, split-runtime-launch) get their file-size numbers refreshed.

2. Site-wide stale-claim sweep across the operator, role-author, and internals surfaces. Highlights:

   • Hard rule violation removed. reference/goals/jackin-desktop-agent-hub.mdx referenced "PR 283" three times (banned by docs/AGENTS.md "Never reference open pull requests in published documentation") and pointed at a non-existent src/daemon.rs. Both replaced with state-only framing.
   • Agent-runtime list drift. The code supports claude, codex, amp, kimi, opencode, but several pages still listed a subset. Fixed across architecture.mdx, getting-started/why.mdx, guides/comparison.mdx, guides/security-model.mdx, guides/role-repos.mdx, guides/authentication/github-cli.mdx. The OpenCode link in why.mdx now points at the canonical anomalyco/opencode fork (was the dead opencode-ai/opencode link).
   • Primary/secondary session vocabulary retired. container-session-lifecycle.mdx had already retired the distinction ("All agent sessions are equal — there is no 'primary' or 'secondary' distinction") but architecture.mdx and runtime-instance-model.mdx still used it. Reconciled.
   • Schema-version stamps. Example manifests in developing/creating-roles.mdx and guides/role-repos.mdx still used version = "v1alpha3"; one was internally inconsistent because it declared a [kimi] block that schema-versions explicitly requires v1alpha4 for. All four bumped.
   • CLI command-page corrections. Cross-checked against src/cli/*.rs:
     • commands/load.mdx: SELECTOR fallback says "last-used or default role", not "agent".
     • commands/role.mdx: add construct-version and published-image subcommands that exist in clap but weren't documented.
     • commands/purge.mdx and commands/eject.mdx: --all description reframed away from the non-existent "default instance" concept.
     • commands/workspace.mdx: add the --prune and --yes/-y flags to the workspace edit options table.
   • TUI design decisions. mount_isolation_choice.rs was listed in the flat button-strip exception list but does not exist in src/console/widgets/.
   • Installation page. jackin --version example output was the aspirational jackin 1.0.0; replaced with the actual jackin 0.6.0-dev from Cargo.toml.
   • Environment variables guide. Reserved-name list was missing JACKIN_GIT_COAUTHOR_TRAILER and JACKIN_GIT_DCO, both present in env_model.rs's RESERVED_RUNTIME_ENV_VARS.

Roadmap-overview reconciliation done in pass 1 (multi-runtime title, reproducibility-pinning status wording, selectable-sandbox-backends em dash) is unchanged.

What's deferred

Items surfaced during the audit but not fixed in this PR (each needs operator input or a code change rather than a docs edit):

• bollard-migration still claims Phase 1 is "the next concrete PR" but no bollard dependency has landed. Status wording may want softening.
• workspace-claude-token-setup lists a "canonical oauth_token auth slot" as remaining work. The current code uses an oauth_token symbol but as the bridge auth_forward = "oauth_token" mode, not a dedicated Claude config slot — left alone.
• CLI clap help-text drift. jackin config auth set --agent help only advertises claude/codex/amp (missing kimi/opencode); jackin workspace create/edit --default-agent help is missing kimi. The docs already document the full agent list, so this is a code-side fix (src/cli/config.rs, src/cli/workspace.rs), not a docs fix.
• Construct image default tag conflict. configuration.mdx documents JACKIN_CONSTRUCT_IMAGE default as projectjackin/construct:trixie; developing/construct-image.mdx and derived_image.rs consistently use projectjackin/construct:0.1-trixie. The CONSTRUCT_IMAGE constant in src/repo_contract.rs is projectjackin/construct:trixie. Left for the operator to disambiguate.

Verify locally

Checkout

Paste this first to bypass the tirith paste scanner for the rest of the session:

export TIRITH=0

Then paste the checkout block:

mkdir -p "$HOME/Projects/jackin-project/test"
cd "$HOME/Projects/jackin-project/test"

if [ ! -d jackin/.git ]; then
  git clone https://github.com/jackin-project/jackin.git
fi

cd jackin
mise trust
git fetch -f origin docs/roadmap-rebake-2026-05-18:refs/remotes/origin/docs/roadmap-rebake-2026-05-18
git checkout -B docs/roadmap-rebake-2026-05-18 refs/remotes/origin/docs/roadmap-rebake-2026-05-18

Run the docs site locally

cd docs
bun install --frozen-lockfile
bun run dev

Astro serves at http://localhost:4321/. Open each changed page directly:

Roadmap re-bake:

• Overview: http://localhost:4321/reference/roadmap/
• Codebase readability: http://localhost:4321/reference/roadmap/codebase-readability/
• Split: runtime/launch.rs: http://localhost:4321/reference/roadmap/split-runtime-launch/
• Split: app/mod.rs: http://localhost:4321/reference/roadmap/split-app-mod/
• Split: input/render editor: http://localhost:4321/reference/roadmap/split-input-editor/
• Selectable sandbox backends: http://localhost:4321/reference/roadmap/selectable-sandbox-backends/

Site-wide sweep:

• Installation: http://localhost:4321/getting-started/installation/
• Why jackin: http://localhost:4321/getting-started/why/
• Comparison: http://localhost:4321/guides/comparison/
• Environment variables: http://localhost:4321/guides/environment-variables/
• Role repos: http://localhost:4321/guides/role-repos/
• Security model: http://localhost:4321/guides/security-model/
• GitHub CLI auth: http://localhost:4321/guides/authentication/github-cli/
• Creating roles: http://localhost:4321/developing/creating-roles/
• Commands → load: http://localhost:4321/commands/load/
• Commands → role: http://localhost:4321/commands/role/
• Commands → eject: http://localhost:4321/commands/eject/
• Commands → purge: http://localhost:4321/commands/purge/
• Commands → workspace: http://localhost:4321/commands/workspace/
• Architecture: http://localhost:4321/reference/architecture/
• Runtime instance model: http://localhost:4321/reference/runtime-instance-model/
• TUI design decisions: http://localhost:4321/reference/tui-design-decisions/
• Desktop hub goal: http://localhost:4321/reference/goals/jackin-desktop-agent-hub/

Static checks

cd docs
bun run build
bun run check:repo-links
bunx tsc --noEmit

All three pass on this branch locally.

Migration notes

None.