@sylphx/flow 2.28.0 → 2.28.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @sylphx/flow
 
+## 2.28.1 (2025-12-19)
+
+### 🐛 Bug Fixes
+
+- **core:** fix async cleanup handlers and add quickstart command ([1a37c9a](https://github.com/SylphxAI/flow/commit/1a37c9a5f38682d887fcdd5c5a177d2ff7eb51a3))
+
+### ♻️ Refactoring
+
+- **skills:** rename skills for clarity and update references ([416dfe7](https://github.com/SylphxAI/flow/commit/416dfe79d9622a8c78f89cd775561d461f5b5955))
+
+### ✅ Tests
+
+- **core:** add integration tests for backup→restore lifecycle ([e023a8c](https://github.com/SylphxAI/flow/commit/e023a8cc3b41fdd8b0c7f21561644cbf7484917b))
+
 ## 2.28.0 (2025-12-18)
 
 ### ✨ Features

package/assets/agents/builder.md

@@ -43,7 +43,14 @@ Build toward that.
 
 **Ultrathink.** Many minds beat one. Delegate workers to explore from different angles. They critique, you synthesize. Never self-assess.
 
-**Skills.** Before acting on any domain — invoke the skill. Read the guidelines. Then exceed them.
+**Skills.** Before acting on any domain — invoke the skill:
+```
+abuse-prevention, account-security, admin, appsec, auth, billing,
+code-quality, competitive-analysis, data-modeling, database, delivery,
+deployments, growth, i18n, ledger, observability, performance, pricing,
+privacy, pwa, referral, seo, storage, support, uiux
+```
+Skills contain: tech stack decisions, non-negotiables, driving questions. Then exceed them.
 
 **Act.** No permission needed. No workarounds. Ship it.
 

package/assets/skills/{trust-safety → abuse-prevention}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: trust-safety
-description: Trust and safety - abuse prevention, rate limiting. Use when fighting bad actors.
+name: abuse-prevention
+description: Abuse prevention - rate limiting, moderation, bad actors. Use when fighting abuse.
 ---
 
-# Trust Safety Guideline
+# Abuse Prevention Guideline
 
 ## Tech Stack
 

package/assets/skills/{security → appsec}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: security
+name: appsec
 description: Application security - OWASP, validation, secrets. Use when securing the app.
 ---
 
-# Security Guideline
+# AppSec Guideline
 
 ## Tech Stack
 

package/assets/skills/{discovery → competitive-analysis}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: discovery
-description: Feature discovery - competitive analysis. Use when exploring features.
+name: competitive-analysis
+description: Competitive analysis - market research, feature gaps. Use when exploring what competitors do.
 ---
 
-# Discovery Guideline
+# Competitive Analysis Guideline
 
 ## Tech Stack
 

package/assets/skills/{data-architecture → data-modeling}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: data-architecture
-description: Data architecture - models, relationships. Use when designing data structures.
+name: data-modeling
+description: Data modeling - entities, relationships, schemas. Use when designing data structures.
 ---
 
-# Data Architecture Guideline
+# Data Modeling Guideline
 
 ## Tech Stack
 

package/assets/skills/{operability → deployments}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: operability
-description: Operations - deployment, rollback, feature flags. Use for ops tooling.
+name: deployments
+description: Deployments - rollback, feature flags, ops tooling. Use when shipping to production.
 ---
 
-# Operability Guideline
+# Deployments Guideline
 
 ## Tech Stack
 

package/assets/slash-commands/continue.md

@@ -16,6 +16,13 @@ Push for world-class:
 
 **Never self-assess.** Delegate to workers — they critique, you synthesize. Final Gate.
 
-**Invoke skills** before acting. Then exceed them.
+**Invoke skills** before acting on any domain:
+```
+abuse-prevention, account-security, admin, appsec, auth, billing,
+code-quality, competitive-analysis, data-modeling, database, delivery,
+deployments, growth, i18n, ledger, observability, performance, pricing,
+privacy, pwa, referral, seo, storage, support, uiux
+```
+Skills contain: tech stack decisions, non-negotiables, driving questions. Then exceed them.
 
 `/continue`

package/assets/slash-commands/review.md

@@ -19,9 +19,12 @@ args:
 
 1. **Invoke skills** — Load guidelines for relevant domains:
    ```
-   auth, account-security, billing, security, database, performance, observability...
+   abuse-prevention, account-security, admin, appsec, auth, billing,
+   code-quality, competitive-analysis, data-modeling, database, delivery,
+   deployments, growth, i18n, ledger, observability, performance, pricing,
+   privacy, pwa, referral, seo, storage, support, uiux
    ```
-   Skills contain: tech stack decisions, non-negotiables, patterns, anti-patterns.
+   Skills contain: tech stack decisions, non-negotiables, driving questions.
 
 2. **Understand** — How is this implemented? Architecture, choices, tradeoffs.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "2.28.0",
+	"version": "2.28.1",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {

package/src/commands/flow/execute-v2.ts

@@ -260,6 +260,7 @@ export async function executeFlowV2(
       verbose: options.verbose,
       skipBackup: false,
       skipSecrets: false,
+      skipProjectDocs: true, // Use /init command for project docs
       merge: options.merge || false,
     });
 

package/src/commands/flow-command.ts

@@ -147,6 +147,107 @@ export const doctorCommand = new Command('doctor')
     }
   });
 
+/**
+ * Quickstart command - interactive onboarding tutorial
+ */
+export const quickstartCommand = new Command('quickstart')
+  .description('Interactive 2-minute tutorial to get started with Flow')
+  .action(async () => {
+    const { default: inquirer } = await import('inquirer');
+
+    console.log(chalk.cyan.bold('\n🚀 Welcome to Sylphx Flow!\n'));
+    console.log(chalk.dim('This 2-minute tutorial will get you up and running.\n'));
+
+    // Step 1: Check for AI CLI
+    console.log(chalk.bold('Step 1/4: Checking your environment\n'));
+
+    const detector = new StateDetector();
+    const state = await detector.detect();
+
+    if (state.claudeCodeInstalled) {
+      console.log(chalk.green('  ✓ Claude Code installed\n'));
+    } else {
+      console.log(chalk.yellow('  ⚠ Claude Code not found\n'));
+      const { installNow } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'installNow',
+          message: 'Install Claude Code now?',
+          default: true,
+        },
+      ]);
+
+      if (installNow) {
+        console.log(chalk.dim('\n  Installing Claude Code...\n'));
+        const { exec } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execAsync = promisify(exec);
+        try {
+          await execAsync('npm install -g @anthropic-ai/claude-code');
+          console.log(chalk.green('  ✓ Claude Code installed\n'));
+        } catch {
+          console.log(chalk.red('  ✗ Installation failed. Run manually:'));
+          console.log(chalk.dim('    npm install -g @anthropic-ai/claude-code\n'));
+        }
+      }
+    }
+
+    // Step 2: Explain core concept
+    console.log(chalk.bold('Step 2/4: How Flow works\n'));
+    console.log(chalk.dim('  Flow orchestrates AI coding assistants with:'));
+    console.log(chalk.dim('  • Specialized agents (coder, writer, reviewer)'));
+    console.log(chalk.dim('  • Smart context (less prompting, more building)'));
+    console.log(chalk.dim('  • Clean git (your config stays untouched)\n'));
+
+    await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'continue',
+        message: chalk.dim('Press Enter to continue...'),
+      },
+    ]);
+
+    // Step 3: Show example usage
+    console.log(chalk.bold('\nStep 3/4: Example commands\n'));
+    console.log(chalk.cyan('  Basic usage:'));
+    console.log(chalk.white('    sylphx-flow "fix the login bug"'));
+    console.log(chalk.white('    sylphx-flow "add dark mode"'));
+    console.log(chalk.white('    sylphx-flow "write tests for auth"'));
+    console.log('');
+    console.log(chalk.cyan('  With agents:'));
+    console.log(chalk.white('    sylphx-flow --agent coder "implement feature"'));
+    console.log(chalk.white('    sylphx-flow --agent writer "document API"'));
+    console.log(chalk.white('    sylphx-flow --agent reviewer "review security"'));
+    console.log('');
+
+    await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'continue',
+        message: chalk.dim('Press Enter to continue...'),
+      },
+    ]);
+
+    // Step 4: Try it
+    console.log(chalk.bold('\nStep 4/4: Try it yourself!\n'));
+    const { tryNow } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'tryNow',
+        message: 'Run Flow now with a sample task?',
+        default: true,
+      },
+    ]);
+
+    if (tryNow) {
+      console.log(chalk.dim('\nLaunching Flow...\n'));
+      await executeFlow('describe this codebase briefly', { agent: 'builder' } as FlowOptions);
+    } else {
+      console.log(chalk.green("\n✨ You're ready to go!\n"));
+      console.log(chalk.dim('  Run: sylphx-flow "your first task"\n'));
+    }
+  });
+
 /**
  * Upgrade command - upgrade components
  */

