geneseed 4.32.0 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/DESIGN.md +2 -2
  3. package/README.md +6 -5
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +6 -5
  6. package/adapters/claude-code/README.md +4 -3
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
  8. package/adapters/openclaude/README.md +4 -3
  9. package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
  10. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
  11. package/adapters/opencode/README.md +18 -18
  12. package/adapters/opencode/plugins/geneseed-activity.js +57 -1
  13. package/adapters/opencode/plugins/geneseed-context.js +85 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +437 -76
  15. package/adapters/opencode/plugins/geneseed-learn.js +97 -23
  16. package/bin/geneseed-cli.mjs +17 -25
  17. package/bin/geneseed-hook.mjs +23 -8
  18. package/docs/DESIGN.md +175 -0
  19. package/docs/PRD.md +111 -0
  20. package/docs/README.md +3 -2
  21. package/docs/architecture.md +145 -0
  22. package/docs/concepts/agents.md +1 -1
  23. package/docs/concepts/collaboration.md +1 -1
  24. package/docs/concepts/enforcement-table.md +1 -1
  25. package/docs/concepts/exclusions.md +5 -5
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hooks.md +22 -8
  29. package/docs/concepts/host-matrix.md +2 -2
  30. package/docs/concepts/hosts.md +1 -1
  31. package/docs/concepts/kits.md +3 -1
  32. package/docs/concepts/ownership.md +1 -1
  33. package/docs/concepts/rules.md +15 -2
  34. package/docs/concepts/shared-tier.md +73 -0
  35. package/docs/concepts/skills.md +2 -2
  36. package/docs/concepts/themes.md +1 -1
  37. package/docs/extending.md +13 -12
  38. package/docs/guides/install-claude-code.md +1 -1
  39. package/docs/guides/install-opencode.md +1 -1
  40. package/docs/guides/migrate.md +8 -4
  41. package/docs/guides/project-context.md +2 -2
  42. package/docs/guides/setup-footprint.md +1 -1
  43. package/docs/guides/uninstall.md +2 -1
  44. package/docs/guides/upgrade-to-5.md +118 -0
  45. package/docs/guides/upgrade.md +21 -9
  46. package/docs/guides/wiki.md +3 -3
  47. package/docs/reference/env-context.md +5 -3
  48. package/docs/reference/environment.md +1 -1
  49. package/docs/reference/glossary.md +2 -0
  50. package/docs/reference/opencode-plugins.md +3 -3
  51. package/docs/reference/plugin-activity.md +1 -1
  52. package/docs/reference/plugin-context.md +1 -0
  53. package/docs/reference/plugin-guard.md +14 -6
  54. package/docs/reference/plugin-learn.md +13 -6
  55. package/docs/reference/troubleshoot-hooks.md +3 -3
  56. package/docs/reference/troubleshoot-update.md +14 -0
  57. package/docs/token-footprint.md +4 -3
  58. package/docs/understand/a-day.md +2 -2
  59. package/docs/understand/design-choices-install.md +2 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-bob.md +2 -0
  62. package/docs/understand/machine-claude.md +7 -5
  63. package/docs/understand/machine-opencode.md +7 -5
  64. package/docs/understand/on-your-machine.md +4 -0
  65. package/docs/understand/take-it-out.md +1 -1
  66. package/docs/web-ui.md +135 -70
  67. package/harness.config.json +1 -1
  68. package/js/README.md +12 -7
  69. package/js/build/args.mjs +10 -8
  70. package/js/build/bundle.mjs +11 -13
  71. package/js/build/driver.mjs +66 -65
  72. package/js/build/emit-claude.mjs +22 -16
  73. package/js/build/emit-common.mjs +4 -5
  74. package/js/build/emit-opencode.mjs +22 -22
  75. package/js/build/fold.mjs +515 -0
  76. package/js/build/generate.mjs +41 -52
  77. package/js/build/render.mjs +115 -29
  78. package/js/build/rule-decide.mjs +273 -0
  79. package/js/build/source.mjs +4 -1
  80. package/js/build/stubs.mjs +70 -9
  81. package/js/build/version.mjs +10 -10
  82. package/js/cli-table.json +23 -83
  83. package/js/hosts/activity.mjs +2 -2
  84. package/js/hosts/geneseed-dir.mjs +1 -1
  85. package/js/hosts/hooks-context.mjs +389 -99
  86. package/js/hosts/hooks-learn.mjs +38 -7
  87. package/js/hosts/hooks-prims.mjs +4 -2
  88. package/js/hosts/hooks.mjs +114 -39
  89. package/js/hosts/hosts.mjs +150 -51
  90. package/js/hosts/installs.mjs +59 -171
  91. package/js/hosts/link.mjs +3 -5
  92. package/js/hosts/mcp.mjs +1 -1
  93. package/js/hosts/memory-files.mjs +219 -17
  94. package/js/hosts/ownership-gate.mjs +1 -1
  95. package/js/hosts/settings.mjs +18 -13
  96. package/js/hosts/shim.mjs +4 -33
  97. package/js/hosts/store-watch.mjs +191 -0
  98. package/js/inspect/checks-authoring.mjs +3 -3
  99. package/js/inspect/checks-build.mjs +45 -18
  100. package/js/inspect/checks-counts.mjs +4 -4
  101. package/js/inspect/checks-repo.mjs +13 -14
  102. package/js/inspect/cost.mjs +24 -2
  103. package/js/inspect/diff.mjs +123 -123
  104. package/js/inspect/doctor.mjs +22 -27
  105. package/js/inspect/excludes.mjs +181 -62
  106. package/js/inspect/inventory.mjs +22 -27
  107. package/js/inspect/registry.mjs +110 -32
  108. package/js/inspect/scan.mjs +5 -5
  109. package/js/inspect/status.mjs +141 -119
  110. package/js/inspect/validate.mjs +22 -24
  111. package/js/lib/fs.mjs +47 -50
  112. package/js/lib/json.mjs +10 -17
  113. package/js/lib/machine-dir.mjs +73 -0
  114. package/js/lib/paths.mjs +35 -33
  115. package/js/lib/proc.mjs +1 -1
  116. package/js/lib/prompt.mjs +19 -27
  117. package/js/lib/text.mjs +8 -12
  118. package/js/lib/udiff.mjs +11 -15
  119. package/js/loop/catalog.mjs +2 -3
  120. package/js/maintain/memory.mjs +17 -17
  121. package/js/maintain/migrate.mjs +120 -92
  122. package/js/maintain/setup.mjs +43 -32
  123. package/js/maintain/uninstall.mjs +43 -61
  124. package/js/maintain/update.mjs +200 -93
  125. package/js/ui/anim.mjs +21 -35
  126. package/js/ui/cli.mjs +36 -58
  127. package/js/ui/menu.mjs +22 -45
  128. package/js/ui/tui.mjs +27 -67
  129. package/js/web/actions.mjs +34 -34
  130. package/js/web/api.mjs +142 -79
  131. package/js/web/catalog.mjs +175 -46
  132. package/js/web/docs.mjs +33 -12
  133. package/js/web/doctor-worker.mjs +14 -0
  134. package/js/web/handler.mjs +16 -5
  135. package/js/web/routes.mjs +24 -22
  136. package/js/web/state.mjs +78 -19
  137. package/js/web/update-check.mjs +27 -12
  138. package/js/web/user-files.mjs +76 -104
  139. package/package.json +7 -4
  140. package/registry.json +48 -55
  141. package/src/AGENT.md.tmpl +13 -14
  142. package/src/agents/_self-improvement.md +1 -1
  143. package/src/agents/_template.md +1 -1
  144. package/src/agents/advocate.md +1 -1
  145. package/src/agents/architect.md +1 -1
  146. package/src/agents/developer.md +1 -1
  147. package/src/agents/devops-engineer.md +1 -1
  148. package/src/agents/docker-expert.md +1 -1
  149. package/src/agents/docs.md +1 -1
  150. package/src/agents/empiricist.md +1 -1
  151. package/src/agents/explorer.md +1 -1
  152. package/src/agents/framer.md +1 -1
  153. package/src/agents/historian.md +1 -1
  154. package/src/agents/kubernetes-specialist.md +1 -1
  155. package/src/agents/memory-curator.md +2 -2
  156. package/src/agents/operator.md +1 -1
  157. package/src/agents/performance.md +1 -1
  158. package/src/agents/pragmatist.md +1 -1
  159. package/src/agents/react-engineer.md +1 -1
  160. package/src/agents/react-reviewer.md +1 -1
  161. package/src/agents/researcher.md +1 -1
  162. package/src/agents/reviewer.md +1 -1
  163. package/src/agents/security.md +1 -1
  164. package/src/agents/skeptic.md +1 -1
  165. package/src/agents/spring-boot-engineer.md +1 -1
  166. package/src/agents/spring-reviewer.md +1 -1
  167. package/src/agents/spring-security.md +1 -1
  168. package/src/agents/steward.md +1 -1
  169. package/src/agents/tester.md +1 -1
  170. package/src/agents/user-advocate.md +1 -1
  171. package/src/agents/visionary.md +1 -1
  172. package/src/memory/README.md +1 -1
  173. package/src/skills/_self-improvement.md +2 -2
  174. package/src/skills/daydream/SKILL.md +2 -2
  175. package/src/skills/daydream/instructions.md +1 -1
  176. package/src/skills/geneseed.md +1 -1
  177. package/src/skills/learn-mode.md +1 -2
  178. package/src/skills/profile.md +2 -2
  179. package/src/skills/rule/approve.md +75 -0
  180. package/src/skills/rule/consolidate.md +3 -3
  181. package/src/skills/rule.md +14 -5
  182. package/src/skills/skill-forge.md +1 -1
  183. package/src/skills/teach.md +29 -12
  184. package/src/skills/wiki.md +1 -1
  185. package/themes/_TEMPLATE.json +1 -2
  186. package/themes/biker.json +1 -2
  187. package/themes/commentator.json +1 -2
  188. package/themes/cyberpunk.json +1 -2
  189. package/themes/gamer.json +1 -2
  190. package/themes/imperial.json +1 -2
  191. package/themes/joker.json +1 -2
  192. package/themes/marvin.json +1 -2
  193. package/themes/mean.json +1 -2
  194. package/themes/military.json +1 -2
  195. package/themes/neutral.json +1 -2
  196. package/themes/pirate.json +1 -2
  197. package/themes/sports.json +1 -2
  198. package/themes/verstappen.json +1 -2
  199. package/themes/wizard.json +1 -2
  200. package/web/dist/assets/Activity-Ci4PZco3.js +1 -0
  201. package/web/dist/assets/ActivityDetail-C8hroCND.js +1 -0
  202. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  203. package/web/dist/assets/Bonsai-C1iBAt4v.js +1 -0
  204. package/web/dist/assets/{CopyButton-C5Li6awl.js → CopyButton-DJ3a4N88.js} +1 -1
  205. package/web/dist/assets/Dashboard-C_On4KXw.js +2 -0
  206. package/web/dist/assets/Docs-Kffdg5uV.js +5 -0
  207. package/web/dist/assets/GreenhouseView-k56_cBSF.js +1 -0
  208. package/web/dist/assets/Installs-DtEKLC9h.js +3 -0
  209. package/web/dist/assets/JournalView-RQnk5l7I.js +1 -0
  210. package/web/dist/assets/Kits-CXkEBpnf.js +1 -0
  211. package/web/dist/assets/Laws-DhhIVqmh.js +3 -0
  212. package/web/dist/assets/Library-CAUiEoJo.js +3 -0
  213. package/web/dist/assets/{Loops-CzitjxGV.js → Loops-LKD8mF4E.js} +2 -2
  214. package/web/dist/assets/{Markdown-C4S4tTA7.js → Markdown-0ORz7tAc.js} +21 -21
  215. package/web/dist/assets/OperatorHudView-CM5jNPwL.js +1 -0
  216. package/web/dist/assets/Personal-B6Uoly3C.js +2 -0
  217. package/web/dist/assets/{RailCats-D5weYPCS.js → RailCats-DQxxYBEP.js} +1 -1
  218. package/web/dist/assets/Settings-BTe6-wda.js +1 -0
  219. package/web/dist/assets/Tabs-CbdDWTp_.js +1 -0
  220. package/web/dist/assets/api-D_r0Jtla.js +1 -0
  221. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  222. package/web/dist/assets/index-HfGmYXab.js +3 -0
  223. package/web/dist/assets/index-ao3M-Fhm.css +1 -0
  224. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  225. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  226. package/web/dist/index.html +5 -5
  227. package/src/skills/quiz.md +0 -44
  228. package/web/dist/assets/Activity-Bjy64wHC.js +0 -1
  229. package/web/dist/assets/ActivityDetail-B0AaipP8.js +0 -1
  230. package/web/dist/assets/Bonsai-CJniRqaH.js +0 -1
  231. package/web/dist/assets/Dashboard-B-6DTmae.js +0 -2
  232. package/web/dist/assets/Docs-LRc30XL9.js +0 -5
  233. package/web/dist/assets/GreenhouseView-CcoYlaWo.js +0 -1
  234. package/web/dist/assets/Installs-dp1epTcE.js +0 -3
  235. package/web/dist/assets/JournalView-nFP4poCf.js +0 -1
  236. package/web/dist/assets/KitApply-DwyZUj57.js +0 -1
  237. package/web/dist/assets/Kits-C0IEdZXe.js +0 -1
  238. package/web/dist/assets/Laws-CkykmQWu.js +0 -3
  239. package/web/dist/assets/Library-Guh9HBZU.js +0 -2
  240. package/web/dist/assets/OperatorHudView-DLGNulIY.js +0 -1
  241. package/web/dist/assets/Personal-BMtberL8.js +0 -2
  242. package/web/dist/assets/Tabs-uYJqfuQt.js +0 -1
  243. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  244. package/web/dist/assets/index-DA7BiaE5.js +0 -3
  245. package/web/dist/assets/index-dbbDGFDq.css +0 -1
  246. package/web/dist/assets/motion-Bccx3zE8.js +0 -1
