@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/commands-v2/handlers/games.js

@@ -0,0 +1,57 @@
+/**
+ * Games Command Handler
+ *
+ * Hidden easter egg - terminal arcade games!
+ */
+import { GamesOverlayV2 } from '../../ui/overlay/index.js';
+import { checkDailyBonus } from '../../games/index.js';
+// =============================================================================
+// Games Command
+// =============================================================================
+export const gamesCommand = {
+    name: 'games',
+    aliases: ['arcade', 'play'],
+    description: 'Open the arcade',
+    details: 'Hidden easter egg! Play classic arcade games. Earn coins by being productive with the CLI.',
+    examples: [
+        { code: '/games', description: 'Open the arcade menu' },
+        { code: '/arcade', description: 'Alias' },
+    ],
+    interactions: [
+        '↑/↓ to select a game',
+        'Enter to play (costs 1 coin)',
+        'Q to exit',
+    ],
+    // Note: Easter egg - could add hidden flag to CommandHandlerV2 if needed
+    async execute(_args, ctx) {
+        // Check for daily bonus (only on first open)
+        let gotDailyBonus = checkDailyBonus();
+        let keepPlaying = true;
+        // Loop: show arcade, play game, return to arcade
+        while (keepPlaying) {
+            // Show overlay (displays coins, bonus notification, and game selection)
+            const overlay = new GamesOverlayV2({ gotDailyBonus });
+            const result = await ctx.ui.showOverlay(overlay);
+            // Clear daily bonus notification after first display
+            gotDailyBonus = false;
+            if (result?.action === 'play' && result.game) {
+                // Pause the UI completely - game will take over stdin
+                ctx.ui.pauseAnimation();
+                try {
+                    // Play the game (runs in alternate screen with its own input handling)
+                    await result.game.play();
+                }
+                finally {
+                    // Resume UI input handling
+                    ctx.ui.resumeAnimation();
+                }
+                // After game ends, loop back to show arcade again
+            }
+            else {
+                // User closed arcade (pressed Q or Escape)
+                keepPlaying = false;
+            }
+        }
+        return true;
+    },
+};

package/dist/commands-v2/handlers/index.d.ts

@@ -9,4 +9,17 @@ export * from './settings.js';
 export * from './context.js';
 export * from './project.js';
 export * from './debug.js';
+export * from './session.js';
+export * from './reset.js';
+export * from './team.js';
+export * from './games.js';
+export * from './tasks.js';
+export * from './background.js';
+export * from './filter.js';
+export * from './auth.js';
+export * from './files.js';
+export * from './terminals.js';
+export * from './notifications.js';
+export * from './mcp.js';
+export * from './delegations.js';
 export declare const allCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/index.js

@@ -8,12 +8,38 @@ import { settingsCommands } from './settings.js';
 import { contextCommands } from './context.js';
 import { projectCommands } from './project.js';
 import { debugCommands } from './debug.js';
+import { sessionCommands } from './session.js';
+import { resetCommands } from './reset.js';
+import { teamCommands } from './team.js';
+import { gamesCommand } from './games.js';
+import { tasksCommand } from './tasks.js';
+import { backgroundCommands } from './background.js';
+import { filterCommands } from './filter.js';
+import { authCommands } from './auth.js';
+import { filesCommands } from './files.js';
+import { terminalsCommands } from './terminals.js';
+import { notificationsCommands } from './notifications.js';
+import { mcpCommands } from './mcp.js';
+import { delegationsCommands } from './delegations.js';
 // Re-export individual modules
 export * from './core.js';
 export * from './settings.js';
 export * from './context.js';
 export * from './project.js';
 export * from './debug.js';
