chati-dev 4.2.2 → 4.3.1

package/README.md

@@ -20,9 +20,9 @@
 
 ## What is Chati.dev?
 
-Chati.dev is a system that **turns AI into a structured development team**. Instead of chatting with a single AI that forgets everything between sessions, you get specialized agents — each with a clear role — working together through a defined pipeline.
+Chati.dev is a system that **turns AI into a structured development team**. Instead of chatting with a single AI that forgets everything between sessions, you get specialized agents - each with a clear role - working together through a defined pipeline.
 
-You describe what you want to build. The agents handle requirements, architecture, planning, coding, testing, and deployment — in order, with quality gates between each phase.
+You describe what you want to build. The agents handle requirements, architecture, planning, coding, testing, and deployment - in order, with quality gates between each phase.
 
 ```
 You → DISCOVER → PLAN → BUILD → DEPLOY → Done
@@ -39,9 +39,9 @@ Every decision is saved. Every artifact is validated. If you close your laptop a
 
 AI-assisted development today has three critical issues:
 
-1. **Context Loss** — AI forgets decisions across sessions, leading to inconsistent implementations
-2. **Planning Gaps** — Jumping straight to code without structured requirements leads to rework
-3. **Vendor Lock-in** — Most AI dev tools only work with one provider, limiting flexibility
+1. **Context Loss** - AI forgets decisions across sessions, leading to inconsistent implementations
+2. **Planning Gaps** - Jumping straight to code without structured requirements leads to rework
+3. **Vendor Lock-in** - Most AI dev tools only work with one provider, limiting flexibility
 
 ### The Solution
 
@@ -54,7 +54,7 @@ Chati.dev introduces **Agent-Driven Development**: a pipeline where each agent o
 ### Prerequisites
 
 - **Node.js** >= 20.0.0 ([download](https://nodejs.org/))
-- **An AI CLI** — at least one of:
+- **An AI CLI** - at least one of:
   - [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) (recommended)
   - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
   - [Codex CLI](https://github.com/openai/codex)
@@ -73,7 +73,7 @@ The wizard guides you through 4 steps:
 |------|-------------|
 | **Language** | English, Portuguese, Spanish, or French |
 | **Project Type** | Greenfield (new) or Brownfield (existing) |
-| **AI Provider** | Claude, Gemini, or Codex — auto-configures optimal models per agent |
+| **AI Provider** | Claude, Gemini, or Codex - auto-configures optimal models per agent |
 | **Confirm** | Review summary and proceed |
 
 ### 2. Activate the orchestrator
@@ -101,7 +101,7 @@ The agents guide you through each phase:
 | **BUILD** | Dev agent implements the code, task by task | Review code as it's built |
 | **DEPLOY** | DevOps agent handles git, deployment, and documentation | Confirm deployment settings |
 
-Quality gates run automatically between phases — if something doesn't meet the threshold, the system loops back and fixes it.
+Quality gates run automatically between phases. If something doesn't meet the threshold, the system loops back and fixes it.
 
 ### Monitor progress
 
@@ -118,7 +118,7 @@ npx chati-dev status --watch  # Auto-refresh every 5s
 | **Gemini CLI** | `/chati exit` | `/chati` |
 | **Codex CLI** | `$chati exit` | `$chati` |
 
-The system saves your full session state — pipeline position, current agent, decisions, and context. You resume exactly where you left off, even across days or machines.
+The system saves your full session state (pipeline position, current agent, decisions, and context). You resume exactly where you left off, even across days or machines.
 
 ---
 
@@ -126,14 +126,18 @@ The system saves your full session state — pipeline position, current agent, d
 
 | Feature | What it means |
 |---------|--------------|
-| **Specialized Agents** | Each agent has a defined mission, success criteria, and handoff protocol — not one AI trying to do everything |
+| **Specialized Agents** | Each agent has a defined mission, success criteria, and handoff protocol. Not one AI trying to do everything |
+| **Agent Teams** | Planning Team (Detail + Architect + UX + QA-Planning) and Build Team (Dev + QA-Implementation) with Wave-Based Pipeline. Teams work in parallel with peer-to-peer communication, cross-review, and intra-team quality assurance. No single agent bottleneck |
+| **Visual QA** | QA-Visual agent validates the visual experience: screenshots at 5 scroll positions, hover states, GSAP/Lenis verification, brandbook compliance. Powered by Playwright. |
+| **Premium Animations** | GSAP + ScrollTrigger + Lenis as mandatory stack for UI projects. Every page has scroll reveals, micro-interactions, and smooth scrolling. |
 | **Multi-CLI Architecture** | Choose your AI provider at install time: Claude, Gemini, or Codex. Each agent gets the optimal model for that provider |
-| **Quality Gates** | Every phase is validated before moving forward. 3-tier verdicts: APPROVED, NEEDS_REVISION, or BLOCKED |
-| **Context Persistence** | Sessions survive restarts. Close your IDE, come back next week — the system remembers everything |
+| **Quality Gates** | Every phase is validated before moving forward, including QA-Visual for visual quality. 3-tier verdicts: APPROVED, NEEDS_REVISION, or BLOCKED |
+| **Fault Vector Protocol** | Root Layer Routing classifies bugs by origin (INTENT/SPEC/CODE/DEFER). Evidence-Bound Verdicts, Decision Trail, and Echo Detection prevent cyclical rework |
+| **Context Persistence** | Sessions survive restarts. Close your IDE, come back next week - the system remembers everything |
 | **Session Lock** | Once activated, you stay inside the system. No accidentally "falling out" into generic AI mode |
-| **Multi-Terminal** | Autonomous agents run in parallel in separate terminals. Detail, Architect Manager, and UX Manager coordinate sub-agent pools simultaneously |
+| **Multi-Terminal** | Autonomous agents run in parallel. Planning Team (Detail + Architect + UX + QA-Planning) and Build Team (Dev + QA-Implementation) coordinate via peer-to-peer mailbox |
 | **Memory System** | The system learns from mistakes. Gotchas are captured automatically and recalled when relevant |
-| **Execution Profiles** | Three profiles — explore (read-only), guided (default), autonomous (gate >= 95%) — with safety net and circuit breaker |
+| **Execution Profiles** | Three profiles: explore (read-only), guided (default), autonomous (gate >= 95%). Includes safety net and circuit breaker |
 | **IDE-Agnostic** | Works with Claude Code, VS Code, Cursor, Gemini CLI, Codex CLI, and AntiGravity |
 | **4 Languages** | Interface supports English, Portuguese, Spanish, and French. Artifacts are always generated in English |
 | **Supply Chain Security** | Every file is cryptographically signed (Ed25519). Tampered packages are blocked on install |
@@ -182,7 +186,7 @@ Each provider uses its own CLI syntax. Chati.dev handles this transparently:
 | Gemini | `gemini --model <id>` | `gemini --model gemini-2.5-pro` |
 | Codex | `codex exec -m <id>` | `codex exec -m gpt-5.3-codex` |
 
-Prompts are piped via stdin for all providers. You can override individual agent models in `chati.dev/config.yaml` under `agent_overrides`.
+Prompts are piped via stdin for all providers. You can override individual agent models in `.chati.dev/config.yaml` under `agent_overrides`.
 
 ---
 
@@ -207,10 +211,9 @@ The system starts in `guided` mode. Transition to `autonomous` requires both QA
 | Phase | Agents | What they do |
 |-------|--------|-------------|
 | **DISCOVER** | Greenfield WU, Brownfield WU, Brief | Interview you, understand your project, extract requirements |
-| **PLAN** | Detail, Architect Manager (System Architect + Data Engineer), UX Manager (Brand Architect + Researcher + Component Engineer), Phases, Tasks | Create PRD, design architecture, define UX, break work into phases and tasks |
-| **BUILD** | Dev | Implement code task by task, following the plan |
+| **PLAN** | Planning Team (Detail + Architect + UX + QA-Planning), Phases, Tasks | Create PRD, architecture, UX spec with cross-review. QA-Planning validates all 3 artifacts before the team dissolves |
+| **BUILD** | Build Team (Dev + QA-Implementation) with Wave-Based Pipeline. After build: QA-Visual validates visual quality. | Implement code task by task, with per-task quality review and visual validation |
 | **DEPLOY** | DevOps | Handle git operations, deployment, and documentation |
-| **Quality** | QA-Planning, QA-Implementation | Validate plan coherence (>= 95%) and code quality (>= 95%) between phases |
 
 ### How the Pipeline Works
 
@@ -230,30 +233,30 @@ The system starts in `guided` mode. Transition to `autonomous` requires both QA
        │    WU interviews you → Brief compiles  │
        │    requirements into a structured doc  │
        │                                        │
-       ├─ Spawns separate terminals ────────────┐
-       │   (using your selected AI provider)    │
+       ├─ Spawns Planning Team ──────────────────┐
+       │   (4 agents, peer communication)       │
        │                                        │
-       │    PLAN (autonomous, parallel)         │
+       │    PLAN                                │
        │    Detail ───┐                         │
        │    Architect ├─ run simultaneously     │
-       │    UX ───────┘                         │
+       │    UX ───────┘  with cross-review      │
+       │         │                              │
+       │    QA-Planning activates after trio    │
+       │    Reviews all 3 artifacts (>= 95%)   │
+       │    Sends feedback via mailbox          │
+       │    Team dissolves when approved        │
+       │         │                              │
        │    Then: Phases → Tasks                │
        │                                        │
-       ├─ Quality Gate ─────────────────────────┐
-       │                                        │
-       │    QA-Planning validates the plan      │
-       │    Must score >= 95% to proceed        │
-       │                                        │
-       ├─ Spawns terminal(s) ───────────────────┐
+       ├─ Spawns Build Team ────────────────────┐
+       │   (2 agents, Wave-Based Pipeline)      │
        │                                        │
        │    BUILD                               │
-       │    Dev implements tasks (parallel      │
-       │    when tasks are independent)         │
-       │                                        │
-       ├─ Quality Gate ─────────────────────────┐
-       │                                        │
-       │    QA-Implementation validates code    │
-       │    Tests + static analysis + coverage  │
+       │    Build Waves: Dev + QA in parallel   │
+       │    Cleanup Wave: fixes remaining warns  │
+       │    Visual QA Wave: QA-Visual validates  │
+       │      screenshots, GSAP/Lenis, brandbook │
+       │    Final QA: Triple Review             │
        │                                        │
        └─ Spawns terminal ──────────────────────┐
                                                 │
@@ -277,18 +280,18 @@ Three systems operate transparently behind the pipeline:
 
 ### Constitution
 
-The system is governed by a **22-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
+The system is governed by a **23-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
 
-- **Agent Governance** — Every agent has a defined mission, scope, and success criteria
-- **Quality Standards** — Minimum 95% score on quality gates. 3-tier verdicts (APPROVED / NEEDS_REVISION / BLOCKED)
-- **Security** — No secrets in system files. No destructive operations without confirmation. Ed25519 supply chain verification
-- **Mode Governance** — Planning mode can't modify project code. Build mode has full access
-- **Session Lock** — Once activated, all messages route through the orchestrator
-- **Model Governance** — Each agent runs on its designated model, enforced by the CLI adapter
-- **Execution Profiles** — Explore, guided, and autonomous modes with safety net and circuit breaker
-- **Multi-CLI** — Provider-agnostic architecture with adapter pattern and automatic model mapping
-- **Agent Teams** — Real-time peer communication between agents with cross-review, per-task QA, and sealed-bid quality assurance
-- **Fault Vector Protocol** — Root Layer Routing, Evidence-Bound Verdicts, Decision Trail, and Echo Detection for adversarial quality
+- **Agent Governance** - Every agent has a defined mission, scope, and success criteria
+- **Quality Standards** - Minimum 95% score on quality gates. 3-tier verdicts (APPROVED / NEEDS_REVISION / BLOCKED)
+- **Security** - No secrets in system files. No destructive operations without confirmation. Ed25519 supply chain verification
+- **Mode Governance** - Planning mode can't modify project code. Build mode has full access
+- **Session Lock** - Once activated, all messages route through the orchestrator
+- **Model Governance** - Each agent runs on its designated model, enforced by the CLI adapter
+- **Execution Profiles** - Explore, guided, and autonomous modes with safety net and circuit breaker
+- **Multi-CLI** - Provider-agnostic architecture with adapter pattern and automatic model mapping
+- **Agent Teams** - Real-time peer communication between agents with cross-review, per-task QA, and sealed-bid quality assurance
+- **Fault Vector Protocol** - Root Layer Routing, Evidence-Bound Verdicts, Decision Trail, and Echo Detection for adversarial quality
 
 ---
 
@@ -350,7 +353,31 @@ All IDEs use a thin router file that points to the same orchestrator. Your proje
 
 ## Project Structure
 
-The structure below shows the Claude Code layout (default). Gemini and Codex get equivalent files in their native locations.
+At a glance, an installed project looks like this:
+
+```
+your-project/
+├── CLAUDE.md              # Project context (auto-generated)
+├── CLAUDE.local.md        # Runtime session lock
+├── artifacts/             # Pipeline output (visible to user)
+│   ├── 0-WU/
+│   ├── 1-Brief/
+│   ├── 2-PRD/
+│   ├── 3-Architecture/
+│   ├── 4-UX/
+│   └── handoffs/
+├── .chati.dev/            # Framework (hidden)
+│   ├── agents/
+│   ├── hooks/
+│   ├── orchestrator/
+│   ├── constitution.md
+│   └── config.yaml
+├── .chati/                # Runtime session state (hidden)
+├── .claude/               # Claude Code settings + rules (hidden)
+└── .gitignore
+```
+
+The full layout below shows the Claude Code layout (default). Gemini and Codex get equivalent files in their native locations.
 
 ```
 your-project/
