geneseed 4.31.0 → 5.0.0

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 (272) hide show
  1. package/CHANGELOG.md +107 -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 +220 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +578 -74
  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 +6 -6
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hook-gates.md +1 -1
  29. package/docs/concepts/hooks.md +27 -11
  30. package/docs/concepts/host-matrix.md +3 -3
  31. package/docs/concepts/hosts.md +1 -1
  32. package/docs/concepts/kits.md +3 -1
  33. package/docs/concepts/loop-bricks.md +1 -1
  34. package/docs/concepts/loop-notes.md +4 -2
  35. package/docs/concepts/loop-templates.md +7 -4
  36. package/docs/concepts/loops.md +3 -0
  37. package/docs/concepts/ownership.md +2 -2
  38. package/docs/concepts/rules.md +15 -2
  39. package/docs/concepts/shared-tier.md +73 -0
  40. package/docs/concepts/skills.md +2 -2
  41. package/docs/concepts/themes.md +1 -1
  42. package/docs/extending.md +13 -12
  43. package/docs/guides/install-claude-code.md +1 -1
  44. package/docs/guides/install-opencode.md +1 -1
  45. package/docs/guides/migrate.md +4 -2
  46. package/docs/guides/project-context.md +2 -2
  47. package/docs/guides/run-a-loop.md +1 -1
  48. package/docs/guides/set-up-ownership.md +1 -1
  49. package/docs/guides/setup-footprint.md +1 -1
  50. package/docs/guides/uninstall.md +2 -1
  51. package/docs/guides/upgrade-to-5.md +116 -0
  52. package/docs/guides/upgrade.md +21 -9
  53. package/docs/guides/wiki.md +3 -3
  54. package/docs/reference/env-context.md +5 -3
  55. package/docs/reference/environment.md +1 -1
  56. package/docs/reference/glossary.md +2 -0
  57. package/docs/reference/loop-actions.md +1 -1
  58. package/docs/reference/opencode-plugins.md +3 -3
  59. package/docs/reference/plugin-activity.md +1 -1
  60. package/docs/reference/plugin-context.md +5 -0
  61. package/docs/reference/plugin-guard.md +14 -6
  62. package/docs/reference/plugin-learn.md +13 -6
  63. package/docs/reference/troubleshoot-hooks.md +3 -3
  64. package/docs/reference/troubleshoot-update.md +14 -0
  65. package/docs/token-footprint.md +4 -3
  66. package/docs/understand/a-day.md +2 -2
  67. package/docs/understand/design-choices-install.md +2 -1
  68. package/docs/understand/enforced-vs-asked.md +4 -3
  69. package/docs/understand/machine-bob.md +3 -1
  70. package/docs/understand/machine-claude.md +7 -5
  71. package/docs/understand/machine-opencode.md +7 -5
  72. package/docs/understand/on-your-machine.md +4 -0
  73. package/docs/understand/take-it-out.md +1 -1
  74. package/docs/web-ui.md +141 -73
  75. package/harness.config.json +1 -1
  76. package/js/README.md +10 -6
  77. package/js/build/args.mjs +10 -8
  78. package/js/build/bundle.mjs +11 -13
  79. package/js/build/driver.mjs +66 -65
  80. package/js/build/emit-claude.mjs +22 -16
  81. package/js/build/emit-common.mjs +4 -5
  82. package/js/build/emit-opencode.mjs +22 -22
  83. package/js/build/fold.mjs +515 -0
  84. package/js/build/generate.mjs +41 -52
  85. package/js/build/render.mjs +115 -29
  86. package/js/build/source.mjs +4 -1
  87. package/js/build/stubs.mjs +70 -9
  88. package/js/build/version.mjs +10 -10
  89. package/js/cli-table.json +23 -83
  90. package/js/hosts/activity.mjs +2 -2
  91. package/js/hosts/geneseed-dir.mjs +1 -1
  92. package/js/hosts/hooks-context.mjs +410 -99
  93. package/js/hosts/hooks-done.mjs +97 -31
  94. package/js/hosts/hooks-learn.mjs +38 -7
  95. package/js/hosts/hooks-prims.mjs +69 -2
  96. package/js/hosts/hooks.mjs +300 -64
  97. package/js/hosts/hosts.mjs +150 -51
  98. package/js/hosts/installs.mjs +55 -167
  99. package/js/hosts/link.mjs +3 -5
  100. package/js/hosts/mcp.mjs +1 -1
  101. package/js/hosts/memory-files.mjs +219 -17
  102. package/js/hosts/ownership-gate.mjs +1 -1
  103. package/js/hosts/settings.mjs +18 -13
  104. package/js/hosts/shim.mjs +4 -33
  105. package/js/hosts/store-watch.mjs +189 -0
  106. package/js/inspect/checks-authoring.mjs +3 -3
  107. package/js/inspect/checks-build.mjs +45 -18
  108. package/js/inspect/checks-counts.mjs +4 -4
  109. package/js/inspect/checks-repo.mjs +13 -14
  110. package/js/inspect/cost.mjs +24 -2
  111. package/js/inspect/diff.mjs +123 -123
  112. package/js/inspect/doctor.mjs +22 -27
  113. package/js/inspect/excludes.mjs +181 -62
  114. package/js/inspect/inventory.mjs +22 -27
  115. package/js/inspect/registry.mjs +106 -30
  116. package/js/inspect/scan.mjs +5 -5
  117. package/js/inspect/status.mjs +141 -119
  118. package/js/inspect/validate.mjs +22 -24
  119. package/js/lib/fs.mjs +47 -50
  120. package/js/lib/json.mjs +10 -17
  121. package/js/lib/machine-dir.mjs +73 -0
  122. package/js/lib/paths.mjs +22 -33
  123. package/js/lib/proc.mjs +1 -1
  124. package/js/lib/prompt.mjs +19 -27
  125. package/js/lib/text.mjs +8 -12
  126. package/js/lib/udiff.mjs +11 -15
  127. package/js/loop/catalog.mjs +2 -3
  128. package/js/loop/state.mjs +15 -5
  129. package/js/maintain/memory.mjs +17 -17
  130. package/js/maintain/migrate.mjs +79 -89
  131. package/js/maintain/setup.mjs +43 -32
  132. package/js/maintain/uninstall.mjs +43 -61
  133. package/js/maintain/update.mjs +200 -93
  134. package/js/ui/anim.mjs +21 -35
  135. package/js/ui/cli.mjs +36 -58
  136. package/js/ui/menu.mjs +22 -45
  137. package/js/ui/tui.mjs +27 -67
  138. package/js/web/actions.mjs +38 -38
  139. package/js/web/api.mjs +132 -76
  140. package/js/web/catalog.mjs +175 -46
  141. package/js/web/docs.mjs +33 -12
  142. package/js/web/doctor-worker.mjs +14 -0
  143. package/js/web/handler.mjs +14 -5
  144. package/js/web/routes.mjs +17 -19
  145. package/js/web/state.mjs +78 -19
  146. package/js/web/update-check.mjs +25 -10
  147. package/js/web/user-files.mjs +50 -105
  148. package/package.json +7 -4
  149. package/registry.json +48 -55
  150. package/src/AGENT.md.tmpl +13 -14
  151. package/src/agents/_self-improvement.md +1 -1
  152. package/src/agents/_template.md +4 -1
  153. package/src/agents/advocate.md +1 -1
  154. package/src/agents/architect.md +1 -1
  155. package/src/agents/developer.md +6 -3
  156. package/src/agents/devops-engineer.md +1 -1
  157. package/src/agents/docker-expert.md +1 -1
  158. package/src/agents/docs.md +1 -1
  159. package/src/agents/empiricist.md +1 -1
  160. package/src/agents/explorer.md +1 -1
  161. package/src/agents/framer.md +1 -1
  162. package/src/agents/historian.md +1 -1
  163. package/src/agents/kubernetes-specialist.md +1 -1
  164. package/src/agents/memory-curator.md +2 -2
  165. package/src/agents/operator.md +1 -1
  166. package/src/agents/performance.md +1 -1
  167. package/src/agents/pragmatist.md +1 -1
  168. package/src/agents/react-engineer.md +1 -1
  169. package/src/agents/react-reviewer.md +1 -1
  170. package/src/agents/researcher.md +1 -1
  171. package/src/agents/reviewer.md +1 -1
  172. package/src/agents/security.md +1 -1
  173. package/src/agents/skeptic.md +1 -1
  174. package/src/agents/spring-boot-engineer.md +1 -1
  175. package/src/agents/spring-reviewer.md +1 -1
  176. package/src/agents/spring-security.md +1 -1
  177. package/src/agents/steward.md +1 -1
  178. package/src/agents/tester.md +5 -2
  179. package/src/agents/user-advocate.md +1 -1
  180. package/src/agents/visionary.md +1 -1
  181. package/src/bricks/apply.md +3 -0
  182. package/src/bricks/test.md +6 -4
  183. package/src/loops/bugfix.json +11 -5
  184. package/src/loops/feature.json +7 -4
  185. package/src/memory/README.md +1 -1
  186. package/src/skills/_self-improvement.md +2 -2
  187. package/src/skills/daydream/SKILL.md +2 -2
  188. package/src/skills/daydream/instructions.md +1 -1
  189. package/src/skills/geneseed.md +1 -1
  190. package/src/skills/learn-mode.md +1 -2
  191. package/src/skills/loop.md +1 -0
  192. package/src/skills/profile.md +2 -2
  193. package/src/skills/rule/approve.md +69 -0
  194. package/src/skills/rule/consolidate.md +3 -3
  195. package/src/skills/rule.md +13 -5
  196. package/src/skills/ship.md +9 -1
  197. package/src/skills/skill-forge.md +1 -1
  198. package/src/skills/teach.md +29 -12
  199. package/src/skills/wiki.md +1 -1
  200. package/themes/_TEMPLATE.json +1 -2
  201. package/themes/biker.json +1 -2
  202. package/themes/commentator.json +1 -2
  203. package/themes/cyberpunk.json +1 -2
  204. package/themes/gamer.json +1 -2
  205. package/themes/imperial.json +1 -2
  206. package/themes/joker.json +1 -2
  207. package/themes/marvin.json +1 -2
  208. package/themes/mean.json +1 -2
  209. package/themes/military.json +1 -2
  210. package/themes/neutral.json +1 -2
  211. package/themes/pirate.json +1 -2
  212. package/themes/sports.json +1 -2
  213. package/themes/verstappen.json +1 -2
  214. package/themes/wizard.json +1 -2
  215. package/web/dist/assets/Activity-D8G4eClY.js +1 -0
  216. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
  217. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  218. package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
  219. package/web/dist/assets/{CopyButton-IXnXzH4Y.js → CopyButton-CHQte7Ap.js} +1 -1
  220. package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
  221. package/web/dist/assets/{DataTable-BWbUx4bY.js → DataTable-b9zTShqJ.js} +1 -1
  222. package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
  223. package/web/dist/assets/{EmptyState-1sPNleqv.js → EmptyState-CY5Pm2xy.js} +1 -1
  224. package/web/dist/assets/FilterInput-qGKNSlxv.js +1 -0
  225. package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
  226. package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
  227. package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
  228. package/web/dist/assets/Kits-CoITzxWM.js +1 -0
  229. package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
  230. package/web/dist/assets/Library-DNwHYVXt.js +3 -0
  231. package/web/dist/assets/{Loops-C5u7fQOR.js → Loops-S85PMQ8m.js} +2 -2
  232. package/web/dist/assets/Markdown-0ORz7tAc.js +69 -0
  233. package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
  234. package/web/dist/assets/Personal-afJNwvRS.js +2 -0
  235. package/web/dist/assets/RailCats-AW92uhsX.js +1 -0
  236. package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
  237. package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
  238. package/web/dist/assets/api-C46vAuqp.js +1 -0
  239. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  240. package/web/dist/assets/index-COTd4TRZ.js +3 -0
  241. package/web/dist/assets/index-CtorA7uK.css +1 -0
  242. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  243. package/web/dist/assets/react-C1iE8mnY.js +9 -0
  244. package/web/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  245. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  246. package/web/dist/assets/{usePoll-bDFN-Hr6.js → usePoll-o8ul-Sog.js} +1 -1
  247. package/web/dist/index.html +7 -7
  248. package/src/skills/quiz.md +0 -44
  249. package/web/dist/assets/Activity-B7cFtS00.js +0 -1
  250. package/web/dist/assets/ActivityDetail-C-GbMmuW.js +0 -1
  251. package/web/dist/assets/Bonsai-_YyexVC5.js +0 -1
  252. package/web/dist/assets/Dashboard-sCfEjowQ.js +0 -2
  253. package/web/dist/assets/Docs-w3Y7M5Ts.js +0 -5
  254. package/web/dist/assets/FilterInput-CZREvrjX.js +0 -1
  255. package/web/dist/assets/GreenhouseView-BWWbMKmg.js +0 -1
  256. package/web/dist/assets/Installs-CnkdJ-VA.js +0 -3
  257. package/web/dist/assets/JournalView-C7bPD3fZ.js +0 -1
  258. package/web/dist/assets/KitApply-CQQbnThf.js +0 -1
  259. package/web/dist/assets/Kits-aj07N7mT.js +0 -1
  260. package/web/dist/assets/Laws-DZ38nl_H.js +0 -3
  261. package/web/dist/assets/Library-QCGXPV5h.js +0 -2
  262. package/web/dist/assets/Markdown-DpmmtW2Y.js +0 -65
  263. package/web/dist/assets/OperatorHudView-Blu1lqiZ.js +0 -1
  264. package/web/dist/assets/Personal-ox_MktWO.js +0 -2
  265. package/web/dist/assets/RailCats-BuJD4Jou.js +0 -1
  266. package/web/dist/assets/Tabs-CIPyMAX-.js +0 -1
  267. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  268. package/web/dist/assets/index-0GCxkY7m.css +0 -1
  269. package/web/dist/assets/index-CzDi9JpF.js +0 -3
  270. package/web/dist/assets/motion-CXaUMNkg.js +0 -1
  271. package/web/dist/assets/react-DlYQp10C.js +0 -9
  272. package/web/dist/assets/rolldown-runtime-hePW80VL.js +0 -1