@@ -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, *Preview next rebuild* on the console's Installs page shows the same, 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, and the console's **Pending** section decides the same items by the same steps; 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 **Pending** section shows what waits in the draft, with *Approve* and *Reject* on a rule, and the two files with three choices on a profile or wiki pointer. A decision that moves a file offers *Rebuild all*, which removes the host copy. An edit in another session makes the decision reload instead of applying, and no decision applies while a rebuild runs.
64
+
65
+ On **Installs**, *Preview next rebuild* shows what each global install would fold, and any orphans, and writes nothing. *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
 
@@ -14,18 +14,22 @@ Claude Code, Bob and OpenClaude call Geneseed's hooks through one small file, th
14
14
 
15
15
  ## Run it
16
16
 
17
- Install the package first (`npm install -g geneseed`, or prefix each command with `npx`), then:
17
+ Install the package first (`npm install -g geneseed`), then run these from it:
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
- `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.
24
+ `migrate` rebuilds every registered install **with its own theme, host, footprint, posture and mode**. Nothing is reset to a default. Each rebuild of a Claude Code, Bob or OpenClaude install rewrites the hook shim to name the Geneseed that runs the rebuild, so it now names the npm package. `migrate` does not write the shim itself, and OpenCode has none. It then reports anything it is not allowed to fix for you. A second run prints `already on the npm shape` and writes nothing.
25
+
26
+ **It runs only from the npm package.** From a git clone or a bundle, a real run has nothing to move: the rebuild would point the shim back at that same copy. So it refuses with exit 3 before it writes anything, and says to use `geneseed update`. An `npx` run refuses too: npm prunes that cache, and the shim would die with it. `--dry-run` works from anywhere. Outside the package it previews the fold, then says a real run would refuse.
27
+
28
+ `--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.
25
29
 
