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
@@ -21,8 +21,10 @@ brick's behalf. This applies to `plan` and `review` as much as to the newer bric
21
21
  brick whose finding the next brick needs writes it to a file in the OS temp directory and reports
22
22
  that file's path with the outcome.
23
23
 
24
- One exception keeps the verdict fresh: each `test` report replaces every earlier `test` note, so a
25
- repair reads only the findings for the code as it stands, never a trace from an older version.
24
+ Two exceptions keep the verdict fresh: each `test` report replaces every earlier `test` note, so a
25
+ repair reads only the findings for the code as it stands, never a trace from an older version; and
26
+ when `apply` reports, every `review` and `mutation-check` note goes, since `apply` has just acted
27
+ on those findings.
26
28
 
27
29
  ## `description` and `rules`: what a template is for, and what every brick must do
28
30
 
@@ -10,8 +10,8 @@ The loop templates Geneseed ships. Each is a graph of [bricks](loop-bricks.md) w
10
10
 
11
11
  | template | purpose | when to use |
12
12
  |---|---|---|
13
- | `bugfix` | reproduce, fix, test, review a defect | a reported bug with a reproduction step |
14
- | `feature` | plan, then build and review in small iterations | new behaviour with no existing test pinning it |
13
+ | `bugfix` | reproduce, fix, test, mutation-check, review a defect | a reported bug with a reproduction step |
14
+ | `feature` | plan, then build test-first and review in small iterations | new behaviour with no existing test pinning it |
15
15
  | `refactor` | restructure behind the existing tests, no behaviour change | the tests already cover the code you're moving |
16
16
  | `tdd` | plan, then write each failing test before the code that passes it | you want the test written first, every iteration |
17
17
  | `legacy-tests` | pin undocumented behaviour with characterization tests, mutation-checked, production code untouched | code with no tests and no spec, before anyone risks changing it |
@@ -30,12 +30,15 @@ The loop templates Geneseed ships. Each is a graph of [bricks](loop-bricks.md) w
30
30
  maps every acceptance criterion to a passing test (or a stated manual check) and reports `fail`
31
31
  with what's missing rather than trusting the iterations that already ran.
32
32
 
33
+ `feature` writes each card's failing test first, through `red-test`, as `tdd` does: the card's write
34
+ set must name a test file, and `untestable` stops the loop.
35
+
33
36
  `legacy-tests` and `legacy-refactor` both open on `baseline-green` — the suite must already be
34
37
  green before either template pins anything, and `baseline-green` reporting `fail` stops the loop
35
38
  rather than characterizing a change no one can tell from existing breakage.
36
39
 
37
- `mutation-check`, inside `legacy-tests`, needs a mutation tool on the stack (Stryker, PIT, mutmut,
38
- cargo-mutants) to prove the new characterization tests actually bite. With none configured it
40
+ `mutation-check`, inside `legacy-tests` and `bugfix`, needs a mutation tool on the stack (Stryker, PIT,
41
+ mutmut, cargo-mutants) to prove the new tests actually bite. With none configured it
39
42
  reports `unavailable` rather than a silent `pass` — and still writes a note saying what it checked,
40
43
  so the gap is visible in `LOOP.md` rather than just absent from it.
41
44
 
@@ -54,6 +54,9 @@ rings (`apply-test`, `fix-test`, `write-run`, `stabilise`) are `max: 2`: two rep
54
54
  attempt is discarded for one fresh try, then the loop stops for you. Most of the gain is in the
55
55
  first revision — 0.82 correct after one, 0.673 after two (arXiv 2607.24604) — but a second still
56
56
  lands fixes the first missed, so it is kept as the last chance, and nothing past it.
57
+ `review-fix` stays at `max: 3`, a deliberate exception to the two-repair rule of Bound the Loop: a
58
+ review round is a verdict from a separate reviewer, not a blind repair of one's own red test. In
59
+ `bugfix` the same budget also pays for `mutation-check` repairs, each one a mutation tool's verdict.
57
60
 
58
61
  **`error` always stops.** A brick may declare the outcome `error` without an edge for it; the
59
62
  engine sends it to `$stop`. The shipped `test` brick reports it when a check crashed or its
@@ -48,7 +48,7 @@ On every host, a hook stops the first write in an application that has not decid
48
48
 
49
49
  - **Where.** An *application repo*: a git root holding a build manifest — `package.json`, `pom.xml`, `build.gradle*`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `*.csproj`, `composer.json` or `Gemfile`. A folder with no git or no manifest is never gated.
50
50
  - **When.** Its root `AGENTS.md` has no `## Ownership` heading outside Geneseed's managed block, and your personal `.geneseed/ownership.md` holds no `Setup: declined <YYYY-MM-DD>` line. The heading with `mode: on` or `mode: off` both count: the team has decided.
51
- - **What.** The first Write, Edit or NotebookEdit of the session in that repo is refused once. The refusal's reason goes to the agent, which then asks you: set ownership up now, skip this session, or skip in this repo until you ask. The next write passes. Writes to `AGENTS.md` and `.geneseed/` themselves always pass.
51
+ - **What.** The first Write, Edit or NotebookEdit of the session in that repo is refused once. The refusal's reason goes to the agent, which then asks you: set ownership up now, skip this session, or skip in this repo until you ask. The next write passes, so despite its name this is a reminder, not a gate: nothing checks that the agent asked. Writes to `AGENTS.md` and `.geneseed/` themselves always pass.
52
52
  - **What it skips.** Sub-agents defer on Claude Code and OpenClaude, which name them in the hook's input, and on OpenCode, whose guard sees that the session has a parent: a sub-agent cannot ask you, so it never spends the session's one stop. Shell writes are not seen; the line in the harness file covers them.
