scriptonia 0.2.0 → 0.6.0

package/README.md

@@ -1,7 +1,8 @@
 # scriptonia
 
-Product memory for your coding agent. One command, browser sign-in, and your
-agent reads what your customers actually asked for — with sources it can cite.
+Turn customer signal into **executable plans your coding agent runs**. An issue
+goes in; a hyper-focused, sourced, contradiction-checked `PLAN.md` comes out —
+your agent (Claude Code, Codex, OpenClaw, Hermes) executes it into a PR.
 
 ## Quick start
 
@@ -9,46 +10,65 @@ agent reads what your customers actually asked for — with sources it can cite.
 npx scriptonia login
 ```
 
-That's it. A browser opens, you sign in with Google, and:
+A browser opens, you sign in, and you're wired: project created, key stored (you
+never see one), and your agent's `AGENTS.md` / skill now know about `scriptonia
+plan`. Then, in your project:
 
-- your project is created (with a sample dataset so you can try it immediately),
-- an API key is minted and stored for you (you never see or paste a key),
-- the Claude Code skill is installed to `~/.claude/skills/scriptonia/`.
+```sh
+scriptonia add feedback.txt call.vtt notes.md   # feed customer signal
+scriptonia plan "let compliance filter the audit log by actor"
+# → writes PLAN.md: goal, cited evidence, non-goals, real file paths, acceptance criteria
+claude "execute PLAN.md"                         # your agent ships it → PR
+```
 
-Then your agent — or you — can ask the product brain:
+Left a review note? The plan regenerates:
 
 ```sh
-scriptonia query "audit log filtering"
+scriptonia comment plan/<slug> "default to all actors, and gate behind the admin role"
+# → PLAN.md v2 with your note folded in
 ```
 
+## The loop
+
+| step | command | what happens |
+|---|---|---|
+| **SIGNAL** | `scriptonia add <files>` | Ingest text · md · vtt as customer signal (deduped, auto-sourced). |
+| **PLAN** | `scriptonia plan "<issue>"` | Retrieve the relevant signal, check prior decisions, and write **PLAN.md** — every claim cites a signal id; contradictions are gated **UNRESOLVED** until a human approves. |
+| **BUILD** | `claude "execute PLAN.md"` | Your agent runs the plan verbatim. Respects the Non-goals fence; cites sources in the PR. |
+| **REFINE** | `scriptonia comment plan/<slug> "…"` | A note regenerates the plan (v+1). A comment approving an override flips a contradiction to **RESOLVED**. |
+
 ## Commands
 
-| command | what it does |
-|---|---|
-| `scriptonia login` | Browser sign-in. Stores creds in `~/.scriptonia/config.json`, installs the skill. |
-| `scriptonia query "<topic>"` | Ask the product brain. Flags: `--window 7d\|30d\|90d\|all`, `--segment enterprise\|mid_market\|smb\|free`, `--json`. |
-| `scriptonia link "<signal_id>"` | Resolve a signal id (from `query` sources) to its full text. |
-| `scriptonia status` | Who you are / which project. |
-| `scriptonia logout` | Forget credentials. |
-| `scriptonia mcp` | Run as an MCP server over stdio (for MCP-native agents like Codex). |
+```
+setup     login                     init [per repo]
+signal    add <files>               (--source, --segment, or  cat x | scriptonia add -)
+plan      plan "<issue>"            (--out <file>, --refresh <slug>)
+          plans                     list plans + their slugs
+          comment plan/<slug> "…"   refine → regenerates PLAN.md
+inspect   scriptonia                the loop + what's next
+          contexts | query "<topic>" | link "<id>" | sync
+account   status | logout | skill | mcp
+```
 
-## For MCP-native agents
+## One brain per repo (for people juggling projects)
+
+`scriptonia init` in a repo gives it its own brain at
+`~/.scriptonia/projects/<slug>/`, scans the code into a repo map (so plan steps
+name real files), and writes an `AGENTS.md` section. Confidential signal stays
+in your home dir — only `PLAN.md` and the `AGENTS.md` note land in the repo.
 
-Point your agent at:
+Skip `init` if you have one product — `login → add → plan` uses your default
+brain and scans whatever repo you run `plan` in.
+
+## For MCP-native agents
 
 ```json
-{
-  "command": "npx",
-  "args": ["-y", "scriptonia", "mcp"]
-}
+{ "command": "npx", "args": ["-y", "scriptonia", "mcp"] }
 ```
 
-It exposes `get_context`, `link_back`, and `flag_contradiction`, reading your
-stored credentials — no env vars needed after `scriptonia login`.
+Exposes `get_context`, `link_back`, `flag_contradiction` from your stored login.
 
 ## Self-hosting
 
-By default the CLI talks to `https://scriptonia.dev`. Point it elsewhere with
-`SCRIPTONIA_URL=https://your.host scriptonia login` (or `--url`).
-
-Requires Node 18+.
+Defaults to `https://scriptonia.dev`. Point elsewhere with
+`SCRIPTONIA_URL=https://your.host scriptonia login` (or `--url`). Node 18+.

package/bin/scriptonia.mjs

@@ -1,34 +1,43 @@
 #!/usr/bin/env node
 /**
- * scriptonia — product memory for your coding agent.
+ * scriptonia — issue → executable plan for your coding agent.
  *
- *   scriptonia login              browser sign-in; stores creds; installs the skill
- *   scriptonia query "<topic>"    ask the product brain (what the agent calls)
- *   scriptonia link "<signal_id>" resolve a signal to its full text
- *   scriptonia status             who am I / which project
- *   scriptonia logout             forget creds
- *   scriptonia mcp                speak MCP over stdio (for MCP-native agents)
+ *   scriptonia login                 browser sign-in; wires your agent
+ *   scriptonia add <files>           feed customer signal (text · md · vtt)
+ *   scriptonia plan "<issue>"        → PLAN.md: sourced, contradiction-checked
+ *   scriptonia comment plan/<slug>   refine → regenerates PLAN.md
+ *   scriptonia init                  [per repo] give a repo its own brain
+ *   scriptonia mcp                   MCP over stdio (for MCP-native agents)
  *
- * After `login`, everything lives in ~/.scriptonia/config.json. No env vars,
- * no key pasting. The installed Claude Code skill just runs `scriptonia query`.
- *
- * Pure ESM, zero build step — runs on Node 18+.
+ * After `login`, everything lives in ~/.scriptonia/. No env vars, no key
+ * pasting. Pure ESM, zero build step — runs on Node 18+.
  */
 import fs from "node:fs";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import readline from "node:readline";