26
30
  ## All or nothing
27
31
 
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.
32
+ 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
33
 
30
34
  `rebuild-all` behaves the opposite way on purpose: it carries on past a broken install so that one failure cannot block the rest.
31
35
 
@@ -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
 
@@ -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,118 @@
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. From a clone those lines do not appear: the preview ends by saying a real run would refuse, and a real `migrate` there exits 3 and changes nothing.
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
+ **In the console.** With no terminal, there is no preview before the first fold: *Update* on a clone pulls and rebuilds in one job, so the fold runs in that click, and a 4.x console has no preview. Nothing is deleted, as step 3 shows. After that, *Preview next rebuild* on the Installs page, beside *Rebuild all*, shows the same fold lines and orphans for any later rebuild, without the `would re-emit` lines, and writes nothing.
49
+
50
+ ## 3. Upgrade
51
+
52
+ Use the route you always use. See [Upgrade](upgrade.md).
53
+
54
+ ```
55
+ geneseed rebuild-all # from npm
56
+ geneseed upgrade # from a clone
57
+ ```
58
+
59
+ Between the install and the end of the rebuild:
60
+
61
+ - Hooks and running sessions stay safe. They read the host files until the rebuild moves them.
62
+ - Do not change anything in the web console until the rebuild ends. *Rebuild all* on its Installs page is the same rebuild as `geneseed rebuild-all`.
63
+ - The first `geneseed upgrade` from 4.x still runs the old doctor gate, which can take up to 300 seconds. Wait for it.
64
+
65
+ Each global install in its host's own config directory prints what it moved, once:
66
+
67
+ ```
68
+ [shared] claude: 1 fact folded, 1 note, 1 rule to approve, old store moved aside
69
+ ```
70
+
71
+ 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.
72
+
73
+ | What you had | Where it is now |
74
+ |---|---|
75
+ | 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>/` |
76
+ | Agent lessons in `<host>/memory/agents/` | `~/.config/geneseed/memory/agents/`, merged by line |
77
+ | `<host>/notebook/skill-notes/`, `agent-notes/` | `~/.config/geneseed/notes/` |
78
+ | `PROFILE.md`, `geneseed-wiki.jsonc` | The tier, if it held only a seed. Otherwise it stays, and a pointer goes to the draft |
79
+ | Exclude paths | The shared `excludes.json` |
80
+ | 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 |
81
+ | The old store | `<host>/archived-memory/<stamp>/`, with notes and whole files in the same kind of folder |
82
+ | The rest of `notebook/`, the constitution, kits | They stay per install |
83
+
84
+ 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.
85
+
86
+ ## 4. Decide what waits in the draft
87
+
88
+ `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.
89
+
90
+ Ask the agent to review the pending rules, or open **Pending** on the console's Personal page. The `rule` skill and that section are the only things that write a decision, and they take the same steps:
91
+
92
+ - **Approve** moves the rule to the shared file under a new number. The next rebuild of that host removes the host copy.
93
+ - **Reject** keeps the rule on that host only, and it is never drafted again.
94
+ - **Later** leaves it pending.
95
+ - For a profile or wiki pointer, you choose which file becomes the shared one.
96
+
97
+ In the console, an item you leave alone stays pending. After a decision that moves a file, the page offers *Rebuild all*, which removes the host copy. If another session changed the draft, the page reloads and applies nothing.
98
+
99
+ ## 5. Project installs
100
+
101
+ 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.
102
+
103
+ ## What was removed
104
+
105
+ - `sync-self` is gone. Use `upgrade`.
106
+ - `upgrade` takes only a theme: `upgrade imperial` works, and `upgrade main imperial` is an error.
107
+ - `bootstrap` no longer takes `ref` or `extra`.
108
+ - `anamnesis/` is no longer read as a store. `status` reports one that is left over.
109
+ - `quiz` is part of `teach`. `/quiz` still opens it.
110
+ - The console's rule limit is gone: each rule shows its token cost, and the page shows a total with no ceiling.
111
+
112
+ ## Going back
113
+
114
+ 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.
115
+
116
+ ---
117
+
118
+ **Next:** [The shared tier](../concepts/shared-tier.md) · [Verify it works](verify.md) · [Upgrade](upgrade.md)
@@ -8,6 +8,8 @@ description: "Get a new version onto every install, and keep your local edits."
8
8
  ---
