zelari-code 0.1.3 → 0.2.1

package/dist/cli/main.bundled.js

@@ -523,11 +523,11 @@ __export(updater_exports, {
 });
 import { createRequire } from "node:module";
 import { spawn as spawn2 } from "node:child_process";
-import path15 from "node:path";
+import path16 from "node:path";
 import { fileURLToPath } from "node:url";
 function getCurrentVersion() {
   try {
-    const pkgPath = path15.resolve(__dirname2, "..", "..", "package.json");
+    const pkgPath = path16.resolve(__dirname2, "..", "..", "package.json");
     const pkg = require2(pkgPath);
     return pkg.version;
   } catch {
@@ -626,7 +626,7 @@ var init_updater = __esm({
   "src/cli/updater.ts"() {
     "use strict";
     require2 = createRequire(import.meta.url);
-    __dirname2 = path15.dirname(fileURLToPath(import.meta.url));
+    __dirname2 = path16.dirname(fileURLToPath(import.meta.url));
     REGISTRY_URL = "https://registry.npmjs.org/zelari-code/latest";
   }
 });
@@ -1321,8 +1321,29 @@ var CODING_SKILL_CATALOG = [];
 function listCodingSkills() {
   return [...CODING_SKILL_CATALOG];
 }
+function validateCodingSkillRequires(skill) {
+  const errors = [];
+  for (const reqId of skill.requires) {
+    if (!CODING_SKILL_CATALOG.some((s) => s.id === reqId)) {
+      errors.push(`Skill "${skill.id}" requires unknown skill "${reqId}"`);
+    }
+  }
+  return errors;
+}
+function registerCodingSkill(skill) {
+  const errors = validateCodingSkillRequires(skill);
+  if (errors.length > 0) {
+    throw new Error(`Cannot register coding skill: ${errors.join("; ")}`);
+  }
+  const idx = CODING_SKILL_CATALOG.findIndex((s) => s.id === skill.id);
+  if (idx >= 0) {
+    CODING_SKILL_CATALOG[idx] = skill;
+  } else {
+    CODING_SKILL_CATALOG.push(skill);
+  }
+}
 
-// src/agents/roles.ts
+// src/agents/skills/builtin/debugging.ts
 var CLARIFICATION_PROTOCOL = `
 
 WHEN TO ASK THE USER (clarification):
@@ -1332,6 +1353,1991 @@ If a single missing fact would materially change your output (target platform, s
 { "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
 ---END---
 
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a wave-in response.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var reproduceBug = {
+  id: "reproduce-bug",
+  version: "1.0.0",
+  name: "Reproduce Bug",
+  description: "Convert a bug report into a MINIMAL failing test. The test must fail without any code changes, then pass after the fix.",
+  category: "debug",
+  requiredRoles: ["oracle", "atlas"],
+  requiredTools: ["read_file", "write_file"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Bug report without a minimal reproduction",
+    "Bug that only happens in production (not in tests)",
+    'Bug that happens "sometimes" (intermittent)',
+    "Bug reported via screenshot or video, not repro steps",
+    "A complex multi-agent state race condition that is hard to verify without a test"
+  ],
+  antiPatterns: [
+    "Bug is in production AND has minimal repro steps already \u2014 skip to fix",
+    "Bug is in test code itself \u2014 fix the test, not the production code",
+    "Bug requires special hardware/network state \u2014 use a mock instead"
+  ],
+  requires: [],
+  relatedSkills: ["debug-with-rag", "root-cause-five-whys"],
+  tags: ["debug", "reproduction", "test", "minimal-example"],
+  examples: [
+    {
+      input: 'Bug report: "Council sometimes shows duplicate messages at the start of a session"',
+      output: {
+        minimalRepro: `// tests/regression/duplicate-messages.test.ts
+import { runCouncilPure } from '../agents/councilApi';
+
+describe('council duplicate message bug', () => {
+  it('does not emit duplicate user message when session resumes', async () => {
+    const mockProvider = async function* () {
+      yield { kind: 'text', delta: 'first' };
+      yield { kind: 'finish', reason: 'stop' };
+    };
+    const harness = new AgentHarness({
+      model: 'test', provider: 'test',
+      messages: [
+        { role: 'user', content: 'hi' },
+        { role: 'user', content: 'hi' }, // duplicate from session resume
+      ],
+      tools: [],
+      providerStream: mockProvider,
+    });
+    const events = [];
+    for await (const e of harness.run()) events.push(e);
+    const userMessages = events.filter(e => e.type === 'message_delta').length;
+    expect(userMessages).toBeGreaterThan(0); // sanity
+    // The actual bug: duplicate is rendered twice
+    // After fix, expect exactly 1 user message rendered
+  });
+});`,
+        reproSteps: [
+          "1. Set up session with duplicate user message in transcript",
+          "2. Run runCouncilPure",
+          "3. Observe duplicate message in output"
+        ],
+        whyMinimal: "Removed all agents except the first specialist (was: sisyphus+prometheus+hephaestus+oracle+chairman). Removed RAG context, workspace context. Kept only the duplication pattern."
+      }
+    }
+  ],
+  outputSchema: "{ minimalRepro: string; reproSteps: string[]; whyMinimal: string }",
+  systemPromptFragment: `You are converting a bug report into a minimal failing test.
+
+## Methodology
+1. **Read the bug report** carefully: what's the exact symptom? When does it happen?
+2. **Strip to essentials**: remove every agent, tool, env var, user state that isn't strictly required.
+3. **Identify the trigger**: what ONE input causes the bug?
+4. **Write the failing test**: it must FAIL on the current (buggy) code.
+5. **Verify it fails**: the test must fail without any code changes.
+6. **After the fix lands**, the test must PASS.
+
+## Output format (JSON-typed)
+- minimalRepro: string (the test code, runnable as-is)
+- reproSteps: string[] (3-7 numbered steps to reproduce manually)
+- whyMinimal: string (what you stripped + why)
+
+## Minimal-repro principles
+- **One assertion per test** \u2014 easier to debug when the test fails
+- **Deterministic** \u2014 no flaky timing, no random data
+- **No external dependencies** \u2014 use mocks for network/DB
+- **Fast** \u2014 under 100ms if possible
+- **Independent** \u2014 doesn't depend on other tests' state
+
+Stay under 300 words.${CLARIFICATION_PROTOCOL}`
+};
+var debugWithRag = {
+  id: "debug-with-rag",
+  version: "1.0.0",
+  name: "Debug With RAG",
+  description: "Search the knowledge base for similar past bugs, read the stack trace, propose the most likely root cause and a concrete fix.",
+  category: "debug",
+  requiredRoles: ["oracle", "atlas"],
+  requiredTools: ["searchRAG", "grep_content", "read_file"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A bug report with a stack trace or error message",
+    "A regression: feature worked before, now broken",
+    "A flaky test that fails intermittently",
+    "Performance regression: response time > 5s where it used to be < 500ms",
+    "A memory leak causing out-of-memory crashes"
+  ],
+  antiPatterns: [
+    "Bug is obvious from the error message (e.g. TypeError: cannot read property of undefined \u2014 fix directly)",
+    "No stack trace or repro steps \u2014 first ask the user for a minimal repro",
+    "A test is failing because the test itself is wrong \u2014 debug the test, not the code"
+  ],
+  requires: ["reproduce-bug"],
+  relatedSkills: ["root-cause-five-whys", "reproduce-bug"],
+  tags: ["debug", "rag", "stack-trace", "root-cause", "regression"],
+  examples: [
+    {
+      input: 'TypeError: Cannot read properties of undefined (reading "map") at Council.tsx:847',
+      output: {
+        ragSearch: 'searchRAG(query="Council.tsx undefined map error") returned 2 prior incidents: similar bug fixed in commit a3f9d by adding optional chaining; another similar issue in Council.tsx:612.',
+        stackTraceAnalysis: "Line 847 is inside `renderMessages()`. The most likely cause: `messages` is undefined when `runCouncilPure()` returns early on the first iteration before any agent has produced output.",
+        rootCause: "race condition: messages array is set after the first agent completes, but renderMessages() is called during the loading state when messages is still undefined.",
+        proposedFix: `function renderMessages() {
+  const messages = session.messages ?? [];
+  return messages.map(m => <Message key={m.id} {...m} />);
+}`,
+        verification: "Add a unit test that calls renderMessages() with messages=undefined and expects [] (not crash). Manual: trigger the bug scenario, confirm no crash."
+      }
+    }
+  ],
+  outputSchema: "{ ragSearch: string; stackTraceAnalysis: string; rootCause: string; proposedFix: string; verification: string }",
+  systemPromptFragment: `You are debugging a bug using the knowledge base.
+
+## Methodology
+1. **Extract key terms** from the error message + stack trace (file names, function names, error type).
+2. **Search the knowledge base**: searchRAG(query="<key terms>")
+3. **Read the relevant files**: use read_file with line ranges from the stack trace.
+4. **Identify the root cause**: what's the actual logic error? Don't just fix the symptom.
+5. **Propose a minimal fix**: the SMALLEST change that addresses the root cause.
+6. **Specify verification**: how to confirm the fix works (test case + manual steps).
+
+## Output format (JSON-typed)
+- ragSearch: string (what you searched + what you found)
+- stackTraceAnalysis: string (which line + what's likely happening)
+- rootCause: string (the actual bug, not the symptom)
+- proposedFix: string (code snippet)
+- verification: string (test + manual steps)
+
+## Debugging principles
+- **Fix the cause, not the symptom** (e.g. don't add a try/catch to silence an error)
+- **Minimal change** \u2014 don't refactor surrounding code while debugging
+- **One hypothesis at a time** \u2014 don't list 5 possible causes
+- **Verify the fix actually fixes** \u2014 write a failing test BEFORE the fix
+
+Stay under 400 words.${CLARIFICATION_PROTOCOL}`
+};
+var rootCauseFiveWhys = {
+  id: "root-cause-five-whys",
+  version: "1.0.0",
+  name: "Root Cause Five Whys",
+  description: 'Apply iterative 5-whys analysis with council consensus. Drill down through 5 levels of "why" to find the systemic root cause, not just the proximate trigger.',
+  category: "debug",
+  requiredRoles: ["sisyphus", "oracle", "chairman"],
+  requiredTools: ["searchRAG", "read_file"],
+  estimatedCost: "high",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    'A bug that keeps recurring after fixes ("whack-a-mole" symptom)',
+    "A systemic issue affecting multiple files/modules",
+    "A post-mortem on a production incident",
+    "Process issues (not just code) \u2014 why does the team keep making the same mistake?",
+    "Frequent merge failures or regression patterns in a single week"
+  ],
+  antiPatterns: [
+    "A trivial bug with obvious cause \u2014 just fix it directly",
+    "A user error (bad input) \u2014 the system should validate, not the user change behavior",
+    "A flaky test \u2014 fix the test, not the underlying system"
+  ],
+  requires: ["debug-with-rag"],
+  relatedSkills: ["debug-with-rag", "reproduce-bug"],
+  tags: ["debug", "root-cause", "systemic", "postmortem", "five-whys"],
+  examples: [
+    {
+      input: "Production incident: 3 outages in 2 weeks, all caused by the same API rate limit hit",
+      output: {
+        whys: [
+          { level: 1, question: "Why did the service go down?", answer: "The MiniMax API returned 429 Too Many Requests at peak load." },
+          { level: 2, question: "Why did we hit the rate limit?", answer: "We made 200 requests/minute; the limit is 100/minute." },
+          { level: 3, question: "Why did we exceed the rate limit?", answer: "A single user request triggered 200 sub-requests for parallel tool calls." },
+          { level: 4, question: "Why did one request trigger 200 sub-requests?", answer: "The agent loop calls all tools in parallel without batching." },
+          { level: 5, question: "Why don't we batch tool calls?", answer: "No rate limiter in the agent loop. The team assumed the API limit was high enough." }
+        ],
+        rootCause: "No client-side rate limiting. The agent loop fires parallel tool calls without backoff or batching.",
+        systemicFix: "Add a token-bucket rate limiter (100 req/min) before the API client. Implement batching for independent tool calls. Add a circuit breaker that pauses on 429 responses.",
+        processFix: "Add a pre-deploy load test that runs 1000 concurrent requests and verifies rate-limit handling.",
+        councilConsensus: 'Chairman: "All three council members agree on the systemic root cause. The process fix is as important as the code fix \u2014 load tests should be CI-required."'
+      }
+    }
+  ],
+  outputSchema: "{ whys: Array<{ level: number; question: string; answer: string }>; rootCause: string; systemicFix: string; processFix: string; councilConsensus: string }",
+  systemPromptFragment: `You are applying the 5-whys technique with council consensus.
+
+## Methodology
+1. **State the symptom** as the starting point for "why?"
+2. **Ask "why?" 5 times**, drilling down through layers of cause
+3. **Each answer must be FACTUAL**, not speculative
+4. **At the 5th why**, you've reached the systemic root cause
+5. **Propose TWO fixes**: systemic (code/architecture) + process (team/workflow)
+6. **Get council consensus**: chairman summarizes agreement from sisyphus (orchestrator) and oracle (analyst)
+
+## Output format (JSON-typed)
+- whys: Array<{ level: number; question: string; answer: string }>
+- rootCause: string (the deepest why)
+- systemicFix: string (code/architecture change)
+- processFix: string (team/workflow change)
+- councilConsensus: string (chairman's summary of agreement)
+
+## Anti-patterns to avoid
+- **"Human error"** is NEVER the root cause \u2014 the system should make the error impossible
+- **"Lack of training"** is NEVER the root cause \u2014 automation + checklists > training
+- **"Not enough time"** is NEVER the root cause \u2014 find the constraint, not the excuse
+- Stop at the FIRST level if it's a trivial bug \u2014 don't overthink simple cases
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL}`
+};
+var registerCodingSkill2 = registerCodingSkill;
+registerCodingSkill2(reproduceBug);
+registerCodingSkill2(debugWithRag);
+registerCodingSkill2(rootCauseFiveWhys);
+
+// src/agents/skills/builtin/docs.ts
+var CLARIFICATION_PROTOCOL2 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var writeReadme = {
+  id: "write-readme",
+  version: "1.0.0",
+  name: "Write README",
+  description: "Generate a project README from the codebase. Sections: Title, Badges, Description, Quick Start, Architecture, Development, Testing, Deployment, Contributing, License.",
+  category: "docs",
+  requiredRoles: ["prometheus", "atlas"],
+  requiredTools: ["read_file", "grep_content"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A new project is being created",
+    "Existing README is missing or stale",
+    "A project is being open-sourced",
+    "Onboarding new team members (they read the README first)"
+  ],
+  antiPatterns: [
+    "README exists and is recent \u2014 update instead of regenerate",
+    "Personal/internal project (README rarely matters)",
+    "Library with auto-generated docs from source code comments"
+  ],
+  requires: [],
+  relatedSkills: ["write-tsdoc", "write-changelog"],
+  tags: ["docs", "readme", "onboarding", "open-source"],
+  examples: [
+    {
+      input: "Generate README for AnathemaBrain (Electron + React + TypeScript AI agent platform)",
+      output: {
+        readme: `# AnathemaBrain
+
+> An educational Python project for learning how coding agents are built.
+
+AnathemaBrain is an Electron desktop app... (truncated)
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Architecture
+
+- **Main process** (electron/main/): Node.js, IPC handlers, LLM streaming
+- **Renderer** (src/): React 19 UI, Zustand stores
+- **Agent system** (src/agents/): Council multi-agent orchestration
+
+## Development
+
+\`\`\`bash
+npm run typecheck
+npm run test
+npm run lint
+\`\`\`
+
+## Testing
+
+96+ tests via Vitest + jsdom.
+
+## Deployment
+
+\`\`\`bash
+npm run build
+npm run electron:build
+\`\`\`
+
+## Contributing
+
+See docs/plans/ for active roadmaps. Pull requests welcome.
+
+## License
+
+Apache 2.0
+`,
+        sections: ["Title + tagline", "Badges", "Description", "Quick Start", "Architecture diagram", "Development commands", "Testing", "Deployment", "Contributing link", "License"]
+      }
+    }
+  ],
+  outputSchema: "{ readme: string; sections: string[] }",
+  systemPromptFragment: `You are writing a project README.md.
+
+## Required sections (in order)
+1. **Title + tagline** (1 sentence): what is this project?
+2. **Badges** (optional): CI status, npm version, license
+3. **Description** (2-3 paragraphs): what does it do, who is it for
+4. **Quick Start** (5-10 lines): install + run + see something working
+5. **Architecture** (1-2 paragraphs + diagram): high-level structure
+6. **Development** (commands): how to run tests, typecheck, lint
+7. **Testing**: what kind of tests exist, how to run them
+8. **Deployment** (if applicable): how to build + ship
+9. **Contributing**: link to CONTRIBUTING.md or describe PR process
+10. **License**: license type
+
+## Output format (JSON-typed)
+- readme: string (the full README content in markdown)
+- sections: string[] (the sections you included)
+
+## README principles
+- **Show, don't tell**: code examples for non-trivial concepts
+- **Up-to-date**: don't include commands that don't work
+- **Scannable**: use headers, bullets, code blocks
+- **One page max**: link to deeper docs rather than nesting everything
+
+Stay under 600 words.${CLARIFICATION_PROTOCOL2}`
+};
+var writeTsdoc = {
+  id: "write-tsdoc",
+  version: "1.0.0",
+  name: "Write TSDoc",
+  description: "Generate TSDoc/JSDoc comments for undocumented exports. Output: docstrings with @param, @returns, @throws, @example tags following the TSDoc standard.",
+  category: "docs",
+  requiredRoles: ["atlas"],
+  requiredTools: ["read_file"],
+  estimatedCost: "low",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A function or class lacks documentation",
+    "A public API is exported without TSDoc",
+    'IDE intellisense shows "any" or missing info for a function',
+    "A new utility is added to a shared library"
+  ],
+  antiPatterns: [
+    "The function is private/internal \u2014 no need for TSDoc",
+    "Auto-generated docs already exist (typedoc, etc.)",
+    "The function is self-explanatory (getName \u2192 returns name)"
+  ],
+  requires: [],
+  relatedSkills: ["write-readme"],
+  tags: ["docs", "tsdoc", "jsdoc", "intellisense", "api-docs"],
+  examples: [
+    {
+      input: "Add TSDoc to src/lib/formatDuration.ts",
+      output: {
+        documented: `/**
+ * Formats a duration in milliseconds as a human-readable string.
+ *
+ * @param ms - Duration in milliseconds. Must be a non-negative finite number.
+ * @param opts - Formatting options.
+ * @param opts.style - 'compact' (1h 23m), 'full' (1:23:45), or 'minimal' (23m).
+ *   Defaults to 'compact'.
+ * @returns The formatted duration string.
+ * @throws {RangeError} If ms is negative.
+ * @throws {TypeError} If ms is NaN or Infinity.
+ *
+ * @example
+ *   formatDuration(4980000);                       // '1h 23m'
+ *   formatDuration(4980000, { style: 'full' });    // '1:23:45'
+ *   formatDuration(60000, { style: 'minimal' });   // '1m'
+ */
+export function formatDuration(ms: number, opts?: { style?: 'compact' | 'full' | 'minimal' }): string {
+  // ... existing implementation
+}`,
+        tagsAdded: ["@param", "@param (nested)", "@returns", "@throws x2", "@example"]
+      }
+    }
+  ],
+  outputSchema: "{ documented: string; tagsAdded: string[] }",
+  systemPromptFragment: `You are writing TSDoc comments for a TypeScript function or class.
+
+## TSDoc tags (use these)
+- \`@param {type} name - description\` \u2014 for each parameter
+- \`@returns description\` (or \`@return\` legacy alias)
+- \`@throws {ErrorType} condition\` \u2014 for each throw path
+- \`@example\` followed by code block (for non-trivial usage)
+- \`@deprecated reason\` \u2014 if the function is being phased out
+- \`@see FunctionName\` \u2014 for cross-references
+- \`@remarks\` \u2014 additional context
+- \`@internal\` \u2014 for internal helpers (suppresses from public docs)
+
+## Output format (JSON-typed)
+- documented: string (the full code block with TSDoc added)
+- tagsAdded: string[] (which tags you included)
+
+## TSDoc principles
+- **First sentence is the summary**: ends with a period, capital letter
+- **One @param per parameter**: don't omit even if obvious
+- **@throws for EVERY throw path**: callers need to know
+- **@example for non-trivial usage**: best way to communicate intent
+- **No marketing language**: just describe what the function does
+- **No implementation details**: TSDoc is for the API contract, not internals
+
+Stay under 400 words.${CLARIFICATION_PROTOCOL2}`
+};
+var writeChangelog = {
+  id: "write-changelog",
+  version: "1.0.0",
+  name: "Write Changelog",
+  description: "Generate a CHANGELOG.md entry from git history. Follows Keep a Changelog format with sections: Added, Changed, Deprecated, Removed, Fixed, Security. Groups commits by category, deduplicates, writes user-facing descriptions.",
+  category: "docs",
+  requiredRoles: ["atlas"],
+  requiredTools: [],
+  estimatedCost: "low",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A release is being prepared",
+    "A sprint/iteration ends",
+    "Significant changes have accumulated since the last entry",
+    "A user-visible breaking change happened"
+  ],
+  antiPatterns: [
+    "No commits since the last changelog entry \u2014 skip",
+    "Internal refactors with no user impact \u2014 exclude",
+    'Doc-only changes \u2014 mention briefly in "Changed" or skip'
+  ],
+  requires: [],
+  relatedSkills: ["write-readme", "write-tsdoc"],
+  tags: ["docs", "changelog", "release-notes", "keep-a-changelog"],
+  examples: [
+    {
+      input: "Generate changelog for v0.2.0 from commits since v0.1.0 (last 30 commits)",
+      output: {
+        changelog: `# Changelog
+
+All notable changes to AnathemaBrain are documented in this file.
+
+## [0.2.0] - 2026-06-28
+
+### Added
+- **BrainEvent provider-neutral types** (Phase 11): 12 discriminated union events for agent lifecycle, message streaming, tool execution, errors
+- **EventBus**: typed in-memory pub/sub with error isolation
+- **AgentHarness**: pure agent loop yielding AsyncIterable<BrainEvent>
+- **runCouncilPure()**: council orchestration without window.electronAPI dependency
+- **5 built-in coding tools**: read_file, write_file, edit_file, bash, grep_content
+- **14 senior-grade coding skills** across 4 categories (Planning, Refactoring, Debugging, Review)
+
+### Changed
+- LLM streaming now emits BrainEvents alongside the IPC bridge (renderer unchanged)
+- Agent system refactored to use AgentHarness as the loop driver
+
+### Fixed
+- Council event timing: agent_start/agent_end now emit at correct boundaries
+- Tool execution start events fire when provider yields tool_call deltas
+
+### Security
+- Grok OAuth token refresh now respects rate limits (fixed race condition)
+
+[0.1.0] - 2026-06-01
+... (previous entries)
+`,
+        sectionsUsed: ["Added", "Changed", "Fixed", "Security"],
+        commitsProcessed: 30
+      }
+    }
+  ],
+  outputSchema: "{ changelog: string; sectionsUsed: string[]; commitsProcessed: number }",
+  systemPromptFragment: `You are writing a CHANGELOG.md entry from git history.
+
+## Keep a Changelog format
+Sections (use only those with content):
+- **Added** \u2014 new features
+- **Changed** \u2014 changes in existing functionality
+- **Deprecated** \u2014 soon-to-be removed features
+- **Removed** \u2014 now removed features
+- **Fixed** \u2014 bug fixes
+- **Security** \u2014 vulnerability fixes
+
+## Methodology
+1. **List commits since the last release** (use git log).
+2. **Categorize each commit** into the right section.
+3. **Translate to user-facing language**: "feat: add event bus" \u2192 "EventBus: typed in-memory pub/sub".
+4. **Group related commits**: if 5 commits all touch the event system, write ONE entry.
+5. **Skip internal-only changes**: refactors that don't change behavior.
+6. **Add version + date**: top of the entry.
+
+## Output format (JSON-typed)
+- changelog: string (the full CHANGELOG.md content)
+- sectionsUsed: string[] (which sections you wrote)
+- commitsProcessed: number
+
+## Changelog principles
+- **User-facing language**: write for end-users, not developers
+- **Group, don't list**: 1 entry per feature, not 1 per commit
+- **Highlight breaking changes**: bold or callout
+- **Link to issues/PRs**: reference #123, fixes #456
+- **Date format**: ISO 8601 (YYYY-MM-DD)
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL2}`
+};
+registerCodingSkill(writeReadme);
+registerCodingSkill(writeTsdoc);
+registerCodingSkill(writeChangelog);
+
+// src/agents/skills/builtin/git-ops.ts
+var CLARIFICATION_PROTOCOL3 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var commitMessage = {
+  id: "commit-message",
+  version: "1.0.0",
+  name: "Commit Message",
+  description: "Generate a Conventional Commits message from a staged git diff. Format: <type>(<scope>): <subject>. Body explains WHY. Footer references issues.",
+  category: "ops",
+  requiredRoles: ["atlas"],
+  requiredTools: [],
+  estimatedCost: "low",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A developer has staged changes and needs a commit message",
+    "A PR description requires a list of conventional commits",
+    "A CHANGELOG is generated from commit history"
+  ],
+  antiPatterns: [
+    "Empty diff (nothing staged) \u2014 fail fast",
+    "Merge commits or reverts \u2014 different format",
+    "Multi-purpose commits (refactor + feat + fix in one) \u2014 split first"
+  ],
+  requires: [],
+  relatedSkills: ["pr-description", "write-changelog"],
+  tags: ["git", "commit", "conventional-commits", "changelog"],
+  examples: [
+    {
+      input: "Staged diff: 3 files changed, +45/-12. Adds brain event types and EventBus class.",
+      output: {
+        subject: "feat(events): add BrainEvent types + EventBus (Phase 11)",
+        body: `Adds the provider-neutral event layer:
+- 12 BrainEvent discriminated union types
+- EventBus class with typed subscribers + error isolation
+- emit/subscribe/subscribeAll API
+
+Foundation for Phase 12 (AgentHarness extraction).`,
+        footer: "Refs: docs/plans/2026-06-28-zelari-code.md",
+        type: "feat",
+        scope: "events"
+      }
+    }
+  ],
+  outputSchema: '{ subject: string; body: string; footer: string; type: "feat" | "fix" | "refactor" | "docs" | "test" | "chore" | "perf" | "style"; scope: string }',
+  systemPromptFragment: `You are writing a Conventional Commits message.
+
+## Format
+<type>(<scope>): <subject>
+
+<body \u2014 explain WHY, not WHAT>
+
+<footer \u2014 issue refs, breaking changes>
+
+## Types
+- feat: new feature
+- fix: bug fix
+- refactor: code change that neither fixes a bug nor adds a feature
+- docs: documentation only
+- test: adding/correcting tests
+- chore: build/tooling changes (deps, CI, config)
+- perf: performance improvement
+- style: formatting, missing semicolons, etc. (no logic change)
+
+## Subject rules
+- Imperative mood ("add" not "added")
+- Lowercase (except proper nouns)
+- Max 72 characters
+- No trailing period
+
+## Body rules
+- Wrap at 72 characters
+- Explain WHY the change was made
+- Bullet points for multiple distinct changes
+
+## Footer rules
+- \`Refs: #123\` for related issues
+- \`BREAKING CHANGE: <description>\` for breaking changes
+- \`Co-authored-by: Name <email>\` for pair work
+
+## Output format (JSON-typed)
+- subject: string
+- body: string
+- footer: string
+- type: ConventionalCommitType
+- scope: string (optional, lowercase module name)
+
+Stay under 300 words.${CLARIFICATION_PROTOCOL3}`
+};
+var prDescription = {
+  id: "pr-description",
+  version: "1.0.0",
+  name: "PR Description",
+  description: "Generate a pull request description with sections: Summary, Motivation, Changes, Testing, Screenshots, Risks. Synthesizes from commits + diff + related issues.",
+  category: "ops",
+  requiredRoles: ["prometheus", "atlas"],
+  requiredTools: [],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A PR is ready for review and needs a description",
+    "A PR template requires filling in structured sections",
+    "A large change (>200 LOC) needs careful framing for reviewers"
+  ],
+  antiPatterns: [
+    "A 1-line typo fix \u2014 title only, no body needed",
+    "A WIP / draft PR \u2014 defer until ready",
+    "Generated code (codegen output) \u2014 link to the generator instead"
+  ],
+  requires: ["commit-message"],
+  relatedSkills: ["commit-message", "write-changelog"],
+  tags: ["git", "pr", "pull-request", "review", "documentation"],
+  examples: [
+    {
+      input: "PR for Phase 11 of AnathemaCoder: BrainEvent types + EventBus + LLM streaming wiring",
+      output: {
+        title: "Phase 11: Provider-neutral events foundation",
+        summary: "Introduces the BrainEvent discriminated union and EventBus \u2014 the provider-neutral contract between LLM providers and any frontend (Electron renderer today, Ink CLI in Phase 14).",
+        motivation: "The current IPC bridge (`emitChunk`/`emitDone`) couples every frontend to provider-specific chunks. Any new frontend (CLI, mobile, web) would need to duplicate SSE parsing per provider. This is the foundation that lets Phase 12 extract an AgentHarness usable from any context.",
+        changes: [
+          "Added `electron/shared/events.ts` \u2014 12 discriminated union types (agent_start, message_delta, tool_execution_start, etc.)",
+          "Added `electron/shared/eventBus.ts` \u2014 typed pub/sub with error isolation",
+          "Wired 5 local emit helpers in `electron/main/ipc/llm.ts` (emitAgentStart, emitMessageStart, emitMessageDelta, emitMessageEnd, emitBrainError)",
+          "Tool execution emits `BrainToolExecutionStartEvent` when provider yields tool_call",
+          "Council emits `agent_start` / `agent_end` at run boundaries",
+          "6 new vitest tests for EventBus (typed delivery, wildcard, error isolation)"
+        ],
+        testing: "96/96 tests passing. New: 6 EventBus tests in tests/unit/eventBus.test.ts. Manual: existing Electron renderer unchanged (verified Council chat still streams correctly).",
+        risks: [
+          "Adding event emission alongside IPC is purely additive \u2014 no migration needed for existing renderer code.",
+          "Council event timing verified manually: agent_start fires before any message events, agent_end fires after."
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ title: string; summary: string; motivation: string; changes: string[]; testing: string; risks: string[] }",
+  systemPromptFragment: `You are writing a Pull Request description.
+
+## Sections (use all)
+1. **Title** (max 72 chars, imperative mood)
+2. **Summary** (1 paragraph): what does this PR do?
+3. **Motivation** (1-2 paragraphs): WHY? What problem does it solve?
+4. **Changes** (bullet list, 5-15 items): specific files/concepts changed
+5. **Testing** (1 paragraph): how was it verified? Test counts, manual steps
+6. **Risks** (bullet list, 2-5 items): what could go wrong? Migration needed?
+
+## Output format (JSON-typed)
+- title: string
+- summary: string
+- motivation: string
+- changes: string[]
+- testing: string
+- risks: string[]
+
+## PR description principles
+- **Reviewer-first**: optimize for someone who has NEVER seen this code
+- **Concrete not abstract**: cite file paths, line numbers, function names
+- **Risk-honest**: don't hide breaking changes or migration steps
+- **Self-contained**: PR description should make sense without clicking through to issues
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL3}`
+};
+var ciPipeline = {
+  id: "ci-pipeline",
+  version: "1.0.0",
+  name: "CI Pipeline",
+  description: "Generate a GitHub Actions workflow YAML that runs typecheck + lint + test + build on every push and PR. Configures Node version, caching, and failure annotations.",
+  category: "ops",
+  requiredRoles: ["atlas"],
+  requiredTools: [],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A project is being open-sourced and needs CI",
+    "Existing CI is missing a step (e.g. no typecheck)",
+    "A new test framework is added",
+    "A release pipeline is being automated"
+  ],
+  antiPatterns: [
+    "The project has no tests yet \u2014 write tests first, then CI",
+    "A different CI system is in use (CircleCI, GitLab CI) \u2014 use that one",
+    "The project is a personal/internal tool (CI rarely matters)"
+  ],
+  requires: [],
+  relatedSkills: ["write-changelog"],
+  tags: ["ci", "github-actions", "automation", "pipeline"],
+  examples: [
+    {
+      input: "Generate GitHub Actions for AnathemaBrain (Electron + React + TS + Vitest)",
+      output: {
+        workflowFile: ".github/workflows/ci.yml",
+        content: `name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js \${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: \${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck (node config)
+        run: npm run typecheck:node
+
+      - name: Typecheck (web config)
+        run: npm run typecheck:web
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm run test
+
+      - name: Build (Electron renderer + main)
+        run: npm run build
+
+      - name: Upload coverage
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-\${{ matrix.node-version }}
+          path: coverage/
+`,
+        jobs: ["test"],
+        triggers: ["push to main", "pull_request to main"],
+        nodeVersion: "20.x"
+      }
+    }
+  ],
+  outputSchema: "{ workflowFile: string; content: string; jobs: string[]; triggers: string[]; nodeVersion: string }",
+  systemPromptFragment: `You are writing a GitHub Actions workflow YAML.
+
+## Required structure
+1. **name**: workflow display name
+2. **on**: triggers (push to main, pull_request, manual workflow_dispatch)
+3. **jobs**: at least one job with steps
+4. **runs-on**: ubuntu-latest (default)
+5. **timeout-minutes**: 15 (default, increase for slower builds)
+6. **matrix.node-version**: pin to a specific major version (e.g. 20.x)
+
+## Standard steps (in order)
+1. actions/checkout@v4
+2. actions/setup-node@v4 with cache: 'npm'
+3. npm ci (NOT npm install \u2014 faster in CI)
+4. typecheck (run the project's typecheck script)
+5. lint (run the project's lint script)
+6. test (run the project's test script)
+7. build (run the project's build script, if applicable)
+
+## Output format (JSON-typed)
+- workflowFile: string (path like .github/workflows/ci.yml)
+- content: string (the full YAML)
+- jobs: string[] (job names)
+- triggers: string[] (trigger events)
+- nodeVersion: string (pinned Node version)
+
+## CI principles
+- **Fail fast**: order steps from fastest \u2192 slowest (typecheck before build)
+- **Cache dependencies**: cache: 'npm' saves 30s+ on cold builds
+- **Pin versions**: use @v4 not @latest for reproducibility
+- **Don't cache build artifacts**: cache only deps
+- **Separate jobs for parallel**: typecheck, lint, test can be parallel jobs
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL3}`
+};
+registerCodingSkill(commitMessage);
+registerCodingSkill(prDescription);
+registerCodingSkill(ciPipeline);
+
+// src/agents/skills/builtin/planning.ts
+var CLARIFICATION_PROTOCOL4 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var architectFeature = {
+  id: "architect-feature",
+  version: "1.0.0",
+  name: "Architect Feature",
+  description: "Multi-perspective feature design: explore 3-5 alternatives, pick the strongest, generate an ADR, list concrete risks and mitigations.",
+  category: "planning",
+  requiredRoles: ["sisyphus", "prometheus", "oracle"],
+  requiredTools: ["createTask", "searchRAG"],
+  estimatedCost: "high",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "New feature spanning multiple modules",
+    "Architectural decision with long-term impact",
+    "Public API design (libraries, services, CLI commands)",
+    "Schema or data model changes affecting persistence",
+    "Cross-cutting concern (auth, logging, caching) added to existing system"
+  ],
+  antiPatterns: [
+    "Simple bug fix \u2014 use debug-with-rag instead",
+    "Single-file refactor under 500 LOC \u2014 use refactor-monolith only if > 1000 LOC",
+    "Documentation update \u2014 use write-tsdoc or write-readme",
+    "Adding a one-line config or env var \u2014 direct edit is faster",
+    "Pure refactor with no design choice \u2014 use refactor-monolith or extract-reusable"
+  ],
+  requires: ["architect-decision-record"],
+  relatedSkills: ["scope-check", "migrate-stack", "code-review"],
+  tags: ["planning", "architecture", "design", "multi-role", "adr"],
+  examples: [
+    {
+      input: "Add OAuth login via Google to the Electron desktop app",
+      output: {
+        goal: "Enable users to sign in to AnathemaBrain with their Google account, replacing the current email+password flow.",
+        alternatives: [
+          { approach: "OAuth library (Passport.js)", score: "F:4 R:3 M:5", rationale: "Battle-tested, large ecosystem, easy revocation, ~50KB bundle." },
+          { approach: "Custom PKCE flow with raw HTTP", score: "F:3 R:4 M:2", rationale: "No deps, but high surface area (token refresh, CSRF, error states)." },
+          { approach: "Use Electron built-in OAuth via deep link", score: "F:4 R:2 M:4", rationale: "Native to Electron, no redirect_uri issues, but desktop-specific." }
+        ],
+        chosen: { approach: "Passport.js with Google strategy", rationale: "Lowest maintenance burden given the OAuth library ecosystem; revocation handled by the library." },
+        adrPath: "docs/adr/0014-google-oauth.md",
+        risks: [
+          { risk: "Token refresh edge cases when offline", mitigation: "Persist refresh token in keychain (already implemented for Grok OAuth)." },
+          { risk: "CSRF on deep-link redirect", mitigation: "Use OAuth state parameter with cryptographic random nonce." }
+        ]
+      }
+    },
+    {
+      input: "Add a /skill command to the CLI that expands a skill template",
+      output: {
+        goal: "Allow the CLI to invoke a skill by name, expanding the template and dispatching to the council.",
+        alternatives: [
+          { approach: "Slash command handler in cli/main.ts", score: "F:5 R:1 M:5", rationale: "Direct, simple." },
+          { approach: "Plugin system with skill loader", score: "F:2 R:4 M:2", rationale: "Over-engineered for v1." }
+        ],
+        chosen: { approach: "Slash command handler", rationale: "YAGNI \u2014 defer plugin system to v2 when users request it." },
+        adrPath: "docs/adr/0015-cli-skill-commands.md",
+        risks: [
+          { risk: "Skill name collisions across categories", mitigation: "Namespace as `<category>:<name>` (e.g. `planning:architect-feature`)." }
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ goal: string; alternatives: Array<{ approach: string; score: string; rationale: string }>; chosen: { approach: string; rationale: string }; adrPath: string; risks: Array<{ risk: string; mitigation: string }> }",
+  systemPromptFragment: `You are designing a feature with multi-perspective analysis.
+
+## Methodology
+1. Restate the goal in ONE sentence: what user need does this serve?
+2. Search the knowledge base for prior decisions: searchRAG(query="<feature-keyword>")
+3. Generate 3-5 DISTINCT approaches (vary the axis: library vs custom, sync vs async, desktop vs server, etc.).
+4. Score each approach on three dimensions (1-5 each):
+   - Feasibility (F): how easy to implement given the current stack
+   - Risk (R, INVERTED \u2014 lower is better): likelihood of bugs, security holes, scope creep
+   - Maintenance (M): long-term cost (bus factor, doc quality, ecosystem health)
+5. Pick the top approach and justify in 1-2 sentences.
+6. Generate an ADR (link to architect-decision-record skill).
+7. List 2-5 concrete risks + mitigations.
+
+## Output format (JSON-typed)
+- goal: string
+- alternatives: Array<{ approach: string; score: string; rationale: string }>
+- chosen: { approach: string; rationale: string }
+- adrPath: string
+- risks: Array<{ risk: string; mitigation: string }>
+
+Stay under 400 words. Be decisive: pick ONE approach, do not list 3 equally good options.${CLARIFICATION_PROTOCOL4}`
+};
+var architectDecisionRecord = {
+  id: "architect-decision-record",
+  version: "1.0.0",
+  name: "Architect Decision Record",
+  description: "Generate an ADR (Architecture Decision Record) from a decision rationale. Format: Context, Decision, Consequences, Alternatives Considered.",
+  category: "planning",
+  requiredRoles: ["prometheus", "atlas"],
+  requiredTools: ["createDocument"],
+  estimatedCost: "low",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A non-trivial architectural decision has been made",
+    "Reviewing a past decision and want to capture WHY it was made",
+    "Onboarding a new team member to the rationale behind existing choices",
+    "After running architect-feature, to formalize the chosen approach"
+  ],
+  antiPatterns: [
+    "No real decision has been made yet \u2014 first run architect-feature or scope-check",
+    "Trivial choice (file naming, color scheme) \u2014 use a code comment",
+    "Decision is reversible in under 1 hour \u2014 defer the ADR"
+  ],
+  requires: [],
+  relatedSkills: ["architect-feature", "scope-check"],
+  tags: ["planning", "documentation", "adr", "decision-log"],
+  examples: [
+    {
+      input: "Document why we use SQLite over Postgres for local storage",
+      output: {
+        path: "docs/adr/0007-sqlite-over-postgres.md",
+        content: `# 7. SQLite over Postgres for local storage
+
+## Context
+AnathemaBrain is an Electron desktop app that runs entirely on the user's machine. We need persistent storage for vault documents, RAG vectors, settings, and council sessions.
+
+## Decision
+Use SQLite (via better-sqlite3) for all local storage.
+
+## Consequences
+- Zero-config: works out of the box, no separate DB server to manage
+- Single-file backups: copy ~/.anathemabrain/db.sqlite
+- FTS5 + JSON1 support built-in (used by RAG and vault search)
+- Cross-platform: tested on macOS, Linux, Windows
+
+### Positive
+- No network round-trip \u2014 sub-millisecond reads
+- Embedded = no auth/connection-string management
+- Mature ecosystem (better-sqlite3, sqlite-vss)
+
+### Negative
+- Single-writer: concurrent writes are serialized (acceptable for desktop)
+- No horizontal scaling (irrelevant for desktop)
+- Migration tooling requires custom scripts (we have db/migrations.ts)
+
+## Alternatives Considered
+- **Postgres**: rejected \u2014 requires a server process, overkill for desktop
+- **LevelDB / RocksDB**: rejected \u2014 no SQL, harder to query vector data
+- **JSON files**: rejected \u2014 no concurrent access, no FTS
+`
+      }
+    }
+  ],
+  outputSchema: "{ path: string; content: string }",
+  systemPromptFragment: `You are writing an Architecture Decision Record (ADR).
+
+## Required sections
+1. **# N. <Title>** \u2014 short title in present tense ("Use X for Y")
+2. **## Context** \u2014 what is the situation? What forces are at play? (2-3 paragraphs)
+3. **## Decision** \u2014 what did we decide? State it clearly in 1-2 sentences.
+4. **## Consequences** \u2014 what becomes easier (+) and harder (-) as a result?
+5. **## Alternatives Considered** \u2014 2-4 alternatives with one-line rejection reasons.
+
+## Numbering
+- Check docs/adr/ for the next available number (NNN-title.md format)
+- ADR numbers are permanent \u2014 never reuse, even if an ADR is superseded (mark superseded in the body instead)
+
+## Tone
+- Factual, not promotional
+- Acknowledge trade-offs honestly
+- Link to relevant code/PRs/files using relative paths
+
+Stay under 800 words.${CLARIFICATION_PROTOCOL4}`
+};
+var migrateStack = {
+  id: "migrate-stack",
+  version: "1.0.0",
+  name: "Migrate Stack",
+  description: "Plan a migration (framework, language, database, build tool) with phased rollout and a concrete rollback strategy. Identifies big-bang risks and proposes incremental steps.",
+  category: "planning",
+  requiredRoles: ["sisyphus", "prometheus", "hephaestus"],
+  requiredTools: ["createTask", "searchRAG"],
+  estimatedCost: "high",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Replacing a framework (e.g. CRA \u2192 Vite, Express \u2192 Fastify)",
+    "Upgrading a major version with breaking changes (React 17 \u2192 18)",
+    "Switching databases (Postgres \u2192 SQLite, JSON files \u2192 Postgres)",
+    "Migrating build tooling (webpack \u2192 esbuild, npm \u2192 pnpm)",
+    "Replacing a key library with a competitor (moment \u2192 date-fns)"
+  ],
+  antiPatterns: [
+    "Greenfield project \u2014 use architect-feature instead",
+    "A/B test of two stacks \u2014 use a spike/benchmark first",
+    "Migration can be done by automated codemods \u2014 skip the planning skill"
+  ],
+  requires: ["architect-decision-record", "scope-check"],
+  relatedSkills: ["architect-feature", "refactor-monolith"],
+  tags: ["planning", "migration", "rollout", "rollback", "risk-management"],
+  examples: [
+    {
+      input: "Migrate AnathemaBrain from Create React App (CRA) to Vite",
+      output: {
+        goal: "Reduce dev server startup from 30s to <2s, reduce prod build from 60s to <10s.",
+        phases: [
+          { name: "Phase 1: Setup parallel build", exitCriterion: "npm run dev:vite works for a hello-world", durationDays: 2 },
+          { name: "Phase 2: Migrate entry points", exitCriterion: "Both Webpack and Vite builds succeed; renderer loads in both", durationDays: 5 },
+          { name: "Phase 3: Migrate loaders (CSS, assets)", exitCriterion: "All static assets load correctly under Vite", durationDays: 3 },
+          { name: "Phase 4: Cut over", exitCriterion: "Webpack config deleted; CI runs only Vite", durationDays: 2 }
+        ],
+        rollbackStrategy: "Keep Webpack config in git history (tag: pre-vite-migration). Revert the single commit that switches the default dev script.",
+        risks: [
+          { risk: "Asset paths differ between Webpack and Vite (~/ aliases, ?url imports)", mitigation: "Phase 3 includes a path-mapping smoke test." },
+          { risk: "electron-vite specific electron features not yet stable", mitigation: "Phase 1 spike verifies electron-vite can compile the existing Electron main process." }
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ goal: string; phases: Array<{ name: string; exitCriterion: string; durationDays: number }>; rollbackStrategy: string; risks: Array<{ risk: string; mitigation: string }> }",
+  systemPromptFragment: `You are planning a stack migration.
+
+## Methodology
+1. State the GOAL in measurable terms (e.g. "reduce build time from 60s to 10s").
+2. Decompose into 3-6 phases. Each phase has a CLEAR exit criterion (testable condition).
+3. Each phase should be DEPLOYABLE on its own (no big-bang steps).
+4. Plan a ROLLBACK strategy: which single commit reverts to the previous state?
+5. List 3-7 concrete risks + mitigations per phase.
+
+## Migration principles
+- **Strangler Fig**: new system grows alongside old, traffic migrates incrementally
+- **No big-bang rewrites**: every phase must be independently shippable
+- **Reversibility first**: every phase has a tested rollback path
+- **Data migration last**: schema changes follow code changes (dual-write during transition)
+
+## Output format (JSON-typed)
+- goal: string (measurable)
+- phases: Array<{ name: string; exitCriterion: string; durationDays: number }>
+- rollbackStrategy: string (the single command or commit that reverts)
+- risks: Array<{ risk: string; mitigation: string }>
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL4}`
+};
+var scopeCheck = {
+  id: "scope-check",
+  version: "1.0.0",
+  name: "Scope Check",
+  description: "Validate feasibility of a proposed feature or change. Identify hidden costs, dependencies, risks. Propose a reduced scope that fits the available budget.",
+  category: "planning",
+  requiredRoles: ["sisyphus", "oracle", "chairman"],
+  requiredTools: ["searchRAG"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "User proposes an ambitious feature without a clear MVP boundary",
+    "Estimates are unclear or contested",
+    "Hidden dependencies suspected (auth, billing, third-party APIs)",
+    "Before committing to a multi-week project",
+    'When a stakeholder says "this should be easy" and you suspect it is not'
+  ],
+  antiPatterns: [
+    "The task is already small and well-scoped \u2014 just do it",
+    "Pure research / exploration \u2014 no commitment to implement",
+    "Bug fix \u2014 use debug-with-rag instead"
+  ],
+  requires: [],
+  relatedSkills: ["architect-feature", "migrate-stack"],
+  tags: ["planning", "feasibility", "risk-assessment", "mvp", "scoping"],
+  examples: [
+    {
+      input: 'Build a "smart inbox" that categorizes emails using the local LLM council',
+      output: {
+        feasibility: "partial",
+        estimatedEffortDays: 14,
+        hiddenCosts: [
+          { cost: "IMAP polling + auth setup (3-5 days)", mitigation: "Use existing Gmail API OAuth2 flow" },
+          { cost: "Email parsing (HTML, attachments) - 2 days", mitigation: "Use mailparser library" },
+          { cost: "Local LLM inference at scale - 1 day setup + per-email ~3s", mitigation: "Batch categorization, use smaller model (gemini-2.5-flash)" },
+          { cost: "Council orchestration - already have it", mitigation: "Reuse runCouncilPure" }
+        ],
+        reducedScope: {
+          phase1: "Single Gmail account, read-only, top-20 inbox categorization (3 days)",
+          phase2: "Multi-account + auto-archive (5 days)",
+          phase3: "Reply drafting suggestions (6 days)"
+        },
+        risks: [
+          "Council API costs: 5 emails \xD7 3 council members \xD7 4 providers = 60 LLM calls per batch",
+          "User privacy: emails sent to cloud providers unless restricted to local-only model"
+        ]
+      }
+    }
+  ],
+  outputSchema: '{ feasibility: "yes" | "partial" | "no"; estimatedEffortDays: number; hiddenCosts: Array<{ cost: string; mitigation: string }>; reducedScope: { phase1: string; phase2: string; phase3: string }; risks: string[] }',
+  systemPromptFragment: `You are validating the scope of a proposed feature or change.
+
+## Methodology
+1. Restate the proposal in ONE sentence.
+2. Search the knowledge base: searchRAG(query="<proposed-keyword>")
+3. Estimate effort realistically (in person-days, with calibration from prior projects).
+4. List HIDDEN costs: auth flows, data migration, third-party APIs, deployment, monitoring.
+5. Propose a REDUCED SCOPE that delivers 80% of the value in 20% of the time.
+6. Flag risks that could block the project.
+
+## Output format (JSON-typed)
+- feasibility: 'yes' | 'partial' | 'no'
+- estimatedEffortDays: number
+- hiddenCosts: Array<{ cost: string; mitigation: string }>
+- reducedScope: { phase1: string; phase2: string; phase3: string } (3 phases, each independently shippable)
+- risks: string[] (3-5 risks)
+
+## When to be skeptical
+- "Just add X" usually hides auth + persistence + UI work (3x multiplier)
+- "Use the existing system" usually means new integration code
+- Estimates from optimistic people \u2014 multiply by 2-3x for calendar time
+
+Stay under 400 words. Be honest about feasibility \u2014 say NO when the answer is NO.${CLARIFICATION_PROTOCOL4}`
+};
+registerCodingSkill(architectDecisionRecord);
+registerCodingSkill(scopeCheck);
+registerCodingSkill(architectFeature);
+registerCodingSkill(migrateStack);
+
+// src/agents/skills/builtin/refactoring.ts
+var CLARIFICATION_PROTOCOL5 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var extractReusable = {
+  id: "extract-reusable",
+  version: "1.0.0",
+  name: "Extract Reusable Module",
+  description: "Find duplication across files via semantic search. Identify shared logic, propose a new reusable module with a clean API, plan the migration of all call sites.",
+  category: "refactor",
+  requiredRoles: ["atlas", "oracle"],
+  requiredTools: ["searchRAG"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Same logic copy-pasted across 3+ files",
+    "Two near-identical utility functions (e.g. formatDate in 2 different files)",
+    "A bug fix needs to be applied in 5 places",
+    "New project copies code from old project (opportunity to extract)"
+  ],
+  antiPatterns: [
+    "Duplication is INTENTIONAL (different domains, different evolution paths)",
+    "Shared logic is so trivial (< 5 lines) that a function call adds more noise than it removes",
+    "API is unstable \u2014 extracting now would force awkward premature abstractions"
+  ],
+  requires: [],
+  relatedSkills: ["refactor-monolith", "simplify-conditionals"],
+  tags: ["refactor", "deduplication", "reuse", "shared-module"],
+  examples: [
+    {
+      input: 'There are 3 different "formatDuration" implementations in src/ \u2014 slightly different in each',
+      output: {
+        duplication: {
+          callSites: [
+            { file: "src/components/Timer.tsx", function: "formatDuration(ms: number): string", line: 23 },
+            { file: "src/lib/utils.ts", function: "formatDuration(ms: number): string", line: 47 },
+            { file: "src/pages/Settings.tsx", function: "formatDurationText(ms: number): string", line: 156 }
+          ],
+          differences: [
+            'Timer.tsx: shows "1h 23m" for >1h, "23m 45s" for >1m, else "45s"',
+            'utils.ts: shows "1:23:45" always (HH:MM:SS)',
+            'Settings.tsx: shows "23m" for >1m, "45s" else'
+          ]
+        },
+        proposedModule: {
+          path: "src/lib/format/duration.ts",
+          api: `export function formatDuration(ms: number, opts?: { style?: 'compact' | 'full' | 'minimal' }): string`,
+          variants: [
+            { style: "compact", example: "1h 23m" },
+            { style: "full", example: "1:23:45" },
+            { style: "minimal", example: "23m" }
+          ]
+        },
+        migration: [
+          { step: "Create src/lib/format/duration.ts with the 3-style API", linesToAdd: 30 },
+          { step: 'Update Timer.tsx to call formatDuration(ms, {style:"compact"})', linesToChange: 2 },
+          { step: 'Update utils.ts to call formatDuration(ms, {style:"full"})', linesToChange: 2 },
+          { step: 'Update Settings.tsx to call formatDuration(ms, {style:"minimal"})', linesToChange: 2 }
+        ],
+        benefits: ["Single source of truth for duration formatting", "Easy to add new styles (e.g. ISO 8601)", "Tests in one place"]
+      }
+    }
+  ],
+  outputSchema: "{ duplication: { callSites: Array<{ file: string; function: string; line: number }>; differences: string[] }; proposedModule: { path: string; api: string; variants: Array<{ style: string; example: string }> }; migration: Array<{ step: string; linesToChange: number }>; benefits: string[] }",
+  systemPromptFragment: `You are finding duplicated logic and extracting a reusable module.
+
+## Methodology
+1. Use grep/semantic search to find candidate duplication (3+ similar implementations).
+2. Read each call site to understand the VARIATIONS (not just the common pattern).
+3. Design an API that accommodates ALL variations (use options pattern, not multiple functions).
+4. Specify the new module path + function signature + behavior table.
+5. List migration steps: which file + which lines change to use the new module.
+
+## Extraction principles
+- **Variations via options, not forks**: prefer formatDuration(ms, opts) over formatDurationCompact()/Full()
+- **Pure functions**: extracted modules should have no hidden state, no I/O
+- **Tests first**: write the test suite for the new module BEFORE migrating call sites
+- **Single responsibility**: extracted module does ONE thing well
+
+## Output format (JSON-typed)
+- duplication: { callSites: [{file, function, line}], differences[] }
+- proposedModule: { path, api (TS signature), variants: [{style, example}] }
+- migration: [{step, linesToChange}]
+- benefits: string[] (3-5 bullet points)
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL5}`
+};
+var simplifyConditionals = {
+  id: "simplify-conditionals",
+  version: "1.0.0",
+  name: "Simplify Conditionals",
+  description: "Reduce cyclomatic complexity of boolean/conditional code. Extract guard clauses, replace nested if-else with lookup tables, simplify boolean expressions using De Morgan's laws.",
+  category: "refactor",
+  requiredRoles: ["atlas"],
+  requiredTools: [],
+  estimatedCost: "low",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Cyclomatic complexity > 10 in a single function",
+    "Nested if-else > 3 levels deep",
+    "Boolean expressions with > 4 terms",
+    "Multiple early returns that could be guard clauses",
+    "Switch statements with > 8 cases that share structure"
+  ],
+  antiPatterns: [
+    "Performance-critical branches (compiler will optimize nested ifs better than lookups)",
+    "Complex domain logic that IS the conditional structure (e.g. tax brackets)",
+    "Code under active development where the structure is still in flux"
+  ],
+  requires: [],
+  relatedSkills: ["extract-reusable", "refactor-monolith"],
+  tags: ["refactor", "simplification", "cyclomatic-complexity", "clean-code"],
+  examples: [
+    {
+      input: "function canUserEdit(user, doc) { if (user.isAdmin) { return true; } else { if (doc.ownerId === user.id) { return true; } else { if (doc.collaborators.includes(user.id) && !doc.locked) { return true; } else { return false; } } } }",
+      output: {
+        before: { lines: 9, cyclomaticComplexity: 5 },
+        after: { lines: 6, cyclomaticComplexity: 1 },
+        refactored: `function canUserEdit(user, doc) {
+  if (user.isAdmin) return true;
+  if (doc.ownerId === user.id) return true;
+  if (doc.collaborators.includes(user.id) && !doc.locked) return true;
+  return false;
+}`,
+        explanation: "Extracted guard clauses (early returns). Eliminated 3 levels of nesting. Cyclomatic complexity dropped from 5 to 1. Logic preserved exactly."
+      }
+    },
+    {
+      input: 'function getDiscount(tier) { if (tier === "bronze") return 0.05; else if (tier === "silver") return 0.10; else if (tier === "gold") return 0.15; else if (tier === "platinum") return 0.20; else return 0; }',
+      output: {
+        before: { lines: 7, cyclomaticComplexity: 5 },
+        after: { lines: 7, cyclomaticComplexity: 1 },
+        refactored: `const DISCOUNT_BY_TIER = { bronze: 0.05, silver: 0.10, gold: 0.15, platinum: 0.20 } as const;
+function getDiscount(tier: DiscountTier): number {
+  return DISCOUNT_BY_TIER[tier] ?? 0;
+}`,
+        explanation: "Replaced if-else chain with const lookup table. Adding a new tier = one line in the table, no function edit. Type-safe via `as const`. Default 0 via nullish coalescing."
+      }
+    }
+  ],
+  outputSchema: "{ before: { lines: number; cyclomaticComplexity: number }; after: { lines: number; cyclomaticComplexity: number }; refactored: string; explanation: string }",
+  systemPromptFragment: `You are reducing the complexity of conditional code.
+
+## Common patterns to apply
+1. **Guard clauses**: replace \`if (cond) { ...big block... } else { return false; }\` with \`if (!cond) return false; ...big block...\`
+2. **Lookup tables**: replace \`if/else if/else if/...\` chains with \`const TABLE = { ... } as const; return TABLE[key] ?? default\`
+3. **Boolean simplification**: apply De Morgan's laws (\`!(A && B)\` \u2192 \`!A || !B\`), extract complex predicates into named booleans
+4. **Polymorphism**: replace type-checking conditionals (\`if (type === 'A') ... else if (type === 'B') ...\`) with method dispatch
+
+## Output format (JSON-typed)
+- before: { lines, cyclomaticComplexity }
+- after: { lines, cyclomaticComplexity }
+- refactored: string (the new code)
+- explanation: string (1-2 sentences on what changed and why)
+
+## What NOT to do
+- Don't change behavior \u2014 only structure
+- Don't introduce new abstractions for one-off conditionals
+- Don't sacrifice readability for fewer lines (e.g. overly clever ternary chains)
+
+Stay under 400 words.${CLARIFICATION_PROTOCOL5}`
+};
+var refactorMonolith = {
+  id: "refactor-monolith",
+  version: "1.0.0",
+  name: "Refactor Monolith",
+  description: "Multi-perspective decomposition of large files (>1000 LOC) into focused modules. Identifies natural responsibility boundaries, proposes a module map with line numbers, validates no circular deps, generates a per-phase migration plan.",
+  category: "refactor",
+  requiredRoles: ["hephaestus", "atlas", "oracle"],
+  requiredTools: ["searchRAG", "createTask"],
+  estimatedCost: "high",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Single file > 1000 LOC with mixed responsibilities",
+    "Cyclomatic complexity > 50 in a single function",
+    "Multiple unrelated imports (>15 distinct packages) in one file",
+    "Onboarding new devs is hard because no one file fits in their head",
+    "Build/test times are slow because one big file recompiles on every change"
+  ],
+  antiPatterns: [
+    "File under 500 LOC \u2014 defer; not worth the migration cost",
+    "Truly cohesive file even if large (e.g. a state machine FSM)",
+    "Quick fix needed urgently \u2014 refactor first, fix second",
+    "No tests exist \u2014 write characterization tests first, refactor second"
+  ],
+  requires: ["extract-reusable"],
+  relatedSkills: ["simplify-conditionals", "architect-feature"],
+  tags: ["refactor", "modularization", "god-module", "split", "architecture"],
+  examples: [
+    {
+      input: "src/Council.tsx is 1822 LOC with mixed concerns: chat rendering, tool dispatch, voice input, slash commands, file attachments",
+      output: {
+        currentState: {
+          file: "src/Council.tsx",
+          totalLines: 1822,
+          responsibilities: ["chat render", "tool dispatch", "voice input", "slash commands", "file attachments", "settings panel", "token counter"]
+        },
+        proposedModules: [
+          { name: "ChatStream.tsx", responsibility: "render assistant/user messages", estimatedLines: 350, dependsOn: ["useChatStream hook"] },
+          { name: "ToolDispatch.tsx", responsibility: "show tool execution + results", estimatedLines: 280, dependsOn: ["brain/tool types"] },
+          { name: "VoiceInput.tsx", responsibility: "microphone + transcription UI", estimatedLines: 150, dependsOn: ["useVoiceRecorder hook"] },
+          { name: "SlashCommands.tsx", responsibility: "command palette + autocomplete", estimatedLines: 200, dependsOn: ["useSlashCommands hook"] },
+          { name: "useCouncil.ts (hook)", responsibility: "state + council orchestration logic", estimatedLines: 400, dependsOn: [] }
+        ],
+        migrationPhases: [
+          { phase: 1, name: "Extract useCouncil hook", exitCriterion: "Council.tsx < 1500 LOC, all behavior unchanged, all tests pass", durationDays: 2 },
+          { phase: 2, name: "Extract ChatStream + ToolDispatch", exitCriterion: "Council.tsx < 1000 LOC", durationDays: 3 },
+          { phase: 3, name: "Extract VoiceInput + SlashCommands", exitCriterion: "Council.tsx < 500 LOC OR deleted entirely", durationDays: 2 }
+        ],
+        risks: [
+          { risk: "Hidden circular imports between new modules", mitigation: "Run `madge --circular src/` after each phase; CI fails on circular deps." },
+          { risk: "Lost re-render optimization (inline JSX vs memoized components)", mitigation: "Phase 1 establishes React.memo + useMemo conventions before extracting." }
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ currentState: { file: string; totalLines: number; responsibilities: string[] }; proposedModules: Array<{ name: string; responsibility: string; estimatedLines: number; dependsOn: string[] }>; migrationPhases: Array<{ phase: number; name: string; exitCriterion: string; durationDays: number }>; risks: Array<{ risk: string; mitigation: string }> }",
+  systemPromptFragment: `You are planning a multi-perspective decomposition of a large file.
+
+## Methodology
+1. Identify the file's CURRENT responsibilities (read the source if needed).
+2. Search the KB for prior split decisions: searchRAG(query="<file-name-keyword>")
+3. Propose 4-8 NEW modules, each with ONE clear responsibility.
+4. Map existing functions/sections to new modules (with line numbers).
+5. Validate NO circular dependencies between proposed modules.
+6. Plan 3-5 migration phases, each independently shippable with all tests passing.
+
+## Module split principles
+- **One job per module**: if you can't describe a module's purpose in ONE sentence, split further
+- **No circular deps**: A imports B, B imports C is fine; A imports B, B imports A is not
+- **Stable abstractions**: the new module boundaries should match NATURAL responsibility seams (state vs UI vs I/O), not arbitrary line counts
+- **Testability first**: each module should be unit-testable in isolation
+
+## Output format (JSON-typed)
+- currentState: { file, totalLines, responsibilities[] }
+- proposedModules: Array<{ name, responsibility, estimatedLines, dependsOn[] }>
+- migrationPhases: Array<{ phase, name, exitCriterion, durationDays }>
+- risks: Array<{ risk, mitigation }>
+
+Stay under 600 words. Be decisive about module boundaries \u2014 pick ONE natural split, don't present 3 equally valid options.${CLARIFICATION_PROTOCOL5}`
+};
+registerCodingSkill(extractReusable);
+registerCodingSkill(simplifyConditionals);
+registerCodingSkill(refactorMonolith);
+
+// src/agents/skills/builtin/review.ts
+var CLARIFICATION_PROTOCOL6 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a wave-in response.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var securityAudit = {
+  id: "security-audit",
+  version: "1.0.0",
+  name: "Security Audit",
+  description: "OWASP Top 10 + CVE check on dependencies + secrets scan. Identifies injection vectors, auth flaws, unsafe deserialization, hardcoded credentials.",
+  category: "review",
+  requiredRoles: ["oracle"],
+  requiredTools: ["grep_content", "read_file"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Any code touching auth, session, password, token, or credential storage",
+    "Pre-release audit of the codebase",
+    "After a security incident or CVE disclosure",
+    "Quarterly compliance check",
+    "Integrating a new third-party npm dependency that handles user data"
+  ],
+  antiPatterns: [
+    "Pure UI code with no I/O \u2014 defer to code-review skill",
+    "A unit test file \u2014 no production risk",
+    "Mock/seed data \u2014 those credentials are intentionally fake"
+  ],
+  requires: [],
+  relatedSkills: ["code-review"],
+  tags: ["security", "owasp", "audit", "cve", "secrets", "compliance"],
+  examples: [
+    {
+      input: "Audit src/auth/ directory for security issues",
+      output: {
+        owaspFindings: [
+          { category: "A01:2021 Broken Access Control", severity: "HIGH", file: "src/auth/middleware.ts:34", issue: "Missing role check on /admin/* routes \u2014 any authenticated user can access admin endpoints" },
+          { category: "A02:2021 Cryptographic Failures", severity: "CRITICAL", file: "src/auth/token.ts:12", issue: "Tokens stored with SHA-256(password) instead of bcrypt/argon2 \u2014 vulnerable to rainbow tables" },
+          { category: "A03:2021 Injection", severity: "MEDIUM", file: "src/auth/login.ts:45", issue: "Email field not validated; potential XSS if rendered unsafed downstream" }
+        ],
+        cveCheck: "npm audit: 3 vulnerabilities (1 high, 2 moderate) in jsonwebtoken@8.5.1 (CVE-2022-23529) \u2014 upgrade to 9.0.0+",
+        secretsScan: "No hardcoded API keys found in src/. .env files are gitignored.",
+        priorityOrder: [
+          "1. Fix SHA-256 \u2192 bcrypt (CRITICAL)",
+          "2. Add role check middleware (HIGH)",
+          "3. Upgrade jsonwebtoken (CVE)",
+          "4. Add email validation (MEDIUM)"
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ owaspFindings: Array<{ category: string; severity: string; file: string; line: number; issue: string }>; cveCheck: string; secretsScan: string; priorityOrder: string[] }",
+  systemPromptFragment: `You are auditing the codebase for security vulnerabilities.
+
+## OWASP Top 10 (2021) \u2014 check each
+1. **A01 Broken Access Control**: missing role checks, IDOR vulnerabilities
+2. **A02 Cryptographic Failures**: weak hashing (MD5/SHA-1/SHA-256 for passwords), missing TLS
+3. **A03 Injection**: SQL injection, command injection, XSS (especially via unsafe dangerouslySetInnerHTML)
+4. **A04 Insecure Design**: missing rate limiting on auth endpoints
+5. **A05 Security Misconfiguration**: default credentials, exposed debug endpoints
+6. **A06 Vulnerable Components**: outdated dependencies with known CVEs (run npm audit)
+7. **A07 Identification & Auth Failures**: missing MFA, weak password policies
+8. **A08 Software & Data Integrity Failures**: missing signature verification on updates
+9. **A09 Logging & Monitoring Failures**: no audit log on sensitive operations
+10. **A10 SSRF**: user-controlled URLs fetched server-side without allowlist
+
+## CVE check
+- Run npm audit (or pip-audit, cargo audit, etc. depending on the stack)
+- Cross-reference with the GitHub Advisory Database
+
+## Secrets scan
+- grep for common patterns: API_KEY, SECRET, TOKEN, PASSWORD, BEGIN PRIVATE KEY
+- Check .env files are gitignored
+
+## Output format (JSON-typed)
+- owaspFindings: Array<{ category, severity, file, line, issue }>
+- cveCheck: string (results of dependency scan)
+- secretsScan: string (results of hardcoded secrets scan)
+- priorityOrder: string[] (numbered list, CRITICAL first)
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL6}`
+};
+var performanceReview = {
+  id: "performance-review",
+  version: "1.0.0",
+  name: "Performance Review",
+  description: "Identify algorithmic complexity issues (O(n\xB2), O(n\xB3)), N+1 queries, unnecessary allocations, missing caching opportunities, I/O blocking patterns.",
+  category: "review",
+  requiredRoles: ["atlas"],
+  requiredTools: ["read_file", "grep_content"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Performance regression report from users",
+    "Response time > 1s where it used to be < 100ms",
+    "CPU profiling shows a hot function",
+    "Memory growth over time (potential leak)",
+    "Database query log shows slow queries"
+  ],
+  antiPatterns: [
+    "UI-only code with no I/O or loops \u2014 defer",
+    "Code that handles < 100 items (premature optimization)",
+    "One-time scripts \u2014 performance rarely matters"
+  ],
+  requires: [],
+  relatedSkills: ["code-review"],
+  tags: ["performance", "optimization", "big-o", "caching", "memory", "profiling"],
+  examples: [
+    {
+      input: "Review src/lib/search.ts (filters 10,000 documents)",
+      output: {
+        findings: [
+          { type: "N+1 query", severity: "HIGH", file: "src/lib/search.ts:34", issue: "For each of 10,000 docs, fires a separate DB query to fetch tags. Total: 10,001 queries per search.", fix: "Use a single JOIN query to fetch all tags upfront. Reduces to 1 query." },
+          { type: "Allocation in hot loop", severity: "MEDIUM", file: "src/lib/search.ts:67", issue: "Creates a new Date object inside the filter loop (10,000 allocations per search).", fix: "Hoist the comparison date outside the loop." },
+          { type: "Missing index", severity: "MEDIUM", file: "src/lib/search.ts:45", issue: "SQL query filters by `created_at` but the table has no index on that column. Full table scan on every search.", fix: "CREATE INDEX idx_documents_created_at ON documents(created_at);" },
+          { type: "Caching opportunity", severity: "LOW", file: "src/lib/search.ts:89", issue: "Results identical for the same query within 60s window; no caching layer.", fix: "Add LRU cache keyed on query hash, TTL 60s." }
+        ],
+        bigO: "O(n) becomes O(1) with the JOIN fix + O(1) with the cache",
+        expectedSpeedup: "10-100x for typical queries"
+      }
+    }
+  ],
+  outputSchema: "{ findings: Array<{ type: string; severity: string; file: string; line: number; issue: string; fix: string }>; bigO: string; expectedSpeedup: string }",
+  systemPromptFragment: `You are reviewing code for performance issues.
+
+## Common patterns to detect
+1. **N+1 queries**: loop with a DB call inside (fetch all data upfront with a JOIN)
+2. **Allocation in hot loops**: \`new SomeClass()\` inside \`for (...)\` (hoist outside)
+3. **Missing index**: SQL filter on unindexed column (add index, EXPLAIN ANALYZE)
+4. **No caching**: identical computation repeated (LRU cache, memoize)
+5. **Blocking I/O in async**: \`await fs.readFileSync(...)\` (use async readFile)
+6. **Quadratic loops**: nested loops over the same array (use hash map for O(n) lookup)
+7. **Synchronous XHR/fetch**: blocking the main thread (use async/await or worker)
+
+## Output format (JSON-typed)
+- findings: Array<{ type, severity, file, line, issue, fix }>
+- bigO: string (the complexity change after fixes)
+- expectedSpeedup: string (estimated speedup magnitude)
+
+## Anti-patterns to avoid
+- **Don't propose premature optimizations** (caching for a function called once)
+- **Don't change behavior for performance** unless explicitly asked
+- **Profile first** \u2014 don't guess where the hot path is
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL6}`
+};
+var testCoverageAnalysis = {
+  id: "test-coverage-analysis",
+  version: "1.0.0",
+  name: "Test Coverage Analysis",
+  description: "Identify untested code branches. Suggest specific test cases that would close the coverage gap, prioritizing edge cases and error paths.",
+  category: "review",
+  requiredRoles: ["oracle", "atlas"],
+  requiredTools: ["read_file"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "Coverage report shows < 80% line coverage",
+    "A new feature was added without tests",
+    "A bug was found that should have been caught by tests",
+    "Quarterly coverage audit",
+    "Refactoring a high-churn module where regression risk is high"
+  ],
+  antiPatterns: [
+    "Tests exist but are tautologies (assertions that always pass)",
+    "Coverage targets > 95% (often forces meaningless tests)",
+    "Auto-generated code (skip \u2014 the generator has its own tests)"
+  ],
+  requires: [],
+  relatedSkills: ["code-review"],
+  tags: ["review", "testing", "coverage", "edge-cases"],
+  examples: [
+    {
+      input: "src/lib/formatDuration.ts has 6 branches; coverage report shows only 3 are tested",
+      output: {
+        untestedBranches: [
+          { branch: "ms < 0 (negative duration)", file: "src/lib/formatDuration.ts:12", suggestedTest: "expect(formatDuration(-1000)).toThrow('Negative duration')" },
+          { branch: "ms === 0", file: "src/lib/formatDuration.ts:14", suggestedTest: "expect(formatDuration(0)).toBe('0s')" },
+          { branch: "ms > 1 day (very large)", file: "src/lib/formatDuration.ts:22", suggestedTest: "expect(formatDuration(86400000 * 2)).toBe('2d')" }
+        ],
+        edgeCases: [
+          "ms is NaN (e.g. from a corrupt timestamp) \u2014 should throw",
+          "ms is Infinity (e.g. from setTimeout overflow) \u2014 should cap at a max",
+          'style option is invalid \u2014 should default to "compact"'
+        ],
+        priorityOrder: ["1. NaN/Infinity handling (data integrity)", "2. ms === 0 boundary (off-by-one)", "3. style validation (UX)"]
+      }
+    }
+  ],
+  outputSchema: "{ untestedBranches: Array<{ branch: string; file: string; line: number; suggestedTest: string }>; edgeCases: string[]; priorityOrder: string[] }",
+  systemPromptFragment: `You are identifying untested code branches.
+
+## Methodology
+1. **Read each branch** in the source file (if/else, switch cases, try/catch).
+2. **Identify untested branches** by reading the corresponding test file.
+3. **Suggest a SPECIFIC test** (not "add a test for X" \u2014 write the actual assertion).
+4. **Prioritize edge cases**: NaN, null, undefined, empty array, max int, negative numbers.
+5. **Prioritize error paths**: what happens when validation fails, network drops, etc.?
+
+## Output format (JSON-typed)
+- untestedBranches: Array<{ branch, file, line, suggestedTest }>
+- edgeCases: string[] (3-7 cases)
+- priorityOrder: string[] (numbered list)
+
+## Test quality principles
+- **One assertion per test** \u2014 easier to debug
+- **Specific assertion** \u2014 not \`expect(result).toBeTruthy()\` but \`expect(result).toBe('1h 23m')\`
+- **Test the boundary** \u2014 \`n=0\`, \`n=1\`, \`n=MAX_INT\`
+- **Test the failure path** \u2014 invalid input, network errors, partial data
+
+Stay under 400 words.${CLARIFICATION_PROTOCOL6}`
+};
+var codeReview = {
+  id: "code-review",
+  version: "1.0.0",
+  name: "Code Review",
+  description: "Multi-role review covering correctness, style, performance, security, and accessibility. Each role emits findings with severity (CRITICAL/HIGH/MEDIUM/LOW). Chairman synthesizes consensus.",
+  category: "review",
+  requiredRoles: ["oracle", "atlas", "chairman"],
+  requiredTools: ["read_file", "grep_content", "searchRAG"],
+  estimatedCost: "high",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A pull request is ready for review",
+    "A code change affects > 100 lines",
+    "Code touches auth, payments, or other security-critical paths",
+    "Before merging to main",
+    "A pre-merge sanity check on critical files"
+  ],
+  antiPatterns: [
+    "Single-line change (typo, comment fix) \u2014 direct merge",
+    "Trivial style fix (whitespace, import order) \u2014 direct merge",
+    "WIP / draft PR \u2014 review when ready",
+    "Generated code (e.g. codegen output) \u2014 review the upstream generator instead"
+  ],
+  requires: ["security-audit", "performance-review", "test-coverage-analysis"],
+  relatedSkills: ["security-audit", "performance-review", "test-coverage-analysis"],
+  tags: ["review", "multi-role", "pr-review", "correctness", "security"],
+  examples: [
+    {
+      input: "Review src/components/AuthForm.tsx (180 LOC) \u2014 adds passwordless email login",
+      output: {
+        findings: [
+          { role: "oracle", severity: "CRITICAL", line: 67, issue: "No CSRF token on the form submit", file: "src/components/AuthForm.tsx" },
+          { role: "atlas", severity: "HIGH", line: 23, issue: "N+1 query: user lookup fires on every keystroke instead of debounced", file: "src/components/AuthForm.tsx" },
+          { role: "oracle", severity: "MEDIUM", line: 102, issue: "Error message leaks server response body (XSS risk)", file: "src/components/AuthForm.tsx" },
+          { role: "chairman", severity: "LOW", line: 45, issue: "Variable name `usrEml` should be `userEmail` (style)", file: "src/components/AuthForm.tsx" }
+        ],
+        consensus: "2 CRITICAL/HIGH blockers must be fixed before merge. CSRF is the most critical. After CSRF fix, N+1 query, then error message.",
+        mergeVerdict: "BLOCK"
+      }
+    }
+  ],
+  outputSchema: '{ findings: Array<{ role: string; severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW"; line: number; issue: string; file: string }>; consensus: string; mergeVerdict: "APPROVE" | "REQUEST_CHANGES" | "BLOCK" }',
+  systemPromptFragment: `You are conducting a multi-role code review.
+
+## Review roles
+- **oracle (correctness)**: bugs, race conditions, edge cases, error handling
+- **atlas (performance)**: O(n\xB2) algorithms, N+1 queries, unnecessary allocations, missing caching
+- **oracle (security)**: injection, auth bypass, secrets in code, unsafe deserialization (overlaps with security-audit skill \u2014 run that first)
+- **atlas (accessibility)**: ARIA labels, keyboard nav, color contrast
+- **chairman (synthesis)**: aggregates all findings, emits verdict (APPROVE / REQUEST_CHANGES / BLOCK)
+
+## Severity levels
+- **CRITICAL**: must fix before merge (security, data loss, crash)
+- **HIGH**: should fix before merge (correctness bug, performance regression)
+- **MEDIUM**: nice to fix (code smell, minor perf)
+- **LOW**: nitpick (style, naming)
+
+## Output format (JSON-typed)
+- findings: Array<{ role, severity, line, issue, file }>
+- consensus: string (chairman's synthesis)
+- mergeVerdict: 'APPROVE' | 'REQUEST_CHANGES' | 'BLOCK'
+
+## Review principles
+- **Be specific**: cite file + line numbers
+- **Be actionable**: each finding has a concrete fix
+- **Don't bikeshed style** \u2014 note as LOW or skip
+- **Trust the author** \u2014 don't require changes that are preference, not correctness
+
+Stay under 600 words.${CLARIFICATION_PROTOCOL6}`
+};
+var registerCodingSkill3 = registerCodingSkill;
+registerCodingSkill3(securityAudit);
+registerCodingSkill3(performanceReview);
+registerCodingSkill3(testCoverageAnalysis);
+registerCodingSkill3(codeReview);
+
+// src/agents/skills/builtin/testing.ts
+var CLARIFICATION_PROTOCOL7 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
+- If you can proceed with a sound documented assumption, DO SO instead of asking.`;
+var writeUnitTests = {
+  id: "write-unit-tests",
+  version: "1.0.0",
+  name: "Write Unit Tests",
+  description: "TDD-style test generation for a function or module. Output: 5-10 focused unit tests covering happy paths, edge cases (empty/null/boundary), error paths. Each test has one assertion. Uses Vitest patterns (the project standard).",
+  category: "test",
+  requiredRoles: ["oracle", "atlas"],
+  requiredTools: ["read_file"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A function or module has no tests",
+    "Coverage report shows a specific function is untested",
+    "A new utility is added (helper, formatter, validator)",
+    "A bug is fixed and a regression test is needed"
+  ],
+  antiPatterns: [
+    "Integration scenarios (multi-component) \u2014 use write-integration-tests",
+    "A bug report exists \u2014 use regression-test instead (more focused)",
+    "Performance benchmarks \u2014 those need write-bench-test, not unit tests"
+  ],
+  requires: [],
+  relatedSkills: ["regression-test", "test-coverage-analysis"],
+  tags: ["test", "unit-test", "tdd", "vitest", "coverage"],
+  examples: [
+    {
+      input: "Write unit tests for src/lib/formatDuration.ts",
+      output: {
+        testFile: "tests/unit/formatDuration.test.ts",
+        tests: [
+          { name: 'formats 0 ms as "0s"', input: 0, expected: "0s" },
+          { name: 'formats 45 seconds as "45s"', input: 45e3, expected: "45s" },
+          { name: 'formats 1 minute as "1m"', input: 6e4, expected: "1m" },
+          { name: "formats 1h 23m for long duration", input: 498e4, expected: "1h 23m" },
+          { name: "formats 2d for >24h", input: 1728e5, expected: "2d" },
+          { name: "throws on negative duration", input: -1e3, expectedThrows: "Negative duration" },
+          { name: "throws on NaN", input: NaN, expectedThrows: "NaN duration" },
+          { name: "respects compact style option", input: 6e4, options: { style: "compact" }, expected: "1m" }
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ testFile: string; tests: Array<{ name: string; input: unknown; expected?: unknown; options?: Record<string, unknown>; expectedThrows?: string }> }",
+  systemPromptFragment: `You are writing Vitest unit tests for a function or module.
+
+## Methodology
+1. **Read the source**: understand the function signature, branches, error paths.
+2. **Identify happy paths**: at least 2 tests for typical inputs.
+3. **Identify edge cases** (boundaries): 0, 1, max, empty array, empty string.
+4. **Identify error paths**: invalid input, network errors, partial data.
+5. **Write one test per assertion** \u2014 easier to debug when a test fails.
+6. **Use Vitest patterns**: describe/it/expect, vi.fn() for mocks, vi.spyOn for stubs.
+
+## Test naming
+- Use \`describe('moduleName', () => { it('does X when Y', ...) })\`.
+- Test name describes behavior, not implementation.
+- Group related tests in the same describe block.
+
+## Output format (JSON-typed)
+- testFile: string (the file path)
+- tests: Array<{ name, input, expected, options?, expectedThrows? }>
+
+## Anti-patterns to avoid
+- Tests that always pass (tautologies)
+- Tests with multiple assertions (split into separate tests)
+- Tests that depend on test execution order
+- Snapshot tests for non-deterministic output
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL7}`
+};
+var writeIntegrationTests = {
+  id: "write-integration-tests",
+  version: "1.0.0",
+  name: "Write Integration Tests",
+  description: "Generate end-to-end scenario tests that span multiple components. Tests verify the integration boundary, not individual units. Uses real subsystems (or close mocks) to catch contract mismatches.",
+  category: "test",
+  requiredRoles: ["oracle", "hephaestus"],
+  requiredTools: ["read_file", "grep_content"],
+  estimatedCost: "medium",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A new feature spans 2+ modules",
+    "A new API endpoint needs end-to-end coverage",
+    "A refactor changes module boundaries \u2014 verify behavior preserved",
+    "A bug was caused by a contract mismatch between two modules"
+  ],
+  antiPatterns: [
+    "Single-component logic \u2014 use write-unit-tests",
+    "Performance benchmarks \u2014 use a dedicated perf test",
+    "Visual regression (UI snapshot) \u2014 needs screenshot diff tooling"
+  ],
+  requires: ["write-unit-tests"],
+  relatedSkills: ["write-unit-tests", "regression-test"],
+  tags: ["test", "integration", "e2e", "contract", "multi-component"],
+  examples: [
+    {
+      input: 'Integration test for "user uploads file \u2192 RAG indexes \u2192 user queries"',
+      output: {
+        testFile: "tests/integration/upload-query.test.ts",
+        scenarios: [
+          { name: "uploaded file appears in search results within 5s", steps: ["create test vault", "upload doc.md", "wait 1s for indexer", 'query "doc.md"', "expect result"] },
+          { name: "deleted file removed from search results", steps: ["upload + query (sanity)", "delete file", "wait 1s", "query", "expect no result"] },
+          { name: "concurrent uploads maintain ordering", steps: ["upload 10 files in parallel", "query each", "expect all 10 found"] },
+          { name: "corrupt file (binary garbage) does not crash indexer", steps: ["upload binary garbage", "wait 5s", "expect vault accessible (no crash)"] }
+        ],
+        contracts: [
+          { between: "vault + indexer", contract: "indexer subscribes to vault:created events and processes new files within 5s" },
+          { between: "indexer + search", contract: "search returns docs only after indexer has flushed their embeddings to SQLite" }
+        ]
+      }
+    }
+  ],
+  outputSchema: "{ testFile: string; scenarios: Array<{ name: string; steps: string[] }>; contracts: Array<{ between: string; contract: string }> }",
+  systemPromptFragment: `You are writing integration tests that span multiple components.
+
+## Methodology
+1. **Identify the integration boundary**: which 2+ components interact?
+2. **Document the contract**: what does component A promise to component B?
+3. **Test the contract, not the internals**: verify the OBSERVABLE behavior, not the implementation.
+4. **Use real subsystems where possible**: in-memory SQLite instead of mocks; fake HTTP server instead of stubbed client.
+5. **Each scenario is a complete user story**: setup \u2192 action \u2192 verify.
+
+## Output format (JSON-typed)
+- testFile: string
+- scenarios: Array<{ name, steps[] }>
+- contracts: Array<{ between, contract }>
+
+## Integration test principles
+- **Minimal mocks**: mock only the OUTSIDE world (network, disk, time), not your own code
+- **Real data**: use realistic test data, not "foo" / "bar"
+- **Deterministic**: avoid timing-based assertions (use polling with timeout)
+- **Cleanup**: each scenario should leave the system in a clean state
+
+Stay under 500 words.${CLARIFICATION_PROTOCOL7}`
+};
+var regressionTest = {
+  id: "regression-test",
+  version: "1.0.0",
+  name: "Regression Test",
+  description: "Convert a bug report into a permanent regression test. The test must fail on the BUGGY code (pre-fix), pass on the FIXED code (post-fix), and stay in the suite forever to prevent the bug from coming back.",
+  category: "test",
+  requiredRoles: ["oracle"],
+  requiredTools: ["write_file"],
+  estimatedCost: "low",
+  enabledByDefault: true,
+  builtin: true,
+  triggers: [
+    "A bug is fixed and a regression test is needed",
+    'A user reports a recurring bug ("this used to work")',
+    "A flaky test that intermittently fails",
+    "A bug found in code review"
+  ],
+  antiPatterns: [
+    "The bug has not been fixed yet \u2014 first fix, then add regression test",
+    "The bug is in test code itself \u2014 fix the test",
+    "A bug that requires impossible-to-mock state (real network, real browser)"
+  ],
+  requires: [],
+  relatedSkills: ["write-unit-tests", "reproduce-bug"],
+  tags: ["test", "regression", "bug-fix", "permanent-test"],
+  examples: [
+    {
+      input: 'Bug: "Council shows duplicate user message at session resume" was just fixed in commit a3f9d',
+      output: {
+        testFile: "tests/regression/duplicate-user-message.test.ts",
+        test: `import { describe, it, expect } from 'vitest';
+import { runCouncilPure } from '../agents/councilApi';
+
+describe('regression: duplicate user message at session resume', () => {
+  it('does not render duplicate user message when session resumes with duplicate input', async () => {
+    const messages = [
+      { role: 'user' as const, content: 'hi' },
+      { role: 'user' as const, content: 'hi' }, // duplicate from session resume
+    ];
+    const mockProvider = async function* () {
+      yield { kind: 'text' as const, delta: 'response' };
+      yield { kind: 'finish' as const, reason: 'stop' };
+    };
+    const events = [];
+    for await (const e of runCouncilPure('hi', {
+      model: 'test', provider: 'test',
+      messages,
+      tools: [],
+      councilSize: 1,
+      debateMode: false,
+      ragContext: '',
+      workspaceContext: '',
+      providerStream: mockProvider,
+    }, {})) {
+      events.push(e);
+    }
+    const userMessageDeltas = events.filter(e => e.type === 'message_delta').length;
+    expect(userMessageDeltas).toBe(1); // exactly 1, not 2
+  });
+});`,
+        whyRegression: "Bug was reported 3 times in the last month. The fix (dedup user messages on session resume) was in commit a3f9d. This test guards against future refactors breaking the dedup logic.",
+        bugCommit: "a3f9d"
+      }
+    }
+  ],
+  outputSchema: "{ testFile: string; test: string; whyRegression: string; bugCommit: string }",
+  systemPromptFragment: `You are converting a fixed bug into a permanent regression test.
+
+## Methodology
+1. **Confirm the bug is FIXED**: check git log / recent commits for the fix.
+2. **Write the test**: it should FAIL if you revert the fix (verify this mentally).
+3. **Add a comment** in the test file linking to the bug commit.
+4. **Place in tests/regression/**: separate from unit tests for visibility.
+
+## Output format (JSON-typed)
+- testFile: string
+- test: string (the full test code, runnable as-is)
+- whyRegression: string (why this test should stay forever)
+- bugCommit: string (the commit hash that fixed the bug)
+
+## Regression test principles
+- **One test per bug** \u2014 easier to identify which regression fired
+- **Reference the bug commit** in a comment so future devs understand the history
+- **Minimal repro** \u2014 strip to the essential trigger, don't include unrelated setup
+- **Never delete a regression test** without a written justification (the bug came back once, it'll come back again)
+
+Stay under 300 words.${CLARIFICATION_PROTOCOL7}`
+};
+registerCodingSkill(writeUnitTests);
+registerCodingSkill(writeIntegrationTests);
+registerCodingSkill(regressionTest);
+
+// src/agents/roles.ts
+var CLARIFICATION_PROTOCOL8 = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
 Rules for clarifications:
 - Ask AT MOST ONE question per turn, and only when genuinely blocked.
 - Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
@@ -1361,7 +3367,7 @@ var AGENT_ROLES = [
 - You run first and set context for everyone downstream; make it count.
 
 ## Output format
-A short "Analysis" section (the goal + constraints), then a "Delegation Plan" with one bullet per specialist naming what they should produce. Keep it tight \u2014 under 150 words total.${CLARIFICATION_PROTOCOL}`,
+A short "Analysis" section (the goal + constraints), then a "Delegation Plan" with one bullet per specialist naming what they should produce. Keep it tight \u2014 under 150 words total.${CLARIFICATION_PROTOCOL8}`,
     tools: ["createTask", "createPhase"],
     skills: ["project-planner", "research-analyst"]
   },
@@ -1397,7 +3403,7 @@ Example format:
 - Make dependencies explicit (task B depends on task A).
 - If the stack/platform is unknown, ask ONCE (see clarification protocol) rather than guessing.
 
-Keep plans hierarchical and practical. Stay under 250 words.${CLARIFICATION_PROTOCOL}`,
+Keep plans hierarchical and practical. Stay under 250 words.${CLARIFICATION_PROTOCOL8}`,
     tools: ["createTask", "createPhase"],
     skills: ["project-planner", "vault-manager"]
   },
@@ -1427,7 +3433,7 @@ Keep plans hierarchical and practical. Stay under 250 words.${CLARIFICATION_PROT
 ## Themes
 ## Top picks (with feasibility/novelty + de-risk note)
 
-Stay under 200 words.${CLARIFICATION_PROTOCOL}`,
+Stay under 200 words.${CLARIFICATION_PROTOCOL8}`,
     tools: ["addIdea"],
     skills: ["idea-synthesizer", "mind-mapper", "document-writer"]
   },
@@ -1454,7 +3460,7 @@ Stay under 200 words.${CLARIFICATION_PROTOCOL}`,
 - Keep the graph comprehensible: prune redundant or duplicate nodes.
 
 ## Output format
-Describe the proposed structure (root \u2192 branches \u2192 leaves) in text and, when building via tool, emit a buildMindMap payload. Stay under 200 words.${CLARIFICATION_PROTOCOL}`,
+Describe the proposed structure (root \u2192 branches \u2192 leaves) in text and, when building via tool, emit a buildMindMap payload. Stay under 200 words.${CLARIFICATION_PROTOCOL8}`,
     tools: ["buildMindMap", "addNode", "linkNodes"],
     skills: ["mind-mapper", "research-analyst"]
   },
@@ -1485,7 +3491,7 @@ Describe the proposed structure (root \u2192 branches \u2192 leaves) in text and
 ## Contradictions
 ## Top improvements
 
-Stay under 200 words. (You do not create workspace artifacts, so you do not emit a tools block \u2014 but you MAY ask the user a clarifying question if a core ambiguity blocks judgment.)${CLARIFICATION_PROTOCOL}`,
+Stay under 200 words. (You do not create workspace artifacts, so you do not emit a tools block \u2014 but you MAY ask the user a clarifying question if a core ambiguity blocks judgment.)${CLARIFICATION_PROTOCOL8}`,
     tools: [],
     skills: ["research-analyst"]
   },
@@ -1519,7 +3525,7 @@ Append EXACTLY this block at the very end of your message when you must create w
 ]
 ---END---
 Available tool names: createTask, addIdea, createPhase, buildMindMap, addNode, linkNodes, createDocument.
-Only emit this block at the very end and only if actions are needed. Otherwise output plain text.${CLARIFICATION_PROTOCOL}`,
+Only emit this block at the very end and only if actions are needed. Otherwise output plain text.${CLARIFICATION_PROTOCOL8}`,
     tools: ["createTask", "addIdea", "createPhase", "buildMindMap", "addNode", "linkNodes", "createDocument"],
     skills: ["vault-manager", "project-planner", "idea-synthesizer"]
   }
@@ -1849,6 +3855,41 @@ var AgentHarness = class {
     });
     this.emit(initialMsgEnd);
     yield initialMsgEnd;
+    const MAX_TOOL_LOOP_ITERATIONS = 12;
+    let toolLoopTurns = 0;
+    while (!this.cancelled && !hadError && toolLoopTurns < MAX_TOOL_LOOP_ITERATIONS && initialFinishRef.value === "tool_calls") {
+      toolLoopTurns++;
+      const turnMessageId = crypto.randomUUID();
+      const msgStart = createBrainEvent(
+        "message_start",
+        this.sessionId,
+        { messageId: turnMessageId, role: "assistant" }
+      );
+      this.emit(msgStart);
+      yield msgStart;
+      let turnLength = 0;
+      const turnFinishRef = { value: "stop" };
+      const turnUsageRef = { value: null };
+      for await (const ev of this.runSingleTurn(turnMessageId, turnFinishRef, turnUsageRef)) {
+        if (ev.type === "message_delta") {
+          turnLength += ev.delta.length;
+        } else if (ev.type === "error") {
+          if (ev.severity !== "cancelled") hadError = true;
+        }
+        yield ev;
+      }
+      totalLength += turnLength;
+      const msgEnd = createBrainEvent("message_end", this.sessionId, {
+        messageId: turnMessageId,
+        totalLength: turnLength,
+        finishReason: turnFinishRef.value,
+        ...turnUsageRef.value ? { usage: turnUsageRef.value } : {}
+      });
+      this.emit(msgEnd);
+      yield msgEnd;
+      initialFinishRef.value = turnFinishRef.value;
+      if (hadError || this.cancelled) break;
+    }
     let turns = 0;
     while (turns < this.maxQueuedIterations) {
       if (this.cancelled) break;
@@ -1919,6 +3960,8 @@ var AgentHarness = class {
       });
       let toolCallsThisTurn = 0;
       const maxToolCalls = this.config.maxToolCallsPerTurn;
+      let turnText = "";
+      const turnToolCalls = [];
       for await (const delta of stream) {
         if (this.cancelled) {
           const cancelEvent = createBrainEvent("error", this.sessionId, {
@@ -1931,6 +3974,7 @@ var AgentHarness = class {
           break;
         }
         if (delta.kind === "text") {
+          turnText += delta.delta;
           const deltaEvent = createBrainEvent(
             "message_delta",
             this.sessionId,
@@ -1947,6 +3991,7 @@ var AgentHarness = class {
           yield thinkEvent;
         } else if (delta.kind === "tool_call") {
           toolCallsThisTurn++;
+          turnToolCalls.push({ id: delta.toolCallId, name: delta.toolName, args: delta.args });
           const toolStartEvent = createBrainEvent("tool_execution_start", this.sessionId, {
             toolCallId: delta.toolCallId,
             toolName: delta.toolName,
@@ -1966,18 +4011,24 @@ var AgentHarness = class {
                 signal: this.activeController?.signal
               }
             );
+            const resultStr = result.ok ? String(result.value) : result.error;
             const endEvent = createBrainEvent(
               "tool_execution_end",
               this.sessionId,
               {
                 toolCallId: delta.toolCallId,
-                result: result.ok ? String(result.value) : result.error,
+                result: resultStr,
                 isError: !result.ok,
                 durationMs: Date.now() - startMs
               }
             );
             this.emit(endEvent);
             yield endEvent;
+            this.config.messages.push({
+              role: "tool",
+              toolCallId: delta.toolCallId,
+              content: resultStr
+            });
           } else if (skipped) {
             const endEvent = createBrainEvent(
               "tool_execution_end",
@@ -1991,9 +4042,21 @@ var AgentHarness = class {
             );
             this.emit(endEvent);
             yield endEvent;
+            this.config.messages.push({
+              role: "tool",
+              toolCallId: delta.toolCallId,
+              content: `[skipped] maxToolCallsPerTurn reached (limit=${maxToolCalls})`
+            });
           }
         } else if (delta.kind === "finish") {
           finishRef.value = delta.reason;
+          if (turnToolCalls.length > 0 || turnText.length > 0) {
+            this.config.messages.push({
+              role: "assistant",
+              content: turnText,
+              ...turnToolCalls.length > 0 ? { toolCalls: turnToolCalls } : {}
+            });
+          }
           break;
         } else if (delta.kind === "error") {
           const errEvent = createBrainEvent("error", this.sessionId, {
@@ -2245,9 +4308,33 @@ function resolveBaseUrl(providerId) {
 }
 function openaiCompatibleProvider(config2) {
   return async function* (params) {
+    const messages = params.messages.map((m) => {
+      if (m.role === "tool") {
+        return {
+          role: "tool",
+          tool_call_id: m.toolCallId,
+          content: m.content
+        };
+      }
+      if (m.role === "assistant" && m.toolCalls && m.toolCalls.length > 0) {
+        return {
+          role: "assistant",
+          content: m.content ?? "",
+          tool_calls: m.toolCalls.map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: {
+              name: tc.name,
+              arguments: JSON.stringify(tc.args ?? {})
+            }
+          }))
+        };
+      }
+      return { role: m.role, content: m.content };
+    });
     const body = {
       model: config2.model,
-      messages: params.messages.filter((m) => m.role !== "tool").map((m) => ({ role: m.role, content: m.content })),
+      messages,
       stream: true,
       temperature: 0.7,
       // Task G.4.2 — request the provider to send real token usage in
@@ -2257,6 +4344,17 @@ function openaiCompatibleProvider(config2) {
       // the harness will fall back to the ~4-char/token approximation.
       stream_options: { include_usage: true }
     };
+    if (params.tools && params.tools.length > 0) {
+      body.tools = params.tools.map((t) => ({
+        type: "function",
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        }
+      }));
+      body.tool_choice = "auto";
+    }
     let response;
     try {
       response = await fetch(`${config2.baseUrl}/chat/completions`, {
@@ -2339,6 +4437,9 @@ function openaiCompatibleProvider(config2) {
                 }
               }
             }
+            if (choice?.finish_reason) {
+              yield { kind: "finish", reason: choice.finish_reason };
+            }
           } catch {
           }
         }
@@ -2840,11 +4941,11 @@ var TOOL_DEFINITIONS = [
     execute: (args, ctx) => {
       if (!ctx.addDocument) return "Knowledge vault tool not available.";
       const title = args["title"] || "New Document";
-      const path17 = args["path"] || `notes/${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+      const path18 = args["path"] || `notes/${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
       const content = args["content"] || "";
       const tags = args["tags"] || [];
       ctx.addDocument({
-        path: path17,
+        path: path18,
         title,
         content,
         format: "markdown",
@@ -2853,7 +4954,7 @@ var TOOL_DEFINITIONS = [
         workspaceId: ctx.workspaceId
       });
       ctx.addActivity("vault", "created document", title);
-      return `Document "${title}" created at "${path17}".`;
+      return `Document "${title}" created at "${path18}".`;
     }
   }
 ];
@@ -5120,10 +7221,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path17) {
-  if (!path17)
+function getElementAtPath(obj, path18) {
+  if (!path18)
     return obj;
-  return path17.reduce((acc, key) => acc?.[key], obj);
+  return path18.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -5532,11 +7633,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path17, issues) {
+function prefixIssues(path18, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path17);
+    iss.path.unshift(path18);
     return iss;
   });
 }
@@ -5683,16 +7784,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path17 = []) => {
+  const processError = (error52, path18 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path18, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else {
-        const fullpath = [...path17, ...issue2.path];
+        const fullpath = [...path18, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -5719,17 +7820,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error52, path17 = []) => {
+  const processError = (error52, path18 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path18, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else {
-        const fullpath = [...path17, ...issue2.path];
+        const fullpath = [...path18, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -5761,8 +7862,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path17 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path17) {
+  const path18 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path18) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -18454,13 +20555,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path17 = ref.slice(1).split("/").filter(Boolean);
-  if (path17.length === 0) {
+  const path18 = ref.slice(1).split("/").filter(Boolean);
+  if (path18.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path17[0] === defsKey) {
-    const key = path17[1];
+  if (path18[0] === defsKey) {
+    const key = path18[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -19073,8 +21174,83 @@ var grepContentTool = {
   }
 };
 
-// src/cli/safety/sandboxPath.ts
+// src/main/core/tools/builtin/listFiles.ts
+import { promises as fs11 } from "node:fs";
 import path10 from "node:path";
+var ListFilesArgsSchema = external_exports.object({
+  /** Directory to list (relative to cwd or absolute). Defaults to cwd. */
+  path: external_exports.string().optional(),
+  /** Max traversal depth. 1 = immediate children only (default). */
+  maxDepth: external_exports.number().int().positive().max(10).default(1),
+  /** Glob-style patterns to exclude (matched against each entry name). */
+  exclude: external_exports.array(external_exports.string()).default([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "__pycache__",
+    ".cache"
+  ])
+});
+function matchesAny(name, patterns) {
+  return patterns.some((p3) => {
+    if (p3.includes("*")) {
+      const regex = new RegExp("^" + p3.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$");
+      return regex.test(name);
+    }
+    return name === p3;
+  });
+}
+async function walk(dir, baseRel, depth, maxDepth, exclude, entries, signal) {
+  if (depth > maxDepth) return;
+  let dirents;
+  try {
+    dirents = await fs11.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  if (signal?.aborted) return;
+  for (const dirent of dirents) {
+    if (matchesAny(dirent.name, exclude)) continue;
+    const rel = baseRel ? `${baseRel}/${dirent.name}` : dirent.name;
+    const isDir = dirent.isDirectory();
+    entries.push({
+      name: rel,
+      type: isDir ? "directory" : dirent.isFile() ? "file" : "other"
+    });
+    if (isDir && depth < maxDepth) {
+      await walk(path10.join(dir, dirent.name), rel, depth + 1, maxDepth, exclude, entries, signal);
+    }
+  }
+}
+var listFilesTool = {
+  name: "list_files",
+  description: "List files and directories in the given path (defaults to the working directory). Returns names with types (file/directory). Use this to discover the project structure before reading specific files. Supports a maxDepth for recursive listing and excludes common dependency/build directories by default.",
+  permissions: ["read"],
+  timeoutMs: 15e3,
+  inputSchema: ListFilesArgsSchema,
+  execute: async (args, ctx) => {
+    try {
+      const target = args.path ? path10.isAbsolute(args.path) ? args.path : path10.join(ctx.cwd, args.path) : ctx.cwd;
+      const entries = [];
+      await walk(target, "", 1, args.maxDepth, args.exclude, entries, ctx.signal);
+      entries.sort((a, b) => {
+        if (a.type === "directory" && b.type !== "directory") return -1;
+        if (a.type !== "directory" && b.type === "directory") return 1;
+        return a.name.localeCompare(b.name);
+      });
+      const MAX_ENTRIES = 500;
+      const truncated = entries.length > MAX_ENTRIES;
+      return typedOk({ dir: target, entries: truncated ? entries.slice(0, MAX_ENTRIES) : entries, truncated });
+    } catch (err) {
+      return typedErr(err instanceof Error ? err.message : String(err));
+    }
+  }
+};
+
+// src/cli/safety/sandboxPath.ts
+import path11 from "node:path";
 var SandboxViolationError = class extends Error {
   constructor(message, attemptedPath, resolvedPath) {
     super(message);
@@ -19087,9 +21263,9 @@ function resolveSandboxedPath(userPath, options = {}) {
   if (typeof userPath !== "string" || userPath.length === 0) {
     throw new SandboxViolationError("Empty path", userPath, "");
   }
-  const root = path10.resolve(options.root ?? process.cwd());
-  const resolved = path10.isAbsolute(userPath) ? path10.resolve(userPath) : path10.resolve(root, userPath);
-  const rootWithSep = root.endsWith(path10.sep) ? root : root + path10.sep;
+  const root = path11.resolve(options.root ?? process.cwd());
+  const resolved = path11.isAbsolute(userPath) ? path11.resolve(userPath) : path11.resolve(root, userPath);
+  const rootWithSep = root.endsWith(path11.sep) ? root : root + path11.sep;
   if (resolved !== root && !resolved.startsWith(rootWithSep)) {
     throw new SandboxViolationError(
       `Path escapes sandbox root: ${userPath} \u2192 ${resolved} (root: ${root})`,
@@ -19152,8 +21328,8 @@ function assertShellAllowed(command) {
 }
 
 // src/cli/safety/auditLogger.ts
-import { promises as fs11 } from "node:fs";
-import path11 from "node:path";
+import { promises as fs12 } from "node:fs";
+import path12 from "node:path";
 import os7 from "node:os";
 var AuditLogger = class {
   logPath;
@@ -19172,8 +21348,8 @@ var AuditLogger = class {
   async append(entry) {
     const line = JSON.stringify(entry) + "\n";
     this.writeQueue = this.writeQueue.then(async () => {
-      await fs11.mkdir(path11.dirname(this.logPath), { recursive: true });
-      await fs11.appendFile(this.logPath, line, "utf-8");
+      await fs12.mkdir(path12.dirname(this.logPath), { recursive: true });
+      await fs12.appendFile(this.logPath, line, "utf-8");
     });
     return this.writeQueue;
   }
@@ -19216,7 +21392,7 @@ var AuditLogger = class {
 function defaultAuditPath() {
   const override = process.env.ANATHEMA_AUDIT_LOG;
   if (override && override.trim().length > 0) return override;
-  return path11.join(os7.tmpdir(), "zelari-code", "audit.jsonl");
+  return path12.join(os7.tmpdir(), "zelari-code", "audit.jsonl");
 }
 function redactArgs(args) {
   const redacted = {};
@@ -19248,6 +21424,7 @@ function createBuiltinToolRegistry(options = {}) {
   const safeWriteFile = wrapWithSandbox(writeFileTool, ["path"], root, audit, sessionId);
   const safeEditFile = wrapWithSandbox(editFileTool, ["path"], root, audit, sessionId);
   const safeGrepContent = wrapWithSandbox(grepContentTool, ["path"], root, audit, sessionId);
+  const safeListFiles = wrapWithSandbox(listFilesTool, ["path"], root, audit, sessionId);
   const safeBash = wrapWithShellSafety(bashTool, audit, sessionId);
   const registry3 = new ToolRegistry();
   registry3.register(safeReadFile);
@@ -19255,12 +21432,14 @@ function createBuiltinToolRegistry(options = {}) {
   registry3.register(safeEditFile);
   registry3.register(safeBash);
   registry3.register(safeGrepContent);
+  registry3.register(safeListFiles);
   const tools = [
     safeReadFile,
     safeWriteFile,
     safeEditFile,
     safeBash,
-    safeGrepContent
+    safeGrepContent,
+    safeListFiles
   ].map((t) => ({
     name: t.name,
     description: t.description,
@@ -19377,7 +21556,7 @@ function redactForAudit(args) {
 // src/cli/gitOps.ts
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import path12 from "node:path";
+import path13 from "node:path";
 var execFileAsync = promisify(execFile);
 async function git(cwd, args) {
   try {
@@ -19423,7 +21602,7 @@ async function undoWorkingChanges(opts = {}) {
   };
 }
 function defaultProjectRoot() {
-  return path12.resolve(__dirname, "..", "..", "..");
+  return path13.resolve(__dirname, "..", "..", "..");
 }
 
 // src/cli/compaction.ts
@@ -19464,16 +21643,16 @@ function formatCompactionSummary(result) {
 }
 
 // src/cli/metrics.ts
-import { promises as fs12, existsSync as existsSync7, statSync as statSync3, renameSync, appendFileSync, mkdirSync as mkdirSync7 } from "node:fs";
-import path13 from "node:path";
+import { promises as fs13, existsSync as existsSync7, statSync as statSync3, renameSync, appendFileSync, mkdirSync as mkdirSync7 } from "node:fs";
+import path14 from "node:path";
 import os8 from "node:os";
 var METRICS_ROTATE_BYTES = 10 * 1024 * 1024;
 var MetricsLogger = class {
   file;
   writeQueue = Promise.resolve();
   constructor(file2) {
-    this.file = file2 ?? process.env.ANATHEMA_METRICS_FILE ?? path13.join(os8.homedir(), ".tmp", "zelari-code", "metrics.jsonl");
-    mkdirSync7(path13.dirname(this.file), { recursive: true });
+    this.file = file2 ?? process.env.ANATHEMA_METRICS_FILE ?? path14.join(os8.homedir(), ".tmp", "zelari-code", "metrics.jsonl");
+    mkdirSync7(path14.dirname(this.file), { recursive: true });
   }
   /** Fire-and-forget record append. */
   record(rec) {
@@ -19524,8 +21703,8 @@ function getMetricsLogger() {
 }
 
 // src/cli/skillHistory.ts
-import { promises as fs13, existsSync as existsSync8, statSync as statSync4, renameSync as renameSync2, appendFileSync as appendFileSync2, mkdirSync as mkdirSync8 } from "node:fs";
-import path14 from "node:path";
+import { promises as fs14, existsSync as existsSync8, statSync as statSync4, renameSync as renameSync2, appendFileSync as appendFileSync2, mkdirSync as mkdirSync8 } from "node:fs";
+import path15 from "node:path";
 import os9 from "node:os";
 import { randomUUID as randomUUID2 } from "node:crypto";
 var SKILL_HISTORY_ROTATE_BYTES = 10 * 1024 * 1024;
@@ -19534,8 +21713,8 @@ var SkillHistoryLogger = class {
   writeQueue = Promise.resolve();
   inflight = /* @__PURE__ */ new Map();
   constructor(file2) {
-    this.file = file2 ?? process.env.ANATHEMA_SKILL_HISTORY_FILE ?? path14.join(os9.homedir(), ".tmp", "zelari-code", "skill-history.jsonl");
-    mkdirSync8(path14.dirname(this.file), { recursive: true });
+    this.file = file2 ?? process.env.ANATHEMA_SKILL_HISTORY_FILE ?? path15.join(os9.homedir(), ".tmp", "zelari-code", "skill-history.jsonl");
+    mkdirSync8(path15.dirname(this.file), { recursive: true });
   }
   /**
    * Mark the start of a skill invocation. Returns a unique invocationId
@@ -19613,7 +21792,7 @@ var SkillHistoryLogger = class {
 async function readSkillHistory(file2) {
   let raw = "";
   try {
-    raw = await fs13.readFile(file2, "utf-8");
+    raw = await fs14.readFile(file2, "utf-8");
   } catch {
     return [];
   }
@@ -19649,7 +21828,7 @@ function getSkillStats(records, skillId, sinceTs) {
 }
 
 // src/cli/app.tsx
-import path16 from "node:path";
+import path17 from "node:path";
 import os10 from "node:os";
 var MODEL = process.env.OPENAI_MODEL ?? "grok-4";
 var PROVIDER = "openai-compatible";
@@ -19887,13 +22066,42 @@ function App() {
       primary: baseProviderStream,
       fallback: failoverResolution.fallback
     });
+    const cwd = process.cwd();
+    const toolList = toolRegistry.toOpenAITools().map((t) => `- ${t.function.name}: ${t.function.description}`).join("\n");
+    const systemPrompt = [
+      "You are Zelari Code, an interactive AI coding agent operating directly in the user's terminal.",
+      "",
+      "You ARE connected to this machine and have real tools to read, modify, and explore the codebase.",
+      "Never claim you lack filesystem or shell access \u2014 you have it. Use your tools instead of asking the user to paste file contents.",
+      "",
+      `# Working Directory`,
+      `You are running in: ${cwd}`,
+      "All relative file paths are resolved against this directory. Always work with real files here.",
+      "",
+      "# Available Tools",
+      "You can call these tools. Use them to take action and gather information autonomously:",
+      toolList,
+      "",
+      "# Guidelines",
+      "- To understand a project, list files (bash: ls) and read key files (read_file), don't ask the user to paste them.",
+      "- Be proactive: explore, read, and act. Prefer doing over asking.",
+      "- When you finish a task, briefly summarize what you did."
+    ].join("\n");
     const harness = new AgentHarness({
       model: envConfig.model,
       provider: PROVIDER,
-      messages: [{ role: "user", content: userText }],
-      tools: toolRegistry.toOpenAITools(),
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userText }
+      ],
+      tools: toolRegistry.toOpenAITools().map((t) => ({
+        name: t.function.name,
+        description: t.function.description,
+        parameters: t.function.parameters
+      })),
       toolRegistry,
-      providerStream
+      providerStream,
+      cwd
     });
     harnessRef.current = harness;
     setQueueCount(harness.queueLength);
@@ -20418,9 +22626,9 @@ ${lines.join("\n")}`;
     if (result.kind === "promote_member" && result.promoteMemberId) {
       try {
         const { skill, markdown } = promoteMember(result.promoteMemberId);
-        const skillDir = process.env.ANATHEMA_SKILL_DIR ?? path16.join(os10.homedir(), ".tmp", "zelari-code", "skills");
+        const skillDir = process.env.ANATHEMA_SKILL_DIR ?? path17.join(os10.homedir(), ".tmp", "zelari-code", "skills");
         await fs.promises.mkdir(skillDir, { recursive: true });
-        const filePath = path16.join(skillDir, `${skill.id}.md`);
+        const filePath = path17.join(skillDir, `${skill.id}.md`);
         await fs.promises.writeFile(filePath, markdown, "utf8");
         setMessages((prev) => [
           ...prev,
@@ -21150,7 +23358,7 @@ ${lines.join("\n")}`,
       return;
     }
     if (result.kind === "skill_stats") {
-      const historyFile = process.env.ANATHEMA_SKILL_HISTORY_FILE ?? path16.join(os10.homedir(), ".tmp", "zelari-code", "skill-history.jsonl");
+      const historyFile = process.env.ANATHEMA_SKILL_HISTORY_FILE ?? path17.join(os10.homedir(), ".tmp", "zelari-code", "skill-history.jsonl");
       try {
         const records = await readSkillHistory(historyFile);
         const stats = getSkillStats(records, result.skillStatsSkillId);
@@ -21179,7 +23387,7 @@ ${lines.join("\n")}`,
         setInput("");
         return;
       }
-      const historyFile = process.env.ANATHEMA_SKILL_HISTORY_FILE ?? path16.join(os10.homedir(), ".tmp", "zelari-code", "skill-history.jsonl");
+      const historyFile = process.env.ANATHEMA_SKILL_HISTORY_FILE ?? path17.join(os10.homedir(), ".tmp", "zelari-code", "skill-history.jsonl");
       try {
         const formatted = await compareSkillsFromFile(ids[0], ids[1], historyFile);
         setMessages((prev) => [
@@ -21235,7 +23443,7 @@ ${lines.join("\n")}`,
 }
 
 // src/cli/main.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 async function backgroundUpdateCheck() {
   if (process.env.ANATHEMA_DEV === "1") return;
   await new Promise((resolve) => setTimeout(resolve, 3e3));