+export * from './session.js';
+export * from './reset.js';
+export * from './team.js';
+export * from './games.js';
+export * from './tasks.js';
+export * from './background.js';
+export * from './filter.js';
+export * from './auth.js';
+export * from './files.js';
+export * from './terminals.js';
+export * from './notifications.js';
+export * from './mcp.js';
+export * from './delegations.js';
 // All commands combined
 export const allCommands = [
     ...coreCommands,
@@ -21,4 +47,17 @@ export const allCommands = [
     ...contextCommands,
     ...projectCommands,
     ...debugCommands,
+    ...sessionCommands,
+    ...resetCommands,
+    ...teamCommands,
+    gamesCommand,
+    tasksCommand,
+    ...backgroundCommands,
+    ...filterCommands,
+    ...authCommands,
+    ...filesCommands,
+    ...terminalsCommands,
+    ...notificationsCommands,
+    ...mcpCommands,
+    ...delegationsCommands,
 ];

package/dist/commands-v2/handlers/mcp.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Command for REPL V2
+ *
+ * Shows the MCP servers overlay for viewing connected servers,
+ * their tools, and managing connections.
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const mcpCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/mcp.js

@@ -0,0 +1,39 @@
+/**
+ * MCP Command for REPL V2
+ *
+ * Shows the MCP servers overlay for viewing connected servers,
+ * their tools, and managing connections.
+ */
+import { MCPOverlayV2 } from '../../ui/overlay/impl/mcp-overlay-v2.js';
+import { getMCPManager, ensureMCPManager } from '../../index.js';
+import { getMCPConfigPath } from '../../settings/mcp-config.js';
+import { getActiveProject } from '../../tools/project-db.js';
+// =============================================================================
+// /mcp Command
+// =============================================================================
+const mcpCommand = {
+    name: 'mcp',
+    description: 'View MCP servers and tools',
+    details: 'Opens the MCP (Model Context Protocol) servers overlay. ' +
+        'View connected servers, their discovered tools, and manage connections. ' +
+        `Configure servers in ${getMCPConfigPath()}.`,
+    examples: [
+        { code: '/mcp', description: 'Show MCP servers dashboard' },
+    ],
+    interactions: [
+        'Enter to view server details and tools',
+        'a to add a new server',
+        'r to restart a server',
+        'd to disconnect a server',
+        '/ to search',
+        'Esc to close',
+    ],
+    async execute(_args, ctx) {
+        const manager = getMCPManager();
+        const project = getActiveProject();
+        const overlay = new MCPOverlayV2(manager, ctx.agent ?? null, ensureMCPManager, project?.path);
+        await ctx.ui.showOverlay(overlay);
+        return true;
+    },
+};
+export const mcpCommands = [mcpCommand];

package/dist/commands-v2/handlers/notifications.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Notifications Command Handler
+ *
+ * Shows cross-session notifications from other terminals.
+ * Opens an interactive overlay when unread notifications exist.
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const notificationsCommand: CommandHandlerV2;
+export declare const notificationsCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/notifications.js

@@ -0,0 +1,34 @@
+/**
+ * Notifications Command Handler
+ *
+ * Shows cross-session notifications from other terminals.
+ * Opens an interactive overlay when unread notifications exist.
+ */
+import { getNotificationManager } from '../../multi-agent/notification-manager.js';
+import { NotificationsOverlayV2 } from '../../ui/overlay/impl/notifications-overlay-v2.js';
+export const notificationsCommand = {
+    name: 'notifications',
+    aliases: ['notif'],
+    description: 'Show cross-session notifications',
+    details: 'Lists unread notifications from other terminal sessions (e.g. background agent completions, pending approval requests).',
+    examples: [
+        { code: '/notifications', description: 'View unread notifications' },
+        { code: '/notif', description: 'Alias for /notifications' },
+    ],
+    async execute(_args, ctx) {
+        const manager = getNotificationManager();
+        if (!manager) {
+            ctx.ui.print({ type: 'info', message: 'Notification manager not available.' });
+            return true;
+        }
+        const count = manager.getUnreadCount();
+        if (count === 0) {
+            ctx.ui.print({ type: 'info', message: 'No unread notifications.' });
+            return true;
+        }
+        const overlay = new NotificationsOverlayV2();
+        await ctx.ui.showOverlay(overlay);
+        return true;
+    },
+};
+export const notificationsCommands = [notificationsCommand];

package/dist/commands-v2/handlers/project.js

@@ -4,11 +4,12 @@
  * Commands for project management: init, backlog, workflow, anchors, design, sketch, refine
  */
 import { executeCommand } from '../registry.js';
-import { BacklogOverlayV2, WorkflowOverlayV2, DocsOverlayV2, DocumentDetailOverlayV2, AnchorsOverlayV2, ProjectsOverlayV2, NewProjectOverlayV2, InitSetupOverlayV2, ArchTypeOverlayV2, ModelWarningOverlayV2 } from '../../ui/overlay/index.js';
+import { BacklogOverlayV2, WorkflowOverlayV2, DocsOverlayV2, DocumentDetailOverlayV2, AnchorsOverlayV2, ProjectsOverlayV2, NewProjectOverlayV2, OnboardingWizardOverlayV2, KeysOverlayV2, ArchTypeOverlayV2, ModelWarningOverlayV2 } from '../../ui/overlay/index.js';
 import { projectRepository, workItemRepository } from '../../db/repositories/index.js';
 import { setCurrentProject, getCurrentProject } from '../../tools/project-db.js';
 import { getSkillPrompt } from '../../repl-helpers.js';
 import { getModelTier, modelMeetsTier } from '../../utils/model-tiers.js';
+import { getCurrentProjectIdForTracking, handleProjectSwitch } from './session.js';
 // =============================================================================
 // Helper Functions
 // =============================================================================
@@ -26,33 +27,80 @@ function syncFooterWithCurrentProject(ctx) {
 export const newCommand = {
     name: 'new',
     description: 'Create a new project',
+    details: 'Interactive wizard to scaffold a new project. Asks about project name, type, tech stack, and documentation preferences. Creates project structure with COMPILR.md, backlog, and optional separate docs repo.',
+    examples: [{ code: '/new' }],
+    interactions: [
+        '8-step wizard (0-7)',
+        '↑/↓ for selection steps, type for input steps',
+        'Enter to confirm, Esc to go back',
+    ],
     async execute(_args, ctx) {
+        // Track project ID before overlay (for session/team switch handling)
+        const oldProjectId = getCurrentProjectIdForTracking();
         const newProjectOverlay = new NewProjectOverlayV2();
         const result = await ctx.ui.showOverlay(newProjectOverlay);
         // User cancelled
         if (!result?.created) {
             return true;
         }
-        // Project was created - show success messages
-        ctx.ui.print({ type: 'success', message: `Project created: ${result.projectPath ?? ''}` });
-        if (result.docsPath) {
-            ctx.ui.print({ type: 'success', message: `Docs repo created: ${result.docsPath}` });
+        // Check if this was an import or new project
+        const isImport = result.imported === true;
+        // Show success message
+        if (isImport) {
+            ctx.ui.print({ type: 'success', message: `Project imported: ${result.projectPath ?? ''}` });
+        }
+        else {
+            ctx.ui.print({ type: 'success', message: `Project created: ${result.projectPath ?? ''}` });
+            if (result.docsPath) {
+                ctx.ui.print({ type: 'success', message: `Docs repo created: ${result.docsPath}` });
+            }
         }
         // Register project in database if tracking is enabled
         if (result.trackInDatabase && result.projectName && result.projectPath) {
             try {
+                // Determine display name - for imports, use detected name; for new projects, prettify
+                const displayName = result.detectedProject?.displayName
+                    ?? result.projectName.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
                 const project = projectRepository.create({
                     name: result.projectName,
-                    display_name: result.projectName.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+                    display_name: displayName,
                     description: result.description,
                     path: result.projectPath,
                     type: 'general',
                     workflow_mode: result.workflowMode ?? 'flexible',
+                    git_remote: result.gitRemote,
+                    // For imports, include detected language and framework
+                    language: result.detectedProject?.language ?? undefined,
+                    framework: result.detectedProject?.framework ?? undefined,
+                    package_manager: result.detectedProject?.packageManager ?? undefined,
                 });
+                // For imports, set lifecycle to 'active' immediately
+                if (isImport) {
+                    projectRepository.update(project.id, { lifecycle_state: 'active' });
+                }
                 setCurrentProject({ id: project.id, name: project.name, displayName: project.displayName, path: project.path });
                 ctx.ui.setProjectName(project.displayName);
                 ctx.ui.print({ type: 'success', message: `Project tracked in database (${result.workflowMode ?? 'flexible'} mode)` });
                 ctx.ui.print({ type: 'success', message: `"${project.displayName}" is now the current project` });
+                // Handle project switch - saves old session/team and creates fresh team for new project
+                const switchResult = await handleProjectSwitch(oldProjectId, ctx.agent ?? null, ctx.team && ctx.agentFactory ? {
+                    team: ctx.team,
+                    agentFactory: ctx.agentFactory,
+                } : undefined);
+                if (switchResult?.switched) {
+                    // Update the team if a new one was created
+                    if (switchResult.newTeam && ctx.setTeam) {
+                        ctx.setTeam(switchResult.newTeam);
+                        // Update footer with new active agent
+                        const active = switchResult.newTeam.getActive();
+                        ctx.ui.setActiveTeamAgent({
+                            id: active.id,
+                            displayName: active.displayName,
+                            mascot: active.mascot,
+                        });
+                    }
+                    ctx.ui.print({ type: 'info', message: 'Fresh team and session started for project.' });
+                }
             }
             catch (dbError) {
                 ctx.ui.print({ type: 'warning', message: `Could not register in database: ${dbError.message}` });
@@ -60,17 +108,29 @@ export const newCommand = {
         }
         // Show next steps
         ctx.ui.print({ type: 'info', message: '' });
-        ctx.ui.print({ type: 'info', message: 'Next steps:' });
-        ctx.ui.print({ type: 'info', message: `  cd ${result.projectPath?.split('/').pop() ?? 'project'}` });
-        ctx.ui.print({ type: 'info', message: '  npm install' });
-        ctx.ui.print({ type: 'info', message: '  npm run dev' });
+        if (isImport) {
+            // Import-specific next steps
+            ctx.ui.print({ type: 'info', message: 'Next steps:' });
+            ctx.ui.print({ type: 'info', message: '  Review the generated COMPILR.md' });
+            ctx.ui.print({ type: 'info', message: '  Add existing work items with /backlog' });
+            ctx.ui.print({ type: 'info', message: '  Or ask the agent to explore the codebase' });
+        }
+        else {
+            // New project next steps
+            ctx.ui.print({ type: 'info', message: 'Next steps:' });
+            ctx.ui.print({ type: 'info', message: `  cd ${result.projectPath?.split('/').pop() ?? 'project'}` });
+            ctx.ui.print({ type: 'info', message: '  npm install' });
+            ctx.ui.print({ type: 'info', message: '  npm run dev' });
+        }
         ctx.ui.print({ type: 'info', message: '' });
         // Hint for agent interaction
         const compilrMdPath = result.docsPath
             ? `${result.docsPath}/COMPILR.md`
             : `${result.projectPath ?? '.'}/COMPILR.md`;
         ctx.ui.print({ type: 'info', message: `Tip: Ask the agent to read ${compilrMdPath} to get started!` });
-        ctx.ui.print({ type: 'info', message: 'When ready to define requirements, type /design' });
+        if (!isImport) {
+            ctx.ui.print({ type: 'info', message: 'When ready to define requirements, type /design' });
+        }
         return true;
     },
 };
@@ -79,10 +139,30 @@ export const newCommand = {
 // =============================================================================
 export const initCommand = {
     name: 'init',
-    description: 'View CLI setup status',
+    description: 'Run the CLI setup wizard',
+    details: 'Opens the onboarding wizard to configure API keys, git settings, and CLI preferences. Re-runnable anytime to update settings.',
+    examples: [{ code: '/init' }],
+    interactions: [
+        '↑/↓ to navigate wizard steps',
+        'Enter to confirm, Esc to go back',
+        'Type to enter values in input steps',
+    ],
     async execute(_args, ctx) {
-        const initSetupOverlay = new InitSetupOverlayV2();
-        await ctx.ui.showOverlay(initSetupOverlay);
+        // Show onboarding wizard (same as first-run experience)
+        // Loop if user chooses to configure keys
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        while (true) {
+            const wizard = new OnboardingWizardOverlayV2();
+            const result = await ctx.ui.showOverlay(wizard);
+            if (result?.openKeys) {
+                // User chose to configure keys - show keys overlay then loop back
+                const keysOverlay = new KeysOverlayV2();
+                await ctx.ui.showOverlay(keysOverlay);
+                continue;
+            }
+            // Done (completed or cancelled)
+            break;
+        }
         return true;
     },
 };
@@ -92,8 +172,19 @@ export const initCommand = {
 export const backlogCommand = {
     name: 'backlog',
     description: 'View and manage project backlog',
+    details: 'Opens an interactive overlay to browse, filter, and manage backlog items. You can add new items, change status/priority, search, and view details.',
+    examples: [{ code: '/backlog' }],
+    interactions: [
+        'Tab cycles: All → Feature → Bug → Tech-Debt → Chore → Active',
+        '↑/↓ to navigate, ←/→ for pages',
+        'Enter for details, Space to toggle status',
+        '/ to search, n for new item',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
-        const backlogOverlay = new BacklogOverlayV2();
+        // Get team agent IDs for owner selection in detail screen
+        const teamAgentIds = ctx.team?.getAgentIds() ?? [];
+        const backlogOverlay = new BacklogOverlayV2(undefined, teamAgentIds);
         const result = await ctx.ui.showOverlay(backlogOverlay);
         if (result?.modified) {
             ctx.ui.print({ type: 'success', message: 'Backlog updated.' });
@@ -107,9 +198,42 @@ export const backlogCommand = {
 export const workflowCommand = {
     name: 'workflow',
     description: 'View project workflow dashboard',
+    details: 'Displays the current project workflow status, progress through phases (init → design → backlog → scaffold → build), and recommended next actions. Helps you understand where you are in the development process.',
+    examples: [{ code: '/workflow' }],
+    interactions: [
+        '↑/↓ to navigate actions',
+        'Enter to run selected action',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
+        // Track project ID before overlay (for session switch handling)
+        const oldProjectId = getCurrentProjectIdForTracking();
         const workflowOverlay = new WorkflowOverlayV2();
         const result = await ctx.ui.showOverlay(workflowOverlay);
+        // Handle project switch if it occurred (includes team switching)
+        const switchResult = await handleProjectSwitch(oldProjectId, ctx.agent ?? null, ctx.team && ctx.agentFactory ? {
+            team: ctx.team,
+            agentFactory: ctx.agentFactory,
+        } : undefined);
+        if (switchResult?.switched) {
+            // Update the team if a new one was created/loaded
+            if (switchResult.newTeam && ctx.setTeam) {
+                ctx.setTeam(switchResult.newTeam);
+                // Update footer with new active agent
+                const active = switchResult.newTeam.getActive();
+                ctx.ui.setActiveTeamAgent({
+                    id: active.id,
+                    displayName: active.displayName,
+                    mascot: active.mascot,
+                });
+            }
+            if (switchResult.sessionRestored) {
+                ctx.ui.print({ type: 'info', message: `Session restored (${String(switchResult.messageCount)} messages).` });
+            }
+            else {
+                ctx.ui.print({ type: 'info', message: 'Started fresh session for this project.' });
+            }
+        }
         // Handle workflow result - execute command if returned
         if (result?.command) {
             // Strip leading slash and execute the command
@@ -127,6 +251,16 @@ export const workflowCommand = {
 export const anchorsCommand = {
     name: 'anchors',
     description: 'View and manage anchors (persistent context)',
+    details: 'Anchors are critical pieces of information that survive context compaction. They are always included at the top of the context window. Manage both global anchors and project-specific anchors.',
+    examples: [{ code: '/anchors' }],
+    interactions: [
+        '↑/↓ to navigate anchors',
+        '[a] Add new anchor',
+        '[e] or Enter to edit',
+        '[d] to delete',
+        '[r] to refresh',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
         const anchorsOverlay = new AnchorsOverlayV2();
         const result = await ctx.ui.showOverlay(anchorsOverlay);
@@ -142,6 +276,8 @@ export const anchorsCommand = {
 export const designCommand = {
     name: 'design',
     description: 'Agent-driven requirements gathering',
+    details: 'Comprehensive requirements gathering workflow. The agent guides you through vision, features, and technical context phases, then creates a PRD and populates the backlog with 5-15 items. Best used after /new.',
+    examples: [{ code: '/design' }],
     async execute(_args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -217,6 +353,8 @@ Please start by using todo_write to track the design phases, then begin with Pha
 export const sketchCommand = {
     name: 'sketch',
     description: 'Quick 6-question project outline',
+    details: 'Lightweight alternative to /design. Asks 6 quick questions and creates 3-8 backlog items. Good for small projects or when you want to get started quickly.',
+    examples: [{ code: '/sketch' }],
     execute(_args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -263,6 +401,11 @@ Please start by asking me about the type of application I'm building using the a
 export const refineCommand = {
     name: 'refine',
     description: 'Iterative refinement of requirements',
+    details: 'Iteratively refine backlog items. Can focus on a specific item or let the agent suggest what to refine. Useful for breaking down large items or adding acceptance criteria.',
+    examples: [
+        { code: '/refine', description: 'Agent picks item to refine' },
+        { code: '/refine REQ-003', description: 'Refine specific item' },
+    ],
     async execute(args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -353,7 +496,13 @@ ${agentInstructions}`;
 // =============================================================================
 export const buildCommand = {
     name: 'build',
-    description: 'Build a backlog item',
+    description: 'Implement a backlog item',
+    details: 'Picks the highest priority backlog item (or a specific one) and guides the agent through implementing it. Includes planning, coding, testing, and committing. Auto-detects if project scaffold is needed first.',
+    examples: [
+        { code: '/build', description: 'Pick highest priority item' },
+        { code: '/build REQ-003', description: 'Build specific item' },
+        { code: '/build scaffold', description: 'Create project structure first' },
+    ],
     async execute(args, ctx) {
         const argTrimmed = args.trim();
         // Handle `/build scaffold` - redirect to scaffold command
@@ -499,7 +648,12 @@ Please start by:
 // =============================================================================
 export const noteCommand = {
     name: 'note',
-    description: 'Create a session note',
+    description: 'Create a session note capturing work done',
+    details: 'Creates a structured markdown note summarizing the current session including changes made, decisions, blockers, and next steps. Optionally provide a title.',
+    examples: [
+        { code: '/note', description: 'Auto-generated title' },
+        { code: '/note "Fixed auth bug"', description: 'Custom title' },
+    ],
     execute(args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -551,7 +705,13 @@ Review the conversation context to understand what was accomplished, then create
 // =============================================================================
 export const prdCommand = {
     name: 'prd',
-    description: 'Update the Product Requirements Document',
+    description: 'Amend or enhance the Product Requirements Document',
+    details: 'Update or refine the PRD created during /design. The agent reads the existing PRD and guides you through updating specific sections.',
+    examples: [
+        { code: '/prd', description: 'Interactive section selection' },
+        { code: '/prd vision', description: 'Update vision section' },
+        { code: '/prd scope', description: 'Update scope section' },
+    ],
     execute(args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -585,7 +745,7 @@ ${prdPrompt}
 
 ${sectionInstruction}
 
-Start by reading the existing PRD.md file to understand current state.`;
+Start by reading the existing PRD from the database using project_document_get({ doc_type: "prd" }). If no document exists yet, create a new one.`;
         // Queue message for agent
         ctx.queueAgentMessage({
             message: fullMessage,
@@ -601,7 +761,9 @@ Start by reading the existing PRD.md file to understand current state.`;
 // =============================================================================
 export const scaffoldCommand = {
     name: 'scaffold',
-    description: 'Create project scaffold/foundation',
+    description: 'Create project foundation/structure',
+    details: 'Creates the base project structure (folders, config files, dependencies) based on tech stack from COMPILR.md. Use this before implementing features if starting from scratch. Alias for /build scaffold.',
+    examples: [{ code: '/scaffold' }],
     async execute(_args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -692,7 +854,18 @@ Please start by reading the project documents from the database using project_do
 // =============================================================================
 export const archCommand = {
     name: 'arch',
-    description: 'Create architecture documentation',
+    description: 'Create architecture documentation (ADRs, diagrams, etc.)',
+    details: 'Guides you through creating architecture documentation. Choose from ADRs (Architecture Decision Records), system diagrams, data models, or API designs. The agent asks questions and generates properly formatted documentation.',
+    examples: [
+        { code: '/arch', description: 'Interactive type selection' },
+        { code: '/arch decision', description: 'Create ADR directly' },
+        { code: '/arch diagram', description: 'Create system diagram' },
+    ],
+    interactions: [
+        '↑/↓ or 1-5 to select type',
+        'Enter to confirm',
+        'Esc to cancel',
+    ],
     async execute(_args, ctx) {
         // Check if a project is set (use database, not filesystem)
         const currentProject = getCurrentProject();
@@ -755,7 +928,17 @@ Please start by using project_document_list to find any existing PRD, and workit
 // =============================================================================
 export const docsCommand = {
     name: 'docs',
-    description: 'View project documents (PRD, architecture, design, notes)',
+    description: 'View project documents (PRD, architecture, etc.)',
+    details: 'Opens an overlay to browse and read documents stored in the database for the active project. Documents are created by /design, /arch, and other workflow commands.',
+    examples: [
+        { code: '/docs', description: 'List all documents' },
+    ],
+    interactions: [
+        '↑/↓ or j/k to navigate',
+        'Enter to view document',
+        '↑/↓ to scroll content',
+        'Esc to go back or close',
+    ],
     async execute(_args, ctx) {
         // Loop: show list → detail → back to list (until user cancels list or Ctrl+C from detail)
         let showList = true;
@@ -783,10 +966,48 @@ export const docsCommand = {
 // =============================================================================
 export const projectsCommand = {
     name: 'projects',
-    description: 'View and manage all projects',
+    description: 'View and manage projects',
+    details: 'Opens an interactive overlay to browse, filter, and manage projects tracked in the database. You can view details, open projects, archive, restore, or delete them.',
+    examples: [{ code: '/projects' }],
+    interactions: [
+        'Tab cycles: All → Active → Paused → Completed → Archived',
+        '↑/↓ or j/k to navigate',
+        'Enter to view details and actions',
+        'x to archive/restore project',
+        'd to delete project',
+        'a to show/hide archived',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
+        // Track project ID before overlay (for session switch handling)
+        const oldProjectId = getCurrentProjectIdForTracking();
         const projectsOverlay = new ProjectsOverlayV2();
         await ctx.ui.showOverlay(projectsOverlay);
+        // Handle project switch if it occurred (includes team switching)
+        const switchResult = await handleProjectSwitch(oldProjectId, ctx.agent ?? null, ctx.team && ctx.agentFactory ? {
+            team: ctx.team,
+            agentFactory: ctx.agentFactory,
+        } : undefined);
+        if (switchResult?.switched) {
+            const current = getCurrentProject();
+            // Update the team if a new one was created/loaded
+            if (switchResult.newTeam && ctx.setTeam) {
+                ctx.setTeam(switchResult.newTeam);
+                // Update footer with new active agent
+                const active = switchResult.newTeam.getActive();
+                ctx.ui.setActiveTeamAgent({
+                    id: active.id,
+                    displayName: active.displayName,
+                    mascot: active.mascot,
+                });
+            }
+            if (switchResult.sessionRestored) {
+                ctx.ui.print({ type: 'success', message: `Switched to "${current?.displayName ?? 'project'}" - session restored (${String(switchResult.messageCount)} messages).` });
+            }
+            else {
+                ctx.ui.print({ type: 'success', message: `Switched to "${current?.displayName ?? 'project'}" - fresh session.` });
+            }
+        }
         // Sync footer with current project (may have changed during overlay)
         syncFooterWithCurrentProject(ctx);
         return true;