9
9
  Upgrading happens in two steps: get the new Geneseed, then rebuild every install from it. Editing or updating Geneseed changes nothing on your machine until something rebuilds. The route depends on how you installed.
10
10
 
11
+ **Coming from 4.x?** Read [Upgrade to 5.0](upgrade-to-5.md) first: the rebuild moves your memory, rules and profile into the [shared tier](../concepts/shared-tier.md).
12
+
11
13
  ## Installed from npm
12
14
 
13
15
  ```
@@ -17,7 +19,7 @@ geneseed rebuild-all # rebuild every install with its own settings
17
19
 
18
20
  `rebuild-all` re-renders each registered install in place, keeping its own theme, host, footprint, posture, mode, packs and rule exclusions. It is best-effort: when one install fails, it reports the failure and carries on with the rest.
19
21
 
20
- `upgrade`, `update`, `sync-self` and `bootstrap` are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
22
+ `upgrade`, `update` and `bootstrap` are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
21
23
 
22
24
  ## Installed from a clone
23
25
 
@@ -32,7 +34,9 @@ geneseed upgrade imperial # the same, switching the theme
32
34
  2. It runs a blocking `doctor` pass over the result, and rolls back if it fails.
33
35
  3. It rebuilds the bundle and every install in place.
34
36
 
35
- A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` and `sync-self` are aliases of `upgrade`. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
37
+ If the `doctor` pass cannot finish, for example on a busy machine after 300 seconds, `upgrade` keeps the pull, rebuilds nothing, and exits 1. The pulled source is unchecked, not bad. Run `geneseed upgrade` again: it runs `doctor` first, rebuilds on a pass, and rolls back to the last checked commit on a failure.
38
+
39
+ A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` is an alias of `upgrade`; `sync-self` was removed in 5.0.0, and `upgrade` takes only a theme. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
36
40
 
37
41
  ## The Update button in the web console
38
42
 
@@ -40,11 +44,11 @@ The **Update** button on the Overview picks its route from how this copy of Gene
40
44
 
41
45
  | Install | What **Update** runs | When the button shows |
42
46
  |---|---|---|
43
- | A clone (or a worktree) | `geneseed upgrade` | Always, because `main` moves between releases. |
47
+ | A clone (or a worktree) | `geneseed upgrade` | When the pull can run, even with no release out, because `main` moves between releases. A clone with local changes, a detached HEAD, no upstream or a diverged branch shows no button, since the job would refuse. While the clone's own check runs, the chip says so and no button shows. |
44
48
  | A global npm install (`npm root -g`/geneseed) | `npm install -g geneseed@latest`, then `geneseed rebuild-all` from the new package | When npm has a newer release. |
45
49
  | Anything else (an npx cache, a project's `node_modules`, an unzipped copy) | Nothing. The Overview shows the command to run instead. | Never. |
46
50
 
47
- On a clone, the Overview also says whether there is anything to pull. Once a day the console runs `git fetch` in the background and counts the commits upstream has that the clone does not: "3 commits to pull", or "up to date". The fetch has the same timeout as `upgrade` (`GENESEED_NET_TIMEOUT`, 120 s by default). If the fetch fails, the Overview shows the release check instead, and the button stays. `GENESEED_NO_UPDATE_CHECK` turns off both the npm check and the fetch.
51
+ On a clone, the Overview also says whether there is anything to pull. Once a day the console runs `git fetch` in the background and counts the commits upstream has that the clone does not: "3 commits to pull", or "up to date". The fetch has the same timeout as `upgrade` (`GENESEED_NET_TIMEOUT`, 120 s by default). If the fetch fails, the Overview shows the release check instead, and the button stays. If a release is out and the clone cannot pull, the chip's tooltip names the reasons. `GENESEED_NO_UPDATE_CHECK` turns off both the npm check and the fetch.
48
52
 
49
53
  The console asks npm for the latest release once a day. An Overview page that stays open asks the console again every hour, and each time you come back to its tab, so it shows a new release within a day.
50
54
 
@@ -52,19 +56,27 @@ The npm route never uses `sudo` and never retries. If npm refuses (no permission
52
56
 
53
57
  When the update is done, the console restarts and the page reloads. If you ran `git pull` yourself, the Overview shows a banner that the console runs old code. Click **Rebuild** on an install that is behind, or **Rebuild all behind** in the header. The console asks you to confirm, rebuilds only the installs it names, then restarts and reloads the page. If no install is behind, click **Restart** in the banner.
54
58
 
59
+ ## The oldest install an upgrade accepts
60
+
61
+ A 1.x install must rebuild on a 4.x release first: hooks that name `harness.py` no longer read as Geneseed's.
62
+
63
+ 5.0.0 no longer recognises an install built before the comms pack (3.7.0, 2026-09-27) and no longer skips it. Its carrier names `process 8` and its `Active packs:` line has no `comms`; `rebuild-all`, `upgrade`, `migrate` and the web console now rebuild it as it reads, which drops the codes rule and leaves the old rule numbers unmapped. Upgrade such an install to a 4.x release first and run `geneseed rebuild-all` there, or run `geneseed setup` for it before moving to 5.0.0.
64
+
55
65
  ## What an upgrade keeps
56
66
 
57
67
  A rebuild only replaces files the install's manifest says Geneseed owns. It leaves these alone:
58
68
 
59
- - the `memory/` and `notebook/` stores;
60
- - your `context.json` and `geneseed-wiki.jsonc` (an older `wiki.jsonc` is renamed to it, contents untouched);
69
+ - the `memory/` and `notebook/` stores of a project install;
70
+ - your `context.json` and a project's `geneseed-wiki.jsonc` (an older `wiki.jsonc` is renamed to it, contents untouched);
61
71
  - the marker files that record each install's choices (theme, footprint, packs, excluded rules), which every rebuild reads back;
62
72
  - your own agents, skills, plugins and hooks, and any `opencode.json` or `settings.json` keys you wrote yourself;
63
73
  - the `improvements/` folder (see below).
64
74
 
75
+ A rebuild of a global install in its host's own config directory also runs [the fold](../concepts/shared-tier.md#the-fold). That moves its facts, self-improvement notes, exclude paths and, where the tier holds only a seed, its profile and wiki manifest into `~/.config/geneseed/`. Its other rules stay in force in the host file until you decide. Nothing is deleted: the old store moves to `archived-memory/<stamp>/`. The tier itself is never rebuilt, so what you keep there survives every upgrade.
76
+
65
77
  ## Local edits, and the improvements file
66
78
 
67
- The agent records what it learns about a skill or agent in notes under `notebook/skill-notes/` and `notebook/agent-notes/`, which rebuilds never touch. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When deployed files carry local edits (files only behind the source are not edits and are not exported), the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
79
+ The agent records what it learns about a skill or agent in notes, which rebuilds never overwrite: under `notes/skill-notes/` and `notes/agent-notes/` in the shared tier on a global install, and under `notebook/skill-notes/` and `notebook/agent-notes/` on a project install. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When deployed files carry local edits (files only behind the source are not edits and are not exported), the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
68
80
 
69
81
  A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
70
82
 
@@ -76,7 +88,7 @@ geneseed diff --full # with line-level diffs
76
88
  geneseed diff --out improvements.md # write the improvements file
77
89
  ```
