@mnemahq/cli 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "htm": "^3.1.1",
     "ink": "^6.8.0",
     "react": "^19.2.7",
-    "@mnemahq/sdk": "0.4.1"
+    "@mnemahq/sdk": "0.5.0"
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

package/src/catalogue.mjs

@@ -41,6 +41,8 @@ export const GROUPS = [
       { name: 'doctor', blurb: 'Diagnose install, hooks, auth, connectivity' },
       { name: 'sessions', blurb: 'List recent sessions for this repo (local + server)' },
       { name: 'sweep', blurb: 'Backfill past local sessions (opt-in)' },
+      { name: 'codex-sweep', blurb: 'Backfill OpenAI Codex CLI sessions from ~/.codex rollouts' },
+      { name: 'gemini-sweep', blurb: 'Backfill Google Gemini CLI sessions from ~/.gemini chats' },
       {
         name: 'binding', blurb: 'Task-binding miss rate, measured locally',
         detail: 'Reads the PreToolUse counters. Reports NO DATA as no data — "0% miss rate" and "the hook never ran" are the same number and mean opposite things.',
@@ -48,6 +50,7 @@ export const GROUPS = [
         examples: ['mnema binding', 'mnema binding --limit 30'],
       },
       { name: 'pull', blurb: 'Export repo-bound docs into .mnema/context (server-is-truth)' },
+      { name: 'prd init', blurb: 'Write a docs/prd.md draft from what Mnema observed (never commits)' },
     ],
   },
   {

package/src/cli.mjs

@@ -10,7 +10,12 @@
  *   mnema uninstall  cleanly reverse everything
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { applyWrites, chooseProject, describeResult, planWrites } from './prd.mjs';
+import { parseCodexRollout } from './codex-rollout.mjs';
+import { parseGeminiChat } from './gemini-chat.mjs';
 import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
 import { makeClient, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
 import {
@@ -71,7 +76,7 @@ const VERSION = JSON.parse(
  * flag followed by an argument" from "a flag and its value" — the parser has to
  * be told which is which, so it is.
  */
-const VALUE_FLAGS = new Set(['workspace', 'origin', 'limit', 'status', 'project', 'repo', 'budget']);
+const VALUE_FLAGS = new Set(['workspace', 'origin', 'limit', 'status', 'project', 'repo', 'budget', 'days']);
 
 export function parseFlags(argv) {
   const flags = {}; const rest = [];
@@ -355,6 +360,113 @@ function cmdSweep() {
   }
 }
 
+// ── codex-sweep ────────────────────────────────────────────────────────────────
+// Backfill OpenAI Codex CLI sessions: read the local rollout JSONL traces under
+// CODEX_HOME/sessions, parse each into a normalised session (see codex-rollout.mjs),
+// and POST to /api/hooks/codex. Cost is computed server-side from tokens × pricing.
+
+function codexHome() {
+  return process.env.CODEX_HOME || join(homedir(), '.codex');
+}
+
+function findRollouts(dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) findRollouts(p, out);
+    else if (e.isFile() && /^rollout-.*\.jsonl$/.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+async function cmdCodexSweep(flags) {
+  const { origin, workspaceId } = resolveContext(flags);
+  if (!workspaceId) { console.error(c.red('Not linked — run `mnema init` first.')); process.exit(1); }
+  const token = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
+  if (!token) { console.error(c.red('No hook token stored. Run `mnema init` first.')); process.exit(1); }
+
+  const sessionsDir = join(codexHome(), 'sessions');
+  const files = findRollouts(sessionsDir);
+  if (!files.length) {
+    console.log(c.dim(`No Codex rollouts found under ${sessionsDir}`));
+    console.log(c.dim('  (set CODEX_HOME if your Codex data lives elsewhere.)'));
+    return;
+  }
+
+  const limit = Number(flags.limit) || files.length;
+  const developerId = defaultDeveloperId();
+  const chosen = files.slice(-limit); // newest by path (…/YYYY/MM/DD/rollout-<ISO>-…)
+  let sent = 0, skipped = 0;
+  process.stdout.write(`Sweeping ${chosen.length} Codex session(s)… `);
+  for (const file of chosen) {
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { skipped++; continue; }
+    let payload;
+    try { payload = parseCodexRollout(text, { developerId }); } catch { payload = null; }
+    if (!payload || !payload.session_id) { skipped++; continue; }
+    try {
+      const r = await apiFetch(origin, '/api/hooks/codex', { method: 'POST', token, body: payload });
+      if (r.ok || r.status === 202) sent++; else skipped++;
+    } catch { skipped++; }
+  }
+  console.log(c.green('done'));
+  console.log(c.green(`✓ ${sent} session(s) sent`) + (skipped ? c.dim(`, ${skipped} skipped`) : ''));
+  console.log(c.dim('  They appear under Sessions shortly, with cost computed from tokens × model pricing.'));
+}
+
+// ── gemini-sweep ─────────────────────────────────────────────────────────────
+// Backfill Google Gemini CLI sessions: read the chat recordings under
+// ~/.gemini/tmp/<project_hash>/chats/, parse each (see gemini-chat.mjs), and POST
+// to /api/hooks/gemini. Gemini CLI records real per-turn tokens, so cost computes.
+
+function geminiChatFiles(root, out = []) {
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const p = join(root, e.name);
+    // Recurse into tmp/<hash>/chats; collect the chat files (json/jsonl) within.
+    if (e.isDirectory()) geminiChatFiles(p, out);
+    else if (e.isFile() && /\.(jsonl?|json)$/i.test(e.name) && /chats?[\\/]/.test(p)) out.push(p);
+  }
+  return out;
+}
+
+async function cmdGeminiSweep(flags) {
+  const { origin, workspaceId } = resolveContext(flags);
+  if (!workspaceId) { console.error(c.red('Not linked — run `mnema init` first.')); process.exit(1); }
+  const token = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
+  if (!token) { console.error(c.red('No hook token stored. Run `mnema init` first.')); process.exit(1); }
+
+  const geminiHome = process.env.GEMINI_HOME || join(homedir(), '.gemini');
+  const files = geminiChatFiles(join(geminiHome, 'tmp'));
+  if (!files.length) {
+    console.log(c.dim(`No Gemini chats found under ${join(geminiHome, 'tmp')}`));
+    console.log(c.dim('  (set GEMINI_HOME if your Gemini CLI data lives elsewhere.)'));
+    return;
+  }
+
+  const limit = Number(flags.limit) || files.length;
+  const developerId = defaultDeveloperId();
+  const chosen = files.slice(-limit);
+  let sent = 0, skipped = 0;
+  process.stdout.write(`Sweeping ${chosen.length} Gemini session(s)… `);
+  for (const file of chosen) {
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { skipped++; continue; }
+    let payload;
+    try { payload = parseGeminiChat(text, { developerId }); } catch { payload = null; }
+    if (!payload || !payload.session_id) { skipped++; continue; }
+    try {
+      const r = await apiFetch(origin, '/api/hooks/gemini', { method: 'POST', token, body: payload });
+      if (r.ok || r.status === 202) sent++; else skipped++;
+    } catch { skipped++; }
+  }
+  console.log(c.green('done'));
+  console.log(c.green(`✓ ${sent} session(s) sent`) + (skipped ? c.dim(`, ${skipped} skipped`) : ''));
+  console.log(c.dim('  They appear under Sessions shortly, with cost computed from tokens × model pricing.'));
+}
+
 // ── search ───────────────────────────────────────────────────────────────────────
 
 async function cmdSearch(flags, rest) {
@@ -748,6 +860,66 @@ function cmdBinding(flags) {
   console.log(formatBindingStats(collectBindingStats(Number.isFinite(days) ? days : 7)));
 }
 
+
+/**
+ * `mnema prd init` — fetch the declaration draft and write it into this repo.
+ *
+ * ⛔ Writes into the WORKING TREE only. Never commits, never pushes. The
+ * declaration is authored by a person; that seam is the point.
+ */
+async function cmdPrd(flags, rest) {
+  const sub = (rest[0] || '').toLowerCase();
+  if (sub !== 'init') {
+    console.error(c.red(`Unknown prd subcommand: ${sub || '(none)'}`));
+    console.error(c.dim('Usage: mnema prd init [--project <name|id>] [--days 365] [--force]'));
+    process.exit(1);
+  }
+
+  const { root, origin, workspaceId } = resolveContext(flags);
+  if (!workspaceId) {
+    console.error(c.red('Not linked — run `mnema init` first.'));
+    process.exit(1);
+  }
+
+  let projects = [];
+  try {
+    projects = (await call({ origin, workspaceId }, (m) => m.projects.list({ limit: 100 }).all())) ?? [];
+  } catch (e) { renderError(e, { context: 'prd init', usedApiKey: hasApiKey(workspaceId) }); return; }
+
+  const choice = chooseProject(projects, flags.project);
+  if (!choice.ok) {
+    // ⚠️ Never guess. Print what there is to choose from — a wrong project would
+    // write another project's features into this repo's PRD.
+    const why = choice.reason === 'none-given'
+      ? 'Which project is this repo?'
+      : choice.reason === 'ambiguous' ? 'That matched more than one project.' : 'No project matched that.';
+    console.error(c.yellow(why));
+    console.error(c.dim('  mnema prd init --project <name or id>'));
+    console.error('');
+    for (const p of (choice.projects || []).slice(0, 25)) {
+      console.error(`  ${c.dim(p.id)}  ${p.name}`);
+    }
+    process.exit(1);
+  }
+
+  let draft;
+  try {
+    draft = await call({ origin, workspaceId }, (m) =>
+      m.prd.draft(choice.project.id, flags.days ? Number(flags.days) : undefined));
+  } catch (e) { renderError(e, { context: 'prd init', usedApiKey: hasApiKey(workspaceId) }); return; }
+
+  if (!draft || draft.available === false) {
+    // A normal answer, not a failure: say why and stop.
+    console.error(c.yellow(draft?.reason || 'No draft available for that project.'));
+    process.exit(1);
+  }
+
+  const plan = planWrites(root, draft.files, { force: Boolean(flags.force) });
+  applyWrites(plan);
+  console.log('');
+  console.log(describeResult(draft, plan));
+}
+
   switch (cmd) {
     case 'login':     return cmdLogin(flags);
     case 'logout':    return cmdLogout();
@@ -755,7 +927,10 @@ function cmdBinding(flags) {
     case 'status':    return cmdStatus(flags);
     case 'sessions':  return cmdSessions(flags);
     case 'sweep':     return cmdSweep();
+    case 'codex-sweep': return cmdCodexSweep(flags);
+    case 'gemini-sweep': return cmdGeminiSweep(flags);
     case 'pull':      return cmdPull(flags);
+    case 'prd':       return cmdPrd(flags, rest);
     case 'search':    return cmdSearch(flags, rest);
     case 'doctor':    return cmdDoctor(flags);
     case 'binding':   return cmdBinding(flags);

package/src/codex-rollout.mjs

@@ -0,0 +1,138 @@
+/**
+ * Parse an OpenAI Codex CLI "rollout" JSONL trace into a normalised Mnema session
+ * payload (the same shape the Claude Code hook POSTs, so the server adapter + worker
+ * are shared).
+ *
+ * Rollout files live at CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ISO>-<UUID>.jsonl
+ * (CODEX_HOME defaults to ~/.codex). Each line is `{timestamp, type, payload}`.
+ * The fields we extract (verified against the documented format — PR openai/codex#1583
+ * added token counts, timestamps + model to rollouts; ccusage parses the same events):
+ *   - session_meta   → session id, cwd, git info, (sometimes) model
+ *   - turn_context   → the active model (latest wins)
+ *   - token_count    → total_token_usage {input, cached_input, output, reasoning_output}
+ *   - function_call  → tool count; apply_patch args → files touched
+ *
+ * Version-tolerant: the payload nesting has changed across Codex releases, so every
+ * lookup is defensive and unknown lines are skipped, never thrown on. Cost is NOT in
+ * the rollout — the server computes it from `model` + `usage` via model_pricing.
+ *
+ * NOTE: token_count has historically been absent from non-interactive `codex exec`
+ * sessions (openai/codex#9660); such a session yields no `usage` and the server records
+ * it with zero cost rather than a wrong one.
+ */
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** Pull file paths out of an apply_patch tool call's argument string. */
+export function extractPatchFiles(argsRaw) {
+  const out = [];
+  let text = argsRaw;
+  if (typeof text !== 'string') {
+    try { text = JSON.stringify(argsRaw ?? ''); } catch { return out; }
+  }
+  // apply_patch envelopes use "*** Add File: path" / "Update File" / "Delete File".
+  const re = /\*\*\*\s+(?:Add|Update|Delete)\s+File:\s+(.+)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const p = m[1].trim();
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Codex tags events on TWO levels, so we match on both:
+ *   - session_meta / turn_context are top-level `type`, data in `payload` (or flat).
+ *   - token_count / function_call are the INNER `payload.type`, wrapped by an outer
+ *     `event_msg` / `response_item` type. Matching only `obj.type` misses them.
+ */
+function classify(obj) {
+  const inner = obj.payload && typeof obj.payload === 'object' ? obj.payload : obj;
+  const topType = typeof obj.type === 'string' ? obj.type : undefined;
+  const innerType = typeof inner.type === 'string' ? inner.type : topType;
+  return { inner, topType, innerType };
+}
+
+/**
+ * @param {string} jsonlText  full contents of one rollout-*.jsonl file
+ * @param {{ sessionId?: string, developerId?: string }} [opts]
+ * @returns {object|null}  normalised session payload, or null if no session id found
+ */
+export function parseCodexRollout(jsonlText, opts = {}) {
+  const lines = String(jsonlText).split(/\r?\n/);
+  let sessionId = opts.sessionId ?? null;
+  let model = null;
+  let cwd = null;
+  let gitRoot = null;
+  let gitBranch = null;
+  let gitRemote = null;
+  let usage = null;
+  let startTs = null;
+  let endTs = null;
+  let toolCount = 0;
+  const files = new Set();
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+
+    if (typeof obj.timestamp === 'string') {
+      if (!startTs) startTs = obj.timestamp;
+      endTs = obj.timestamp;
+    }
+
+    const { inner, topType, innerType } = classify(obj);
+
+    if (topType === 'session_meta' || innerType === 'session_meta') {
+      sessionId = sessionId ?? inner.id ?? inner.session_id ?? null;
+      cwd = cwd ?? inner.cwd ?? null;
+      model = model ?? inner.model ?? null;
+      const git = inner.git ?? inner.git_info ?? {};
+      gitRoot = gitRoot ?? git.repository_root ?? git.root ?? null;
+      gitBranch = gitBranch ?? git.branch ?? null;
+      gitRemote = gitRemote ?? git.remote_url ?? git.origin_url ?? git.remote ?? null;
+    } else if (topType === 'turn_context' || innerType === 'turn_context') {
+      if (typeof inner.model === 'string') model = inner.model; // latest wins
+      cwd = cwd ?? inner.cwd ?? null;
+    } else if (innerType === 'token_count') {
+      const tot = inner.total_token_usage ?? inner.info?.total_token_usage ?? inner.total ?? null;
+      if (tot && typeof tot === 'object') {
+        usage = {
+          input_tokens: num(tot.input_tokens),
+          output_tokens: num(tot.output_tokens) + num(tot.reasoning_output_tokens),
+          cache_read_tokens: num(tot.cached_input_tokens),
+        };
+      }
+    } else if (innerType === 'function_call') {
+      toolCount += 1;
+      const name = inner.name ?? '';
+      if (name === 'apply_patch' || name === 'shell' || name === 'local_shell') {
+        for (const f of extractPatchFiles(inner.arguments)) files.add(f);
+      }
+    }
+  }
+
+  if (!sessionId) return null;
+
+  const payload = {
+    session_id: sessionId,
+    hook_event_name: 'SessionEnd',
+    usage_cumulative: true,
+    developer_id: opts.developerId,
+    files_changed: [...files].map((path) => ({ path, added: null, removed: null })),
+  };
+  if (model) payload.model = model;
+  if (usage) payload.usage = usage;
+  if (cwd) payload.cwd = cwd;
+  if (gitRoot) payload.git_root = gitRoot;
+  if (gitBranch) payload.git_branch = gitBranch;
+  if (gitRemote) payload.git_remote = gitRemote;
+  if (toolCount > 0) payload.tool_count = toolCount;
+  if (startTs) payload.started_at = startTs;
+  if (endTs) payload.ended_at = endTs;
+  return payload;
+}

package/src/gemini-chat.mjs

@@ -0,0 +1,132 @@
+/**
+ * Parse a Google Gemini CLI chat-recording file into a normalised Mnema session
+ * payload (the same shape the Claude Code hook + Codex reader POST, so the server
+ * adapter + worker are shared).
+ *
+ * Gemini CLI's chatRecordingService writes conversations under
+ *   ~/.gemini/tmp/<project_hash>/chats/
+ * as a ConversationRecord — { sessionId, projectHash, model, messages[] } — where
+ * each message carries per-turn token usage (Gemini's usageMetadata:
+ * promptTokenCount / candidatesTokenCount / cachedContentTokenCount / total).
+ * Unlike Codex's cumulative token_count, Gemini logs usage PER TURN, so the
+ * session total is the SUM across messages.
+ *
+ * Format-tolerant: the file may be one JSON object (the whole ConversationRecord)
+ * or JSONL (a header line + one message per line), and field names have drifted
+ * (usageMetadata vs tokens; camelCase vs snake_case). Every lookup is defensive and
+ * malformed input is skipped, never thrown on.
+ *
+ * Gemini CLI records real tokens (this is why it was chosen over Antigravity CLI,
+ * which does not) — but no USD; the server computes cost from model + usage.
+ *
+ * NOTE: verified against the DOCUMENTED shape (chatRecordingTypes.ts + Google's
+ * session docs), not yet a live ~/.gemini file — validate against a real chat
+ * before trusting cost numbers in prod.
+ */
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** Read a usageMetadata-ish object off a message, tolerating field-name variants. */
+function readUsage(m) {
+  const u = m.usageMetadata ?? m.usage ?? m.tokens ?? m.tokenUsage ?? null;
+  if (!u || typeof u !== 'object') return null;
+  const input = num(u.promptTokenCount ?? u.inputTokens ?? u.input_tokens ?? u.prompt_tokens);
+  const output = num(u.candidatesTokenCount ?? u.outputTokens ?? u.output_tokens ?? u.candidates_tokens);
+  const cached = num(u.cachedContentTokenCount ?? u.cachedTokens ?? u.cache_read_tokens ?? u.cached_tokens);
+  if (input === 0 && output === 0 && cached === 0) return null;
+  return { input, output, cached };
+}
+
+/** Pull edited file paths out of a message's tool calls. */
+function filesFromMessage(m, into) {
+  const calls = m.toolCalls ?? m.tool_calls ?? m.functionCalls ?? [];
+  if (!Array.isArray(calls)) return;
+  for (const call of calls) {
+    const name = call.name ?? call.tool ?? call.functionName ?? '';
+    if (!/write_file|replace|edit|create_file|apply/i.test(String(name))) continue;
+    const args = call.args ?? call.arguments ?? call.input ?? {};
+    const path = args.file_path ?? args.absolute_path ?? args.path ?? args.filePath ?? args.filename;
+    if (typeof path === 'string' && path.trim()) into.add(path.trim());
+  }
+}
+
+/** Coerce a file's contents into an array of records (whole-object or JSONL). */
+function toRecords(text) {
+  const trimmed = String(text).trim();
+  if (!trimmed) return [];
+  // Try the whole file as one JSON value first (the common ConversationRecord case).
+  try {
+    const whole = JSON.parse(trimmed);
+    return Array.isArray(whole) ? whole : [whole];
+  } catch { /* fall through to JSONL */ }
+  const out = [];
+  for (const line of trimmed.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+/**
+ * @param {string} text        contents of one Gemini chat file
+ * @param {{ sessionId?: string, developerId?: string }} [opts]
+ * @returns {object|null}      normalised session payload, or null if no session id
+ */
+export function parseGeminiChat(text, opts = {}) {
+  const records = toRecords(text);
+  if (records.length === 0) return null;
+
+  let sessionId = opts.sessionId ?? null;
+  let model = null;
+  let startTs = null;
+  let endTs = null;
+  const usage = { input: 0, output: 0, cached: 0 };
+  let sawUsage = false;
+  const files = new Set();
+  let turns = 0;
+
+  // A record is either a header (sessionId/projectHash/model + maybe messages[])
+  // or a single message. Handle both, and recurse into an embedded messages[].
+  const messages = [];
+  for (const rec of records) {
+    if (!rec || typeof rec !== 'object') continue;
+    sessionId = sessionId ?? rec.sessionId ?? rec.session_id ?? rec.id ?? null;
+    if (typeof rec.model === 'string') model = rec.model;
+    if (rec.startTime ?? rec.start_time) startTs = startTs ?? (rec.startTime ?? rec.start_time);
+    if (rec.lastUpdated ?? rec.last_updated) endTs = rec.lastUpdated ?? rec.last_updated;
+    if (Array.isArray(rec.messages)) messages.push(...rec.messages);
+    else if (rec.role || rec.content || rec.usageMetadata || rec.tokens) messages.push(rec);
+  }
+
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue;
+    turns += 1;
+    if (typeof m.model === 'string' && !model) model = m.model;
+    const ts = m.timestamp ?? m.time ?? m.created_at ?? m.createdAt;
+    if (ts) { startTs = startTs ?? ts; endTs = ts; }
+    const u = readUsage(m);
+    if (u) { usage.input += u.input; usage.output += u.output; usage.cached += u.cached; sawUsage = true; }
+    filesFromMessage(m, files);
+  }
+
+  if (!sessionId) return null;
+
+  const payload = {
+    session_id: sessionId,
+    hook_event_name: 'SessionEnd',
+    usage_cumulative: true, // we already summed to the session total
+    developer_id: opts.developerId,
+    files_changed: [...files].map((path) => ({ path, added: null, removed: null })),
+  };
+  if (model) payload.model = model;
+  if (sawUsage) {
+    payload.usage = { input_tokens: usage.input, output_tokens: usage.output, cache_read_tokens: usage.cached };
+  }
+  if (turns > 0) payload.tool_count = turns;
+  if (startTs) payload.started_at = String(startTs);
+  if (endTs) payload.ended_at = String(endTs);
+  return payload;
+}

package/src/prd.mjs

@@ -0,0 +1,97 @@
+/**
+ * `mnema prd init` — write the declaration bootstrap into this repo (t-934).
+ *
+ * ⭐ THIS COMMAND WAS ADVERTISED BEFORE IT EXISTED. The app's bootstrap prompt
+ * has told people to run `npx mnema prd init` since it shipped. There was no
+ * `prd` command in any published version, so every reader who followed the
+ * instruction got "Unknown command: prd". The generator behind the promise was
+ * real — it had no route a CLI could reach, and no CLI caller.
+ *
+ * ⛔ MNEMA WRITES INTO A WORKING TREE, NEVER INTO HISTORY. It does not commit,
+ * and it does not push. The declaration is authored in the repo BY A PERSON;
+ * Mnema reading its own output back as though a human had written it is the seam
+ * the whole declaration build rests on. So: write the files, tell the reader to
+ * review them, stop.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Pick the project to draft for.
+ *
+ * ⚠️ NO GUESSING FROM THE GIT REMOTE. The projects API returns `repoId`, not a
+ * repo name, so matching a remote would mean a second lookup per project and a
+ * confident wrong answer when two projects share a repo. An explicit choice, or
+ * a list to choose from, is the honest interface.
+ */
+export function chooseProject(projects, wanted) {
+  if (!wanted) return { ok: false, reason: 'none-given', projects };
+  const want = String(wanted).trim().toLowerCase();
+  const byId = projects.find((p) => p.id.toLowerCase() === want);
+  if (byId) return { ok: true, project: byId };
+  const byName = projects.filter((p) => p.name.toLowerCase() === want);
+  if (byName.length === 1) return { ok: true, project: byName[0] };
+  if (byName.length > 1) return { ok: false, reason: 'ambiguous', projects: byName };
+  const partial = projects.filter((p) => p.name.toLowerCase().includes(want));
+  if (partial.length === 1) return { ok: true, project: partial[0] };
+  if (partial.length > 1) return { ok: false, reason: 'ambiguous', projects: partial };
+  return { ok: false, reason: 'no-match', projects };
+}
+
+/**
+ * Decide what to do with each file the server returned.
+ *
+ * ⚠️ NEVER OVERWRITE SILENTLY. `docs/prd.md` is the declaration — a human wrote
+ * it, and it is the source of truth for what every feature claims. Replacing one
+ * without asking would destroy exactly the authorship this design protects.
+ * Identical content is a no-op, not a write, so re-running is safe.
+ */
+export function planWrites(root, files, { force = false } = {}) {
+  return Object.entries(files).map(([rel, content]) => {
+    const abs = join(root, rel);
+    if (!existsSync(abs)) return { rel, abs, content, action: 'create' };
+    const current = readFileSync(abs, 'utf8');
+    if (current === content) return { rel, abs, content, action: 'unchanged' };
+    return { rel, abs, content, action: force ? 'overwrite' : 'skip-exists' };
+  });
+}
+
+/** Apply a plan. Returns the plan, annotated with what happened. */
+export function applyWrites(plan) {
+  for (const item of plan) {
+    if (item.action === 'create' || item.action === 'overwrite') {
+      mkdirSync(dirname(item.abs), { recursive: true });
+      writeFileSync(item.abs, item.content, 'utf8');
+    }
+  }
+  return plan;
+}
+
+/** The report a reader needs after a draft is written. */
+export function describeResult(draft, plan) {
+  const lines = [];
+  const wrote = plan.filter((p) => p.action === 'create' || p.action === 'overwrite');
+  const skipped = plan.filter((p) => p.action === 'skip-exists');
+  const same = plan.filter((p) => p.action === 'unchanged');
+
+  for (const p of wrote) lines.push(`  wrote     ${p.rel}`);
+  for (const p of same) lines.push(`  unchanged ${p.rel}`);
+  for (const p of skipped) lines.push(`  kept      ${p.rel}  (already exists — pass --force to replace)`);
+
+  lines.push('');
+  lines.push(`  ${draft.kept.length} feature${draft.kept.length === 1 ? '' : 's'} drafted from ` +
+             `${draft.observedScopes} observed scope${draft.observedScopes === 1 ? '' : 's'} ` +
+             `over ${draft.windowDays} days`);
+
+  const rejected = Array.isArray(draft.rejected) ? draft.rejected.length : 0;
+  if (rejected > 0) {
+    // ⚠️ Reported, not hidden. A scope screened out is a feature the draft does
+    // NOT claim — leaving that silent would let someone believe the file covers
+    // everything.
+    lines.push(`  ${rejected} scope${rejected === 1 ? '' : 's'} screened out (too little evidence to declare)`);
+  }
+  lines.push('');
+  lines.push('  Review it, correct it, and commit it. Mnema does not commit — the');
+  lines.push('  declaration is yours, and that is what makes it worth trusting.');
+  return lines.join('\n');
+}