@@ -388,8 +415,8 @@ your-project/
 ├── AGENTS.md                     # Project context with inline governance
 ├── AGENTS.override.md            # Runtime state / session lock (gitignored)
 │
-│── # ─── Framework ─────────────────────
-├── chati.dev/
+│── # ─── Framework (hidden) ────────────
+├── .chati.dev/
 │   ├── orchestrator/             # Main orchestrator
 │   ├── agents/                   # Agent definitions
 │   │   ├── discover/             # Greenfield WU, Brownfield WU, Brief
@@ -410,7 +437,7 @@ your-project/
 │   ├── data/                     # Entity registry
 │   ├── i18n/                     # EN, PT, ES, FR translations
 │   ├── migrations/               # Version migration scripts
-│   ├── constitution.md           # 22 Articles + Preamble
+│   ├── constitution.md           # 23 Articles + Preamble
 │   └── config.yaml               # System configuration
 └── packages/
     └── chati-dev/                # CLI + runtime engine
@@ -447,7 +474,7 @@ Upgrades include automatic backup, migrations, validation, and config merging. R
 
 ## Contributing
 
-We welcome contributions — agents, templates, workflows, translations, and CLI improvements. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
+We welcome contributions: agents, templates, workflows, translations, and CLI improvements. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
 
 ## Security
 
