@cluesmith/codev 2.0.0-rc.7 → 2.0.0-rc.70

package/dist/terminal/shepherd-replay-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shepherd-replay-buffer.d.ts","sourceRoot":"","sources":["../../src/terminal/shepherd-replay-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;gBACS,QAAQ,GAAE,MAAe;IAIrC;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0CnC;;;OAGG;IACH,aAAa,IAAI,MAAM;IAMvB,sCAAsC;IACtC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0CAA0C;IAC1C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,+BAA+B;IAC/B,KAAK,IAAI,IAAI;CAKd"}

package/dist/terminal/shepherd-replay-buffer.js

@@ -0,0 +1,94 @@
+/**
+ * Standalone replay buffer for the shepherd process.
+ *
+ * Unlike RingBuffer (which stores lines), this stores raw byte chunks
+ * to preserve exact terminal output including escape sequences. It tracks
+ * the total bytes stored and evicts oldest chunks when the limit is exceeded.
+ *
+ * This module has NO dependencies beyond Node.js built-ins so the shepherd
+ * process doesn't need to pull in the full package dependency tree.
+ */
+export class ShepherdReplayBuffer {
+    chunks = [];
+    totalBytes = 0;
+    maxLines;
+    lineCount = 0;
+    /**
+     * @param maxLines Maximum number of lines to retain. Lines are delimited
+     *   by newline characters in the raw data stream.
+     */
+    constructor(maxLines = 10_000) {
+        this.maxLines = maxLines;
+    }
+    /**
+     * Append raw PTY output data to the buffer.
+     * Evicts oldest chunks if the line count exceeds maxLines.
+     */
+    append(data) {
+        const buf = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
+        if (buf.length === 0)
+            return;
+        // Count newlines in this chunk
+        let newLines = 0;
+        for (let i = 0; i < buf.length; i++) {
+            if (buf[i] === 0x0a)
+                newLines++;
+        }
+        this.chunks.push(buf);
+        this.totalBytes += buf.length;
+        this.lineCount += newLines;
+        // Evict oldest chunks if we've exceeded the line limit
+        while (this.lineCount > this.maxLines && this.chunks.length > 1) {
+            const oldest = this.chunks[0];
+            let removedLines = 0;
+            for (let i = 0; i < oldest.length; i++) {
+                if (oldest[i] === 0x0a)
+                    removedLines++;
+            }
+            this.chunks.shift();
+            this.totalBytes -= oldest.length;
+            this.lineCount -= removedLines;
+        }
+        // Handle edge case: single chunk exceeds line limit.
+        // Trim from the front to keep only the last maxLines lines.
+        if (this.lineCount > this.maxLines && this.chunks.length === 1) {
+            const chunk = this.chunks[0];
+            let linesToSkip = this.lineCount - this.maxLines;
+            let offset = 0;
+            while (linesToSkip > 0 && offset < chunk.length) {
+                if (chunk[offset] === 0x0a)
+                    linesToSkip--;
+                offset++;
+            }
+            this.chunks[0] = chunk.subarray(offset);
+            this.totalBytes = this.chunks[0].length;
+            this.lineCount = this.maxLines;
+        }
+    }
+    /**
+     * Get all buffered data as a single concatenated Buffer.
+     * Used for the REPLAY frame on reconnection.
+     */
+    getReplayData() {
+        if (this.chunks.length === 0)
+            return Buffer.alloc(0);
+        if (this.chunks.length === 1)
+            return this.chunks[0];
+        return Buffer.concat(this.chunks);
+    }
+    /** Current number of bytes stored. */
+    get size() {
+        return this.totalBytes;
+    }
+    /** Approximate number of lines stored. */
+    get lines() {
+        return this.lineCount;
+    }
+    /** Clear all buffered data. */
+    clear() {
+        this.chunks = [];
+        this.totalBytes = 0;
+        this.lineCount = 0;
+    }
+}
+//# sourceMappingURL=shepherd-replay-buffer.js.map

package/dist/terminal/shepherd-replay-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shepherd-replay-buffer.js","sourceRoot":"","sources":["../../src/terminal/shepherd-replay-buffer.ts"],"names":[],"mappings":"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"}

package/dist/terminal/ws-protocol.d.ts