package/src/core/__tests__/backup-restore.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Integration tests for backup → attach → restore lifecycle
+ * Tests the complete flow of:
+ * 1. Creating backup of existing config
+ * 2. Attaching Flow templates
+ * 3. Restoring original config on cleanup
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AttachManager } from '../attach-manager.js';
+import { BackupManager } from '../backup-manager.js';
+import { ProjectManager } from '../project-manager.js';
+import { targetManager } from '../target-manager.js';
+
+describe('Backup → Attach → Restore Lifecycle', () => {
+  let tempDir: string;
+  let projectManager: ProjectManager;
+  let backupManager: BackupManager;
+  let attachManager: AttachManager;
+  let projectPath: string;
+  let projectHash: string;
+
+  // Get Claude Code target for tests
+  const getClaudeTarget = () => {
+    const targetOption = targetManager.getTarget('claude-code');
+    if (targetOption._tag === 'None') {
+      throw new Error('Claude Code target not found');
+    }
+    return targetOption.value;
+  };
+
+  beforeEach(async () => {
+    // Create temp directories
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-test-'));
+    projectPath = path.join(tempDir, 'test-project');
+    fs.mkdirSync(projectPath, { recursive: true });
+
+    // Initialize managers
+    projectManager = new ProjectManager();
+
+    // Override Flow data directory to use temp
+    const flowDataDir = path.join(tempDir, '.sylphx-flow');
+    fs.mkdirSync(flowDataDir, { recursive: true });
+    (projectManager as any).flowDataDir = flowDataDir;
+
+    backupManager = new BackupManager(projectManager);
+    attachManager = new AttachManager(projectManager);
+
+    // Get project hash
+    projectHash = projectManager.getProjectHash(projectPath);
+  });
+
+  afterEach(async () => {
+    // Cleanup temp directory
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('Empty project (no existing config)', () => {
+    it('should create backup with empty manifest', async () => {
+      const target = getClaudeTarget();
+      const backup = await backupManager.createBackup(projectPath, projectHash, target);
+
+      expect(backup.sessionId).toMatch(/^session-\d+$/);
+      expect(backup.projectPath).toBe(projectPath);
+      expect(backup.target).toBe('claude-code');
+      expect(fs.existsSync(backup.backupPath)).toBe(true);
+
+      // Check manifest exists
+      const manifest = await backupManager.getManifest(projectHash, backup.sessionId);
+      expect(manifest).not.toBeNull();
+      expect(manifest?.backup.agents.user).toEqual([]);
+      expect(manifest?.backup.agents.flow).toEqual([]);
+    });
+
+    it('should restore to empty state after attach', async () => {
+      const target = getClaudeTarget();
+      const backup = await backupManager.createBackup(projectPath, projectHash, target);
+
+      // Simulate attach by creating .claude directory
+      const claudeDir = path.join(projectPath, '.claude');
+      fs.mkdirSync(claudeDir, { recursive: true });
+      fs.writeFileSync(path.join(claudeDir, 'settings.json'), '{"mcpServers":{}}');
+
+      // Verify .claude exists after "attach"
+      expect(fs.existsSync(claudeDir)).toBe(true);
+
+      // Restore
+      await backupManager.restoreBackup(projectHash, backup.sessionId);
+
+      // .claude should be removed (back to empty state)
+      expect(fs.existsSync(claudeDir)).toBe(false);
+    });
+  });
+
+  describe('Project with existing config', () => {
+    const existingConfig = {
+      mcpServers: {
+        'my-server': {
+          command: 'my-cmd',
+          args: ['--flag'],
+        },
+      },
+    };
+
+    beforeEach(() => {
+      // Create existing .claude config
+      const claudeDir = path.join(projectPath, '.claude');
+      fs.mkdirSync(claudeDir, { recursive: true });
+      fs.writeFileSync(path.join(claudeDir, 'settings.json'), JSON.stringify(existingConfig));
+
+      // Create existing agent file
+      const agentsDir = path.join(claudeDir, 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'my-agent.md'), '# My Custom Agent\n\nMy custom prompt.');
+    });
+
+    it('should backup existing config', async () => {
+      const target = getClaudeTarget();
+      const backup = await backupManager.createBackup(projectPath, projectHash, target);
+
+      // Check backup directory has .claude
+      const backupClaudeDir = path.join(backup.backupPath, '.claude');
+      expect(fs.existsSync(backupClaudeDir)).toBe(true);
+
+      // Check settings.json was backed up
+      const backupSettings = path.join(backupClaudeDir, 'settings.json');
+      expect(fs.existsSync(backupSettings)).toBe(true);
+
+      const settingsContent = JSON.parse(fs.readFileSync(backupSettings, 'utf-8'));
+      expect(settingsContent).toEqual(existingConfig);
+
+      // Check agent was backed up
+      const backupAgentFile = path.join(backupClaudeDir, 'agents', 'my-agent.md');
+      expect(fs.existsSync(backupAgentFile)).toBe(true);
+    });
+
+    it('should restore existing config after modifications', async () => {
+      const target = getClaudeTarget();
+      const backup = await backupManager.createBackup(projectPath, projectHash, target);
+
+      // Simulate modifications (what attach would do)
+      const claudeDir = path.join(projectPath, '.claude');
+
+      // Modify settings.json
+      const newConfig = {
+        mcpServers: {
+          'flow-server': { command: 'flow-cmd' },
+        },
+      };
+      fs.writeFileSync(path.join(claudeDir, 'settings.json'), JSON.stringify(newConfig));
+
+      // Add new agent file
+      fs.writeFileSync(path.join(claudeDir, 'agents', 'builder.md'), '# Builder Agent');
+
+      // Remove original agent
+      fs.unlinkSync(path.join(claudeDir, 'agents', 'my-agent.md'));
+
+      // Verify modifications
+      expect(fs.existsSync(path.join(claudeDir, 'agents', 'my-agent.md'))).toBe(false);
+      expect(fs.existsSync(path.join(claudeDir, 'agents', 'builder.md'))).toBe(true);
+
+      // Restore
+      await backupManager.restoreBackup(projectHash, backup.sessionId);
+
+      // Verify restoration
+      const restoredSettings = JSON.parse(fs.readFileSync(path.join(claudeDir, 'settings.json'), 'utf-8'));
+      expect(restoredSettings).toEqual(existingConfig);
+
+      // Original agent should be back
+      expect(fs.existsSync(path.join(claudeDir, 'agents', 'my-agent.md'))).toBe(true);
+
+      // Flow agent should be gone
+      expect(fs.existsSync(path.join(claudeDir, 'agents', 'builder.md'))).toBe(false);
+    });
+  });
+
+  describe('Backup cleanup', () => {
+    it('should keep only specified number of backups', async () => {
+      const target = getClaudeTarget();
+
+      // Create 5 backups
+      const backups: string[] = [];
+      for (let i = 0; i < 5; i++) {
+        const backup = await backupManager.createBackup(projectPath, projectHash, target);
+        backups.push(backup.sessionId);
+        // Small delay to ensure unique timestamps
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+
+      // Should have 5 backups
+      const listBefore = await backupManager.listBackups(projectHash);
+      expect(listBefore.length).toBe(5);
+
+      // Cleanup to keep last 2
+      await backupManager.cleanupOldBackups(projectHash, 2);
+
+      // Should have 2 backups
+      const listAfter = await backupManager.listBackups(projectHash);
+      expect(listAfter.length).toBe(2);
+
+      // The 2 most recent should remain
+      const remainingIds = listAfter.map((b) => b.sessionId);
+      expect(remainingIds).toContain(backups[4]);
+      expect(remainingIds).toContain(backups[3]);
+    });
+  });
+
+  describe('Manifest tracking', () => {
+    it('should update manifest with attach results', async () => {
+      const target = getClaudeTarget();
+      const backup = await backupManager.createBackup(projectPath, projectHash, target);
+
+      // Get original manifest
+      const manifest = await backupManager.getManifest(projectHash, backup.sessionId);
+      expect(manifest).not.toBeNull();
+
+      // Update manifest (simulating attach results)
+      manifest!.backup.agents.flow = ['builder.md', 'coder.md'];
+      manifest!.backup.commands.flow = ['init.md', 'review.md'];
+      manifest!.secrets.mcpEnvExtracted = true;
+
+      await backupManager.updateManifest(projectHash, backup.sessionId, manifest!);
+
+      // Read updated manifest
+      const updatedManifest = await backupManager.getManifest(projectHash, backup.sessionId);
+      expect(updatedManifest?.backup.agents.flow).toEqual(['builder.md', 'coder.md']);
+      expect(updatedManifest?.backup.commands.flow).toEqual(['init.md', 'review.md']);
+      expect(updatedManifest?.secrets.mcpEnvExtracted).toBe(true);
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should throw on restore of non-existent backup', async () => {
+      await expect(backupManager.restoreBackup(projectHash, 'session-nonexistent')).rejects.toThrow('Backup not found');
+    });
+
+    it('should return null manifest for non-existent session', async () => {
+      const manifest = await backupManager.getManifest(projectHash, 'session-nonexistent');
+      expect(manifest).toBeNull();
+    });
+  });
+});

package/src/core/cleanup-handler.ts

@@ -2,6 +2,10 @@
  * Cleanup Handler
  * Manages graceful cleanup on exit and crash recovery
  * Handles process signals and ensures backup restoration
+ *
+ * IMPORTANT: Node.js 'exit' event handlers MUST be synchronous.
+ * We use SIGINT/SIGTERM handlers to perform async cleanup before exiting.
+ * The 'exit' handler is only a last-resort sync cleanup.
  */
 
 import type { BackupManager } from './backup-manager.js';
@@ -13,6 +17,8 @@ export class CleanupHandler {
   private backupManager: BackupManager;
   private registered = false;
   private currentProjectHash: string | null = null;
+  private cleanupInProgress = false;
+  private cleanupCompleted = false;
 
   constructor(
     projectManager: ProjectManager,
@@ -35,64 +41,63 @@ export class CleanupHandler {
     this.currentProjectHash = projectHash;
     this.registered = true;
 
-    // Normal exit
-    process.on('exit', async () => {
-      await this.onExit();
+    // SIGINT (Ctrl+C) - perform async cleanup then exit
+    process.on('SIGINT', () => {
+      this.handleSignal('SIGINT', 0);
     });
 
-    // SIGINT (Ctrl+C)
-    process.on('SIGINT', async () => {
-      await this.onSignal('SIGINT');
-      process.exit(0);
+    // SIGTERM - perform async cleanup then exit
+    process.on('SIGTERM', () => {
+      this.handleSignal('SIGTERM', 0);
     });
 
-    // SIGTERM
-    process.on('SIGTERM', async () => {
-      await this.onSignal('SIGTERM');
-      process.exit(0);
-    });
-
-    // Uncaught exceptions
-    process.on('uncaughtException', async (error) => {
+    // Uncaught exceptions - perform async cleanup then exit with error
+    process.on('uncaughtException', (error) => {
       console.error('\nUncaught Exception:', error);
-      await this.onSignal('uncaughtException');
-      process.exit(1);
+      this.handleSignal('uncaughtException', 1);
     });
 
-    // Unhandled rejections
-    process.on('unhandledRejection', async (reason) => {
+    // Unhandled rejections - perform async cleanup then exit with error
+    process.on('unhandledRejection', (reason) => {
       console.error('\nUnhandled Rejection:', reason);
-      await this.onSignal('unhandledRejection');
-      process.exit(1);
+      this.handleSignal('unhandledRejection', 1);
+    });
+
+    // 'exit' handler - SYNC ONLY, last resort
+    // This catches cases where process.exit() was called without going through signals
+    process.on('exit', () => {
+      // If cleanup wasn't done via signal handlers, log warning
+      // (We can't do async cleanup here - just flag it)
+      if (!this.cleanupCompleted && this.currentProjectHash) {
+        // Recovery will happen on next startup via recoverOnStartup()
+        // This is the intended safety net for abnormal exits
+      }
     });
   }
 
   /**
-   * Normal exit cleanup (with multi-session support)
+   * Handle signal with async cleanup
+   * Ensures cleanup completes before process exit
    */
-  private async onExit(): Promise<void> {
-    if (!this.currentProjectHash) {
+  private handleSignal(signal: string, exitCode: number): void {
+    // Prevent double cleanup
+    if (this.cleanupInProgress || this.cleanupCompleted) {
+      process.exit(exitCode);
       return;
     }
 
-    try {
-      const { shouldRestore, session } = await this.sessionManager.endSession(
-        this.currentProjectHash
-      );
+    this.cleanupInProgress = true;
 
-      if (shouldRestore && session) {
-        // Last session - restore backup silently on normal exit
-        await this.backupManager.restoreBackup(this.currentProjectHash, session.sessionId);
-        await this.backupManager.cleanupOldBackups(this.currentProjectHash, 3);
-      }
-    } catch (_error) {
-      // Silent fail on exit
-    }
+    // Perform async cleanup, then exit
+    this.onSignal(signal).finally(() => {
+      this.cleanupCompleted = true;
+      process.exit(exitCode);
+    });
   }
 
   /**
-   * Signal-based cleanup (SIGINT, SIGTERM, etc.) with multi-session support
-   * Silent operation - no console output
+   * Async cleanup for signals and manual cleanup
+   * Handles session end and backup restoration
    */
   private async onSignal(_signal: string): Promise<void> {
     if (!this.currentProjectHash) {
@@ -106,9 +111,10 @@ export class CleanupHandler {
 
       if (shouldRestore && session) {
         await this.backupManager.restoreBackup(this.currentProjectHash, session.sessionId);
+        await this.backupManager.cleanupOldBackups(this.currentProjectHash, 3);
       }
     } catch (_error) {
-      // Silent fail
+      // Silent fail - recovery will happen on next startup
     }
   }
 

package/src/core/flow-executor.ts

@@ -4,10 +4,10 @@
  * Handles backup → attach → run → restore lifecycle
  */
 
-import chalk from 'chalk';
 import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import chalk from 'chalk';
 import type { Target } from '../types/target.types.js';
 import { AttachManager } from './attach-manager.js';
 import { BackupManager } from './backup-manager.js';
@@ -23,6 +23,7 @@ export interface FlowExecutorOptions {
   verbose?: boolean;
   skipBackup?: boolean;
   skipSecrets?: boolean;
+  skipProjectDocs?: boolean; // Skip auto-creating PRODUCT.md/ARCHITECTURE.md
   merge?: boolean; // Merge mode: keep user files (default: replace all)
 }
 
@@ -96,8 +97,10 @@ export class FlowExecutor {
       return { joined: true };
     }
 
-    // First session - ensure project docs, stash, backup, attach (all silent)
-    await this.ensureProjectDocs(projectPath);
+    // First session - optionally create project docs, stash, backup, attach (all silent)
+    if (!options.skipProjectDocs) {
+      await this.ensureProjectDocs(projectPath);
+    }
     await this.gitStashManager.stashSettingsChanges(projectPath);
     const backup = await this.backupManager.createBackup(projectPath, projectHash, target);
 
@@ -271,7 +274,10 @@ export class FlowExecutor {
     const templatesDir = this.templateLoader.getAssetsDir();
     const templates = [
       { name: 'PRODUCT.md', template: path.join(templatesDir, 'templates', 'PRODUCT.md') },
-      { name: 'ARCHITECTURE.md', template: path.join(templatesDir, 'templates', 'ARCHITECTURE.md') },
+      {
+        name: 'ARCHITECTURE.md',
+        template: path.join(templatesDir, 'templates', 'ARCHITECTURE.md'),
+      },
     ];
 
     for (const { name, template } of templates) {

package/src/index.ts

@@ -12,6 +12,7 @@ import { executeFlow } from './commands/flow/execute-v2.js';
 import {
   doctorCommand,
   flowCommand,
+  quickstartCommand,
   setupCommand,
   statusCommand,
   upgradeCommand,
@@ -71,6 +72,7 @@ export function createCLI(): Command {
 
   // Add subcommands - these can still be used explicitly
   program.addCommand(flowCommand);
+  program.addCommand(quickstartCommand);
   program.addCommand(setupCommand);
   program.addCommand(statusCommand);
   program.addCommand(doctorCommand);

package/src/utils/config/mcp-config.ts

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 
 import inquirer from 'inquirer';
-import type { MCPServerID } from '../../config/servers.js';
+import type { EnvVarConfig, MCPServerDefinition, MCPServerID } from '../../config/servers.js';
 import { getAllServerIDs, MCP_SERVER_REGISTRY } from '../../config/servers.js';
 import { targetManager } from '../../core/target-manager.js';
 import { getNestedProperty, setNestedProperty } from './target-config.js';
@@ -93,7 +93,7 @@ export class MCPConfigurator {
     return serverId as MCPServerID;
   }
 
-  private async configureServer(server: any): Promise<Record<string, string>> {
+  private async configureServer(server: MCPServerDefinition): Promise<Record<string, string>> {
     const fields = this.buildConfigFields(server);
     const values: Record<string, string> = {};
 
@@ -108,11 +108,12 @@ export class MCPConfigurator {
     return values;
   }
 
-  private buildConfigFields(server: any): ConfigField[] {
+  private buildConfigFields(server: MCPServerDefinition): ConfigField[] {
     const fields: ConfigField[] = [];
 
     if (server.envVars) {
-      Object.entries(server.envVars).forEach(([key, config]: [string, any]) => {
+      Object.entries(server.envVars).forEach(([key, config]) => {
+        const envConfig = config as EnvVarConfig;
         let options: string[] | undefined;
 
         if (key === 'EMBEDDING_MODEL') {
@@ -123,10 +124,10 @@ export class MCPConfigurator {
 
         fields.push({
           name: key,
-          description: config.description,
-          required: config.required,
-          secret: config.secret || false,
-          defaultValue: config.default,
+          description: envConfig.description,
+          required: envConfig.required,
+          secret: envConfig.secret || false,
+          defaultValue: envConfig.default,
           currentValue: this.existingValues[key],
           options,
         });