+import { spawn, execSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 
 const DEFAULT_URL = process.env.SCRIPTONIA_URL || "https://scriptonia.dev";
 const CONFIG_DIR = path.join(os.homedir(), ".scriptonia");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+const PROJECTS_DIR = path.join(CONFIG_DIR, "projects");
 
 const [, , cmd, ...rest] = process.argv;
 
-const commands = { login, query, link, status, logout, init: reinstallSkill, mcp, help: async () => usage() };
-const run = commands[cmd ?? "help"] ?? (async () => { usage(); process.exit(1); });
+const commands = {
+  login, init, sync,
+  add, ingest: add, push: add,
+  plan, plans, comment,
+  query, contexts, link,
+  status, logout, skill: reinstallSkill, mcp,
+  flow, guide: flow,
+  help: async () => usage(),
+};
+// No command → show the guided flow (where am I / what's next), not raw usage.
+const run = commands[cmd ?? "flow"] ?? (async () => { usage(); process.exit(1); });
 run(rest).catch((e) => {
   console.error("error:", e instanceof Error ? e.message : String(e));
   process.exit(1);
@@ -79,18 +88,292 @@ async function login(args) {
   saveConfig(result);
   installSkill();
 
-  console.log(`\n  ✓ Signed in as ${result.email}`);
-  console.log(`  ✓ Project "${result.project}" ready (with a sample dataset to try)`);
-  console.log(`  ✓ Skill installed → ~/.claude/skills/scriptonia/SKILL.md`);
-  console.log(`\n  Your agent now reads your customers. Try it:\n`);
-  console.log(`    scriptonia query "audit log filtering"\n`);
+  const C = colors();
+  console.log(`\n  ${C.g}✓${C.r} Signed in as ${result.email}  ${C.dim}(project "${result.project}", with sample data to try)${C.r}`);
+  console.log(`  ${C.g}✓${C.r} Agent wired — skill + AGENTS.md know about \`scriptonia plan\``);
+  console.log(`\n  ${C.b}The loop — feed signal, turn an issue into a plan your agent runs:${C.r}\n`);
+  console.log(`    ${C.g}scriptonia add${C.r} feedback.txt call.vtt      ${C.dim}feed customer signal${C.r}`);
+  console.log(`    ${C.g}scriptonia plan${C.r} "the thing to build"      ${C.dim}→ PLAN.md (sourced, checked)${C.r}`);
+  console.log(`    ${C.g}claude${C.r} "execute PLAN.md"                 ${C.dim}your agent ships it${C.r}`);
+  console.log(`\n  ${C.dim}Try it on the sample data now:${C.r} ${C.g}scriptonia plan "filter audit log by actor"${C.r}`);
+  console.log(`  ${C.dim}Working across repos? Run${C.r} ${C.g}scriptonia init${C.r} ${C.dim}in each for its own brain.${C.r}\n`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// flow — the guided map: where am I, what's next (bare `scriptonia`)
+// ─────────────────────────────────────────────────────────────
+async function flow() {
+  const cfg = loadConfig();
+  const C = colors();
+  if (!cfg) {
+    console.log(`\n  ${C.b}SCRIPTONIA${C.r} · turn customer signal into plans your agent can execute\n`);
+    console.log(`  One command sets everything up:\n`);
+    console.log(`    ${C.g}scriptonia login${C.r}\n`);
+    return;
+  }
+
+  const repo = findProjectForCwd();
+  const token = repo ? repo.data.token : cfg.token;
+  const projName = repo ? repo.data.name : cfg.project;
+
+  let o = null;
+  try {
+    const res = await fetch(`${cfg.url}/api/overview`, { headers: { authorization: `Bearer ${token}` } });
+    if (res.ok) o = await res.json();
+  } catch { /* offline */ }
+
+  const s = o?.signals ?? { total: 0, enriched: 0 };
+  const plansN = o?.plans_count ?? 0;
+  const recentPlan = o?.plans?.[0]?.slug ?? null;
+
+  console.log(`\n  ${C.b}SCRIPTONIA${C.r}  ·  issue → executable plan for your agent`);
+  console.log(`  ${C.dim}${cfg.email} · project ${o?.project ?? projName}${repo ? "" : C.dim + "  (global — run `scriptonia init` in a repo for its own brain)"}${C.r}\n`);
+
+  const row = (n, name, desc, cmd) =>
+    console.log(`  ${C.v}${n}${C.r}  ${C.b}${name.padEnd(7)}${C.r} ${C.dim}${desc.padEnd(34)}${C.r} ${cmd ? C.g + cmd + C.r : ""}`);
+
+  console.log(`  ${C.dim}THE LOOP${C.r}   ${C.dim}${s.total} signals · ${plansN} plans${C.r}`);
+  row("1", "SIGNAL", "feed customer reality (text·md·vtt)", `scriptonia add <files>`);
+  row("2", "PLAN", "issue → PLAN.md, sourced & checked", `scriptonia plan "<issue>"`);
+  row("3", "BUILD", "your agent executes PLAN.md → PR", `claude "execute PLAN.md"`);
+  row("4", "REFINE", "a note regenerates the plan", `scriptonia comment plan/<slug> "…"`);
+
+  console.log(`\n  ${C.b}NEXT${C.r}  ${nextStep(s, plansN, recentPlan, repo, C)}\n`);
+}
+
+function nextStep(s, plansN, recentPlan, repo, C) {
+  if (s.total === 0)
+    return `${C.g}scriptonia add feedback.txt call.vtt${C.r}  ${C.dim}— feed the brain customer signal${C.r}`;
+  if (plansN === 0)
+    return `${C.g}scriptonia plan "the thing you're about to build"${C.r}  ${C.dim}— writes PLAN.md${C.r}`;
+  return `${C.g}claude "execute PLAN.md"${C.r}  ${C.dim}— ship it · or refine: ${C.r}${C.g}scriptonia comment plan/${recentPlan} "…"${C.r}`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// add — ingest files from the terminal (the founder's on-ramp)
+// ─────────────────────────────────────────────────────────────
+async function add(args) {
+  const cfg = activeCreds();
+  const flags = parseFlags(args);
+  const items = args.filter((a) => !a.startsWith("--"));
+  if (items.length === 0) {
+    fail(
+      'usage: scriptonia add <file...>            e.g. scriptonia add slack.txt notes.md call.vtt\n' +
+      '       scriptonia add "Issue #42: …"       inline signal — also analyzed against the brain → context.md\n' +
+      "       flags: --source slack|ticket|sales_call|voice_note|founder_note|email|notion|github\n" +
+      "              --segment enterprise|mid_market|smb|free\n" +
+      "       pipe:  cat thread.txt | scriptonia add -",
+    );
+  }
+
+  const C = colors();
+  // A single non-file argument with whitespace is inline signal text (an issue,
+  // a pasted message). A bare word that isn't a file stays a "not found" error
+  // so typo'd filenames don't get silently ingested as one-word signals.
+  const inline = items.length === 1 && items[0] !== "-" && !fs.existsSync(items[0]) && /\s/.test(items[0]);
+  let created = 0, dup = 0, failed = 0;
+  let inlineSignalId = null;
+
+  for (const item of inline ? [items[0]] : items) {
+    let body, ref, srcHint;
+    if (inline) {
+      body = item;
+      ref = null;
+      srcHint = flags.source ?? "ticket";
+    } else if (item === "-") {
+      body = fs.readFileSync(0, "utf8"); // stdin
+      ref = null;
+      srcHint = "founder_note";
+    } else {
+      if (!fs.existsSync(item)) { console.log(`  ${C.w}skip${C.r} ${item} (not found)`); failed++; continue; }
+      body = fs.readFileSync(item, "utf8");
+      ref = `upload/${path.basename(item)}`;
+      srcHint = detectSource(item);
+    }
+    if (!body.trim()) { console.log(`  ${C.w}skip${C.r} ${item} (empty)`); continue; }
+
+    const res = await fetch(`${cfg.url}/api/ingest`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+      body: JSON.stringify({
+        source: flags.source ?? srcHint,
+        body,
+        // omit when absent — the API's schema rejects an explicit null
+        externalRef: ref ?? undefined,
+        segment: flags.segment,
+      }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) { console.log(`  ${C.w}fail${C.r} ${inline ? "inline signal" : item} (${res.status})`); failed++; continue; }
+    const label = inline ? `"${body.slice(0, 56)}${body.length > 56 ? "…" : ""}"` : item;
+    if (data.status === "duplicate") { console.log(`  ${C.dim}dup ${C.r} ${label}`); dup++; }
+    else { console.log(`  ${C.g}✓${C.r}   ${label} ${C.dim}→ ${flags.source ?? srcHint} · sig_${(data.signalId ?? "").slice(0, 8)}${C.r}`); created++; }
+    if (inline) inlineSignalId = data.signalId ?? null;
+
+    // Local receipt so an agent reading the brain sees what signal exists.
+    if (cfg.inited && data.signalId) {
+      writeSignalReceipt(cfg.dir, {
+        id: data.signalId,
+        source: flags.source ?? srcHint,
+        externalRef: ref,
+        segment: flags.segment ?? null,
+        preview: body.slice(0, 240),
+        status: data.status === "duplicate" ? "duplicate" : "queued_for_embedding",
+      });
+    }
+  }
+
+  if (cfg.inited) appendLog(cfg.dir, "add", `${created} added, ${dup} dup, ${failed} failed${inline ? " (inline)" : ""}`);
+  console.log(`\n  ${created} added${dup ? `, ${dup} already there` : ""}${failed ? `, ${failed} failed` : ""}.`);
+
+  // Inline signal = an issue. Analyze it against the brain now (the existing
+  // embedded signal + decisions) and materialize context.md.
+  if (inline && (created > 0 || dup > 0)) {
+    console.log(`  ${C.dim}Analyzing against the brain — retrieved signal · prior decisions… (~10s)${C.r}`);
+    try {
+      const qres = await fetch(`${cfg.url}/api/query`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+        body: JSON.stringify({ query: items[0], window: "all" }),
+      });
+      const q = await qres.json();
+      if (qres.ok) {
+        const md = renderContextLive(items[0], q, cfg.project, inlineSignalId);
+        if (cfg.inited) fs.writeFileSync(path.join(cfg.dir, "context.md"), md);
+        const unresolved = (q.contradictions ?? []).length;
+        console.log(`\n  ${C.g}✓${C.r} context synthesized${cfg.inited ? ` → ${C.dim}${path.join(cfg.dir, "context.md")}${C.r}` : ""}`);
+        console.log(`  ${C.dim}${(q.sources ?? []).length} signal(s) cited${unresolved ? ` · ${C.r}${C.w}⚠ ${unresolved} contradiction(s) with prior decisions — gate is UNRESOLVED${C.r}` : ""}${C.r}`);
+        if (cfg.inited) appendLog(cfg.dir, "add", `context.md synthesized (${(q.sources ?? []).length} cited, ${unresolved} contradictions)`);
+      }
+    } catch { /* analysis is best-effort; the signal is already ingested */ }
+    console.log(`\n  ${C.b}Next:${C.r} ${C.g}scriptonia plan "${items[0].slice(0, 48)}${items[0].length > 48 ? "…" : ""}"${C.r}\n`);
+    return;
+  }
+
+  if (created > 0) {
+    console.log(`  ${C.dim}The brain is enriching them now. Then:${C.r} ${C.g}scriptonia plan "<issue>"${C.r}\n`);
+  }
+}
+
+function detectSource(file) {
+  const ext = path.extname(file).toLowerCase();
+  if (ext === ".vtt" || ext === ".srt") return "sales_call";
+  if (ext === ".md") return "founder_note";
+  return "founder_note";
+}
+
+// ─────────────────────────────────────────────────────────────
+// contexts — what the brain produced
+// ─────────────────────────────────────────────────────────────
+async function contexts() {
+  const cfg = activeCreds();
+  const C = colors();
+  const res = await fetch(`${cfg.url}/api/overview`, { headers: { authorization: `Bearer ${cfg.token}` } });
+  if (!res.ok) fail(`could not load contexts (${res.status})`);
+  const o = await res.json();
+
+  if (o.contexts_count === 0) {
+    console.log(`\n  ${C.dim}No contexts yet.${C.r}`);
+    if ((o.signals?.total ?? 0) === 0) console.log(`  Add signal first: ${C.g}scriptonia add <files>${C.r}\n`);
+    else console.log(`  The brain is still indexing ${o.signals.total} signals — check back in a minute.\n`);
+    return;
+  }
+
+  console.log(`\n  ${C.b}${o.contexts_count} context${o.contexts_count > 1 ? "s" : ""}${C.r} ${C.dim}· ${o.project}${C.r}\n`);
+  for (const c of o.contexts) {
+    const warn = c.contradicts ? ` ${C.w}⚠ contradicts${C.r}` : "";
+    console.log(`  ${C.g}${String(c.strength).padStart(4)}${C.r}  ${C.b}${c.title}${C.r}  ${C.dim}${c.type} · v${c.version} · ${c.segment}${C.r}${warn}`);
+    console.log(`        ${C.v}${cfg.url}/contexts/${c.slug}${C.r}`);
+  }
+  console.log(`\n  ${C.dim}Turn any of these into a plan:${C.r} ${C.g}scriptonia plan "<the issue>"${C.r}\n`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// plans — list generated plans (find a slug to refine or re-fetch)
+// ─────────────────────────────────────────────────────────────
+async function plans() {
+  const cfg = activeCreds();
+  const C = colors();
+  const res = await fetch(`${cfg.url}/api/overview`, { headers: { authorization: `Bearer ${cfg.token}` } });
+  if (!res.ok) fail(`could not load plans (${res.status})`);
+  const o = await res.json();
+  const list = o.plans ?? [];
+  if (list.length === 0) {
+    console.log(`\n  ${C.dim}No plans yet.${C.r}  Generate one: ${C.g}scriptonia plan "<issue>"${C.r}\n`);
+    return;
+  }
+  console.log(`\n  ${C.b}${list.length} plan${list.length > 1 ? "s" : ""}${C.r} ${C.dim}· ${o.project}${C.r}\n`);
+  for (const p of list) {
+    console.log(`  ${C.b}${p.slug}${C.r} ${C.dim}v${p.version}${C.r}`);
+    console.log(`     ${C.dim}${p.issue}${C.r}`);
+    console.log(`     ${C.g}scriptonia plan --refresh ${p.slug}${C.r} ${C.dim}·${C.r} ${C.g}scriptonia comment plan/${p.slug} "…"${C.r}`);
+  }
+  console.log("");
+}
+
+// ─────────────────────────────────────────────────────────────
+// comment — leave an inline note; the brain absorbs it (version bump)
+// ─────────────────────────────────────────────────────────────
+async function comment(args) {
+  const cfg = activeCreds();
+  const C = colors();
+  const flags = parseFlags(args);
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const target = positional[0];
+  const text = positional.slice(1).join(" ").trim();
+  if (!target || !text) {
+    fail(
+      'usage: scriptonia comment <slug> "<your note>"          comment on a context\n' +
+      '       scriptonia comment plan/<slug> "<your note>"     comment on a plan → regenerates PLAN.md\n' +
+      '       --as "Name"   attribute the comment (defaults to you)',
+    );
+  }
+
+  // Comment on a PLAN → regenerate it (v+1) and rewrite PLAN.md.
+  if (target.startsWith("plan/")) {
+    const slug = target.slice(5);
+    console.log(`\n  ${C.dim}Folding your note into "${slug}" and regenerating…${C.r}`);
+    const res = await fetch(`${cfg.url}/api/plan/comment`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+      body: JSON.stringify({ slug, body: text, author: flags.as ?? cfg.email }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (res.status === 404) fail(`no plan "${slug}" — generate one first: scriptonia plan "<issue>"`);
+    if (!res.ok) fail(`comment failed (${res.status}): ${JSON.stringify(data).slice(0, 200)}`);
+    // Approval-chain receipt: which human note produced which plan version.
+    if (cfg.inited) {
+      const cdir = path.join(cfg.dir, "comments", "plan", slug);
+      fs.mkdirSync(cdir, { recursive: true });
+      fs.writeFileSync(
+        path.join(cdir, `v${data.version}.json`),
+        JSON.stringify({ author: flags.as ?? cfg.email, body: text, applied_in_version: data.version, at: new Date().toISOString() }, null, 2),
+      );
+      appendLog(cfg.dir, "comment", `plan/${slug} — regenerated to v${data.version}`);
+    }
+    writePlan(cfg, data, flags);
+    return;
+  }
+
+  // Comment on a CONTEXT → constrained-patch absorption.
+  const res = await fetch(`${cfg.url}/api/comment`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+    body: JSON.stringify({ slug: target, body: text, author: flags.as ?? cfg.email }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (res.status === 404) fail(`no context "${target}" — see \`scriptonia contexts\``);
+  if (!res.ok) fail(`comment failed (${res.status}): ${JSON.stringify(data)}`);
+
+  console.log(`\n  ${C.g}✓${C.r} comment posted on ${C.b}${target}${C.r} ${C.dim}(v${data.from_version})${C.r}`);
+  console.log(`  ${C.dim}the brain is absorbing it — it'll bump the version. check:${C.r} ${C.g}scriptonia contexts${C.r}\n`);
 }
 
 // ─────────────────────────────────────────────────────────────
 // query — what the agent (and you) call
 // ─────────────────────────────────────────────────────────────
 async function query(args) {
-  const cfg = requireConfig();
+  const cfg = activeCreds();
   const flags = parseFlags(args);
   const q = args.filter((a) => !a.startsWith("--")).join(" ").trim();
   if (!q) fail('usage: scriptonia query "<topic>" [--window 30d] [--segment enterprise] [--json]');
@@ -112,7 +395,7 @@ async function query(args) {
 // link — resolve a signal_id to its full body
 // ─────────────────────────────────────────────────────────────
 async function link(args) {
-  const cfg = requireConfig();
+  const cfg = activeCreds();
   const id = args.find((a) => !a.startsWith("--"));
   if (!id) fail('usage: scriptonia link "<signal_id>"');
   const res = await fetch(`${cfg.url}/api/link_back?signal_id=${encodeURIComponent(id)}`, {
@@ -159,33 +442,31 @@ function skillMarkdown() {
   return `---
 name: scriptonia
 description: >
-  BEFORE planning any user-facing change — a feature, a bug fix, a refactor with
-  UX impact, or a non-trivial default — run \`scriptonia query "<topic>"\`. It
-  returns what THIS project's customers actually asked for (with source ids you
-  can cite), what prior decisions your plan might contradict, and known edge
-  cases. Skipping it means shipping a plan that isn't grounded in customer signal.
+  BEFORE building any user-facing change — a feature, a bug fix, a refactor with
+  UX impact — run \`scriptonia plan "<the issue>"\`. It writes PLAN.md here: a
+  hyper-focused, sourced, executable plan grounded in this project's real
+  customer signal, prior decisions, and human comments. Execute PLAN.md exactly.
 ---
 
-# Scriptonia — Product Memory
+# Scriptonia — Product Memory → executable plans
 
-Before writing a plan for anything user-facing, call:
+When asked to build/fix anything user-facing:
 
-\`\`\`sh
-scriptonia query "<the topic you're about to build>"
-\`\`\`
+1. Run \`scriptonia plan "<the issue>"\` — it writes **PLAN.md** in the repo.
+2. Execute PLAN.md **exactly**. Respect its **Non-goals** — do not add anything
+   outside the acceptance criteria.
+3. If a constraint is marked **UNRESOLVED**, STOP and surface it to the human.
+4. Your PR description must cite the \`sources\` signal ids from PLAN.md.
 
-Optional flags: \`--window 7d|30d|90d|all\` (default 30d), \`--segment enterprise|mid_market|smb|free\`.
+If a plan step conflicts with what you find in the code, run
+\`scriptonia comment plan/<slug> "<what you found>"\` and re-read the regenerated PLAN.md.
 
-Output (JSON when piped) contains:
-- **requirements[]** — each with \`source_ids\` and a \`context_url\`. Cite the
-  source_ids next to the matching step in your plan.
-- **contradictions[]** — if non-empty, STOP and surface it to the human before
-  writing code. Each has a \`decision_ref\`.
-- **edge_cases[]** — fold these into the plan.
-- **sources[]** — quote a customer verbatim with \`scriptonia link "<signal_id>"\`.
+To just look something up without a full plan: \`scriptonia query "<topic>"\`
+(JSON: requirements with source_ids, contradictions, edge_cases). Quote a
+customer verbatim with \`scriptonia link "<signal_id>"\`.
 
-Rule: every plan step for a user-facing change should cite at least one
-source_id. If it can't, you're inventing demand — query first.
+Rule: never invent demand. If nothing in the plan/query supports a step, it
+doesn't belong in the PR.
 `;
 }
 
@@ -193,7 +474,7 @@ source_id. If it can't, you're inventing demand — query first.
 // mcp — MCP stdio server (for MCP-native agents)
 // ─────────────────────────────────────────────────────────────
 async function mcp() {
-  const cfg = requireConfig();
+  const cfg = activeCreds();
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
   const { z } = await import("zod");
@@ -275,8 +556,17 @@ function openBrowser(url) {
   try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); } catch { /* click the printed URL */ }
 }
 
+function colors() {
+  const on = !!process.stdout.isTTY;
+  const w = (code) => (on ? code : "");
+  return {
+    dim: w("\x1b[2m"), b: w("\x1b[1m"), v: w("\x1b[35m"),
+    w: w("\x1b[33m"), g: w("\x1b[32m"), r: w("\x1b[0m"),
+  };
+}
+
 function printPretty(d) {
-  const c = { dim: "\x1b[2m", b: "\x1b[1m", v: "\x1b[35m", w: "\x1b[33m", g: "\x1b[32m", r: "\x1b[0m" };
+  const c = colors();
   console.log(`\n${c.b}${d.tldr ?? ""}${c.r}\n`);
   for (const req of d.requirements ?? []) {
     console.log(`  ${c.g}●${c.r} ${c.b}${req.title}${c.r} ${c.dim}[${req.strength}]${c.r}`);
@@ -307,16 +597,541 @@ function escapeHtml(s) {
 }
 function fail(msg) { console.error(msg); process.exit(1); }
 function usage() {
-  console.log(`scriptonia — product memory for your coding agent
+  console.log(`scriptonia — issue → executable plan for your coding agent
+
+  THE LOOP
+    1 SIGNAL   scriptonia add <files>              feed customer reality (text · md · vtt)
+    2 PLAN     scriptonia plan "<issue>"           → PLAN.md: sourced, contradiction-checked
+    3 BUILD    claude "execute PLAN.md"            your agent ships it → PR
+    4 REFINE   scriptonia comment plan/<slug> "…"  a note regenerates the plan
 
-  scriptonia login              sign in (browser) — installs the skill, no keys to copy
-  scriptonia query "<topic>"    ask the product brain
-  scriptonia link "<id>"        resolve a signal to its full text
-  scriptonia status             show who you are
-  scriptonia logout             forget credentials
-  scriptonia mcp                run as an MCP server (stdio)
+  SETUP
+    scriptonia login              sign in (browser) — wires your agent, no keys
+    scriptonia init               [per repo] give this repo its own brain + AGENTS.md
 
-  login flags: --dev --email you@co.com   (local testing; skips Google)
-  query flags: --window 30d --segment enterprise --json
+  SIGNAL & PLANS
+    scriptonia add <file...>      ingest files  (--source, --segment; or  cat x | scriptonia add -)
+    scriptonia plan "<issue>"     generate PLAN.md  (--out <file>, --refresh <slug>)
+    scriptonia plans              list your plans (and their slugs)
+    scriptonia comment plan/<slug> "…"   refine a plan → regenerates PLAN.md
+
+  INSPECT
+    scriptonia                    the loop + what's next
+    scriptonia contexts           what the brain learned from your signal
+    scriptonia query "<topic>"    quick lookup, no full plan  (--json)
+    scriptonia link "<id>"        a signal's full text
+    scriptonia sync               write the brain to local files
+
+  ACCOUNT   scriptonia status | logout | skill | mcp
 `);
 }
+
+// ═════════════════════════════════════════════════════════════
+// v2 — per-repo brain: init · sync · plan, pwd resolution
+// ═════════════════════════════════════════════════════════════
+
+/** Repo-local project when pwd is inside an initialized repo, else the global login. */
+function activeCreds() {
+  const g = loadConfig();
+  if (!g) fail("run `scriptonia login` first");
+  const proj = findProjectForCwd();
+  if (proj) {
+    // v0.6 brains are flat (REPO.md etc. at the project dir root); older ones
+    // used a brain/ subfolder — keep reading those until re-init.
+    const legacy = !fs.existsSync(path.join(proj.dir, "REPO.md")) && fs.existsSync(path.join(proj.dir, "brain"));
+    return {
+      url: g.url, email: g.email,
+      token: proj.data.token, project: proj.data.name, projectId: proj.data.projectId,
+      dir: proj.dir, brainDir: legacy ? path.join(proj.dir, "brain") : proj.dir,
+      plansDir: path.join(proj.dir, "plans"),
+      repoPath: proj.data.repoPath, inited: true,
+    };
+  }
+  return { url: g.url, email: g.email, token: g.token, project: g.project, inited: false };
+}
+
+function findProjectForCwd() {
+  if (!fs.existsSync(PROJECTS_DIR)) return null;
+  const cwd = realPath(process.cwd());
+  let best = null;
+  for (const slug of fs.readdirSync(PROJECTS_DIR)) {
+    const dir = path.join(PROJECTS_DIR, slug);
+    const pj = path.join(dir, "project.json");
+    if (!fs.existsSync(pj)) continue;
+    let data; try { data = JSON.parse(fs.readFileSync(pj, "utf8")); } catch { continue; }
+    if (!data.repoPath) continue;
+    const rp = realPath(data.repoPath);
+    if (cwd === rp || cwd.startsWith(rp + path.sep)) {
+      if (!best || rp.length > realPath(best.data.repoPath).length) best = { dir, slug, data };
+    }
+  }
+  return best;
+}
+
+// ── init ──────────────────────────────────────────────────────
+async function init(args) {
+  const flags = parseFlags(args);
+  const g = loadConfig();
+  if (!g) fail("run `scriptonia login` first, then `scriptonia init` in your repo");
+  const C = colors();
+  const cwd = process.cwd();
+
+  const existing = findProjectForCwd();
+  if (existing && !flags.force) {
+    writeRepoMd(existing.dir, scanRepo(cwd));
+    console.log(`\n  ${C.g}✓${C.r} already initialized as ${C.b}${existing.data.name}${C.r} ${C.dim}(${existing.dir})${C.r}`);
+    console.log(`  ${C.dim}re-scan from scratch:${C.r} ${C.g}scriptonia init --force${C.r}`);
+    console.log(`  ${C.dim}next:${C.r} ${C.g}scriptonia add <files>${C.r}\n`);
+    return;
+  }
+
+  console.log(`\n  ${C.dim}Scanning ${cwd}…${C.r}`);
+  const repoPath = realPath(cwd);
+  const scan = scanRepo(cwd);
+  const name = flags.name ?? scan.name;
+  const slug = slugify(name);
+  const dir = path.join(PROJECTS_DIR, slug);
+
+  let projectId, token;
+  if (existing?.data?.projectId) {
+    projectId = existing.data.projectId; token = existing.data.token;
+  } else {
+    const res = await fetch(`${g.url}/api/projects`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${g.token}`, "content-type": "application/json" },
+      body: JSON.stringify({ name }),
+    });
+    if (!res.ok) fail(`could not create project (${res.status}) — is your login valid? try \`scriptonia login\``);
+    const data = await res.json();
+    projectId = data.projectId; token = data.token;
+  }
+
+  const pitch = flags.about ?? (await ask(`  In one or two sentences — what is ${name} and who is it for?\n  > `));
+
+  // Brain structure (v0.6, flat): everything an agent needs to be grounded,
+  // as plain files. cache/ + embeddings/ intentionally absent — vectors live
+  // server-side (pgvector); writing fake index files here would be theater.
+  for (const sub of ["signals", "rules", "contexts", "plans", "comments/plan", "logs"]) {
+    fs.mkdirSync(path.join(dir, sub), { recursive: true });
+  }
+  // Migrate a legacy brain/ subfolder layout if present.
+  const legacyBrain = path.join(dir, "brain");
+  if (fs.existsSync(legacyBrain)) fs.rmSync(legacyBrain, { recursive: true, force: true });
+
+  fs.writeFileSync(
+    path.join(dir, "project.json"),
+    JSON.stringify({ projectId, token, name, slug, repoPath, pitch: pitch || null, createdAt: new Date().toISOString() }, null, 2),
+    { mode: 0o600 },
+  );
+  writeProjectMd(dir, scan, pitch);
+  writeRepoMd(dir, scan);
+  writeAgentsBrainMd(dir, { name, pitch, stack: scan.stack }, []);
+  fs.writeFileSync(path.join(dir, ".gitignore"), "logs/\nproject.json\n");
+  injectAgentsMd(cwd);
+  installSkill();
+  appendLog(dir, "init", `Initialized brain for ${name} (${repoPath}) — stack: ${scan.stack}`);
+
+  console.log(`\n  ${C.g}✓${C.r} Brain created for ${C.b}${name}${C.r}  ${C.dim}→ ${dir}${C.r}`);
+  console.log(`      ${C.dim}AGENTS.md · PROJECT.md · REPO.md · signals/ · rules/ · contexts/ · plans/ · comments/ · logs/${C.r}`);
+  console.log(`  ${C.g}✓${C.r} Scanned repo (${scan.stack})`);
+  console.log(`  ${C.g}✓${C.r} Wrote agent instructions  ${C.dim}→ ./AGENTS.md${C.r}`);
+  console.log(`\n  ${C.b}Feed it customer signal, then turn an issue into a plan:${C.r}\n`);
+  console.log(`    ${C.g}scriptonia add${C.r} feedback.txt call.vtt   ${C.dim}(or:  scriptonia add "Issue #42: …")${C.r}`);
+  console.log(`    ${C.g}scriptonia plan${C.r} "the issue you want to build"\n`);
+}
+
+// ── sync ──────────────────────────────────────────────────────
+async function sync() {
+  const cfg = activeCreds();
+  const C = colors();
+  if (!cfg.inited) fail("run `scriptonia init` in this repo first");
+  const res = await fetch(`${cfg.url}/api/brain`, { headers: { authorization: `Bearer ${cfg.token}` } });
+  if (!res.ok) fail(`sync failed (${res.status})`);
+  const brain = await res.json();
+
+  const cdir = path.join(cfg.brainDir, "contexts");
+  fs.mkdirSync(cdir, { recursive: true });
+  for (const f of fs.readdirSync(cdir)) if (f.endsWith(".md")) fs.rmSync(path.join(cdir, f));
+  for (const c of brain.contexts) fs.writeFileSync(path.join(cdir, `${c.slug}.md`), renderContextFile(c));
+
+  // Decisions → machine-checkable rules/. The server enforces these during
+  // `plan` (conflicts come back ⚠ UNRESOLVED); the local copies ground agents.
+  const rdir = path.join(cfg.brainDir, "rules");
+  fs.mkdirSync(rdir, { recursive: true });
+  for (const f of fs.readdirSync(rdir)) if (f.endsWith(".rule")) fs.rmSync(path.join(rdir, f));
+  for (const d of brain.decisions) {
+    fs.writeFileSync(path.join(rdir, `${slugify(d.title)}.rule`), renderRule(d));
+  }
+
+  // Refresh the brain's master contract with the live constraint set.
+  const pj = readProjectJson(cfg.dir);
+  writeAgentsBrainMd(cfg.brainDir, { name: cfg.project, pitch: pj?.pitch ?? "", stack: null }, brain.decisions);
+
+  appendLog(cfg.dir, "sync", `${brain.contexts.length} contexts, ${brain.decisions.length} decisions → rules/`);
+  console.log(`  ${C.g}✓${C.r} synced ${brain.contexts.length} context(s) → contexts/, ${brain.decisions.length} decision(s) → rules/ ${C.dim}(${cfg.brainDir})${C.r}`);
+}
+
+// ── plan (the money command) ──────────────────────────────────
+async function plan(args) {
+  const cfg = activeCreds();
+  const C = colors();
+  const flags = parseFlags(args);
+
+  if (flags.refresh) {
+    const res = await fetch(`${cfg.url}/api/plan?slug=${encodeURIComponent(flags.refresh)}`, { headers: { authorization: `Bearer ${cfg.token}` } });
+    const data = await res.json();
+    if (!res.ok) fail(`refresh failed (${res.status}): ${JSON.stringify(data)}`);
+    return writePlan(cfg, data, flags);
+  }
+
+  const issue = args.filter((a) => !a.startsWith("--")).join(" ").trim();
+  if (!issue) fail('usage: scriptonia plan "<the issue>"   [--out PLAN.md] [--refresh <slug>]');
+
+  const repoSummary = cfg.inited && fs.existsSync(path.join(cfg.brainDir, "REPO.md"))
+    ? fs.readFileSync(path.join(cfg.brainDir, "REPO.md"), "utf8").slice(0, 6000)
+    : buildRepoMd(scanRepo(process.cwd())).slice(0, 6000);
+
+  console.log(`\n  ${C.dim}Planning "${issue}" — retrieving signal, checking decisions, drafting… (Opus, ~15s)${C.r}`);
+  const res = await fetch(`${cfg.url}/api/plan`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+    body: JSON.stringify({ issue, repo_summary: repoSummary }),
+  });
+  const data = await res.json();
+  if (!res.ok) fail(`plan failed (${res.status}): ${JSON.stringify(data).slice(0, 200)}`);
+  writePlan(cfg, data, flags);
+}
+
+function writePlan(cfg, data, flags) {
+  const C = colors();
+  const out = flags.out ?? "PLAN.md";
+  fs.writeFileSync(path.resolve(process.cwd(), out), data.markdown);
+  if (cfg.inited) {
+    fs.mkdirSync(cfg.plansDir, { recursive: true });
+    fs.writeFileSync(path.join(cfg.plansDir, `${data.slug}.md`), data.markdown);
+    // Live copy in the brain, so an agent grounded on the brain dir sees the
+    // current plan without knowing the slug.
+    fs.writeFileSync(path.join(cfg.brainDir, "plan.md"), data.markdown);
+    appendLog(cfg.dir, "plan", `${data.slug} v${data.version} — ${(data.sources ?? []).length} sources, ${data.contradictions ?? 0} unresolved`);
+  }
+  console.log(`\n  ${C.g}✓${C.r} Plan ${C.b}${data.slug}${C.r} ${C.dim}v${data.version}${C.r} → ${C.v}${out}${C.r}`);
+  console.log(`  ${C.dim}${(data.sources ?? []).length} cited signal(s)${data.contradictions ? `, ${data.contradictions} unresolved contradiction(s)` : ""}${C.r}`);
+  console.log(`\n  ${C.b}Hand it to your agent:${C.r}  ${C.g}claude "execute PLAN.md"${C.r}   ${C.dim}(or codex · opencode · hermes)${C.r}`);
+  console.log(`  ${C.dim}refine:${C.r} ${C.g}scriptonia comment plan/${data.slug} "…"${C.r} ${C.dim}(rewrites PLAN.md)${C.r}\n`);
+}
+
+// ── repo scan ─────────────────────────────────────────────────
+function scanRepo(cwd) {
+  const readme = firstExisting(cwd, ["README.md", "readme.md", "Readme.md"]);
+  const readmeHead = readme ? fs.readFileSync(readme, "utf8").slice(0, 2000) : "";
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")); } catch {}
+  const stack = detectStack(cwd, pkg);
+  const tree = buildTree(cwd, 3);
+  const name =
+    (pkg && pkg.name && String(pkg.name).replace(/^@[^/]+\//, "")) ||
+    gitRemoteName(cwd) ||
+    path.basename(cwd);
+  const scripts = pkg && pkg.scripts ? Object.keys(pkg.scripts) : [];
+  const deps = pkg ? Object.keys({ ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }).slice(0, 20) : [];
+  const entryPoints = findEntryPoints(cwd);
+  return { name, readmeHead, stack, tree, scripts, deps, entryPoints, pkgDescription: pkg?.description || "" };
+}
+
+function detectStack(cwd, pkg) {
+  const has = (f) => fs.existsSync(path.join(cwd, f));
+  if (pkg) {
+    const d = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (d.next) return "Next.js / TypeScript";
+    if (d.react) return "React / TypeScript";
+    if (has("tsconfig.json")) return "TypeScript / Node";
+    return "Node / JavaScript";
+  }
+  if (has("go.mod")) return "Go";
+  if (has("Cargo.toml")) return "Rust";
+  if (has("requirements.txt") || has("pyproject.toml")) return "Python";
+  if (has("Gemfile")) return "Ruby";
+  if (has("pom.xml") || has("build.gradle")) return "Java/JVM";
+  if (has("composer.json")) return "PHP";
+  return "unknown";
+}
+
+function findEntryPoints(cwd) {
+  const cands = [
+    "src/app", "app", "pages", "src/index.ts", "src/index.js", "src/main.ts",
+    "main.py", "app.py", "cmd", "src/main.rs", "index.js", "server", "src/server",
+  ];
+  return cands.filter((c) => fs.existsSync(path.join(cwd, c)));
+}
+
+function buildTree(cwd, maxDepth) {
+  const IGNORE = new Set(["node_modules", ".git", ".next", "dist", "build", ".turbo", "coverage", ".vercel", "out", "__pycache__", ".venv", "target", "vendor"]);
+  const lines = [];
+  const walk = (d, depth, prefix) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    entries = entries.filter((e) => !e.name.startsWith(".") || e.name === ".env.example").filter((e) => !IGNORE.has(e.name));
+    entries.sort((a, b) => (a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1));
+    for (const e of entries.slice(0, 40)) {
+      lines.push(`${prefix}${e.name}${e.isDirectory() ? "/" : ""}`);
+      if (e.isDirectory()) walk(path.join(d, e.name), depth + 1, prefix + "  ");
+    }
+  };
+  walk(cwd, 1, "");
+  return lines.slice(0, 200).join("\n");
+}
+
+function gitRemoteName(cwd) {
+  try {
+    const url = execSync("git remote get-url origin", { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    const m = url.match(/([^/:]+?)(?:\.git)?$/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+// ── brain file writers ────────────────────────────────────────
+function writeProjectMd(dir, scan, pitch) {
+  const md = [
+    "---",
+    `project_name: ${JSON.stringify(scan.name)}`,
+    `stack: ${JSON.stringify(scan.stack)}`,
+    scan.scripts.length ? `scripts: [${scan.scripts.join(", ")}]` : null,
+    `initialized: ${new Date().toISOString().slice(0, 10)}`,
+    "---",
+    "",
+    `# ${scan.name}`,
+    "",
+    pitch ? `> ${pitch}` : (scan.pkgDescription ? `> ${scan.pkgDescription}` : "> (describe this product with `scriptonia init --force`)"),
+    "",
+    `**Stack:** ${scan.stack}`,
+    scan.deps.length ? `**Key deps:** ${scan.deps.join(", ")}` : "",
+    scan.entryPoints.length ? `**Entry points:** ${scan.entryPoints.join(", ")}` : "",
+    "",
+    scan.readmeHead ? "## From the README\n\n" + scan.readmeHead : "",
+    "",
+    "---",
+    "*The product brain. Signal receipts in `signals/`, constraints in `rules/`, enriched contexts in `contexts/`, live synthesis in `context.md`, live plan in `plan.md`. Generated by `scriptonia init`.*",
+  ].filter((l) => l !== "" && l !== null).join("\n");
+  fs.writeFileSync(path.join(dir, "PROJECT.md"), md);
+}
+
+function writeRepoMd(dir, scan) {
+  // v0.6 flat layout; keep writing into brain/ for pre-0.6 projects.
+  const target = fs.existsSync(path.join(dir, "brain")) && !fs.existsSync(path.join(dir, "REPO.md"))
+    ? path.join(dir, "brain")
+    : dir;
+  fs.mkdirSync(target, { recursive: true });
+  fs.writeFileSync(path.join(target, "REPO.md"), buildRepoMd(scan));
+}
+
+/**
+ * AGENTS.md — the brain's master contract. What an agent must respect when
+ * acting on this project: identity, the Scriptonia workflow, and the
+ * non-negotiable constraints (mirrored from the decisions corpus; the server
+ * enforces them during `plan`, this copy grounds agents working offline).
+ */
+function writeAgentsBrainMd(dir, meta, decisions) {
+  const L = [
+    `# AGENTS.md — ${meta.name} project brain`,
+    `# Generated by: scriptonia (refreshed on \`sync\`)`,
+    "",
+    "## 1. Identity",
+    "",
+    meta.pitch ? `${meta.pitch}` : "(run `scriptonia init --force` to describe this product)",
+    meta.stack ? `\nStack: ${meta.stack}` : "",
+    "",
+    "## 2. Workflow — non-negotiable",
+    "",
+    '1. Before building any user-facing change, run `scriptonia plan "<the issue>"`.',
+    "   It writes PLAN.md, grounded in real customer signal and checked against",
+    "   the rules below.",
+    "2. Execute PLAN.md **exactly**. Its **Non-goals** section is a fence — do not",
+    "   build past it.",
+    "3. Any constraint marked **⚠ UNRESOLVED** is an approval gate: STOP and get a",
+    '   human comment (`scriptonia comment plan/<slug> "…"`) before writing code.',
+    "4. Cite PLAN.md's `sources` signal ids in your PR description.",
+    "",
+    "## 3. Non-negotiable constraints (from the decisions corpus)",
+    "",
+  ];
+  if (decisions.length === 0) {
+    L.push("_None synced yet — run `scriptonia sync` after decisions exist. The server_", "_still enforces them during `plan` regardless._");
+  } else {
+    for (const d of decisions) {
+      L.push(`### ${d.title}${d.ref ? ` (${d.ref})` : ""}`, "", d.body, "");
+    }
+  }
+  L.push(
+    "",
+    "## 4. Approval gates",
+    "",
+    "- Overriding any constraint above requires an explicit human comment on the",
+    "  plan. The comment is recorded in `comments/plan/<slug>/` and flips the",
+    "  plan's gate to RESOLVED on regeneration.",
+    "",
+  );
+  fs.writeFileSync(path.join(dir, "AGENTS.md"), L.join("\n"));
+}
+
+/** Decision → machine-checkable rule file. */
+function renderRule(d) {
+  const id = slugify(d.title);
+  return [
+    "---",
+    `rule_id: ${JSON.stringify(id)}`,
+    `name: ${JSON.stringify(d.title)}`,
+    "severity: BLOCKING",
+    d.ref ? `source: ${JSON.stringify(d.ref)}` : null,
+    d.decidedAt ? `decided_at: ${JSON.stringify(String(d.decidedAt).slice(0, 10))}` : null,
+    "check: |",
+    ...String(d.body).split("\n").map((l) => `  ${l}`),
+    "enforcement: |",
+    "  Server-side during `scriptonia plan`: any issue conflicting with this rule",
+    "  is marked ⚠ UNRESOLVED in PLAN.md until a human comment approves the",
+    "  override (recorded in comments/plan/<slug>/).",
+    "---",
+  ].filter(Boolean).join("\n") + "\n";
+}
+
+/** Per-signal local receipt: signals/sig_<8>.json */
+function writeSignalReceipt(dir, sig) {
+  const sdir = path.join(dir, "signals");
+  fs.mkdirSync(sdir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sdir, `sig_${sig.id.slice(0, 8)}.json`),
+    JSON.stringify({ ...sig, added_at: new Date().toISOString() }, null, 2),
+  );
+}
+
+/** context.md — live synthesis of the current issue against the brain. */
+function renderContextLive(issue, q, project, signalId) {
+  const cite = (ids) => (ids?.length ? `  \`[${ids.map((i) => i.slice(0, 8)).join(", ")}]\`` : "");
+  const L = [
+    `# Context — ${issue.slice(0, 90)}${issue.length > 90 ? "…" : ""}`,
+    "",
+    `> Synthesized ${new Date().toISOString().slice(0, 10)} against the **${project}** brain · ${(q.sources ?? []).length} signal(s) retrieved${signalId ? ` · this issue ingested as \`sig_${signalId.slice(0, 8)}\`` : ""}`,
+    "",
+    "## TL;DR",
+    q.tldr ?? "(no synthesis)",
+    "",
+    "## What customers actually asked for",
+  ];
+  for (const r of q.requirements ?? []) {
+    L.push(`- **${r.title}** _[${r.strength}]_ — ${r.detail}${cite(r.source_ids)}`);
+  }
+  if (!(q.requirements ?? []).length) L.push("- (no supporting signal retrieved — treat scope with caution)");
+  L.push("");
+
+  const cons = q.contradictions ?? [];
+  if (cons.length) {
+    L.push("## ⚠ CONTRADICTION GATE — UNRESOLVED");
+    for (const c of cons) L.push(`- ${c.detail} (${c.decision_ref})`);
+    L.push("", "**STATUS: ⚠ UNRESOLVED.** A human must approve the override before any plan", "built on this context is executed. `scriptonia plan` will carry this gate.", "");
+  } else {
+    L.push("## Contradiction gate", "", "✓ No conflicts with prior decisions on record.", "");
+  }
+
+  if ((q.edge_cases ?? []).length) {
+    L.push("## Edge cases — fold into any plan");
+    for (const e of q.edge_cases) L.push(`- ${e}`);
+    L.push("");
+  }
+
+  L.push("## Cited signals");
+  for (const s of q.sources ?? []) {
+    L.push(`- \`sig_${s.signal_id.slice(0, 8)}\` ${s.source}${s.ref ? ` — ${s.ref}` : ""} _(similarity ${s.similarity})_`);
+  }
+  L.push("", "---", `*Next: \`scriptonia plan "${issue.slice(0, 60)}${issue.length > 60 ? "…" : ""}"\` → PLAN.md.*`);
+  return L.join("\n");
+}
+
+function readProjectJson(dir) {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, "project.json"), "utf8")); } catch { return null; }
+}
+
+/** Append to the brain's audit trail: logs/<name>.log */
+function appendLog(dir, name, msg) {
+  try {
+    const ldir = path.join(dir, "logs");
+    fs.mkdirSync(ldir, { recursive: true });
+    fs.appendFileSync(path.join(ldir, `${name}.log`), `[${new Date().toISOString()}] INFO  scriptonia.${name} — ${msg}\n`);
+  } catch { /* audit trail is best-effort */ }
+}
+
+function buildRepoMd(scan) {
+  return [
+    `# Repo map — ${scan.name}`,
+    "",
+    `**Stack:** ${scan.stack}`,
+    scan.entryPoints.length ? `**Entry points:** ${scan.entryPoints.join(", ")}` : "",
+    "",
+    "## Tree (depth 3)",
+    "```",
+    scan.tree,
+    "```",
+    "",
+    "*When you name files in a plan, use paths from this tree. Refresh with `scriptonia init --force`.*",
+  ].filter(Boolean).join("\n");
+}
+
+function renderContextFile(c) {
+  const L = [`# ${c.title}`, "", `> **${c.type}** · ${c.segment} · strength ${c.strength}/10 · v${c.version}`, "", c.summary, ""];
+  if (c.sources?.length) { L.push("## Sources"); for (const s of c.sources) L.push(`- \`${s.id.slice(0, 8)}\` ${s.source}${s.ref ? ` — ${s.ref}` : ""}`); L.push(""); }
+  if (c.contradicts?.length) { L.push("## ⚠ Contradicts"); for (const x of c.contradicts) L.push(`- ${x}`); L.push(""); }
+  return L.join("\n");
+}
+
+// ── AGENTS.md injection (every agent reads this) ──────────────
+function injectAgentsMd(cwd) {
+  const file = path.join(cwd, "AGENTS.md");
+  const START = "<!-- scriptonia:start -->";
+  const END = "<!-- scriptonia:end -->";
+  const section = `${START}
+## Scriptonia — product memory
+
+This repo has a product brain (customer signal + prior decisions). Before building
+any user-facing change:
+
+- \`scriptonia plan "<the issue>"\` → writes **PLAN.md** here. Execute PLAN.md
+  exactly; respect its **Non-goals**; cite its \`sources\` ids in your PR.
+- \`scriptonia query "<topic>"\` → JSON: what customers asked for, contradictions,
+  edge cases.
+- If a plan constraint is **UNRESOLVED**, stop and ask the human. If a step
+  conflicts with the code, \`scriptonia comment plan/<slug> "<what you found>"\`
+  and re-read PLAN.md.
+${END}`;
+
+  let existing = "";
+  try { existing = fs.readFileSync(file, "utf8"); } catch {}
+  if (existing.includes(START) && existing.includes(END)) {
+    const next = existing.replace(new RegExp(`${START}[\\s\\S]*?${END}`), section);
+    fs.writeFileSync(file, next);
+  } else if (existing.trim()) {
+    fs.writeFileSync(file, existing.replace(/\s*$/, "") + "\n\n" + section + "\n");
+  } else {
+    fs.writeFileSync(file, "# Agent instructions\n\n" + section + "\n");
+  }
+}
+
+// ── misc ──────────────────────────────────────────────────────
+function slugify(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 60) || "project";
+}
+
+// Resolve symlinks (e.g. macOS /var → /private/var) so repo matching is stable
+// no matter which path the user cd'd through.
+function realPath(p) {
+  try { return fs.realpathSync(p); } catch { return p; }
+}
+
+function firstExisting(cwd, names) {
+  for (const n of names) { const p = path.join(cwd, n); if (fs.existsSync(p)) return p; }
+  return null;
+}
+
+function ask(prompt) {
+  if (!process.stdin.isTTY) return Promise.resolve("");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(prompt, (a) => { rl.close(); resolve(a.trim()); }));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scriptonia",
-  "version": "0.2.0",
-  "description": "Product memory for your coding agent. One command, browser sign-in, your agent reads your customers.",
+  "version": "0.6.0",
+  "description": "Turn customer signal into executable plans your coding agent runs. Issue in, PLAN.md out.",
   "type": "module",
   "bin": {
     "scriptonia": "bin/scriptonia.mjs"