@mod-computer/cli 0.1.1 → 0.2.1

package/dist/commands/init.js

@@ -1,20 +1,14 @@
 #!/usr/bin/env node
-// glassware[type=implementation, id=cli-init-command, requirements=req-cli-init-ux-1,req-cli-init-ux-2,req-cli-init-ux-3,req-cli-init-ux-4,req-cli-init-ux-5a,req-cli-init-ux-5b,req-cli-init-ux-6,req-cli-init-ux-7,req-cli-init-app-1,req-cli-init-app-5]
-import fs from 'fs';
+// glassware[type="implementation", id="cli-init-command--da781f68", requirements="requirement-cli-init-ux-1--1e5666e7,requirement-cli-init-ux-2--b69b045f,requirement-cli-init-ux-3--3dde4846,requirement-cli-init-ux-4--140d9249,requirement-cli-init-ux-5a--09a5bdab,requirement-cli-init-ux-5b--4cb7bb13,requirement-cli-init-ux-6--1627332e,requirement-cli-init-ux-7--97fe5eff,requirement-cli-init-app-1--1c2b11b4,requirement-cli-init-app-5--74a2ea93"]
 import path from 'path';
-import { fileURLToPath } from 'url';
-import { createModWorkspace } from '@mod/mod-core';
+import fs from 'fs';
+import { createModWorkspace, createModUser, setTextContent, detectMimeType, mimeTypeToCanvasType } from '@mod/mod-core';
 import { readConfig, readWorkspaceConnection, writeWorkspaceConnection, ensureModDir, } from '../lib/storage.js';
 import { select, input, validateWorkspaceName } from '../lib/prompts.js';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+import { addWorkspaceToSharePolicy, addFilesToSharePolicy } from '../daemon/share-policy.js';
