geneseed 4.32.0 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/DESIGN.md +2 -2
  3. package/README.md +6 -5
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +6 -5
  6. package/adapters/claude-code/README.md +4 -3
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
  8. package/adapters/openclaude/README.md +4 -3
  9. package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
  10. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
  11. package/adapters/opencode/README.md +18 -18
  12. package/adapters/opencode/plugins/geneseed-activity.js +57 -1
  13. package/adapters/opencode/plugins/geneseed-context.js +85 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +437 -76
  15. package/adapters/opencode/plugins/geneseed-learn.js +97 -23
  16. package/bin/geneseed-cli.mjs +17 -25
  17. package/bin/geneseed-hook.mjs +23 -8
  18. package/docs/DESIGN.md +175 -0
  19. package/docs/PRD.md +111 -0
  20. package/docs/README.md +3 -2
  21. package/docs/architecture.md +145 -0
  22. package/docs/concepts/agents.md +1 -1
  23. package/docs/concepts/collaboration.md +1 -1
  24. package/docs/concepts/enforcement-table.md +1 -1
  25. package/docs/concepts/exclusions.md +5 -5
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hooks.md +22 -8
  29. package/docs/concepts/host-matrix.md +2 -2
  30. package/docs/concepts/hosts.md +1 -1
  31. package/docs/concepts/kits.md +3 -1
  32. package/docs/concepts/ownership.md +1 -1
  33. package/docs/concepts/rules.md +15 -2
  34. package/docs/concepts/shared-tier.md +73 -0
  35. package/docs/concepts/skills.md +2 -2
  36. package/docs/concepts/themes.md +1 -1
  37. package/docs/extending.md +13 -12
  38. package/docs/guides/install-claude-code.md +1 -1
  39. package/docs/guides/install-opencode.md +1 -1
  40. package/docs/guides/migrate.md +8 -4
  41. package/docs/guides/project-context.md +2 -2
  42. package/docs/guides/setup-footprint.md +1 -1
  43. package/docs/guides/uninstall.md +2 -1
  44. package/docs/guides/upgrade-to-5.md +118 -0
  45. package/docs/guides/upgrade.md +21 -9
  46. package/docs/guides/wiki.md +3 -3
  47. package/docs/reference/env-context.md +5 -3
  48. package/docs/reference/environment.md +1 -1
  49. package/docs/reference/glossary.md +2 -0
  50. package/docs/reference/opencode-plugins.md +3 -3
  51. package/docs/reference/plugin-activity.md +1 -1
  52. package/docs/reference/plugin-context.md +1 -0
  53. package/docs/reference/plugin-guard.md +14 -6
  54. package/docs/reference/plugin-learn.md +13 -6
  55. package/docs/reference/troubleshoot-hooks.md +3 -3
  56. package/docs/reference/troubleshoot-update.md +14 -0
  57. package/docs/token-footprint.md +4 -3
  58. package/docs/understand/a-day.md +2 -2
  59. package/docs/understand/design-choices-install.md +2 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-bob.md +2 -0
  62. package/docs/understand/machine-claude.md +7 -5
  63. package/docs/understand/machine-opencode.md +7 -5
  64. package/docs/understand/on-your-machine.md +4 -0
  65. package/docs/understand/take-it-out.md +1 -1
  66. package/docs/web-ui.md +135 -70
  67. package/harness.config.json +1 -1
  68. package/js/README.md +12 -7
  69. package/js/build/args.mjs +10 -8
  70. package/js/build/bundle.mjs +11 -13
  71. package/js/build/driver.mjs +66 -65
  72. package/js/build/emit-claude.mjs +22 -16
  73. package/js/build/emit-common.mjs +4 -5
  74. package/js/build/emit-opencode.mjs +22 -22
  75. package/js/build/fold.mjs +515 -0
  76. package/js/build/generate.mjs +41 -52
  77. package/js/build/render.mjs +115 -29
  78. package/js/build/rule-decide.mjs +273 -0
  79. package/js/build/source.mjs +4 -1
  80. package/js/build/stubs.mjs +70 -9
  81. package/js/build/version.mjs +10 -10
  82. package/js/cli-table.json +23 -83
  83. package/js/hosts/activity.mjs +2 -2
  84. package/js/hosts/geneseed-dir.mjs +1 -1
  85. package/js/hosts/hooks-context.mjs +389 -99
  86. package/js/hosts/hooks-learn.mjs +38 -7
  87. package/js/hosts/hooks-prims.mjs +4 -2
  88. package/js/hosts/hooks.mjs +114 -39
  89. package/js/hosts/hosts.mjs +150 -51
  90. package/js/hosts/installs.mjs +59 -171
  91. package/js/hosts/link.mjs +3 -5
  92. package/js/hosts/mcp.mjs +1 -1
  93. package/js/hosts/memory-files.mjs +219 -17
  94. package/js/hosts/ownership-gate.mjs +1 -1
  95. package/js/hosts/settings.mjs +18 -13
  96. package/js/hosts/shim.mjs +4 -33
  97. package/js/hosts/store-watch.mjs +191 -0
  98. package/js/inspect/checks-authoring.mjs +3 -3
  99. package/js/inspect/checks-build.mjs +45 -18
  100. package/js/inspect/checks-counts.mjs +4 -4
  101. package/js/inspect/checks-repo.mjs +13 -14
  102. package/js/inspect/cost.mjs +24 -2
  103. package/js/inspect/diff.mjs +123 -123
  104. package/js/inspect/doctor.mjs +22 -27
  105. package/js/inspect/excludes.mjs +181 -62
  106. package/js/inspect/inventory.mjs +22 -27
  107. package/js/inspect/registry.mjs +110 -32
  108. package/js/inspect/scan.mjs +5 -5
  109. package/js/inspect/status.mjs +141 -119
  110. package/js/inspect/validate.mjs +22 -24
  111. package/js/lib/fs.mjs +47 -50
  112. package/js/lib/json.mjs +10 -17
  113. package/js/lib/machine-dir.mjs +73 -0
  114. package/js/lib/paths.mjs +35 -33
  115. package/js/lib/proc.mjs +1 -1
  116. package/js/lib/prompt.mjs +19 -27
  117. package/js/lib/text.mjs +8 -12
  118. package/js/lib/udiff.mjs +11 -15
  119. package/js/loop/catalog.mjs +2 -3
  120. package/js/maintain/memory.mjs +17 -17
  121. package/js/maintain/migrate.mjs +120 -92
  122. package/js/maintain/setup.mjs +43 -32
  123. package/js/maintain/uninstall.mjs +43 -61
  124. package/js/maintain/update.mjs +200 -93
  125. package/js/ui/anim.mjs +21 -35
  126. package/js/ui/cli.mjs +36 -58
  127. package/js/ui/menu.mjs +22 -45
  128. package/js/ui/tui.mjs +27 -67
  129. package/js/web/actions.mjs +34 -34
  130. package/js/web/api.mjs +142 -79
  131. package/js/web/catalog.mjs +175 -46
  132. package/js/web/docs.mjs +33 -12
  133. package/js/web/doctor-worker.mjs +14 -0
  134. package/js/web/handler.mjs +16 -5
  135. package/js/web/routes.mjs +24 -22
  136. package/js/web/state.mjs +78 -19
  137. package/js/web/update-check.mjs +27 -12
  138. package/js/web/user-files.mjs +76 -104
  139. package/package.json +7 -4
  140. package/registry.json +48 -55
  141. package/src/AGENT.md.tmpl +13 -14
  142. package/src/agents/_self-improvement.md +1 -1
  143. package/src/agents/_template.md +1 -1
  144. package/src/agents/advocate.md +1 -1
  145. package/src/agents/architect.md +1 -1
  146. package/src/agents/developer.md +1 -1
  147. package/src/agents/devops-engineer.md +1 -1
  148. package/src/agents/docker-expert.md +1 -1
  149. package/src/agents/docs.md +1 -1
  150. package/src/agents/empiricist.md +1 -1
  151. package/src/agents/explorer.md +1 -1
  152. package/src/agents/framer.md +1 -1
  153. package/src/agents/historian.md +1 -1
  154. package/src/agents/kubernetes-specialist.md +1 -1
  155. package/src/agents/memory-curator.md +2 -2
  156. package/src/agents/operator.md +1 -1
  157. package/src/agents/performance.md +1 -1
  158. package/src/agents/pragmatist.md +1 -1
  159. package/src/agents/react-engineer.md +1 -1
  160. package/src/agents/react-reviewer.md +1 -1
  161. package/src/agents/researcher.md +1 -1
  162. package/src/agents/reviewer.md +1 -1
  163. package/src/agents/security.md +1 -1
  164. package/src/agents/skeptic.md +1 -1
  165. package/src/agents/spring-boot-engineer.md +1 -1
  166. package/src/agents/spring-reviewer.md +1 -1
  167. package/src/agents/spring-security.md +1 -1
  168. package/src/agents/steward.md +1 -1
  169. package/src/agents/tester.md +1 -1
  170. package/src/agents/user-advocate.md +1 -1
  171. package/src/agents/visionary.md +1 -1
  172. package/src/memory/README.md +1 -1
  173. package/src/skills/_self-improvement.md +2 -2
  174. package/src/skills/daydream/SKILL.md +2 -2
  175. package/src/skills/daydream/instructions.md +1 -1
  176. package/src/skills/geneseed.md +1 -1
  177. package/src/skills/learn-mode.md +1 -2
  178. package/src/skills/profile.md +2 -2
  179. package/src/skills/rule/approve.md +75 -0
  180. package/src/skills/rule/consolidate.md +3 -3
  181. package/src/skills/rule.md +14 -5
  182. package/src/skills/skill-forge.md +1 -1
  183. package/src/skills/teach.md +29 -12
  184. package/src/skills/wiki.md +1 -1
  185. package/themes/_TEMPLATE.json +1 -2
  186. package/themes/biker.json +1 -2
  187. package/themes/commentator.json +1 -2
  188. package/themes/cyberpunk.json +1 -2
  189. package/themes/gamer.json +1 -2
  190. package/themes/imperial.json +1 -2
  191. package/themes/joker.json +1 -2
  192. package/themes/marvin.json +1 -2
  193. package/themes/mean.json +1 -2
  194. package/themes/military.json +1 -2
  195. package/themes/neutral.json +1 -2
  196. package/themes/pirate.json +1 -2
  197. package/themes/sports.json +1 -2
  198. package/themes/verstappen.json +1 -2
  199. package/themes/wizard.json +1 -2
  200. package/web/dist/assets/Activity-Ci4PZco3.js +1 -0
  201. package/web/dist/assets/ActivityDetail-C8hroCND.js +1 -0
  202. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  203. package/web/dist/assets/Bonsai-C1iBAt4v.js +1 -0
  204. package/web/dist/assets/{CopyButton-C5Li6awl.js → CopyButton-DJ3a4N88.js} +1 -1
  205. package/web/dist/assets/Dashboard-C_On4KXw.js +2 -0
  206. package/web/dist/assets/Docs-Kffdg5uV.js +5 -0
  207. package/web/dist/assets/GreenhouseView-k56_cBSF.js +1 -0
  208. package/web/dist/assets/Installs-DtEKLC9h.js +3 -0
  209. package/web/dist/assets/JournalView-RQnk5l7I.js +1 -0
  210. package/web/dist/assets/Kits-CXkEBpnf.js +1 -0
  211. package/web/dist/assets/Laws-DhhIVqmh.js +3 -0
  212. package/web/dist/assets/Library-CAUiEoJo.js +3 -0
  213. package/web/dist/assets/{Loops-CzitjxGV.js → Loops-LKD8mF4E.js} +2 -2
  214. package/web/dist/assets/{Markdown-C4S4tTA7.js → Markdown-0ORz7tAc.js} +21 -21
  215. package/web/dist/assets/OperatorHudView-CM5jNPwL.js +1 -0
  216. package/web/dist/assets/Personal-B6Uoly3C.js +2 -0
  217. package/web/dist/assets/{RailCats-D5weYPCS.js → RailCats-DQxxYBEP.js} +1 -1
  218. package/web/dist/assets/Settings-BTe6-wda.js +1 -0
  219. package/web/dist/assets/Tabs-CbdDWTp_.js +1 -0
  220. package/web/dist/assets/api-D_r0Jtla.js +1 -0
  221. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  222. package/web/dist/assets/index-HfGmYXab.js +3 -0
  223. package/web/dist/assets/index-ao3M-Fhm.css +1 -0
  224. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  225. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  226. package/web/dist/index.html +5 -5
  227. package/src/skills/quiz.md +0 -44
  228. package/web/dist/assets/Activity-Bjy64wHC.js +0 -1
  229. package/web/dist/assets/ActivityDetail-B0AaipP8.js +0 -1
  230. package/web/dist/assets/Bonsai-CJniRqaH.js +0 -1
  231. package/web/dist/assets/Dashboard-B-6DTmae.js +0 -2
  232. package/web/dist/assets/Docs-LRc30XL9.js +0 -5
  233. package/web/dist/assets/GreenhouseView-CcoYlaWo.js +0 -1
  234. package/web/dist/assets/Installs-dp1epTcE.js +0 -3
  235. package/web/dist/assets/JournalView-nFP4poCf.js +0 -1
  236. package/web/dist/assets/KitApply-DwyZUj57.js +0 -1
  237. package/web/dist/assets/Kits-C0IEdZXe.js +0 -1
  238. package/web/dist/assets/Laws-CkykmQWu.js +0 -3
  239. package/web/dist/assets/Library-Guh9HBZU.js +0 -2
  240. package/web/dist/assets/OperatorHudView-DLGNulIY.js +0 -1
  241. package/web/dist/assets/Personal-BMtberL8.js +0 -2
  242. package/web/dist/assets/Tabs-uYJqfuQt.js +0 -1
  243. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  244. package/web/dist/assets/index-DA7BiaE5.js +0 -3
  245. package/web/dist/assets/index-dbbDGFDq.css +0 -1
  246. package/web/dist/assets/motion-Bccx3zE8.js +0 -1