78
90
 
79
- `diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. A file unmodified since its build that differs only because the source moved on is listed as behind source; a rebuild updates it, and it stays out of the improvements file too. `diff` also lists every non-empty self-improvement note, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
91
+ `diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. A file unmodified since its build that differs only because the source moved on is listed as behind source; a rebuild updates it, and it stays out of the improvements file too. `diff` also lists every non-empty self-improvement note, the tier's included, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
80
92
 
81
93
  ## Moving from a clone to npm
82
94
 
@@ -84,4 +96,4 @@ If you installed from a clone and now want the npm package, `geneseed migrate` m
84
96
 
85
97
  ---
86
98
 
87
- **Next:** [Verify it works](verify.md) · [Uninstall](uninstall.md)
99
+ **Next:** [Upgrade to 5.0](upgrade-to-5.md) · [Verify it works](verify.md) · [Uninstall](uninstall.md)
@@ -20,7 +20,7 @@ When a memory fact or a notebook note hardens into knowledge worth keeping acros
20
20
 
21
21
  ## Declare it in `geneseed-wiki.jsonc`
22
22
 
23
- The build writes a `geneseed-wiki.jsonc` stub beside `AGENT.md` (for the OpenCode global install, `~/.config/opencode/geneseed-wiki.jsonc`) and never overwrites it. The file is JSONC, so comments and trailing commas are fine. The stub contains this example, commented out:
23
+ The build writes a `geneseed-wiki.jsonc` stub beside `AGENT.md` (for the OpenCode global install, `~/.config/opencode/geneseed-wiki.jsonc`) and never overwrites it. On a global install, declare your wiki in the shared file, `~/.config/geneseed/geneseed-wiki.jsonc`: every host reads it, and a declaration in a host file replaces that whole file. The file is JSONC, so comments and trailing commas are fine. The stub contains this example, commented out:
24
24
 