@@ -0,0 +1,27 @@
+/**
+ * WebSocket frame encoding/decoding for terminal communication.
+ *
+ * Hybrid protocol:
+ * - 0x00 prefix: Control frame (remainder is UTF-8 JSON)
+ * - 0x01 prefix: Data frame (remainder is raw PTY bytes)
+ */
+export declare const FRAME_CONTROL = 0;
+export declare const FRAME_DATA = 1;
+export interface ControlMessage {
+    type: 'resize' | 'ping' | 'pong' | 'pause' | 'resume' | 'error';
+    payload: Record<string, unknown>;
+}
+/** Encode a control message into a binary frame. */
+export declare function encodeControl(msg: ControlMessage): Buffer;
+/** Encode raw PTY data into a binary frame. */
+export declare function encodeData(data: Buffer | string): Buffer;
+export type DecodedFrame = {
+    type: 'control';
+    message: ControlMessage;
+} | {
+    type: 'data';
+    data: Buffer;
+};
+/** Decode a received WebSocket frame. */
+export declare function decodeFrame(frame: Buffer): DecodedFrame;
+//# sourceMappingURL=ws-protocol.d.ts.map

package/dist/terminal/ws-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-protocol.d.ts","sourceRoot":"","sources":["../../src/terminal/ws-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,aAAa,IAAO,CAAC;AAClC,eAAO,MAAM,UAAU,IAAO,CAAC;AAE/B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAChE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAOzD;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAMxD;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAmBvD"}

package/dist/terminal/ws-protocol.js

@@ -0,0 +1,44 @@
+/**
+ * WebSocket frame encoding/decoding for terminal communication.
+ *
+ * Hybrid protocol:
+ * - 0x00 prefix: Control frame (remainder is UTF-8 JSON)
+ * - 0x01 prefix: Data frame (remainder is raw PTY bytes)
+ */
+export const FRAME_CONTROL = 0x00;
+export const FRAME_DATA = 0x01;
+/** Encode a control message into a binary frame. */
+export function encodeControl(msg) {
+    const json = JSON.stringify(msg);
+    const jsonBuf = Buffer.from(json, 'utf-8');
+    const frame = Buffer.allocUnsafe(1 + jsonBuf.length);
+    frame[0] = FRAME_CONTROL;
+    jsonBuf.copy(frame, 1);
+    return frame;
+}
+/** Encode raw PTY data into a binary frame. */
+export function encodeData(data) {
+    const dataBuf = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
+    const frame = Buffer.allocUnsafe(1 + dataBuf.length);
+    frame[0] = FRAME_DATA;
+    dataBuf.copy(frame, 1);
+    return frame;
+}
+/** Decode a received WebSocket frame. */
+export function decodeFrame(frame) {
+    if (frame.length === 0) {
+        throw new Error('Empty frame');
+    }
+    const prefix = frame[0];
+    const payload = frame.subarray(1);
+    if (prefix === FRAME_CONTROL) {
+        const json = payload.toString('utf-8');
+        const message = JSON.parse(json);
+        return { type: 'control', message };
+    }
+    if (prefix === FRAME_DATA) {
+        return { type: 'data', data: payload };
+    }
+    throw new Error(`Unknown frame prefix: 0x${prefix.toString(16)}`);
+}
+//# sourceMappingURL=ws-protocol.js.map

package/dist/terminal/ws-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-protocol.js","sourceRoot":"","sources":["../../src/terminal/ws-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAClC,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC;AAO/B,oDAAoD;AACpD,MAAM,UAAU,aAAa,CAAC,GAAmB;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,KAAK,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC;IACzB,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,UAAU,CAAC,IAAqB;IAC9C,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;IACtB,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AAMD,yCAAyC;AACzC,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAElC,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC;QACnD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "2.0.0-rc.7",
+  "version": "2.0.0-rc.70",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -14,32 +14,46 @@
     "dist",
     "bin",
     "skeleton",
