geneseed 3.4.0 → 3.6.0

package/js/maintain/uninstall.mjs

@@ -47,7 +47,7 @@ import {
 } from 'node:fs';
 import path from 'node:path';
 
-import { hookRunnerEntry } from '../../bin/build-driver.mjs';
+import { hookRunnerEntry } from '../build/driver.mjs';
 import { confirm } from './setup.mjs';
 import {
   claudeCfg, claudeReadManifest, doctrinesOfDir, emitHostScopeOf, excludedRulesOfDir, installKind,
@@ -60,7 +60,7 @@ import {
 import { mcpCommented } from '../hosts/mcp.mjs';
 import {
   copilotIntegrityCheck, managedBlockRead, managedBlockRemove, managedBlockWrite,
-  mergeClaudeSettings, mergeCopilotSettings, opencodeTarget, readJsonc,
+  mergeClaudeSettings, opencodeTarget, readJsonc,
   settingsIntegrityCheck, wireClaudeExcludes, unwireClaudeExcludes, unwireClaudeSettings,
   unwireCopilotSettings,
 } from '../hosts/settings.mjs';
@@ -347,9 +347,8 @@ export function uninstallGlobal(target, archiveMemory, host = 'opencode') {
 /**
  * `_harness_mcp._mcp_load`, reduced to the OpenCode arm.
  *
- * The Claude arm (`.mcp.json`, `~/.claude.json`, parsed with STRICT `json.loads` because the
- * comment stripper's trailing-comma pass is not string-aware) belongs to the MCP catalog and
- * the TUI, and neither has crossed. `installAgentEntry` is this port's only caller and passes
+ * The Claude arm (`.mcp.json`, `~/.claude.json`, parsed STRICTLY — see `mcpLoad` in
+ * js/hosts/mcp.mjs for why) lives with the MCP catalog. `installAgentEntry` is this port's only caller and passes
  * no host, so porting the branch would ship an unreachable arm with no cell and no partition
  * to be part of — the criterion this port decides keep-vs-delete by.
  */
@@ -645,7 +644,7 @@ function printSurvivingProjectInventory(removedRoot) {
 function printOtherHostHits(root, removedHost) {
   for (const spec of HOSTS) {
     if (spec.host !== removedHost && projectQualifies(root, spec.host)) {
-      printOut(`[uninstall] also found ${spec.host}:project here — run \`harness `
+      printOut(`[uninstall] also found ${spec.host}:project here — run \`geneseed `
         + 'uninstall` again to remove it.\n');
     }
   }
@@ -1058,15 +1057,18 @@ function cleanHostStash(cfg, host = 'claude') {
 function remergeClaudeHooks(cfg, root = cfg, host = 'claude') {
   const data = claudeReadManifest(cfg);
   const managed = managedOf(data);
-  // A Copilot install: its own merge, its own claim key, and none of the pack/exclude axes
-  // below — the Copilot gate is not pack-conditional (see `copilotHooks`). Without this
-  // branch a Copilot reactivate would write CLAUDE-shaped hook groups into
-  // ~/.copilot/settings.json, which Copilot cannot read.
+  // A LEGACY Copilot install (single-slot `copilot_hooks`, the dead `toolCall` event):
+  // reactivating it re-wires the CURRENT Copilot shape — event → array, recorded under
+  // `settings_hooks` — rather than restoring hooks Copilot no longer reads. None of the
+  // pack/exclude axes below apply: the Copilot gate is not pack-conditional.
   if (Array.isArray(managed.copilot_hooks)) {
-    const [, claims] = mergeCopilotSettings(settingsFile(cfg, managed), managed.copilot_hooks,
-      hookRunnerEntry());
-    if (!deepEquals(claims, managed.copilot_hooks) && Object.keys(data).length > 0) {
-      managed.copilot_hooks = claims;
+    const sf = settingsFile(cfg, managed);
+    unwireCopilotSettings(sf, managed.copilot_hooks);
+    const [, claims] = mergeClaudeSettings(sf, 'global', null, hookRunnerEntry(), null, [],
+      'copilot', cfg);
+    if (Object.keys(data).length > 0) {
+      delete managed.copilot_hooks;
+      managed.settings_hooks = claims;
       data.managed = managed;
       const tmp = path.join(cfg, `${GLOBAL_MANIFEST}.tmp`);
       try {
@@ -1098,7 +1100,7 @@ function remergeClaudeHooks(cfg, root = cfg, host = 'claude') {
     : excludedRulesOfDir(cfg);
   // `host` reaches the group builder: a Bob reactivate must re-wire Gemini-named groups.
   const [, claims] = mergeClaudeSettings(settingsFile(cfg, managed), 'global',
-    managed.settings_hooks ?? null, hookRunnerEntry(), doctrines, excluded, host);
+    managed.settings_hooks ?? null, hookRunnerEntry(), doctrines, excluded, host, cfg);
   // `and data` — a manifest that did not parse is not one to write back.
   if (!deepEquals(claims, managed.settings_hooks ?? null) && Object.keys(data).length > 0) {
     managed.settings_hooks = claims;

package/js/ui/cli.mjs

@@ -441,6 +441,25 @@ export function cliCommand(verb) {
  * CRLF ON WINDOWS for `die`'s reason: argparse writes through a Python text stream, which
  * translates, and this text lands in the same terminals and the same pipes as that one.
  */
+/**
+ * `geneseed --help` — every verb with its one-line help, from the same table the per-verb help
+ * reads. `verbs` is the entry's own dispatch list, so the listing can name nothing the entry
+ * would refuse; a verb the table does not describe still appears, with no help line.
+ */
+export function printVerbList(prog, verbs, extra = {}) {
+  const helpOf = new Map([...Object.entries(extra),
+    ...cliReference().commands.filter((c) => c.help).map((c) => [c.name, c.help])]);
+  const names = [...verbs].sort();
+  const pad = Math.max(...names.map((n) => n.length)) + 2;
+  const lines = [`usage: ${prog} <command> [options]`, '',
+    `A bare \`${prog}\` runs \`home\`. \`${prog} <command> --help\` describes one command.`, '',
+    'commands:'];
+  for (const n of names) lines.push(`  ${n.padEnd(pad)}${helpOf.get(n) || ''}`.trimEnd());
+  const text = `${lines.join('\n')}\n`;
+  process.stdout.write(process.platform === 'win32' ? text.replaceAll('\n', '\r\n') : text);
+  return 0;
+}
+
 export function printHelp(prog, verb) {
   const cmd = cliCommand(verb);
   if (cmd === null) return null;

package/js/ui/menu.mjs

@@ -45,7 +45,7 @@ import { startDaemon } from '../web/daemon.mjs';
 function menuHelp() {
   printOut('Geneseed — no interactive menu here. Get started with:  geneseed setup\n');
   printOut('Other commands:  bootstrap · update · build · doctor · diff · tui · web\n');
-  printOut('On a VT-capable terminal, a bare `./geneseed` opens the interactive menu of these.\n');
+  printOut('`geneseed --help` lists every command.\n');
   return 0;
 }
 

package/js/web/actions.mjs

@@ -32,7 +32,7 @@ import {
 import os from 'node:os';
 import path from 'node:path';
 
-import { emitGlobalInto } from '../../bin/build-driver.mjs';
+import { emitGlobalInto } from '../build/driver.mjs';
 import {
   ROOT, discoverNames, knownRuleIds, PACK_ORDER,
 } from '../build/source.mjs';
@@ -127,7 +127,7 @@ function bodyExcludeRules(body) {
 const splitWords = (s) => s.split(new RegExp(`[${WHITESPACE}]+`)).filter(Boolean);
 
 /** Today's date, LOCAL (not UTC) — this is a user-facing date, not a wire timestamp. */
-export function todayIso(d = new Date()) {
+function todayIso(d = new Date()) {
   const p2 = (n) => String(n).padStart(2, '0');
   return `${d.getFullYear()}-${p2(d.getMonth() + 1)}-${p2(d.getDate())}`;
 }
@@ -278,13 +278,13 @@ const rulesPath = (state) => path.join(state.target, RULES_FILE);
  * `max(ids) + 1`. Widening this to match would only move the gap one line down, to whatever
  * parses the captured digits back into a number.
  */
-export const RULE_HEAD_RE = new RegExp(
+const RULE_HEAD_RE = new RegExp(
   `^##[${WHITESPACE}]+R(\\d+)[${WHITESPACE}]*[—–-]+[${WHITESPACE}]*`
   + `([^${WHITESPACE}].*?)[${WHITESPACE}]*$`,
 );
 
 /** Advisory only; nothing blocks past it. */
-export const RULES_BUDGET = { max_rules: 15, max_tokens: 1500 };
+const RULES_BUDGET = { max_rules: 15, max_tokens: 1500 };
 
 const META_RE = new RegExp(`^\\((.+)\\)[${WHITESPACE}]*$`);
 

package/js/web/activity.mjs

@@ -48,7 +48,7 @@ import { NotFound, stemOf } from './api.mjs';
  * platform where the probe cannot tell. Generous on purpose: streaming bumps `updated_at`
  * constantly, so only a genuinely abandoned (process-still-alive) session ages out.
  */
-export const ACTIVITY_STALE_SECONDS = 1800;
+const ACTIVITY_STALE_SECONDS = 1800;
 
 const nowSeconds = () => Date.now() / 1000;
 
@@ -66,7 +66,7 @@ const activityFlag = (state) => path.join(state.target, '.geneseed-activity');
  * default every user who has never toggled is in. An undecodable flag file is not treated
  * specially: Node substitutes U+FFFD and reads on rather than raising.
  */
-export function activityEnabled(state) {
+function activityEnabled(state) {
   let raw;
   try {
     raw = readText(activityFlag(state));
@@ -97,7 +97,7 @@ function toIntOr(raw) {
 }
 
 /** Best-effort liveness for the writer process. See this file's header. */
-export function pidAlive(raw) {
+function pidAlive(raw) {
   const pid = toIntOr(raw);
   if (pid === null || pid <= 0) return false;
   try {
@@ -161,7 +161,7 @@ function isLive(entry, now) {
  * missing dir is `[]`, a garbage file is skipped (and kept — only a snapshot that PARSED and
  * failed the liveness test is unlinked), newest first.
  */
-export function activityEntries(state) {
+function activityEntries(state) {
   const d = activityDir(state);
   if (!isDir(d)) return [];
   const now = nowSeconds();

package/js/web/api.mjs

@@ -201,7 +201,7 @@ export function specDesc(fm, body) {
  * plumbing rather than prose, which is what makes a deployed entry the same shape as a
  * source-rendered one and every consumer indifferent to the origin.
  */
-export function specEntries(root, nested) {
+function specEntries(root, nested) {
   const out = [];
   if (!isDir(root)) return out;
   let names;
@@ -238,7 +238,7 @@ export function specEntries(root, nested) {
  * the walk. So the catalogue is always whole, and which packs this INSTALL built in comes from
  * its own carrier via `doctrinesForBuild`, which resolves "no marker" to every pack.
  */
-export function deployedInventory(state) {
+function deployedInventory(state) {
   const render = tuiInventory(state.theme, doctrinesForBuild(state.target),
     excludedRulesOfDir(state.target));
   const registry = loadRegistry();
@@ -259,7 +259,7 @@ export function deployedInventory(state) {
 }
 
 /** The deployed record when there is one, else the source render. */
-export function inventoryFor(state) {
+function inventoryFor(state) {
   return deployed(state) ? deployedInventory(state) : tuiInventory(state.theme);
 }
 
@@ -305,7 +305,7 @@ export function memoryItems(state) {
   });
 }
 
-export function notebookItems(state) {
+function notebookItems(state) {
   const d = notebookDir(state);
   if (!isDir(d)) return [];
   return globMd(d).map((n) => ({
@@ -319,7 +319,7 @@ const CONFIG_META = {
   'wiki.jsonc': ['Wiki manifest', 'your machine-wide knowledge base(s)'],
 };
 
-export function configItems(state) {
+function configItems(state) {
   const out = [];
   for (const fname of ['context.json', 'wiki.jsonc']) {
     const p = path.join(state.target, fname);
@@ -331,7 +331,7 @@ export function configItems(state) {
   return out;
 }
 
-export const WIKI_FILE_CAP = 5000;
+const WIKI_FILE_CAP = 5000;
 
 /**
  * `resolvePath` for a path that came out of a HAND-MAINTAINED manifest — `null`, never a throw.
@@ -419,7 +419,10 @@ export function wikiItems(state) {
     // blank every OTHER vault in it.
     const root = wikiPath(String(dget(w, 'path', null) || ''));
     if (!root || !isDir(root)) continue;
-    const entries = (dget(w, 'entries', null) || [])
+    // A hand-edited `entries` that is not a list (`{}`, a string) is a malformed vault, not a
+    // crash: `/api/status` counts these, and one bad manifest must not fail the dashboard.
+    const rawEntries = dget(w, 'entries', null);
+    const entries = (Array.isArray(rawEntries) ? rawEntries : [])
       .filter((e) => e && typeof e === 'object' && !Array.isArray(e));
     const excludes = entries.filter((e) => dget(e, 'load', null) === 'exclude')
       .map((e) => String(dget(e, 'path', null) || '').replace(/^\/+|\/+$/g, '').replace(/\\/g, '/'));
@@ -450,7 +453,7 @@ export function wikiItems(state) {
 }
 
 /** One page by `<wiki>:<relpath>`, never outside the vault. */
-export function apiWikiItem(state, name) {
+function apiWikiItem(state, name) {
   const at = name.indexOf(':');
   const wname = at < 0 ? name : name.slice(0, at);
   const rel = (at < 0 ? '' : name.slice(at + 1))
@@ -497,7 +500,7 @@ function flatName(name) {
   }
 }
 
-export const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
+const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
 
 /**
  * `[[name]]` matched against known agent and skill names.
@@ -746,9 +749,9 @@ export function apiInstalls(state) {
 
 /** Beside the deployed AGENT.md. */
 export const PROFILE_FILE = 'PROFILE.md';
-export const profilePath = (state) => path.join(state.target, PROFILE_FILE);
+const profilePath = (state) => path.join(state.target, PROFILE_FILE);
 
-export function apiProfile(state) {
+function apiProfile(state) {
   const p = profilePath(state);
   if (!isFile(p)) return { exists: false, path: p, text: '', fingerprint: '' };
   const text = readMaybe(p) ?? '';

package/js/web/daemon.mjs

@@ -83,7 +83,7 @@ export async function probe(url, timeout = 1.5) {
 }
 
 /** The token-carrying POST `geneseed web stop` and the in-page Stop button both send. */
-export async function postShutdown(url, token, timeout = 3.0) {
+async function postShutdown(url, token, timeout = 3.0) {
   try {
     const res = await fetch(`${url}/api/shutdown`, {
       method: 'POST',

package/js/web/docs.mjs

@@ -24,7 +24,7 @@ import { readJsonMaybe, readMaybe } from '../hosts/installs.mjs';
 import { resolvePath } from '../hosts/hosts.mjs';
 import { parseJson } from '../lib/json.mjs';
 import { isFile } from '../lib/fs.mjs';
-import { normcase } from '../lib/paths.mjs';
+import { normcase, within } from '../lib/paths.mjs';
 import { WHITESPACE, stripWhitespace } from '../lib/text.mjs';
 import { statusData } from '../inspect/status.mjs';
 import { originDisplay } from '../maintain/update.mjs';
@@ -39,7 +39,7 @@ const DOC_DIR = path.join(ROOT, 'docs', 'web');
  * covers every key these pages use and parses with the standard library. A value that is
  * not valid JSON is kept as the raw string, which is how `title: Something` works.
  */
-export function docFrontmatter(text) {
+function docFrontmatter(text) {
   const marker = '---\n';
   if (!text.startsWith(marker)) return [{}, text];
   const rest = text.slice(marker.length);
@@ -109,8 +109,13 @@ export function docGroups() {
  */
 const GLOSSARY_KEYS = [
   // The three tiers, in constitutional order and before the entities — a reader who does not
-  // know what an Ontology is here cannot read the rest of the glossary's first rows.
-  ['Ontology', 'ONTOLOGY', 'the always-on worldview under the rules — telos, evidence, '
+  // know what an Ethos is here cannot read the rest of the glossary's first rows.
+  //
+  // `Ethos (Ontology)` for the same reason as `Rule (Law)` below: the neutral theme renamed
+  // what a reader SEES, while the address the reader will meet in `src/ontology/`, in the
+  // `ONTOLOGY` theme key and in every identifier did not move. The parenthesis is the bridge
+  // between the two, and the glossary is the one page that owes a reader that bridge.
+  ['Ethos (Ontology)', 'ONTOLOGY', 'the always-on worldview under the rules — telos, evidence, '
     + 'decisions, conduct; it holds the Pact'],
   ['Rule (Law)', 'LAW', 'one of the nine always-on invariants: what is never done'],
   ['Rules (Laws)', 'LAWS', 'the body of always-on invariants'],
@@ -126,8 +131,9 @@ const GLOSSARY_KEYS = [
   ['Wiki', 'WIKI', 'the machine-wide knowledge base'],
   // Still a token, still themed, but it names a CONCEPT INSIDE the ontology's Telos now
   // rather than a peer of the Rules — `src/postures/peer.md` cites it and the section that
-  // used to carry it is the Ontology.
-  ['Pact', 'PACT', "the two-way collaboration contract, stated in the Ontology's Telos"],
+  // used to carry it is the Ethos.
+  ['Pact', 'PACT', 'the two-way collaboration contract, stated in Telos, the first Ethos '
+    + 'section'],
   ['Posture', null, 'the relationship register the agent works in '
     + '(peer, mentor, expert, assistant, artisan)'],
   ['Mode', null, 'how work gets executed — direct (the agent works every '
@@ -357,12 +363,6 @@ function readDocSource(rel) {
   return readMaybe(target) ?? '';
 }
 
-function within(child, parent) {
-  const c = normcase(child).split(/[\\/]/);
-  const p = normcase(parent).split(/[\\/]/);
-  return p.length <= c.length && p.every((seg, i) => c[i] === seg);
-}
-
 /** The deployed theme's words beside the neutral ones. */
 function glossary(state) {
   const load = (theme) => {

package/js/web/handler.mjs

@@ -62,6 +62,13 @@ export function makeHandler(state, jm, token, dist, holder = null) {
   // syscall against the readFileSync + gzipSync it saves. `gz` is the gzipped body,
   // computed once on the first gzip-accepting request instead of per request.
   const staticCache = new Map();
+  // `dist` RESOLVED ONCE, because every path compared against it below is resolved too.
+  // `resolvePath` is `realpathSync.native`, so a checkout reached by any path that is not its
+  // canonical one — a symlink, a Windows junction, a `subst` or mapped drive, an 8.3 short name,
+  // a lowercase drive letter — made `fp.startsWith(dist + sep)` false for EVERY asset. Each one
+  // then fell back to index.html at `text/html`, the browser refused the module script, and the
+  // page stayed blank with nothing logged on either side.
+  const distReal = resolvePath(dist);
 
   function sendBytes(res, body, ctype, code = 200, extra = null, acceptEncoding = '', gzStore = null) {
     const headers = { ...(extra || {}) };
@@ -86,12 +93,12 @@ export function makeHandler(state, jm, token, dist, holder = null) {
 
   function serveStatic(res, path, acceptEncoding) {
     const rel = (path === '/' || path === '') ? 'index.html' : path.replace(/^\/+/, '');
-    const index = resolvePath(join(dist, 'index.html'));
-    let fp = resolvePath(join(dist, rel));
+    const index = join(distReal, 'index.html');
+    let fp = resolvePath(join(distReal, rel));
     // STRICTLY under `dist`: `fp === dist` itself must also take the fallback below, which
-    // is why this checks `fp !== dist` and not just the prefix.
-    if (!(fp.startsWith(dist + sep) && fp !== dist) && fp !== index) fp = join(dist, 'index.html');
-    if (!isFile(fp)) fp = join(dist, 'index.html');
+    // is why this checks `fp !== distReal` and not just the prefix.
+    if (!(fp.startsWith(distReal + sep) && fp !== distReal) && fp !== index) fp = index;
+    if (!isFile(fp)) fp = index;
     if (!isFile(fp)) {
       return sendJson(res, { error: 'web/dist missing — run the UI build' }, 500, acceptEncoding);
     }

package/js/web/jobs.mjs

@@ -98,7 +98,7 @@ import { jsonDumpsCompact, parseJson, isTruthy } from '../lib/json.mjs';
  * NEVER THROWS: it runs from `cancel()` and from the crash path in `_run`'s `catch`, and an
  * exception in either would leave the child alive with the manager believing it dead.
  */
-export function killJobTree(child) {
+function killJobTree(child) {
   try {
     if (process.platform === 'win32') {
       // The one machine primitive with no Node equivalent — see this module's header.

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/src/AGENT.md.tmpl

@@ -19,19 +19,26 @@ name, or reference it from the tool's config. Where a tool supports sub-agents,
 the {{AGENTS}} below are dispatched as real sub-agents; where it does not, treat
 each as a *persona* the single agent adopts for that slice of work.
 <!-- LEAN:else -->
-It is tool-agnostic: any assistant that reads a root instructions file can be
-pointed here. Where the tool supports sub-agents, the {{AGENTS}} below are
-dispatched as real sub-agents; where it does not, treat each as a *persona* the
-single agent adopts for that slice of work.
+Tool-agnostic: where the host has no sub-agents, each {{AGENT}} below is a
+*persona* the single agent adopts for that slice of work.
 <!-- LEAN:end -->
 
+<!-- LEAN:begin -->
 **Readiness sigil — required.** Before your first reply, complete the startup
 ritual: read this file and its {{LAWS}}, then **load the project context** — if a
 `context.json` sits beside this file, read it and load its `eager` entries now
 (§9). Only then emit your first reply, which MUST begin with the
 exact line below, before any other text. Do not paraphrase it and do not skip it —
 a first reply that omits the sigil signals the harness was not read, and emitting
-it certifies you have loaded the {{LAWS}} *and* the project context.
+it certifies you have loaded the {{LAWS}} *and* the project context. **{{SKILLS}}
+first:** when a request matches a {{SKILL}}, invoke it as your first tool
+call — before loading context or touching files.
+<!-- LEAN:else -->
+**Readiness sigil — required.** Your first reply MUST begin with the exact line below,
+verbatim — it certifies you have read this file and its {{LAWS}} and loaded `context.json`
+and its `eager` entries (§9). **{{SKILLS}} first:** when the request matches a {{SKILL}}, invoke
+it as your very first tool call — before loading context, reading files, or searching.
+<!-- LEAN:end -->
 
 > {{LOADED_SIGIL}}
 
@@ -128,7 +135,7 @@ Active packs: {{DOCTRINES_LIST}}{{EXCLUDED_RULES_LINE}}
 
 {{INTRO_AGENTS}} Specs live in [`{{DIR_AGENTS}}/`]({{DIR_AGENTS}}/).
 
-<!-- CATALOG:begin -->
+<!-- CATALOG:begin agents -->
 | {{AGENT}} | Use it when… |
 | --- | --- |
 | [reviewer]({{DIR_AGENTS}}/reviewer.md) | a change is ready and needs a correctness + quality pass before merge |
@@ -173,7 +180,7 @@ content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
 workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
 the same shape model-driven via the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md).
 
-The last ten — `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`,
+Ten of them — `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`,
 `user-advocate`, `framer`, `empiricist`, `operator`, `historian` — are the standing
 **council**: read-only debate seats that each argue one assigned stance. They are rarely
 dispatched alone; the [council {{SKILL}}]({{DIR_SKILLS}}/council.md) convenes the
@@ -187,7 +194,7 @@ subset that productively clashes on a given motion.
 
 {{INTRO_SKILLS}} Specs live in [`{{DIR_SKILLS}}/`]({{DIR_SKILLS}}/).
 
-<!-- CATALOG:begin -->
+<!-- CATALOG:begin skills -->
 | {{SKILL}} | Trigger |
 | --- | --- |
 | [brainstorm]({{DIR_SKILLS}}/brainstorm.md) | a new feature or project with no design yet, or whose goal, scope, or success criteria need pinning down first |
@@ -202,7 +209,7 @@ subset that productively clashes on a given motion.
 | [debug]({{DIR_SKILLS}}/debug.md) | a bug or failure to diagnose before fixing |
 | [prototype]({{DIR_SKILLS}}/prototype.md) | a design question needs a runnable answer before real implementation |
 | [repo-map]({{DIR_SKILLS}}/repo-map.md) | orienting to the repo, or structure changed |
-| [document-project]({{DIR_SKILLS}}/document-project.md) | the project's own docs or HTML overview are missing or have drifted from the code |
+| [document-project]({{DIR_SKILLS}}/document-project.md) | missing/drifted docs, or a PRD, design system, architecture doc or AGENTS.md |
 | [ingest]({{DIR_SKILLS}}/ingest.md) | a task needs content from a PDF, Office doc, or URL |
 | [research]({{DIR_SKILLS}}/research.md) | a question needs answers gathered and verified from the open web |
 | [teach]({{DIR_SKILLS}}/teach.md) | the user wants to be taught — a crash course, confusing material decoded, or a day-by-day path to a deadline |
@@ -249,14 +256,14 @@ demand.
 When a task repeats and no {{SKILL}} covers it, forge one through the
 [skill-forge]({{DIR_SKILLS}}/skill-forge.md) {{SKILL}}: copy
 [`{{DIR_SKILLS}}/_template.md`]({{DIR_SKILLS}}/_template.md), keep it to one coherent
-domain ({{DOCTRINE}} craft 1), and register it in the catalogue above. Every {{SKILL}} ends with a
+domain ({{DOCTRINE}} craft 1), and list it wherever this file carries a catalogue. Every {{SKILL}} ends with a
 **self-improvement loop** — honour it: fold what a run teaches back into the
 file, or into {{MEMORY}} ({{DOCTRINE}} process 1).
 
 **Folder {{SKILLS}}.** Some {{SKILLS}} ship as self-contained folders under
 `{{DIR_SKILLS}}/`, each with its own format and provenance (`VENDOR.md`) —
-third-party vendors plus first-party ones bundling scripts. Not in the catalogue
-above — reach for one only when its domain comes up:
+third-party vendors plus first-party ones bundling scripts. Reach for one only when
+its domain comes up:
 - [react-view-transitions]({{DIR_SKILLS}}/react-view-transitions/SKILL.md) — animating
   React UIs with the View Transition API (`<ViewTransition>`, shared elements, Next.js).
 - [daydream]({{DIR_SKILLS}}/daydream/SKILL.md) — mining the `wiki.jsonc` vault (§8) for
@@ -270,6 +277,7 @@ above — reach for one only when its domain comes up:
 
 *{{EPI_MEMORY}}*
 
+<!-- LEAN:begin -->
 Persistent facts live in [`{{DIR_MEMORY}}/`]({{DIR_MEMORY}}/) — one fact per file, indexed by a
 local `MEMORY.md`. Read that index at the start of a session; write a new memory
 whenever the conversation yields a durable fact, a correction, or a decision worth
@@ -284,6 +292,15 @@ carry an optional `force` (constraint · choice · conviction · tempered): when
 evidence contradicts one, revise it rather than ignore it, and never overturn a
 `constraint` yourself — surface it to the user. Full
 convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
+<!-- LEAN:else -->
+Durable facts live in [`{{DIR_MEMORY}}/`]({{DIR_MEMORY}}/), one per file, indexed by
+`MEMORY.md` — **read that index at the start of a session**. Write one through the
+[rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with the user whether a
+lesson is a memory or a standing rule ({{DOCTRINE}} process 1). The directory is
+**personal and git-ignored**; shared knowledge goes in code, docs, or `user-rules.md`
+(§1). Convention, including the optional `force` field:
+[`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
+<!-- LEAN:end -->
 
 ---
 
@@ -307,24 +324,21 @@ tool you build for yourself — belongs in `{{DIR_NOTEBOOK}}/`, never in the hos
 tree. Read `NOTEBOOK.md` at the start of a session to recall what
 you keep here, and keep the space referable across sessions — the seeded index
 is one way; replace it with whatever scheme serves you better. When a note
-hardens into a durable fact worth recalling verbatim, promote it to {{MEMORY}}
-(§5, {{DOCTRINE}} process 1). Keep the two stores distinct by *role*, not just by
+hardens into a durable fact worth recalling verbatim, propose it for {{MEMORY}}
+through the rule {{SKILL}} (§5, {{DOCTRINE}} process 1). Keep the two stores distinct by *role*, not just by
 format: {{MEMORY}} holds durable insight for future sessions, the {{NOTEBOOK}}
 holds your working artifacts. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
 git-ignored** — never committed or shared, and the `.gitignore` that guarantees
 it is not yours to lift.
 <!-- LEAN:else -->
-{{INTRO_NOTEBOOK}} It lives in [`{{DIR_NOTEBOOK}}/`]({{DIR_NOTEBOOK}}/), with
-**no imposed format and no imposed medium** — notes, plans, scratch code,
-datasets, experiments. It is not {{MEMORY}} (§5): {{MEMORY}} holds curated
-durable facts for recall, the {{NOTEBOOK}} holds your working artifacts, and a
-note that hardens into a durable fact is promoted there ({{DOCTRINE}} process 1).
-Any file you create for your own benefit belongs here, never in the host tree.
-Read `NOTEBOOK.md` at the start of a session to recall what you keep; the
-charter at [`{{DIR_NOTEBOOK}}/README.md`]({{DIR_NOTEBOOK}}/README.md) is yours
-to rewrite. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
-git-ignored** — never committed or shared, and the `.gitignore` that guarantees
-it is not yours to lift.
+Your own working space, [`{{DIR_NOTEBOOK}}/`]({{DIR_NOTEBOOK}}/): any file you make
+for your own benefit — scratch code, drafts, datasets, experiments — goes here, never
+in the host tree, in whatever format serves. **Read `NOTEBOOK.md` at the start of a
+session.** A note that hardens into a durable fact is proposed for {{MEMORY}} through
+the rule {{SKILL}} (§5).
+The charter [`{{DIR_NOTEBOOK}}/README.md`]({{DIR_NOTEBOOK}}/README.md) is yours to
+rewrite; the one fixed law is that the folder is **personal and git-ignored**, and
+that `.gitignore` is not yours to lift.
 <!-- LEAN:end -->
 
 ---
@@ -333,14 +347,15 @@ it is not yours to lift.
 
 *{{EPI_VAULT}}*
 
+<!-- LEAN:begin -->
 {{INTRO_WORKSPACE}} The harness files — these {{LAWS}}, {{AGENTS}}, {{SKILLS}}, this file — sit
 *alongside* whatever already belongs to this machine or repository: notes, data,
 configs, documents, prior work. All of it is context you may use.
 
 After reading this file, take stock of what surrounds it. That non-harness
 content is knowledge to **read and learn from**, not scaffolding to reorganise.
-When you find a durable fact there worth keeping, index it into {{MEMORY}} (§5) so
-it outlives the session.
+When you find a durable fact there worth keeping, propose it for {{MEMORY}} through
+the rule {{SKILL}} (§5) so it outlives the session.
 
 Because the folder is shared, two cautions hold:
 - **You do not own it.** Files you did not create are not yours to move, rename,
@@ -351,6 +366,15 @@ Because the folder is shared, two cautions hold:
 And it receives only the **deliverables** of the task. Your own working files —
 scratch scripts, analysis dumps, drafts, experiments — are made in the
 {{NOTEBOOK}} (§6), never here.
+<!-- LEAN:else -->
+{{INTRO_WORKSPACE}} Whatever sits beside the harness files — notes, data, configs,
+prior work — is knowledge to read and learn from, not scaffolding to reorganise;
+propose a durable fact from it for {{MEMORY}} through the rule {{SKILL}} (§5). You do not own the folder: files
+you did not create are not yours to move or delete unless the task requires it
+({{LAW}} IV), and a file is verified before it is treated as disposable ({{LAW}} III).
+It receives only the task's deliverables; your working files go in the {{NOTEBOOK}}
+(§6).
+<!-- LEAN:end -->
 
 ---
 
@@ -387,17 +411,14 @@ durable fact worth sharing across projects goes here via the
 [wiki]({{DIR_SKILLS}}/wiki.md) {{SKILL}}; one that matters only to you stays in
 {{MEMORY}} (§5).
 <!-- LEAN:else -->
-{{INTRO_WIKI}} It is declared in `wiki.jsonc`, **beside this AGENT.md** — or
-wherever `$GENESEED_WIKI` points; an empty `wikis` list means this section
-stays dormant. Read `wiki.jsonc` at the start of every session and honour each
-declared wiki: load its `entries` by their `load` mode exactly as in
-`context.json` (§9); read its `conventions` before your first write there and
-follow them over your own habits; drop a note you cannot place into `inbox`
-rather than guess a home; never write inside `protected`. The wiki is **the
-user's**, not yours — wikilinks (`[[Note Name]]`) over bare paths, every new
-note linked into the graph. A durable fact worth sharing across projects goes
-here via the [wiki]({{DIR_SKILLS}}/wiki.md) {{SKILL}}; one that matters only to
-you stays in {{MEMORY}} (§5).
+{{INTRO_WIKI}} Declared in `wiki.jsonc` beside this AGENT.md (or at `$GENESEED_WIKI`;
+an empty `wikis` list means dormant) — **read it at the start of every session**
+and honour each wiki: load `entries` by `load` mode as in `context.json` (§9), read
+`conventions` before your first write there, drop an unplaceable note in `inbox`,
+never write inside `protected`. It is the user's: wikilinks over bare paths, every
+new note linked in. Cross-project facts go here via the
+[wiki]({{DIR_SKILLS}}/wiki.md) {{SKILL}}; facts that matter only to you stay in
+{{MEMORY}} (§5).
 <!-- LEAN:end -->
 
 ---
@@ -406,6 +427,7 @@ you stays in {{MEMORY}} (§5).
 
 *{{EPI_CONTEXT}}*
 
+<!-- LEAN:begin -->
 **Read `context.json` at the start of every session — this is not a
 suggestion.** The harness carries no project-specific knowledge; this manifest,
 **beside this AGENT.md**, is how the project hands you its own. (On OpenCode it
@@ -422,6 +444,14 @@ you do not work blind, and if you have not loaded it you are not ready to act.
 
 Each `path` may be absolute or relative to the repository root. The file's own
 comment carries its schema and setup notes.
+<!-- LEAN:else -->
+**Read `context.json` at the start of every session — before your first reply, not
+deferrable.** It sits beside this AGENT.md and is how the project hands you its own
+knowledge (on OpenCode it is loaded for you). `"eager"` entries are read now and are
+**project law for this repo, as binding as this file**; `"lazy"` entries only when
+the task needs them ({{DOCTRINE}} process 3). Schema and setup notes are in the file's
+own comment.
+<!-- LEAN:end -->
 
 ---
 
@@ -429,12 +459,18 @@ comment carries its schema and setup notes.
 
 *{{EPI_SCRIPTS}}*
 
+<!-- LEAN:begin -->
 {{INTRO_SCRIPTS}} The harness ships a dependency-free CLI (`geneseed
 build|doctor|diff|status|setup|web`, plus `geneseed-hook` for the verbs a host
 fires on its own) that can be wired into your host's hooks or into CI — notably
 `geneseed-hook context`, which injects the project context at session start so
 this read is enforced by the hook rather than left to you. All of it is
 opt-in; the harness works without any of it.
+<!-- LEAN:else -->
+{{INTRO_SCRIPTS}} A dependency-free CLI (`geneseed build|doctor|diff|status|setup|web`,
+plus `geneseed-hook` for host-fired verbs) can wire the gates and the §9 context
+read into your host's hooks or CI. Opt-in; the harness works without it.
+<!-- LEAN:end -->
 
 ---