25
25
  ```json
26
26
  {
@@ -47,7 +47,7 @@ The build writes a `geneseed-wiki.jsonc` stub beside `AGENT.md` (for the OpenCod
47
47
 
48
48
  You can declare several wikis. An empty `wikis` list keeps the feature off. The file may hold private paths. It is specific to this machine and must never be committed. A project install's own `.gitignore` already lists it.
49
49
 
50
- Geneseed looks for the file in this order: `$GENESEED_WIKI`, then `$GENESEED_HARNESS/geneseed-wiki.jsonc`, then beside the installed `AGENT.md`. The build renames a `wiki.jsonc` or `wiki.json` left by an older install to `geneseed-wiki.jsonc`, contents untouched, and adds the new name to a `.gitignore` that listed the old one. Until that next build, the old `wiki.jsonc` is still read at each of those places.
50
+ Geneseed looks for the file in this order: `$GENESEED_WIKI`, then `$GENESEED_HARNESS/geneseed-wiki.jsonc`, then beside the installed `AGENT.md`, then, on a global install, in the machine tier at `~/.config/geneseed/geneseed-wiki.jsonc`. A host file you changed replaces the tier's whole file; a host file still at its seed does not. The build renames a `wiki.jsonc` or `wiki.json` left by an older install to `geneseed-wiki.jsonc`, contents untouched, and adds the new name to a `.gitignore` that listed the old one. Until that next build, both old names are still read at each of those places.
51
51
 
52
52
  ## How each host honours it
53
53
 
@@ -60,7 +60,7 @@ The context plugin loads your eager entries and lists your lazy ones at session
60
60
  <!--harness:claude-->
61
61
  *(Claude Code only)*
62
62
 
63
- No hook reads the wiki. The instructions in your harness tell the agent to read `geneseed-wiki.jsonc` at session start and to honour it, including the `protected` folders. That is an instruction the model follows, not a block. Nothing stops a write at the tool boundary. The same applies to Bob, OpenClaude and plain `AGENT.md` tools. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
63
+ The context hook loads your eager entries and lists your lazy ones at session start, inside its 9,000-character budget: a note that does not fit is listed instead, and a long listing folds by folder and ends with a count. It also prints your `conventions`, `inbox` and `protected` lines. Bob and OpenClaude run the same hook. Honouring `protected` is an instruction the model follows, not a block. Nothing stops a write at the tool boundary. Plain `AGENT.md` tools have no hook, so the agent reads `geneseed-wiki.jsonc` itself. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
64
64
  <!--/harness-->
65
65
 
66
66
  ## What the agent does with it
@@ -18,7 +18,7 @@ What gets loaded into the agent's context at session start — your project's do
18
18
  | --- | --- | --- |
19
19
  | `GENESEED_CONTEXT` | context plugin, context hook | Explicit `context.json` manifest path; overrides discovery. |
20
20
  | `GENESEED_ROOT` | context hook | Repo root to discover docs from (default: the current directory). |
21
- | `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `geneseed-wiki.jsonc` path (default `$GENESEED_HARNESS/geneseed-wiki.jsonc`, else beside the install). |
21
+ | `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `geneseed-wiki.jsonc` path (default `$GENESEED_HARNESS/geneseed-wiki.jsonc`, else beside the install, else the [shared tier](../concepts/shared-tier.md) on a global install). |
22
22
  | `GENESEED_STACK_GLOBAL` | context, git-gate and learn hooks, Claude Code project build | `1` lets a global and a project install of the same host both run. By default a live project install in the session's project folder (not a parent of it) that wires the same hook makes the global one stand down. Rebuild the project install after changing it. |
23
23
  | `GENESEED_CONTEXT_INJECT` | context plugin | `off` disables injection; the agent is only *asked* to read the docs. |
24
24
  | `GENESEED_CONTEXT_VISIBLE` | context plugin | `1` shows the visible `PROJECT CONTEXT` block instead of the invisible per-request delivery. |
@@ -31,10 +31,12 @@ What gets loaded into the agent's context at session start — your project's do
31
31
 
32
32
  Where distilled memories land at session end, and which model distils them. See [Memory](../concepts/memory.md).
33
33
 
34
+ `GENESEED_MEMORY` and `GENESEED_HARNESS` are deprecated as of 5.0.0, with removal planned for 6.0. They keep working, and the CLI prints one warning on stderr when one is set. A global install finds the shared store by itself; to pin a store for one command, pass `--memory <dir>`.
35
+
34
36
  | Variable | Read by | Effect |
35
37
  | --- | --- | --- |
36
- | `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `geneseed-wiki.jsonc` is looked up). Optional — the plugin finds the in-config store by itself; set it to pin the location. |
37
- | `GENESEED_MEMORY` | learn plugin, CLI | Explicit memory dir; wins over `GENESEED_HARNESS`. |
38
+ | `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `geneseed-wiki.jsonc` is looked up). Optional — a global install finds the shared store by itself. Set it only to pin another store: it wins over the shared one, so a value such as `~/.config/opencode` keeps facts out of the tier. |
39
+ | `GENESEED_MEMORY` | learn plugin, CLI, hand-run `learn` | Explicit memory dir; wins over `GENESEED_HARNESS` and the shared store. It moves what the OpenCode learn plugin, `geneseed memory` and a hand-run `learn` use. It does not move the `learn` hook, which is told its store by `--memory`, or what a session loads and the console shows: those read the tier. Without either variable, `geneseed memory`, `status` and a hand-run `learn` use a project install in the cwd or `./Harness`, then the shared store, then the OpenCode config store. A `memory/` folder counts only when an emit made it: a known `.geneseed-emit`, `.geneseed-version` beside the folder and `MEMORY.md` in it. Any other is not a store: name it with `--memory`. Two host installs in one repo keep two stores, and these commands use the one the marker names: name the other with `--memory`. |
38
40
  | `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