-    "templates"
+    "templates",
+    "dashboard/dist"
   ],
   "scripts": {
-    "build": "tsc && npm run copy-skeleton",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc && npm run build:dashboard && npm run copy-skeleton",
+    "build:dashboard": "cd dashboard && npm install && npm run build",
+    "dev:dashboard": "cd dashboard && npm run dev",
     "copy-skeleton": "rm -rf skeleton && cp -r ../../codev-skeleton skeleton",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "test": "vitest",
+    "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
+    "test:e2e:watch": "vitest --config vitest.e2e.config.ts",
+    "test:e2e:playwright": "npx playwright test",
+    "test:e2e:cli": "npm run build && vitest run --config vitest.cli.config.ts",
+    "postinstall": "node -e \"try{require('fs').chmodSync(require('path').join(require.resolve('node-pty'),'..','..','prebuilds',process.platform+'-'+process.arch,'spawn-helper'),0o755)}catch{}\"",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.41",
     "@google/genai": "^1.0.0",
     "better-sqlite3": "^12.5.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "glob": "^11.0.0",
-    "http-proxy": "^1.18.1",
+    "js-yaml": "^4.1.0",
+    "node-pty": "^1.1.0",
     "open": "^10.1.0",
     "tree-kill": "^1.2.2",
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.0",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/http-proxy": "^1.17.17",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.1",
     "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "playwright": "^1.58.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.0.15"

package/skeleton/.claude/skills/af/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: af
+description: Agent Farm CLI quick reference. Use when running af commands to check correct syntax, subcommands, and flags. Prevents guessing at command names.
+disable-model-invocation: false
+---
+
+# Agent Farm Quick Reference
+
+## Tower (Dashboard Server)
+
+```bash
+af tower start             # Start Tower on port 4100
+af tower stop              # Stop Tower
+af tower log               # Tail Tower logs
+af tower status            # Check if Tower is running
+```
+
+There is NO `af tower restart` — use `af tower stop && af tower start`.
+
+## Dashboard
+
+```bash
+af dash start              # Start architect dashboard for current project
+af dash stop               # Stop dashboard for current project
+af dash open               # Open dashboard in browser
+```
+
+## Builder Management
+
+```bash
+af spawn -p 0003           # Spawn builder for spec (strict mode, default)
+af spawn --soft -p 0003    # Spawn builder (soft mode)
+af spawn --issue 42        # Spawn builder for a bugfix
+af spawn -p 0003 --resume  # Resume builder in existing worktree
+af status                  # Check all builder status
+af cleanup --project 0003  # Clean up builder worktree (safe)
+af cleanup --project 0003 -f  # Force cleanup
+```
+
+### Resuming Builders
+
+When a builder's Claude process dies but the worktree and porch state survive,
+use `--resume` to restart it without recreating the worktree:
+
+```bash
+af spawn -p 0003 --resume
+```
+
+This reuses the existing `.builders/0003` worktree, creates a fresh terminal
+session registered with the Tower (so it appears in the dashboard), and lets
+porch pick up from whatever phase the builder was in. Works with all spawn
+modes: `-p`, `--issue`, `--task`, `--protocol`, `--worktree`.
+
+## Utility
+
+```bash
+af util                    # Open utility shell
+af open file.ts            # Open file in annotation viewer
+af ports list              # List port allocations
+af send <builder> "msg"    # Send message to a builder
+```
+
+## Configuration
+
+Edit `af-config.json` at project root to customize shell commands.
+
+```json
+{
+  "shell": {
+    "architect": "claude",
+    "builder": "claude",
+    "shell": "bash"
+  }
+}
+```
+
+## Pre-Spawn Checklist
+
+**Before `af spawn`, commit all local changes.** Builders work in git worktrees
+branched from HEAD — uncommitted files (specs, plans, codev updates) are invisible
+to the builder. The spawn command will refuse if the worktree is dirty (override
+with `--force`).
+
+## Common Mistakes
+
+- **Spawning with uncommitted changes** — builder won't see specs, plans, or codev updates
+- There is NO `codev tower` command — Tower is managed via `af tower`
+- There is NO `restart` subcommand — stop then start
+- There is NO `af start` for Tower — use `af tower start` or `af dash start`

package/skeleton/.claude/skills/codev/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: codev
+description: Codev project management CLI quick reference. Use when running codev commands to check correct syntax for init, adopt, update, and doctor.
+disable-model-invocation: false
+---
+
+# codev - Project Management CLI
+
+## Commands
+
+```bash
+codev init [name]          # Create a new codev project
+codev init my-app -y       # Non-interactive with defaults
+codev adopt                # Add codev to existing project (run from project root)
+codev adopt -y             # Skip conflict prompts
+codev update               # Update protocols, roles, skills from installed package
+codev update --dry-run     # Preview changes without applying
+codev update --force       # Force overwrite all framework files
+codev doctor               # Check system dependencies
+```
+
+## What Each Command Does
+
+### codev init
+Creates a new project directory with codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, .claude/skills/, af-config.json, .gitignore.
+
+### codev adopt
+Adds codev to the **current directory**. Detects existing CLAUDE.md/AGENTS.md and creates `.codev-new` versions for merge if conflicts exist. Spawns Claude to merge automatically.
+
+### codev update
+Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). If you've customized a framework file, creates a `.codev-new` version for manual merge.
+
+### codev doctor
+Checks that all required dependencies are installed: Node.js (>=18), git (>=2.5), gh (authenticated), and at least one AI CLI (Claude, Gemini, or Codex).
+
+## Common Mistakes
+
+- There is NO `codev tower` command — Tower is managed via `af tower start` / `af tower stop`
+- `codev init` creates a **new directory** — use `codev adopt` for existing projects
+- `codev update` only updates framework files — it will never overwrite your specs/plans/reviews
+- Always run `codev adopt` and `codev update` from the **project root directory**