+import { FileImportService } from '../services/file-import-service.js';
 export async function initCommand(args, repo) {
-    const subcommand = args[0];
     const isForce = args.includes('--force');
-    if (subcommand === 'list' || args.includes('--list')) {
-        await listAvailableCommands();
-        process.exit(0);
-    }
     try {
         ensureModDir();
         // Check for existing workspace connection
@@ -24,18 +18,33 @@ export async function initCommand(args, repo) {
             console.log('Already initialized');
             console.log(`Workspace: ${existingConnection.workspaceName}`);
             console.log('');
-            console.log('Run `mod sync start` to begin syncing');
-            console.log('');
-            console.log("To connect to a different workspace, run `mod init --force`");
-            process.exit(0);
-        }
-        // Install Claude commands
-        await ensureClaudeCommandsDirectory();
-        const availableCommands = await discoverAvailableCommands();
-        const installedCommands = await getInstalledCommands();
-        const commandsToInstall = await determineCommandsToInstall(availableCommands, installedCommands, isForce);
-        if (commandsToInstall.length > 0) {
-            await installCommands(commandsToInstall);
+            // Offer to resume import if there are files not yet synced
+            const resumeChoice = await select('What would you like to do?', [
+                { label: 'Resume file import (if interrupted)', value: 'resume' },
+                { label: 'Start syncing', value: 'sync' },
+                { label: 'Reinitialize with different workspace', value: 'force' },
+            ]);
+            if (resumeChoice === 'resume') {
+                console.log('Checking for files to import...');
+                try {
+                    await importDirectoryFiles(repo, { id: existingConnection.workspaceId });
+                    console.log('Resume complete');
+                }
+                catch (error) {
+                    console.error('Resume failed:', error instanceof Error ? error.message : error);
+                    process.exit(1);
+                }
+            }
+            else if (resumeChoice === 'sync') {
+                console.log('Run `mod sync start` to begin syncing');
+            }
+            else if (resumeChoice === 'force') {
+                console.log('Reinitializing...');
+                // Continue with force init below
+            }
+            if (resumeChoice !== 'force') {
+                process.exit(0);
+            }
         }
         // Check auth state
         const config = readConfig();
@@ -47,26 +56,64 @@ export async function initCommand(args, repo) {
         else {
             workspaceConnection = await handleUnauthenticatedInit(repo);
         }
-        // Save workspace connection
+        // Workspace connection already saved during creation
+        // Update last synced time
+        workspaceConnection.lastSyncedAt = new Date().toISOString();
         writeWorkspaceConnection(currentDir, workspaceConnection);
+        // Install the /mod agent skill for spec-driven development
+        installModSkill();
+        console.log('Installed /mod skill to .claude/skills/mod/');
         // Display success message
-        displayInitializationSuccess(commandsToInstall, workspaceConnection, isAuthenticated);
+        displayInitializationSuccess(workspaceConnection, isAuthenticated);
         process.exit(0);
     }
     catch (error) {
-        handleInstallationError(error);
+        console.error('Initialization failed:', error.message);
+        process.exit(1);
     }
 }
+// glassware[type="implementation", id="impl-init-authenticated--1fe6c419", requirements="requirement-cli-init-app-2--51f0306f,requirement-cli-init-app-3--76844b98,requirement-cli-init-qual-1--ca672702"]
 async function handleAuthenticatedInit(repo, email) {
     console.log(`Signed in as ${email}`);
-    // Get workspace list
-    const modWorkspace = createModWorkspace(repo);
+    // Get workspace list from user document (app-2)
+    const config = readConfig();
     let workspaces = [];
     try {
-        const handles = await modWorkspace.listWorkspaces();
-        workspaces = handles.map((h) => ({ id: h.id, name: h.name }));
+        const userDocId = config.auth?.userDocId;
+        if (!userDocId) {
+            console.warn('User document not found. Creating local workspace.');
+        }
+        else {
+            // Fetch workspaces from user document (app-3)
+            const userHandle = await repo.find(userDocId);
+            await userHandle.whenReady();
+            const userDoc = userHandle.doc();
+            if (userDoc) {
+                const workspaceIds = userDoc.workspaceIds || [];
+                // Load workspace metadata for each workspace
+                for (const wsId of workspaceIds) {
+                    try {
+                        const wsHandle = await repo.find(wsId);
+                        await wsHandle.whenReady();
+                        const ws = wsHandle.doc();
+                        workspaces.push({
+                            id: wsId,
+                            name: ws?.title || ws?.name || 'Untitled',
+                        });
+                    }
+                    catch {
+                        // Workspace might not be available, add with just ID
+                        workspaces.push({
+                            id: wsId,
+                            name: `Workspace ${String(wsId).slice(0, 8)}`,
+                        });
+                    }
+                }
+            }
+        }
     }
     catch (error) {
+        // Handle network errors gracefully (qual-1)
         console.warn('Could not load cloud workspaces. Creating local workspace.');
     }
     // Build options
@@ -84,13 +131,32 @@ async function handleAuthenticatedInit(repo, email) {
     if (choice.type === 'create') {
         return await createNewWorkspace(repo);
     }
-    return {
-        path: process.cwd(),
+    // Add existing workspace to share policy so it can sync
+    addWorkspaceToSharePolicy(choice.id);
+    // Save workspace connection immediately
+    const currentDir = process.cwd();
+    const workspaceConnection = {
+        path: currentDir,
         workspaceId: choice.id,
         workspaceName: choice.name,
         connectedAt: new Date().toISOString(),
         lastSyncedAt: new Date().toISOString(),
     };
+    writeWorkspaceConnection(currentDir, workspaceConnection);
+    console.log('Workspace connection saved');
+    // Register existing workspace on UserDoc (in case it wasn't registered before)
+    if (config.auth?.userDocId) {
+        try {
+            const modUser = createModUser(repo);
+            await modUser.addWorkspace(config.auth.userDocId, choice.id);
+        }
+        catch (error) {
+            // Silently ignore - workspace is already connected
+        }
+    }
+    // Import files from directory if this is a new connection
+    await importDirectoryFiles(repo, { id: choice.id });
+    return workspaceConnection;
 }
 async function handleUnauthenticatedInit(repo) {
     const choice = await select('Select option:', [
@@ -113,231 +179,419 @@ async function handleUnauthenticatedInit(repo) {
     }
     return await createNewWorkspace(repo);
 }
+// glassware[type="implementation", id="impl-init-create-workspace--4ff92c7c", requirements="requirement-cli-init-app-4--761a37a6,requirement-cli-init-int-1--e3f9f2b6"]
 async function createNewWorkspace(repo) {
     const currentDirName = path.basename(process.cwd());
+    const currentDir = process.cwd();
     const defaultName = currentDirName.charAt(0).toUpperCase() + currentDirName.slice(1);
     const name = await input('Workspace name', {
         default: defaultName,
         validate: validateWorkspaceName,
     });
     console.log('Creating workspace...');
+    // Create new workspace - works with or without auth (app-4)
     const modWorkspace = createModWorkspace(repo);
+    // No branching by default (enableBranching: true to opt-in)
+    // The CLI stores workspace IDs in its local storage instead
     const workspace = await modWorkspace.createWorkspace({ name });
-    return {
-        path: process.cwd(),
+    // Add workspace to share policy so it can sync
+    addWorkspaceToSharePolicy(workspace.id);
+    // CRITICAL: Save workspace connection immediately before import
+    // This allows resuming if import is interrupted
+    const workspaceConnection = {
+        path: currentDir,
         workspaceId: workspace.id,
         workspaceName: workspace.name,
         connectedAt: new Date().toISOString(),
         lastSyncedAt: new Date().toISOString(),
     };
-}
-function displayInitializationSuccess(commands, connection, isAuthenticated) {
-    console.log('');
-    console.log('Initialized Mod in ' + connection.path);
-    console.log(`Workspace: ${connection.workspaceName}`);
-    if (commands.length > 0) {
-        console.log('');
-        console.log(`Installed ${commands.length} Claude command(s)`);
-    }
-    console.log('');
-    if (isAuthenticated) {
-        console.log('Run `mod sync start` to begin syncing');
-    }
-    else {
-        console.log('Run `mod auth login` to enable sync with collaborators');
-    }
-}
-// ============ Claude Commands Installation ============
-async function ensureClaudeCommandsDirectory() {
-    const claudeDir = path.join(process.cwd(), '.claude');
-    const commandsDir = path.join(claudeDir, 'commands');
-    try {
-        if (!fs.existsSync(claudeDir)) {
-            fs.mkdirSync(claudeDir, { recursive: true, mode: 0o755 });
-        }
-        if (!fs.existsSync(commandsDir)) {
-            fs.mkdirSync(commandsDir, { recursive: true, mode: 0o755 });
-        }
-    }
-    catch (error) {
-        throw new Error(`Failed to create .claude/commands directory: ${error.message}`);
-    }
-}
-async function discoverAvailableCommands() {
-    const packageRoot = path.resolve(__dirname, '../..');
-    const commandsSourceDir = path.join(packageRoot, 'commands');
-    if (!fs.existsSync(commandsSourceDir)) {
-        return [];
-    }
-    const commands = [];
-    const files = fs.readdirSync(commandsSourceDir).filter((f) => f.endsWith('.md'));
-    for (const filename of files) {
-        const filePath = path.join(commandsSourceDir, filename);
-        const content = fs.readFileSync(filePath, 'utf8');
-        const metadata = parseFrontmatter(content);
-        commands.push({
-            filename,
-            path: filePath,
-            metadata,
-            content,
-        });
-    }
-    return commands;
-}
-async function getInstalledCommands() {
-    const commandsDir = path.join(process.cwd(), '.claude', 'commands');
-    const installed = new Map();
-    if (!fs.existsSync(commandsDir)) {
-        return installed;
-    }
-    const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'));
-    for (const filename of files) {
-        const filePath = path.join(commandsDir, filename);
+    writeWorkspaceConnection(currentDir, workspaceConnection);
+    console.log('Workspace connection saved');
+    // Wait for workspace document to sync to server
+    console.log('Syncing workspace...');
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    // Register workspace on UserDoc for cross-device discovery (do this before import)
+    const config = readConfig();
+    if (config.auth?.userDocId) {
         try {
-            const content = fs.readFileSync(filePath, 'utf8');
-            const metadata = parseFrontmatter(content);
-            installed.set(filename, metadata);
+            const modUser = createModUser(repo);
+            await modUser.addWorkspace(config.auth.userDocId, workspace.id);
+            // Wait for user doc to sync
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            console.log('Workspace registered for sync');
         }
         catch (error) {
-            console.warn(`Could not read metadata from ${filename}: ${error.message}`);
-        }
-    }
-    return installed;
-}
-function parseFrontmatter(content) {
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!frontmatterMatch) {
-        return {
-            version: '0.0.0',
-            updated: '1970-01-01',
-            checksum: '',
-            description: undefined,
-        };
-    }
-    const frontmatterText = frontmatterMatch[1];
-    const metadata = {};
-    const lines = frontmatterText.split('\n');
-    for (const line of lines) {
-        const match = line.match(/^(\w+):\s*(.+)$/);
-        if (match) {
-            const [, key, value] = match;
-            metadata[key] = value
-                .trim()
-                .replace(/^["']|["']$/g, '');
-        }
-    }
-    return {
-        version: metadata.version || '1.0.0',
-        updated: metadata.updated || new Date().toISOString(),
-        checksum: metadata.checksum || '',
-        description: metadata.description,
-    };
-}
-async function determineCommandsToInstall(available, installed, force) {
-    const toInstall = [];
-    for (const command of available) {
-        const installedMetadata = installed.get(command.filename);
-        if (force || !installedMetadata) {
-            toInstall.push(command);
-            continue;
-        }
-        if (compareVersions(command.metadata.version, installedMetadata.version) > 0) {
-            toInstall.push(command);
+            // Don't fail the init if registration fails - workspace still created
+            console.warn('Note: Could not register workspace for cross-device sync');
         }
     }
-    return toInstall;
+    // Import existing files from the directory
+    await importDirectoryFiles(repo, workspace);
+    console.log('Workspace synced');
+    return workspaceConnection;
 }
-function compareVersions(v1, v2) {
-    const parts1 = v1.split('.').map((n) => parseInt(n, 10));
-    const parts2 = v2.split('.').map((n) => parseInt(n, 10));
-    for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
-        const part1 = parts1[i] || 0;
-        const part2 = parts2[i] || 0;
-        if (part1 > part2)
-            return 1;
-        if (part1 < part2)
-            return -1;
+// glassware[type="implementation", id="impl-cli-init-import--74b5c00f", requirements="requirement-cli-add-init-integration--e953a345"]
+// TODO: Migrate to use AddService instead of FileImportService for consistency with `mod add`
+async function importDirectoryFiles(repo, workspace) {
+    const currentDir = process.cwd();
+    // Check if directory has any files to import
+    const entries = fs.readdirSync(currentDir);
+    const hasFiles = entries.some(entry => {
+        const fullPath = path.join(currentDir, entry);
+        const stats = fs.statSync(fullPath);
+        return stats.isFile() && entry !== '.modconfig';
+    });
+    if (!hasFiles) {
+        console.log('No files found to import');
+        return;
     }
-    return 0;
-}
-async function installCommands(commands) {
-    const commandsDir = path.join(process.cwd(), '.claude', 'commands');
-    const tempFiles = [];
+    console.log('Importing files from directory...');
+    const importService = new FileImportService(repo);
     try {
-        for (const command of commands) {
-            const tempPath = path.join(commandsDir, `${command.filename}.tmp`);
-            const contentWithChecksum = await updateChecksumInContent(command.content);
-            fs.writeFileSync(tempPath, contentWithChecksum, 'utf8');
-            tempFiles.push(tempPath);
+        // Scan for files to import
+        const preview = await importService.previewImport({
+            workingDirectory: currentDir,
+            verbose: false
+        });
+        if (preview.filteredFiles.length === 0) {
+            console.log('No trackable files found to import');
+            return;
         }
-        for (let i = 0; i < commands.length; i++) {
-            const tempPath = tempFiles[i];
-            const finalPath = path.join(commandsDir, commands[i].filename);
-            fs.renameSync(tempPath, finalPath);
+        console.log(`Found ${preview.filteredFiles.length} files to scan`);
+        // Import the files with batching to avoid memory issues
+        const modWorkspace = createModWorkspace(repo);
+        const workspaceHandle = await modWorkspace.openWorkspace(workspace.id);
+        // Query existing files to enable resume capability
+        console.log('Checking for existing files...');
+        const existingFiles = await workspaceHandle.file.list();
+        const existingPaths = new Set(existingFiles
+            .map(f => f.metadata?.typeData?.path || f.metadata?.typeData?.relativePath)
+            .filter(Boolean));
+        // Filter out files that already exist
+        const filesToImport = preview.filteredFiles.filter(filePath => {
+            const relativePath = path.relative(currentDir, filePath);
+            return !existingPaths.has(relativePath);
+        });
+        if (filesToImport.length === 0) {
+            console.log('All files already imported, nothing to do');
+            return;
         }
-    }
-    catch (error) {
-        cleanup(tempFiles);
-        throw error;
-    }
-}
-async function updateChecksumInContent(content) {
-    const crypto = await import('crypto');
-    const contentHash = crypto
-        .createHash('sha256')
-        .update(content)
-        .digest('hex')
-        .substring(0, 16);
-    const withoutChecksum = content.replace(/^(\s*)checksum:\s*\S*$/gm, '');
-    return withoutChecksum.replace(/^(---\n)([\s\S]*?)(---)/, `$1$2checksum: ${contentHash}\n$3`);
-}
-function cleanup(tempFiles) {
-    for (const file of tempFiles) {
-        try {
-            if (fs.existsSync(file)) {
-                fs.unlinkSync(file);
-            }
+        const skippedCount = preview.filteredFiles.length - filesToImport.length;
+        if (skippedCount > 0) {
+            console.log(`Skipping ${skippedCount} files that already exist`);
         }
-        catch (error) {
-            console.warn(`Could not clean up temporary file ${file}: ${error.message}`);
+        console.log(`Importing ${filesToImport.length} new files`);
+        const importedFileIds = [];
+        let importedCount = 0;
+        const BATCH_SIZE = 20; // Reduced batch size to avoid Automerge concurrency issues
+        // Split files into batches
+        const batches = [];
+        for (let i = 0; i < filesToImport.length; i += BATCH_SIZE) {
+            batches.push(filesToImport.slice(i, i + BATCH_SIZE));
         }
-    }
-}
-async function listAvailableCommands() {
-    console.log('Available Claude Commands:\n');
-    try {
-        const commands = await discoverAvailableCommands();
-        if (commands.length === 0) {
-            console.log('   No commands available');
-            return;
+        // Process each batch
+        for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+            const batch = batches[batchIndex];
+            // Process files sequentially to avoid Automerge concurrency issues
+            // Concurrent modifications cause "recursive use of an object" errors
+            for (const filePath of batch) {
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    const relativePath = path.relative(currentDir, filePath);
+                    const pathParts = relativePath.split(path.sep);
+                    const fileName = pathParts.pop();
+                    // Detect proper mime type instead of hardcoding markdown
+                    const mimeType = detectMimeType(fileName);
+                    const canvasType = mimeTypeToCanvasType(mimeType);
+                    const isCodeFile = canvasType === 'code';
+                    const isTextFile = mimeType.startsWith('text/') ||
+                        mimeType === 'application/json' ||
+                        mimeType === 'application/javascript';
+                    // Create file in workspace
+                    // Code files: Store content directly (no prosemirror formatting)
+                    // Text/markdown files: Create empty first, then apply setTextContent for proper formatting
+                    const fileDoc = await workspaceHandle.file.create({
+                        text: isCodeFile ? content : '',
+                        metadata: {
+                            type: 'text',
+                            path: relativePath,
+                            name: fileName,
+                            mimeType,
+                            createdAt: new Date().toISOString(),
+                            updatedAt: new Date().toISOString(),
+                            createdBy: 'cli'
+                        }
+                    }, {
+                        name: fileName,
+                        mimeType
+                    });
+                    // Apply proper richtext formatting using setTextContent for text/markdown files only
+                    // Code files should NOT use setTextContent - they need plain text for CodeMirror
+                    if (isTextFile && !isCodeFile && content.length > 0) {
+                        await setTextContent(fileDoc, ['text'], content);
+                    }
+                    importedFileIds.push(fileDoc.documentId);
+                    importedCount++;
+                    // Longer delay to ensure Automerge completes save cycle
+                    // The "recursive use" error happens when save is triggered while another save is in progress
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                }
+                catch (error) {
+                    console.warn(`  Failed to import ${filePath}:`, error instanceof Error ? error.message : error);
+                    // On Automerge error, wait longer before continuing
+                    if (error instanceof Error && error.message.includes('recursive')) {
+                        console.warn('  Automerge concurrency detected, waiting 2s...');
+                        await new Promise(resolve => setTimeout(resolve, 2000));
+                    }
+                }
+            }
+            console.log(`  Imported ${importedCount}/${filesToImport.length} files...`);
+            // Trigger garbage collection hint between batches to free memory
+            if (global.gc && batchIndex < batches.length - 1) {
+                global.gc();
+            }
+            // Small delay between batches to allow memory cleanup
+            if (batchIndex < batches.length - 1) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
         }
-        for (const command of commands) {
-            console.log(`   ${command.filename.replace('.md', '')}`);
-            console.log(`   Version: ${command.metadata.version}`);
-            if (command.metadata.description) {
-                console.log(`   Description: ${command.metadata.description}`);
+        // Add imported files to share policy in batches
+        if (importedFileIds.length > 0) {
+            const SHARE_POLICY_BATCH_SIZE = 100;
+            for (let i = 0; i < importedFileIds.length; i += SHARE_POLICY_BATCH_SIZE) {
+                const batch = importedFileIds.slice(i, i + SHARE_POLICY_BATCH_SIZE);
+                addFilesToSharePolicy(batch);
             }
-            console.log();
         }
+        console.log(`✓ Imported ${importedCount} files (${skippedCount} already existed)`);
     }
     catch (error) {
-        console.error('Error listing commands:', error.message);
+        console.warn('Failed to import files:', error instanceof Error ? error.message : error);
+        throw error; // Re-throw so caller knows import failed
     }
 }
-function handleInstallationError(error) {
-    console.error('Initialization failed:');
-    if (error.code === 'EACCES' || error.code === 'EPERM') {
-        console.error('   Permission denied.');
+/**
+ * Install the /mod agent skill to .claude/skills/mod/
+ * This enables coding agents to use spec-driven development workflows
+ */
+function installModSkill() {
+    const currentDir = process.cwd();
+    const skillDir = path.join(currentDir, '.claude', 'skills', 'mod');
+    const referencesDir = path.join(skillDir, 'references');
+    // Create directories if they don't exist
+    if (!fs.existsSync(skillDir)) {
+        fs.mkdirSync(skillDir, { recursive: true });
+    }
+    if (!fs.existsSync(referencesDir)) {
+        fs.mkdirSync(referencesDir, { recursive: true });
     }
-    else if (error.code === 'ENOSPC') {
-        console.error('   Insufficient disk space.');
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+    const commandsMdPath = path.join(referencesDir, 'commands.md');
+    // Only write if files don't exist (don't overwrite user modifications)
+    if (!fs.existsSync(skillMdPath)) {
+        fs.writeFileSync(skillMdPath, SKILL_MD_CONTENT);
+    }
+    if (!fs.existsSync(commandsMdPath)) {
+        fs.writeFileSync(commandsMdPath, COMMANDS_MD_CONTENT);
+    }
+}
+const SKILL_MD_CONTENT = `---
+name: mod
+description: Spec-driven development with traceability. Implements specs, adds traces, verifies coverage. Use when implementing from specifications, adding requirement traceability, or checking trace coverage before merging.
+---
+
+# Mod: Spec-Driven Development
+
+Use this skill when the user asks to implement from specs, add traceability, or verify coverage.
+
+## Triggers
+
+- "implement this spec"
+- "implement specs/*.md"
+- "/mod implement <file>"
+- "add tests for this spec"
+- "check trace coverage"
+
+## Workflow
+
+### 1. Setup (if needed)
+
+Check if workspace exists:
+\`\`\`bash
+mod status
+\`\`\`
+
+If not initialized:
+\`\`\`bash
+mod init
+mod auth login
+\`\`\`
+
+### 2. Read the Spec
+
+Parse the spec file for requirements. Requirements may be marked with glassware annotations or be plain markdown sections.
+
+### 3. Implement with Traces
+
+For each requirement:
+
+1. Write the implementation
+2. Add a trace connecting implementation to requirement:
+\`\`\`bash
+mod trace add <file>:<line> --type=implementation --link=<requirement-id>
+\`\`\`
+
+3. Verify the trace was added:
+\`\`\`bash
+mod trace report <spec-file>
+\`\`\`
+
+### 4. Add Tests with Traces
+
+For each implementation:
+
+1. Write tests
+2. Add traces connecting tests to implementations:
+\`\`\`bash
+mod trace add <test-file>:<line> --type=test --link=<implementation-id>
+\`\`\`
+
+### 5. Verify Coverage
+
+Before completing, always run:
+\`\`\`bash
+mod trace report <spec-file>
+mod trace unmet
+mod trace diff
+\`\`\`
+
+Address any gaps:
+- Unmet requirements -> implement them
+- Untraced files -> add traces or mark as utility
+
+### 6. Final Validation
+
+\`\`\`bash
+mod trace diff && mod trace unmet
+\`\`\`
+
+Only report completion when both commands exit 0 (all files traced, all requirements implemented).
+
+## Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| \`mod init\` | Initialize workspace |
+| \`mod auth login\` | Authenticate |
+| \`mod trace add <file>:<line> --type=<type> [--link=<id>]\` | Add trace |
+| \`mod trace link <source> <target>\` | Link two traces |
+| \`mod trace report <file>\` | Show trace coverage for spec |
+| \`mod trace coverage\` | Workspace-wide stats |
+| \`mod trace unmet\` | Requirements without implementations |
+| \`mod trace diff\` | Untraced files on branch (auto-detects base) |
+
+## Types
+
+- \`requirement\` - Spec requirement
+- \`specification\` - Technical spec detail
+- \`implementation\` - Code that builds
+- \`test\` - Code that verifies
+- \`utility\` - Intentionally untraced helpers
+
+## Important
+
+- Always verify coverage before completing
+- If \`mod trace diff\` or \`mod trace unmet\` fails, address gaps before finishing
+- Use \`mod trace unmet\` to find requirements that still need implementation
+- Mark helper files as \`utility\` type to avoid false positives in diff
+`;
+const COMMANDS_MD_CONTENT = `# Mod CLI Commands Reference
+
+## Authentication
+
+\`\`\`bash
+mod auth login          # OAuth login (opens browser)
+mod auth login --dev    # Dev mode (no OAuth)
+mod auth logout
+mod auth status
+\`\`\`
+
+## Workspace
+
+\`\`\`bash
+mod init                # Initialize workspace in current directory
+mod status              # Show workspace status
+\`\`\`
+
+## Traces
+
+\`\`\`bash
+# Add traces
+mod trace add <file>:<line> --type=<type> ["description"]
+mod trace add <file>:<line> --type=<type> --link=<trace-id>
+
+# Link traces
+mod trace link <source-id> <target-id>
+
+# View traces
+mod trace list                    # All traces
+mod trace list --type=requirement # Filter by type
+mod trace list --file=<path>      # Filter by file
+mod trace get <trace-id>          # Get trace details
+
+# Reports
+mod trace report <file>           # Per-document coverage
+mod trace coverage                # Workspace-wide stats
+
+# Find gaps
+mod trace diff                    # Untraced files on branch (auto-detects base)
+mod trace diff main..HEAD         # Explicit range
+mod trace unmet                   # Requirements without implementations
+\`\`\`
+
+## Trace Types
+
+| Type | Use For |
+|------|---------|
+| \`requirement\` | Specs, user stories, acceptance criteria |
+| \`specification\` | Detailed technical specs |
+| \`implementation\` | Code that builds something |
+| \`test\` | Code that verifies something |
+| \`design\` | Design docs, architecture notes |
+| \`decision\` | ADRs, decision records |
+| \`utility\` | Helpers that don't need tracing |
+
+## Comments
+
+\`\`\`bash
+mod comment add <file>:<line> "text"
+mod comment list [file]
+\`\`\`
+
+## Exit Codes for CI
+
+Commands exit non-zero when issues exist:
+
+| Command | Exit 0 | Exit 1 |
+|---------|--------|--------|
+| \`mod trace diff\` | All changed files traced | Untraced files exist |
+| \`mod trace unmet\` | All requirements implemented | Unmet requirements |
+| \`mod trace report\` | Always (informational) | - |
+
+Pre-merge validation:
+\`\`\`bash
+mod trace diff && mod trace unmet && git push
+\`\`\`
+`;
+function displayInitializationSuccess(connection, isAuthenticated) {
+    console.log('');
+    console.log('Initialized Mod in ' + connection.path);
+    console.log(`Workspace: ${connection.workspaceName}`);
+    console.log('');
+    if (isAuthenticated) {
+        console.log('Run `mod sync start` to begin syncing');
     }
     else {
-        console.error(`   ${error.message}`);
+        console.log('Run `mod auth login` to enable sync with collaborators');
     }
-    console.error('');
-    console.error('Troubleshooting:');
-    console.error('   - Ensure you have write permissions');
-    console.error('   - Try running "mod init --force" to overwrite');
-    process.exit(1);
 }