@@ -12,25 +12,27 @@ What an OpenCode install writes, piece by piece. The **Kind** words are explaine
12
12
  | Piece | What it does for you | Kind | Cost | Turn it off |
13
13
  |---|---|---|---|---|
14
14
  | `AGENT.md` | The rules, the pointers to agents and skills, and how memory works | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
15
- | `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
- | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
15
+ | `user-rules.md` | Your own standing rules, read every session. A global install reads the [shared](../concepts/shared-tier.md) file first, then this one, which can narrow it. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
+ | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill. On a global install it lives in the shared tier, and a filled host file replaces the shared one | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `git reflog expire`, `git gc --prune` or a force-push or delete of `main`/`master`, and before every commit and push when the **process** pack is on. `permission.skill` denies each user-only skill, so the model never starts it but `/name` still runs it; Geneseed takes back only the denies it wrote | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
18
18
  | context plugin | Puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `GENESEED_CONTEXT_INJECT=off` |
19
19
  | guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), every other real data loss judged against the repository's state, a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours. In an application repo with no `## Ownership` section in its root `AGENTS.md`, refuses the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block; the ownership refusal alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
- | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into `memory/` with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
20
+ | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into the memory store with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
21
21
  | activity plugin | Writes one small file per session that the web console's Activity view shows: what the session does now, its sub-agents, the files each of them changed (by path inside the repository), its turns, how full its context is and its compactions | automatic | No tokens | `GENESEED_ACTIVITY=off` |