@@ -455,11 +482,11 @@ For security concerns, see our [Security Policy](.github/SECURITY.md).
 
 ## License
 
-[Elastic License 2.0](LICENSE) — free to use for any purpose; you may not offer it as a hosted/managed service to third parties or remove licensing notices.
+[Elastic License 2.0](LICENSE) - free to use for any purpose; you may not offer it as a hosted/managed service to third parties or remove licensing notices.
 
 ---
 
 <p align="center">
   <sub>Built with structure, validated by agents, governed by constitution.</sub><br>
-  <sub>Chati.dev v4.2 "Phoenix" &copy; 2026</sub>
+  <sub>Chati.dev v4.3.0 "Phoenix" &copy; 2026</sub>
 </p>

package/bin/chati.js

@@ -9,6 +9,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 
 import { logBanner } from '../src/utils/logger.js';
+import { resolveFrameworkDir } from '../src/utils/framework-dir.js';
 
 function showBanner() {
   let logoText;
@@ -22,7 +23,32 @@ function showBanner() {
 
 const args = process.argv.slice(2);
 const command = args[0] || 'init';
-const targetDir = resolve(args.find(a => !a.startsWith('-') && a !== command) || process.cwd());
+// Known subcommands and agent names that should NOT be mistaken for targetDir paths.
+// Without this, `chati orchestrate advance --agent detail` resolves targetDir to `<cwd>/detail/`.
+const KNOWN_SUBCOMMANDS = new Set([
+  // CLI subcommands
+  'next', 'advance', 'init', 'status', 'validate-handoff', 'deviation', 'exit',
+  'providers', 'detect-flow', 'backlog', 'qa-plan-score', 'qa-impl-score', 'scan',
+  'spawn-team', 'team-status', 'team-dissolve',
+  'stats', 'list', 'search', 'clean', 'check', // memory/registry subcommands
+  'scaffold', // scaffold preset commands
+  // Scaffold preset ids (prevent consumption as targetDir after `scaffold <preset>`)
+  'motion-premium',
+  // Agent names (prevent consumption as targetDir when passed via --agent flag)
+  'greenfield-wu', 'brownfield-wu', 'brief', 'detail', 'architect', 'ux',
+  'phases', 'tasks', 'qa-planning', 'qa-implementation', 'qa-visual', 'dev', 'devops',
+]);
+// Skip values that follow --flag patterns (e.g., --agent detail, --score 100)
+const flagValues = new Set();
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('--') && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+    flagValues.add(args[i + 1]);
+  }
+}
+const targetDir = resolve(
+  args.find(a => !a.startsWith('-') && a !== command && !KNOWN_SUBCOMMANDS.has(a) && !flagValues.has(a))
+  || process.cwd()
+);
 
 async function main() {
   switch (command) {
@@ -109,12 +135,44 @@ async function main() {
       console.log('  Syncing framework files...');
       try {
         const { copyFrameworkFiles } = await import('../src/installer/core.js');
-        copyFrameworkFiles(join(targetDir, 'chati.dev'));
+        copyFrameworkFiles(join(targetDir, resolveFrameworkDir(targetDir)));
         console.log('  Framework files synced.');
       } catch (err) {
         console.log(`  Framework sync skipped: ${err.message}`);
       }
 
+      // 2.6. Re-bundle CLI (Bug 4 part 3, v4.3.1+) — refreshes .chati.dev/_cli/
+      // and writes version.json so chati-router.js mismatch detection clears
+      // on the next invocation.
+      console.log('  Re-bundling CLI...');
+      try {
+        const { copyCliSource, copyCliDependencies } = await import('../src/installer/core.js');
+        const { writeFileSync } = await import('fs');
+        const fwDir = resolveFrameworkDir(targetDir);
+        const frameworkDir = join(targetDir, fwDir);
+        copyCliSource(join(__dirname, '..', 'src'), join(frameworkDir, '_cli'));
+        copyCliDependencies(join(__dirname, '..'), join(frameworkDir, '_cli', 'node_modules'));
+        writeFileSync(
+          join(frameworkDir, '_cli', 'version.json'),
+          JSON.stringify({ version: pkg.version, bundled_at: new Date().toISOString() }, null, 2),
+        );
+        console.log('  CLI re-bundled.');
+      } catch (err) {
+        console.log(`  CLI rebundle skipped: ${err.message}`);
+      }
+
+      // 2.6. Detect tracked framework files and warn user (non-blocking)
+      try {
+        const { detectTrackedFrameworkFiles } = await import('../src/upgrade/tracked-files-detector.js');
+        const { renderTrackedFilesWarning } = await import('../src/upgrade/user-messages.js');
+        const trackedFiles = detectTrackedFrameworkFiles(targetDir);
+        if (trackedFiles.length > 0) {
+          process.stdout.write(renderTrackedFilesWarning(trackedFiles));
+        }
+      } catch {
+        // Non-critical — skip silently if git is unavailable
+      }
+
       // 3. Validate
       console.log('  Validating...');
       const validation = await validateInstallation(targetDir);
@@ -305,7 +363,7 @@ async function main() {
       console.log('  - Specialized agents across DISCOVER, PLAN, BUILD, DEPLOY phases');
       console.log('  - 6 workflow blueprints');
       console.log('  - 6 templates');
-      console.log('  - Constitution (19 Articles + Preamble)');
+      console.log('  - Constitution (23 Articles + Preamble)');
       console.log('  - Dashboard TUI');
       console.log('  - Upgrade system with migrations');
       console.log('  - 6 IDE support');
@@ -357,6 +415,12 @@ Intelligence:
   npx chati-dev registry [stats|check]             Entity registry
   npx chati-dev health                             System health check
 
+Scaffold:
+  npx chati-dev scaffold                           List available scaffold presets
+  npx chati-dev scaffold <preset>                  Apply a scaffold preset (e.g. motion-premium)
+  npx chati-dev scaffold <preset> --dry-run        Show what would be applied, write nothing
+  npx chati-dev scaffold <preset> --force          Overwrite existing files
+
 License:
   npx chati-dev activate [--key=CHATI-XXXX]        Activate license on this machine
   npx chati-dev deactivate                         Remove license key locally
@@ -402,10 +466,111 @@ Telemetry:
       break;
     }
 
+    case 'scaffold': {
+      const sub = args[1];
+      const {
+        resolveScaffoldSource, listPresets, applyScaffold, syncBrand, upgradeScaffold,
+      } = await import('../src/installer/scaffold-applier.js');
+
+      const scaffoldSrc = (() => {
+        try { return resolveScaffoldSource(targetDir); }
+        catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+      })();
+
+      if (!sub || sub === 'list') {
+        const presets = listPresets(scaffoldSrc);
+        if (presets.length === 0) {
+          console.log('No scaffold presets found.');
+        } else {
+          console.log('Available scaffold presets:\n');
+          for (const p of presets) {
+            console.log(`  ${p.id}@${p.version}`);
+            if (p.description) console.log(`    ${p.description}`);
+          }
+          console.log(`\nApply: npx chati-dev scaffold <preset-id>`);
+        }
+        break;
+      }
+
+      const preset = sub;
+      const dryRun = args.includes('--dry-run');
+      const force = args.includes('--force');
+
+      if (args.includes('--sync-brand')) {
+        try { syncBrand(); }
+        catch (e) { console.log(e.message); process.exit(1); }
+        break;
+      }
+      if (args.includes('--upgrade')) {
+        try { upgradeScaffold(); }
+        catch (e) { console.log(e.message); process.exit(1); }
+        break;
+      }
+
+      let result;
+      try {
+        result = applyScaffold({
+          projectDir: targetDir,
+          scaffoldSourceDir: scaffoldSrc,
+          preset,
+          dryRun,
+          force,
+        });
+      } catch (e) {
+        console.error(`Error: ${e.message}`);
+        process.exit(1);
+      }
+
+      const verb = dryRun ? 'Would apply' : 'Applied';
+      console.log(`${verb} scaffold "${result.preset}@${result.version}" — ${result.applied.length} files:\n`);
+      for (const f of result.applied) console.log(`  + ${f}`);
+      if (result.skipped.length > 0) {
+        console.log(`\nSkipped ${result.skipped.length} file(s):`);
+        for (const s of result.skipped) console.log(`  - ${s.target}  (${s.reason})`);
+      }
+      console.log(`\nBrand source: ${result.brandSource}`);
+      if (result.manifestPath) {
+        console.log(`Manifest:     ${result.manifestPath}`);
+      }
+      if (result.skipped.some(s => s.reason === 'already-exists')) {
+        console.log('\nTip: use --force to overwrite existing files.');
+      }
+      break;
+    }
+
     case 'orchestrate': {
-      const { runOrchestrate } = await import('../src/orchestrator/cli.js');
       const subCommand = args[1] || 'next';
-      await runOrchestrate(subCommand, args.slice(1), targetDir);
+      // Validate subcommand exists in KNOWN_SUBCOMMANDS to prevent misparsing
+      // (e.g., `chati orchestrate xyz` should not silently create cwd/xyz/ as targetDir)
+      const VALID_ORCHESTRATE_SUBS = new Set([
+        'next', 'advance', 'init', 'status', 'validate-handoff',
+        'deviation', 'exit', 'providers', 'detect-flow', 'backlog',
+        'qa-plan-score', 'qa-impl-score', 'scan',
+        'spawn-team', 'team-status', 'team-dissolve',
+      ]);
+      if (!VALID_ORCHESTRATE_SUBS.has(subCommand)) {
+        console.error(`Error: Unknown orchestrate subcommand "${subCommand}".`);
+        console.error(`Valid: ${[...VALID_ORCHESTRATE_SUBS].join(', ')}`);
+        process.exit(1);
+      }
+      // Reject positional args after subcommand (orchestrate accepts only --flags).
+      // Prevents `chati orchestrate init <free-text>` from being misparsed as targetDir.
+      const orchArgs = args.slice(2);
+      const stray = orchArgs.find((a, i) => {
+        if (a.startsWith('-')) return false;
+        const prev = i > 0 ? orchArgs[i - 1] : null;
+        // skip values that follow a --flag
+        if (prev && prev.startsWith('--')) return false;
+        return true;
+      });
+      if (stray) {
+        console.error(`Error: Unexpected positional argument "${stray}" for orchestrate ${subCommand}.`);
+        console.error('orchestrate subcommands accept only --flag arguments. To set the project name, use --name "<name>".');
+        process.exit(1);
+      }
+      // targetDir for orchestrate is ALWAYS cwd (or auto-resolved by handleInit)
+      const { runOrchestrate } = await import('../src/orchestrator/cli.js');
+      await runOrchestrate(subCommand, args.slice(1), process.cwd());
       break;
     }