53
53
 
54
54
  Per host: Claude Code and OpenClaude deny the call with the reason; Bob refuses it with exit 2, once; OpenCode's guard plugin refuses it. See [Hooks](hooks.md) and [Rule enforcement, by host](enforcement-table.md).
@@ -60,7 +60,7 @@ Per host: Claude Code and OpenClaude deny the call with the reason; Bob refuses
60
60
  | One session | Answer "skip this session" when the agent asks | This session; it asks again in the next one |
61
61
  | One repo, for you | Answer "skip in this repo until I ask": the agent writes `Setup: declined <YYYY-MM-DD>` into your personal `.geneseed/ownership.md` in the main worktree — from a linked git worktree, the main checkout's, so the decline survives each new worktree (Claude Desktop opens one per session) | No expiry: until you delete the line or ask for the setup; never committed, so it never reaches the team. Each session opens with the reminder `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it` |
62
62
  | One repo, for the team | `## Ownership` with `mode: off` in the root `AGENTS.md` | Until the line changes; travels with the repo |
63
- | One install | Rebuild with `--no-ownership-gate` ([Exclusions](exclusions.md)) | Every rebuild replays it |
63
+ | One install | Open the *Ownership* row and flip its gate switch, in the Credo band of the web console's Constitution page, or rebuild with `--no-ownership-gate` ([Exclusions](exclusions.md)) | Every rebuild replays it |
64
64
 