22
22
  | notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
23
23
  | ponytail plugin | Minimal-code mode. `/ponytail lite`, `full` or `ultra` adds a short ruleset to every turn until you switch it off | on demand | 0 while off, which is the default | `/ponytail off` |
24
24
  | workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
25
25
  | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
26
26
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
27
- | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
28
- | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
27
+ | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects. A global install keeps them in the shared `~/.config/geneseed/memory/`; this folder holds only the convention and a seeded index | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
28
+ | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl`. It stays per host; on a global install only the self-improvement notes live in the shared `notes/` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
29
29
 
30
30
  ## Where the files are
31
31
 
32
32
  **OpenCode.** A global install writes to `~/.config/opencode/`. Setting `OPENCODE_CONFIG_DIR` or `XDG_CONFIG_HOME` moves it. Geneseed merges its entries into your existing `opencode.json` and keeps every other key. A per-repo install writes into the repo instead.
33
33
 
34
+ **Shared by every host.** Each global install also reads and writes one machine-wide folder, `~/.config/geneseed/`: your rules, profile, memory, wiki manifest, exclude paths and notes. See [The shared tier](../concepts/shared-tier.md). A per-repo install keeps its own copies.
35
+
34
36
  ---
35
37
 
36
38
  **Next:** [On Bob, or any AGENT.md tool](machine-bob.md) · [Taking it back out](take-it-out.md)
@@ -15,6 +15,10 @@ An install writes a handful of files into your host's config folder and, where t
15
15
 
16
16
  Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about 5k on the rules file. For a live figure on your own install, ask the agent to use the `token-report` skill.
17
17
 
18
+ ## One folder for the whole machine
19
+
20
+ Host config folders are not the only place. Every global install shares `~/.config/geneseed/`, which holds what you teach the agent: your rules, profile, memory, wiki manifest, exclude paths and notes. Teach one tool something, and the others know it. See [The shared tier](../concepts/shared-tier.md). The rules text, agents, skills and kits stay in each host's own folder.
21
+
18
22
  ## One page per host
19
23
 
20
24
  <!--harness:opencode-->
@@ -6,7 +6,7 @@ kind: "concept"
6
6
  section: "On your machine"
7
7
  description: "What geneseed uninstall removes, and what it keeps for you."
8
8
  ---
9
- `geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. A file Geneseed wrote that you have since edited stays too, and becomes yours; add `--force` to delete edited files as well. See [Uninstall](../guides/uninstall.md).
9
+ `geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). It never touches the [shared tier](../concepts/shared-tier.md), `~/.config/geneseed/`, even for the last host: it prints where the tier lives, and removing it is your call. Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. A file Geneseed wrote that you have since edited stays too, and becomes yours; add `--force` to delete edited files as well. See [Uninstall](../guides/uninstall.md).
10
10
 
11
11
  ---
12
12
 
package/docs/web-ui.md CHANGED
@@ -61,7 +61,7 @@ A request can name the install it reads or writes. A read takes two query parame
61
61
  it against the same detected-install allowlist as the install toggle. An unknown or half pair
62
62
  gets a 404 and never falls through to another install's folder. The writes that take the pair
63
63
  are `/api/activity`, `/api/memory/delete`, `/api/rules`, `/api/rules/promote`, `/api/profile`,
64
- and the `restore` and `build` actions. In `/api/install`, the `install` and
64
+ and the `restore` and `build` actions. In `/api/install`, `/api/default-install`, the `install` and
65
65
  `deploy` actions, `/api/excludes` and `/api/reveal`, `host`/`path` keep their own meaning.
66
66
 
67
67
  Every `/api/*` read takes and checks the pair, with these exceptions:
@@ -76,7 +76,9 @@ Every `/api/*` read takes and checks the pair, with these exceptions:
76
76
 
77
77
  The skill, agent, memory and notebook lists read every active install (memory and notebook
78
78
  entries are your own files, so a fact's Forget and Promote act on the install of the copy on
79
- screen, and Promote writes to that install's `user-rules.md`). Each row is one id (kind and name), and
79
+ screen, and Promote writes to that install's `user-rules.md`). The installs that read the shared
80
+ tier hold one memory store: it is listed under the first of them, and `/api/catalog/memory` names
81
+ them all in `sharedInstalls`. Each row is one id (kind and name), and
80
82
  its `installs` field names the installs that have it, as `host:scope:root` keys (the same keys
81
83
  as `/api/usage`). An id that only some installs have lists only those installs, so an exclusion
82
84
  stays visible. The other catalog sections stay install-scoped. `/api/item/skill/<name>` and
@@ -87,9 +89,15 @@ it. The order is the host order (OpenCode, Claude Code, Bob, OpenClaude), then g
87
89
  project. The item's `install` field names the copy, and its `installs` field names every
88
90
  install that has the id.
89
91
 
90
- A request that names no install reads the **default install**: the first active one in the console's one
91
- install order (`fleetSort`): host order (opencode, claude, bob, openclaude), then global before
92
- project. `/api/installs` marks
92
+ A request that names no install reads the **default install**: the one you chose on the Installs
93
+ page (*Make default* on an active row), while it stays active. With no choice, it is the first
94
+ active one in the console's one install order (`fleetSort`): host order (opencode, claude, bob,
95
+ openclaude), then global before project. The choice is machine-wide and lives in
96
+ `default-install.json` in the shared tier. `POST /api/default-install` with `{host, path}` sets it
97
+ and refuses anything else with a 409, an empty or malformed body included, and the choice stays.
98
+ The console has no way to clear it: choose another install, or delete the file. A choice that no
99
+ longer names an active install is ignored, and it applies again if that install comes back. The
100
+ `install` and `theme` lines of `geneseed status` follow the same choice. `/api/installs` marks
93
101
  that row `default: true`. There is no console-wide install and no `POST /api/view`: a page that
94
102
  acts on one install names it on each request, through a picker placed beside the entry or form it
95
103
  applies to (see below).
@@ -98,31 +106,67 @@ of them.
98
106
 
99
107
  ## The rail
100
108
 
101
- The left rail mirrors the harness's own shape:
109
+ The left rail has one flat list, and three entries at its foot:
102
110
 
103
- | Group | Views |
111
+ | Entry | Holds |
104
112
  | --- | --- |
105
- | *(ungrouped)* | Dashboard |
106
- | **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Loops · Docs |
107
- | **🩺 Care** | Activity · Changes · Doctor |
108
- | **🎨 Setup** | Harness · Settings |
109
-
110
- At the foot of the rail sits a **vitals** card — the doctor's verdict, drift, how long ago the
113
+ | **Overview** (`#/`) | The fleet: every install on one Ledger, and *Needs you* |
114
+ | **Constitution** (`#/laws`) | Ethos, Rules and doctrines |
115
+ | **Library** (`#/library`) | Skills, agents, the wiki and the setup files |
116
+ | **Kits** (`#/kits`) | The kit catalogue |
117
+ | **Loops** (`#/loops`) | Tabs: Templates · Bricks · Active |
118
+ | **Personal** (`#/personal`) | Tabs: Rules · Profile · Memory · Notebook |
119
+ | **Installs** (`#/installs`) | Tabs: Hosts · Local edits · Doctor |
120
+ | **Docs**, **Activity**, **Settings** (foot) | The documentation, the agent sessions on this machine, and this copy of Geneseed with its server |
121
+
122
+ The old flat routes still resolve to their tab (`VIEW_ALIAS`, `web/src/lib/router.js`): `#/rules`,
123
+ `#/profile`, `#/harness`, `#/harnesses`, `#/themes`, `#/diff`, `#/doctor`, `#/about`. Addresses of
124
+ what moved open its one home: `#/installs/kits` the Kits page, `#/installs/server` Settings, and
125
+ `#/section/memory`, `#/section/notebook`, `#/item/memory/<name>` and `#/item/notebook/<name>` the
126
+ Personal tabs. The view notes below keep those older names and their old grouping.
127
+
128
+ **A rail badge equals what its page lists.** Every count covers every install, deduped by name, and
129
+ `/api/overview` `counts` is the size of the same lists the pages show (`fleetCounts`,
130
+ `js/web/catalog.mjs`). A folder's index and README (`MEMORY.md`, `NOTEBOOK.md`) are in no list and no
131
+ count, and stay readable by name. Constitution counts its rules, on or off, and not the Ethos
132
+ sections. Library is the sum of its kinds. Installs counts what is installed, on or off. A number
133
+ measured on one install, such as a root file's size on an Overview row, is a measurement and stays
134
+ on its row. An install that cannot be read is skipped, and the rest still count. The Loops badge is
135
+ the union across installs, and its title says so; the page lists the picked install's templates.
136
+ `web/src/__tests__/railCounts.test.jsx` and `tests/unit/web_counts.test.mjs` hold this.
137
+
138
+ **A read still out is not a failed one.** Each card tells three states apart: `Loading.jsx` while the
139
+ first read is out, a sentence when it failed, and what it found when it is empty. No count appears
140
+ before its data. The Constitution waits for the picked install's own overview too: a gate read
141
+ before it would read as armed.
142
+
143
+ At the foot of the rail sits a **vitals** card — the doctor's verdict, local edits, how long ago the
111
144
  harness was built, and a Voice button — so those facts are on screen from every page. It is
112
145
  hidden where the rail collapses to icons (≤960px) and returns with the phone drawer. The topbar's
113
146
  breadcrumb starts at the page: it names no install.
114
147
 
115
- **Install pickers.** The console has no install switch. Where a page acts on one install, an
116
- `InstallPicker` sits beside what it applies to, labelled for it (*Write to:*, *Doctor for:*), and
117
- starts on the default install; with one active install it is not shown. Rules and Profile list
118
- every active install's entries together, each tagged with its install, and write back to the
119
- install an entry came from; so do Memory and Notebook, whose Forget and Promote act on the
120
- install of the copy on screen. Doctor, Local edits, Server, the Constitution (*Constitution of:*,
121
- for its gate switches and doctrine Apply), Loops (*Templates and bricks of:*) and the rail's Voice
122
- popover (*Rebuild:*) each keep their own pick (in the browser's localStorage). The Overview is
123
- fleet-wide: each install's own facts (voice, footprint, posture, mode, memory facts, drift) sit on
124
- its row, and a figure still read off the default install (a suggestion, a tab badge, an older
125
- Overview view, Personal's Rule budget) names that install once two or more are active.
148
+ **Install pickers.** The console has no install switch. Where a page acts on one install, one
149
+ `InstallPicker`, always labelled *Install:*, sits right above the heading of the view it acts on
150
+ (under the tabs on a tabbed page, over the h1 on a page with none), and starts on the default install; with one active install it is not shown. A form or popover that
151
+ acts on its own install holds the same control: the new-rule form, the rail's Voice popover, and a
152
+ Library entry with several copies. The Personal page names no harness for what the harnesses share:
153
+ every global install reads one set of rules, one profile and one memory store in the shared tier
154
+ (`~/.config/geneseed`), so Rules, Profile and Memory list each once. Its header states that scope
155
+ once, a list head or profile card says `shared`, and a project install keeps its own, named by its
156
+ install. Each `/api/installs` and `/api/fleet` row carries `shared`, which the pages read from
157
+ `useInstalls`; `sharedTier` is only a project install's switch. A write goes back to the file an
158
+ entry came from. Notebook stays per install, and its Forget acts on the install of the copy on
159
+ screen. Doctor, Local edits, the Constitution (for its gate switches and doctrine Apply), Loops and
160
+ the rail's Voice popover each keep their own pick (in the browser's localStorage). The Overview is
161
+ fleet-wide: each install's own facts (voice, footprint, posture, mode, local edits) sit on
162
+ its row, and a figure still read off a project install set as the default (a suggestion, a lens)
163
+ names that install once two or more are active. A *Needs you*
164
+ suggestion about a shared file or the shared memory store appears once and names no harness.
165
+
166
+ The Loaded every turn card also shows the session-start hook output against its 9 000-character
167
+ budget, measured without project context, for the install whose content was cut, else the
168
+ largest. It turns amber at 85% of the budget or whenever content was cut, and Needs you adds one
169
+ suggestion at the same point.
126
170
 
127
171
  A global **Spotlight** search lives in the topbar — press <kbd>/</kbd> to focus it (or
128
172
  <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd>, which also works from inside a text field), type
@@ -136,10 +180,14 @@ streams the output of background jobs and keeps their history across reloads.
136
180
 
137
181
  ### Dashboard
138
182
 
139
- - **Dashboard** (`#/`) — a live readout of what's deployed. Three lenses: **Status**
140
- (readiness ring, a KPI band, a genome grid, recent activity), **Lineage** (the
141
- source → render → deployed timeline and the genome-by-volume strand chart), and
142
- **Operator** (a searchable table of every deployed capability). Every lens hero carries the
183
+ - **Overview** (`#/`) — the header's **View** control is the one home of the lens: **Overview** (the
184
+ Ledger), **Genome**, **Greenhouse**, **HUD** and **Journal**. A lens never takes a skin's name, and
185
+ a browser that stored the old `cultivar` or `operator` keeps its lens (`resolveLayout`). All five
186
+ views share one header: the title, the install count, the version chip and the View control.
187
+ Beside the Ledger, a lens has a row with the facts it reads and *Run doctor* and *Rebuild*, then
188
+ three sub-views: **Status** (laid out by the lens), **Lineage** (the source → render → deployed
189
+ timeline and the genome-by-volume strand chart), and **Readout** (a searchable table of every
190
+ deployed capability). Every lens hero carries the
143
191
  fleet verdict badge (the Ledger's `fleetVerdict`). The headline speaks the theme's voice only
144
192
  while that verdict is good or still loading; a warn, bad or unreachable fleet reads plain
145
193
  *Deployed*. Recent-run previews read `verb · scope · result · duration`, and the raw command
@@ -149,21 +197,25 @@ streams the output of background jobs and keeps their history across reloads.
149
197
  labelled *Dictates* (the name AGENT.md gives the laws) and not *Constitution* on purpose: its value is the law count
150
198
  alone, and calling it the constitution would under-report the ontology and the doctrine
151
199
  packs. The two Status *layouts* that have room for it add the missing half: Greenhouse
152
- puts an active-packs fraction under the tile (`3/4 packs · N rules`), and the Operator HUD
200
+ puts an active-packs fraction under the tile (`3/4 packs · N rules`), and the HUD
153
201
  gives it its own cell (`PACKS 3/4`). That is what makes a narrowed install *look* different
154
202
  from a full one at a glance.
155
203
 
156
204
  ### 📖 Codex
157
205
 
158
206
  - **Rules** (`#/rules`) — your own standing rules, read from and written to the
159
- `user-rules.md` beside the deployed AGENT.md (the seed-once file no update ever
160
- touches) of every active install, listed together and tagged with their install; an edit,
161
- graduate or retire writes back to the rule's own install, and a new rule goes to the install
162
- its form's *Write to:* picker names. List with scope (project/global — a hand-written `user` opens as global — or any other scope written by hand, which a
207
+ `user-rules.md` (the seed-once file no update ever touches): the shared file every global
208
+ install reads, listed once under a `shared` head, beside each project install's own, under its
209
+ install's name. An edit, graduate or retire writes back to the rule's own file, and a new rule goes
210
+ to the file its form's *Install:* picker names. List with scope (project/global — a hand-written `user` opens as global — or any other scope written by hand, which a
163
211
  save keeps as written) and trial chips, add/edit/retire forms (retire moves the rule to `user-rules-retired.md`, which is never loaded; its id is never reused) (a body line starting
164
212
  `## ` is refused: the file would read it as a new rule heading), a
165
- **Graduate** action that adopts a trial rule for good, and a budget meter that turns
166
- amber as the always-loaded set gets heavy. Every write carries the fingerprint of the
213
+ **Graduate** action that adopts a trial rule for good. Each rule row shows its token cost
214
+ (code points / 4 of its own block), and each list's head shows the one rule count and total, such
215
+ as `4 rules · ≈1,055 tokens every turn · scope global unless marked`, which counts the file's
216
+ header too. A row shows a scope only when it differs from that. There is no ceiling.
217
+ A **Pending** section lists what waits undecided in `user-rules.draft.md`: read-only, because
218
+ the rule skill alone decides a draft, and a pending rule still binds on its host. Every write carries the fingerprint of the
167
219
  content the page last read — if an agent session edited the file meanwhile, the save
168
220
  409s and the page reloads instead of clobbering it.
169
221
  - **Constitution** (`#/laws`) — the whole governance surface on one page, in three bands:
@@ -174,23 +226,38 @@ streams the output of background jobs and keeps their history across reloads.
174
226
  secrets gate, the done gate and the deletion gate (`--no-secrets-gate`, `--no-done-gate`,
175
227
  `--no-deletion-gate`; *Enforced by* reads *Gate off* while one is off) — flipping one asks,
176
228
  then rebuilds the install once; the other Rules read *no gate*. The ownership gate belongs
177
- to no Rule, so it has no switch here: rebuild with `--no-ownership-gate` instead. A precedence ladder heads the page (a state pill per rung; ranks 5–6 below). *Gated* and *Changed* narrow the rows; packs fold; staged doctrine changes collect in a sticky *Unapplied changes* bar that holds Revert and the page's one Apply. Every row expands to its full body, lazily fetched. The rail entry is
178
- labelled *Constitution* while the route, the id and the badge key stay `laws`; deep links
179
- are `#/item/law/ont:telos`, `#/item/law/IV` and `#/item/law/process.5` — three address
180
- shapes that cannot collide, because a slug carries a colon no numeral has and a doctrine
181
- address carries a dot.
182
- - **Library** (`#/library`) — browse the content that has no tab of its own: **Memory ·
183
- Notebook · Knowledge** (the wiki chip, which also carries the two setup manifests).
184
- Constitution, Skills and Agents each have their own rail entry instead. Drill into a section, then an item, to read its
185
- rendered markdown body and follow its cross-links. On a memory fact, a **Forget this
229
+ to no Rule, so its switch (`--no-ownership-gate`) sits inside the Ethos band's *Ownership*
230
+ row and works the same way. Closed, the row reads *Always* (the section's text binds whatever
231
+ the gate does) and *Hook gate* or *Gate off*. Open, it shows the text, then a gate line with
232
+ the gate's asks and the switch. That line exists only in the console and only where an install
233
+ can be rebuilt: with no install the row reads *Instruction*. The gate counts in *Gated* but
234
+ not as a Rule or a section, and the Ethos rank's pill counts it while it is off. Every tab,
235
+ view and filter shows the row, like the sections around it.
236
+ A precedence ladder heads the page (a state pill per rank; ranks 5–6 below). *Gated* and *Changed* narrow the rows; packs fold; staged doctrine changes
237
+ collect in a sticky *Unapplied changes* bar that holds Revert and the page's one Apply.
238
+ Every row expands to its full body, lazily fetched. The rail
239
+ entry is labelled *Constitution* while the route, the id and the badge key stay `laws`; deep links
240
+ are `#/item/law/ont:telos`, `#/item/law/IV`, `#/item/law/process.5` and `#/item/law/ownership` — address
241
+ shapes that cannot collide, because a slug carries a colon no numeral has, a doctrine
242
+ address carries a dot, and `ownership`, which opens the Ownership row at its gate, is a word
243
+ no rule uses.
244
+ - **Library** (`#/library`) — browse the catalogue: **Skills · Agents · Wiki · Setup files**.
245
+ Constitution has its own rail entry, and Memory and Notebook are Personal's tabs, their one home:
246
+ the same reader, locked to one kind, with one empty state each. Drill into a section, then an item, to read its
247
+ rendered markdown body and follow its cross-links. On a memory fact in Personal, a **Forget this
186
248
  fact** control deletes it (token-gated; bare-slug guarded server-side), and a
187
249
  **Promote to rule** control turns a recurring lesson into a trial rule in
188
250
  `user-rules.md` — provenance recorded, the source fact deleted so it isn't loaded
189
- twice — landing you on the Rules page.
251
+ twice — landing you on Personal's Rules tab.
190
252
  - **Kits** (`#/kits`, `#/kits/<kit>`) — a card per shipped kit over a kits × installs matrix of
191
253
  switches; a staged-changes bar applies one install at a time (the server runs one job at a
192
254
  time). `#/kits/<kit>` is the kit's page: rules, word budget, banned APIs, upstream credits,
193
- members and one switch per install.
255
+ members and one switch per install. This page is the one home of the kit switches. Toggling only
256
+ stages the set; **Apply** asks first, then rebuilds that install with exactly that set as a console
257
+ job. Staged switches are held for the whole console: they survive leaving the page. A refetch drops
258
+ a row's staging only when that install's kits changed. A failed rebuild keeps it and says so, and
259
+ a reload asks first while anything is staged. Files you edited in a kit that is now off are kept,
260
+ and the matrix lists them under their install.
194
261
  `GET /api/kits` carries `rules`, `rulesWordBudget`, `banned` and `credits` per kit; the
195
262
  catalog and item endpoints for skills and agents carry `kit` (the owning kit or `null`),
196
263
  which the Library shows as a `kit:` badge.
@@ -211,7 +278,7 @@ streams the output of background jobs and keeps their history across reloads.
211
278
  for *mutate*, *human gate*, what they override and *unavailable*; the reader shows the
212
279
  frontmatter facts (outcomes as pills, availability with its reason), then the body rendered as
213
280
  markdown, with a **View source** toggle for the file as parsed, frontmatter and all. Templates and
214
- Bricks read `GET /api/loops` for the install the page's *Templates and bricks of:* picker
281
+ Bricks read `GET /api/loops` for the install the page's *Install:* picker
215
282
  names (its own remembered pick, starting on the default; hidden with one install and on
216
283
  Active), resolved from that install's root, so a project install shows its `.geneseed/` bricks
217
284
  and templates. **Active** is every loop
@@ -221,25 +288,27 @@ streams the output of background jobs and keeps their history across reloads.
221
288
  the page's only write), what an awaiting loop waits on (launch / declared / actual / a
222
289
  human gate, with its node) — the answer is given in the agent's session, never here — and
223
290
  its ring with the current node filled, with its iteration history under it.
224
- - **Profile** (`#/profile`) — `PROFILE.md` beside the deployed AGENT.md: who you are and
225
- how you like to work, one card per active install, each saving to its own. Opens rendered; **Edit** is a whole-file editor. The save carries
291
+ - **Profile** (`#/profile`) — `PROFILE.md`: who you are and how you like to work, one card
292
+ per file: the shared one every global install reads, tagged `shared`, and each project
293
+ install's own. Opens rendered; **Edit** is a whole-file editor. The save carries
226
294
  the fingerprint it loaded — if an agent session changed the file first, your edit stays
227
295
  on screen and a second Save replaces the newer version.
228
296
  - **Skills** (`#/skills`) and **Agents** (`#/agents`) — the deployed catalogue of every
229
297
  installed harness, each entry with its purpose line and full spec. Each row is one skill or
230
298
  agent; when more than one install is active, it carries a badge for each install that has it
231
299
  (`opencode · global`; a project install by its folder). The reader shows the first install's copy. When more installs have the entry,
232
- a **Viewing copy from** picker beside the copy opens another install's version, for that
233
- entry only. While Skills is selected, its skill types sit nested
300
+ an *Install:* picker beside the copy opens another install's version, for that entry only. While Skills is selected, its skill types sit nested
234
301
  under it in the rail, each with its count, above a thin bar of their shares; pick one to
235
- narrow the list.
302
+ narrow the list. A skill the registry does not know sits under *Custom*.
236
303
  - **Docs** (`#/docs`) — rendered documentation: markdown pages, concept pages, a CLI
237
304
  reference (generated from the harness argument parser), and a glossary, in a reader: one
238
305
  nav column holding the parts (Understand / Guides / Concepts / Reference) with their page
239
306
  counts, the open part's sections (pick one to narrow the list) and the part's pages with a
240
307
  filter; then the page, with its breadcrumb, section and reading time, a Copy button on each
241
308
  code block, an outline that marks the heading being read, and Previous / Next within the
242
- section. Filtered for one host (OpenCode, Claude
309
+ section. On a phone the page comes first and the parts and pages follow, in the DOM as on screen.
310
+ A page's title is its H1 and its first heading an H2, whatever level the source starts at.
311
+ Filtered for one host (OpenCode, Claude
243
312
  Code, Bob or OpenClaude; Claude-family pages show to all three Claude-engine hosts, a page
244
313
  tagged with a list of hosts only to those); with no
245
314
  choice stored it follows the deployed install.
@@ -272,30 +341,32 @@ streams the output of background jobs and keeps their history across reloads.
272
341
  are tied together in red (same worktree) or dashed amber (two worktrees of the repo): tangled
273
342
  roots in the moss when they stand side by side, a thread under the pots when they do not.
274
343
  Hover a tree for its model, turns, context and compactions, or a pad for its author's files;
275
- click it to open the session. Past ten trees, quiet shelves (no session working or waiting on
276
- you) fold into chips, the largest first; the last standing shelf never folds. **Sakura** repaints the crowns pink, nothing more.
344
+ click it to open the session. With no mouse, tap a pad to show its files (a second tap clears them,
345
+ and neither opens the session), or focus the tree and walk its pads with the arrow keys; Escape leaves. Past ten trees, quiet shelves (no session working or waiting on
346
+ you) fold into chips, the largest first; the last standing shelf never folds. **Pink blossom** repaints the crowns pink, nothing more.
277
347
  A session's detail page shows its tree too, live or ended, with the same pad hovers and a
278
348
  legend of its turns, context, compactions and sub-agents; an ended session's tree stands still, without the `!`.
279
- - **Changes** (`#/diff`) — the diff between the install its *Local edits of:* picker names and the source: edited /
349
+ - **Local edits** (`#/diff`) — the diff between the install its *Install:* picker names and the source: edited /
280
350
  added / missing files, and files only behind the source (unedited; a rebuild updates them)
281
351
  listed apart under **Behind source**, with per-file expansion and coloured unified-diff lines. Select
282
352
  files to **export an `improvements.md`** back-port, or **restore** them to source.
283
353
  Restore acts only on files the diff lists, and never on your own files (`user-rules.md`,
284
354
  `PROFILE.md`, `memory/`, `notebook/`). An added file is moved into
285
355
  `archived-restore/<date-time>/` in the install, not deleted.
286
- - **Doctor** (`#/doctor`) — runs, for the install its *Doctor for:* picker names, the same health engine as the `doctor` command (every
287
- theme, parity, links, authoring gates, drift), grouping any problems per check. It shows
356
+ - **Doctor** (`#/doctor`) — runs, for the install its *Install:* picker names, the same health engine as the `doctor` command (that
357
+ install's voice, parity, links, authoring gates, local edits), grouping any problems per check. It shows
288
358
  the server's last run for that install — warmed at start, redone after a job or an install
289
- toggle — and **Re-run checks** runs every check again on demand.
359
+ toggle — and **Run doctor** runs every check again on demand.
290
360
 
291
361
  ### 🎨 Setup
292
362
 
293
- - **Harness** (`#/harness`) — this machine's own install first (path, voice, footprint,
363
+ - **Hosts** (`#/installs/hosts`; `#/harness` resolves here) — this machine's own install first (path, voice, footprint,
294
364
  and when it was built), then the **Voice** reference, then every detected install. A
295
365
  **Sync with source** column says whether each install is behind the source (and by how many
296
- files), in sync or not checked, shows hand edits apart from stale files, and links to Local edits.
366
+ files), in sync or not checked, shows local edits apart from stale files, and links to Local edits.
297
367
  `#/harnesses` and `#/themes` both still resolve here, so old links and bookmarks keep
298
- working.
368
+ working. *Make default* on an active row sets the default install (above), and a per-repo
369
+ install's panel has the **Shared tier** switch, with its benefit and cost beside it.
299
370
  - The **Voice** card is the former Themes tab, kept as a REFERENCE rather than a second
300
371
  control: a collapsed row that opens to every shipped voice with its tagline, the
301
372
  deployed one pinned first and marked. It is the one place you can read what a voice
@@ -305,7 +376,8 @@ streams the output of background jobs and keeps their history across reloads.
305
376
  - **Every install** lists each detected install (host × scope), one row each. An
306
377
  ACTIVE row carries per-row **Voice**, **Footprint**, **Posture** and **Mode**
307
378
  pickers plus **Apply**, an on/off switch, and remove; a host that is NOT installed
308
- yet shows a single **Install…** that discloses the same four choices as steps.
379
+ yet shows a single **Install…** that discloses the same four choices as steps. The panel is the
380
+ footprint's one home: a line under the pickers says what the chosen footprint does.
309
381
  **Posture** is the relationship register (peer/mentor/expert/assistant/artisan —
310
382
  default **peer**); **Mode** is the operating register (direct/foreman — default
311
383
  **direct**; foreman triages tasks into isolated pipelines instead of working every
@@ -315,21 +387,17 @@ streams the output of background jobs and keeps their history across reloads.
315
387
  card (shown once a global install exists) manages sovereign repos — folders where every
316
388
  global harness goes dormant (hooks stay silent, the global preamble never loads);
317
389
  add or remove one here, the web mirror of `harness exclude add|remove|list`.
318
- - **Kits** (`#/installs/kits`) — every install (disabled ones read-only) as a panel with one switch per kit.
319
- Toggling only stages the set; **Apply** asks first, then rebuilds that install with
320
- exactly that set as a console job. Staged switches are held for the whole console: they
321
- survive leaving the page, and the Kits page and Installs › Kits share them. A refetch drops a
322
- row's staging only when that install's kits changed. A failed rebuild keeps it and says so,
323
- and a reload asks first while anything is staged. Files you edited in a kit that is now off are kept,
324
- and the row lists them.
325
- - **Server** (`#/installs/server`; `#/settings` and `#/about` resolve here) — a settings sheet
326
- with a section index. **Appearance**: skin, accent (a skin change resets it to the skin's own), Overview view. **Machine**:
390
+ - **Settings** (`#/settings`; `#/about` and `#/installs/server` resolve here) — a rail entry of its
391
+ own, about the tool and never one install: a sheet with a section index. **Machine**:
327
392
  version + Update (labelled by how this copy updates: git pull, npm install -g, or the command
328
- to run by hand), Add to PATH, the footprint of the install the head's *Footprint of:* picker names (read-only, links to Hosts). **Server**: running · port ·
393
+ to run by hand; on the Overview the button shows only when the pull can run), Add to PATH. **Server**: running · port ·
329
394
  pid · uptime, whether the code matches the disk (with Restart), start-at-login state (read
330
395
  only), and the four request guards; the index marks Server with a good/warn dot. **About**: version, changelog, credits, source, creator.
331
396
  **Danger zone**: Stop server, Remove from PATH, and a pointer to each install's own
332
397
  Uninstall in Hosts.
398
+ - **Appearance** (the topbar's popover, on every page) — the one home of the skin and the accent (a
399
+ skin change resets it to the skin's own), each with a line that says what it does. Both are this
400
+ browser's alone, and nothing here rebuilds.
333
401
 
334
402
  ## Rebuilding the UI
335
403
 
@@ -2,5 +2,5 @@
2
2
  "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
3
3
  "theme": "neutral",
4
4
  "product": "Geneseed",
5
- "version": "4.31.0"
5
+ "version": "5.0.0"
6
6
  }
package/js/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # `js/` — the module map
2
2
 
3
- Every module under `js/`, in eight folders. This page is the address book: **what each one owns**, and
3
+ Every module under `js/`, in eight folders. For how to prove a change, read the repo guide, [`AGENTS.md`](../AGENTS.md), first. This page is the address book: **what each one owns**, and
4
4
  **which file to open first** for a given task. It is not documentation of behaviour — every module
5
5
  has a docblock for that, and the docblock is the thing to read before editing.
6
6
 
@@ -13,7 +13,7 @@ a module that does not exist, is a test failure. `geneseed doctor` reports the s
13
13
 
14
14
  ```
15
15
  bin/geneseed-cli.mjs the `geneseed` CLI — 20+ verbs, may NOT spawn
16
- bin/geneseed-hook.mjs the hook entry — 5 verbs, loads on EVERY tool call (~14 ms)
16
+ bin/geneseed-hook.mjs the hook entry — 6 verbs, loads on EVERY tool call (~14 ms)
17
17
  bin/build-driver.mjs `geneseed-build` — a thin entry over js/build/driver.mjs
18
18
 
19
19
  js/build/ src/ + themes/ → rendered text → a bundle → a per-host install
@@ -64,6 +64,7 @@ as a per-host install at project or global scope.
64
64
  | `emit-claude.mjs` | The Claude/Bob/OpenClaude emit — the render half plus the settings + CLAUDE.md managed-block wire |
65
65
  | `emit-opencode.mjs` | The OpenCode emits — a project's `.opencode/` and the global config dir. Deliberate twin of the above |
66
66
  | `emit-common.mjs` | Constants, tree walkers, and the three writers BOTH global emits share. Decides no host |
67
+ | `fold.mjs` | The fold: moves a global install's stores into the shared tier, in the emit. Moves aside, never deletes; a second run writes nothing |
67
68
  | `stubs.mjs` | Write-once seed files: context, wiki, rules, excludes, profile, `.gitignore`, memory/notebook indexes |
68
69
  | `version.mjs` | The release marker: fingerprint the sources, read/compare/write an install's version, warn on downgrade |
69
70
  | `driver.mjs` | The generator driver: the nine emit targets, per-host emit orchestration, the prune and the manifest. `bin/build-driver.mjs` is only its entry |
@@ -90,15 +91,16 @@ user co-owns, and the hook verbs those emitted configs then run.
90
91
  |---|---|
91
92
  | `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), their `family` (`CLAUDE_STYLE`), plus `resolvePath`/`expanduser` |
92
93
  | `hooks.mjs` | The gate verbs, run on every tool call: `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), plus `ask`/the gate ledger/`guardGate`. `--host` picks the verdict dialect |
93
- | `hooks-context.mjs` | The `context` verb — SessionStart: session files plus the repo's context docs |
94
+ | `hooks-context.mjs` | The `context` verb — SessionStart: session files (shared tier first on a global install, wiki rendered) plus the repo's context docs; `sessionStartSize`, the console's read of the same payload |
94
95
  | `ownership-gate.mjs` | The ownership first-write gate, last in `rule-gate`: in an application repo (git root + build manifest) whose root `AGENTS.md` has no `## Ownership` section, denies the session's first write once (a tmpdir marker per session). Builtins + `gitRootOf` only. Twin: the OpenCode guard plugin |
95
96
  | `hooks-done.mjs` | The done gate (#289): on Stop, inside `learn` and before its spawn, judges a turn that edited files against the project's checks — blocks until `.geneseed/done-checks.txt`'s checks passed after the last edit; without that file, the inferred checks are advisory (a `systemMessage`, never a block) |
96
97
  | `done-checks.mjs` | Where the done gate's checks come from: `.geneseed/done-checks.txt`, else inferred from the git root's manifests (package.json scripts, pom.xml, Gradle, pyproject.toml, Cargo.toml, go.mod), each a group of accepted command forms; plus `doneLine`, the SessionStart line `context` prints. Spawn-free: `context` is in the CLI's closure. Twin: the OpenCode context plugin |
97
98
  | `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
98
99
  | `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`), plus the activity off switch (`activityOn`) and the do-nothing `activity` verb |
100
+ | `store-watch.mjs` | The change report: a session's baseline of the rule and memory files (`writeBaseline`, from the hook entry after `context`), the compare at Stop (`storeReport`, from `learn`), and `recordOwnWrites`, around Geneseed's own writers. It detects; it prevents nothing. The OpenCode guard holds the twin |
99
101
  | `activity.mjs` | The hook-side activity writer and the owner of snapshot liveness: `recordActivity` (one payload into `<root>/activity/`), `readTranscriptDelta`, `sweepActivity` (archive, newest 50, 7 days). Loaded only when tracking is on; never prints |
100
102
  | `usage.mjs` | The usage counter `tool-gate` runs: one `{day, kind, name}` line per Skill or subagent call into `notebook/usage.jsonl`. Hook path: builtins only, silent, never throws |
101
- | `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate. No spawn: the CLI and web console import it |
103
+ | `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate — the `user-rules.md` parser, the draft's format and the fold's ledger reader. No spawn: the CLI, web console and fold import it |
102
104
  | `geneseed-dir.mjs` | The Node writers into a project's `<git root>/.geneseed/`: the personal-by-default `.gitignore` (`GENESEED_GITIGNORE`, pinned to the two OpenCode copies), and the protected-checks seed every project emit runs (`seedProtectedChecks`: seed once when absent, then the user's — never recorded, rewritten or uninstalled). Never throws, never writes through a link. Spawn-free |
103
105
  | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `gitCommonDirOf`, `currentBranch`, `protectedBranches`, `stashExists`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate, `loss.mjs` and `js/loop/cli.mjs`'s commit-message writer |
104
106
  | `loss.mjs` | Law IV calibrated to real loss: `lossReason` decides whether a command would really lose data (protected branch, unpushed branch, dirty tree, stash, reflog, files git cannot restore) and fails closed. The gate path's one `git` spawn, reached only after `LOSS_CANDIDATE_RE` matched. Twin: the OpenCode guard plugin |
@@ -137,7 +139,7 @@ Everything that inspects an already-built or already-deployed harness and report
137
139
  | `status.mjs` | `geneseed status` and `version` — the panel data, counts, accent colour, version verdict |
138
140
  | `cost.mjs` | What one install injects every session, by part (root file, skill and agent lists, session files), in characters; owns `CARRIER_CEILING`, which the smoke test gates and the console draws |
139
141
  | `diff.mjs` | `geneseed diff` — what a deployed install has that a fresh render of `src/` does not |
140
- | `excludes.mjs` | `geneseed exclude add|remove|list` — the WRITER for `excludes.json`; `hooks.mjs` only reads it |
142
+ | `excludes.mjs` | `geneseed exclude add|remove|list` — the WRITER for `excludes.json` and the shared list in the machine tier; `hosts.mjs` `sovereignBypass` reads both |
141
143
  | `registry.mjs` | `installs.json` under XDG — the persistent deploy-root list `rebuild-all` re-emits into |
142
144
  | `scorecard.mjs` | `geneseed scorecard` — a port of the AI Harness Scorecard (upstream pinned in its docblock): the repo walk, the CI-YAML parsing, `assessRepo`, the text/JSON renderers. Pure: no spawn, no network |
143
145
  | `scorecard-yaml.mjs` | The YAML 1.1 subset the scorecard reads CI configs with, plus Python's `str()`/`bool()` over its values; `scorecard.mjs` re-exports it. Its ceiling is in its `ponytail:` note |
@@ -164,6 +166,7 @@ into files users have committed, so change the test that states it in the same c
164
166
  | `udiff.mjs` | `geneseed diff`'s own difflib clone — the alignment IS the printed hunks — plus `splitLines` |
165
167
  | `proc.mjs` | One constant: the `windowsHide` flag every spawn in `js/` must reuse |
166
168
  | `prompt.mjs` | The line-mode stdin readers — `ask`, `promptLine`, `confirm`, `askChoice` — read a byte at a time so they stop where Enter stops. Shared by `setup`, `uninstall` and `web` without dragging in the wizard |
169
+ | `machine-dir.mjs` | `machineDir()`, `sharedPaths()`, `readDefaultInstall()` and `WIKI_NAMES`: the one home of `$XDG_CONFIG_HOME/geneseed`, the names beneath it, the reader of the chosen default install, and the wiki manifest's names. Spawn-free, so the hook and driver may import it |
167
170
  | `node-floor.mjs` | The first import of all three binaries: below Node 22.7, one sentence on stderr and exit 1 (0 in the hook) instead of a stack trace |
168
171
 
169
172
  **Before editing:** parse with `parseJson`, never `JSON.parse` — the latter collapses int `1` and
@@ -205,7 +208,7 @@ Verbs that change an install that already exists, as opposed to rendering one.
205
208
 
206
209
  | module | owns |
207
210
  |---|---|
208
- | `update.mjs` | `upgrade`/`sync-self`/`bootstrap` — git pull, doctor gate, rebuild, each via a respawn |
211
+ | `update.mjs` | `upgrade`/`bootstrap` — git pull, doctor gate, rebuild, each via a respawn |
209
212
  | `setup.mjs` | The install wizard. Its prompts go through `js/lib/prompt.mjs`'s stdin readers |
210
213
  | `uninstall.mjs` | Removes or disables an install: manifest-driven reversal, plus stash deactivate/reactivate |
211
214
  | `migrate.mjs` | `geneseed migrate` — all-or-nothing re-emit moving installs onto the npm install shape |
@@ -240,6 +243,7 @@ the deployed harness as JSON.
240
243
  | `server.mjs` | `serve()`/`cmdWeb`: UI-build precheck, socket bind, token mint, daemon record wiring |
241
244
  | `routes.mjs` | The route tables — `STATE_ROUTES`, `PREFIX_ROUTES`, `POST_ROUTES` (+ its 409 column) — and the inline lists |
242
245
  | `handler.mjs` | One function per request: per-request install (`?host=&path=` on every read but `MACHINE_GETS`, or the body on `VIEW_POSTS`), dispatch, gzip, `requestGuard` (Host+port, Origin/Sec-Fetch-Site on `/api`, constant-time CSRF token) and body cap (before the body is read), `securityHeaders` (CSP nonce, framing), static SPA fallback |
246
+ | `doctor-worker.mjs` | The warm-up doctor's thread: one `doctorCollect`, one message back (`warmDoctor` in `state.mjs`) |
243
247
  | `state.mjs` | `webState` — the resolved install view every endpoint reads, with its cached inventory and doctor, `defaultView` (the install a request naming none reads) and `fleetSort` (the one install order); per-install views (`installView` in `actions.mjs`) hang off it, pinned, refreshed with it |
244
248
  | `catalog.mjs` | The Library read model: inventory, constitution tiers, memory/notebook/wiki/config items, `apiCatalog`/`apiItem`, `NotFound`. Skills and agents are listed across every active install (`FLEET_SECTIONS`; `routes.mjs` builds the fleet), each item served from one install's copy |
245
249
  | `api.mjs` | The dashboard and settings reads: overview, recent, themes, setup, doctor, diff, installs, excludes, loops |
package/js/build/args.mjs CHANGED
@@ -23,12 +23,12 @@ const EMITS = ['files', 'opencode', 'opencode-global', 'claude', 'claude-global'
23
23
  'bob', 'bob-global', 'openclaude', 'openclaude-global'];
24
24
 
25
25
  /**
26
- * build.py:307-321 — the three defaults that come from `harness.config.json`.
26
+ * The three defaults that come from `harness.config.json`.
27
27
  *
28
28
  * The corrupt-file branch is reproduced including its imprecision: the warning says only
29
- * "using theme 'neutral'", but the branch also resets posture and mode. Matching the
30
- * Python text mattered more than fixing it here, because the two CLIs' stderr was compared
31
- * byte-for-byte by the former Python golden harness; nothing pins the wording now.
29
+ * "using theme 'neutral'", but the branch also resets posture and mode. The wording
30
+ * stays as it was: stderr was once compared byte-for-byte across the two CLIs, and nothing
31
+ * pins it now.
32
32
  */
