scriptonia 0.2.0 → 0.5.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,231 @@ 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 files = args.filter((a) => !a.startsWith("--"));
+  if (files.length === 0) {
+    fail(
+      'usage: scriptonia add <file...>    e.g. scriptonia add slack.txt notes.md call.vtt\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();
+  let created = 0, dup = 0, failed = 0;
+
+  for (const file of files) {
+    let body, ref, srcHint;
+    if (file === "-") {
+      body = fs.readFileSync(0, "utf8"); // stdin
+      ref = null;
+      srcHint = "founder_note";
+    } else {
+      if (!fs.existsSync(file)) { console.log(`  ${C.w}skip${C.r} ${file} (not found)`); failed++; continue; }
+      body = fs.readFileSync(file, "utf8");
+      ref = `upload/${path.basename(file)}`;
+      srcHint = detectSource(file);
+    }
+    if (!body.trim()) { console.log(`  ${C.w}skip${C.r} ${file} (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,
+        externalRef: ref,
+        segment: flags.segment,
+      }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) { console.log(`  ${C.w}fail${C.r} ${file} (${res.status})`); failed++; continue; }
+    if (data.status === "duplicate") { console.log(`  ${C.dim}dup ${C.r} ${file}`); dup++; }
+    else { console.log(`  ${C.g}✓${C.r}   ${file} ${C.dim}→ ${flags.source ?? srcHint}${C.r}`); created++; }
+  }
+
+  console.log(`\n  ${created} added${dup ? `, ${dup} already there` : ""}${failed ? `, ${failed} failed` : ""}.`);
+  if (created > 0) {
+    console.log(`  ${C.dim}The brain is enriching them now. In ~2 min:${C.r} ${C.g}scriptonia contexts${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)}`);
+    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 +334,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 +381,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 +413,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 +495,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 +536,371 @@ 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
+
+  SETUP
+    scriptonia login              sign in (browser) — wires your agent, no keys
+    scriptonia init               [per repo] give this repo its own brain + AGENTS.md
+
+  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
+`);
+}
 
-  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)
+// ═════════════════════════════════════════════════════════════
+// 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) {
+    return {
+      url: g.url, email: g.email,
+      token: proj.data.token, project: proj.data.name, projectId: proj.data.projectId,
+      dir: proj.dir, brainDir: path.join(proj.dir, "brain"), 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 };
+}
 
-  login flags: --dev --email you@co.com   (local testing; skips Google)
-  query flags: --window 30d --segment enterprise --json
-`);
+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  > `));
+
+  fs.mkdirSync(path.join(dir, "brain", "contexts"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "plans"), { recursive: 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);
+  injectAgentsMd(cwd);
+  installSkill();
+
+  console.log(`\n  ${C.g}✓${C.r} Brain created for ${C.b}${name}${C.r}  ${C.dim}→ ${dir}${C.r}`);
+  console.log(`  ${C.g}✓${C.r} Scanned repo (${scan.stack})  ${C.dim}→ brain/PROJECT.md · brain/REPO.md${C.r}`);
+  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 notes.md`);
+  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));
+  fs.writeFileSync(path.join(cfg.brainDir, "DECISIONS.md"), renderDecisions(brain.decisions));
+
+  console.log(`  ${C.g}✓${C.r} synced ${brain.contexts.length} context(s), ${brain.decisions.length} decision(s) → ${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);
+  }
+  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 = [
+    `# ${scan.name}`,
+    "",
+    pitch ? `> ${pitch}` : (scan.pkgDescription ? `> ${scan.pkgDescription}` : "> (describe this product with `scriptonia init --force`)"),
+    "",
+    `**Stack:** ${scan.stack}`,
+    scan.scripts.length ? `**Scripts:** ${scan.scripts.join(", ")}` : "",
+    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 : "",
+    "",
+    "---",
+    "*This is the product brain. Customer signal, contexts, and decisions live alongside this file. Generated by `scriptonia init`.*",
+  ].filter((l) => l !== "").join("\n");
+  fs.writeFileSync(path.join(dir, "brain", "PROJECT.md"), md);
+}
+
+function writeRepoMd(dir, scan) {
+  fs.mkdirSync(path.join(dir, "brain"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "brain", "REPO.md"), buildRepoMd(scan));
+}
+
+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");
+}
+
+function renderDecisions(decs) {
+  if (!decs?.length) return "# Decisions\n\n(none on record)\n";
+  const L = ["# Decisions", "", "*The contradiction corpus — plans are checked against these.*", ""];
+  for (const d of decs) L.push(`## ${d.title}${d.ref ? ` (${d.ref})` : ""}`, "", d.body, "");
+  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.5.0",
+  "description": "Turn customer signal into executable plans your coding agent runs. Issue in, PLAN.md out.",
   "type": "module",
   "bin": {
     "scriptonia": "bin/scriptonia.mjs"