@lumenflow/cli 2.2.2 → 2.3.1

package/dist/init.js

@@ -4,31 +4,55 @@
  * WU-1006: Library-First - use core defaults for config generation
  * WU-1028: Vendor-agnostic core + vendor overlays
  * WU-1085: Added createWUParser for proper --help support
+ * WU-1171: Added --merge mode, --client flag, AGENTS.md, updated vendor paths
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { getDefaultConfig, createWUParser, WU_OPTIONS } from '@lumenflow/core';
 // WU-1067: Import GATE_PRESETS for --preset support
 import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
+// WU-1171: Import merge block utilities
+import { updateMergeBlock } from './merge-block.js';
 /**
  * WU-1085: CLI option definitions for init command
+ * WU-1171: Added --merge and --client options
  */
 const INIT_OPTIONS = {
     full: {
         name: 'full',
         flags: '--full',
-        description: 'Add docs + agent onboarding + task scaffolding',
+        description: 'Add docs + agent onboarding + task scaffolding (default: true)',
+    },
+    minimal: {
+        name: 'minimal',
+        flags: '--minimal',
+        description: 'Skip agent onboarding docs (only core files)',
     },
     framework: {
         name: 'framework',
         flags: '--framework <name>',
         description: 'Add framework hint + overlay docs',
     },
+    // WU-1171: --client is the new primary flag (wu:spawn vocabulary)
+    client: {
+        name: 'client',
+        flags: '--client <type>',
+        description: 'Client type (claude, cursor, windsurf, codex, all, none)',
+    },
+    // WU-1171: --vendor kept as backward-compatible alias
     vendor: {
         name: 'vendor',
         flags: '--vendor <type>',
-        description: 'Vendor type (claude, cursor, aider, all, none)',
+        description: 'Alias for --client (deprecated)',
+    },
+    // WU-1171: --merge mode for safe insertion into existing files
+    merge: {
+        name: 'merge',
+        flags: '--merge',
+        description: 'Merge LumenFlow config into existing files using bounded markers',
     },
     preset: {
         name: 'preset',
@@ -39,6 +63,7 @@ const INIT_OPTIONS = {
 };
 /**
  * WU-1085: Parse init command options using createWUParser
+ * WU-1171: Added --merge, --client options
  * Provides proper --help, --version, and option parsing
  */
 export function parseInitOptions() {
@@ -47,20 +72,133 @@ export function parseInitOptions() {
         description: 'Initialize LumenFlow in a project',
         options: Object.values(INIT_OPTIONS),
     });
+    // WU-1171: --client takes precedence, --vendor is alias
+    const clientValue = opts.client || opts.vendor;
+    // WU-1286: --full is now the default (true), use --minimal to disable
+    // --minimal explicitly sets full to false, otherwise full defaults to true
+    const fullMode = opts.minimal ? false : (opts.full ?? true);
     return {
         force: opts.force ?? false,
-        full: opts.full ?? false,
+        full: fullMode,
+        merge: opts.merge ?? false,
         framework: opts.framework,
-        vendor: opts.vendor,
+        client: clientValue,
+        vendor: clientValue,
         preset: opts.preset,
     };
 }
+const DEFAULT_CLIENT_CLAUDE = 'claude-code';
 const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
 const FRAMEWORK_HINT_FILE = '.lumenflow.framework.yaml';
 const LUMENFLOW_DIR = '.lumenflow';
 const LUMENFLOW_AGENTS_DIR = `${LUMENFLOW_DIR}/agents`;
 const CLAUDE_DIR = '.claude';
 const CLAUDE_AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
+// Shared path segment for docs structure
+const DOCS_OPERATIONS_DIR = '04-operations';
+/**
+ * WU-1177: Detect IDE environment from environment variables
+ * Auto-detects which AI coding assistant is running
+ */
+export function detectIDEEnvironment() {
+    // Claude Code detection (highest priority - most specific)
+    if (process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_CODE) {
+        return 'claude';
+    }
+    // Cursor detection
+    const cursorVars = Object.keys(process.env).filter((key) => key.startsWith('CURSOR_'));
+    if (cursorVars.length > 0) {
+        return 'cursor';
+    }
+    // Windsurf detection
+    const windsurfVars = Object.keys(process.env).filter((key) => key.startsWith('WINDSURF_'));
+    if (windsurfVars.length > 0) {
+        return 'windsurf';
+    }
+    // VS Code detection (lowest priority - most generic)
+    const vscodeVars = Object.keys(process.env).filter((key) => key.startsWith('VSCODE_'));
+    if (vscodeVars.length > 0) {
+        return 'vscode';
+    }
+    return undefined;
+}
+/**
+ * Get command version safely using execFileSync
+ */
+function getCommandVersion(command, args) {
+    try {
+        const output = execFileSync(command, args, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return output;
+    }
+    catch {
+        return 'not found';
+    }
+}
+/**
+ * Parse semver version string to compare
+ */
+function parseVersion(versionStr) {
+    // Extract version numbers using a non-backtracking pattern
+    const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(versionStr);
+    if (!match) {
+        return [0, 0, 0];
+    }
+    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3] || '0', 10)];
+}
+/**
+ * Compare versions: returns true if actual >= required
+ */
+function compareVersions(actual, required) {
+    const actualParts = parseVersion(actual);
+    const requiredParts = parseVersion(required);
+    for (let i = 0; i < 3; i++) {
+        if (actualParts[i] > requiredParts[i]) {
+            return true;
+        }
+        if (actualParts[i] < requiredParts[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * WU-1177: Check prerequisite versions
+ * Non-blocking - returns results but doesn't fail init
+ */
+export function checkPrerequisites() {
+    const nodeVersion = getCommandVersion('node', ['--version']);
+    const pnpmVersion = getCommandVersion('pnpm', ['--version']);
+    const gitVersion = getCommandVersion('git', ['--version']);
+    const requiredNode = '22.0.0';
+    const requiredPnpm = '9.0.0';
+    const requiredGit = '2.0.0';
+    const nodeOk = nodeVersion !== 'not found' && compareVersions(nodeVersion, requiredNode);
+    const pnpmOk = pnpmVersion !== 'not found' && compareVersions(pnpmVersion, requiredPnpm);
+    const gitOk = gitVersion !== 'not found' && compareVersions(gitVersion, requiredGit);
+    return {
+        node: {
+            passed: nodeOk,
+            version: nodeVersion,
+            required: `>=${requiredNode}`,
+            message: nodeOk ? undefined : `Node.js ${requiredNode}+ required`,
+        },
+        pnpm: {
+            passed: pnpmOk,
+            version: pnpmVersion,
+            required: `>=${requiredPnpm}`,
+            message: pnpmOk ? undefined : `pnpm ${requiredPnpm}+ required`,
+        },
+        git: {
+            passed: gitOk,
+            version: gitVersion,
+            required: `>=${requiredGit}`,
+            message: gitOk ? undefined : `Git ${requiredGit}+ required`,
+        },
+    };
+}
 /**
  * Generate YAML configuration with header comment
  * WU-1067: Supports --preset option for config-driven gates
@@ -92,8 +230,11 @@ function normalizeFrameworkName(framework) {
     const name = framework.trim();
     const slug = name
         .toLowerCase()
-        .replace(/[^a-z0-9-_]+/g, '-')
-        .replace(/^-+|-+$/g, '');
+        .replace(/[^a-z0-9_-]+/g, '-')
+        // Remove leading dashes and trailing dashes separately (explicit precedence)
+        .replace(/^-+/, '')
+        // eslint-disable-next-line sonarjs/slow-regex -- Simple pattern, no catastrophic backtracking risk
+        .replace(/-+$/, '');
     if (!slug) {
         throw new Error(`Invalid framework name: "${framework}"`);
     }
@@ -112,6 +253,66 @@ function processTemplate(content, tokens) {
 function getRelativePath(targetDir, filePath) {
     return path.relative(targetDir, filePath).split(path.sep).join('/');
 }
+// WU-1171: Template for AGENTS.md (universal entry point)
+const AGENTS_MD_TEMPLATE = `# Universal Agent Instructions
+
+**Last updated:** {{DATE}}
+
+This project uses LumenFlow workflow. For complete documentation, see [LUMENFLOW.md](LUMENFLOW.md).
+
+---
+
+## Quick Start
+
+\`\`\`bash
+# 1. Claim a WU
+pnpm wu:claim --id WU-XXXX --lane <Lane>
+cd worktrees/<lane>-wu-xxxx
+
+# 2. Work in worktree, run gates
+pnpm gates
+
+# 3. Complete (ALWAYS run this!)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXXX
+\`\`\`
+
+---
+
+## Critical: Always wu:done
+
+After completing work, ALWAYS run \`pnpm wu:done --id WU-XXXX\` from the main checkout.
+
+This is the single most forgotten step. See [LUMENFLOW.md](LUMENFLOW.md) for details.
+
+---
+
+## Core Principles
+
+1. **TDD**: Write tests first, then implementation
+2. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree
+3. **Gates Before Done**: Run \`pnpm gates\` before \`wu:done\`
+4. **Never Bypass Hooks**: No \`--no-verify\`
+
+---
+
+## Forbidden Commands
+
+- \`git reset --hard\`
+- \`git push --force\`
+- \`git stash\` (on main)
+- \`--no-verify\`
+
+---
+
+## Vendor-Specific Overlays
+
+This file provides universal guidance for all AI agents. Additional vendor-specific configuration:
+
+- **Claude Code**: See \`CLAUDE.md\` (if present)
+- **Cursor**: See \`.cursor/rules/lumenflow.md\` (if present)
+- **Windsurf**: See \`.windsurf/rules/lumenflow.md\` (if present)
+`;
 // Template for LUMENFLOW.md (main entry point)
 const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {{DATE}}\n\nLumenFlow is a vendor-agnostic workflow framework for AI-native software development.\n\n---\n\n## Critical Rule: ALWAYS Run wu:done\n\n**After completing work on a WU, you MUST run \`pnpm wu:done --id WU-XXXX\` from the main checkout.**\n\nThis is the single most forgotten step. Do NOT:\n- Write "To Complete: pnpm wu:done" and stop\n- Ask if you should run wu:done\n- Forget to run wu:done\n\n**DO**: Run \`pnpm wu:done --id WU-XXXX\` immediately after gates pass.\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Create a WU\npnpm wu:create --id WU-XXXX --lane <Lane> --title "Title"\n\n# 2. Edit WU spec with acceptance criteria, then claim:\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 3. Implement in worktree\n\n# 4. Run gates\npnpm gates --docs-only  # for docs changes\npnpm gates              # for code changes\n\n# 5. Complete (from main checkout)\ncd {{PROJECT_ROOT}}\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Core Principles\n\n1. **TDD**: Failing test -> implementation -> passing test (>=90% coverage on new code)\n2. **Library-First**: Search existing libraries before custom code\n3. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings\n4. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree\n5. **Gates Before Done**: All gates must pass before \`wu:done\`\n6. **Do Not Bypass Hooks**: No \`--no-verify\`, fix issues properly\n7. **Always wu:done**: Complete every WU by running \`pnpm wu:done\`\n\n---\n\n## Documentation Structure\n\n### Core (Vendor-Agnostic)\n\n- **LUMENFLOW.md** - This file, main entry point\n- **.lumenflow/constraints.md** - Non-negotiable workflow constraints\n- **.lumenflow/agents/** - Agent instructions (vendor-agnostic)\n- **.lumenflow.config.yaml** - Workflow configuration\n\n### Optional Overlays\n\n- **CLAUDE.md + .claude/agents/** - Claude Code overlay (auto if Claude Code detected)\n- **docs/04-operations/tasks/** - Task boards and WU storage (\`lumenflow init --full\`)\n- **docs/04-operations/_frameworks/<framework>/** - Framework overlay docs (\`lumenflow init --framework <name>\`)\n- **.lumenflow.framework.yaml** - Framework hint file (created with \`--framework\`)\n\n---\n\n## Worktree Discipline (IMMUTABLE LAW)\n\nAfter claiming a WU, you MUST work in its worktree:\n\n\`\`\`bash\n# 1. Claim creates worktree\npnpm wu:claim --id WU-XXX --lane <lane>\n\n# 2. IMMEDIATELY cd to worktree\ncd worktrees/<lane>-wu-xxx\n\n# 3. ALL work happens here\n\n# 4. Return to main ONLY to complete\ncd {{PROJECT_ROOT}}\npnpm wu:done --id WU-XXX\n\`\`\`\n\n---\n\n## Definition of Done\n\n- Acceptance criteria satisfied\n- Gates green (\`pnpm gates\` or \`pnpm gates --docs-only\`)\n- WU YAML status = \`done\`\n- \`wu:done\` has been run\n\n---\n\n## Commands Reference\n\n| Command           | Description                         |\n| ----------------- | ----------------------------------- |\n| \`pnpm wu:create\` | Create new WU spec                  |\n| \`pnpm wu:claim\`  | Claim WU and create worktree        |\n| \`pnpm wu:done\`   | Complete WU (merge, stamp, cleanup) |\n| \`pnpm gates\`     | Run quality gates                   |\n\n---\n\n## Constraints\n\nSee [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 6 non-negotiable rules.\n\n---\n\n## Agent Onboarding\n\n- Start with **CLAUDE.md** if present (Claude Code overlay).\n- Add vendor-agnostic guidance in **.lumenflow/agents/**.\n- Add framework-specific notes in **docs/04-operations/_frameworks/<framework>/**.\n`;
 // Template for .lumenflow/constraints.md
@@ -149,8 +350,108 @@ const CLAUDE_SETTINGS_TEMPLATE = `{
   }
 }
 `;
-// Template for .cursor/rules.md
-const CURSOR_RULES_TEMPLATE = `# Cursor Rules\n\nThis project uses LumenFlow workflow. See [LUMENFLOW.md](../LUMENFLOW.md).\n\n## Critical Rules\n\n1. **Always run wu:done** - After gates pass, run \`pnpm wu:done --id WU-XXX\`\n2. **Work in worktrees** - After \`wu:claim\`, work only in the worktree\n3. **Never bypass hooks** - No \`--no-verify\`\n4. **TDD** - Write tests first\n\n## Forbidden Commands\n\n- \`git reset --hard\`\n- \`git push --force\`\n- \`git stash\` (on main)\n- \`--no-verify\`\n`;
+// WU-1171: Template for .cursor/rules/lumenflow.md (updated path)
+const CURSOR_RULES_TEMPLATE = `# Cursor LumenFlow Rules
+
+This project uses LumenFlow workflow. See [LUMENFLOW.md](../../LUMENFLOW.md).
+
+## Critical Rules
+
+1. **Always run wu:done** - After gates pass, run \`pnpm wu:done --id WU-XXX\`
+2. **Work in worktrees** - After \`wu:claim\`, work only in the worktree
+3. **Never bypass hooks** - No \`--no-verify\`
+4. **TDD** - Write tests first
+
+## Forbidden Commands
+
+- \`git reset --hard\`
+- \`git push --force\`
+- \`git stash\` (on main)
+- \`--no-verify\`
+
+## Quick Reference
+
+\`\`\`bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <Lane>
+cd worktrees/<lane>-wu-xxx
+
+# Run gates
+pnpm gates
+
+# Complete (from main)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXX
+\`\`\`
+`;
+// WU-1171: Template for .windsurf/rules/lumenflow.md
+const WINDSURF_RULES_TEMPLATE = `# Windsurf LumenFlow Rules
+
+This project uses LumenFlow workflow. See [LUMENFLOW.md](../../LUMENFLOW.md).
+
+## Critical Rules
+
+1. **Always run wu:done** - After gates pass, run \`pnpm wu:done --id WU-XXX\`
+2. **Work in worktrees** - After \`wu:claim\`, work only in the worktree
+3. **Never bypass hooks** - No \`--no-verify\`
+4. **TDD** - Write tests first
+
+## Forbidden Commands
+
+- \`git reset --hard\`
+- \`git push --force\`
+- \`git stash\` (on main)
+- \`--no-verify\`
+
+## Quick Reference
+
+\`\`\`bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <Lane>
+cd worktrees/<lane>-wu-xxx
+
+# Run gates
+pnpm gates
+
+# Complete (from main)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXX
+\`\`\`
+`;
+// WU-1177: Template for .clinerules (Cline AI assistant)
+const CLINE_RULES_TEMPLATE = `# Cline LumenFlow Rules
+
+This project uses LumenFlow workflow. See [LUMENFLOW.md](LUMENFLOW.md).
+
+## Critical Rules
+
+1. **Always run wu:done** - After gates pass, run \`pnpm wu:done --id WU-XXX\`
+2. **Work in worktrees** - After \`wu:claim\`, work only in the worktree
+3. **Never bypass hooks** - No \`--no-verify\`
+4. **TDD** - Write tests first
+
+## Forbidden Commands
+
+- \`git reset --hard\`
+- \`git push --force\`
+- \`git stash\` (on main)
+- \`--no-verify\`
+
+## Quick Reference
+
+\`\`\`bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <Lane>
+cd worktrees/<lane>-wu-xxx
+
+# Run gates
+pnpm gates
+
+# Complete (from main)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXX
+\`\`\`
+`;
 // Template for .aider.conf.yml
 const AIDER_CONF_TEMPLATE = `# Aider Configuration for LumenFlow Projects\n# See LUMENFLOW.md for workflow documentation\n\nmodel: gpt-4-turbo\nauto-commits: false\ndirty-commits: false\n\nread:\n  - LUMENFLOW.md\n  - .lumenflow/constraints.md\n`;
 // Template for docs/04-operations/tasks/backlog.md
@@ -158,7 +459,7 @@ const BACKLOG_TEMPLATE = `---\nsections:\n  ready:\n    heading: '## 🚀 Ready
 // Template for docs/04-operations/tasks/status.md
 const STATUS_TEMPLATE = `# Status (active work)\n\n## In Progress\n\n(No items in progress)\n\n## Blocked\n\n(No items blocked)\n\n## Completed\n\n(No items completed yet)\n`;
 // Template for docs/04-operations/tasks/templates/wu-template.yaml
-const WU_TEMPLATE_YAML = `# Work Unit Template (LumenFlow WU Schema)\n#\n# Copy this template when creating new WUs. Fill in all required fields and\n# remove optional fields if not needed.\n#\n# If you used "lumenflow init --full", this template lives at:\n# docs/04-operations/tasks/templates/wu-template.yaml\n\n# Required: Unique work unit identifier (format: WU-NNN)\nid: WU-XXX\n\n# Required: Short, descriptive title (max 80 chars)\ntitle: 'Your WU title here'\n\n# Required: Lane (Parent: Sublane format)\nlane: 'Framework: CLI'\n\n# Required: Type of work\ntype: 'feature' # feature | bug | documentation | process | tooling | chore | refactor\n\n# Required: Current status\nstatus: 'ready' # ready | in_progress | blocked | done | cancelled\n\n# Required: Priority\npriority: P2 # P0 | P1 | P2 | P3\n\n# Required: Creation date (YYYY-MM-DD)\ncreated: {{DATE}}\n\n# Required: Owner/assignee (email)\nassigned_to: 'unassigned@example.com'\n\n# Required: Description\ndescription: |\n  Context: ...\n  Problem: ...\n  Solution: ...\n\n# Required: Acceptance criteria (testable, binary)\nacceptance:\n  - Criterion 1 (specific, measurable, testable)\n  - Criterion 2 (binary pass/fail)\n  - Documentation updated\n\n# Required: References to plans/specs (required for type: feature)\nspec_refs:\n  - docs/04-operations/plans/WU-XXX-plan.md\n\n# Required: Code files changed or created (empty only for docs/process WUs)\ncode_paths:\n  - path/to/file.ts\n\n# Required: Test paths (at least one of manual/unit/e2e/integration for non-doc WUs)\ntests:\n  manual:\n    - Manual test: Verify behavior\n  unit:\n    - path/to/test.test.ts\n  e2e: []\n  integration: []\n\n# Required: Exposure level\nexposure: 'backend-only' # ui | api | backend-only | documentation\n\n# Optional: User journey (recommended for ui/api)\n# user_journey: |\n#   User navigates to ...\n#   User performs ...\n\n# Optional: UI pairing WUs (for api exposure)\n# ui_pairing_wus:\n#   - WU-1234\n\n# Optional: Navigation path (required when exposure=ui and no page file)\n# navigation_path: '/settings'\n\n# Required: Deliverable artifacts (stamps, docs, etc.)\nartifacts:\n  - .lumenflow/stamps/WU-XXX.done\n\n# Optional: Dependencies (other WUs that must complete first)\ndependencies: []\n\n# Optional: Risks\nrisks:\n  - Risk 1\n\n# Optional: Notes\nnotes: ''\n\n# Optional: Requires human review\nrequires_review: false\n\n# Optional: Claimed mode (worktree or branch-only)\n# Automatically set by wu:claim, usually don't need to specify\n# claimed_mode: worktree\n\n# Optional: Assigned to (email of current claimant)\n# Automatically set by wu:claim\n# assigned_to: engineer@example.com\n\n# Optional: Locked status (prevents concurrent edits)\n# Automatically set by wu:claim and wu:done\n# locked: false\n\n# Optional: Completion date (ISO 8601 format)\n# Automatically set by wu:done\n# completed: 2025-10-23\n\n# Optional: Completion notes (added by wu:done)\n# completion_notes: |\n#   Additional notes added during wu:done.\n#   Any deviations from original plan.\n#   Lessons learned.\n\n# ============================================================================\n# GOVERNANCE BLOCK (WU Schema v2.0)\n# ============================================================================\n# Optional: COS governance rules that apply to this WU\n# Only include if this WU needs specific governance enforcement\n\n# governance:\n#   # Rules that apply to this WU (evaluated during cos:gates)\n#   rules:\n#     - rule_id: UPAIN-01\n#       satisfied: false  # Initially false, set true when evidence provided\n#       evidence:\n#         - type: link\n#           value: docs/product/voc/feature-user-pain.md\n#           description: "Voice of Customer analysis showing user pain"\n#       notes: |\n#         VOC analysis shows 40% of support tickets request this feature.\n#         Average time wasted: 15min/user/week.\n#\n#     - rule_id: CASH-03\n#       satisfied: false\n#       evidence:\n#         - type: link\n#           value: docs/finance/spend-reviews/2025-10-cloud-infra.md\n#           description: "Spend review for £1200/month cloud infrastructure"\n#         - type: approval\n#           value: owner@example.com\n#           description: "Owner approval for spend commitment"\n#       notes: |\n#         New cloud infrastructure commitment: £1200/month for 12 months.\n#         ROI: Reduces latency by 50%, improves user retention.\n#\n#   # Gate checks (enforced by cos-gates.mjs)\n#   gates:\n#     narrative: "pending"  # Status: pending, passed, skipped, failed\n#     finance: "pending"\n#\n#   # Exemptions (only if rule doesn't apply)\n#   exemptions:\n#     - rule_id: FAIR-01\n#       reason: "No user-facing pricing changes in this WU"\n#       approved_by: product-owner@example.com\n#       approved_at: 2025-10-23\n\n# ============================================================================\n# USAGE NOTES\n# ============================================================================\n#\n# 1. Remove this entire governance block if no COS rules apply to your WU\n# 2. Only include rules that require enforcement (not all rules apply to all WUs)\n# 3. Evidence types: link:, metric:, screenshot:, approval:\n# 4. Gates are checked during wu:done (before merge)\n# 5. Exemptions require approval from rule owner\n#\n# For more details, see:\n# - docs/04-operations/_frameworks/cos/system-prompt-v1.3.md\n# - docs/04-operations/_frameworks/cos/evidence-format.md\n`;
+const WU_TEMPLATE_YAML = `# Work Unit Template (LumenFlow WU Schema)\n#\n# Copy this template when creating new WUs. Fill in all required fields and\n# remove optional fields if not needed.\n#\n# If you used "lumenflow init --full", this template lives at:\n# docs/04-operations/tasks/templates/wu-template.yaml\n\n# Required: Unique work unit identifier (format: WU-NNN)\nid: WU-XXX\n\n# Required: Short, descriptive title (max 80 chars)\ntitle: 'Your WU title here'\n\n# Required: Lane (Parent: Sublane format)\nlane: 'Framework: CLI'\n\n# Required: Type of work\ntype: 'feature' # feature | bug | documentation | process | tooling | chore | refactor\n\n# Required: Current status\nstatus: 'ready' # ready | in_progress | blocked | done | cancelled\n\n# Required: Priority\npriority: P2 # P0 | P1 | P2 | P3\n\n# Required: Creation date (YYYY-MM-DD)\ncreated: {{DATE}}\n\n# Required: Owner/assignee (email)\nassigned_to: 'unassigned@example.com'\n\n# Required: Description\ndescription: |\n  Context: ...\n  Problem: ...\n  Solution: ...\n\n# Required: Acceptance criteria (testable, binary)\nacceptance:\n  - Criterion 1 (specific, measurable, testable)\n  - Criterion 2 (binary pass/fail)\n  - Documentation updated\n\n# Required: References to plans/specs (required for type: feature)\nspec_refs:\n  - docs/04-operations/plans/WU-XXX-plan.md\n\n# Required: Code files changed or created (empty only for docs/process WUs)\ncode_paths:\n  - path/to/file.ts\n\n# Required: Test paths (at least one of manual/unit/e2e/integration for non-doc WUs)\ntests:\n  manual:\n    - Manual test: Verify behavior\n  unit:\n    - path/to/test.test.ts\n  e2e: []\n  integration: []\n\n# Required: Exposure level\nexposure: 'backend-only' # ui | api | backend-only | documentation\n\n# Optional: User journey (recommended for ui/api)\n# user_journey: |\n#   User navigates to ...\n#   User performs ...\n\n# Optional: UI pairing WUs (for api exposure)\n# ui_pairing_wus:\n#   - WU-1234\n\n# Optional: Navigation path (required when exposure=ui and no page file)\n# navigation_path: '/settings'\n\n# Required: Deliverable artifacts (stamps, docs, etc.)\nartifacts:\n  - .lumenflow/stamps/WU-XXX.done\n\n# Optional: Dependencies (other WUs that must complete first)\ndependencies: []\n\n# Optional: Risks\nrisks:\n  - Risk 1\n\n# Optional: Notes\nnotes: ''\n\n# Optional: Requires human review\nrequires_review: false\n\n# Optional: Claimed mode (worktree or branch-only)\n# Automatically set by wu:claim, usually don't need to specify\n# claimed_mode: worktree\n\n# Optional: Assigned to (email of current claimant)\n# Automatically set by wu:claim\n# assigned_to: engineer@example.com\n\n# Optional: Locked status (prevents concurrent edits)\n# Automatically set by wu:claim and wu:done\n# locked: false\n\n# Optional: Completion date (ISO 8601 format)\n# Automatically set by wu:done\n# completed: 2025-10-23\n\n# Optional: Completion notes (added by wu:done)\n# completion_notes: |\n#   Additional notes added during wu:done.\n#   Any deviations from original plan.\n#   Lessons learned.\n\n# ============================================================================\n# GOVERNANCE BLOCK (WU Schema v2.0)\n# ============================================================================\n# Optional: COS governance rules that apply to this WU\n# Only include if this WU needs specific governance enforcement\n\n# governance:\n#   # Rules that apply to this WU (evaluated during cos:gates)\n#   rules:\n#     - rule_id: UPAIN-01\n#       satisfied: false  # Initially false, set true when evidence provided\n#       evidence:\n#         - type: link\n#           value: docs/product/voc/feature-user-pain.md\n#           description: "Voice of Customer analysis showing user pain"\n#       notes: |\n#         VOC analysis shows 40% of support tickets request this feature.\n#         Average time wasted: 15min/user/week.\n#\n#     - rule_id: CASH-03\n#       satisfied: false\n#       evidence:\n#         - type: link\n#           value: docs/finance/spend-reviews/2025-10-cloud-infra.md\n#           description: "Spend review for £1200/month cloud infrastructure"\n#         - type: approval\n#           value: owner@example.com\n#           description: "Owner approval for spend commitment"\n#       notes: |\n#         New cloud infrastructure commitment: £1200/month for 12 months.\n#         ROI: Reduces latency by 50%, improves user retention.\n#\n#   # Gate checks (enforced by cos-gates.ts)\n#   gates:\n#     narrative: "pending"  # Status: pending, passed, skipped, failed\n#     finance: "pending"\n#\n#   # Exemptions (only if rule doesn't apply)\n#   exemptions:\n#     - rule_id: FAIR-01\n#       reason: "No user-facing pricing changes in this WU"\n#       approved_by: product-owner@example.com\n#       approved_at: 2025-10-23\n\n# ============================================================================\n# USAGE NOTES\n# ============================================================================\n#\n# 1. Remove this entire governance block if no COS rules apply to your WU\n# 2. Only include rules that require enforcement (not all rules apply to all WUs)\n# 3. Evidence types: link:, metric:, screenshot:, approval:\n# 4. Gates are checked during wu:done (before merge)\n# 5. Exemptions require approval from rule owner\n#\n# For more details, see:\n# - docs/04-operations/_frameworks/cos/system-prompt-v1.3.md\n# - docs/04-operations/_frameworks/cos/evidence-format.md\n`;
 // Template for .lumenflow.framework.yaml
 const FRAMEWORK_HINT_TEMPLATE = `# LumenFlow Framework Hint\n# Generated by: lumenflow init --framework {{FRAMEWORK_NAME}}\n\nframework: "{{FRAMEWORK_NAME}}"\nslug: "{{FRAMEWORK_SLUG}}"\n`;
 // Template for docs/04-operations/_frameworks/<framework>/README.md
@@ -814,7 +1115,7 @@ version: 1.0.0
 
 // WRONG - Absolute path bypasses worktree
 Write({
-  file_path: '/home/user/source/project/apps/web/src/validator.ts',
+  file_path: '/<user-home>/source/project/apps/web/src/validator.ts',
   content: '...',
 });
 // Result: Written to MAIN checkout, not worktree!
@@ -840,9 +1141,9 @@ Write({
 
 2. **Check file path format**:
 
-   | Pattern                           | Safe? | Example                  |
-   | --------------------------------- | ----- | ------------------------ |
-   | Starts with \`/home/\` or \`/Users/\` | NO    | \`/home/user/.../file.ts\` |
+   | Pattern                           | Safe? | Example                     |
+   | --------------------------------- | ----- | --------------------------- |
+   | Starts with \`/<user-home>/\`       | NO    | \`/<user-home>/.../file.ts\` |
    | Contains full repo path           | NO    | \`/source/project/...\`    |
    | Starts with package name          | YES   | \`apps/web/src/...\`       |
    | Starts with \`./\` or \`../\`         | YES   | \`./src/lib/...\`          |
@@ -935,76 +1236,77 @@ pnpm typecheck            # Check types
  */
 function detectDefaultClient() {
     if (process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_CODE) {
-        return 'claude-code';
+        return DEFAULT_CLIENT_CLAUDE;
     }
     return 'none';
 }
 /**
- * Parse vendor flag from arguments
+ * WU-1171: Resolve client type from options
+ * --client takes precedence over --vendor (backwards compat)
  */
-function parseVendorArg(args) {
-    const vendorIndex = args.findIndex((arg) => arg === '--vendor');
-    if (vendorIndex !== -1 && args[vendorIndex + 1]) {
-        const vendor = args[vendorIndex + 1].toLowerCase();
-        if (['claude', 'cursor', 'aider', 'all', 'none'].includes(vendor)) {
-            return vendor;
-        }
+function resolveClientType(client, vendor, defaultClient) {
+    // Explicit --client or --vendor takes precedence
+    if (client) {
+        return client;
     }
-    return undefined;
+    if (vendor) {
+        return vendor;
+    }
+    // Default based on environment
+    return defaultClient === DEFAULT_CLIENT_CLAUDE ? 'claude' : 'none';
 }
 /**
- * Parse framework flag from arguments
+ * WU-1171: Determine file mode from options
  */
-function parseFrameworkArg(args) {
-    const frameworkArg = args.find((arg) => arg.startsWith('--framework='));
-    if (frameworkArg) {
-        const [, value] = frameworkArg.split('=', 2);
-        return value?.trim() || undefined;
+function getFileMode(options) {
+    if (options.force) {
+        return 'force';
     }
-    const frameworkIndex = args.findIndex((arg) => arg === '--framework');
-    if (frameworkIndex !== -1 && args[frameworkIndex + 1]) {
-        return args[frameworkIndex + 1];
+    if (options.merge) {
+        return 'merge';
     }
-    return undefined;
+    return 'skip';
 }
 /**
- * WU-1067: Parse --preset flag from arguments for config-driven gates
+ * WU-1171: Get templates directory path
  */
-function parsePresetArg(args) {
-    const presetArg = args.find((arg) => arg.startsWith('--preset='));
-    if (presetArg) {
-        const [, value] = presetArg.split('=', 2);
-        const preset = value?.trim().toLowerCase();
-        if (preset && ['node', 'python', 'go', 'rust', 'dotnet'].includes(preset)) {
-            return preset;
-        }
-        return undefined;
-    }
-    const presetIndex = args.findIndex((arg) => arg === '--preset');
-    if (presetIndex !== -1 && args[presetIndex + 1]) {
-        const preset = args[presetIndex + 1].toLowerCase();
-        if (['node', 'python', 'go', 'rust', 'dotnet'].includes(preset)) {
-            return preset;
-        }
+function getTemplatesDir() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    // Check for dist/templates (production) or ../templates (development)
+    const distTemplates = path.join(__dirname, '..', 'templates');
+    if (fs.existsSync(distTemplates)) {
+        return distTemplates;
     }
-    return undefined;
+    throw new Error(`Templates directory not found at ${distTemplates}`);
 }
-function shouldUseVendor(vendor, defaultClient) {
-    if (vendor) {
-        return vendor;
+/**
+ * WU-1171: Load a template file
+ */
+function loadTemplate(templatePath) {
+    const templatesDir = getTemplatesDir();
+    const fullPath = path.join(templatesDir, templatePath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`Template not found: ${templatePath}`);
     }
-    return defaultClient === 'claude-code' ? 'claude' : 'none';
+    return fs.readFileSync(fullPath, 'utf-8');
 }
 /**
  * Scaffold a new LumenFlow project
+ * WU-1171: Added AGENTS.md, --merge mode, updated vendor/client handling
  */
 export async function scaffoldProject(targetDir, options) {
     const result = {
         created: [],
         skipped: [],
+        merged: [],
+        warnings: [],
     };
     const defaultClient = options.defaultClient ?? detectDefaultClient();
-    const vendor = shouldUseVendor(options.vendor, defaultClient);
+    // WU-1171: Use resolveClientType with both client and vendor (vendor is deprecated but kept for backwards compat)
+    // eslint-disable-next-line sonarjs/deprecation -- Intentional backwards compatibility
+    const client = resolveClientType(options.client, options.vendor, defaultClient);
+    const fileMode = getFileMode(options);
     // Ensure target directory exists
     if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
@@ -1014,14 +1316,24 @@ export async function scaffoldProject(targetDir, options) {
         PROJECT_ROOT: targetDir,
     };
     // Create .lumenflow.config.yaml (WU-1067: includes gate preset if specified)
-    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(options.gatePreset), options.force, result, targetDir);
+    // Note: Config files don't use merge mode (always skip or force)
+    await createFile(path.join(targetDir, CONFIG_FILE_NAME), generateLumenflowConfigYaml(options.gatePreset), options.force ? 'force' : 'skip', result, targetDir);
+    // WU-1171: Create AGENTS.md (universal entry point for all agents)
+    try {
+        const agentsTemplate = loadTemplate('core/AGENTS.md.template');
+        await createFile(path.join(targetDir, 'AGENTS.md'), processTemplate(agentsTemplate, tokenDefaults), fileMode, result, targetDir);
+    }
+    catch {
+        // Fallback to hardcoded template if template file not found
+        await createFile(path.join(targetDir, 'AGENTS.md'), processTemplate(AGENTS_MD_TEMPLATE, tokenDefaults), fileMode, result, targetDir);
+    }
     // Create LUMENFLOW.md (main entry point)
-    await createFile(path.join(targetDir, 'LUMENFLOW.md'), processTemplate(LUMENFLOW_MD_TEMPLATE, tokenDefaults), options.force, result, targetDir);
+    await createFile(path.join(targetDir, 'LUMENFLOW.md'), processTemplate(LUMENFLOW_MD_TEMPLATE, tokenDefaults), fileMode, result, targetDir);
     // Create .lumenflow/constraints.md
-    await createFile(path.join(targetDir, LUMENFLOW_DIR, 'constraints.md'), processTemplate(CONSTRAINTS_MD_TEMPLATE, tokenDefaults), options.force, result, targetDir);
+    await createFile(path.join(targetDir, LUMENFLOW_DIR, 'constraints.md'), processTemplate(CONSTRAINTS_MD_TEMPLATE, tokenDefaults), fileMode, result, targetDir);
     // Create .lumenflow/agents directory with .gitkeep
     await createDirectory(path.join(targetDir, LUMENFLOW_AGENTS_DIR), result, targetDir);
-    await createFile(path.join(targetDir, LUMENFLOW_AGENTS_DIR, '.gitkeep'), '', options.force, result, targetDir);
+    await createFile(path.join(targetDir, LUMENFLOW_AGENTS_DIR, '.gitkeep'), '', options.force ? 'force' : 'skip', result, targetDir);
     // Optional: full docs scaffolding
     if (options.full) {
         await scaffoldFullDocs(targetDir, options, result, tokenDefaults);
@@ -1030,12 +1342,12 @@ export async function scaffoldProject(targetDir, options) {
     if (options.framework) {
         await scaffoldFrameworkOverlay(targetDir, options, result, tokenDefaults);
     }
-    // Scaffold vendor-specific files
-    await scaffoldVendorFiles(targetDir, options, result, tokenDefaults, vendor);
+    // Scaffold client-specific files (WU-1171: renamed from vendor)
+    await scaffoldClientFiles(targetDir, options, result, tokenDefaults, client);
     return result;
 }
 async function scaffoldFullDocs(targetDir, options, result, tokens) {
-    const tasksDir = path.join(targetDir, 'docs', '04-operations', 'tasks');
+    const tasksDir = path.join(targetDir, 'docs', DOCS_OPERATIONS_DIR, 'tasks');
     const wuDir = path.join(tasksDir, 'wu');
     const templatesDir = path.join(tasksDir, 'templates');
     await createDirectory(wuDir, result, targetDir);
@@ -1051,7 +1363,7 @@ async function scaffoldFullDocs(targetDir, options, result, tokens) {
  * WU-1083: Scaffold agent onboarding documentation
  */
 async function scaffoldAgentOnboardingDocs(targetDir, options, result, tokens) {
-    const onboardingDir = path.join(targetDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    const onboardingDir = path.join(targetDir, 'docs', DOCS_OPERATIONS_DIR, '_frameworks', 'lumenflow', 'agent', 'onboarding');
     await createDirectory(onboardingDir, result, targetDir);
     await createFile(path.join(onboardingDir, 'quick-ref-commands.md'), processTemplate(QUICK_REF_COMMANDS_TEMPLATE, tokens), options.force, result, targetDir);
     await createFile(path.join(onboardingDir, 'first-wu-mistakes.md'), processTemplate(FIRST_WU_MISTAKES_TEMPLATE, tokens), options.force, result, targetDir);
@@ -1088,34 +1400,73 @@ async function scaffoldFrameworkOverlay(targetDir, options, result, tokens) {
         FRAMEWORK_SLUG: slug,
     };
     await createFile(path.join(targetDir, FRAMEWORK_HINT_FILE), processTemplate(FRAMEWORK_HINT_TEMPLATE, frameworkTokens), options.force, result, targetDir);
-    const overlayDir = path.join(targetDir, 'docs', '04-operations', '_frameworks', slug);
+    const overlayDir = path.join(targetDir, 'docs', DOCS_OPERATIONS_DIR, '_frameworks', slug);
     await createDirectory(overlayDir, result, targetDir);
     await createFile(path.join(overlayDir, 'README.md'), processTemplate(FRAMEWORK_OVERLAY_TEMPLATE, frameworkTokens), options.force, result, targetDir);
 }
 /**
- * Scaffold vendor-specific files based on --vendor option
+ * WU-1171: Scaffold client-specific files based on --client option
+ * Updated paths: Cursor uses .cursor/rules/lumenflow.md, Windsurf uses .windsurf/rules/lumenflow.md
  */
-async function scaffoldVendorFiles(targetDir, options, result, tokens, vendor) {
+async function scaffoldClientFiles(targetDir, options, result, tokens, client) {
+    const fileMode = getFileMode(options);
     // Claude Code
-    if (vendor === 'claude' || vendor === 'all') {
-        await createFile(path.join(targetDir, 'CLAUDE.md'), processTemplate(CLAUDE_MD_TEMPLATE, tokens), options.force, result, targetDir);
+    if (client === 'claude' || client === 'all') {
+        // WU-1171: Single CLAUDE.md at root only (no .claude/CLAUDE.md duplication)
+        await createFile(path.join(targetDir, 'CLAUDE.md'), processTemplate(CLAUDE_MD_TEMPLATE, tokens), fileMode, result, targetDir);
         await createDirectory(path.join(targetDir, CLAUDE_AGENTS_DIR), result, targetDir);
-        await createFile(path.join(targetDir, CLAUDE_AGENTS_DIR, '.gitkeep'), '', options.force, result, targetDir);
-        await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), CLAUDE_SETTINGS_TEMPLATE, options.force, result, targetDir);
+        await createFile(path.join(targetDir, CLAUDE_AGENTS_DIR, '.gitkeep'), '', options.force ? 'force' : 'skip', result, targetDir);
+        await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), CLAUDE_SETTINGS_TEMPLATE, options.force ? 'force' : 'skip', result, targetDir);
         // WU-1083: Scaffold Claude skills
         await scaffoldClaudeSkills(targetDir, options, result, tokens);
         // WU-1083: Scaffold agent onboarding docs for Claude vendor (even without --full)
         await scaffoldAgentOnboardingDocs(targetDir, options, result, tokens);
     }
-    // Cursor
-    if (vendor === 'cursor' || vendor === 'all') {
-        const cursorDir = path.join(targetDir, '.cursor');
-        await createDirectory(cursorDir, result, targetDir);
-        await createFile(path.join(cursorDir, 'rules.md'), processTemplate(CURSOR_RULES_TEMPLATE, tokens), options.force, result, targetDir);
+    // WU-1171: Cursor uses .cursor/rules/lumenflow.md (not .cursor/rules.md)
+    if (client === 'cursor' || client === 'all') {
+        const cursorRulesDir = path.join(targetDir, '.cursor', 'rules');
+        await createDirectory(cursorRulesDir, result, targetDir);
+        // Try to load from template, fallback to hardcoded
+        let cursorContent;
+        try {
+            cursorContent = loadTemplate('vendors/cursor/.cursor/rules/lumenflow.md.template');
+        }
+        catch {
+            cursorContent = CURSOR_RULES_TEMPLATE;
+        }
+        await createFile(path.join(cursorRulesDir, 'lumenflow.md'), processTemplate(cursorContent, tokens), fileMode, result, targetDir);
+    }
+    // WU-1171: Windsurf uses .windsurf/rules/lumenflow.md (not .windsurfrules)
+    if (client === 'windsurf' || client === 'all') {
+        const windsurfRulesDir = path.join(targetDir, '.windsurf', 'rules');
+        await createDirectory(windsurfRulesDir, result, targetDir);
+        // Try to load from template, fallback to hardcoded
+        let windsurfContent;
+        try {
+            windsurfContent = loadTemplate('vendors/windsurf/.windsurf/rules/lumenflow.md.template');
+        }
+        catch {
+            windsurfContent = WINDSURF_RULES_TEMPLATE;
+        }
+        await createFile(path.join(windsurfRulesDir, 'lumenflow.md'), processTemplate(windsurfContent, tokens), fileMode, result, targetDir);
+    }
+    // WU-1171: Codex reads AGENTS.md directly - minimal extra config needed
+    // AGENTS.md is always created, so nothing extra needed for codex
+    // WU-1177: Cline uses .clinerules file at project root
+    if (client === 'cline' || client === 'all') {
+        // Try to load from template, fallback to hardcoded
+        let clineContent;
+        try {
+            clineContent = loadTemplate('vendors/cline/.clinerules.template');
+        }
+        catch {
+            clineContent = CLINE_RULES_TEMPLATE;
+        }
+        await createFile(path.join(targetDir, '.clinerules'), processTemplate(clineContent, tokens), fileMode, result, targetDir);
     }
     // Aider
-    if (vendor === 'aider' || vendor === 'all') {
-        await createFile(path.join(targetDir, '.aider.conf.yml'), AIDER_CONF_TEMPLATE, options.force, result, targetDir);
+    if (client === 'aider' || client === 'all') {
+        await createFile(path.join(targetDir, '.aider.conf.yml'), AIDER_CONF_TEMPLATE, fileMode, result, targetDir);
     }
 }
 /**
@@ -1128,14 +1479,62 @@ async function createDirectory(dirPath, result, targetDir) {
     }
 }
 /**
- * Create a file, respecting force option
+ * WU-1171: Create a file with support for skip, merge, and force modes
+ *
+ * @param filePath - Path to the file to create
+ * @param content - Content to write (or merge block content in merge mode)
+ * @param mode - 'skip' (default), 'merge', or 'force'
+ * @param result - ScaffoldResult to track created/skipped/merged files
+ * @param targetDir - Target directory for relative path calculation
  */
-async function createFile(filePath, content, force, result, targetDir) {
+async function createFile(filePath, content, mode, result, targetDir) {
     const relativePath = getRelativePath(targetDir, filePath);
-    if (fs.existsSync(filePath) && !force) {
+    // Handle boolean for backwards compatibility (true = force, false = skip)
+    const resolvedMode = resolveBooleanToFileMode(mode);
+    // Ensure merged/warnings arrays exist
+    result.merged = result.merged ?? [];
+    result.warnings = result.warnings ?? [];
+    const fileExists = fs.existsSync(filePath);
+    if (fileExists && resolvedMode === 'skip') {
+        result.skipped.push(relativePath);
+        return;
+    }
+    if (fileExists && resolvedMode === 'merge') {
+        handleMergeMode(filePath, content, result, relativePath);
+        return;
+    }
+    // Force mode or file doesn't exist: write new content
+    writeNewFile(filePath, content, result, relativePath);
+}
+/**
+ * Convert boolean or FileMode to FileMode
+ */
+function resolveBooleanToFileMode(mode) {
+    if (typeof mode === 'boolean') {
+        return mode ? 'force' : 'skip';
+    }
+    return mode;
+}
+/**
+ * Handle merge mode file update
+ */
+function handleMergeMode(filePath, content, result, relativePath) {
+    const existingContent = fs.readFileSync(filePath, 'utf-8');
+    const mergeResult = updateMergeBlock(existingContent, content);
+    if (mergeResult.unchanged) {
         result.skipped.push(relativePath);
         return;
     }
+    if (mergeResult.warning) {
+        result.warnings?.push(`${relativePath}: ${mergeResult.warning}`);
+    }
+    fs.writeFileSync(filePath, mergeResult.content);
+    result.merged?.push(relativePath);
+}
+/**
+ * Write a new file, creating parent directories if needed
+ */
+function writeNewFile(filePath, content, result, relativePath) {
     const parentDir = path.dirname(filePath);
     if (!fs.existsSync(parentDir)) {
         fs.mkdirSync(parentDir, { recursive: true });
@@ -1146,19 +1545,33 @@ async function createFile(filePath, content, force, result, targetDir) {
 /**
  * CLI entry point
  * WU-1085: Updated to use parseInitOptions for proper --help support
+ * WU-1171: Added --merge and --client support
  */
 export async function main() {
+    /* eslint-disable no-console -- CLI tool requires console output for user feedback */
     const opts = parseInitOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow init] Scaffolding LumenFlow project...');
-    console.log(`  Mode: ${opts.full ? 'full' : 'minimal'}`);
+    console.log(`  Mode: ${opts.full ? 'full' : 'minimal'}${opts.merge ? ' (merge)' : ''}`);
     console.log(`  Framework: ${opts.framework ?? 'none'}`);
-    console.log(`  Vendor overlays: ${opts.vendor ?? 'auto'}`);
+    console.log(`  Client: ${opts.client ?? 'auto'}`);
     console.log(`  Gate preset: ${opts.preset ?? 'none (manual config)'}`);
+    // WU-1177: Check prerequisites (non-blocking)
+    const prereqs = checkPrerequisites();
+    const failingPrereqs = Object.entries(prereqs)
+        .filter(([, check]) => !check.passed)
+        .map(([name, check]) => `${name}: ${check.version} (requires ${check.required})`);
+    if (failingPrereqs.length > 0) {
+        console.log('\nPrerequisite warnings (non-blocking):');
+        failingPrereqs.forEach((msg) => console.log(`  ! ${msg}`));
+        console.log('  Run "lumenflow doctor" for details.\n');
+    }
     const result = await scaffoldProject(targetDir, {
         force: opts.force,
         full: opts.full,
-        vendor: opts.vendor,
+        merge: opts.merge,
+        client: opts.client,
+        vendor: opts.vendor, // Backwards compatibility
         framework: opts.framework,
         gatePreset: opts.preset,
     });
@@ -1166,12 +1579,21 @@ export async function main() {
         console.log('\nCreated:');
         result.created.forEach((f) => console.log(`  + ${f}`));
     }
+    if (result.merged && result.merged.length > 0) {
+        console.log('\nMerged (LumenFlow block inserted/updated):');
+        result.merged.forEach((f) => console.log(`  ~ ${f}`));
+    }
     if (result.skipped.length > 0) {
-        console.log('\nSkipped (already exists, use --force to overwrite):');
+        console.log('\nSkipped (already exists, use --force to overwrite or --merge to insert block):');
         result.skipped.forEach((f) => console.log(`  - ${f}`));
     }
+    if (result.warnings && result.warnings.length > 0) {
+        console.log('\nWarnings:');
+        result.warnings.forEach((w) => console.log(`  ⚠ ${w}`));
+    }
     console.log('\n[lumenflow init] Done! Next steps:');
-    console.log('  1. Review LUMENFLOW.md for workflow documentation');
+    console.log('  1. Review AGENTS.md and LUMENFLOW.md for workflow documentation');
     console.log(`  2. Edit ${CONFIG_FILE_NAME} to match your project structure`);
     console.log('  3. Run: pnpm wu:create --id WU-0001 --lane <lane> --title "First WU"');
+    /* eslint-enable no-console */
 }