@@ -25,8 +25,10 @@
25
25
  //
26
26
  // Where it writes — first match wins:
27
27
  // 1. $GENESEED_MEMORY an explicit memory dir
28
- // 2. $GENESEED_HARNESS/memory (or /anamnesis for the imperial theme)
29
- // 3. ./memory or ./Harness/memory (when the bundle is inside the project)
28
+ // 2. $GENESEED_HARNESS/memory
29
+ // 3. the install's own target: a GLOBAL install uses the shared store, <machine dir>/memory,
30
+ // when it exists, else its own memory/; a project install uses its own memory/
31
+ // 4. ./memory or ./Harness/memory (the repo, last: never ahead of the install)
30
32
  // If none resolve, it logs once and does nothing — it never blocks a session.
31
33
  //
32
34
  // It is intentionally conservative: trivial sessions are skipped, one session never
@@ -37,6 +39,7 @@ import { promises as fs, realpathSync } from "node:fs"
37
39
  import * as path from "node:path"
38
40
  import { fileURLToPath } from "node:url"
39
41
  import { homedir } from "node:os"
42
+ import { readdirSync, statSync, writeFileSync as writeLogSync, mkdirSync, readFileSync as readLogSync } from "node:fs"
40
43
 
41
44
  // OpenCode 1.x paints a plugin's stderr over its TUI input box (in red); its own log API