package/skeleton/.claude/skills/consult/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: consult
+description: AI consultation CLI quick reference. Use when running consult commands to check syntax for PR reviews, spec reviews, plan reviews, and general queries across Gemini, Codex, and Claude.
+disable-model-invocation: false
+---
+
+# consult - AI Consultation CLI
+
+## Synopsis
+
+```bash
+consult -m <model> <subcommand> [args] [options]
+```
+
+The `-m` / `--model` flag is **always required**.
+
+## Models
+
+| Model | Alias | Speed | Approach |
+|-------|-------|-------|----------|
+| `gemini` | `pro` | ~120-150s | Pure text analysis, fast |
+| `codex` | `gpt` | ~200-250s | Shell command exploration, thorough |
+| `claude` | `opus` | ~60-120s | Balanced tool use |
+
+## Subcommands
+
+```bash
+consult -m gemini pr 42              # Review a pull request
+consult -m codex spec 42             # Review a specification
+consult -m gemini plan 42            # Review an implementation plan
+consult -m claude general "query"    # General question (quoted string)
+```
+
+## Options
+
+```bash
+-n, --dry-run              # Show command without running
+-t, --type <type>          # Review type (spec-review, plan-review, impl-review, pr-ready, integration-review)
+-r, --role <role>          # Custom role from codev/roles/ (without .md extension)
+```
+
+## Review Types (--type)
+
+| Type | Stage | Use Case |
+|------|-------|----------|
+| `spec-review` | conceived | Review spec completeness |
+| `plan-review` | specified | Review implementation plan |
+| `impl-review` | implementing | Review code implementation |
+| `pr-ready` | implemented | Final check before PR |
+| `integration-review` | committed | Architect's integration review |
+
+Review type prompts live in `codev/consult-types/` and can be customized.
+
+## Parallel Consultation (3-Way / cmap)
+
+Run all three models in parallel for thorough reviews:
+
+```bash
+consult -m gemini spec 42 &
+consult -m codex spec 42 &
+consult -m claude spec 42 &
+wait
+```
+
+Or from Claude Code, use **cmap** pattern: three parallel background Bash calls.
+
+## Custom Roles
+
+```bash
+consult -m gemini --role security-reviewer pr 42
+consult -m codex --role architect general "Review this design"
+```
+
+Roles are markdown files in `codev/roles/`. Create your own by adding `.md` files there.
+
+## Common Mistakes
+
+- The `-m` flag is **required** — `consult pr 42` will fail without it
+- PR numbers are GitHub PR numbers, not spec numbers
+- Spec/plan numbers match the `0042` prefix in filenames (pass just `42`, not `0042`)
+- General queries must be **quoted**: `consult -m gemini general "your question here"`

