scriptonia 0.5.0 → 0.7.0

package/bin/scriptonia.mjs

@@ -32,7 +32,7 @@ const commands = {
   add, ingest: add, push: add,
   plan, plans, comment,
   query, contexts, link,
-  status, logout, skill: reinstallSkill, mcp,
+  status, credits, logout, skill: reinstallSkill, mcp,
   flow, guide: flow,
   help: async () => usage(),
 };
@@ -132,13 +132,19 @@ async function flow() {
   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}`);
+  const cr = o?.credits;
+  const creditStr = cr && cr.metered !== false ? ` · ${cr.plan} ${cr.used}/${cr.cap} credits` : "";
+  console.log(`  ${C.dim}THE LOOP${C.r}   ${C.dim}${s.total} signals · ${plansN} plans${creditStr}${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`);
+  console.log(`\n  ${C.b}NEXT${C.r}  ${nextStep(s, plansN, recentPlan, repo, C)}`);
+  if (cr && cr.metered !== false && cr.available <= 0) {
+    console.log(`  ${C.w}Out of credits${C.r} ${C.dim}— ${cr.topup}${C.r}`);
+  }
+  console.log("");
 }
 
 function nextStep(s, plansN, recentPlan, repo, C) {
@@ -155,10 +161,11 @@ function nextStep(s, plansN, recentPlan, repo, C) {
 async function add(args) {
   const cfg = activeCreds();
   const flags = parseFlags(args);
-  const files = args.filter((a) => !a.startsWith("--"));
-  if (files.length === 0) {
+  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' +
+      '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 -",
@@ -166,21 +173,30 @@ async function add(args) {
   }
 
   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 file of files) {
+  for (const item of inline ? [items[0]] : items) {
     let body, ref, srcHint;
-    if (file === "-") {
+    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(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 (!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} ${file} (empty)`); continue; }
+    if (!body.trim()) { console.log(`  ${C.w}skip${C.r} ${item} (empty)`); continue; }
 
     const res = await fetch(`${cfg.url}/api/ingest`, {
       method: "POST",
@@ -188,19 +204,60 @@ async function add(args) {
       body: JSON.stringify({
         source: flags.source ?? srcHint,
         body,
-        externalRef: ref,
+        // 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} ${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++; }
+    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. In ~2 min:${C.r} ${C.g}scriptonia contexts${C.r}\n`);
+    console.log(`  ${C.dim}The brain is enriching them now. Then:${C.r} ${C.g}scriptonia plan "<issue>"${C.r}\n`);
   }
 }
 
@@ -288,8 +345,19 @@ async function comment(args) {
       body: JSON.stringify({ slug, body: text, author: flags.as ?? cfg.email }),
     });
     const data = await res.json().catch(() => ({}));
+    if (res.status === 402) failCredits(data);
     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;
   }
@@ -301,6 +369,7 @@ async function comment(args) {
     body: JSON.stringify({ slug: target, body: text, author: flags.as ?? cfg.email }),
   });
   const data = await res.json().catch(() => ({}));
+  if (res.status === 402) failCredits(data);
   if (res.status === 404) fail(`no context "${target}" — see \`scriptonia contexts\``);
   if (!res.ok) fail(`comment failed (${res.status}): ${JSON.stringify(data)}`);
 
@@ -323,6 +392,7 @@ async function query(args) {
     body: JSON.stringify({ query: q, window: flags.window, segment: flags.segment }),
   });
   const data = await res.json();
+  if (res.status === 402) failCredits(data);
   if (!res.ok) fail(`query failed (${res.status}): ${JSON.stringify(data)}`);
 
   const wantJson = flags.json !== undefined || !process.stdout.isTTY;
@@ -351,12 +421,65 @@ async function link(args) {
 async function status() {
   const cfg = loadConfig();
   if (!cfg) { console.log("not logged in — run `scriptonia login`"); return; }
+  const active = activeCreds();
+  const C = colors();
   console.log(`signed in as ${cfg.email}`);
-  console.log(`project      ${cfg.project}`);
+  console.log(`project      ${active.project}`);
+  const c = await fetchCredits(active);
+  if (c && c.metered !== false) {
+    const bar = creditBar(c.used, c.cap, C);
+    console.log(`plan         ${C.b}${c.plan}${C.r}`);
+    console.log(`credits      ${bar} ${c.used}/${c.cap} used · resets ${c.resets_at}`);
+    if (c.available <= 0) console.log(`             ${C.w}out of credits${C.r} — ${c.topup}`);
+    else if (c.available <= Math.max(2, Math.round(c.cap * 0.2))) console.log(`             ${C.dim}running low — ${c.topup}${C.r}`);
+  }
   console.log(`endpoint     ${cfg.url}`);
   console.log(`config       ${CONFIG_PATH}`);
 }
 
+// ── credits ───────────────────────────────────────────────────
+async function credits() {
+  const cfg = activeCreds();
+  const C = colors();
+  const c = await fetchCredits(cfg);
+  if (!c) fail("could not load credits");
+  if (c.metered === false) { console.log(`\n  ${C.dim}This project isn't metered.${C.r}\n`); return; }
+  console.log(`\n  ${C.b}${c.plan.toUpperCase()}${C.r} · ${cfg.project}`);
+  console.log(`  ${creditBar(c.used, c.cap, C)}  ${C.b}${c.available}${C.r} of ${c.cap} credits left ${C.dim}(resets ${c.resets_at})${C.r}`);
+  console.log(`\n  ${C.dim}Plans & comments cost 5 · queries 1 · adding signal is free.${C.r}`);
+  if (c.available <= 0) console.log(`  ${C.w}Out of credits.${C.r} ${c.topup}`);
+  else console.log(`  ${C.dim}Need more? ${c.topup}${C.r}`);
+  console.log("");
+}
+
+async function fetchCredits(cfg) {
+  try {
+    const res = await fetch(`${cfg.url}/api/credits`, { headers: { authorization: `Bearer ${cfg.token}` } });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch { return null; }
+}
+
+function creditBar(used, cap, C) {
+  const width = 16;
+  const frac = cap > 0 ? Math.min(1, used / cap) : 0;
+  const filled = Math.round(frac * width);
+  const color = frac >= 1 ? C.w : frac >= 0.8 ? C.w : C.g;
+  return `${color}${"█".repeat(filled)}${C.dim}${"░".repeat(width - filled)}${C.r}`;
+}
+
+/** Render an HTTP 402 credits_exhausted body and exit. Shared by plan/query/comment. */
+function failCredits(data) {
+  const C = colors();
+  const resets = data.resets_at ? ` (resets ${data.resets_at})` : "";
+  console.error(`\n  ${C.w}✕ Out of credits${C.r} — ${data.plan}: ${data.used}/${data.cap} used this month${resets}.\n`);
+  console.error(`    Your signal is safe and still being collected. Plans & queries resume`);
+  console.error(`    when credits do.\n`);
+  console.error(`    ${C.b}Top up:${C.r} ${data.topup}`);
+  console.error(`    ${C.dim}(adding signal, sync, contexts, plans list — all still free)${C.r}\n`);
+  process.exit(1);
+}
+
 async function logout() {
   if (fs.existsSync(CONFIG_PATH)) fs.rmSync(CONFIG_PATH);
   console.log("logged out.");
@@ -560,8 +683,10 @@ function usage() {
     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
+    scriptonia credits            plan, balance, reset date
 
   ACCOUNT   scriptonia status | logout | skill | mcp
+  Plans & comments cost 5 credits · queries 1 · adding signal is free.
 `);
 }
 
@@ -575,10 +700,14 @@ function activeCreds() {
   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: path.join(proj.dir, "brain"), plansDir: path.join(proj.dir, "plans"),
+      dir: proj.dir, brainDir: legacy ? path.join(proj.dir, "brain") : proj.dir,
+      plansDir: path.join(proj.dir, "plans"),
       repoPath: proj.data.repoPath, inited: true,
     };
   }
@@ -643,8 +772,16 @@ async function init(args) {
 
   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 });
+  // 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),
@@ -652,14 +789,18 @@ async function init(args) {
   );
   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.g}✓${C.r} Scanned repo (${scan.stack})  ${C.dim}→ brain/PROJECT.md · brain/REPO.md${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 notes.md`);
+  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`);
 }
 
@@ -676,9 +817,22 @@ async function sync() {
   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}`);
+  // 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) ──────────────────────────────────
@@ -708,6 +862,7 @@ async function plan(args) {
     body: JSON.stringify({ issue, repo_summary: repoSummary }),
   });
   const data = await res.json();
+  if (res.status === 402) failCredits(data);
   if (!res.ok) fail(`plan failed (${res.status}): ${JSON.stringify(data).slice(0, 200)}`);
   writePlan(cfg, data, flags);
 }
@@ -719,11 +874,21 @@ function writePlan(cfg, data, flags) {
   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`);
+  console.log(`  ${C.dim}refine:${C.r} ${C.g}scriptonia comment plan/${data.slug} "…"${C.r} ${C.dim}(rewrites PLAN.md)${C.r}`);
+  if (data.credits) {
+    const cr = data.credits;
+    const low = cr.cap > 0 && cr.cap - cr.used <= Math.max(2, Math.round(cr.cap * 0.2));
+    console.log(`  ${low ? C.w : C.dim}${cr.used}/${cr.cap} credits used this month${low ? " — top up: sathwik07@scriptonia.dev" : ""}${C.r}`);
+  }
+  console.log("");
 }
 
 // ── repo scan ─────────────────────────────────────────────────
@@ -799,26 +964,170 @@ function gitRemoteName(cwd) {
 // ── 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.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);
+    "*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) {
-  fs.mkdirSync(path.join(dir, "brain"), { recursive: true });
-  fs.writeFileSync(path.join(dir, "brain", "REPO.md"), buildRepoMd(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) {
@@ -844,13 +1153,6 @@ function renderContextFile(c) {
   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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scriptonia",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Turn customer signal into executable plans your coding agent runs. Issue in, PLAN.md out.",
   "type": "module",
   "bin": {