65
65
  The decline is looked up only in the main worktree; the `## Ownership` section and the manifest are read from the git root you work in. A decline left inside a linked worktree is ignored, and a `.git` file that names no gitdir falls back to the current root. If the host refuses the write to the main checkout (outside the session's working directory, a sandbox, a declined permission prompt), the agent tells you the decline was not saved and why; it never writes it inside the linked worktree instead. A `## Ownership` section, on or off, outranks a personal decline: the line is then ignored and no reminder prints. The per-install switch stops the gate, drops the setup proposal from the install's `AGENT.md`, and prints no decline reminder. A repo with `mode: on` still runs the ownership checkpoints, and the Credo section still binds.
66
66
 
@@ -23,11 +23,24 @@ When two instructions disagree, the higher one wins.
23
23
 
24
24
  1. **Ethos** — always on. {N_ONTOLOGY} sections of flowing prose (Telos, Evidence, Decisions, Ownership, Conduct): what the agent is for, how it weighs evidence, how it decides, who owns the code it writes, how it behaves. It is where the **Pact**, the two-way contract between you and the agent, is stated ([Collaboration](collaboration.md)). Cited by section name, e.g. *Ethos: Decisions*.
25
25
  2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
26
- 3. **Your `user-rules.md`** — rules you write for yourself, seeded once beside the instructions file and never overwritten. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
26
+ 3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
27
27
  4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
28
28
  5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a crew — and never overrides a layer above it. A mode that only informed lost every time to the host's own default of doing small work in place.
29
29
  6. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
30
30
 
31
+ ### The shared tier
32
+
33
+ A global install keeps what you teach it in one place for every host on the machine: `~/.config/geneseed/`. [The shared tier](shared-tier.md) says what it holds, what stays per install, and how existing stores fold into it. The constitution itself is not in the tier: each install renders its own.
34
+
35
+ Your rules now come in layers, and the later layer wins: **project over host over shared**. A session reads the shared file first, then the host file, so a host or a project can narrow a machine-wide rule. All three stay in the place the list above gives `user-rules.md`, under the rules. `PROFILE.md` and the wiki manifest do not merge: a host file that is no longer its seed replaces the shared one.
36
+
37
+ **A project that reads the tier.** A project install does not read the tier by default: it sees only its own harness, as before. `--shared-tier on` (a `geneseed build` flag, a `setup` question for a per-repo install, and a switch on the project's panel in the console) adds a marker line, `Shared tier: on`, to the project's instructions file, and `rebuild-all` and `upgrade` keep it. Then the session start injects your machine-wide rules, profile and memory map as a labelled, read-only view, before the project's own docs. Writes stay local: the project keeps its own `memory/`, and its text keeps relative paths. A global install owns the tier, so the option is refused for one.
38
+
39
+ - **Benefit:** This project sees your machine-wide rules, profile and memory map, so what you taught one tool or repo applies here too.
40
+ - **Cost:** About 1 500 tokens at every session start, growing with your rules. The hook budget is fixed at 9 000 characters, and the tier loads before this project's docs, so a large tier can push them down to a lazy listing.
41
+
42
+ Only one hook injects the tier. On Claude Code, Bob and OpenClaude a wired project hook decides, and the global hook stands down, except under `$GENESEED_STACK_GLOBAL`, when the global hook injects and the project hook skips the tier. On OpenCode both plugins run, so the project plugin skips the tier when a global OpenCode install exists, and injects it when there is none. With the option off, a project gets no tier from its own hook, as today.
43
+
31
44
  ### Doctrine packs
32
45
 
33
46
  {N_PACKS} packs ship, one file each under `src/doctrines/`:
@@ -52,4 +65,4 @@ A [theme](themes.md) renames the nouns — an `imperial` install calls the invar
52
65
 
53
66
  ### Related
54
67
 
55
- [Footprint](footprint.md) — how much of this text loads every turn · [Exclusions](exclusions.md) — switching rules off per rule versus per repo · [Rule enforcement, by host](enforcement-table.md) — which rules a hook actually checks · [Glossary](../reference/glossary.md)
68
+ [Footprint](footprint.md) — how much of this text loads every turn · [The shared tier](shared-tier.md) — your rules, memory and profile for the whole machine · [Exclusions](exclusions.md) — switching rules off per rule versus per repo · [Rule enforcement, by host](enforcement-table.md) — which rules a hook actually checks · [Glossary](../reference/glossary.md)
@@ -0,0 +1,73 @@
1
+ ---
2
+ group: concepts
3
+ order: 10
4
+ title: "The shared tier"
5
+ kind: "concept"
6
+ section: "Memory"
7
+ description: "One machine-wide folder for memory, rules, profile and wiki, read by every global install."
8
+ ---
9
+ A global install keeps what you teach it in one place for every host on the machine: `~/.config/geneseed/` (or `$XDG_CONFIG_HOME/geneseed/`). Teach Claude Code a fact, and OpenCode knows it too. A project install keeps its own stores unless you [opt in](rules.md).
10
+
11
+ > **You already know this:** a shell's `~/.gitconfig`. One file serves every repo, and a repo's own config can narrow it.
12
+
13
+ ### What it holds
14
+
15
+ | In the tier | What it is |
16
+ | --- | --- |
17
+ | `user-rules.md` | Your standing rules for this machine |
18
+ | `PROFILE.md` | Who you are |
19
+ | `geneseed-wiki.jsonc` | Your [wiki](../guides/wiki.md) declaration |
20
+ | `excludes.json` | [Sovereign folders](exclusions.md) |
21
+ | `memory/` | The [memory](memory.md) store: facts, `MEMORY.md`, `topics/`, `agents/`, `archive/` |
22
+ | `notes/` | The self-improvement notes: `skill-notes/`, `agent-notes/` |
23
+ | `user-rules.draft.md` | What waits for your decision. Never loaded |
24
+ | `.fold-state.json` | The record of each drafted or decided item |
25
+ | `default-install.json` | The console's default install, once you pick one |
26
+
27
+ The same folder already held the install registry, your own loop bricks and templates.
28
+
29
+ **What stays per install.** The constitution and kits: each install renders its own, in its own theme, footprint and packs. The [notebook](notebook.md), apart from its two notes folders. The `wired` receipts in a host's own `excludes.json`. **MCP servers stay yours:** each host keeps its own file, and Geneseed only lists them, read-only, in `geneseed mcp` and the console.
30
+
31
+ ### How a session reads it
32
+
33
+ | File | How the layers combine |
34
+ | --- | --- |
35
+ | `user-rules.md`, `memory/MEMORY.md` | Both load, shared first, then host. The order is project over host over shared, so a host can narrow a machine-wide rule |
36
+ | `PROFILE.md`, `geneseed-wiki.jsonc` | Whole file. A host file that is no longer its seed replaces the shared one. `$GENESEED_WIKI` overrides both |
37
+ | `excludes.json` | A global install reads the union of the shared list and its own |
38
+
39
+ When both layers load, the heads say which is which: `----- user-rules.md (shared) -----` and `----- user-rules.md (host: claude) -----`. A file still at its seed is skipped. Rules load first, then profile, wiki, memory map and notebook index, so the hook budget cuts the last of these first, with a line that names the file.
40
+
41
+ A global install's text names these locations as absolute paths. A project install keeps its relative paths and its own `memory/`. Geneseed grants no directory permission for the tier, so an agent write there follows your host's permission mode, as a write to the host's own folder does. A write to the shared rules, draft or memory passes the same [rule gate](hooks.md) as a local one.
42
+
43
+ ### How it is created
44
+
45
+ The first global emit in a host's own config directory creates the folder and seeds each file once. An emit into another directory writes the same paths into its text and creates nothing, and `geneseed diff` compares an install against the paths it already names. If the tier cannot be created, that emit renders relative paths and the host files serve as before. `geneseed doctor` adds a note when a carrier names another tier than the one in force, for example after `$XDG_CONFIG_HOME` moves. `geneseed rebuild-all` clears it.
46
+
47
+ ### The fold
48
+
49
+ Each global emit, in the host's own config directory, moves that host's stores into the tier and prints one line, such as `[shared] claude: 12 facts folded, 1 collision, 2 rules to approve, old store moved aside`. A host with nothing to move prints nothing, and a second emit writes nothing. `geneseed migrate --dry-run` previews the fold for each host, and [Upgrade to 5.0](../guides/upgrade-to-5.md) walks through a first run.
50
+
51
+ - **Facts** copy byte for byte. A fact with the same name and other text lands as `<name>-<host>.md`, then `-2`, `-3`. The memory-curator agent can merge them later. Agent lessons append to the tier's file for that agent.
52
+ - **Notes** in `notebook/skill-notes/` and `notebook/agent-notes/` copy the same way. The rest of the notebook stays per host.
53
+ - **`PROFILE.md` and the wiki manifest** move when the tier holds only a seed. If the tier holds different text, the host file stays in force and `user-rules.draft.md` gets a pointer that asks which one becomes the shared file.
54
+ - **Exclude paths** join the shared list, and a shared path the host never saw gets its wiring. The report line names each file this writes in your repo.
55
+ - **`user-rules.md`** merges rule by rule. A rule with the same title and body as a shared rule leaves the host file. Any other rule goes to `user-rules.draft.md` with its host and old number, and stays in the host file, still binding. A host file with no rules left and nothing else of yours returns to its seed; hand-written text keeps the file as it is.
56
+
57
+ **Approving a draft.** The [rule skill](skills.md) takes each item in turn; nothing else writes a decision. Approve a rule and it joins the shared file under a new number, and the next fold of that host removes the host copy. Reject it and it stays on that host only, and the fold never drafts it again. For a profile or wiki pointer, the file you choose becomes the shared one and the other moves aside, or you keep both and the host file goes on overriding. The draft is never loaded: a drafted rule binds only from its host file.
58
+
59
+ Nothing is deleted. After every copy is read back, the old `memory/` moves to `archived-memory/<stamp>/` beside it, and the notes and whole files move to the same kind of folder. The host store returns to its seed and keeps its `README.md`. Hand-written index text and `archive/` stay in that folder, and the report line names every other file that stayed there and did not fold. A store or file already linked to the tier, in either direction, is left alone. If a copy fails, the old store stays readable, the emit reports it on stderr and goes on, and the next emit retries. There is no automatic way back: to downgrade, restore the archived folder by hand.
60
+
61
+ ### The console
62
+
63
+ The console has one hub and no install switch. On the **Personal** page, Rules, Profile and Memory list the shared store once, tagged `shared`, and name no harness; a project install keeps its own entry. Each rule row shows its token cost, and the page shows the total. There is no rule limit. A read-only **Pending** section shows what waits in the draft.
64
+
65
+ On **Installs**, *Make default* on an active install picks the one the console's pickers start on and a request naming no install reads. The `install` and `theme` lines of `geneseed status` follow it. The pick is `default-install.json`; if that install goes away, the console returns to the fixed host order.
66
+
67
+ ### Uninstall
68
+
69
+ `geneseed uninstall` never touches the tier, even for the last host and whatever `--archive-memory` says. It prints where the tier lives. Delete the folder yourself if you want it gone.
70
+
71
+ ### Related
72
+
73
+ [Memory](memory.md) · [Rules](rules.md) — the layers, and `--shared-tier on` for a project · [Exclusions](exclusions.md) · [Upgrade to 5.0](../guides/upgrade-to-5.md)
@@ -35,14 +35,14 @@ A **skill** is a repeatable workflow written as a markdown playbook: when it app
35
35
  | stage the right paths and write a focused commit | `commit` |
36
36
  | open a pull request, or finish and merge a branch | `ship` |
37
37
  | decide whether something is a standing rule or a fact to remember | `rule` |
38
- | be taught a topic, or quizzed on it | `teach`, `quiz` |
38
+ | be taught a topic, or quizzed on it (`/quiz` opens it too) | `teach` |
39
39
  | have every reply lead with the next action and keep the state in view (ADHD mode) | `adhd` |
40
40
 
41
41
  The full list, with each description, is in the catalog.
42
42
 
43
43
  ### Skills improve themselves
44
44
 
45
- Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with your assent, into that skill's notes file, `notebook/skill-notes/<name>.md`, and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `notebook/agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> — seen: <what happened, against what was expected> (<date>)`: `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Most runs end with nothing to change.
45
+ Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with your assent, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> — seen: <what happened, against what was expected> (<date>)`: `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Most runs end with nothing to change.
46
46
 
47
47
  ### Old names keep working
48
48
 
@@ -35,7 +35,7 @@ The theme is stored in a `.geneseed-theme` marker in the install, so upgrades an
35
35
  geneseed setup
36
36
  ```
37
37
 
38
- - **Web console** — the per-install voice dropdown on the Harness page.
38
+ - **Web console** — the per-install voice dropdown on the Installs page.
39
39
  - **Command line** — with the emit target of the install you are changing:
40
40
 
41
41
  ```bash
package/docs/extending.md CHANGED
@@ -125,7 +125,7 @@ Notes that matter:
125
125
 
126
126
  ### The gates CI does not run
127
127
 
128
- - **The mutation matrix itself.** `tests/mutate.mjs` — 34 rows, each a one-string edit to a
128
+ - **The mutation matrix itself.** `tests/mutate.mjs` — 35 rows, each a one-string edit to a
129
129
  product file with a written argument for which gate should catch it. The full run is **in no
130
130
  workflow** and should not be: it mutates the product tree 33 times and runs a gate per edit.
131
131
  Run `node tests/mutate.mjs --all` (or `--only M7`) by hand when you change something a gate is
@@ -219,9 +219,9 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
219
219
  `{N_PACKS}` / `{N_PACKS_ACTIVE}` / `{N_DOCTRINE_RULES}`, all computed at request time.
220
220
  - **No citation to rewire.** But there *are* written-out rule totals to bump — expected values are
221
221
  written out, never recorded — in `tests/unit/emit_smoke.test.mjs`, `harness.test.mjs`,
222
- `setup.test.mjs` and `web_api.test.mjs`. Each fails loudly with the new count; change the
222
+ `setup.test.mjs` and the `web_api*.test.mjs` files. Each fails loudly with the new count; change the
223
223
  number *and* the comment that explains it. A rule in **craft** moves more: `setup` and
224
- `web_api` also pin the craft-only narrowed counts, `generate.test.mjs` excludes every craft
224
+ `web_api*` also pin the craft-only narrowed counts, `generate.test.mjs` excludes every craft
225
225
  rule by address to empty the pack. Grep `tests/` for the previous
226
226
  rule's address before trusting this list. A rule long enough to matter can also breach the
227
227
  `full` carrier ceiling in `emit_smoke` — raise it with a dated note there, as every earlier
@@ -303,7 +303,7 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
303
303
  step 2 already makes a new pack default-on. `constitutionProblems` refuses a `doctrines`
304
304
  array naming a pack this checkout does not ship.
305
305
  6. The written-out **pack lists** in `tests/` — not only the rule totals of §2a. The full set is
306
- spelled out, in `PACK_ORDER`, in `emit_smoke`, `generate`, `harness`, `setup`, `web_api`,
306
+ spelled out, in `PACK_ORDER`, in `emit_smoke`, `generate`, `harness`, `setup`, `web_api*`,
307
307
  `web_jobs` and `wizard`, and the wizard cells also feed one y/n answer per pack on stdin.
308
308
  Grep `tests/` for `'process']` and `ops,process` before trusting this list.
309
309
  7. **Existing installs.** An install's pack set is read back off its carrier's `Active packs:`
@@ -313,11 +313,9 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
313
313
  pack cannot, or the moved rule disappears on the next rebuild — `comms` (2026-09-27) is the
314
314
  worked example. Through 3.x this was auto-migrated on sight; 4.0.0 retired that (CHANGELOG
315
315
  "Removed") because the detector it relied on breaks the day the donor pack regains a rule at
316
- the same old count. `js/hosts/installs.mjs`'s `legacyProcessCarrier` now only warns a
317
- pre-migration install to re-run `geneseed setup` rather than rewriting its data for it, and
318
- `legacyProcessCarrierOfDir` makes `rebuild-all`/`upgrade` (§9 below) skip that install
319
- entirely rather than re-emit it — re-emitting would write a fresh carrier that drops the
320
- rewrite silently and for good, since no `process 8` text survives it to warn about next time.
316
+ the same old count. 5.0.0 removed the leftover warning and the `rebuild-all`/`upgrade`/`migrate`
317
+ skip that went with it: an install older than the comms pack is rebuilt as it reads (see the
318
+ upgrade guide for the floor).
321
319
 
322
320
  ---
323
321
 
@@ -551,7 +549,7 @@ The `geneseed-` prefix and the `.js` suffix are mechanically load-bearing: the b
551
549
  4. `docs/concepts/host-matrix.md` — check the capability matrix still tells the truth.
552
550
  5. `README.md` — **three** sites: the badge, the `N plugins` prose, and the 🔌 Plugins row.
553
551
  6. `SHIPPED.md` — the bare name inside `plugins (…)`; that list must equal the directory exactly,
554
- in both directions (`tests/unit/web_api.test.mjs:1655`).
552
+ in both directions (`tests/unit/web_api_docs.test.mjs:329`).
555
553
  7. `adapters/opencode/README.md` and `docs/opencode-plugin-setup.md` — spelled-out counts, in
556
554
  **word form** ("seven" → "eight"), the second file twice.
557
555
  8. `tests/plugins/<name>.test.mjs`. Auto-discovered; no workflow edit.
@@ -890,8 +888,11 @@ rows, nor `web/package.json`.
890
888
  the `.geneseed-disabled` stash; registry rows whose directory is gone; and everything after the
891
889
  point where a `rebuild-all` fails mid-loop — it is best-effort by contract and leaves a mixed
892
890
  machine. Autostart entries are surveyed and reported, never rewritten. An install whose carrier
893
- predates the comms pack (§2d item 7) is also skipped, deliberately, every run until its owner
894
- runs `geneseed setup` for it — `rebuild-all` names it SKIPPED rather than re-emitting it.
891
+ predates the comms pack (§2d item 7) is no longer skipped: it is rebuilt as it reads.
892
+
893
+ **A global emit also folds.** In a host's own config directory it moves that host's stores into the
894
+ shared tier (`foldOnEmit`, `js/build/fold.mjs`), so a rebuild is not only a re-render there. Nothing
895
+ moves on a project install, in `geneseed diff`, or under a `--config-dir` that is not the host's own.
895
896
 
896
897
  **The web daemon serves the code it launched with**, plus an in-memory cache of every dist file.
897
898
  After a `web/dist` rebuild the correct move is `geneseed web restart`, not a hard refresh —
@@ -13,7 +13,7 @@ geneseed build --emit claude-global # ~/.claude
13
13
  geneseed build --emit claude --out /path/to/repo --root /path/to/repo # one repo
14
14
  ```
15
15
 
16
- The install writes `CLAUDE.md`, `agents/`, `skills/`, `memory/` and `notebook/`, plus hooks in Claude Code's `settings.json`. Hooks are commands Claude Code runs around each tool call. They gate risky actions and load project context (see [Hooks](../concepts/hooks.md)). For a project install the hooks go into `.claude/settings.local.json`, which stays out of git because it names a path on your machine.
16
+ The install writes `CLAUDE.md`, `agents/`, `skills/`, `memory/` and `notebook/`, plus hooks in Claude Code's `settings.json`. A global install also creates the [shared tier](../concepts/shared-tier.md), `~/.config/geneseed/`, where your rules, profile and memory live for every host. Hooks are commands Claude Code runs around each tool call. They gate risky actions and load project context (see [Hooks](../concepts/hooks.md)). For a project install the hooks go into `.claude/settings.local.json`, which stays out of git because it names a path on your machine.
17
17
 
18
18
  Every hook calls `geneseed-hook <verb>` through one stable file, the **hook shim** at `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim knows where Node and Geneseed live. If you move or replace Geneseed, one rebuild rewrites the shim and every install works again. `GENESEED_HOME` moves the shim's folder.
19
19
 
@@ -14,7 +14,7 @@ The setup wizard runs this for you (see [Install](install.md)). Use the commands
14
14
  geneseed build --emit opencode-global
15
15
  ```
16
16
 
17
- This writes into OpenCode's config directory: `$OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode` (on Windows too: `C:\Users\<you>\.config\opencode`). The install contains `AGENT.md`, `agents/`, `skills/`, the plugins, the `memory/` store, and a merged `opencode.json` whose `instructions` key points at `AGENT.md`. It also writes a one-line Geneseed block into `AGENTS.md` there when that file is missing. OpenCode loads `~/.claude/CLAUDE.md` only when `AGENTS.md` is absent, and a Claude install keeps the harness in that file too, so without the block the harness would load twice. If you already have an `AGENTS.md`, it is left alone. Every repo you open in OpenCode inherits it. You do not need a per-repo file, because the context plugin finds each repo's docs by itself (see [Project context](project-context.md)).
17
+ This writes into OpenCode's config directory: `$OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode` (on Windows too: `C:\Users\<you>\.config\opencode`). The install contains `AGENT.md`, `agents/`, `skills/`, the plugins, a seeded `memory/` folder, and a merged `opencode.json` whose `instructions` key points at `AGENT.md`. It also creates the [shared tier](../concepts/shared-tier.md), `~/.config/geneseed/`, where your rules, profile and memory live for every host. It also writes a one-line Geneseed block into `AGENTS.md` there when that file is missing. OpenCode loads `~/.claude/CLAUDE.md` only when `AGENTS.md` is absent, and a Claude install keeps the harness in that file too, so without the block the harness would load twice. If you already have an `AGENTS.md`, it is left alone. Every repo you open in OpenCode inherits it. You do not need a per-repo file, because the context plugin finds each repo's docs by itself (see [Project context](project-context.md)).
18
18
 
19
19
  The install is non-destructive. A manifest (`.geneseed-manifest.json`) records the files Geneseed owns. A rebuild replaces and prunes only those files, and never touches your own agents, skills, plugins or memory.
20
20
 
@@ -17,15 +17,17 @@ Claude Code, Bob and OpenClaude call Geneseed's hooks through one small file, th
17
17
  Install the package first (`npm install -g geneseed`, or prefix each command with `npx`), then:
18
18
 
19
19
  ```
20
- geneseed migrate --dry-run # survey every install and print the plan; writes nothing
20
+ geneseed migrate --dry-run # survey every install, print the plan and the fold report; writes nothing
21
21
  geneseed migrate # do it
22
22
  ```
23
23
 
24
24
  `migrate` rebuilds every registered install **with its own theme, host, footprint, posture and mode**. Nothing is reset to a default. It then rewrites the hook shim to point at the npm package, and reports anything it is not allowed to fix for you. A second run prints `already on the npm shape` and writes nothing.
25
25
 
26
+ `--dry-run` also previews [the fold](../concepts/shared-tier.md#the-fold) for each global install, even on a machine that has already migrated, because the fold runs in every global emit. Each host is read against the shared tier as it stands, so two hosts that hold the same new fact both count it.
27
+
26
28
  ## All or nothing
27
29
 
28
- Before changing anything, `migrate` copies every host settings file and the hook shim into `~/.geneseed/.migrate-backup/`. If any install fails to rebuild, **everything is put back** and the command exits non-zero. You are never left half on one setup and half on the other.
30
+ Before changing anything, `migrate` copies every host settings file and the hook shim into `~/.geneseed/.migrate-backup/`. If any install fails to rebuild, **everything is put back** and the command exits non-zero. You are never left half on one setup and half on the other. What an earlier install folded into the shared tier stays there: the tier and the host layer are read together, so nothing is lost.
29
31
 
30
32
  `rebuild-all` behaves the opposite way on purpose: it carries on past a broken install so that one failure cannot block the rest.
31
33
 
@@ -21,11 +21,11 @@ The context step sorts every doc it finds into one of two lists:
21
21
 
22
22
  With no configuration, the context step finds these files:
23
23
 
24
- - **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins). The root file your tool already loads by itself is skipped, so you never pay for it twice.
24
+ - **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins). The root file your tool already loads by itself is skipped, so you never pay for it twice. On Claude Code that covers `AGENTS.md` too, when `CLAUDE.md` imports it with `@AGENTS.md`, or when the repo has no `CLAUDE.md` and Claude Code is 2.1.277 or newer. If the hook cannot read the version, it injects the file.
25
25
  - **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`. AsciiDoc docs (`.adoc`) are found everywhere a `.md` is.
26
26
  - **Never scanned:** `node_modules`, `.git`, `dist`, `build`, `vendor`, `.next`, `target`, `.venv`, `__pycache__`, `.opencode` and `.harness`.
27
27
 
28
- On Claude Code, Bob and OpenClaude the whole injection stays under 9,000 characters, because Claude Code hands the model only a short preview of a hook output past about 10,000 and keeps the rest in a file. Your session files come first, then eager files whole; an eager file that does not fit is listed instead, to be read on demand. On OpenCode eager files share a 48 KB budget. On every host, three or more docs in one folder are listed as that folder with a count (`docs/guides/ — 30 docs`), not file by file.
28
+ On Claude Code, Bob and OpenClaude the whole injection stays under 9,000 characters, because Claude Code hands the model only a short preview of a hook output past about 10,000 and keeps the rest in a file. Your session files come first, in the order rules, profile, wiki, memory map, notebook, so the memory map is cut before your rules, with a line that names the file; then eager files whole; an eager file that does not fit is listed instead, to be read on demand. On OpenCode eager files share a 48 KB budget. On every host, three or more docs in one folder are listed as that folder with a count (`docs/guides/ — 30 docs`), not file by file.
29
29
 
30
30
  On OpenCode the context plugin does this work. On Claude Code, Bob and OpenClaude, the session-start hook does it (`geneseed-hook context`). Both read the same override file, described next.
31
31
 
@@ -18,7 +18,7 @@ This page is the how-to. For how the engine works (rings, scoring, trailers), se
18
18
  | A git repository with a remote named `origin` | Every iteration ends with `git push -u origin HEAD:loop/<slug>`. With no remote, the agent reports and stops. |
19
19
  | A test command the agent can run | The `test` brick runs the project's suite, and most templates retry `apply` until it passes. |
20
20
  | For `ci-repair`: CI that runs on `loop/*` branches, and the `gh` CLI | `ci-triage` reads the checks of the HEAD commit with `gh run list --commit`. |
21
- | For `legacy-tests`: a mutation tool (PIT, Stryker, mutmut, cargo-mutants) | Optional. Without one, `mutation-check` reports `unavailable` and the loop carries on, with a note saying so. |
21
+ | For `legacy-tests` and `bugfix`: a mutation tool (PIT, Stryker, mutmut, cargo-mutants) | Optional. Without one, `mutation-check` reports `unavailable` and the loop carries on, with a note saying so. |
22
22
 
23
23
  Check the catalogue the CLI sees from your repo:
24
24
 
@@ -82,7 +82,7 @@ Commit the root `AGENTS.md` with the repository, so the whole team works under t
82
82
  - **The team default.** Edit `granularity:` in `AGENTS.md` and commit it.
83
83
  - **Opt the repo out.** Set `mode: off`. The gate stays quiet, and no checkpoint runs.
84
84
  - **Skip it for yourself only.** Answer "skip in this repo until I ask" to the proposal, or write `Setup: declined <YYYY-MM-DD>` into `.geneseed/ownership.md` yourself. The team's `AGENTS.md` does not change.
85
- - **Opt the whole install out of the gate.** Rebuild with the flag, as [Exclusions](../concepts/exclusions.md) shows. The install's `AGENT.md` then carries no ownership proposal either, and no decline reminder prints:
85
+ - **Opt the whole install out of the gate.** Open the *Ownership* row and flip its gate switch, in the Credo band of the web console's Constitution page, or rebuild with the flag, as [Exclusions](../concepts/exclusions.md) shows. The install's `AGENT.md` then carries no ownership proposal either, and no decline reminder prints:
86
86
 
87
87
  ```bash
88
88
  geneseed build --emit claude-global --no-ownership-gate
@@ -40,7 +40,7 @@ geneseed build --emit opencode-global --trust prudent
40
40
  You have three ways to change a choice:
41
41
 
42
42
  - **Re-run the wizard** with `geneseed setup`. It pre-selects what the install already has, so holding Enter cannot widen a set you narrowed on purpose. The wizard does not ask about single rules, but it keeps any rule exclusions already in place.
43
- - **Use the web console** (`geneseed web`). the **Hosts** page changes theme, footprint and the rest per install. **Constitution** toggles packs and rules.
43
+ - **Use the web console** (`geneseed web`). the **Installs** page changes theme, footprint and the rest per install. **Constitution** toggles packs and rules.
44
44
  - **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want.
45
45
 
46
46
  ---
@@ -18,7 +18,7 @@ geneseed uninstall --target ~/.claude # a global install: pass its config
18
18
 
19
19
  Without `--target`, the command picks the project install in the current folder if there is one, and the OpenCode global install otherwise. It prints what it will remove and asks before going on. Pass `--yes` to skip the question. In a shell without an interactive terminal, `--yes` is required: without it, the command refuses and exits 1.
20
20
 
21
- To see where each install lives, run `geneseed status`. The web console's **Harnesses** page can also uninstall.
21
+ To see where each install lives, run `geneseed status`. The web console's **Installs** page can also uninstall.
22
22
 
23
23
  ## What it removes
24
24
 
@@ -35,6 +35,7 @@ It also removes the install's row from the registry of installs. Start a new ses
35
35
  ## What it keeps
36
36
 
37
37
  - **`memory/` and `notebook/`.** These are never deleted. `--archive-memory` moves both aside, into sibling `archived-memory/<timestamp>/` and `archived-notebook/<timestamp>/` folders, instead of leaving them in place. Even then they are moved, not deleted.
38
+ - **The shared tier, `~/.config/geneseed/`.** Uninstall never touches it, whatever `--archive-memory` says, and it prints where the tier lives. Your rules, profile, memory and wiki manifest stay there. Delete the folder yourself if you want them gone.
38
39
  - **`geneseed-wiki.jsonc`** (or `wiki.jsonc`, its name before the rename), **`context.json`** and the **`improvements/`** folder. None of these are in the manifest.
39
40
  - **Other installs.** Removing the global install does not touch any project install. Uninstall lists the project installs that remain, each with the command that removes it. If a repo carries installs for several hosts, uninstall removes one and tells you to run it again for the next.
40
41
 
@@ -0,0 +1,116 @@
1
+ ---
2
+ group: guides
3
+ order: 25.5
4
+ title: "Upgrade to 5.0"
5
+ kind: "concept"
6
+ section: "Keep it running"
7
+ description: "What moves when a 4.x machine reaches 5.0, what to check, and how to go back."
8
+ ---
9
+ 5.0 moves your memory, rules, profile and wiki manifest into one folder that every host on the machine shares: the [shared tier](../concepts/shared-tier.md), `~/.config/geneseed/`. The move runs by itself in the next global rebuild, and nothing is deleted. This page is the whole path for a machine that already runs 4.x. A first install needs none of it.
10
+
11
+ > **You already know this:** a database migration that runs at deploy time. You can preview it, it runs once, and it keeps the old table until you drop it yourself.
12
+
13
+ ## 1. Check that the install is new enough
14
+
15
+ - A **1.x** install must rebuild on a 4.x release first. Hooks that name `harness.py` no longer read as Geneseed's.
16
+ - An install **older than 3.7.0** must also rebuild on 4.x first, or run `geneseed setup` for it. 5.0 rebuilds it as it reads, which drops the comms pack and leaves the old rule numbers unmapped.
17
+
18
+ Anything from 3.7.0 upward goes straight to 5.0.
19
+
20
+ ## 2. Preview the fold
21
+
22
+ Get the new version first, and let nothing rebuild yet. A 4.x `migrate` knows nothing of the fold.
23
+
24
+ ```
25
+ npm install -g geneseed@latest # from npm
26
+ git pull --ff-only # from a clone, in the Geneseed folder
27
+ ```
28
+
29
+ Then preview:
30
+
31
+ ```
32
+ geneseed migrate --dry-run
33
+ ```
34
+
35
+ It writes nothing. It prints one line for each global install, read against the tier as it stands:
36
+
37
+ ```
38
+ [migrate] would fold claude: 1 fact folded, 1 note, 1 rule to approve, old store moved aside
39
+ [migrate] 1 install(s) to migrate.
40
+ [migrate] would re-emit claude:global (…/.claude)
41
+ [migrate] --dry-run: nothing was written.
42
+ ```
43
+
44
+ **Use only the `--dry-run` form here.** The `would re-emit` lines are the plan of `geneseed migrate` itself, which moves a clone install to [the npm shape](migrate.md). That is not a 5.0 step.
45
+
46
+ It also lists orphans: a root `AGENT.md`, or the folder of a retired skill, that no manifest owns. Such a folder may be yours. Geneseed never moves it, so move it by hand if it is not.
47
+
48
+ ## 3. Upgrade
49
+
50
+ Use the route you always use. See [Upgrade](upgrade.md).
51
+
52
+ ```
53
+ geneseed rebuild-all # from npm
54
+ geneseed upgrade # from a clone
55
+ ```
56
+
57
+ Between the install and the end of the rebuild:
58
+
59
+ - Hooks and running sessions stay safe. They read the host files until the rebuild moves them.
60
+ - Do not use the web console until the rebuild ends.
61
+ - The first `geneseed upgrade` from 4.x still runs the old doctor gate, which can take up to 300 seconds. Wait for it.
62
+
63
+ Each global install in its host's own config directory prints what it moved, once:
64
+
65
+ ```
66
+ [shared] claude: 1 fact folded, 1 note, 1 rule to approve, old store moved aside
67
+ ```
68
+
69
+ The next rebuild prints nothing, because nothing is left to move. A hand-written line in a host `MEMORY.md` is named on that line as `memory/MEMORY.md`, with the archive path: it stops loading, so copy it into a fact or a rule. A fact with the same name and other text counts as a `collision` and lands as `<name>-<host>.md`. The `memory-curator` agent can merge those later. A failed copy prints `fold stopped at …`: the old store stays readable, and the next rebuild retries.
70
+
71
+ | What you had | Where it is now |
72
+ |---|---|
73
+ | Facts in `<host>/memory/` | `~/.config/geneseed/memory/`. The index is rebuilt there: a hand-written `MEMORY.md` or `topics/` page stays only in `archived-memory/<stamp>/` |
74
+ | Agent lessons in `<host>/memory/agents/` | `~/.config/geneseed/memory/agents/`, merged by line |
75
+ | `<host>/notebook/skill-notes/`, `agent-notes/` | `~/.config/geneseed/notes/` |
76
+ | `PROFILE.md`, `geneseed-wiki.jsonc` | The tier, if it held only a seed. Otherwise it stays, and a pointer goes to the draft |
77
+ | Exclude paths | The shared `excludes.json` |
78
+ | Rules in `<host>/user-rules.md` | A rule the tier already holds word for word leaves the host file. Any other stays there, still binding, and goes to the draft |
79
+ | The old store | `<host>/archived-memory/<stamp>/`, with notes and whole files in the same kind of folder |
80
+ | The rest of `notebook/`, the constitution, kits | They stay per install |
81
+
82
+ A host installed after an `exclude add` also gets the repo-side wiring on this rebuild, so the first upgrade can write `.bob/rules/geneseed.md` or `settings.local.json` in an excluded repo. The report line names each file.
83
+
84
+ ## 4. Decide what waits in the draft
85
+
86
+ `user-rules.draft.md` in the tier lists what the fold could not decide for you. It is never loaded: a drafted rule goes on binding from its host file until you decide.
87
+
88
+ Ask the agent to review the pending rules. The `rule` skill is the only thing that writes a decision. It takes each item in turn:
89
+
90
+ - **Approve** moves the rule to the shared file under a new number. The next rebuild of that host removes the host copy.
91
+ - **Reject** keeps the rule on that host only, and it is never drafted again.
92
+ - **Later** leaves it pending.
93
+ - For a profile or wiki pointer, you choose which file becomes the shared one.
94
+
95
+ The console's Personal page shows the same items under **Pending**, read-only.
96
+
97
+ ## 5. Project installs
98
+
99
+ A project install does not change. It keeps its own `memory/` and notes and never folds. To let one read the tier as well, add `--shared-tier on` to its build, or answer the `setup` question. The trade is stated in [Rules](../concepts/rules.md): a session pays about 1 500 tokens more, and a large tier can push the project's docs down to a lazy listing.
100
+
101
+ ## What was removed
102
+
103
+ - `sync-self` is gone. Use `upgrade`.
104
+ - `upgrade` takes only a theme: `upgrade imperial` works, and `upgrade main imperial` is an error.
105
+ - `bootstrap` no longer takes `ref` or `extra`.
106
+ - `anamnesis/` is no longer read as a store. `status` reports one that is left over.
107
+ - `quiz` is part of `teach`. `/quiz` still opens it.
108
+ - The console's rule limit is gone: each rule shows its token cost, and the page shows a total with no ceiling.
109
+
110
+ ## Going back
111
+
112
+ There is no automatic downgrade. Install the older version, then copy `archived-memory/<stamp>/` back over the host's `memory/`, and do the same for `archived-user-rules.md/` and `archived-PROFILE.md/`. Rules you approved into the tier and excludes folded into the shared list are not merged back, so the archives are where the old text lives. The tier stays where it is, and an older Geneseed does not read it.
113
+
114
+ ---
115
+
116
+ **Next:** [The shared tier](../concepts/shared-tier.md) · [Verify it works](verify.md) · [Upgrade](upgrade.md)