42
45
  // writes to the log file instead. The V1 entry sets LOG_CLIENT; V2 and tests have no
@@ -110,11 +113,25 @@ async function mainWorktreeOf(dir) {
110
113
  return path.basename(common) === ".git" ? path.dirname(common) : null
111
114
  } catch { return null }
112
115
  }
116
+ // The machine tier: machineDir() in js/lib/machine-dir.mjs, which a plugin cannot import.
117
+ function machineDir() {
118
+ return path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config"), "geneseed")
119
+ }
120
+ // A global install reads the tier: its .geneseed-emit names a -global emit, or it IS the host's config dir.
121
+ async function readsTier(dir) {
122
+ try { if ((await fs.readFile(path.join(dir, ".geneseed-emit"), "utf8")).trim().endsWith("-global")) return true } catch { /* no marker */ }
123
+ return isHostConfigDir(dir)
124
+ }
113
125
  async function sovereignBypass(cwd) {
114
126
  try {
115
127
  const cfg = path.dirname(PLUGIN_DIR) // plugins/ sits directly in <cfg>
116
- const raw = await fs.readFile(path.join(cfg, "excludes.json"), "utf8")
117
- const entries = (JSON.parse(raw).excludes) || []
128
+ const listOf = async (file) => {
129
+ try { const l = JSON.parse(await fs.readFile(file, "utf8")).excludes; return Array.isArray(l) ? l : [] } catch { return [] }
130
+ }
131
+ const entries = await listOf(path.join(cfg, "excludes.json"))
132
+ // Shared list (<machineDir>/excludes.json): a GLOBAL install adds it, a project install never does.
133
+ const shared = await listOf(path.join(machineDir(), "excludes.json"))
134
+ if (shared.length && await readsTier(cfg)) entries.push(...shared)
118
135
  const here = norm(cwd || process.cwd())
119
136
  const main = await mainWorktreeOf(cwd || process.cwd())
120
137
  const heres = main ? [here, norm(main)] : [here]
@@ -130,7 +147,6 @@ async function sovereignBypass(cwd) {
130
147
 
131
148
  const MAX_NOTES_CHARS = 16000 // cap the prompt; keep the most recent tail
132
149
  const MIN_NOTES_CHARS = 200 // below this, the session is too trivial to mine
133
- const MEMORY_DIR_NAMES = ["memory", "anamnesis"] // neutral + imperial
134
150
  // NaN-safe: garbage in the env var would make setTimeout fire immediately (NaN
135
151
  // delay → 0), distilling after EVERY turn instead of at session end.
136
152
  const _debounceRaw = Number(process.env.GENESEED_LEARN_DEBOUNCE_MS || 60000)
@@ -189,20 +205,30 @@ async function isDir(p) {
189
205
  try { return (await fs.stat(p)).isDirectory() } catch { return false }
190
206
  }
191
207
 
192
- async function resolveMemoryDir() {
208
+ // The install's own target comes BEFORE the repo: a global session in a repo that has its own
209
+ // memory/ (possibly tracked) must not learn into it. A global install (.geneseed-emit ends in
210
+ // -global, as geneseed-context.js tests it) takes the shared store when it exists, else its own
211
+ // memory/. Only "memory" names a store: a themed "anamnesis" matched Terra's Anamnesis/ vault
212
+ // by Windows case folding (B3). The shared store is machineDir() in js/lib/machine-dir.mjs,
213
+ // which a plugin cannot import.
214
+ // The host's own config dir counts as global too, whatever its marker says (the hook's
215
+ // isHostGlobalDir accepts both): OPENCODE_CONFIG_DIR, else <XDG config>/opencode.
216
+ const hostConfigDir = () => process.env.OPENCODE_CONFIG_DIR || path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config"), "opencode")
217
+ async function isHostConfigDir(dir) {
218
+ const real = async (d) => { const r = await fs.realpath(path.resolve(d)).catch(() => path.resolve(d)); return process.platform === "win32" ? r.toLowerCase() : r }
219
+ return (await real(dir)) === (await real(hostConfigDir()))
220
+ }
221
+
222
+ async function resolveMemoryDir(pluginDir = PLUGIN_DIR) {
193
223
  const env = process.env.GENESEED_MEMORY
194
224
  if (env && (await isDir(env))) return env
195
225
  const harness = process.env.GENESEED_HARNESS
196
- const bases = []
197
- if (harness) bases.push(harness)
198
- // The plugin's own dir (global install: <cfg>/plugins → <cfg>/memory) and the repo.
199
- bases.push(path.resolve(PLUGIN_DIR, ".."), process.cwd(), path.join(process.cwd(), "Harness"))
200
- for (const base of bases) {
201
- for (const name of MEMORY_DIR_NAMES) {
202
- const cand = path.join(base, name)
203
- if (await isDir(cand)) return cand
204
- }
205
- }
226
+ const own = path.resolve(pluginDir, "..")
227
+ const cands = []
228
+ if (harness) cands.push(path.join(harness, "memory"))
229
+ if (await readsTier(own)) cands.push(path.join(machineDir(), "memory"))
230
+ cands.push(path.join(own, "memory"), path.join(process.cwd(), "memory"), path.join(process.cwd(), "Harness", "memory"))
231
+ for (const cand of cands) if (await isDir(cand)) return cand
206
232
  return null
207
233
  }
208
234
 
@@ -242,7 +268,10 @@ async function appendAgentLesson(memDir, agent, lesson) {
242
268
  const file = path.join(dir, `${agent}.md`)
243
269
  let bullets = []
244
270
  try {
245
- bullets = (await fs.readFile(file, "utf8")).split("\n").filter((l) => l.startsWith("- "))
271
+ // The fold's rule (js/build/fold.mjs foldRules): a file that is not UTF-8 is left whole, the lesson dropped.
272
+ const raw = await fs.readFile(file)
273
+ if (!raw.equals(Buffer.from(raw.toString("utf8")))) return null
274
+ bullets = raw.toString("utf8").split("\n").filter((l) => l.startsWith("- "))
246
275
  } catch { /* first lesson for this agent */ }
247
276
  const day = new Date().toISOString().slice(0, 10)
248
277
  bullets.push(`- ${day}: ${lesson.replace(/\s+/g, " ").trim()}`)
@@ -420,7 +449,10 @@ const listMd = async (dir) => {
420
449
  async function writeIfChanged(p, text) {
421
450
  const old = await readLines(p)
422
451
  if (old && old.join("\n") + "\n" === text) return
423
- await fs.writeFile(p, text, "utf8")
452
+ // temp file + rename: two hosts can rebuild the index at once, and a reader never sees half of it
453
+ const tmp = `${p}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp` // two sessions in one process share a pid
454
+ await fs.writeFile(tmp, text, "utf8")
455
+ await fs.rename(tmp, p)
424
456
  }
425
457
  // `topic:`, else `type:` (a `type:` nested under `metadata:` reads the same: keys are trimmed).
426
458
  function topicOf(fm) {
@@ -478,15 +510,57 @@ async function rebuildIndex(memDir, fresh = new Set()) {
478
510
  await writeIfChanged(index, body.length ? MEMORY_SEED + body.join("\n") + "\n" : MEMORY_SEED)
479
511
  }
480
512
 
513
+ // The store files under one home, as `path -> "size:mtime"`: stats, no reads. Twin of
514
+ // js/hosts/store-watch.mjs `storeScan`; the plugins' copies are held equal by helper_parity.
515
+ function storeScan(home, found = {}) {
516
+ const stamp = (f) => {
517
+ try { const s = statSync(f); if (s.isFile()) found[f] = `${s.size}:${Math.trunc(s.mtimeMs)}` } catch { /* absent */ }
518
+ }
519
+ for (const n of ["user-rules.md", "PROFILE.md", "geneseed-wiki.jsonc", "wiki.jsonc", "wiki.json"]) stamp(path.join(home, n))
520
+ const walk = (dir) => {
521
+ let items = []
522
+ try { items = readdirSync(dir, { withFileTypes: true }) } catch { return }
523
+ for (const e of items) {
524
+ if (e.isDirectory()) { if (e.name !== "archive" && !e.name.startsWith("archived-")) walk(path.join(dir, e.name)) }
525
+ else if (e.name.endsWith(".md")) stamp(path.join(dir, e.name))
526
+ }
527
+ }
528
+ walk(path.join(home, "memory"))
529
+ return found
530
+ }
531
+
532
+ // This plugin's own writes, logged so the change report does not call them unapproved: the store
533
+ // around the run, and what moved, as an exact stamp. Twin of store-watch.mjs `recordOwnWrites`.
534
+ async function recordOwnWrites(home, fn) {
535
+ const before = storeScan(home)
536
+ try { return await fn() } finally {
537
+ try {
538
+ const now = storeScan(home)
539
+ const moved = [...new Set([...Object.keys(before), ...Object.keys(now)])].filter((f) => before[f] !== now[f])
540
+ if (moved.length) {
541
+ const f = path.join(home, "memory", ".own-writes.json")
542
+ let log = {}
543
+ try { log = JSON.parse(readLogSync(f, "utf8")) } catch { /* the first */ }
544
+ for (const p of moved) { delete log[p]; log[p] = now[p] ?? "gone" }
545
+ mkdirSync(path.dirname(f), { recursive: true })
546
+ writeLogSync(f, JSON.stringify(Object.fromEntries(Object.entries(log).slice(-2000))))
547
+ }
548
+ } catch { /* the log never fails a write */ }
549
+ }
550
+ }
551
+
481
552
  // The distil's reply into the store: a child session's one agent lesson, else memory
482
553
  // files plus their two-level index. Shared by the V1 and V2 runs.
483
- async function storeDistil(output, { isChild, memDir, agentName, existing }) {
554
+ async function storeDistil(output, opts) {
555
+ return recordOwnWrites(path.dirname(opts.memDir), () => writeDistil(output, opts))
556
+ }
557
+ async function writeDistil(output, { isChild, memDir, agentName, existing }) {
484
558
  if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
485
559
  if (isChild) {
486
560
  const lesson = output.trim().split("\n")[0].replace(/^[-*]\s*/, "").trim()
487
561
  if (lesson.length < 10 || lesson.length > 300) return // junk / truncation guard
488
562
  const f = await appendAgentLesson(memDir, agentName, lesson)
489
- say(`agent lesson -> ${f}`, "info")
563
+ say(f ? `agent lesson -> ${f}` : `${agentName}'s lesson file is not UTF-8 - left as it is, lesson dropped`, "info")
490
564
  return
491
565
  }
492
566
  const res = await writeMemories(output, memDir, existing)
@@ -527,7 +601,7 @@ export const GeneseedLearn = async (ctx) => {
527
601
  if (!warnedNoDir) {
528
602
  warnedNoDir = true
529
603
  say(
530
- "no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY."
604
+ "no memory dir — this install has no memory/ folder, and neither does the shared tier or this repo."
531
605
  )
532
606
  }
533
607
  return
@@ -610,7 +684,7 @@ export const GeneseedLearn = async (ctx) => {
610
684
 
611
685
  // OpenCode treats every export as a plugin and rejects non-functions; hang the test
612
686
  // helpers off the factory instead — reachable via import, invisible to the loader.
613
- Object.assign(GeneseedLearn, { writeMemories, resolveAgentName, appendAgentLesson, flattenV2 })
687
+ Object.assign(GeneseedLearn, { resolveMemoryDir, writeMemories, resolveAgentName, appendAgentLesson, flattenV2 })
614
688
 
615
689
  // ---- OpenCode 2 ----------------------------------------------------------------
616
690
  // `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
@@ -663,7 +737,7 @@ async function setupV2(ctx) {
663
737
  if (!memDir) {
664
738
  if (!warnedNoDir) {
665
739
  warnedNoDir = true
666
- say("no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY.")
740
+ say("no memory dir — this install has no memory/ folder, and neither does the shared tier or this repo.")
667
741
  }
668
742
  return
669
743
  }
@@ -22,8 +22,7 @@
22
22
  * names every verb it does not carry, is what makes "silently accepted `doctor` and did
23
23
  * nothing" impossible; every Geneseed hook exits 0 and signals through stdout, so a
24
24
  * no-op and a success are one observation.
25
- * * `bin/build-driver.mjs` IS `build.py`'s `main()` — a different Python program from
26
- * `rituals/harness.py`, not a different half of the same one. It parses generator FLAGS
25
+ * * `bin/build-driver.mjs` is the generator, not a different half of this CLI. It parses generator FLAGS
27
26
  * with a partition asserted over them ('the driver classifies every emit',
28
27
  * `tests/unit/node_driver.test.mjs`),
29
28
  * `tests/golden.mjs` drives it over every emit configuration, and it is under a hard `child_process`
@@ -36,10 +35,8 @@
36
35
  * `bin` per cell — and it would have been paid identically by the `bin/build-driver.mjs` option,
37
36
  * so it is not a discriminator between the two.
38
37
  *
39
- * THE VERB SET REFUSES THE REST BY NAME, exactly as the hook entry does. It carries 22 of the
40
- * 26 names the reference's parser answered to (25 subparsers, plus the alias) — the other
41
- * four are the hook verbs — and, since the three rows at the end of the table below, three
42
- * that the reference never had at all. 'the two entry points carry disjoint verb sets'
38
+ * THE VERB SET REFUSES THE REST BY NAME, exactly as the hook entry does. The four hook verbs live in the
39
+ * hook entry, and the last rows of the table below are native verbs. 'the two entry points carry disjoint verb sets'
43
40
  * (`tests/unit/hook_cli.test.mjs`) keeps the two tables from ever answering the same verb
44
41
  * twice, since the shim bakes only one of them.
45
42
  *
@@ -107,19 +104,11 @@ const VERBS = {
107
104
  // as an `aliases` field on the row above — because a field would be a DECLARATION and the
108
105
  // three matrix gates read this table as the DISPATCH (rule 7, and M23 is where it was
109
106
  // learned). As a key it is a real verb: `tests/unit/hook_cli.test.mjs`'s 'every entry verb
110
- // is a command the driver table dispatches' finds it in `js/cli-table.json`, and 'the matrix
111
- // covers every verb each entry claims' demands the `update/` cell group that proves
112
- // it reaches `cmdUpgrade` — including the theme re-read, which is what separates it from
113
- // `sync-self`.
107
+ // is a command the driver table dispatches' finds it in `js/cli-table.json`.
114
108
  //
115
109
  // It is NOT what the web console's `update` ACTION needs: that row's argv names `upgrade`,
116
110
  // the subparser, and always did. The two were coupled only in a handoff's note.
117
111
  update: () => import('../js/maintain/update.mjs').then((m) => m.cmdUpgrade),
118
- // Points at `cmdSyncSelf` rather than at `cmdUpgrade`, and that is not tidiness:
119
- // `sync-self` DROPS its `ref` before `upgrade` ever sees it, where `upgrade` both WARNS
120
- // about one and re-reads it as a theme — so the two verbs answer `sync-self cyberpunk`
121
- // and `sync-self v1.2.3` differently. See `js/maintain/update.mjs`'s `syncSelf` for both halves.
122
- 'sync-self': () => import('../js/maintain/update.mjs').then((m) => m.cmdSyncSelf),
123
112
  bootstrap: () => import('../js/maintain/update.mjs').then((m) => m.cmdBootstrap),
124
113
  // P7a. Both are DISPATCHERS whose off-TTY arm is the whole of what a cell can reach, and
125
114
  // `menu`'s on-TTY arm falls back rather than opening a panel — `js/ui/menu.mjs`'s header
@@ -151,13 +140,11 @@ const VERBS = {
151
140
  catalog: () => import('../js/build/catalog.mjs').then((m) => m.cmdCatalog),
152
141
  mcp: () => import('../js/hosts/mcp.mjs').then((m) => m.cmdMcp),
153
142
  memory: () => import('../js/maintain/memory.mjs').then((m) => m.cmdMemory),
154
- // Task 5. A fourth native verb: there was never a Python subparser for a state machine that
155
- // lives entirely inside this port, so — like the three above — it has no recorded cell to
156
- // compare against, only the absolute gates named beside it in `NATIVE`.
143
+ // Task 5. A fourth native verb: a state machine with
144
+ // no recorded cell to compare against, only the absolute gates named beside it in `NATIVE`.
157
145
  loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
158
146
  // A fifth native verb, and a port rather than an invention: the AI Harness Scorecard
159
- // (upstream Python, pinned in the module's docblock). No Geneseed Python subparser ever
160
- // existed for it, so there is no recorded cell — its absolute gate is
147
+ // (upstream Python, pinned in the module's docblock). There is no recorded cell — its absolute gate is
161
148
  // tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
162
149
  scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
163
150
  };
@@ -287,8 +274,13 @@ function parse(spec, argv) {
287
274
  }
288
275
 
289
276
  async function main(argv) {
290
- // `geneseed exclude list | head` closes stdout early. Python exits quietly through
291
- // BrokenPipeError; the Node equivalent is an EPIPE that would otherwise be an unhandled
277
+ // One line on stderr, here and never in the hook: its stdout is its verdict.
278
+ const deprecated = ['GENESEED_MEMORY', 'GENESEED_HARNESS'].filter((v) => process.env[v]);
279
+ if (deprecated.length) {
280
+ printErr(`[geneseed] ${deprecated.map((v) => `$${v}`).join(' and ')}: deprecated, removal planned for 6.0. `
281
+ + 'A global install finds the shared store by itself; pass --memory <dir> to pin one.\n');
282
+ }
283
+ // `geneseed exclude list | head` closes stdout early. That is an EPIPE that would otherwise be an unhandled
292
284
  // 'error' event and a stack trace.
293
285
  process.stdout.on('error', (e) => { if (e.code === 'EPIPE') process.exit(0); });
294
286
 
@@ -384,9 +376,9 @@ async function main(argv) {
384
376
  return await (await load())(parsed.args);
385
377
  } catch (e) {
386
378
  // `e.exitCode` is the generator's existing marker for a DELIBERATE refusal that has
387
- // already explained itself on stderr — `js/build/emit-claude.mjs` reads the same flag, and it is
388
- // `sys.exit(<message>)` on the Python side. Anything without it is a crash and keeps its
389
- // stack: Python prints a traceback for an unhandled exception, and turning one into a
379
+ // already explained itself on stderr — `js/build/emit-claude.mjs` reads the same flag.
380
+ // Anything without it is a crash and keeps its
381
+ // stack: turning one into a
390
382
  // tidy one-liner here would hide a bug behind a refusal's clothing.
391
383
  //
392
384
  // No verb needed this until `status`, which renders — and renders at a theme read out
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * The hook entry point — a Node twin of `rituals/harness.py` for the verbs the emitted
4
- * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Bob and
3
+ * The hook entry point, for the verbs the emitted
4
+ * `settings.json` actually invokes (four hook verbs, plus `tool-gate` for Bob and
5
5
  * `activity` for the web console's Activity view).
6
6
  *
7
7
  * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/build-driver.mjs`. Three reasons,
@@ -13,8 +13,8 @@
13
13
  * it is a real implementation rather than a passthrough to `build.py`. `learn` MUST
14
14
  * spawn — the whole verb is "hand these notes to whatever `$GENESEED_LLM` names".
15
15
  * Putting it in that file means either breaking the gate or weakening it.
16
- * * The hook shim bakes ONE entry and forwards `%*` to it. `harness.py` is that entry on
17
- * the Python side; a Node twin needs its own, invoked as `<node> <this> context
16
+ * * The hook shim bakes ONE entry and forwards `%*` to it. this file is that entry,
17
+ * invoked as `<node> <this> context
18
18
  * --root "<cfg>"`.
19
19
  * * `bin/build-driver.mjs` parses generator FLAGS (`--emit`, `--theme`, `--footprint`), and
20
20
  * 'the driver classifies every emit' (`tests/unit/node_driver.test.mjs`) asserts a
@@ -36,7 +36,7 @@
36
36
  * written.
37
37
  *
38
38
  * The verb set is deliberately SMALL and refuses the rest by name. `harness.py` has 24
39
- * subparsers (25 invocable names — `update` is an alias of `upgrade`); a hook entry that
39
+ * subparsers (25 invocable names — `update` is an alias of `upgrade`; `sync-self`, one of them, was removed in 5.0.0); a hook entry that
40
40
  * silently accepted `doctor` and did nothing would be the worst available failure, because
41
41
  * every Geneseed hook returns 0 and signals through stdout — so "did nothing" and "worked"
42
42
  * are the same observation. That refusal exits **1**, never 2: on Claude Code and Bob, exit 2
@@ -108,6 +108,21 @@ const VERBS = {
108
108
  activity: { load: () => import('../js/hosts/hooks-prims.mjs'), fn: 'cmdActivity', flags: HOSTED },
109
109
  };
110
110
 
111
+ /**
112
+ * The change report's baseline (js/hosts/store-watch.mjs): `context` only, so once per session, after
113
+ * it has printed. Never a gate verb, whose stdout is its verdict and which runs on every tool call.
114
+ * Prints nothing, and a failure costs the report, never the session.
115
+ */
116
+ async function baselineStores(verb, args) {
117
+ try {
118
+ if (verb !== 'context' || !args.root || process.env.GENESEED_LEARN_CHILD || isatty(0)) return;
119
+ const raw = readStdin();
120
+ if (!raw.includes('session_id')) return;
121
+ const { writeBaseline } = await import('../js/hosts/store-watch.mjs');
122
+ writeBaseline(args.root, JSON.parse(raw).session_id);
123
+ } catch { /* see above */ }
124
+ }
125
+
111
126
  /**
112
127
  * Records the payload the verb just answered into `<root>/activity/` (js/hosts/activity.mjs),
113
128
  * AFTER the verb has decided and printed, so a verdict never waits on it and never sees it.
@@ -176,8 +191,7 @@ function parse(spec, argv) {
176
191
  }
177
192
 
178
193
  async function main(argv) {
179
- // `geneseed status | head` closes stdout early. Python exits quietly through
180
- // BrokenPipeError; the Node equivalent is an EPIPE that would otherwise be an unhandled
194
+ // `geneseed status | head` closes stdout early. That is an EPIPE that would otherwise be an unhandled
181
195
  // 'error' event and a stack trace on a hook path.
182
196
  process.stdout.on('error', (e) => { if (e.code === 'EPIPE') process.exit(0); });
183
197
 
@@ -207,7 +221,7 @@ async function main(argv) {
207
221
  }
208
222
  // `<verb> --help`, for the same reason and by the same owner as `bin/geneseed-cli.mjs`:
209
223
  // argparse holds `-h` at the parser, so this entry's `parse` calls it an unrecognized
210
- // argument. The four hook verbs are four of the reference's 26 and had the same gap.
224
+ // argument. The four hook verbs have the same gap.
211
225
  // `js/ui/cli.mjs` is imported HERE, not at the top: a static import cost every tool call
212
226
  // of every session a module parse (~3 ms of an ~12 ms controllable budget) for a branch
213
227
  // only a human at a terminal ever takes.
@@ -236,6 +250,7 @@ async function main(argv) {
236
250
  }
237
251
  const rc = (await spec.load())[spec.fn](parsed.args);
238
252
  await trackActivity(verb, parsed.args);
253
+ await baselineStores(verb, parsed.args);
239
254
  return rc;
240
255
  }
241
256
 
package/docs/DESIGN.md ADDED
@@ -0,0 +1,175 @@
1
+ ---
2
+ type: design-system
3
+ mirrors-commit: 9c4af014
4
+ generated: 2026-11-06
5
+ ---
6
+
7
+ # Console design system
8
+
9
+ The design system of the `geneseed web` console, extracted from `web/src/styles.css`. Product
10
+ decisions are in the root [`DESIGN.md`](../DESIGN.md), and console behaviour in
11
+ [`web-ui.md`](web-ui.md).
12
+
13
+ <!-- geneseed:doc:start -->
14
+ ## Principles
15
+
16
+ - **A developer terminal, not a marketing page.** Deep ink surfaces, mono chrome, one accent (`styles.css:1-5`).
17
+ - **Skins, not themes.** Four skins (`cultivar`, `operator`, `matrix`, `atlas`, `web/src/hooks/useFlavour.js`) redefine the same tokens on `.app`, each in dark and light. The accent follows the deployed theme.
18
+ - **Offline first.** Fonts are self-hosted through `@fontsource`; nothing loads from a CDN (`styles.css:19-22`).
19
+ - **Motion defers to the user.** Every JS animation passes `motionOK()` (`web/src/lib/motion.js`) and keeps its `settle()`, and CSS motion stops under `prefers-reduced-motion`.
20
+ <!-- geneseed:doc:end -->
21
+
22
+ <!-- geneseed:doc:start -->
23
+ ## Tokens
24
+
25
+ Values are the `:root` defaults, before a flavour block overrides them. Each flavour's own values
26
+ are in its `.fl-*` block. Contrast is the WCAG 2.x ratio against `--bg` (`#08090B`).
27
+ `web/src/__tests__/contrast.test.js` gates AA on every flavour and surface.
28
+
29
+ ### Colour
30
+
31
+ | Name | Value | Role | Contrast | Source |
32
+ |---|---|---|---|---|
33
+ | `--bg` | `#08090B` | Page background | — | `styles.css` `:root` |
34
+ | `--bg-2` | `#0C0E11` | Second background | — | same |
35
+ | `--surface` | `#101317` | Card | 1.07 | same |
36
+ | `--surface-2` | `#14181D` | Raised card | — | same |
37
+ | `--surface-3` | `#1B2026` | Highest surface | 1.22 | same |
38
+ | `--line` | `#2C333B` | Border | 1.56 (not text) | same |
39
+ | `--line-2` | `#3A434D` | Stronger border | 1.98 (not text) | same |
40
+ | `--line-3` | `#4C5762` | Strongest border | 2.70 (not text) | same |
41
+ | `--text` | `#EAEEF2` | Body text | 17.08 AAA | same |
42
+ | `--text-2` | `#9AA6B2` | Secondary text | 8.04 AAA | same |
43
+ | `--text-3` | `#727F8E` | Tertiary text | 4.88 AA | same |
44
+ | `--accent` | `#3AD4C4` | Accent, set at run time | 10.81 AAA | same |
45
+ | `--accent-2` | `#2BA89B` | Accent, second step | 6.81 AA | same |
46
+ | `--accent-ink` | `#04100D` | Text on a filled accent | 10.50 on `--accent` | same |
47
+ | `--good` | `#4ED888` | Success | 10.91 AAA | same |
48
+ | `--warn` | `#E8B53D` | Warning | 10.54 AAA | same |
49
+ | `--bad` | `#FF5C57` | Failure | 6.56 AA | same |
50
+ | `--bad-ink` | `#1A0605` | Text on a filled `--bad` | 6.45 on `--bad` | same |
51
+
52
+ ### Typography
53
+
54
+ | Name | Value | Role | Source |
55
+ |---|---|---|---|
56
+ | `--font-display`, `--font-ui` | Hanken Grotesk, system-ui | Headings and interface | `styles.css` `:root` |
57
+ | `--font-mono` | Geist Mono, ui-monospace | Code, chips, figures | same |
58
+ | `--fs-2xs` … `--fs-2xl` | 11, 12, 13, 14, 17, 22, 28 px | Seven steps; 11 px is the floor, 28 px the page title | same |
59
+
60
+ ### Spacing
61
+
62
+ | Name | Value | Role | Source |
63
+ |---|---|---|---|
64
+ | `--sp-1` … `--sp-8` | 4, 8, 12, 16, 20, 24, 32, 48 px | A 4 px grid | `styles.css` `:root` |
65
+ | `--rail-w`, `--topbar-h` | 248 px, 64 px | Shell. `--rail-w` must stay on `:root`, or the breakpoints stop winning | same |
66
+
67
+ Breakpoints are three, and only three: 1180, 960 and 720 px.
68
+
69
+ ### Radius
70
+
71
+ | Name | Value | Role | Source |
72
+ |---|---|---|---|
73
+ | `--r-xs` … `--r-xl` | 4, 7, 11, 16, 22 px | Corners, small to large | `styles.css` `:root` |
74
+
75
+ ### Shadow
76
+
77
+ | Name | Value | Role | Source |
78
+ |---|---|---|---|
79
+ | `--shadow-card` | `0 1px 0 rgba(255,255,255,.02) inset, 0 14px 40px -28px rgba(0,0,0,.9)` | Card | `styles.css` `:root` |
80
+ | `--shadow-pop` | `0 18px 50px -12px rgba(0,0,0,.7), 0 2px 0 rgba(255,255,255,.02) inset` | Popover | same |
81
+
82
+ ### Motion
83
+
84
+ One scale, written once in `styles.css` `:root`. anime.js cannot read a CSS variable, so `DUR` in
85
+ `web/src/lib/motion.js` mirrors it, and `web/src/__tests__/motionTokens.test.js` fails when the two
86
+ part or a literal time or curve returns. The two exceptions: the reduced-motion stop (`.01ms`,
87
+ `.01s`), which is an off switch, and a negative `animation-delay`, which sets a loop's phase.
88
+ `linear` and `steps()` stay as they are: neither is a curve to tune.
89
+
90
+ | Name | Value | Role | Source |
91
+ |---|---|---|---|
92
+ | `--dur-0`, `--dur-1` | 20, 50 ms | Stagger steps; `--dur-1` also the shortest arc | `styles.css` `:root` |
93
+ | `--dur-2` … `--dur-5` | 100, 150, 200, 250 ms | Hover, press, colour | same |
94
+ | `--dur-6` … `--dur-8` | 300, 400, 500 ms | Expand, entrance, sweep | same |
95
+ | `--dur-9`, `--dur-10` | 700, 1000 ms | Count-up, ring sweep, one-shot flourish | same |
96
+ | `--dur-11` … `--dur-16` | 1500, 2500, 3000, 4000, 6000, 8000 ms | Ambient loops | same |
97
+ | `--dur-17`, `--dur-18` | 24, 40 s | Slow orbits | same |
98
+ | `--ease-out` | `cubic-bezier(.22,1,.36,1)` | The console's settle; `EASE_OUT` (`outExpo`) in anime.js | same |
99
+ | `--ease-soft` | `cubic-bezier(.2,.7,.2,1)` | A gentler settle | same |
100
+ | `--ease-swing` | `cubic-bezier(.65,0,.35,1)` | Both ends eased, for a sweep | same |
101
+ | `--ease-fade`, `--ease-in` | `ease-out`, `ease-in` | Fades | same |
102
+ | `--ease-loop` | `ease-in-out` | Ambient loops | same |
103
+
104
+ ### Layers
105
+
106
+ `--z-page` 1, `--z-sticky` 6, `--z-spotlight` 12, `--z-console` 20, `--z-tabbar` 25, `--z-scrim` 39,
107
+ `--z-drawer` 40, `--z-pop` 45, `--z-toast` 50, `--z-modal` 60, `--z-splash` 100. A new overlay picks a
108
+ layer, not a number.
109
+
110
+ ### Drift
111
+
112
+ Pages still carry literal font sizes: 131 `font-size` declarations in `styles.css` use a number, not
113
+ a `--fs-*` token. The comment at the scale says they move one page at a time, not by codemod.
114
+ <!-- geneseed:doc:end -->
115
+
116
+ <!-- geneseed:doc:start -->
117
+ ## Components
118
+
119
+ Shared primitives in `web/src/components/`.
120
+
121
+ | Component | Role | Variants and states | Key props |
122
+ |---|---|---|---|
123
+ | `PageHeader.jsx` | Page title block | With or without actions | title, children |
124
+ | `Tabs.jsx` | Sub-pages of a rail entry | Active tab | tabs |
125
+ | `DataTable.jsx` | Sortable data | Empty | columns, rows |
126
+ | `Stat.jsx`, `StatusBadge.jsx` | Figures and verdicts | good, warn, bad | value, label |
127
+ | `InstallPicker.jsx` | Names the install an action applies to, always as *Install:* | Hidden with one active install | installs, value, onChange |
128
+ | `EmptyState.jsx`, `ErrorState.jsx`, `Loading.jsx` | The three non-data states | Retry on error | message |
129
+ | `ConfirmDialog.jsx`, `Popover.jsx`, `Toast.jsx` | Overlays | Open, closed | children |
130
+ | `Spotlight.jsx`, `Search.jsx` | Jump to anything | `/`, Ctrl or ⌘ + K | — |
131
+ | `Markdown.jsx` | Rendered docs and rule text | — | text |
132
+
133
+ ⚠ to confirm: the prop names above are summaries from reading the files, not a full contract.
134
+ <!-- geneseed:doc:end -->
135
+
136
+ <!-- geneseed:doc:start -->
137
+ ## Usage rules
138
+
139
+ - **Do** use a surface and text token, so a flavour can restyle the page. **Do not** add a colour outside a flavour block; `contrast.test.js` reads the blocks.
140
+ - **Do** reuse one of the three breakpoints. **Do not** add a fourth.
141
+ - **Do** give a page's `InstallPicker` `className="page-pick"`: right above the heading of the view it acts on, labelled *Install:*: under the tabs on a tabbed page, over the h1 on a page with none. A form or popover that acts on its own install holds the same control inside it. **Do not** add a console-wide install switch, and **do not** write another label.
142
+ - **Do** read whether an install is on the shared tier from its `shared` field (`useInstalls`). State the shared scope once, in the page header, and tag a list head, not its rows. A project install's entry names its install.
143
+ - **Do** give each control one home. Skin and accent live in the Appearance popover, the lens in the Overview header, a kit's switches on the Kits page, a footprint in the Hosts panel. **Do not** add a second place that sets them.
144
+ - **Do** pass a JS animation through `motionOK()` and give it a settled end state.
145
+ - **Do** take a duration and a curve from the motion tokens. **Do not** write a literal one; pick the nearest step.
146
+ - **Do** show `Loading.jsx` while a first read is out, and print no count before its data. **Do not** let a pending read say it failed or found nothing.
147
+ - **Do** name an install with `installTag` and a host with `hostInfo().label`, and only where it differs.
148
+ - **Do** rebuild and commit `web/dist/` with every change under `web/src/`.
149
+ <!-- geneseed:doc:end -->
150
+
151
+ ## Words
152
+
153
+ One word per concept. Every visible string uses the word in the middle column, and never one from
154
+ the right column. API fields, ids and CSS classes keep their own names: this table is about what a
155
+ person reads.
156
+
157
+ | Concept | Word | Never |
158
+ |---|---|---|
159
+ | A build against its source | *in sync*, *behind source*, *not checked* | in step, up to date |
160
+ | Geneseed against its release | *latest*, *N commits to pull*, *X available* | up to date |
161
+ | Files changed by hand in an install | *local edits*; a count reads *N edited* or *N local edits* | drift, drifted, hand edits, hand-edited, edited by hand, edits to graft |
162
+ | One copy of the harness on a host | *install* | harness (for a copy), deployed harness |
163
+ | What Geneseed makes, as a whole | *harness* | — |
164
+ | The tool an install lives in | *host*; its name is `hostInfo().label` | harness, in the Docs host switch |
165
+ | The agent's way of speaking | *voice* | theme |
166
+ | The console's look | *skin* | flavour, theme, direction |
167
+ | A way to lay out the Overview | *lens*: Overview, Genome, Greenhouse, HUD, Journal | a skin's name |
168
+ | A dive inside a lens | *sub-view*: Status, Lineage, Readout | a lens's or a skin's name |
169
+ | The numbered laws | the theme's noun `nouns.laws`, with *Dictates* as its fallback | Laws, in fixed prose |
170
+ | A rule named by the gate ledger | its principle; with no catalog entry, *Rule IV* or *Process rule 5* | `law-4`, `process.5` |
171
+ | Running the checks | *Run doctor*, on every button | Re-run checks |
172
+ | The tier's files | *shared* | global, on a row |
173
+
174
+ Keep the themed nouns the theme tokens own: a word that comes from `nouns` or a catalog title is
175
+ the voice's own and this table does not rule it.