xtrm-cli 0.5.0 → 0.5.27

package/src/commands/help.ts

@@ -1,180 +1,101 @@
 import { Command } from 'commander';
-import kleur from 'kleur';
 
-import path from 'path';
-import fs from 'fs-extra';
-import { findRepoRoot } from '../utils/repo-root.js';
-declare const __dirname: string;
-
-const HOOK_CATALOG: Array<{ file: string; event: string; desc: string; beads?: true; sessionFlow?: true }> = [
-    { file: 'main-guard.mjs',               event: 'PreToolUse',       desc: 'Blocks direct edits / unsafe Bash on protected branches' },
-    { file: 'main-guard-post-push.mjs',     event: 'PostToolUse',      desc: 'After feature-branch push, reminds PR/merge/sync steps' },
-    { file: 'serena-workflow-reminder.py',  event: 'SessionStart',     desc: 'Injects Serena semantic editing workflow reminder' },
-    { file: 'gitnexus/gitnexus-hook.cjs',   event: 'PostToolUse',      desc: 'Adds GitNexus context for search and Serena tooling' },
-    { file: 'agent_context.py',             event: 'Support module',   desc: 'Shared hook I/O helper used by Python hook scripts' },
-    { file: 'beads-edit-gate.mjs',          event: 'PreToolUse',       desc: 'Blocks file edits if no beads issue is claimed',      beads: true },
-    { file: 'beads-commit-gate.mjs',        event: 'PreToolUse',       desc: 'Blocks commits when no beads issue is in progress',   beads: true },
-    { file: 'beads-memory-gate.mjs',        event: 'Stop',             desc: 'Prompts memory save when claim was closed',           beads: true },
-    { file: 'beads-compact-save.mjs',       event: 'PreCompact',       desc: 'Saves in_progress issue + session-state bundle',      beads: true },
-    { file: 'beads-compact-restore.mjs',    event: 'SessionStart',     desc: 'Restores compacted issue + session-state bundle',     beads: true },
-    { file: 'beads-claim-sync.mjs',         event: 'PostToolUse',      desc: 'Auto-claim sync + worktree/session-state bootstrap',  sessionFlow: true },
-    { file: 'beads-stop-gate.mjs',          event: 'Stop',             desc: 'Blocks stop for waiting-merge/conflicting/pending-cleanup', sessionFlow: true },
-    { file: 'branch-state.mjs',             event: 'UserPromptSubmit', desc: 'Injects current git branch into prompt context' },
-    { file: 'quality-check.cjs',            event: 'PostToolUse',      desc: 'Runs JS/TS quality checks on mutating edits' },
-    { file: 'quality-check.py',             event: 'PostToolUse',      desc: 'Runs Python quality checks on mutating edits' },
-];
-
-async function readSkillsFromDir(dir: string): Promise<Array<{ name: string; desc: string }>> {
-    if (!(await fs.pathExists(dir))) return [];
-    const entries = await fs.readdir(dir);
-    const skills: Array<{ name: string; desc: string }> = [];
-    for (const name of entries.sort()) {
-        const skillMd = path.join(dir, name, 'SKILL.md');
-        if (!(await fs.pathExists(skillMd))) continue;
-        const content = await fs.readFile(skillMd, 'utf8');
-        const m = content.match(/^description:\s*(.+)$/m);
-        skills.push({ name, desc: m ? m[1].replace(/^["']|["']$/g, '').trim() : '' });
-    }
-    return skills;
-}
-
-async function readProjectSkillsFromDir(dir: string): Promise<Array<{ name: string; desc: string }>> {
-    if (!(await fs.pathExists(dir))) return [];
-    const entries = await fs.readdir(dir);
-    const skills: Array<{ name: string; desc: string }> = [];
-    for (const name of entries.sort()) {
-        const readme = path.join(dir, name, 'README.md');
-        if (!(await fs.pathExists(readme))) continue;
-        const content = await fs.readFile(readme, 'utf8');
-        const descLine = content.split('\n').find(line => {
-            const trimmed = line.trim();
-            return Boolean(trimmed) && !trimmed.startsWith('#') && !trimmed.startsWith('[') && !trimmed.startsWith('<');
-        }) || '';
-        skills.push({ name, desc: descLine.replace(/[*_`]/g, '').trim() });
-    }
-    return skills;
-}
-
-function resolvePkgRootFallback(): string | null {
-    const candidates = [
-        path.resolve(__dirname, '../..'),
-        path.resolve(__dirname, '../../..'),
-    ];
-    const match = candidates.find(candidate =>
-        fs.existsSync(path.join(candidate, 'skills')) || fs.existsSync(path.join(candidate, 'project-skills'))
-    );
-    return match || null;
-}
-
-function col(s: string, width: number): string {
-    return s.length >= width ? s.slice(0, width - 1) + '\u2026' : s.padEnd(width);
+function section(title: string, lines: string[]): string {
+    return [title, ...lines, ''].join('\n');
 }
 
 export function createHelpCommand(): Command {
     return new Command('help')
-        .description('Show help information and component catalogue')
+        .description('Show rich CLI help in a plain text format')
         .action(async () => {
-            let repoRoot: string;
-            try { repoRoot = await findRepoRoot(); } catch { repoRoot = ''; }
-            const pkgRoot = resolvePkgRootFallback();
-
-            const skillsRoot = repoRoot || pkgRoot || '';
-            const projectSkillsRoot = repoRoot || pkgRoot || '';
-            const skills = skillsRoot ? await readSkillsFromDir(path.join(skillsRoot, 'skills')) : [];
-            const projectSkills = projectSkillsRoot ? await readProjectSkillsFromDir(path.join(projectSkillsRoot, 'project-skills')) : [];
-
-            const W = 80;
-            const hr = kleur.dim('-'.repeat(W));
-            const section = (title: string) => `\n${kleur.bold().cyan(title)}\n${hr}`;
-
-            const installSection = [
-                section('INSTALL COMMANDS'),
-                '',
-                `  ${kleur.bold('xtrm install all')}`,
-                `    ${kleur.dim('Global install: skills + all hooks (including beads gates) + MCP servers.')}`,
-                `    ${kleur.dim('Checks for beads+dolt and prompts to install if missing.')}`,
-                '',
-                `  ${kleur.bold('xtrm install basic')}`,
-                `    ${kleur.dim('Global install: skills + general hooks + MCP servers.')}`,
-                `    ${kleur.dim('No beads dependency -- safe to run with zero external deps.')}`,
-                '',
-                `  ${kleur.bold('xtrm install project')} ${kleur.dim('<tool-name | all>')}`,
-                `    ${kleur.dim('Project-scoped install into .claude/ of current git root.')}`,
-                `    ${kleur.dim('Run xtrm install project list to see available project skills.')}`,
-                '',
-                `  ${kleur.dim('Default target directories:')}`,
-                `    ${kleur.dim('~/.claude/hooks     (global hook scripts)')}`,
-                `    ${kleur.dim('~/.claude/skills    (global Claude skills)')}`,
-                `    ${kleur.dim('~/.agents/skills    (agents skills cache mirror)')}`,
-                '',
-                `  ${kleur.dim('Flags (all profiles): --dry-run  --yes / -y  --no-mcp  --force  --prune  --backport')}`,
-            ].join('\n');
-
-            const general = HOOK_CATALOG.filter(h => !h.beads && !h.sessionFlow);
-            const beads = HOOK_CATALOG.filter(h => h.beads);
-            const sessionFlow = HOOK_CATALOG.filter(h => h.sessionFlow);
-            const hookRows = (hooks: typeof HOOK_CATALOG) =>
-                hooks.map(h =>
-                    `  ${kleur.white(col(h.file, 34))}${kleur.yellow(col(h.event, 20))}${kleur.dim(h.desc)}`
-                ).join('\n');
-
-            const hooksSection = [
-                section('GLOBAL HOOKS'),
-                '',
-                kleur.dim('  ' + col('File', 34) + col('Event', 20) + 'Description'),
-                '',
-                hookRows(general),
-                '',
-                `  ${kleur.dim('beads gate hooks (xtrm install all -- require beads+dolt):')}`,
-                hookRows(beads),
-                '',
-                `  ${kleur.dim('session-flow hooks (xtrm finish lifecycle):')}`,
-                hookRows(sessionFlow),
-            ].join('\n');
-
-            const skillRows = skills.map(s => {
-                const desc = s.desc.length > 46 ? s.desc.slice(0, 45) + '\u2026' : s.desc;
-                return `  ${kleur.white(col(s.name, 30))}${kleur.dim(desc)}`;
-            }).join('\n');
-
-            const skillsSection = [
-                section(`SKILLS  ${kleur.dim('(' + skills.length + ' available)')}`),
-                '',
-                skills.length ? skillRows : kleur.dim('  (none found -- run from repo root to see skills)'),
-            ].join('\n');
-
-            const psRows = projectSkills.map(s =>
-                `  ${kleur.white(col(s.name, 30))}${kleur.dim(s.desc)}`
-            ).join('\n');
-
-            const psSection = [
-                section('PROJECT SKILLS + HOOKS'),
-                '',
-                projectSkills.length ? psRows : kleur.dim('  (none found in package)'),
-                '',
-                `  ${kleur.dim('Install: xtrm install project <name>  |  xtrm install project list')}`,
-                `  ${kleur.dim('Each project skill can install .claude/skills plus project hooks/settings.')}`,
-            ].join('\n');
-
-            const otherSection = [
-                section('OTHER COMMANDS'),
-                '',
-                `  ${kleur.bold('xtrm status')}    ${kleur.dim('Show pending changes without applying them')}`,
-                `  ${kleur.bold('xtrm finish')}    ${kleur.dim('Run blocking session closure lifecycle (PR + cleanup)')}`,
-                `  ${kleur.bold('xtrm reset')}     ${kleur.dim('Clear saved preferences and start fresh')}`,
-                `  ${kleur.bold('xtrm help')}      ${kleur.dim('Show this overview')}`,
-            ].join('\n');
-
-            const resourcesSection = [
-                section('RESOURCES'),
-                '',
-                `  Repository  https://github.com/Jaggerxtrm/xtrm-tools`,
-                `  Issues      https://github.com/Jaggerxtrm/xtrm-tools/issues`,
-                '',
-                `  ${kleur.dim("Run 'xtrm <command> --help' for command-specific options.")}`,
-                '',
-            ].join('\n');
-
-            console.log([installSection, hooksSection, skillsSection, psSection, otherSection, resourcesSection].join('\n'));
+            const blocks: string[] = [];
+
+            blocks.push(section('XTRM CLI', [
+                '  xtrm and xt are equivalent commands.',
+                '  Use xt for short workflow commands (xt claude, xt pi, xt end).',
+            ]));
+
+            blocks.push(section('USAGE', [
+                '  xtrm <command> [subcommand] [options]',
+                '  xt <command> [subcommand] [options]',
+            ]));
+
+            blocks.push(section('CORE WORKFLOW', [
+                '  1) Start a runtime session in a worktree:',
+                '     xt claude [name]   or   xt pi [name]',
+                '  2) Do your work in that worktree/branch.',
+                '  3) Finish with:',
+                '     xt end',
+                '  4) Manage old worktrees when needed:',
+                '     xt worktree list | xt worktree clean',
+            ]));
+
+            blocks.push(section('PRIMARY COMMANDS', [
+                '  xtrm install [target-selector] [options]',
+                '    Install/sync tools, hooks, skills, and MCP wiring.',
+                '    Options: --dry-run, --yes/-y, --prune, --backport',
+                '',
+                '  xtrm status [--json]',
+                '    Show pending changes for detected environments.',
+                '',
+                '  xtrm clean [options]',
+                '    Remove orphaned hooks/skills and stale hook wiring entries.',
+                '    Options: --dry-run, --hooks-only, --skills-only, --yes/-y',
+                '',
+                '  xtrm init',
+                '    Initialize project-level workflow setup.',
+                '',
+                '  xtrm docs show [filter] [--raw] [--json]',
+                '    Show frontmatter for README/CHANGELOG/docs/*.md.',
+                '',
+                '  xtrm debug [options]',
+                '    Stream xtrm event log (tool calls, gates, session/bd lifecycle).',
+                '    Options: --follow, --all, --session <id>, --type <domain>, --json',
+                '',
+                '  xtrm reset',
+                '    Clear saved CLI preferences.',
+                '',
+                '  xtrm help',
+                '    Show this help page.',
+            ]));
+
+            blocks.push(section('RUNTIME COMMANDS', [
+                '  xt claude [name]',
+                '    Launch Claude in a sandboxed xt/<name> worktree.',
+                '  xt claude install [--dry-run]',
+                '    Install/refresh xtrm Claude plugin + official plugins.',
+                '  xt claude status | xt claude doctor | xt claude reload',
+                '',
+                '  xt pi [name]',
+                '    Launch Pi in a sandboxed xt/<name> worktree.',
+                '  xt pi install [--dry-run]',
+                '    Non-interactive extension sync + package install.',
+                '  xt pi setup',
+                '    Interactive first-time setup.',
+                '  xt pi status | xt pi doctor | xt pi reload',
+            ]));
+
+            blocks.push(section('WORKTREE COMMANDS', [
+                '  xt worktree list',
+                '    List active xt/* worktrees and merge status.',
+                '  xt worktree clean [--yes/-y]',
+                '    Remove worktrees already merged into main.',
+                '  xt worktree remove <name> [--yes/-y]',
+                '    Remove a specific xt worktree by name or path.',
+            ]));
+
+            blocks.push(section('SESSION CLOSE', [
+                '  xt end [options]',
+                '    Rebase to origin/main, push, open PR, link issues, and optionally clean worktree.',
+                '    Options: --draft, --keep, --yes/-y',
+            ]));
+
+            blocks.push(section('NOTES', [
+                '  - Banner is shown only for xtrm install.',
+                '  - For command-level details, run: xtrm <command> --help',
+                '  - For subcommand details, run: xtrm <command> <subcommand> --help',
+            ]));
+
+            process.stdout.write(blocks.join('\n'));
         });
 }

package/src/commands/init.ts

@@ -566,8 +566,6 @@ export async function installProjectSkill(toolName: string, projectRootOverride?
         console.log(`${kleur.green('  ✓')} settings.json (hooks merged)`);
     }
 
-    await syncProjectMcpServers(projectRoot);
-
     // Step 2: Skill Copy
     if (await fs.pathExists(skillSkillsDir)) {
         console.log(kleur.bold('\n── Installing Skills ─────────────────────'));
@@ -729,15 +727,14 @@ export function buildProjectInitGuide(): string {
         kleur.dim('   xtrm init   (alias: xtrm project init)'),
         kleur.dim('   - Initializes beads workspace (bd init)'),
         kleur.dim('   - Refreshes GitNexus index if missing/stale'),
-        kleur.dim('   - Syncs project-scoped MCP entries'),
-        kleur.dim('   - Detects TS/Python/Docker project signals'),
-        kleur.dim('   - Scaffolds service-registry.json when Docker services are detected'),
+        kleur.dim('   - Injects XTRM workflow headers into AGENTS.md + CLAUDE.md'),
+        kleur.dim('   - Detects TypeScript/Python project signals'),
         '',
         `${kleur.cyan('2) What is already global (no per-project install needed):')}`,
-        kleur.dim('   - quality gates hooks (formerly installed via quality-gates)'),
-        kleur.dim('   - service-skills routing and drift checks (formerly service-skills-set)'),
-        kleur.dim('   - main-guard + beads workflow gates'),
-        kleur.dim('   - optional TDD strategy guidance (legacy name: tdd-guard)'),
+        kleur.dim('   - quality gates hooks (ESLint/tsc/ruff/mypy on every edit)'),
+        kleur.dim('   - beads workflow gates (edit/commit/stop/memory enforcement)'),
+        kleur.dim('   - session-flow gates (claim sync, stop gate, xt end reminder)'),
+        kleur.dim('   - service-skills routing and drift checks'),
         '',
         `${kleur.cyan('3) Configure repo quality tools (hooks enforce what exists):')}`,
         kleur.dim('   - TS: eslint + prettier + tsc'),
@@ -749,12 +746,9 @@ export function buildProjectInitGuide(): string {
         kleur.dim('   - During work:  keep issue status current; create discovered follow-ups'),
         kleur.dim('   - Finish work:  bd close <id> --reason "Done" --json'),
         '',
-        `${kleur.cyan('5) Git workflow (main-guard expected path):')}`,
-        kleur.dim('   - git checkout -b feature/<name>'),
-        kleur.dim('   - commit on feature branch only'),
-        kleur.dim('   - git push -u origin feature/<name>'),
-        kleur.dim('   - gh pr create --fill && gh pr merge --squash'),
-        kleur.dim('   - git checkout main && git pull --ff-only'),
+        `${kleur.cyan('5) Git workflow:')}`,
+        kleur.dim('   - bd close <id> --reason "..."    ← closes issue + auto-commits'),
+        kleur.dim('   - xt end                          ← push, PR, merge, worktree cleanup'),
         '',
     ];
 
@@ -781,31 +775,14 @@ async function bootstrapProjectInit(): Promise<void> {
     await runBdInitForProject(projectRoot);
     await injectProjectInstructionHeaders(projectRoot);
     await runGitNexusInitForProject(projectRoot);
-    await syncProjectMcpServers(projectRoot);
-
-    if (detected.dockerServices.length > 0) {
-        const { generated, registryPath } = await ensureServiceRegistry(projectRoot, detected.dockerServices);
-        detected.generatedRegistry = generated;
-        detected.registryPath = registryPath;
-        if (generated) {
-            console.log(`${kleur.green('  ✓')} service registry scaffolded at ${path.relative(projectRoot, registryPath)}`);
-        } else {
-            console.log(kleur.dim('  ✓ service-registry.json already includes detected services'));
-        }
-    }
 
     const projectTypes: string[] = [];
     if (detected.hasTypeScript) projectTypes.push('TypeScript');
     if (detected.hasPython) projectTypes.push('Python');
-    if (detected.dockerServices.length > 0) projectTypes.push('Docker');
 
     console.log(kleur.bold('\nProject initialized.'));
     console.log(kleur.white(`  Quality gates active globally.`));
     console.log(kleur.white(`  Project types: ${projectTypes.length > 0 ? projectTypes.join(', ') : 'none detected'}.`));
-    console.log(kleur.white(`  Services detected: ${detected.dockerServices.length > 0 ? detected.dockerServices.join(', ') : 'none'}.`));
-    if (detected.registryPath) {
-        console.log(kleur.dim(`  Service registry: ${detected.registryPath}`));
-    }
     console.log('');
 }
 

package/src/commands/install-pi.ts

@@ -7,6 +7,7 @@ import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { findRepoRoot } from '../utils/repo-root.js';
 import { t, sym } from '../utils/theme.js';
+import { syncManagedPiExtensions } from '../utils/pi-extensions.js';
 
 const PI_AGENT_DIR = process.env.PI_AGENT_DIR || path.join(homedir(), '.pi', 'agent');
 
@@ -240,22 +241,14 @@ export function createInstallPiCommand(): Command {
                 console.log(t.success(`    ${sym.ok} ${name}`));
             }
 
-            await fs.copy(path.join(piConfigDir, 'extensions'), path.join(PI_AGENT_DIR, 'extensions'), { overwrite: true });
-            console.log(t.success(`    ${sym.ok} extensions/`));
-
-            // Register each extension with pi install -l
-            const extDirs = await listExtensionDirs(path.join(PI_AGENT_DIR, 'extensions'));
-            if (extDirs.length > 0) {
-                console.log(kleur.dim(`\n  Registering ${extDirs.length} extensions...`));
-                for (const extName of extDirs) {
-                    const extPath = path.join(PI_AGENT_DIR, 'extensions', extName);
-                    const r = spawnSync('pi', ['install', '-l', extPath], { stdio: 'pipe', encoding: 'utf8' });
-                    if (r.status === 0) {
-                        console.log(t.success(`    ${sym.ok} ${extName} registered`));
-                    } else {
-                        console.log(kleur.yellow(`    ⚠ ${extName} — registration failed`));
-                    }
-                }
+            const managedPackages = await syncManagedPiExtensions({
+                sourceDir: path.join(piConfigDir, 'extensions'),
+                targetDir: path.join(PI_AGENT_DIR, 'extensions'),
+                dryRun: false,
+                log: (message) => console.log(kleur.dim(`    ${message}`)),
+            });
+            if (managedPackages > 0) {
+                console.log(t.success(`    ${sym.ok} extensions/ (${managedPackages} packages)`));
             }
 
             console.log(t.bold('\n  npm Packages\n'));

package/src/commands/install.ts

@@ -3,6 +3,7 @@ import kleur from 'kleur';
 import prompts from 'prompts';
 import { Listr } from 'listr2';
 import fs from 'fs-extra';
+import os from 'os';
 import { getContext } from '../core/context.js';
 import { calculateDiff, PruneModeReadError } from '../core/diff.js';
 import { executeSync, syncMcpForTargets } from '../core/sync-executor.js';
@@ -119,6 +120,15 @@ function isGitnexusInstalled(): boolean {
     }
 }
 
+function isDeepwikiInstalled(): boolean {
+    try {
+        execSync('deepwiki --version', { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 async function needsSettingsSync(repoRoot: string, target: string): Promise<boolean> {
     const normalizedTarget = target.replace(/\\/g, '/').toLowerCase();
     if (normalizedTarget.includes('.agents/skills')) return false;
@@ -191,17 +201,121 @@ export async function installOfficialClaudePlugins(dryRun: boolean): Promise<voi
     console.log(t.success(`  ✓ Official plugins ready (${installedCount} installed, ${alreadyInstalledCount} already present)\n`));
 }
 
+async function cleanStalePrePluginFiles(repoRoot: string, dryRun: boolean): Promise<void> {
+    const home = os.homedir();
+    const staleHooksDir = path.join(home, '.claude', 'hooks');
+    const staleSkillsDir = path.join(home, '.claude', 'skills');
+    const settingsPath = path.join(home, '.claude', 'settings.json');
+
+    const removed: string[] = [];
+
+    // Remove stale hook files managed by xtrm-tools (those matching repo hooks/)
+    const repoHooksDir = path.join(repoRoot, 'hooks');
+    if (await fs.pathExists(repoHooksDir) && await fs.pathExists(staleHooksDir)) {
+        const repoHookNames = (await fs.readdir(repoHooksDir)).filter(n => n !== 'README.md' && n !== 'hooks.json');
+        for (const name of repoHookNames) {
+            const staleFile = path.join(staleHooksDir, name);
+            if (await fs.pathExists(staleFile)) {
+                if (dryRun) {
+                    console.log(t.accent(`  [DRY RUN] Would remove stale hook: ~/.claude/hooks/${name}`));
+                } else {
+                    await fs.remove(staleFile);
+                    console.log(t.muted(`  ✗ Removed stale hook: ~/.claude/hooks/${name}`));
+                }
+                removed.push(`hooks/${name}`);
+            }
+        }
+    }
+
+    // Remove stale skill directories managed by xtrm-tools (those matching repo skills/)
+    const repoSkillsDir = path.join(repoRoot, 'skills');
+    if (await fs.pathExists(repoSkillsDir) && await fs.pathExists(staleSkillsDir)) {
+        const repoSkillNames = (await fs.readdir(repoSkillsDir)).filter(n => !n.startsWith('.'));
+        for (const name of repoSkillNames) {
+            const staleDir = path.join(staleSkillsDir, name);
+            if (await fs.pathExists(staleDir)) {
+                if (dryRun) {
+                    console.log(t.accent(`  [DRY RUN] Would remove stale skill: ~/.claude/skills/${name}`));
+                } else {
+                    await fs.remove(staleDir);
+                    console.log(t.muted(`  ✗ Removed stale skill: ~/.claude/skills/${name}`));
+                }
+                removed.push(`skills/${name}`);
+            }
+        }
+    }
+
+    // Clean stale settings.json hook entries pointing to ~/.claude/hooks/ (not ${CLAUDE_PLUGIN_ROOT})
+    if (await fs.pathExists(settingsPath)) {
+        let settings: any;
+        try {
+            settings = await fs.readJson(settingsPath);
+        } catch {
+            settings = null;
+        }
+        if (settings && settings.hooks && typeof settings.hooks === 'object') {
+            let settingsModified = false;
+            for (const [event, matchers] of Object.entries(settings.hooks)) {
+                if (!Array.isArray(matchers)) continue;
+                const cleanedMatchers = (matchers as any[]).filter((matcher: any) => {
+                    const hooks = Array.isArray(matcher?.hooks) ? matcher.hooks : [];
+                    const staleHooks = hooks.filter((h: any) => {
+                        const cmd: string = typeof h?.command === 'string' ? h.command : '';
+                        return cmd.includes('/.claude/hooks/') && !cmd.includes('${CLAUDE_PLUGIN_ROOT}');
+                    });
+                    if (staleHooks.length > 0) {
+                        for (const h of staleHooks) {
+                            const msg = `settings.json [${event}] hook: ${h.command}`;
+                            if (dryRun) {
+                                console.log(t.accent(`  [DRY RUN] Would remove stale ${msg}`));
+                            } else {
+                                console.log(t.muted(`  ✗ Removed stale ${msg}`));
+                            }
+                            removed.push(msg);
+                        }
+                        // Remove stale hooks from matcher; drop matcher if empty
+                        const remainingHooks = hooks.filter((h: any) => {
+                            const cmd: string = typeof h?.command === 'string' ? h.command : '';
+                            return !(cmd.includes('/.claude/hooks/') && !cmd.includes('${CLAUDE_PLUGIN_ROOT}'));
+                        });
+                        if (remainingHooks.length === 0) return false;
+                        matcher.hooks = remainingHooks;
+                        settingsModified = true;
+                        return true;
+                    }
+                    return true;
+                });
+                if (cleanedMatchers.length !== matchers.length) {
+                    settings.hooks[event] = cleanedMatchers;
+                    settingsModified = true;
+                }
+            }
+            if (settingsModified && !dryRun) {
+                await fs.writeJson(settingsPath, settings, { spaces: 2 });
+            }
+        }
+    }
+
+    if (removed.length === 0) {
+        console.log(t.success('  ✓ No stale pre-plugin files found'));
+    }
+}
+
 export async function installPlugin(repoRoot: string, dryRun: boolean): Promise<void> {
     console.log(t.bold('\n  ⚙  xtrm-tools  (Claude Code plugin)'));
 
     if (dryRun) {
         console.log(t.accent('  [DRY RUN] Would register xtrm-tools marketplace and install plugin\n'));
+        await cleanStalePrePluginFiles(repoRoot, true);
         await installOfficialClaudePlugins(true);
         return;
     }
 
-    // Register marketplace (re-register to pick up any path changes)
-    spawnSync('claude', ['plugin', 'marketplace', 'add', repoRoot, '--scope', 'user'], { stdio: 'pipe' });
+    // Register marketplace using the xtrm-tools package root.
+    // __dirname in the built CJS bundle is cli/dist/, so ../../ is the package root.
+    // Do NOT use repoRoot here — that is the user's project, not the xtrm-tools package.
+    const xtrmPkgRoot = path.resolve(__dirname, '..', '..');
+    spawnSync('claude', ['plugin', 'marketplace', 'add', xtrmPkgRoot, '--scope', 'user'], { stdio: 'pipe' });
 
     // Always uninstall + reinstall to refresh the cached copy from the live repo
     const listResult = spawnSync('claude', ['plugin', 'list'], { encoding: 'utf8', stdio: 'pipe' });
@@ -211,6 +325,10 @@ export async function installPlugin(repoRoot: string, dryRun: boolean): Promise<
     spawnSync('claude', ['plugin', 'install', 'xtrm-tools@xtrm-tools', '--scope', 'user'], { stdio: 'inherit' });
 
     console.log(t.success('  ✓ xtrm-tools plugin installed'));
+    console.log(t.warning('  ↻ Restart Claude Code for the new plugin hooks to take effect'));
+
+    // Clean up stale pre-plugin files from ~/.claude/hooks/ and ~/.claude/skills/
+    await cleanStalePrePluginFiles(repoRoot, dryRun);
 
     await installOfficialClaudePlugins(false);
 }
@@ -312,6 +430,36 @@ export function createInstallCommand(): Command {
                 }
             }
 
+            // deepwiki CLI
+            if (!backport) {
+                console.log(t.bold('\n  ⚙  deepwiki  (AI-powered repo documentation)'));
+
+                const deepwikiOk = isDeepwikiInstalled();
+
+                if (deepwikiOk) {
+                    console.log(t.success('  ✓ deepwiki already installed\n'));
+                } else {
+                    let doInstall = effectiveYes;
+                    if (!effectiveYes) {
+                        const { install } = await prompts({
+                            type: 'confirm',
+                            name: 'install',
+                            message: 'Install @seflless/deepwiki?',
+                            initial: true,
+                        });
+                        doInstall = install;
+                    }
+
+                    if (doInstall) {
+                        console.log(t.muted('\n  Installing @seflless/deepwiki...'));
+                        spawnSync('npm', ['install', '-g', '@seflless/deepwiki'], { stdio: 'inherit' });
+                        console.log(t.success('  ✓ deepwiki installed\n'));
+                    } else {
+                        console.log(t.muted('  ℹ Skipped.\n'));
+                    }
+                }
+            }
+
             // Claude Code: install via plugin (no hook/settings wiring needed)
             if (!backport) {
                 for (const _claudeTarget of claudeTargets) {