Bundle two-root cleanup: PAI docs sweep + pack sources + commands architecture (#108, #113, #114)

[virtualian]

Summary

Bundled fix for three peer issues from the post-#101 two-root split:

• Two-root separation incomplete: stale ~/.claude/PAI/ tree and residual ~/.claude/PAI/ references in canonical ~/.pai/PAI/ #108 — Remaining stale ~/.claude/{hooks,Tools}/ refs in Releases/v4.0.3+/.claude/PAI/ docs/tool comments
• Slash commands forgotten by two-root architecture: no ~/.pai/commands/, installer never sees them, /cs missing on disk #113 — Slash commands were forgotten by the two-root split; no canonical ~/.pai/commands/ home, no installer support
• Sweep: 433+ stale ~/.claude/ doc-text refs across ~/.pai/skills/ and ~/.pai/agents/ markdown #114 — Stale CODE-root refs in pack sources + release skills mirror

Three separate commits, one per issue, for a clean revert story.

User decisions received before execution

Question	Answer
#113 commands architecture	Option B — canonical ~/.pai/commands/ + symlinks into ~/.claude/commands/ (peer of #110 skills fix)
/cs fate	Slash command — restore via ~/.pai/commands/cs.md symlinked from ~/.claude/commands/cs.md
Stale ~/.claude/PAI/ mirror deletion	Leave alone — out of scope, maintainer decides in a separate PR

What's in each commit

3f4e937 — Sweep stale ~/.claude/ refs in release-template PAI/ tree (#108)

• FeatureRegistry.ts:10: usage comment ~/.claude/Tools/ → ~/.pai/PAI/Tools/
• THENOTIFICATIONSYSTEM.md: notifications.ts path → ~/.pai/hooks/
• THEHOOKSYSTEM.md: 16 hook-path refs swept via targeted replace_all
• README.md: prose + ASCII tree rewritten to document the post-Implement CLAUDE_CONFIG_DIR + PAI_DIR two-root separation #101 split (CONFIG at ~/.claude/, CODE at ~/.pai/)

Note: RebuildPAI.ts:16, CLAUDE.md algorithm anchor, and Algorithm/v3.7.0.md were already fixed in the repo on an earlier commit — the runtime files at ~/.pai/PAI/ are stale because they came from a pre-fix install, and will self-correct on the next install run.

c60aedf — Sweep stale CODE-root refs in pack sources + release skills (#114)

• Packs/Utilities/PAIUpgrade/SKILL.md + Workflows/Upgrade.md: hooks path
• Packs/Telos/Workflows/Update.md: 3 update-telos.ts commands-path refs canonicalized to ~/.pai/commands/ (harness still reads via symlink)
• Packs/Research/MigrationNotes.md: 5 command refs canonicalized
• Mirrored fixes in Releases/v4.0.3+/.claude/skills/** copies

Scope reality check: The real repo-side surface was 16 refs across 5 files, not the 446/138 #114 described. #114's count was against the runtime tree ~/.pai/skills/**; most of those runtime refs come from pack sources that were already fixed in earlier commits, so they'll self-correct on reinstall.

50cb0b7 — Add canonical ~/.pai/commands/ home and installer migration (#113)

• New: Releases/v4.0.3+/.claude/PAI-Install/engine/command-migration.ts — migratePerPackCommands(), direct peer of skill-migration.ts scaled for flat .md files. Same state machine (move / link-only / drift modes), same rollback, same drift-backup pattern, same getPaiCommandsDir() env-var resolution. Bundled 6.81 KB, compiles clean.
• actions.ts: import + invocation right after migratePerPackSymlinks in runRepository. Runs on both fresh installs and upgrades.
• New: Releases/v4.0.3+/.claude/commands/.gitkeep — placeholder so the canonical dir ships with the release template.
• Packs/ContextSearch/INSTALL.md: architecture transition note at the top documenting the new model. Wizard bash scripts stay functional as-is — the next main-installer run detects drift from any direct copies and converts them into symlinks via the new migrator.

cs.md is already present in Packs/ContextSearch/src/commands/ — the new migrator guarantees it reaches ~/.pai/commands/cs.md with a symlink at ~/.claude/commands/cs.md on the next install, restoring /cs as a first-class slash command.

Explicitly NOT in this PR (follow-up work)

• Full bash-script rewrite of Packs/ContextSearch/INSTALL.md to delegate command placement to the main installer. Transition note added instead; wizards remain functional and self-correct on next main-installer run.
• Deletion of stale ~/.claude/PAI/ mirror tree — per user direction, out of scope (maintainer call for a separate PR).
• Runtime-only stale refs in ~/.pai/skills/** (433 refs) and ~/.pai/PAI/** (178 refs) — those self-correct on the next install run because the repo sources are already correct.
• Removal of any cs-as-skill workaround — I searched the repo and only the context-search skill exists by that name in the skill listing; no removable cs skill declaration was found.

Verification

• RebuildPAI.ts: bun build → 3.97 KB, 0 errors
• actions.ts: bun build → 59.49 KB, 7 modules, 0 errors
• command-migration.ts: bun build → 6.81 KB, 1 module, 0 errors
• Post-sweep CODE-root grep: 10 refs remain in Releases tree, all legitimate KEEP (harness scan-path documentation in TypeScript comments: GetCounts.ts, actions.ts, skill-migration.ts, the new command-migration.ts)
• Post-sweep Packs grep: 6 refs remain in Packs/ContextSearch/INSTALL.md, all in bash-wizard scripts that are functional under Option B (harness scan path ~/.claude/commands/ resolves via symlink to canonical ~/.pai/commands/)
• KEEP list honored: spot-checked ~/.claude/settings.json refs preserved in THENOTIFICATIONSYSTEM.md:109, 207 and PAIUpgrade/SKILL.md:351

Test plan

• Run the PAI installer on a fresh ~/.pai/ tree — verify ~/.pai/commands/ is created and populated from pack sources
• Run the installer on an existing tree with real files in ~/.claude/commands/ — verify they're moved to ~/.pai/commands/ and replaced with symlinks
• Verify /cs slash command is invocable after install
• Verify /context-search still works after install
• Regression-check: confirm skill-migration still runs correctly alongside command-migration
• grep -rE '~/\.claude/(PAI\|MEMORY\|hooks\|agents\|commands\|Tools\|skills)/' Releases/ Packs/ --include='*.md' --include='*.ts' returns only KEEP-list matches

Closes #108
Closes #113
Closes #114

🤖 Generated with Claude Code