33
33
  export function configDefaults() {
34
34
  const d = {
@@ -97,7 +97,7 @@ export function configDefaults() {
97
97
  const VALUED = {
98
98
  '--theme': 'theme', '--posture': 'posture', '--mode': 'mode', '--trust': 'trust',
99
99
  '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules', '--exclude-skills': 'excludeSkills',
100
- '--kits': 'kits',
100
+ '--kits': 'kits', '--shared-tier': 'sharedTier',
101
101
  '--out': 'out', '--target': 'out', '--emit': 'emit',
102
102
  '--footprint': 'footprint', '--root': 'root', '--config-dir': 'cfgDir',
103
103
  };
@@ -151,6 +151,7 @@ function choicesFor() {
151
151
  '--posture': discoverNames('postures', 'peer'),
152
152
  '--mode': discoverNames('modes', 'direct'),
153
153
  '--trust': Object.keys(PRESETS),
154
+ '--shared-tier': ['on', 'off'],
154
155
  };
155
156
  }
156
157
 
@@ -333,6 +334,7 @@ export function parseArgs(argv, defaults) {
333
334
  excludeRules: defaults.excludeRules,
334
335
  excludeSkills: defaults.excludeSkills ?? [],
335
336
  kits: defaults.kits ?? [],
337
+ sharedTier: 'off',
336
338
  out: 'Harness', emit: 'files', footprint: 'lean', root: null,
337
339
  syncThemes: false, validateOnly: false, verbose: false,
338
340
  ...Object.fromEntries(GATE_SWITCHES.map((g) => [g.arg, false])),
@@ -385,7 +387,7 @@ export function parseArgs(argv, defaults) {
385
387
  *
386
388
  * `geneseed validate` takes every render flag but `--sync-themes`/`--config-dir` (it refuses
387
389
  * those two, and prints its own `-h` before this parser can print the generator's) — the reference's
388
- * `--validate-only` reads exactly the flags `build.py`'s parser already produced, so the port
390
+ * `--validate-only` reads exactly the flags this parser produces, so validate
389
391
  * hands the CLI this parser rather than a second one beside it. That is not tidiness: a
390
392
  * hand-rolled copy would have its own `--target` alias, its own `choices` lists and its own
391
393
  * `-h`, and `tests/unit/node_driver.test.mjs`'s '--help names every flag the parser takes' gates only
@@ -409,8 +411,8 @@ function choice(flag, value, allowed) {
409
411
  * argparse's error exit — a THROW since P5f, where it used to be `process.exit(code)`.
410
412
  *
411
413
  * `harness rebuild-all` re-emits every active install and its whole contract is "continue
412
- * past a failure so one broken install never blocks the rest". The Python gets that for free:
413
- * each rebuild is a SUBPROCESS, and a child that exits 2 hands back a return code. Here the
414
+ * past a failure so one broken install never blocks the rest". A subprocess per rebuild would
415
+ * get that for free, since a child that exits 2 hands back a return code. Here the
414
416
  * driver is a module in the same process, so `process.exit` would take the loop, the CLI and
415
417
  * every remaining install with it — the one place where importing rather than spawning is not
416
418
  * transparent, and it turns a per-install failure into a total one.