futura-scion 0.2.0 → 0.2.2

package/README.md

@@ -53,6 +53,63 @@ scion run "fix var in src/legacy.js" --intent fix    # fix + gate-verify + certi
 scion brain --all          # fleet-brain memory inventory
 ```
 
+## The brief organ — context in, verified contract out
+
+FS's rungs act on commands, but real work arrives as CONTEXT — tickets,
+specs, conversations. The brief organ (`scion brief`, `docs/brief.md`)
+ingests a context document and produces a structured problem model:
+entities, business rules (`MUST`/`never` sentences), acceptance criteria
+(Gherkin `Given/When/Then`, bullets). Each requirement is classified
+**checkable** (compiles to a Gate verifier command — the same oracle that
+judges code judges the business rules) or **judgment** (kept visible for
+the clarify/review loop, never dropped). A failing requirement **vetoes
+completeness**, so FS cannot declare work done while the contract is
+broken.
+
+## Temporal memory: forgetting, supersession, semantic recall (cortex lineage)
+
+The brain never grows stale or noisy — two deterministic organs (ported from
+agentic-cortex, LLM-free throughout) keep it sharp:
+
+- **Temporal expiry** — a memory whose text carries a deadline (`2026-12-25`,
+  `in 3 days`, `tomorrow`, or an explicit `ttlDays`) gets that lifespan on
+  save; `scion brain --sweep` soft-deletes everything whose time has passed.
+- **Supersession** — saving a statement-like fact with a near-identical title
+  (`deploy is Monday` over `deploy is Friday`) marks the old fact
+  `superseded_by` the new one and excludes it from retrieval. Gate-verified
+  memories are append-only evidence and never auto-supersede.
+- **Semantic recall** — every memory carries a deterministic 512-dim
+  hashed-feature vector (no model, no download, byte-identical on every
+  machine). Hybrid search blends FTS keyword rank with vector similarity;
+  when FTS cannot match at all (morphological near-misses like `pools
+  exhausting` vs `pool exhaustion`), retrieval falls back to vector-only.
+  `scion brain` reports the forgetting ledger (`superseded` / `expired`).
+
+## FS Desktop (the UI)
+
+The web UI ships inside the npm package — one command after install:
+
+```bash
+scion ui                   # boots the kernel + opens FS Desktop in the browser
+# or: scion serve, then open http://127.0.0.1:5107/ui
+```
+
+### Windows installer (two-tier)
+
+A native Windows app is also built from this repo:
+
+```bash
+cd desktop && npm install && npm run dist   # → dist-desktop/FS-Desktop-Setup-<ver>.exe
+```
+
+The shell is a thin Electron host (~78 MB installer) that **detects the npm kernel at
+launch**: if `futura-scion` is installed globally (or `SCION_BIN` is set) it spawns
+`scion serve` itself and opens the UI window; otherwise it shows a guided setup screen
+with the one-line install command and a Retry button. The kernel always runs under the
+user's own Node — updates flow through `npm update -g futura-scion` without
+re-installing the shell. Silent install: `FS-Desktop-Setup-<ver>.exe /S`.
+
+
 `better-sqlite3` ships prebuilt binaries for common platforms (Linux/macOS/Windows,
 x64/arm64); exotic platforms need build tools. FS keeps its brain per project
 (`.scion/`), reads config from `config/scion.config.yaml` (or shipped defaults),
@@ -617,6 +674,154 @@ default) keeps it fully inert even for tasks that opt in with
 `payload.generate: true`. The doctrine is unchanged — the LLM proposes,
 the Gate disposes, the certificate proves it.
 
+### Self-improvement — the harness evolves under its own Gate (`scion evolve`)
+
+FS applies its verification doctrine to ITSELF. The nightly evolution loop
+(imp_doc adoption, zero-LLM) is: **mine → propose → gate → apply**.
+
+- **Weakness miner** — failures from the queue and trail are normalized to
+  signature hashes (`failureSignatureOf`); a signature with ≥3 occurrences
+  across ≥2 goal families is a HARNESS weakness (not one goal's bad luck),
+  classified into the 4-layer taxonomy (environment-contract /
+  procedural-skill / action-realization / trajectory-regulation).
+- **Proposals** — deterministic per layer (bounds-field, verifier-recipe,
+  tool-filter-rule, spec-note), hard 20-line diff budget, targets must
+  exist. No LLM anywhere; a generator can be attached later but is still
+  gate-checked.
+- **The harness-edit Gate** — SICA utility scoring
+  (`U = 0.5·passRate + 0.25·(1−cost) + 0.25·(1−time)`) over the replay
+  window: accept only if utility improves AND pass-rate does not regress.
+  Every decision lands in the `harness_edits` audit table; rejected
+  edit-hashes are remembered (never re-proposed); bounded to ≤3 accepted
+  edits per batch; addressed signatures skip (idempotent). Gate-passing but
+  utility-unproven edits ARCHIVE in `harness_variants` for monthly re-scoring
+  (`scion evolve variants`) — population thinking, nothing promising is lost.
+
+```bash
+scion evolve              # one bounded, idempotent batch
+scion evolve --dry-run    # mine + propose only
+scion evolve variants     # re-score the archive (G4)
+```
+
+### Stuck-trajectory watchdog + completeness + grading (the guardrails)
+
+- **Watchdog** (`src/kernel/watchdog.js`) — hash consecutive `(action,
+  state)` pairs; 3 identical → stuck, abort before burning the bounds.
+  Key-order-insensitive, pure, also usable as an audit (`findStuckPoint`).
+- **Completeness** (`src/mind/completeness.js`) — every research bundle now
+  carries a deterministic completeness verdict: entity coverage,
+  subquestion corroboration (stem-folded), source-quality floor. Incomplete
+  results produce gap-targeted `replan_hints` and a bounded replan loop
+  (`verifyWithReplan`, ≤2 replans) — the VMAO orchestration-level check.
+- **Run records + grading** (`scion eval`) — every task appends a portable
+  JSONL run record to `eval/runs.jsonl` (trajectory, cost, outcome); the
+  3-scorer grader (outcome 0.5 / trajectory 0.3 / economy 0.2) emits
+  per-run grades and a trend file. `scion eval regression` gates on
+  per-family pass-rate drops; `scion eval capability` trends pass-rate per
+  difficulty tier.
+
+### Graph-linked memory + interventions (the brain connects and travels)
+
+- **Memory graph** — every save links into `memory_links`:
+  token-overlap → `related` (weight = Jaccard), same family + opposite
+  outcome polarity → `contradicts` (the older side ranks lower —
+  suppression, never deletion), newer-higher-confidence → `supersedes`.
+  Recall does 1-hop expansion (neighbors at ×0.5) and trust ranking:
+  gate-verified memories weigh 1.0, observed 0.95, web 0.7, LLM 0.6.
+- **Interventions** (`scion interventions import [dir]`) — accepted harness
+  edits export as `interventions/<hash>.intervention.yaml` artifacts
+  (signature, layer, edit, evidence, provenance) and import into another
+  FS instance ONLY if that instance's own history shows the same failure
+  signature ≥2 times: no blind cross-pollination. This is the fleet brain's
+  transport format for learned fixes.
+
+### Call-tree context + indexed actions (Jev/LLM-as-code discipline)
+
+- **Call-tree context** (`src/mind/calltree-context.js`) — the generate
+  rung's context is the task's ANCESTOR CHAIN from the trail, each ancestor
+  budget-capped by depth (deeper → less), total ≤4000 chars — replacing
+  flat truncation. Flat inputs stay backward compatible.
+- **Indexed action space** — clarification options render as numbered
+  ACTIONS with executable consequences (`[2] analyze the named file and
+  apply a gate-verified fix`); answering `2` is a complete decision.
+- **Pre-execution revalidation** — tool calls re-check freshness before
+  spawning: file targets that vanished since the decision refuse loudly
+  (`stale decision`) instead of executing into a world that moved.
+
+### The learn → build → improve → repeat layer (`scion learn`)
+
+The mandate: FS must get BETTER at every kind of problem it takes on —
+software, research, finding things — from its own mistakes, without anyone
+remembering to run a command. This layer is the always-on circulatory
+system connecting every learning organ:
+
+- **LEARN** — every task outcome (verified fix, gate failure, escalation,
+  error) is observed automatically by the worker and written as a graded
+  run record. Failures are the raw material; nothing escapes the loop.
+- **BUILD** — repeated verified fixes forge into seeds (precision-floored);
+  clarifications teach the NLU lexicon; interventions export to the fleet.
+- **IMPROVE** — the weakness miner finds recurring failure patterns across
+  ALL domains; the harness gate utility-verifies bounded self-edits; the
+  variant archive re-scores what didn't win yet.
+- **REPEAT** — every cycle is measured into the `learn_cycles` ledger
+  (pass rate, replay hit rate, deterministic share, seeds, edits accepted);
+  improvement is a TREND over rows, never a claim.
+
+```bash
+scion learn            # one full cycle now
+scion learn trend      # is FS improving? (ledger-backed, ≥2 cycles)
+scion learn vitals     # current vital signs
+```
+
+With `learn: { auto: true }` in config, `scion serve` runs a cycle every
+`learn.interval_ms` (default 6h) in-process — the harness improves itself
+while it works. Zero-LLM by construction.
+
+### FS Desktop — the standalone UI (chat / agent / plan / architect)
+
+FS ships a real UI in two forms, both zero-build:
+
+- **Web console (ships in the npm package):** `scion serve` now serves the
+  FS Desktop SPA at `http://127.0.0.1:5107/ui` — open it in any browser.
+  Nothing extra to install; works over SSH tunnels and on remote machines.
+- **Electron desktop shell (`desktop/`):** a thin host that boots the kernel
+  as a child process and renders the same UI in a native window.
+  ```bash
+  npm run desktop        # dev (needs: cd desktop && npm install)
+  npm run desktop:build  # installers (NSIS / DMG / AppImage) via electron-builder
+  ```
+
+**Surfaces** (every action goes through the same kernel routes the CLI and
+MCP use — the UI can never do more than the kernel allows):
+
+- **Chat with streaming + history** — replies stream over SSE with live
+  NLU/agent progress events; every conversation persists in the brain with a
+  sidebar (new / open / rename / delete), auto-titling, and secret redaction
+  at write time — history survives restarts and travels with the DB.
+- **Chat mode** — plain language in, state-grounded answers out: status,
+  brain/economy/queue lookups, brain search. Deterministic NLU; no LLM.
+- **Agent mode** — real work: your utterance is NLU-interpreted, slotted,
+  enqueued, and run through the full ladder→Gate pipeline with a rung+
+  certificate summary in the transcript.
+- **Plan mode** — research with tools + the deterministic completeness
+  verdict (entity coverage, corroboration, source floor) as evidence.
+- **Architect mode** — one-click declared-architecture scan with violations.
+- **Review queue** — the human gate in the loop: escalations with the
+  ladder's last proposal, Approve/Reject/Defer, badge counts live.
+- **Trail / Brain / Economy dashboards** — the journaled decision trail,
+  brain stats, and the token-economy report as live views.
+- **Autonomy toggle** — semi-autonomous (default: each agent action asks
+  through the Gate + Review flow) vs autonomous (apply directly; the Gate
+  still verifies everything, destructive work still escalates).
+
+**LLM attach (optional):** Settings → Provider covers Ollama, LM Studio,
+OpenAI, Anthropic, OpenRouter, and any OpenAI-compatible endpoint, with a
+connection test. Saving sets `llm.provider/baseUrl/model/apiKey` +
+`llm.daily_tokens` in config, which arms rung G (the governance-shell
+generator): the model PROPOSES patches, the Gate verifies them by exit code,
+and nothing unverified is learned or shipped. `daily_tokens: 0` keeps FS
+fully deterministic — a local model (Ollama/LM Studio) works offline.
+
 ### Semi-autonomous auto-fix (`scion watch` + `daemon.auto_fix`)
 
 By default the daemon only **detects and remembers**. With `daemon.auto_fix: true`

