@difflab/difflab-cli 0.3.0 → 0.5.0

package/dist/index.js

@@ -33,6 +33,19 @@ var __toESM = (mod, isNodeMode, target) => {
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
 var __esm = (fn, res, err) => () => {
   if (fn)
     try {
@@ -12783,17 +12796,17 @@ var init_registry = __esm(() => {
 // ../../libs/difflab-ts/src/gitx.ts
 import { execFileSync } from "child_process";
 import { appendFile, readFile } from "fs/promises";
-import { isAbsolute, join, resolve as resolve2 } from "path";
+import { isAbsolute, resolve as resolve2 } from "path";
 function gitRoot(cwd) {
   return runGit(cwd, ["rev-parse", "--show-toplevel"]);
 }
 function discoverGitRepository(cwd) {
   const root = gitRoot(cwd);
-  const gitDir = runGit(root, ["rev-parse", "--git-dir"]);
+  const exclude = runGit(root, ["rev-parse", "--git-path", "info/exclude"]);
   return {
     root,
     originUrl: runGit(root, ["remote", "get-url", "origin"]),
-    excludePath: join(isAbsolute(gitDir) ? gitDir : resolve2(root, gitDir), "info", "exclude")
+    excludePath: isAbsolute(exclude) ? exclude : resolve2(root, exclude)
   };
 }
 async function addPathToGitExcludes(path, entry) {
@@ -26472,9 +26485,9 @@ var init_dist3 = __esm(() => {
 
 // src/projects/config.ts
 import { lstat as lstat2, readFile as readFile2, writeFile } from "fs/promises";
-import { join as join2 } from "path";
+import { join } from "path";
 function repoConfigPath(root = process.cwd()) {
-  return join2(root, "difflab.yaml");
+  return join(root, "difflab.yaml");
 }
 async function readRepoConfig(root = process.cwd()) {
   const path = repoConfigPath(root);
@@ -26535,7 +26548,7 @@ var init_config = __esm(() => {
 import { realpathSync } from "fs";
 import { lstat as lstat3, mkdir } from "fs/promises";
 import { homedir } from "os";
-import { join as join3, resolve as resolve3 } from "path";
+import { join as join2, resolve as resolve3 } from "path";
 function userPaths(home = process.env.HOME || homedir()) {
   let tilde;
   try {
@@ -26545,8 +26558,8 @@ function userPaths(home = process.env.HOME || homedir()) {
       throw error;
     tilde = resolve3(home);
   }
-  const root = join3(tilde, ".difflab");
-  return { root, projects: join3(root, "projects"), database: join3(root, "difflab.sqlite") };
+  const root = join2(tilde, ".difflab");
+  return { root, projects: join2(root, "projects"), database: join2(root, "difflab.sqlite") };
 }
 function createUserStore(home) {
   return {
@@ -26630,25 +26643,65 @@ function hasErrorCode(error, code) {
 }
 var init_osx = () => {};
 
+// src/extensions/pathx.ts
+import { lstat as lstat4, realpath, stat } from "fs/promises";
+import { isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve4, sep } from "path";
+async function resolvePath(cwd, path) {
+  if (!isAbsolute2(cwd))
+    throw new Error("cwd must be an absolute path to an existing directory");
+  if (!path.trim() || isAbsolute2(path))
+    throw new Error("path must be a non-empty relative file path");
+  const root = await realpath(cwd);
+  if (!(await stat(root)).isDirectory())
+    throw new Error("cwd must be an existing directory");
+  const file = resolve4(root, path);
+  const inside = relative(root, file);
+  if (!inside || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute2(inside)) {
+    throw new Error("path must name a file inside cwd; parent traversal outside cwd is not allowed");
+  }
+  let current = root;
+  for (const segment of inside.split(sep)) {
+    current = join3(current, segment);
+    try {
+      if ((await lstat4(current)).isSymbolicLink()) {
+        throw new Error(`Symlink paths are not allowed for files: ${current}`);
+      }
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT"))
+        break;
+      throw error;
+    }
+  }
+  return file;
+}
+var init_pathx = __esm(() => {
+  init_osx();
+});
+
 // src/extensions/fsx.ts
 import { randomUUID as randomUUID3 } from "crypto";
-import { lstat as lstat4, mkdir as mkdir2, readFile as readFile3, rename, rm, writeFile as writeFile2 } from "fs/promises";
+import { lstat as lstat5, mkdir as mkdir2, readFile as readFile3, rename, rm, writeFile as writeFile2 } from "fs/promises";
 import { dirname } from "path";
 async function lstatOrNull(file) {
   try {
-    return await lstat4(file);
+    return await lstat5(file);
   } catch (error) {
     if (hasErrorCode(error, "ENOENT"))
       return null;
     throw error;
   }
 }
+async function ensurePathDirsExist(path, cwd = process.cwd()) {
+  const file = await resolvePath(cwd, path);
+  await mkdir2(dirname(file), { recursive: true });
+  return resolvePath(cwd, path);
+}
 function isObject3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 async function readJsonFile(file) {
   try {
-    if ((await lstat4(file)).isSymbolicLink())
+    if ((await lstat5(file)).isSymbolicLink())
       throw new Error(`JSON file at ${file} is a symlink`);
     const parsed = JSON.parse(await readFile3(file, "utf8"));
     if (!isObject3(parsed))
@@ -26674,11 +26727,12 @@ async function patchJsonToFile(file, patch) {
 }
 var init_fsx = __esm(() => {
   init_osx();
+  init_pathx();
 });
 
 // src/projects/repo-store.ts
 import { mkdir as mkdir3, readlink, symlink } from "fs/promises";
-import { dirname as dirname2, join as join4, resolve as resolve4 } from "path";
+import { dirname as dirname2, join as join4, resolve as resolve5 } from "path";
 async function preflightRepoStore(root, target) {
   for (const path of [root, dirname2(target)]) {
     const entry = await lstatOrNull(path);
@@ -26693,7 +26747,7 @@ async function preflightRepoStore(root, target) {
   if (entry) {
     if (!entry.isSymbolicLink())
       throw new RepoStoreError(`Refusing to replace existing .difflab path: ${link}`);
-    if (resolve4(root, await readlink(link)) !== resolve4(target))
+    if (resolve5(root, await readlink(link)) !== resolve5(target))
       throw new RepoStoreError(`.difflab already links elsewhere: ${link}`);
   }
 }
@@ -26704,7 +26758,7 @@ async function checkRepoStore(root, target, excludePath) {
     throw new RepoStoreError(`Missing .difflab symlink at ${link}`);
   if (!entry.isSymbolicLink())
     throw new RepoStoreError(`Refusing to replace existing .difflab path: ${link}`);
-  if (resolve4(root, await readlink(link)) !== resolve4(target))
+  if (resolve5(root, await readlink(link)) !== resolve5(target))
     throw new RepoStoreError(`.difflab already links elsewhere: ${link}`);
   const targetStat = await lstatOrNull(target);
   if (!targetStat?.isDirectory())
@@ -47818,7 +47872,8 @@ function defineTool(name, config, handler, options = {}) {
     },
     callback: async (untrustedInput) => {
       try {
-        return serializeToolResult(await handler(config.inputSchema.parse(untrustedInput)), config.outputSchema);
+        const value = await handler(config.inputSchema.parse(untrustedInput));
+        return serializeToolResult(value, config.outputSchema, options.toStructuredContent?.(value) ?? value);
       } catch (error) {
         return {
           ...serializeToolResult({
@@ -47830,49 +47885,14 @@ function defineTool(name, config, handler, options = {}) {
     }
   };
 }
-function serializeToolResult(value, outputSchema) {
-  const structuredContent = outputSchema?.parse(value);
+function serializeToolResult(value, outputSchema, content = value) {
+  const structuredContent = outputSchema?.parse(content);
   return {
     content: [{ type: "text", text: JSON.stringify(value) }],
     ...structuredContent ? { structuredContent } : {}
   };
 }
 
-// src/extensions/pathx.ts
-import { lstat as lstat5, realpath, stat } from "fs/promises";
-import { isAbsolute as isAbsolute2, join as join6, relative, resolve as resolve5, sep } from "path";
-async function resolvePath(cwd, path) {
-  if (!isAbsolute2(cwd))
-    throw new Error("cwd must be an absolute path to an existing directory");
-  if (!path.trim() || isAbsolute2(path))
-    throw new Error("path must be a non-empty relative file path");
-  const root = await realpath(cwd);
-  if (!(await stat(root)).isDirectory())
-    throw new Error("cwd must be an existing directory");
-  const file = resolve5(root, path);
-  const inside = relative(root, file);
-  if (!inside || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute2(inside)) {
-    throw new Error("path must name a file inside cwd; parent traversal outside cwd is not allowed");
-  }
-  let current = root;
-  for (const segment of inside.split(sep)) {
-    current = join6(current, segment);
-    try {
-      if ((await lstat5(current)).isSymbolicLink()) {
-        throw new Error(`Symlink paths are not allowed for files: ${current}`);
-      }
-    } catch (error) {
-      if (hasErrorCode(error, "ENOENT"))
-        break;
-      throw error;
-    }
-  }
-  return file;
-}
-var init_pathx = __esm(() => {
-  init_osx();
-});
-
 // src/stores/json-file-store.ts
 import { randomUUID as randomUUID4 } from "crypto";
 import { mkdir as mkdir4, readFile as readFile4, rename as rename2, rm as rm2, writeFile as writeFile3 } from "fs/promises";
@@ -48161,14 +48181,100 @@ var init_tools = __esm(() => {
   ];
 });
 
-// src/projects/tools.ts
+// src/extensions/zodx.ts
 import { isAbsolute as isAbsolute4 } from "path";
+var absolutePath, relativePath, fileName;
+var init_zodx = __esm(() => {
+  init_zod();
+  absolutePath = string2().refine(isAbsolute4, "path must be absolute");
+  relativePath = string2().min(1).refine((value) => value.trim().length > 0 && !isAbsolute4(value), "path must be relative");
+  fileName = string2().refine((value) => value.trim().length > 0 && value !== "." && value !== ".." && !/[/\\\0]/.test(value), "filename must be a single non-empty file name");
+});
+
+// src/logs/store.ts
+import { constants } from "fs";
+import { lstat as lstat6, open as open2, realpath as realpath2 } from "fs/promises";
+import { basename, dirname as dirname5, isAbsolute as isAbsolute5, resolve as resolve8 } from "path";
+async function appendProgressLog(path, message, now = new Date) {
+  if (!isAbsolute5(path) || resolve8(path) !== path || basename(path) !== "logs.txt") {
+    throw new ProgressLogError("path must be an absolute, normalized path ending in logs.txt");
+  }
+  if (!message.trim() || /[\r\n\v\f\0\u0085\u2028\u2029]/.test(message) || Buffer.byteLength(message, "utf8") > 2048) {
+    throw new ProgressLogError("message must be one non-empty line of at most 2048 bytes");
+  }
+  const parent = dirname5(path);
+  if (await realpath2(parent) !== parent) {
+    throw new ProgressLogError("path must not contain symlinked directories");
+  }
+  const pad = (value) => String(value).padStart(2, "0");
+  const stamp = `${pad(now.getFullYear() % 100)}${pad(now.getMonth() + 1)}${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+  const entry = `[${stamp}]: ${message}`;
+  try {
+    const existing = await lstat6(path);
+    if (existing.isSymbolicLink())
+      throw new ProgressLogError("logs.txt must not be a symlink");
+    if (!existing.isFile())
+      throw new ProgressLogError("logs.txt must be a regular file");
+  } catch (error) {
+    if (!hasErrorCode(error, "ENOENT"))
+      throw error;
+  }
+  let handle;
+  try {
+    handle = await open2(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 384);
+  } catch (error) {
+    if (hasErrorCode(error, "ELOOP"))
+      throw new ProgressLogError("logs.txt must not be a symlink");
+    throw error;
+  }
+  try {
+    if (!(await handle.stat()).isFile())
+      throw new ProgressLogError("logs.txt must be a regular file");
+    const line = Buffer.from(`${entry}
+`, "utf8");
+    const { bytesWritten } = await handle.write(line);
+    if (bytesWritten !== line.length)
+      throw new ProgressLogError("Could not append the full log line");
+  } finally {
+    await handle.close();
+  }
+  return { path, entry };
+}
+var ProgressLogError;
+var init_store2 = __esm(() => {
+  init_osx();
+  ProgressLogError = class ProgressLogError extends Error {
+  };
+});
+
+// src/logs/tools.ts
+var logOutput, logTools;
+var init_tools2 = __esm(() => {
+  init_zod();
+  init_zodx();
+  init_store2();
+  logOutput = object({ result: object({ path: string2(), entry: string2() }) });
+  logTools = [
+    defineTool("log_append", {
+      description: "Append one locally timestamped progress line to logs.txt at an absolute physical path. The parent directory must already exist; create the file if absent, never overwrite prior entries.",
+      inputSchema: strictObject({
+        path: absolutePath.describe("Absolute physical path to an existing plan directory/logs.txt"),
+        message: string2().min(1).describe("Single-line progress message")
+      }),
+      outputSchema: logOutput,
+      annotations: { openWorldHint: false }
+    }, async ({ path, message }) => appendProgressLog(path, message), { toStructuredContent: (result) => ({ result }) })
+  ];
+});
+
+// src/projects/tools.ts
+import { isAbsolute as isAbsolute6 } from "path";
 function createProjectTools(home) {
   return [
     defineTool("project_context", {
       description: "Read the configured Difflab project and GitHub repository for an existing absolute cwd. Never sets up or modifies a repository.",
       inputSchema: strictObject({
-        cwd: string2().refine(isAbsolute4, "cwd must be an absolute existing directory")
+        cwd: string2().refine(isAbsolute6, "cwd must be an absolute existing directory")
       }),
       outputSchema: projectContextOutput,
       annotations: { readOnlyHint: true, openWorldHint: false }
@@ -48176,7 +48282,7 @@ function createProjectTools(home) {
   ];
 }
 var setupHint = "Use the difflab-init skill to set up this repository with the Difflab CLI.", projectContextOutput, projectTools;
-var init_tools2 = __esm(() => {
+var init_tools3 = __esm(() => {
   init_zod();
   init_context();
   projectContextOutput = strictObject({
@@ -48193,10 +48299,1171 @@ var init_tools2 = __esm(() => {
   projectTools = createProjectTools();
 });
 
+// templates/spec-driven-plan.md
+var spec_driven_plan_default = `# [Outcome to deliver]
+
+- **Status:** draft
+- **Branch:** [branch]
+- **Issue:** [issue or none]
+
+## Intent
+
+[Who needs this change, what should be possible afterward, and why now?]
+
+## Requirements
+
+- [Observable outcome and how to tell whether it works.]
+- [Limits and explicit non-goals.]
+
+## Design
+
+### Big Ideas
+
+[Describe the intended behavior and the main architectural choices.]
+
+### Infrastructure Changes
+
+[Any infra changes. Optional. Only include if there's actual infra being handled in repo.]
+
+### Interfaces
+
+[CLI commands, API endpoint, data contracts, db entities, modules, apps, libs, project tasks added, changed or removed. Summary of how a user's interaction with the app/lib/cli/sdk/etc. will change as a result.]
+
+### Consequences
+
+[Trade-offs, risks, compatibility, and what is deferred.]
+
+## Phases
+
+[Instructions broken down granularly, specifying modules/classes/methods/files to be added/updated/removed, and relevant technical work done with terse reasoning. Terse for human readers, sufficiently detailed for delegating implementation to less capable language models i.e. a fool proof guide for a junior developer.]
+
+### Phase 1: [Outcome]
+
+- [ ] [Task A]
+- [ ] [Task B]
+- [ ] [Task C]
+- [ ] [Task D]
+- [ ] Validation
+  - [ ] Lint, format, etc.
+  - [ ] Commit, CI green (if expected)
+
+### Phase 2: [Outcome]
+
+- [ ] [Task A]
+- [ ] [Task B]
+- [ ] [Task C]
+- [ ] [Task D]
+- [ ] Validation
+  - [ ] Lint, format, etc.
+  - [ ] Commit, CI green (if expected)
+
+### Phase 3: [Outcome]
+
+- [ ] [Task A]
+- [ ] [Task B]
+- [ ] [Task C]
+- [ ] [Task D]
+- [ ] Validation
+  - [ ] Lint, format, etc.
+  - [ ] Commit, CI green (if expected)
+
+## References
+
+- [Source or related decision.]
+- [External references, docs supporting the implementation plan.]
+`;
+var init_spec_driven_plan = () => {};
+
+// templates/software-architecture-design.md
+var software_architecture_design_default = `# [System or feature] \u2014 software architecture
+
+## Overview
+
+[Purpose, system boundary, users, and explicit non-goals.]
+
+## Requirement
+
+### Functional
+
+[Functionality app, lib or product must perform.]
+
+- FR1
+- FR2
+- ...
+
+### Non-Functional
+
+[Performance, security, cost and other non-functional characteristics which the system must fulfil.]
+
+- NFR1
+- NFR2
+
+## Design
+
+### Components and Responsibilities
+
+[System diagram(s) with bullet list enumerating and explaining components and their relationships. Prefer mermaid diagrams unless user/AGENTS.md provde other stated preferences.]
+
+> @agent: add example mermaid diagram
+
+\`\`\`mermaid
+
+\`\`\`
+
+- Component A does this.
+- It then calls component B to do this.
+- And so on.
+
+### Data and Control Flow
+
+[Describe the main request/event path and where state lives. Include flow charts or sequence diagrams if applicable.]
+
+### Interfaces and Contracts
+
+[Database entities, input/output schemas, endpoints, core types, and public methods. Include ERD where applicable.]
+
+## Implementation
+
+### Important topic 1
+
+[Owned modules, dependency direction, and extension points.]
+
+### Important topic 2
+
+[More important topics.]
+
+## References
+
+- [Relevant code, ADR, or external specification.]
+`;
+var init_software_architecture_design = () => {};
+
+// templates/architecture-decision-record.md
+var architecture_decision_record_default = `# [Decision: problem and chosen solution]
+
+- **Status:** proposed
+- **Deciders:** [people or team]
+- **Date:** [YYYY-MM-DD]
+
+## Context and Problem Statement
+
+[What decision is needed, and what happens if we do nothing?]
+
+## Decision Drivers
+
+- [Constraint or quality attribute.]
+
+## Considered Options
+
+### [Option A]
+
+- Good: [reason.]
+- Bad: [reason.]
+
+### [Option B]
+
+- Good: [reason.]
+- Bad: [reason.]
+
+## Decision Outcome
+
+Chosen option: [option], because [reason and evidence].
+
+### Positive Consequences
+
+- [Benefit.]
+
+### Negative Consequences
+
+- [Cost or follow-up work.]
+
+## References
+
+- [Related decision, issue, or evidence.]
+
+## Appendix
+
+### Appendix A
+
+Useful background information.
+
+### Appendix B
+
+More useful background information.
+`;
+var init_architecture_decision_record = () => {};
+
+// templates/product-requirements-document.md
+var product_requirements_document_default = `# [User outcome or product change]
+
+> @agent: make this closer to the PRD under prd dir!
+
+- **Status:** draft
+- **Owner:** [person or team]
+- **Date:** [YYYY-MM-DD]
+
+## Summary
+
+[What changes for users, and why?]
+
+## Problem and Evidence
+
+[Who has the problem? Give observed evidence or mark assumptions.]
+
+## Users and Use Cases
+
+- [User]: [job to be done and context.]
+
+## Goals
+
+- [User outcome to achieve.]
+
+## Non-Goals
+
+- [Related need that this work does not address.]
+
+## Proposed Experience
+
+[Describe the user journey, inputs, outputs, errors, and recovery.]
+
+## Requirements
+
+### [Capability]
+
+[Required user-facing behavior, edge cases, and constraints.]
+
+**Acceptance:** [Observable way to check the requirement.]
+
+## Success Measures
+
+[Signal, baseline or assumption, target, and when/how it will be measured.]
+
+## Risks and Dependencies
+
+- [Risk or dependency]: [mitigation or owner.]
+
+## Open Questions
+
+- [Question and decision owner.]
+
+## Rollout
+
+[Release, feedback, migration, and rollback plan, if needed.]
+`;
+var init_product_requirements_document = () => {};
+
+// templates/code-review.md
+var code_review_default = `# Review: [change or pull request]
+
+- **Revision:** [commit or diff]
+- **Intent:** [stated objective and source]
+- **Reviewer:** [name]
+
+## Intent Delivery
+
+[Does the change actually deliver the intended behavior? What is missing or outside scope?]
+
+## Readability
+
+[Can a new reader follow the flow, names, and error paths? Is code readable for and understandable for an average mide-level developer at a glance?]
+
+## Semantic Organization
+
+[Are responsibilities, boundaries, and public APIs arranged by meaning? Are modules semantically meaningful? Is code in applications and libraries well sliced by concerns?]
+
+## Maintainability
+
+[Is the code DRY? Is the code over-engineered beyond required scope? Are well trusted / industry-standard libraries and frameworks used for standard tasks? Are domain specific conventions approprate for the codebase being followed? Is basic linting, formatting and static analysis hygiene present?]
+
+## Reliability/Testing
+
+[Behavior, edge cases, test coverage, and evidence from executed checks. Adhere to repo testing standards if specified in AGENTS.md or docs. Otherwise, generally prioritize e2e coverage and test readability and organization.]
+
+## Performance
+
+[Cost, allocations, I/O, scaling, and measured or expected impact. State SKIPPED with reasons for non-perf bugfixes, minor refactors, and non-performance critical applications.]
+
+## Security
+
+[Evaluate authentication and autorization, permissions, secrets, dependencies, input validation, proper error handling, and trust boundaries. State SKIPPED if skipped with reason, for example for chores, simple scripting, pure cosmetic UI work, documentation, etc.]
+
+## Change Requests
+
+Track actionable inline requests with one entry per request. End each generated request and response with its own model attribution quote; preserve human text unchanged.
+
+### [file:line \u2014 request]
+
+- **Status:** [open/in progress/resolved]
+- **Request:** [verbatim request or concise generated finding]
+
+> Generated via [actual model name, only for a generated request]
+
+- **Response:** [resolution, evidence, or reason this remains open]
+
+> Generated via [actual model name, only for a generated response]
+
+## Findings
+
+| Severity                 | Location    | Evidence and impact        | Required change or question |
+| ------------------------ | ----------- | -------------------------- | --------------------------- |
+| [blocking/consider/note] | [file:line] | [reproducible observation] | [concrete action]           |
+
+## Overall Assessment
+
+[Recommendation and reasons; distinguish findings from preferences.]
+
+## Verification and Limits
+
+- **Checks run:** [command and result.]
+- **Not verified:** [environment, path, or behavior not checked.]
+`;
+var init_code_review = () => {};
+
+// templates/planning-intent.md
+var planning_intent_default = `# Intent: [short name]
+
+## Objective
+
+[What do you want to add/change?]
+
+## Requirements/Instructions
+
+[Requirements deliverable must meet. Alternately, imperative instructions which must be followed.]
+
+## Constraints
+
+[Implementation requirements (particularly non-functional ones), important invariants, behavioral must-haves or limits. Optional.]
+
+## Open Questions
+
+[Decisions you want help making. Optional.]
+`;
+var init_planning_intent = () => {};
+
+// templates/ui-component-architecture.md
+var ui_component_architecture_default = `# [UI component name]
+
+## Overview
+
+[What does this component do, who uses it, and where does it appear?]
+
+## Design
+
+### Layout
+
+\`\`\`text
++---------------------------------------+
+| [Title]                       [Action] |
+|----------------------------------------|
+| [Main content]                         |
+| [Status or feedback]                   |
++---------------------------------------+
+\`\`\`
+
+[Replace the sketch with the actual component layout, including responsive changes. Could also be an image or inline svg.]
+
+### Behavior
+
+- **Default:** [Initial content and action.]
+- **Interaction:** [Inputs, focus changes, and responses.]
+- **Loading, empty, and error:** [What users see and how they recover.]
+- **Accessibility:** [Keyboard path, semantics, labels, and announcements.]
+
+## Implementation
+
+### Public API
+
+[Props, events, slots, and example usage.]
+
+### State and Data Flow
+
+[Who owns state? What is derived? What is persisted?]
+
+### Styling and Responsiveness
+
+[Tokens, breakpoints, layout constraints, loading behavior, interaction design, etc. Optional. Often theme controlled.]
+
+### Maintainer Notes
+
+[Non-obvious invariants, testing strategy, performance concerns, and known limits.]
+`;
+var init_ui_component_architecture = () => {};
+
+// templates/pull-request-description.md
+var pull_request_description_default = `## Intent
+
+{{intent}}
+
+## Changes
+
+{{changes}}
+
+## Validation
+
+{{validation}}
+
+## Further Work
+
+{{further_work}}
+
+## References
+
+- Issue: {{issue_url}}
+`;
+var init_pull_request_description = () => {};
+
+// templates/examples/plan-feature.md
+var plan_feature_default = `# Invite teammates to a project
+
+- **Status:** draft
+- **Branch:** feature/project-invites
+- **Issue:** EX-12
+
+## Intent
+
+Project owners need to invite teammates without sharing credentials. Recipients should know which project they are joining before accepting.
+
+## Requirements
+
+- An owner can send an invite to a valid email address and see its pending state.
+- Only the intended recipient can accept; expired or used invites fail without changing membership.
+- Bulk invitations and organization-level roles are out of scope.
+
+## Design
+
+### Big Ideas
+
+Store a single-use invitation tied to project, email, and expiry. Acceptance adds membership in the same transaction that consumes the invitation. Queue delivery after saving the invite so a temporary email failure cannot lose it.
+
+### Interfaces
+
+\`POST /projects/:id/invitations\` creates a pending invite; \`POST /invitations/:token/accept\` returns membership or a safe expired/used error. \`src/invitations/store.ts\` owns persistence; \`src/invitations/service.ts\` owns eligibility, expiry, and token consumption; \`src/http/invitations.ts\` maps results to responses.
+
+### Consequences
+
+Email delivery can fail after persistence, so queue retries and show a pending invitation. Rate-limit creation to avoid abuse. Resend and cancellation are deferred.
+
+## Phases
+
+### Phase 1: Persist and consume invitations
+
+- [ ] Add a unique token hash, recipient email, project ID, expiry, and consumed timestamp to invitation storage in \`src/invitations/store.ts\`; never log raw tokens.
+- [ ] Implement transactional membership creation and token consumption in \`src/invitations/service.ts\`; reject expired, used, or wrong-recipient tokens without a membership change.
+- [ ] Add boundary, repeat-use, and rollback tests in \`src/invitations/service.test.ts\`.
+- [ ] Validation
+  - [ ] Run invitation unit tests, lint, and format checks.
+  - [ ] Commit this phase and confirm CI is green.
+
+### Phase 2: Expose and deliver invitations
+
+- [ ] Add owner creation and recipient acceptance handlers in \`src/http/invitations.ts\` with safe error responses and creation rate limits.
+- [ ] Queue delivery after persistence, retry transient mail failures, and expose the pending state to owners.
+- [ ] Add endpoint integration tests for authorization, expiry, used tokens, and delivery failures in \`src/http/invitations.spec.ts\`.
+- [ ] Validation
+  - [ ] Run unit and integration tests, lint, and format checks.
+  - [ ] Commit this phase and confirm CI is green.
+
+## References
+
+- EX-12 \u2014 sample product request.
+`;
+var init_plan_feature = () => {};
+
+// templates/examples/plan-migration.md
+var plan_migration_default = `# Move activity history to a new store
+
+- **Status:** draft
+- **Branch:** feature/activity-migration
+- **Issue:** EX-27
+
+## Intent
+
+Readers should retain access to historical activity while the team changes storage engines without downtime.
+
+## Requirements
+
+- Old and new records produce the same user-visible history, order, and cursors.
+- Rollback can restore the prior reader without losing activity written during migration.
+- No reader switches until backfill and comparison pass.
+
+## Design
+
+### Big Ideas
+
+Write to both stores temporarily, backfill older records with stable IDs, compare counts and ordering, then switch readers behind a reversible flag. Keep the legacy reader authoritative until the new store is verified.
+
+### Infrastructure Changes
+
+Provision the new activity store and credentials before dual writes. Retain the legacy store and its capacity until the rollback window closes; monitor write failures for each store separately.
+
+### Interfaces
+
+\`listActivity(projectId, cursor)\` preserves ordering and cursor behavior during cutover. \`src/activity/writer.ts\` owns dual writes, \`src/activity/backfill.ts\` copies historical records, and \`src/activity/reader.ts\` selects the store behind the feature flag.
+
+### Consequences
+
+Dual writes increase latency and create a risk of partial failure. Record discrepancies and retry failed writes instead of hiding them. Removing the legacy store is outside this plan.
+
+## Phases
+
+### Phase 1: Provision and dual-write
+
+- [ ] Provision the new store and credentials; add write-failure metrics for both stores.
+- [ ] Make \`src/activity/writer.ts\` write idempotently to both stores with stable activity IDs while retaining the legacy reader.
+- [ ] Test partial-write retries and duplicate events in \`src/activity/writer.test.ts\`.
+- [ ] Validation
+  - [ ] Run writer tests, lint, and format checks; confirm write-failure metrics are visible.
+  - [ ] Commit this phase and confirm CI is green.
+
+### Phase 2: Backfill and compare
+
+- [ ] Add resumable, idempotent batches in \`src/activity/backfill.ts\` without replacing newer dual-written records.
+- [ ] Compare record IDs, counts, and ordering per project; report mismatches before any reader switch.
+- [ ] Add backfill restart and parity tests in \`src/activity/backfill.test.ts\`.
+- [ ] Validation
+  - [ ] Run backfill and writer tests, lint, and format checks; review mismatch reports.
+  - [ ] Commit this phase and confirm CI is green.
+
+### Phase 3: Switch reads with rollback
+
+- [ ] Route \`listActivity(projectId, cursor)\` through a reversible flag in \`src/activity/reader.ts\` and preserve cursor compatibility.
+- [ ] Test new-store reads, cursor boundaries, and rollback to the legacy reader in \`src/activity/reader.spec.ts\`.
+- [ ] Keep dual writes and monitor parity through the rollback window.
+- [ ] Validation
+  - [ ] Run unit and integration tests, lint, and format checks; verify flag rollback.
+  - [ ] Commit this phase and confirm CI is green.
+
+## References
+
+- EX-27 \u2014 sample migration request.
+`;
+var init_plan_migration = () => {};
+
+// templates/examples/design-service.md
+var design_service_default = `# Notification service \u2014 software architecture
+
+## Overview
+
+The service delivers email notifications for account events. It consumes messages from the application queue; it does not decide who should receive a message or block account requests on email delivery.
+
+## Requirement
+
+### Functional
+
+- FR1: Consume and validate account events with an ID, type, recipient, and timestamp.
+- FR2: Deduplicate deliveries, send email, and record each attempt and its outcome.
+- FR3: Retry transient provider failures and report permanent rejections.
+
+### Non-Functional
+
+- NFR1: Queue redelivery must not send the same event twice; retain a durable event ID for deduplication.
+- NFR2: Provider credentials must stay outside event payloads and the account service.
+- NFR3: A burst of events must not delay account requests; alert when the queue grows.
+
+## Design
+
+### Components and Responsibilities
+
+\`\`\`mermaid
+flowchart LR
+    Account[Account service] -->|Account event| Queue[(Durable queue)]
+    Queue --> Consumer[Notification consumer]
+    Consumer --> Sender[Email sender]
+    Sender --> Provider[Email API]
+    Consumer --> Store[(Attempt store)]
+\`\`\`
+
+- The account service publishes events and knows only the event contract.
+- The durable queue isolates delivery from account requests and retries transient failures.
+- The consumer validates and deduplicates events; the sender formats and submits mail to the provider.
+- The attempt store records event IDs, delivery outcomes, and retry attempts.
+
+### Data and Control Flow
+
+An account event enters the queue. The consumer validates it and checks the attempt store for its ID before the sender calls the provider. The consumer records the result; a transient failure is retried, while a permanent rejection is reported. Sending synchronously would avoid the queue but could delay account requests whenever the provider is slow.
+
+### Interfaces and Contracts
+
+\`AccountEvent\` contains \`id\`, \`type\`, \`recipient\`, and \`timestamp\`. \`handle(event)\` consumes the event, \`send(message)\` calls the provider, and \`record(attempt)\` persists its result. The event ID is the deduplication key; provider credentials never enter the payload.
+
+## Implementation
+
+### Consumer and storage
+
+The notification service owns its consumer and attempt store; the account service imports only the event contract. Persist the deduplication key with the delivery outcome so queue redelivery is safe. Integration tests simulate duplicate events and provider timeouts.
+
+### Delivery operations
+
+Keep provider credentials in the notification service. Alert on a growing queue and repeated provider failures; disable sending and drain pending work if credentials are compromised. Load tests cover bursts without slowing the account service.
+
+## References
+
+- EX-34 \u2014 example notification requirement.
+`;
+var init_design_service = () => {};
+
+// templates/examples/adr-storage.md
+var adr_storage_default = `# Use object storage for user exports
+
+- **Status:** accepted
+- **Deciders:** Platform team
+- **Date:** 2026-01-14
+
+## Context and Problem Statement
+
+Exports may exceed the response size limit of the application server. Where should completed exports live until users download them?
+
+## Decision Drivers
+
+- Exports must expire after seven days.
+- The application server should not retain large files on local disk.
+
+## Considered Options
+
+### Object storage
+
+- Good: Lifecycle rules remove expired exports without an application job.
+- Bad: Requires bucket credentials and signed download URLs.
+
+### Database
+
+- Good: Existing backup process covers exports.
+- Bad: Large blobs make backups slow and expensive.
+
+## Decision Outcome
+
+Chosen option: object storage, because it provides expiry policies and direct downloads without loading large files into application memory.
+
+### Positive Consequences
+
+- Large exports do not occupy application disks.
+
+### Negative Consequences
+
+- Download authorization requires short-lived signed URLs.
+
+## References
+
+- EX-41 \u2014 example export requirement.
+
+## Appendix
+
+### Appendix A
+
+A seven-day lifecycle rule deletes exports even if a user never downloads them. Issue signed URLs only after checking that the requester owns the export.
+
+### Appendix B
+
+An export job records the object key and expiry time so the download endpoint can reject expired requests before generating a URL.
+`;
+var init_adr_storage = () => {};
+
+// templates/examples/prd-onboarding.md
+var prd_onboarding_default = `# Help new members finish project onboarding
+
+- **Status:** draft
+- **Owner:** Product team
+- **Date:** 2026-01-14
+
+## Summary
+
+Give invited members a short checklist so they can find their project and complete their first task.
+
+## Problem and Evidence
+
+New members frequently ask where to start after accepting an invite. This is a product assumption until interviews confirm the pattern.
+
+## Users and Use Cases
+
+- New project member: find the project, read its purpose, and finish a first task.
+
+## Goals
+
+- Members can find their first task without contacting an administrator.
+
+## Non-Goals
+
+- Training on every product feature.
+
+## Proposed Experience
+
+After joining, a member sees a three-step checklist with links to the project overview and an assigned starter task. Dismissal is reversible from the help menu.
+
+## Requirements
+
+### Visible next step
+
+Show one task assigned to the member, or a clear empty state when none exists.
+
+**Acceptance:** A member with no assigned task sees an actionable empty state, not a blank panel.
+
+## Success Measures
+
+Measure the share of invited members who open a project and complete a task within seven days; record a baseline before launch.
+
+## Risks and Dependencies
+
+- Task assignment data may be delayed: refresh the checklist when assignment changes.
+
+## Open Questions
+
+- Should dismissed checklists reappear for new projects? Product owner to decide.
+
+## Rollout
+
+Enable for a small cohort, compare completion and feedback, then expand or disable.
+`;
+var init_prd_onboarding = () => {};
+
+// templates/examples/review-change.md
+var review_change_default = `# Review: invitation expiry change
+
+- **Revision:** example-change-17
+- **Intent:** Reject expired invitations without creating membership.
+- **Reviewer:** Example reviewer
+
+## Intent Delivery
+
+The acceptance path checks expiry before membership creation. The resend path was not part of this change.
+
+## Readability
+
+Function names describe outcomes, and the request path is understandable without tracing helpers. Move the expiry guard before token decoding so a mid-level maintainer can see the rejection path at a glance.
+
+## Semantic Organization
+
+Invitation policy belongs in the invitation service, not the HTTP handler. The handler should own transport errors; the service should own token and membership rules.
+
+## Maintainability
+
+The shared expiry helper avoids duplicate rules in request and background paths. No new library or abstraction is needed for this change; formatting and static analysis should remain clean.
+
+## Reliability/Testing
+
+Tests cover expiry at the boundary and a used token. A clock-skew case is missing; add a readable test that checks the server clock source and confirms no membership is created on rejection.
+
+## Performance
+
+One lookup occurs per acceptance; no new unbounded loop is present.
+
+## Security
+
+The response does not reveal whether an address has an account. The recipient is authorized before the token is consumed, tokens are treated as opaque values, and failed acceptance does not create membership.
+
+## Findings
+
+| Severity | Location                | Evidence and impact                               | Required change or question                           |
+| -------- | ----------------------- | ------------------------------------------------- | ----------------------------------------------------- |
+| consider | \`src/invitations.ts:52\` | Clock skew near expiry may reject valid requests. | Add a boundary test and document server clock source. |
+
+## Overall Assessment
+
+No blocking issue found in the reviewed path; address the boundary test before release.
+
+## Verification and Limits
+
+- **Checks run:** \`bun test src/invitations.test.ts\` \u2014 passed in this example.
+- **Not verified:** Real email delivery and production clock behavior.
+`;
+var init_review_change = () => {};
+
+// templates/examples/intent-request.md
+var intent_request_default = `# Intent: Faster project search
+
+## Objective
+
+People with many projects need to find a project by name without scrolling through the full list. Support has received requests about this, but we do not yet have a measured search-time baseline.
+
+## Requirements/Instructions
+
+- Let users search accessible projects by name while keeping the existing project list available.
+- Do not add search for tasks or users.
+
+## Constraints
+
+Search must work from the keyboard and must not reveal projects a user cannot access.
+
+## Open Questions
+
+Should results include archived projects by default?
+`;
+var init_intent_request = () => {};
+
+// templates/examples/component-dialog.md
+var component_dialog_default = `# ConfirmDeleteDialog
+
+## Overview
+
+A modal asks for confirmation before a destructive action. It appears only when the user chooses Delete.
+
+## Design
+
+### Layout
+
+\`\`\`text
++------------------------------------------+
+| Delete project?                       [X]  |
+|------------------------------------------|
+| This removes the project and its tasks.   |
+|                    [Cancel] [Delete]      |
++------------------------------------------+
+\`\`\`
+
+The buttons stack on narrow screens while preserving Cancel before Delete in keyboard order.
+
+### Behavior
+
+- **Default:** Focus the title or Cancel button; explain the affected project.
+- **Interaction:** Cancel and Escape close without deleting; Delete submits once.
+- **Loading, empty, and error:** Disable repeat submit; report server failure and allow retry.
+- **Accessibility:** Use a labelled modal, trap focus while open, and restore focus to Delete trigger on close.
+
+## Implementation
+
+### Public API
+
+\`ConfirmDeleteDialog({ projectName, open, onCancel, onConfirm })\` receives the project name and emits confirmation only once per open cycle.
+
+### State and Data Flow
+
+Parent owns \`open\` and performs deletion; the dialog owns only pending/error display.
+
+### Styling and Responsiveness
+
+Use shared spacing tokens and a 28rem maximum width; stack actions below 22rem.
+
+### Maintainer Notes
+
+Use the design system modal primitive for focus management. Test Escape, focus restoration, double-submit prevention, and the server error path.
+`;
+var init_component_dialog = () => {};
+
+// templates/examples/component-navigation.md
+var component_navigation_default = `# ProjectNavigation
+
+## Overview
+
+A navigation rail lets members switch between project sections. The active section is always identifiable without color alone.
+
+## Design
+
+### Layout
+
+\`\`\`text
++---------------------+
+| Project name        |
+|---------------------|
+| > Overview          |
+|   Tasks             |
+|   Activity          |
+|---------------------|
+|   Settings          |
++---------------------+
+\`\`\`
+
+At narrow widths, the rail becomes a labelled navigation menu.
+
+### Behavior
+
+- **Default:** Highlight the route that matches the current page.
+- **Interaction:** Arrow keys move focus within the menu; Enter activates a route.
+- **Loading, empty, and error:** Render available routes while project metadata loads; show a safe fallback label on failure.
+- **Accessibility:** Use a \`nav\` landmark, accessible item names, and \`aria-current="page"\` for the active link.
+
+## Implementation
+
+### Public API
+
+\`ProjectNavigation({ project, currentRoute, routes })\` receives visible routes already filtered for permissions.
+
+### State and Data Flow
+
+The router owns navigation state; the component derives the active item from \`currentRoute\`.
+
+### Styling and Responsiveness
+
+Use existing navigation tokens; collapse below the compact breakpoint.
+
+### Maintainer Notes
+
+Route links come from the application router; do not duplicate permission checks in display code. Test route changes, keyboard operation, permission-filtered items, and compact layout.
+`;
+var init_component_navigation = () => {};
+
+// templates/examples/pull-request-feature.md
+var pull_request_feature_default = `## Intent
+
+Let project owners invite teammates without sharing credentials.
+
+## Changes
+
+- Added a single-use invitation token with an expiry.
+- Added an acceptance endpoint that creates membership and consumes the token atomically.
+- Added owner and recipient error handling.
+
+## Validation
+
+- \`bun test src/invitations.test.ts\` \u2014 passed in this example.
+- Manual check: expired and already-used tokens did not grant membership.
+
+## Further Work
+
+Add invitation resend and cancellation in a separate change.
+
+## References
+
+- Issue: EX-12 (example)
+`;
+var init_pull_request_feature = () => {};
+
+// src/templates/source.ts
+var catalog, contents, embeddedSource;
+var init_source = __esm(() => {
+  init_spec_driven_plan();
+  init_software_architecture_design();
+  init_architecture_decision_record();
+  init_product_requirements_document();
+  init_code_review();
+  init_planning_intent();
+  init_ui_component_architecture();
+  init_pull_request_description();
+  init_plan_feature();
+  init_plan_migration();
+  init_design_service();
+  init_adr_storage();
+  init_prd_onboarding();
+  init_review_change();
+  init_intent_request();
+  init_component_dialog();
+  init_component_navigation();
+  init_pull_request_feature();
+  catalog = [
+    { name: "spec-driven-plan", description: "Spec-driven implementation plan" },
+    { name: "software-architecture-design", description: "Software architecture design" },
+    { name: "architecture-decision-record", description: "Architecture decision record" },
+    { name: "product-requirements-document", description: "Product requirements document" },
+    { name: "code-review", description: "Thorough code review" },
+    { name: "planning-intent", description: "Planning intent for a user to fill in" },
+    { name: "ui-component-architecture", description: "UI component design and implementation" },
+    { name: "pull-request-description", description: "Draft pull request description" }
+  ];
+  contents = {
+    "spec-driven-plan.md": spec_driven_plan_default,
+    "software-architecture-design.md": software_architecture_design_default,
+    "architecture-decision-record.md": architecture_decision_record_default,
+    "product-requirements-document.md": product_requirements_document_default,
+    "code-review.md": code_review_default,
+    "planning-intent.md": planning_intent_default,
+    "ui-component-architecture.md": ui_component_architecture_default,
+    "pull-request-description.md": pull_request_description_default,
+    "examples/plan-feature.md": plan_feature_default,
+    "examples/plan-migration.md": plan_migration_default,
+    "examples/design-service.md": design_service_default,
+    "examples/adr-storage.md": adr_storage_default,
+    "examples/prd-onboarding.md": prd_onboarding_default,
+    "examples/review-change.md": review_change_default,
+    "examples/intent-request.md": intent_request_default,
+    "examples/component-dialog.md": component_dialog_default,
+    "examples/component-navigation.md": component_navigation_default,
+    "examples/pull-request-feature.md": pull_request_feature_default
+  };
+  embeddedSource = {
+    catalog,
+    assets: Object.keys(contents),
+    async read(asset) {
+      const content = contents[asset];
+      if (content === undefined)
+        throw new Error(`Missing embedded template asset: ${asset}`);
+      return content;
+    }
+  };
+});
+
+// src/templates/service.ts
+var exports_service = {};
+__export(exports_service, {
+  TemplateService: () => TemplateService
+});
+import { constants as constants2 } from "fs";
+import { lstat as lstat7, open as open3, rm as rm3 } from "fs/promises";
+import { isAbsolute as isAbsolute7, join as join6 } from "path";
+
+class TemplateService {
+  home;
+  source;
+  constructor(options = {}) {
+    this.home = resolveHomeDirectory(options.home);
+    this.source = options.source ?? embeddedSource;
+  }
+  async listTemplates() {
+    await this.installMissing();
+    return [...this.source.catalog];
+  }
+  async scaffoldFromTemplate(name, cwd, path, filename) {
+    if (!this.source.catalog.some((item) => item.name === name)) {
+      throw new UnknownTemplateError(`Unknown template: ${name}`);
+    }
+    if (!path.trim() || isAbsolute7(path)) {
+      throw new TemplateError("path must be a non-empty relative directory inside cwd");
+    }
+    if (!filename.trim() || filename === "." || filename === ".." || /[/\\\0]/.test(filename)) {
+      throw new TemplateError("filename must be a single non-empty file name");
+    }
+    await this.installMissing();
+    const installed = await resolvePath(this.home, join6(".difflab", "templates", `${name}.md`));
+    const contents = await readMarkdown(installed);
+    const destination = path.startsWith(".difflab/") ? await this.projectDestination(cwd, path.slice(".difflab/".length), filename) : await ensurePathDirsExist(join6(path, filename), cwd);
+    try {
+      await createExclusive(destination, contents);
+    } catch (error) {
+      if (hasErrorCode(error, "EEXIST")) {
+        throw new TemplateDestinationExistsError(`Destination already exists: ${destination}`, {
+          cause: error
+        });
+      }
+      throw error;
+    }
+    return destination;
+  }
+  async projectDestination(cwd, path, filename) {
+    if (!isAbsolute7(cwd))
+      throw new TemplateError("cwd must be an absolute path");
+    const git = discoverGitRepository(cwd);
+    const config = await readRepoConfig(git.root);
+    if (!config)
+      throw new TemplateError(`Initialize this repository with difflab init: ${git.root}`);
+    const target = join6(userPaths(this.home).projects, config.project.id, repositorySlug(canonicalGitUrl(git.originUrl)));
+    await checkRepoStore(git.root, target);
+    return ensurePathDirsExist(join6(path, filename), target);
+  }
+  async installMissing() {
+    for (const asset of this.source.assets) {
+      const relative = join6(".difflab", "templates", asset);
+      const destination = await ensurePathDirsExist(relative, this.home);
+      try {
+        if ((await lstat7(destination)).isSymbolicLink()) {
+          throw new TemplateSourceError(`Installed template asset is a symlink: ${destination}`);
+        }
+        await readMarkdown(destination);
+      } catch (error) {
+        if (!hasErrorCode(error, "ENOENT"))
+          throw error;
+        const content = await readSource(this.source, asset);
+        try {
+          await createExclusive(destination, content);
+        } catch (writeError) {
+          if (!hasErrorCode(writeError, "EEXIST"))
+            throw writeError;
+          await readMarkdown(destination);
+        }
+      }
+    }
+  }
+}
+async function readSource(source, asset) {
+  try {
+    const content = await source.read(asset);
+    if (!content.trim())
+      throw new TemplateSourceError(`Template is empty: ${asset}`);
+    return content;
+  } catch (error) {
+    if (error instanceof TemplateSourceError)
+      throw error;
+    throw new TemplateSourceError(`Cannot read template asset: ${asset}`, { cause: error });
+  }
+}
+async function readMarkdown(path) {
+  let handle;
+  try {
+    handle = await open3(path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
+    if (!(await handle.stat()).isFile())
+      throw new TemplateSourceError(`Template is not a file: ${path}`);
+    const content = await handle.readFile("utf8");
+    if (!content.trim())
+      throw new TemplateSourceError(`Template is empty: ${path}`);
+    return content;
+  } catch (error) {
+    if (error instanceof TemplateSourceError)
+      throw error;
+    throw new TemplateSourceError(`Cannot read template asset: ${path}`, { cause: error });
+  } finally {
+    await handle?.close();
+  }
+}
+async function createExclusive(path, content) {
+  const handle = await open3(path, constants2.O_WRONLY | constants2.O_CREAT | constants2.O_EXCL | constants2.O_NOFOLLOW, 384);
+  try {
+    await handle.writeFile(content, "utf8");
+  } catch (error) {
+    await handle.close();
+    await rm3(path, { force: true });
+    throw error;
+  } finally {
+    await handle.close();
+  }
+}
+var TemplateError, UnknownTemplateError, TemplateSourceError, TemplateDestinationExistsError;
+var init_service = __esm(() => {
+  init_fsx();
+  init_osx();
+  init_pathx();
+  init_gitx2();
+  init_config();
+  init_repo_store();
+  init_user_store();
+  init_source();
+  TemplateError = class TemplateError extends Error {
+  };
+  UnknownTemplateError = class UnknownTemplateError extends TemplateError {
+  };
+  TemplateSourceError = class TemplateSourceError extends TemplateError {
+  };
+  TemplateDestinationExistsError = class TemplateDestinationExistsError extends TemplateError {
+  };
+});
+
+// src/templates/tools.ts
+var templateInfo, templateListOutput, scaffoldOutput, templateTools;
+var init_tools4 = __esm(() => {
+  init_zod();
+  init_zodx();
+  init_service();
+  templateInfo = object({
+    name: string2(),
+    description: string2()
+  });
+  templateListOutput = object({ result: array(templateInfo) });
+  scaffoldOutput = object({
+    result: object({ name: string2(), path: string2() })
+  });
+  templateTools = [
+    defineTool("template_list", {
+      description: "List eight document templates; install any missing defaults and examples in the user templates directory without overwriting local edits.",
+      inputSchema: strictObject({}),
+      outputSchema: templateListOutput,
+      annotations: { openWorldHint: false }
+    }, async () => new TemplateService().listTemplates(), { toStructuredContent: (result) => ({ result }) }),
+    defineTool("scaffold", {
+      description: "Copy a named installed template into a new file under absolute cwd in relative directory path with the supplied filename. Create missing directories; never overwrite an existing file.",
+      inputSchema: strictObject({
+        name: string2().describe("Hyphenated template name from template_list, such as spec-driven-plan"),
+        cwd: absolutePath.describe("Absolute path to an existing destination base directory"),
+        path: relativePath.describe("Relative directory inside cwd; use . for cwd itself; missing directories are created"),
+        filename: fileName.describe("Name of the new file inside path, such as my-plan.md; no separators")
+      }),
+      outputSchema: scaffoldOutput,
+      annotations: { openWorldHint: false }
+    }, async ({ name, cwd, path, filename }) => ({
+      name,
+      path: await new TemplateService().scaffoldFromTemplate(name, cwd, path, filename)
+    }), { toStructuredContent: (result) => ({ result }) })
+  ];
+});
+
 // src/mcp/server.ts
 async function serveMcp(version = "0.1.0") {
   const server = new McpServer({ name: "difflab", version });
-  for (const tool of [...todoTools, ...projectTools]) {
+  for (const tool of [...todoTools, ...projectTools, ...templateTools, ...logTools]) {
     server.registerTool(tool.name, tool.config, tool.callback);
   }
   await server.connect(new StdioServerTransport);
@@ -48206,6 +49473,8 @@ var init_server3 = __esm(() => {
   init_stdio2();
   init_tools();
   init_tools2();
+  init_tools3();
+  init_tools4();
 });
 
 // src/extensions/processx.ts
@@ -50529,12 +51798,25 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
     await Promise.resolve().then(() => init_mcp2());
     await setupMcpClients(client, write);
   });
+  const templates = program.command("templates").description("List and scaffold documents");
+  const service = async () => options.templateService ?? new (await Promise.resolve().then(() => (init_service(), exports_service))).TemplateService;
+  templates.command("list").description("List available document templates").action(async () => {
+    const templatesService = await service();
+    for (const template of await templatesService.listTemplates()) {
+      write(`${template.name} \u2014 ${template.description}`);
+    }
+  });
+  templates.command("scaffold <name> <path> <filename>").description("Copy a template into a new document inside a directory; never overwrite").option("--cwd <directory>", "absolute base directory for the relative destination path").action(async (name, path, filename, options) => {
+    const templatesService = await service();
+    const destination = await templatesService.scaffoldFromTemplate(name, options.cwd ?? process.cwd(), path, filename);
+    write(destination);
+  });
   return program;
 }
 
 // src/index.ts
 init_errors3();
-var version2 = "0.3.0";
+var version2 = "0.5.0";
 try {
   await createProgram(console.log, version2).parseAsync(process.argv);
 } catch (error) {