@compilr-dev/cli 0.5.0 → 0.5.2

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 { projectRepository, workItemRepository } from '../../db/repositories/index.js';
+import { BacklogOverlayV2, WorkflowOverlayV2, DocsOverlayV2, DocumentDetailOverlayV2, AnchorsOverlayV2, ProjectsOverlayV2, NewProjectOverlayV2, OnboardingWizardOverlayV2, KeysOverlayV2, ArchTypeOverlayV2, ModelWarningOverlayV2 } from '../../ui/overlay/index.js';
+import { projectRepository, workItemRepository, documentRepository } 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: 'Smart project scaffolding. If an Application Model exists, generates a complete app via the factory. If the PRD mentions entities, offers to build a model first. Otherwise falls back to manual scaffolding.',
+    examples: [{ code: '/scaffold' }],
     async execute(_args, ctx) {
         // Check if a project is set
         const currentProject = getCurrentProject();
@@ -645,14 +807,53 @@ export const scaffoldCommand = {
                     break;
             }
         }
-        // Get scaffold skill prompt and replace path placeholder
-        let scaffoldPrompt = getSkillPrompt('scaffold');
+        // Check if an Application Model exists for this project
+        const appModelDoc = documentRepository.getByType(currentProject.id, 'app-model');
+        const hasAppModel = appModelDoc !== null;
+        let modelEntityCount = 0;
+        if (appModelDoc) {
+            try {
+                const parsed = JSON.parse(appModelDoc.content);
+                modelEntityCount = parsed.entities?.length ?? 0;
+            }
+            catch { /* invalid JSON — treat as no model */ }
+        }
+        // Check PRD for entity patterns (only if no model yet)
+        let prdMentionsEntities = false;
+        if (!hasAppModel) {
+            const prdDoc = documentRepository.getByType(currentProject.id, 'prd');
+            if (prdDoc) {
+                const lower = prdDoc.content.toLowerCase();
+                prdMentionsEntities = ['manage', 'track', 'crud', 'entities', 'database', 'table', 'records', 'list of', 'collection of']
+                    .some(p => lower.includes(p));
+            }
+        }
+        // Choose skill: factory-scaffold if model exists or PRD has entities, else manual scaffold
+        let skillName;
+        let factoryContext = '';
+        if (hasAppModel && modelEntityCount > 0) {
+            skillName = 'factory-scaffold';
+            factoryContext = `\n## FACTORY CONTEXT\nAn Application Model exists with ${String(modelEntityCount)} entities. Use factory tools to scaffold from this model.\nIMPORTANT: Pass output_dir: "${currentProject.path}" to factory_scaffold.\n`;
+            ctx.ui.print({ type: 'info', message: `Application Model found (${String(modelEntityCount)} entities). Using factory generation.` });
+        }
+        else if (prdMentionsEntities) {
+            skillName = 'factory-scaffold';
+            factoryContext = `\n## FACTORY CONTEXT\nNo Application Model yet, but the PRD mentions entity patterns. Build the model first, then generate.\nIMPORTANT: Pass output_dir: "${currentProject.path}" to factory_scaffold.\n`;
+            ctx.ui.print({ type: 'info', message: 'Entity patterns detected in PRD. Using factory-assisted generation.' });
+        }
+        else {
+            skillName = 'scaffold';
+        }
+        // Get skill prompt and replace path placeholder
+        let scaffoldPrompt = getSkillPrompt(skillName);
         if (!scaffoldPrompt) {
-            ctx.ui.print({ type: 'error', message: 'Scaffold skill not found.' });
+            ctx.ui.print({ type: 'error', message: `${skillName} skill not found.` });
             return true;
         }
-        // Replace {{projectPath}} placeholder with actual path
         scaffoldPrompt = scaffoldPrompt.replace(/\{\{projectPath\}\}/g, currentProject.path);