package/skeleton/.claude/skills/generate-image/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: generate-image
+description: AI image generation CLI using Gemini. Use when generating images, checking syntax for resolution, aspect ratio, and reference image options.
+disable-model-invocation: false
+---
+
+# generate-image - AI Image Generation
+
+Uses Google Gemini (gemini-3-pro-image-preview) to generate images from text prompts.
+
+## Synopsis
+
+```bash
+codev generate-image "<prompt>" [options]
+```
+
+## Options
+
+```bash
+-o, --output <file>        # Output file path (default: output.png)
+-r, --resolution <res>     # Resolution: 1K, 2K, 4K (default: 1K)
+-a, --aspect <ratio>       # Aspect ratio (default: 1:1)
+--ref <image>              # Reference image (repeatable, max 14)
+```
+
+## Aspect Ratios
+
+`1:1` | `16:9` | `9:16` | `3:4` | `4:3` | `3:2` | `2:3`
+
+## Examples
+
+```bash
+# Basic generation
+codev generate-image "A sunset over mountains"
+
+# High-res widescreen
+codev generate-image "A futuristic city" -r 4K -a 16:9 -o city.png
+
+# With reference images (style transfer)
+codev generate-image "Same style but with cats" --ref style.png --ref layout.png
+
+# Prompt from file
+codev generate-image prompt.txt -o result.png
+```
+
+## Prerequisites
+
+Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable.
+Get a key at https://aistudio.google.com/apikey
+
+## Common Mistakes
+
+- Prompt must be **quoted** if it contains spaces
+- Prompt can also be a `.txt` file path (auto-detected by extension)
+- Reference images must exist on disk — max 14 images
+- Output defaults to `output.png` in current directory — use `-o` to change

package/skeleton/DEPENDENCIES.md

@@ -37,49 +37,6 @@ sudo apt install -y nodejs
 node --version  # Should show v18.x or higher
 ```
 
-### tmux
-
-| Requirement | Value |
-|-------------|-------|
-| Minimum Version | 3.0 |
-| Purpose | Terminal multiplexer for managing builder sessions |
-
-**Installation:**
-
-```bash
-# macOS
-brew install tmux
-
-# Ubuntu/Debian
-sudo apt install tmux
-
-# Verify
-tmux -V  # Should show tmux 3.x or higher
-```
-
-### ttyd
-
-| Requirement | Value |
-|-------------|-------|
-| Minimum Version | 1.7.0 |
-| Purpose | Web-based terminal for dashboard access |
-
-**Installation:**
-
-```bash
-# macOS
-brew install ttyd
-
-# Ubuntu/Debian (build from source)
-sudo apt install build-essential cmake git libjson-c-dev libwebsockets-dev
-git clone https://github.com/tsl0922/ttyd.git
-cd ttyd && mkdir build && cd build
-cmake .. && make && sudo make install
-
-# Verify
-ttyd --version  # Should show 1.7.x or higher
-```
-
 ### git
 
 | Requirement | Value |
@@ -192,8 +149,6 @@ codex --version
 | Dependency | Minimum Version | Required? |
 |------------|-----------------|-----------|
 | Node.js | 18.0.0 | Yes |
-| tmux | 3.0 | Yes |
-| ttyd | 1.7.0 | Yes |
 | git | 2.5.0 | Yes |
 | gh | latest | Yes |
 | Claude Code | latest | At least one AI CLI |
@@ -210,7 +165,7 @@ All dependencies are available via Homebrew:
 
 ```bash
 # Install all core dependencies at once
-brew install node tmux ttyd gh
+brew install node gh
 
 # Git is included with Xcode command line tools
 xcode-select --install
@@ -218,15 +173,13 @@ xcode-select --install
 
 ### Ubuntu/Debian
 
-Most dependencies are available via apt, except ttyd which must be built from source:
+Most dependencies are available via apt:
 
 ```bash
 # Core dependencies
-sudo apt install nodejs npm tmux git
+sudo apt install nodejs npm git
 
 # gh requires adding GitHub's apt repository (see above)
-
-# ttyd must be built from source (see above)
 ```
 
 ### Windows
@@ -256,18 +209,7 @@ echo $PATH
 export PATH="$PATH:$(npm config get prefix)/bin"
 ```
 
-### tmux version too old
-
-Ubuntu LTS versions often have older tmux. Install from source or use a PPA:
-
-```bash
-# Add tmux PPA for newer versions
-sudo add-apt-repository ppa:pi-rho/dev
-sudo apt update
-sudo apt install tmux
-```
-
-### ttyd connection issues
+### Terminal connection issues
 
 Ensure no firewall is blocking the ports (default: 4200-4299):
 

package/skeleton/builders.md

@@ -4,7 +4,7 @@ Track active builder agents here. Update manually or via `architect status`.
 
 ## Status Values
 
-- **spawning**: Worktree being created, ttyd starting
+- **spawning**: Worktree being created, terminal starting
 - **implementing**: Builder is working
 - **blocked**: Builder waiting for architect input
 - **pr-ready**: Builder has created a PR