futura-scion 0.2.3 → 0.2.5

package/bin/scion.js

@@ -791,6 +791,134 @@ switch (cmd || '') {
     console.log(JSON.stringify(out, null, 2));
     break;
   }
+  case 'scaffold': {
+    // CONSTRUCTION: compose a template into a project skeleton, gated by
+    // the stack's real verifier recipe before success is reported.
+    const { scaffold, listTemplates, loadTemplate } = await import('../src/mind/scaffold.js');
+    if (!arg || arg === 'list' || arg === '--list') {
+      const tpls = listTemplates();
+      if (tpls.length === 0) { console.log('no templates in templates/ — add YAML manifests'); break; }
+      for (const t of tpls) console.log(`${t.id.padEnd(16)} ${(t.stack ?? '-').toString().padEnd(8)} ${t.description}`);
+      break;
+    }
+    const flags = restArgs.filter((a) => a.startsWith('--'));
+    const positional = restArgs.filter((a) => !a.startsWith('--'));
+    const target = positional[0];   // output directory
+    if (!target) {
+      console.error('usage: scion scaffold <template|fullstack|list> <target-dir> [--name x] [--port N] [--concurrency N] [--no-verify] [--dry-run]');
+      process.exitCode = 2;
+      break;
+    }
+    if (arg === 'fullstack') {
+      // COMPOSABLE CONSTRUCTION: a workflow DAG that scaffolds backend,
+      // frontend, and CLI in parallel, then wires them into one repo.
+      const { planFullstack } = await import('../src/mind/plan-fullstack.js');
+      const params = {};
+      for (const f of flags) {
+        const m = f.match(/^--([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (m) params[m[1]] = m[2];
+      }
+      const manifest = planFullstack(resolve(target), {
+        name: params.name,
+        ...(params.port !== undefined ? { port: Number(params.port) } : {}),
+      });
+      if (flags.includes('--dry-run')) {
+        console.log(`fullstack plan for ${target}:`);
+        for (const t of manifest.tasks) console.log(`  ${t.id.padEnd(20)} deps: ${(t.depends_on ?? []).join(', ') || '(parallel)'}`);
+        console.log('\nrun with --approve-as <reviewer> to construct');
+        break;
+      }
+      const approveIdx = restArgs.indexOf('--approve-as');
+      const reviewer = approveIdx !== -1 ? restArgs[approveIdx + 1] : null;
+      if (!reviewer) {
+        console.error('fullstack construction is a mutating workflow — approve it: --approve-as <reviewer> (or inspect first with --dry-run)');
+        process.exitCode = 2;
+        break;
+      }
+      const { runWorkflow } = await import('../src/kernel/workflow.js');
+      const conc = Number(flags.find((f) => f.startsWith('--concurrency='))?.split('=')[1]) || 3;
+      const r = await runWorkflow(manifest, { concurrency: conc, approval: { reviewer } });
+      console.log(`fullstack ${r.status}: ${r.completed}/${r.total} steps (concurrency ${conc})`);
+      for (const t of r.tasks ?? []) {
+        if (t.status !== 'completed') console.log(`  ${t.status.toUpperCase()}: ${t.manifestId ?? t.id} ${t.error ?? ''}`);
+      }
+      if (r.status !== 'completed') process.exitCode = 1;
+      break;
+    }
+    const tpl = loadTemplate(arg);
+    const params = {};
+    for (const f of flags) {
+      const m = f.match(/^--([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (m) params[m[1]] = m[2];
+    }
+    // Default missing params to sensible template-agnostic values instead
+    // of a raw throw — the CLI user should see WHICH param is missing in a
+    // friendly line, not a stack trace.
+    for (const req of ['name', 'title', 'port', 'description']) {
+      if (!(req in params)) {
+        if (req === 'port') params.port = '3000';
+        else if (req === 'title') params.title = params.name ?? arg;
+        else if (req === 'name') params.name = params.name ?? 'app';
+        else params.description ??= `built with FS scaffold (${arg})`;
+      }
+    }
+    let r;
+    try {
+      r = await scaffold(arg, { params, cwd: resolve(target), verify: !flags.includes('--no-verify') });
+    } catch (err) {
+      console.error(`scaffold failed: ${err.message}`);
+      process.exitCode = 1;
+      break;
+    }
+    if (r.ok === false && r.error) {
+      console.error(`scaffold failed: ${r.error}`);
+      process.exitCode = 1;
+      break;
+    }
+    console.log(`scaffold ${r.template} → ${target}`);
+    for (const f of r.files) console.log(`  + ${f}`);
+    if (r.gate) {
+      console.log(`gate: ${r.gate.verified ? 'VERIFIED' : 'FAILED'} — [${r.gate.evidence.exit_codes.join(',')}]`);
+      if (!r.gate.verified) process.exitCode = 1;
+    } else {
+      console.log('gate: skipped (no stack recipe)');
+    }
+    break;
+  }
+  case 'research': {
+    // The research rung, driven from the CLI (webresearcher lineage):
+    // deterministic-first web research with a completion gate.
+    const q = [arg, ...restArgs.filter((a) => !a.startsWith('--'))].filter(Boolean).join(' ').trim();
+    const flags = restArgs.filter((a) => a.startsWith('--')) || [];
+    const { runResearch } = await import('../src/mind/research/index.js');
+    if (!q) {
+      console.error('usage: scion research "<question>" [--no-persist] [--pages N] [--deep] [--learn]');
+      process.exitCode = 2;
+      break;
+    }
+    const recipe = flags.includes('--deep')
+      ? { id: 'deep-dive', parameters: { max_pages: 16 }, verify: { min_pages: 2, min_items: 5, min_corroborated: 1 } }
+      : undefined;
+    const report = await runResearch(q, {
+      recipe,
+      persist: !flags.includes('--no-persist'),
+      max_pages: Number((flags.find((f) => f.startsWith('--pages')) ?? '').split('=')[1]) || (flags.includes('--pages') ? Number(restArgs[restArgs.indexOf('--pages') + 1]) : undefined) || undefined,
+    });
+    console.log(`research: ${report.pages} pages → ${report.items.length} items ` +
+      `(${report.census.SUPPORTED} corroborated, ${report.census.CONFLICTING} conflicting)`);
+    console.log(`gate: ${report.gate.verdict} — ${report.gate.checks.map((c) => `${c.check}:${c.pass ? 'ok' : 'fail'}(${c.actual})`).join(' ')}`);
+    for (const f of report.summary.KEY_FACT.slice(0, 5)) console.log(`  ✓ ${f.slice(0, 140)}`);
+    for (const c of report.summary.CONTRADICTION.slice(0, 3)) console.log(`  ⚡ ${c.slice(0, 140)}`);
+    for (const e of report.summary.EVIDENCE.slice(0, 3)) console.log(`  · ${e.slice(0, 140)}`);
+    if (report.fallback) console.log(`  [llm-fallback] ${report.fallback.synthesis.slice(0, 200)}`);
+    if (flags.includes('--learn')) {
+      const { learnResearchLoops } = await import('../src/mind/research/loop-learner.js');
+      const learned = learnResearchLoops();
+      console.log(`loop-learner: ${learned.length} lesson(s) persisted`);
+    }
+    process.exitCode = report.gate.verdict === 'PASS' ? 0 : 1;
+    break;
+  }
   case 'conventions': {
     // Measure + persist project conventions (cortex convention-detector
     // lineage, as EVIDENCE): discovered, never enforced.
@@ -884,6 +1012,10 @@ switch (cmd || '') {
       leaseMs, pollMs,
       primaryUrl: followerMode || primaryUrl ? (primaryUrl || null) : null,
     });
+    // Lever 3: the capability tools (web-search, scholar-search, scaffold-*)
+    // register at boot so serve/UI/MCP all share the widened hands.
+    const { registerBuiltinCapabilities } = await import('../src/mind/builtins-register.js');
+    registerBuiltinCapabilities();
     const api = await startApi({ port: Number(arg) || undefined, leader });
     leader.start();
     // FS Desktop support: provider-backed generator (rung G) from config,

package/config/scion.config.yaml

@@ -11,12 +11,8 @@ ladder:
   min_insight_confidence: 0.55  # reasoner rung admission floor
 
 llm:
-  daily_tokens: 500
+  daily_tokens: 0               # 0 = LLM rung off (zero-LLM doctrine)
 
-  apiKey: null
-  model: "qwen2.5-coder:7b"
-  baseUrl: "http://localhost:11434/v1"
-  provider: "ollama"
 bounds:
   max_turns: 25
   timeout_ms: 300000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "The fused scion of cortex-os-agent + persona: one zero-LLM-dependent agent stack — Mind proposes, Muscle executes, Gate disposes.",
   "type": "module",
   "main": "src/index.js",
@@ -13,6 +13,7 @@
     "bin/",
     "src/",
     "recipes/",
+    "templates/",
     "config/",
     "knowledge/",
     "README.md",

package/src/brain/memory.js

@@ -368,6 +368,30 @@ export function list(opts = {}) {
   return rows.map(r => ({ ...r, tags: JSON.parse(r.tags || '[]') }));
 }
 
+/**
+ * reinforce — DEDUP-REINFORCE (webresearcher cortex_bridge lineage): when
+ * new evidence matches an existing memory, STRENGTHEN it instead of
+ * duplicating. Confidence rises by delta (capped at 100), importance to at
+ * least the floor, and the access counter ticks. Repeated corroboration is
+ * a trust signal — the memory-graph weights read it on every recall.
+ * @param {number} id — existing memory id
+ * @param {object} [opts] — { confidence_delta=5, importance_floor=null }
+ * @returns {{ id, confidence, importance, reinforced: true }}
+ */
+export function reinforce(id, opts = {}) {
+  const db = getDb();
+  const row = db.prepare('SELECT confidence, importance FROM memories WHERE id = ?').get(id);
+  if (!row) throw new Error(`memory.reinforce: no memory ${id}`);
+  const delta = opts.confidence_delta ?? 5;
+  const confidence = Math.min(100, row.confidence + delta);
+  const importance = opts.importance_floor != null
+    ? Math.max(row.importance, opts.importance_floor)
+    : Math.min(10, row.importance + (delta >= 5 ? 1 : 0));
+  db.prepare('UPDATE memories SET confidence = ?, importance = ?, access_count = access_count + 1 WHERE id = ?')
+    .run(confidence, importance, id);
+  return { id, confidence, importance, reinforced: true };
+}
+
 export function stats() {
   const db = getDb();
   const row = db.prepare(

package/src/config.js

@@ -59,6 +59,22 @@ function parseScalar(raw) {
   return v.replace(/^['"]|['"]$/g, '');
 }
 
+/**
+ * Strip a block scalar's BASE indentation while preserving relative
+ * indentation (Python code in templates lives or dies by its indents).
+ * The base is the indentation of the FIRST content line; subsequent lines
+ * are dedented by the same amount. `|` literal blocks are exact; `>` folded
+ * blocks joined with spaces downstream, so per-line dedent is harmless.
+ */
+function dedentBlockLine(line, blockScalar) {
+  if (blockScalar.folded) return line.trim();
+  if (blockScalar.baseIndent === undefined) {
+    blockScalar.baseIndent = line.match(/^\s*/)[0].length;
+  }
+  const cut = Math.min(blockScalar.baseIndent, line.match(/^\s*/)[0].length);
+  return line.slice(cut);
+}
+
 /**
  * Minimal YAML-subset parser: nested maps by indentation, scalars, inline
  * arrays, `#` comments. Deliberately NOT full YAML — unsupported syntax
@@ -144,11 +160,23 @@ export function parseYaml(text, source = CONFIG_PATH) {
     if (!match) {
       // Continuation line of a block scalar ("key: >" folded text)?
       if (blockScalar !== null && /^\s+\S/.test(line)) {
-        blockScalar.text.push(line.trim());
+        blockScalar.text.push(dedentBlockLine(line, blockScalar));
         continue;
       }
       throw new Error(`config: ${source}:${lineno} unsupported syntax — ${JSON.stringify(line.trim())}`);
     }
+    // A block scalar is OPEN and this line is deeper-indented than its key:
+    // it is SCALAR TEXT, never a new key — even when it looks like
+    // "word: value" (template manifests embed whole files in block scalars;
+    // their `port: 3000`-shaped lines are content, not structure). Leading
+    // indentation is PRESERVED relative to the block's first content line —
+    // Python files in templates live or die by their indentation.
+    if (blockScalar !== null
+        && match[1].length > (blockScalar.indent ?? 0)
+        && !/^\s*-\s/.test(line)) {
+      blockScalar.text.push(dedentBlockLine(line, blockScalar));
+      continue;
+    }
     const [, ws, key, rest] = match;
     const indent = ws.length;
 

package/src/kernel/safety.js

@@ -86,8 +86,12 @@ export function assertPathAllowed(p) {
     throw new Error('safety: path must be a non-empty string');
   }
   const norm = p.replace(/\\/g, '/');
+  const base = norm.split('/').pop(); // final segment decides secrets, not substrings
   for (const d of denylist()) {
-    if (norm.includes(d)) {
+    // Segment-aware matching: `.env` denies the secrets file itself, not
+    // `.env.example` or `backend-service/` (substring matching blocked the
+    // scaffolded env CONTRACT — a template file, not a secret).
+    if (d === '.env' ? base === '.env' : norm.includes(d)) {
       throw new Error(`safety: path denied by muscle.path_deny ("${d}"): ${p}`);
     }
   }

package/src/kernel/workflow.js

@@ -231,11 +231,35 @@ async function kernelCallable(fn) {
   if (fn === 'ocrImage') {
     return (args) => ocrImage(args?.image, { ...(args?.engine ? { engine: args.engine } : {}) });
   }
+  if (fn === 'scaffold') {
+    return async (args) => {
+      const { scaffold } = await import('../mind/scaffold.js');
+      const r = await scaffold(args?.template, {
+        params: args?.params ?? {},
+        ...(args?.cwd !== undefined ? { cwd: args.cwd } : {}),
+        ...(args?.verify !== undefined ? { verify: args.verify } : {}),
+      });
+      if (!r.ok) throw new Error(r.error ?? `scaffold ${args?.template} failed (gate: ${r.gate?.verified})`);
+      return { template: r.template, files: r.files, gate: r.gate?.verified ?? null };
+    };
+  }
+  if (fn === 'scaffold.file') {
+    // Wiring step: write one glue file through the transactional applier
+    // (snapshot + rollback) with the same path guardrails as any mutation.
+    return async (args) => {
+      const { transactionalApplier } = await import('./apply.js');
+      const tx = transactionalApplier({
+        files: [{ file: args?.file, content: args?.content ?? '', description: args?.description ?? `wire ${args?.file}` }],
+      });
+      const description = tx.apply();
+      return { description, file: args?.file };
+    };
+  }
   return null;
 }
 
 function callableSurface() {
-  return 'boostConsensus, ocrImage';
+  return 'boostConsensus, ocrImage, scaffold, scaffold.file';
 }
 
 async function execShellStep(step) {

package/src/mind/builtins-register.js

@@ -0,0 +1,88 @@
+/**
+ * mind/builtins-register.js — LEVER 3 (tool-calling breadth): registers the
+ * network + construction capabilities as FIRST-CLASS registry tools so the
+ * research rung (`research()`) and the swarm can invoke them by name like
+ * any shell tool. Import once at boot/serve; registration is idempotent.
+ *
+ * These are ASYNC capability tools (functions, not argv templates) — the
+ * registry stores their runner and runTool dispatches to it. Same rails
+ * apply: journaled, redacted, bounded.
+ *
+ * @module mind/builtins-register
+ */
+
+'use strict';
+
+import { registerTool } from './tools.js';
+import { searchWeb } from './research/search.js';
+import { listTemplates, loadTemplate } from './scaffold.js';
+
+let registered = false;
+
+/** Idempotently register the capability tools. */
+export function registerBuiltinCapabilities() {
+  if (registered) return listTemplates();
+  registered = true;
+
+  registerTool({
+    name: 'web-search',
+    description: 'search the web (DuckDuckGo keyless / Tavily keyed); {topic} is the query',
+    tags: ['web', 'research', 'network'],
+    capability: async (opts = {}) => {
+      const r = await searchWeb(opts.topic ?? '', { max_results: opts.max_results ?? 5 });
+      return {
+        ok: r.results.length > 0,
+        stdout: r.results.map((x) => `- ${x.title}\n  ${x.url}\n  ${String(x.snippet ?? '').slice(0, 160)}`).join('\n').slice(0, 8000),
+        meta: { provider: r.provider, count: r.results.length, attempts: r.attempts.length },
+      };
+    },
+  });
+
+  registerTool({
+    name: 'scholar-search',
+    description: 'search scholarship (arXiv/Semantic Scholar/CrossRef); {topic} is the query',
+    tags: ['academic', 'research', 'network'],
+    capability: async (opts = {}) => {
+      const { searchScholar } = await import('./research/academic.js');
+      const papers = await searchScholar(opts.topic ?? '', { max_results: 5 });
+      return {
+        ok: papers.length > 0,
+        stdout: papers.map((p) => `- ${p.title} (${p.year ?? 'n.d.'}, cites: ${p.citation_count ?? '?'})\n  ${p.url}`).join('\n').slice(0, 8000),
+        meta: { count: papers.length },
+      };
+    },
+  });
+
+  registerTool({
+    name: 'scaffold-list',
+    description: 'list constructable project templates (what FS can BUILD)',
+    tags: ['construction'],
+    capability: async () => {
+      const tpls = listTemplates();
+      return {
+        ok: tpls.length > 0,
+        stdout: tpls.map((t) => `${t.id.padEnd(16)} ${(t.stack ?? '-').padEnd(8)} ${t.description}`).join('\n'),
+        meta: { count: tpls.length },
+      };
+    },
+  });
+
+  registerTool({
+    name: 'scaffold-inspect',
+    description: 'show a template manifest (files, post commands, stack) for {topic}=template id',
+    tags: ['construction'],
+    capability: async (opts = {}) => {
+      try {
+        const t = loadTemplate(opts.topic ?? '');
+        return {
+          ok: true,
+          stdout: `${t.name} (stack: ${t.stack ?? 'none'})\n${t.description}\nfiles:\n${t.files.map((f) => `  + ${f.path}`).join('\n')}\npost:\n${(t.post ?? []).map((c) => `  $ ${c}`).join('\n') || '  (none)'}`,
+        };
+      } catch (err) {
+        return { ok: false, error: String(err?.message || err).slice(0, 200) };
+      }
+    },
+  });
+
+  return listTemplates();
+}

package/src/mind/plan-fullstack.js

@@ -0,0 +1,164 @@
+/**
+ * mind/plan-fullstack.js — COMPOSABLE CONSTRUCTION: a fullstack scaffold is
+ * a WORKFLOW DAG (the plan-fix lineage applied to building).
+ *
+ * Wave 1 (parallel): scaffold the backend, the frontend, and the CLI into
+ * their subdirectories — three independent `scaffold` kernel calls.
+ * Wave 2 (wiring, after all of wave 1): generate the cross-component glue
+ * that only makes sense once all three exist:
+ *
+ *   - frontend/src/api.js      — a typed-ish fetch client for the backend
+ *   - README.md                — the repo-level map of all three components
+ *   - .env.example             — shared env contract (PORT for the backend)
+ *
+ * The wiring steps are shell-independent: they are emitted as additional
+ * `scaffold`-adjacent `call` steps writing files through the same
+ * transactional path the Gate judges. Resumability inherits from the
+ * workflow engine: a failed wiring step can be re-driven; completed
+ * scaffolds never re-run.
+ *
+ * @module mind/plan-fullstack
+ */
+
+'use strict';
+
+import * as trail from '../kernel/trail.js';
+
+/**
+ * Generate the fullstack workflow manifest.
+ * @param {string} targetDir — repo root to construct into
+ * @param {object} [opts] — { name?, backend?, frontend?, cli?, port? }
+ *   backend/frontend/cli: { template, params } overrides; defaults build
+ *   node-api + static-web + node-cli.
+ * @returns {object} a workflow manifest ({ name, tasks })
+ */
+export function planFullstack(targetDir, opts = {}) {
+  if (!targetDir || typeof targetDir !== 'string') {
+    throw new Error('planFullstack: targetDir is required');
+  }
+  const name = opts.name ?? targetDir.split(/[\\/]/).pop() ?? 'fullstack-app';
+  const port = String(opts.port ?? 3000);
+  const backend = { template: 'node-api', dir: 'backend', params: { name: `${name}-api`, port }, ...(opts.backend ?? {}) };
+  const frontend = { template: 'static-web', dir: 'frontend', params: { name: `${name}-web`, title: name }, ...(opts.frontend ?? {}) };
+  const cli = { template: 'node-cli', dir: 'cli', params: { name: `${name}-cli` }, ...(opts.cli ?? {}) };
+  const base = String(targetDir).replace(/\\/g, '/').replace(/\/$/, '');
+
+  const tasks = [];
+
+  // ── Wave 1: the three scaffolds, mutually independent → parallel ──
+  tasks.push(
+    { id: 'scaffold-backend', type: 'call', fn: 'scaffold', args: { template: backend.template, params: backend.params, cwd: `${base}/${backend.dir}` } },
+    { id: 'scaffold-frontend', type: 'call', fn: 'scaffold', args: { template: frontend.template, params: frontend.params, cwd: `${base}/${frontend.dir}` } },
+    { id: 'scaffold-cli', type: 'call', fn: 'scaffold', args: { template: cli.template, params: cli.params, cwd: `${base}/${cli.dir}` } },
+  );
+
+  // ── Wave 2: wiring — depends on ALL of wave 1 ──
+  tasks.push(
+    {
+      id: 'wire-frontend-api',
+      type: 'call',
+      fn: 'scaffold.file',
+      args: {
+        file: `${base}/${frontend.dir}/js/api.js`,
+        content: apiClientModule(port),
+        description: 'frontend API client for the backend',
+      },
+      depends_on: ['scaffold-backend', 'scaffold-frontend'],
+    },
+    {
+      id: 'wire-env-contract',
+      type: 'call',
+      fn: 'scaffold.file',
+      args: {
+        file: `${base}/.env.example`,
+        content: envContract(port),
+        description: 'shared env contract',
+      },
+      depends_on: ['scaffold-backend'],
+    },
+    {
+      id: 'wire-root-readme',
+      type: 'call',
+      fn: 'scaffold.file',
+      args: {
+        file: `${base}/README.md`,
+        content: rootReadme(name, { backend, frontend, cli, port }),
+        description: 'repo-level map of the three components',
+      },
+      depends_on: ['scaffold-backend', 'scaffold-frontend', 'scaffold-cli'],
+    },
+  );
+
+  const manifest = {
+    name: `fullstack-${name}`,
+    description: `Fullstack construct: ${backend.template} backend + ${frontend.template} frontend + ${cli.template} CLI, wired into one repo`,
+    tasks,
+  };
+  trail.journal('scaffold.fullstack-plan', { name, target: base, tasks: tasks.length });
+  return manifest;
+}
+
+/** The frontend's generated API client — fetch wrapper over the backend. */
+function apiClientModule(port) {
+  return `/**
+ * api.js — generated by FS fullstack scaffold. The ONLY place the frontend
+ * knows the backend's address; change API_URL here and nowhere else.
+ */
+const API_URL = 'http://localhost:${port}';
+
+async function request(path, opts = {}) {
+  const res = await fetch(\`\${API_URL}\${path}\`, {
+    headers: { 'content-type': 'application/json' },
+    ...opts,
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body.error ?? \`HTTP \${res.status}\`);
+  return body;
+}
+
+export const api = {
+  health: () => request('/health'),
+  listItems: () => request('/items'),
+  addItem: (title) => request('/items', { method: 'POST', body: JSON.stringify({ title }) }),
+};
+`;
+}
+
+/** The shared env contract. */
+function envContract(port) {
+  return `# Generated by FS fullstack scaffold — the env contract shared by all components.
+PORT=${port}
+NODE_ENV=development
+`;
+}
+
+/** The repo-level README. */
+function rootReadme(name, { backend, frontend, cli, port }) {
+  return `# ${name}
+
+Fullstack repo constructed by FS scaffold — three gate-verified components
+wired into one tree. Every file passed the stack's verifier recipe (real
+exit codes) before this run reported success.
+
+## Layout
+
+| Component | Template | Location |
+|---|---|---|
+| Backend API | \`${backend.template}\` | \`${backend.dir}/\` — serves on :${port} |
+| Frontend | \`${frontend.template}\` | \`${frontend.dir}/\` — open \`index.html\` |
+| CLI | \`${cli.template}\` | \`${cli.dir}/\` |
+
+## Run
+
+\`\`\`bash
+cd ${backend.dir} && npm install && npm start   # API on :${port}
+cd ${frontend.dir}                               # open index.html (js/api.js talks to :${port})
+cd ${cli.dir} && npm install && npm test
+\`\`\`
+
+## Contract
+
+- The frontend's \`${frontend.dir}/js/api.js\` is the single seam to the backend.
+- \`.env.example\` is the shared environment contract.
+`;
+}