+        const closingInstruction = skillName === 'factory-scaffold'
+            ? 'Start by checking the Application Model with app_model_get. If no model exists, read the PRD with project_document_get and build the model incrementally using app_model_update. Then generate with factory_scaffold.'
+            : 'Start by reading the project documents from the database using project_document_list and project_document_get. Then create a plan with todo_write before generating files.';
         // Build full message for agent with explicit project path context
         const fullMessage = `I want to create the project scaffold/foundation.
 
@@ -660,7 +861,7 @@ export const scaffoldCommand = {
 - Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
 - **Project Directory: ${currentProject.path}**
 - ALL files MUST be created in this directory
-
+${factoryContext}
 ## TOOL RESTRICTIONS (CRITICAL)
 - Do NOT use detect_project or find_project_root
 - Do NOT scan filesystem to detect project type
@@ -678,11 +879,15 @@ When creating files:
 
 ${scaffoldPrompt}
 
-Please start by reading the project documents from the database using project_document_list and project_document_get. Then create a plan with todo_write before generating files.`;
+${closingInstruction}`;
         // Queue message for agent
         ctx.queueAgentMessage({
             message: fullMessage,
-            displayMessage: 'Create project scaffold.',
+            displayMessage: hasAppModel
+                ? 'Generate project from Application Model.'
+                : prdMentionsEntities
+                    ? 'Build model and generate project.'
+                    : 'Create project scaffold.',
         });
         return true;
     },
@@ -692,7 +897,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 +971,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 +1009,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;

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

@@ -0,0 +1,11 @@
+/**
+ * Reset Command for REPL V2
+ *
+ * Clears the conversation history while staying in the current project.
+ * Options:
+ * - Reset & reload context: Clear messages, refresh COMPILR.md
+ * - Reset only: Clear messages, keep current context
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const resetCommand: CommandHandlerV2;
+export declare const resetCommands: CommandHandlerV2[];

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

@@ -0,0 +1,118 @@
+/**
+ * Reset Command for REPL V2
+ *
+ * Clears the conversation history while staying in the current project.
+ * Options:
+ * - Reset & reload context: Clear messages, refresh COMPILR.md
+ * - Reset only: Clear messages, keep current context
+ */
+import { ResetOverlayV2, } from '../../ui/overlay/impl/reset-overlay-v2.js';
+import { getCurrentProject } from '../../tools/project-db.js';
+import { getProjectSessionManager } from '../../session/index.js';
+import { archiveCurrentSession } from './session.js';
+// =============================================================================
+// Reset Command
+// =============================================================================
+export const resetCommand = {
+    name: 'reset',
+    aliases: ['clear-context'],
+    description: 'Clear conversation and optionally reload project context',
+    details: 'Starts a fresh conversation within the current project. Previous session is archived to history. Use this when you want to start over without switching projects.',
+    examples: [{ code: '/reset' }],
+    interactions: [
+        'j/k to navigate options',
+        'Enter to select',
+        'Esc to cancel',
+    ],
+    async execute(_args, ctx) {
+        if (!ctx.agent) {
+            ctx.ui.print({ type: 'error', message: 'No agent connected. Cannot reset.' });
+            return true;
+        }
+        // Get current project info
+        const currentProject = getCurrentProject();
+        const projectName = currentProject?.displayName ?? 'Global';
+        // Get current session stats
+        const history = ctx.agent.getHistory();
+        const messageCount = history.length;
+        const contextManager = ctx.agent.getContextManager();
+        const tokenCount = contextManager?.getTokenCount();
+        // Show reset overlay
+        const overlay = new ResetOverlayV2({
+            projectName,
+            messageCount,
+            tokenCount,
+        });
+        const result = await ctx.ui.showOverlay(overlay);
+        if (!result || result.option === 'cancel') {
+            ctx.ui.print({ type: 'info', message: 'Reset cancelled.' });
+            return true;
+        }
+        const projectId = currentProject?.id ?? null;
+        // Handle delete-history option separately
+        if (result.option === 'delete-history') {
+            const psm = getProjectSessionManager();
+            try {
+                const deletedCount = await psm.deleteProjectHistory(projectId, false);
+                if (deletedCount > 0) {
+                    ctx.ui.print({ type: 'success', message: `Deleted ${String(deletedCount)} archived session${deletedCount !== 1 ? 's' : ''}.` });
+                }
+                else {
+                    ctx.ui.print({ type: 'info', message: 'No archived sessions to delete.' });
+                }
+            }
+            catch {
+                ctx.ui.print({ type: 'error', message: 'Failed to delete session history.' });
+            }
+            return true;
+        }
+        // Archive current session before resetting
+        try {
+            await archiveCurrentSession();
+            ctx.ui.print({ type: 'info', message: 'Previous session archived.' });
+        }
+        catch {
+            // Silently continue - archiving is best-effort
+        }
+        // Clear the agent history - both default agent and all team agents
+        ctx.agent.clearHistory();
+        // Clear restored history (Ctrl+R view)
+        ctx.ui.setRestoredHistory([]);
+        // If we have a team, clear all team agent histories too
+        if (ctx.team) {
+            ctx.team.clearAllHistories();
+            ctx.ui.print({ type: 'info', message: `Team context cleared (${String(ctx.team.size)} agents)` });
+        }
+        // Clear all message queues
+        if (ctx.clearAllQueues) {
+            const clearedCount = ctx.clearAllQueues();
+            if (clearedCount > 0) {
+                ctx.ui.print({ type: 'info', message: `${String(clearedCount)} queued message${clearedCount !== 1 ? 's' : ''} cleared` });
+            }
+        }
+        if (result.option === 'reset-reload') {
+            // Reset & reload context - need to refresh project context
+            // This is handled by creating a new agent with fresh context
+            // For now, we just clear history. Full context refresh requires
+            // recreating the agent (to be implemented in Phase 2 integration)
+            ctx.ui.print({ type: 'success', message: 'Conversation cleared. Project context refreshed.' });
+            ctx.ui.print({ type: 'info', message: 'Note: Full context reload requires CLI restart for now.' });
+        }
+        else {
+            // Reset only - just clear messages
+            ctx.ui.print({ type: 'success', message: 'Conversation cleared. Context preserved.' });
+        }
+        // Save the fresh session state
+        const psm = getProjectSessionManager();
+        const state = ctx.agent.serialize();
+        await psm.saveProjectSession(projectId, currentProject?.displayName ?? null, state);
+        ctx.ui.print({ type: 'info', message: 'Ready for a fresh conversation.' });
+        return true;
+    },
+};
+// =============================================================================
+// Export
+// =============================================================================
+export const resetCommands = [
+    resetCommand,
+];