package/bin/scion.js

@@ -16,8 +16,10 @@
 'use strict';
 
 import { createInterface } from 'node:readline';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import * as trail from '../src/kernel/trail.js';
 import {
   enqueue, runSwarm, economy, trailList, runTask, claim as claimTask,
@@ -90,7 +92,7 @@ async function oneShot(text, opts = {}, depth = 0) {
   // persisted scopes (brain config). interpret() strips the @tokens itself.
   const projectScopes = opts.noProjectScopes ? [] : getProjectScopes();
   const mergedScopes = resolveScopes(text, { flag: opts.scope ?? null, projectScopes });
-  const interp = interpret(text, { existsSync: (p) => existsSync(p), intentOverride: opts.intentOverride, scopes: mergedScopes.length ? mergedScopes : undefined });
+  let interp = interpret(text, { existsSync: (p) => existsSync(p), intentOverride: opts.intentOverride, scopes: mergedScopes.length ? mergedScopes : undefined });
   trail.journal('nlu.interpret', {
     utterance: String(text).slice(0, 200),
     intent: interp.intent,
@@ -102,6 +104,26 @@ async function oneShot(text, opts = {}, depth = 0) {
     override: opts.intentOverride ?? null,
   });
 
+  // Tier 3 — the System-1 language-parse rung: ONLY when the deterministic
+  // interpreter found no evidence at all, and an llm provider is configured
+  // AND budgeted (daily_tokens > 0 — off by default). The model parses the
+  // utterance into intent JSON; the SAME schema check validates it; an
+  // abstention falls through to the clarify loop. Never a guess.
+  if (interp.intentEvidence.length === 0 && interp.confidence === 0 && !interp.question && !opts.intentOverride) {
+    const cfg = loadConfig();
+    if (cfg.llm?.daily_tokens > 0 && cfg.llm?.baseUrl && cfg.llm?.model) {
+      const { llmInterpret } = await import('../src/mind/nlu.js');
+      const parsed = await llmInterpret(text, { llmCfg: cfg.llm });
+      trail.journal('nlu.llm-parse', {
+        utterance: String(text).slice(0, 200),
+        accepted: !!parsed,
+        intent: parsed?.intent ?? null,
+        confidence: parsed?.confidence ?? null,
+      });
+      if (parsed) interp = parsed;
+    }
+  }
+
   // Route pure service intents to their kernel surface — a question about
   // state should not become a queue task.
   if (interp.intent === 'show') {
@@ -158,7 +180,7 @@ async function oneShot(text, opts = {}, depth = 0) {
         // Unresolved answer: fall through and surface the question.
       }
     }
-    return { ok: false, intent: 'clarify', prompt: cl.prompt, options: cl.options, open: cl.open, gap_id: gap.id };
+    return { ok: false, intent: 'clarify', prompt: cl.prompt, options: cl.options, open: cl.open, gap_id: gap.id, lang_notice: interp.lang_notice ?? null };
   }
 
   // Ordinary task — enriched with extracted slots.
@@ -310,17 +332,130 @@ switch (cmd || '') {
     const db = getDb();
     const scope = restArgs[0] === '--all' ? 'all'
       : restArgs[0] === '--project' ? resolve(restArgs[1] || '.').replace(/\\/g, '/') : null;
+    // Temporal forgetting (cortex lineage): --sweep expires every memory
+    // whose lifespan has passed; --sweep --dry-run previews it.
+    if (arg === '--sweep' || restArgs.includes('--sweep')) {
+      const { sweepExpires } = await import('../src/brain/forgetting.js');
+      console.log(JSON.stringify(sweepExpires({ dryRun: arg === '--dry-run' || restArgs.includes('--dry-run') }), null, 2));
+      break;
+    }
     const perProject = db.prepare(
       'SELECT project, COUNT(*) as memories, SUM(is_active) as active FROM memories GROUP BY project ORDER BY memories DESC'
     ).all();
+    const forgetting = db.prepare(
+      `SELECT SUM(CASE WHEN is_active = 0 AND superseded_by IS NOT NULL THEN 1 ELSE 0 END) as superseded,
+              SUM(CASE WHEN is_active = 0 AND expires_at IS NOT NULL THEN 1 ELSE 0 END) as expired,
+              SUM(CASE WHEN is_active = 1 AND expires_at IS NOT NULL THEN 1 ELSE 0 END) as expiring_future
+       FROM memories`
+    ).get();
+    // Claims (YOINK lineage): open bets, settled record, the overconfidence
+    // gap, the Brier score, and the dead-memory census.
+    const { calibration, deadMemories } = await import('../src/mind/claims.js');
+    const claims = db.prepare(
+      'SELECT COUNT(*) as total, SUM(CASE WHEN outcome IS NULL THEN 1 ELSE 0 END) as open, SUM(CASE WHEN outcome IS NOT NULL THEN 1 ELSE 0 END) as settled FROM claims'
+    ).get();
     console.log(JSON.stringify({
       ...brainStats(),
       ...(scope ? { scope } : {}),
       projects: perProject,
+      forgetting,
+      claims: { ...claims, record: calibration() },
+      dead_memories: deadMemories().length,
       replay_conflicts: listConflicts(20),
     }, null, 2));
     break;
   }
+  case 'brief': {
+    // The problem-understanding stage: ingest a context document (file or
+    // inline text), compile its requirements to Gate checks, optionally
+    // verify now. scion brief <file> [--verify] | scion brief show <id>
+    const briefs = await import('../src/mind/brief.js');
+    if (arg === 'show') {
+      try { console.log(JSON.stringify(briefs.getBrief(Number(restArgs[0])), null, 2)); }
+      catch (e) { console.error('✗ ' + e.message); process.exitCode = 1; }
+      break;
+    }
+    if (arg === 'list') {
+      console.log(JSON.stringify(briefs.listBriefs(), null, 2));
+      break;
+    }
+    try {
+      const { readFileSync } = await import('node:fs');
+      const text = arg && arg !== '-' && existsSync(arg) ? readFileSync(arg, 'utf8') : (arg || '');
+      if (!text.trim()) { console.error('✗ brief: provide a file path or inline text'); process.exitCode = 1; break; }
+      const b = briefs.ingest({ text, title: restArgs.find(x => !x.startsWith('--')), source: 'cli' });
+      const c = briefs.compileBrief(b.brief.id);
+      const out = { brief: b.brief, entities: b.entities.length, requirements: b.requirements.length, compiled: c.compiled, judgment: c.judgment };
+      if (process.argv.includes('--verify')) {
+        const v = await briefs.verifyBrief(b.brief.id);
+        out.verification = { passed: v.passed, failed: v.failed, coverage: v.coverage, uncheckable: v.uncheckable };
+        out.results = v.results;
+      }
+      console.log(JSON.stringify(out, null, 2));
+    } catch (e) { console.error('✗ ' + e.message); process.exitCode = 1; }
+    break;
+  }
+  case 'lang': {
+    // The multilingual layer: list configured languages, or set the active
+    // one (persisted per brain, like project scopes).
+    const langs = await import('../src/mind/langs.js');
+    if (!arg || arg === 'list') {
+      const packs = langs.loadPacks();
+      console.log(JSON.stringify({
+        active: langs.activeLanguage(),
+        languages: ['en', ...langs.configuredLanguages()],
+        packs: Object.values(packs).map(p => ({ lang: p.lang, name: p.name, script: p.script, entries: p.entries.length })),
+      }, null, 2));
+    } else if (arg === 'set') {
+      try { console.log(JSON.stringify(langs.setActiveLanguage(restArgs[0]), null, 2)); }
+      catch (e) { console.error('✗ ' + e.message); process.exitCode = 1; }
+    } else {
+      try { console.log(JSON.stringify(langs.setActiveLanguage(arg), null, 2)); }
+      catch (e) { console.error('✗ ' + e.message); process.exitCode = 1; }
+    }
+    break;
+  }
+  case 'claim': {
+    // YOINK lineage: turn a memory into a bet with a date on it.
+    // scion claim <memoryId> --claim "..." --settles 2027-01-01 --reads file:...#json.path --test "gte 10" --confidence 0.7
+    const { declare } = await import('../src/mind/claims.js');
+    const flag = (name) => {
+      const i = restArgs.indexOf('--' + name);
+      return i >= 0 ? restArgs[i + 1] : undefined;
+    };
+    try {
+      const r = declare({
+        memoryId: Number(arg),
+        claim: flag('claim'),
+        settles: flag('settles'),
+        reads: flag('reads'),
+        test: flag('test'),
+        confidence: Number(flag('confidence')),
+      });
+      console.log(JSON.stringify(r, null, 2));
+    } catch (e) {
+      console.error('✗ ' + e.message); process.exitCode = 1;
+    }
+    break;
+  }
+  case 'settle': {
+    // Settle everything due: read the sources, apply the tests, write the
+    // outcomes back beside the thoughts. Unreadable sources stay open.
+    const { settleAll } = await import('../src/mind/claims.js');
+    const r = await settleAll();
+    console.log(JSON.stringify(r, null, 2));
+    break;
+  }
+  case 'calibrate': {
+    // The record: said vs right — the gap and the Brier score.
+    const { calibration, deadMemories } = await import('../src/mind/claims.js');
+    console.log(JSON.stringify({
+      record: calibration(),
+      dead: deadMemories({ minAgeDays: Number(restArgs[0]) || 14 }),
+      trail_chain: (await import('../src/kernel/trail.js')).verifyChain(),
+    }, null, 2));
+    break;
+  }
   case 'conflicts': {
     const { listConflicts, clearConflicts } = await import('../src/mind/replay.js');
     if (arg === '--clear') {
@@ -441,6 +576,54 @@ switch (cmd || '') {
     console.log(JSON.stringify({ dry_run: dryRun, ...result }, null, 2));
     break;
   }
+  case 'eval': {
+    // Portable run records + grading (workstream F):
+    //   scion eval regression   per-family pass-rate drop check (gate-able)
+    //   scion eval capability   pass-rate per difficulty tier (trend only)
+    const { regressionCheck, capabilityReport } = await import('../src/mind/grade.js');
+    if (arg === 'capability') console.log(JSON.stringify(capabilityReport(), null, 2));
+    else console.log(JSON.stringify(regressionCheck(), null, 2));
+    const reg = regressionCheck();
+    if (arg !== 'capability' && Object.values(reg).some(f => f.ok === false)) process.exitCode = 1;
+    break;
+  }
+  case 'interventions': {
+    // Shared failure-intervention library (workstream E):
+    //   scion interventions import [dir]   import artifacts with the local-occurrence floor
+    const { importInterventions } = await import('../src/mind/interventions.js');
+    const dir = arg && arg !== 'import' ? arg : 'interventions';
+    console.log(JSON.stringify(importInterventions(dir), null, 2));
+    break;
+  }
+  case 'learn': {
+    // THE learn → build → improve → repeat layer:
+    //   scion learn            one full cycle (mine → gate → forge → rescore → ledger)
+    //   scion learn trend      is FS improving? (ledger-backed, ≥2 cycles)
+    //   scion learn vitals     the current vital signs
+    const loop = await import('../src/mind/learn-loop.js');
+    if (arg === 'trend') console.log(JSON.stringify(loop.trend(), null, 2));
+    else if (arg === 'vitals') console.log(JSON.stringify(loop.vitals(), null, 2));
+    else console.log(JSON.stringify(loop.cycle(), null, 2));
+    break;
+  }
+  case 'evolve': {
+    // The nightly harness-evolution pass (A4): mine weaknesses → propose
+    // harness edits → gate them (SICA utility) → apply the accepted. Bounded
+    // (≤3 accepted per batch), idempotent (addressed signatures skip),
+    // zero-LLM. `scion evolve --dry-run` mines+proposes but applies nothing.
+    //   scion evolve              one bounded batch
+    //   scion evolve --dry-run    mine + propose only
+    //   scion evolve variants     re-score archived harness variants (G4)
+    const hGate = await import('../src/mind/harness-gate.js');
+    if (arg === 'variants') {
+      console.log(JSON.stringify(hGate.rescoreVariants({}), null, 2));
+      break;
+    }
+    const dryRun = arg === '--dry-run';
+    const result = hGate.evolveBatch(dryRun ? { applyAfter: undefined } : {});
+    console.log(JSON.stringify({ dry_run: dryRun, ...result }, null, 2));
+    break;
+  }
   case 'recipes': {
     // The recipe library: gate verifier bundles per stack.
     //   scion recipes             list the library
@@ -565,9 +748,21 @@ switch (cmd || '') {
     //   scion conventions <file>     deviations of one file (evidence rows)
     const c = await import('../src/mind/conventions.js');
     if (arg && !arg.startsWith('--')) {
-      const { readFileSync } = await import('node:fs');
-      const source = readFileSync(arg, 'utf8');
-      console.log(JSON.stringify({ file: arg, deviations: c.deviationsFor(source) }, null, 2));
+      const { readFileSync, statSync } = await import('node:fs');
+      let st = null;
+      try { st = statSync(arg); } catch { /* handled below */ }
+      if (st?.isDirectory()) {
+        // A directory argument means: discover + persist over that tree.
+        const result = c.discoverConventions(arg);
+        c.saveConventions(result);
+        console.log(JSON.stringify({ ok: true, files: result.files, conventions: result.conventions }, null, 2));
+      } else if (st?.isFile()) {
+        const source = readFileSync(arg, 'utf8');
+        console.log(JSON.stringify({ file: arg, deviations: c.deviationsFor(source) }, null, 2));
+      } else {
+        console.error(`conventions: no such file or directory: ${arg}`);
+        process.exitCode = 1;
+      }
     } else {
       const result = c.discoverConventions(arg && arg !== '--all' ? arg : 'src');
       c.saveConventions(result);
@@ -641,13 +836,37 @@ switch (cmd || '') {
     });
     const api = await startApi({ port: Number(arg) || undefined, leader });
     leader.start();
+    // FS Desktop support: provider-backed generator (rung G) from config,
+    // and the default agent-mode runTask over the real oracle.
+    const { makeGenerator } = await import('../src/mind/provider.js');
+    const { configureLlm } = await import('../src/ladder.js');
+    const generator = makeGenerator(cfg.llm);
+    configureLlm({ generator, daily_tokens: cfg.llm?.daily_tokens ?? 0 });
+    const { setRunTask } = await import('../src/http.js');
+    setRunTask(async (task) => runTask(claimTask('ui', task.id), oracle));
+    // The always-on learn→build→improve→repeat layer (config learn.auto).
+    if (cfg.learn?.auto) {
+      const { startAuto } = await import('../src/mind/learn-loop.js');
+      startAuto();
+      console.log(`  learn-loop: auto-cycle every ${Math.round((cfg.learn.interval_ms ?? 21600000) / 60000)} min`);
+    }
     // Observability (env-gated): OTLP log export + ntfy push.
     const { startObservers } = await import('../src/kernel/observe.js');
     startObservers();
     console.log(`scion serve: http://127.0.0.1:${api.port} role=${leader.role}${leader.primaryUrl ? ` primary=${leader.primaryUrl}` : ''} (SCION_TOKEN guards routes when set)`);
-    console.log('  flags: --follower --lease-ms N --leader-poll-ms N --primary-url URL');
+    console.log(`  UI:      http://127.0.0.1:${api.port}/ui   ← FS Desktop (chat, agent, dashboards)`);
+    console.log('  flags: --follower --lease-ms N --leader-poll-ms N --primary-url URL [--open]');
+    // --open: launch the default browser at the UI (best-effort, every OS).
+    if (process.argv.includes('--open')) {
+      const { spawn } = await import('node:child_process');
+      const url = `http://127.0.0.1:${api.port}/ui`;
+      const opener = process.platform === 'win32' ? spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' })
+        : process.platform === 'darwin' ? spawn('open', [url], { detached: true, stdio: 'ignore' })
+        : spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
+      opener.unref();
+    }
     const sweep = setInterval(() => {
-      try { dailyMaintenance(); } catch { /* maintenance never kills the server */ }
+      dailyMaintenance().catch(() => { /* maintenance never kills the server */ });
     }, 60_000);
     for (const sig of ['SIGINT', 'SIGTERM']) {
       process.on(sig, async () => {
@@ -659,6 +878,16 @@ switch (cmd || '') {
     }
     break;
   }
+  case 'ui': {
+    // `scion ui` — the one-command desktop experience: serve + open the UI.
+    // Identical to `scion serve --open`; a separate word because that's what
+    // people type after `npm i -g futura-scion`.
+    const self = process.argv[1];
+    const rest = process.argv.slice(2).filter(a => a !== 'ui');
+    const r = spawnSync(process.execPath, [self, 'serve', ...rest, '--open'], { stdio: 'inherit', env: process.env });
+    process.exitCode = r.status ?? 0;
+    break;
+  }
   case 'remote': {
     // Distributed tier: drain a remote scion's queue from THIS machine.
     //   scion remote --url http://host:5107 --workerId rw-1 [--max N] [--token T]
@@ -687,9 +916,13 @@ switch (cmd || '') {
   }
   case 'dash': {
     // Live TUI dashboard — one ANSI refresh loop over kernel state.
+    // `scion dash <frames> <intervalMs>` runs N frames then exits (CI/trial
+    // friendly); bare `scion dash` loops until Ctrl+C as before.
     const { runDashboard } = await import('../src/kernel/dash.js');
-    const intervalMs = Number(restArgs.find(a => /^\d+$/.test(a))) || 2000;
-    await runDashboard({ intervalMs });
+    const nums = [arg, ...restArgs].filter(a => /^\d+$/.test(a)).map(Number);
+    const frames = nums[0] ?? null;
+    const intervalMs = nums[1] ?? 2000;
+    await runDashboard({ intervalMs, ...(frames ? { maxFrames: frames } : {}) });
     break;
   }
   case 'mcp': {
@@ -777,7 +1010,16 @@ switch (cmd || '') {
     }
     break;
   }
+  case '--version':
+  case '-v': {
+    // Self-reported version — the FS Desktop shell probes this to detect the
+    // kernel and warn on shell/kernel version skew.
+    let kernelPkg = { version: 'dev' };
+    try { kernelPkg = JSON.parse(readFileSync(resolve(fileURLToPath(import.meta.url), '../../package.json'), 'utf8')); } catch { /* dev checkout without package.json */ }
+    console.log(kernelPkg.version);
+    break;
+  }
   default:
-    console.error(`unknown command: ${cmd}\nusage: scion [run "<task>" | swarm [n] | plan <target> [--out m.json] [--run] | workflow <manifest.json> | analyze [dir] | fix <file> | watch [dir] [--auto-fix] [--concurrency N] | economy | brain | remember "<c>" | search "<q>" | reason "<topic>" | forge [--dry-run] | review [-i] | resolve <id> approve "<fix>"|reject|defer | gaps [teach <id> <intent> | forget <id> | --all] | scopes [list|add <name>|rm <name>] | serve [port] [--follower --lease-ms N --leader-poll-ms N --primary-url URL] | remote --url URL --workerId ID | leader | recipes [doctor | show <name>]`);
+    console.error(`unknown command: ${cmd}\nusage: scion [run "<task>" | swarm [n] | plan <target> [--out m.json] [--run] | workflow <manifest.json> | analyze [dir] | fix <file> | watch [dir] [--auto-fix] [--concurrency N] | economy | brain | remember "<c>" | search "<q>" | reason "<topic>" | forge [--dry-run] | review [-i] | resolve <id> approve "<fix>"|reject|defer | gaps [teach <id> <intent> | forget <id> | --all] | scopes [list|add <name>|rm <name>] | ui | serve [port] [--follower --lease-ms N --leader-poll-ms N --primary-url URL] | remote --url URL --workerId ID | leader | recipes [doctor | show <name>]`);
     process.exitCode = 1;
 }