39
41
  | `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, a real Stop/SubagentStop/PreCompact call returns immediately — nothing reads its stdout there; a manual `learn` run (notes piped or given as a file) still prints the prompt instead of distilling. |
40
42
  | `GENESEED_LEARN_CHILD` | learn hook | Set by `learn` itself on the model CLI it spawns; a nested session's own Stop hook sees it and returns immediately, which stops `GENESEED_LLM="claude -p"` (hooks not disabled) from recursing. Not meant to be set by hand. |
@@ -22,7 +22,7 @@ Where Geneseed writes an install, and what an upgrade re-renders.
22
22
  | `GENESEED_ACTIVITY` | hooks, OpenCode plugin | `off` (or `0`, `false`, `no`) stops the activity writer; the hooks then load none of its code. Absent means on. See [geneseed-activity](plugin-activity.md). |
23
23
  | `GENESEED_NO_SHIM_CHECK` | CLI | `1` silences the warning every `geneseed` command prints when the hook shim points at a path that no longer exists. For scripted callers; the `status` gates row still says `DEAD`. |
24
24
  | `OPENCODE_CONFIG_DIR` | OpenCode emits, `diff`, plugins | OpenCode's config dir — where the global install is written. OpenCode still loads `$XDG_CONFIG_HOME/opencode` beside it, so `status` and `doctor` warn when both hold a Geneseed install. |
25
- | `XDG_CONFIG_HOME` | OpenCode emits, plugins | Used when `OPENCODE_CONFIG_DIR` is unset: the install goes to `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). |
25
+ | `XDG_CONFIG_HOME` | every emit, hooks, plugins, web console | The base of the [shared tier](../concepts/shared-tier.md), `$XDG_CONFIG_HOME/geneseed` (default `~/.config/geneseed`), on every host. Also used when `OPENCODE_CONFIG_DIR` is unset: the install goes to `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). |
26
26
  | `CLAUDE_CONFIG_DIR` | Claude Code emits, hooks, lifecycle verbs | Claude Code's config dir (default `~/.claude`) — where the global install is written. A Geneseed install left in `~/.claude` is still treated as a global, never as a project at your home folder. |
27
27
  | `BOB_CONFIG_DIR` | Bob emits | Bob's config dir (default `~/.bob`). |
28
28
  | `OPENCLAUDE_CONFIG_DIR` | OpenClaude emits | OpenClaude's own config-dir variable (default `~/.openclaude`); also moves `.openclaude.json`. |
@@ -24,6 +24,8 @@ Every word Geneseed uses that you would not find in a general programming glossa
24
24
  | Memory | MEMORY | durable, one-fact-per-file knowledge | a team wiki the agent writes |
25
25
  | Notebook | NOTEBOOK | the agent's sovereign space | the agent's scratch branch |
26
26
  | Wiki | WIKI | the machine-wide knowledge base | your personal notes, shared with the agent |
27
+ | Shared tier | — | the machine-wide folder `~/.config/geneseed`: rules, profile, memory, wiki manifest, exclude paths and notes, read by every global install | `~/.gitconfig` beside each repo's config |
28
+ | Fold | — | the step of a global emit that moves a host's stores into the shared tier, moved aside and never deleted | a migration that runs at deploy |
27
29
  | Pact | PACT | the two-way collaboration contract, stated in Telos, the first Ethos section | a working agreement |
28
30
  | Posture | — | the relationship register the agent works in (peer, mentor, expert, assistant, artisan) | pairing style |
29
31
  | Mode | — | how work gets executed — direct (the agent works every task itself) or foreman (tasks that would block the session go to a background task worker) | solo vs. delegating to a sub-team |