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
@@ -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 |
@@ -14,7 +14,7 @@ The actions of `geneseed loop`, the state machine behind [Loops](../concepts/loo
14
14
  | `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
15
15
  | `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
16
16
  | `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
17
- | `record` | records a brick's reported outcome and advances the graph; `--note` or `--note-file <path>` carries a finding (a read brick's plan or review findings) into `LOOP.md`'s notes so it survives the unit |
17
+ | `record` | records a brick's reported outcome and advances the graph; `--note` or `--note-file <path>` carries a finding into `LOOP.md`'s notes for the bricks after it: a plan survives the unit, and `review` and `mutation-check` findings last until `apply` reports. `test` cannot report `pass` when that note lists a check as `SKIPPED`: the record is refused and `LOOP.md` does not change |
18
18
  | `decide` | answers an `awaiting` validation with a verdict and a note |
19
19
 
20
20
  Run `geneseed loop --help` for the full flag list.
@@ -18,7 +18,7 @@ Every plugin swallows its own errors — none can block or crash a session. Each
18
18
 
19
19
  The same files work on OpenCode 1 (1.3.4 or newer) and OpenCode 2. OpenCode 2 rewrote the plugin API, and each plugin carries both halves. You don't need to configure anything. Two differences show on OpenCode 2:
20
20
 
21
- - **A guard block shows up as a failed tool call.** The call never runs. The model gets an error that starts with `[geneseed-guard] blocked:` and gives the reason.
21
+ - **A guard block shows up as a failed tool call.** The call never runs. The model gets an error that starts with `[geneseed-guard] blocked:` and gives the reason; on OpenCode 2 that text follows `BLOCKED, not a missing tool: `.
22
22
  - **The Activity view shows no todo list, and files touched have no line counts.** OpenCode 2 publishes no todo event. It names the files each step changed, but not how many lines, and an undo does not remove a file from the list.
23
23
 
24
24
  If a plugin seems silent on OpenCode 2, check that `~/.config/opencode/plugins/` holds the current files. Copies from before this change fail to load with *"Plugin must export a default definition with an id and an effect or setup function"*. Running `geneseed rebuild-all` replaces them.
@@ -27,7 +27,7 @@ If a plugin seems silent on OpenCode 2, check that `~/.config/opencode/plugins/`
27
27
 
28
28
  - [geneseed-context](plugin-context.md): Puts your project docs, rules, profile, memory index and wiki in front of the agent.
29
29
  - [geneseed-guard](plugin-guard.md): Blocks credential files, catastrophic commands and protected wiki writes before they run.
30
- - [geneseed-learn](plugin-learn.md): Distils durable facts into memory/ once a session goes quiet.
30
+ - [geneseed-learn](plugin-learn.md): Distils durable facts into the memory store once a session goes quiet.
31
31
  - [geneseed-workflow](plugin-workflow.md): Adds a workflow tool that runs saved orchestration scripts.
32
32
  - [geneseed-notify](plugin-notify.md): A desktop notification when a long turn finishes.
33
33
  - [geneseed-ponytail](plugin-ponytail.md): An opt-in minimal-code mode, re-applied every turn.
@@ -35,4 +35,4 @@ If a plugin seems silent on OpenCode 2, check that `~/.config/opencode/plugins/`
35
35
 
36
36
  ## Excluded folders
37
37
 
38
- `geneseed-context`, `geneseed-guard` and `geneseed-learn` go dormant inside a folder listed in the global install's `excludes.json` (managed by `geneseed exclude`), and inside any linked git worktree of such a folder. See [Exclusions](../concepts/exclusions.md).
38
+ `geneseed-context`, `geneseed-guard` and `geneseed-learn` go dormant inside a folder listed in the shared `excludes.json` or the global install's own (managed by `geneseed exclude`), and inside any linked git worktree of such a folder. See [Exclusions](../concepts/exclusions.md).
@@ -16,7 +16,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
16
16
 
17
17
  **Archive.** On `SessionStart` and `SessionEnd` the hook writer moves every snapshot that is no longer live into `activity/archive/`, keeping the newest 50 and none older than 7 days. `/api/activity` returns them, with the stale and dead ones still in `activity/`, in its `ended` list — capped there by the same rule, since the OpenCode plugin never sweeps.
18
18
 
19
- **What `/api/activity` returns.** One list over every active install on the machine (each install's `activity/` folder), so it ignores a `?host=&path=` pair. It returns `enabled`, `installs`, `activity` (the live sessions), `ended`, and `collisions`. `installs` has one `{install, host, scope, path, enabled}` row per active install, in the same fixed order: `install` is the `host:scope:root` key that `/api/usage` also uses, `path` is the install root as `/api/installs` gives it, and `enabled` is that install's own on/off flag. An install that is off gives no session. The top-level `enabled` is true when any install is on, or when no install is active. `ended` keeps the newest 50 over all installs. A global and a project install of one host both record the same session (both hooks run), so the copies that share a session id and a checkout (the same `root`, case-folded on Windows, or the same `cwd` when there is no root) are one session. Its data comes from the newest copy. `installs` lists every install that recorded it in a fixed order (host order: OpenCode, Claude Code, Bob, OpenClaude; then global before project; then detection order), and `install`, the first of them, names the install the chip shows and the detail link reads. The order never follows recency, because two installs write one session milliseconds apart. The session also has a `key` (its id and its checkout, with a trailing separator dropped) that never names an install, so the console keeps the same card from poll to poll. A detail page that is already open keeps reading the install its link names. Such a session never collides with itself. The same id in two checkouts stays two sessions. Each collision writer carries `install` too. An OpenCode project install has no `installs` row: the plugin always writes its sessions and reads its on/off flag in the global OpenCode config folder, so OpenCode project sessions appear under, and follow the switch of, the OpenCode global install. Each session carries the snapshot as written, plus the v2 fields: `root` (the git root of the session's own checkout, read from the session's directory: never the plugin instance's, since one `opencode serve` hosts an instance per opened project and each hears every session; `null` outside any repository), `repo` (its main worktree), `agents` (`{id, type, status, started}`), `attribution` (`false` only on a Bob session that ran a sub-agent, else `null`), `turns`, `context` (`{used, window}`), `compactions`, `compacted_at` and `context_at_compaction` (either `context` field can be `null`, right after a compaction for one), and `repo_key`, the repo (else the root) case-folded on Windows, to group a repo's sessions whatever case each host spelled it in. A v1 snapshot reads `null` for those, `[]` for `agents` and `0` for the counts. A live session also gets `files_all`, the uncapped file rows from its detail file (`files` stays the capped summary), and `loops`: `{title, iteration, status}` for each loop registered on its `root`, a finished or unreadable loop left out. `collisions` lists each `{repo, path}` that two or more writers changed among the live sessions — a writer is a session or one of its sub-agents (`{sid, by, root, install}`), and sessions from different installs collide too — with `kind: "same-worktree"` when two of them share a `root`, else `"cross-worktree"`. A file outside the root is stored with `path: null` (its `file` keeps the basename) and takes no part in a collision. Roots and paths compare case-folded on Windows, and a session root is resolved to its real path before the loop join, as the loop registry stores it. `/api/activity/<id>?host=&path=` returns the same fields for one session of the install the pair names (the console's link carries it), an archived one included; with no pair it reads the default install (the first active one). `POST /api/activity` with `{enabled, host, path}` turns tracking on or off for that install only.
19
+ **What `/api/activity` returns.** One list over every active install on the machine (each install's `activity/` folder), so it ignores a `?host=&path=` pair. It returns `enabled`, `installs`, `activity` (the live sessions), `ended`, and `collisions`. `installs` has one `{install, host, scope, path, enabled}` row per active install, in the same fixed order: `install` is the `host:scope:root` key that `/api/usage` also uses, `path` is the install root as `/api/installs` gives it, and `enabled` is that install's own on/off flag. An install that is off gives no session. The top-level `enabled` is true when any install is on, or when no install is active. `ended` keeps the newest 50 over all installs. A global and a project install of one host both record the same session (both hooks run), so the copies that share a session id and a checkout (the same `root`, case-folded on Windows, or the same `cwd` when there is no root) are one session. Its data comes from the newest copy. `installs` lists every install that recorded it in a fixed order (host order: OpenCode, Claude Code, Bob, OpenClaude; then global before project; then detection order), and `install`, the first of them, names the install the chip shows and the detail link reads. The order never follows recency, because two installs write one session milliseconds apart. The session also has a `key` (its id and its checkout, with a trailing separator dropped) that never names an install, so the console keeps the same card from poll to poll. A detail page that is already open keeps reading the install its link names. Such a session never collides with itself. The same id in two checkouts stays two sessions. Each collision writer carries `install` too. An OpenCode project install has no `installs` row: the plugin always writes its sessions and reads its on/off flag in the global OpenCode config folder, so OpenCode project sessions appear under, and follow the switch of, the OpenCode global install. Each session carries the snapshot as written, plus the v2 fields: `root` (the git root of the session's own checkout, read from the session's directory: never the plugin instance's, since one `opencode serve` hosts an instance per opened project and each hears every session; `null` outside any repository), `repo` (its main worktree), `agents` (`{id, type, status, started}`), `attribution` (`false` only on a Bob session that ran a sub-agent, else `null`), `turns`, `context` (`{used, window}`), `compactions`, `compacted_at` and `context_at_compaction` (either `context` field can be `null`, right after a compaction for one), and `repo_key`, the repo (else the root) case-folded on Windows, to group a repo's sessions whatever case each host spelled it in. A v1 snapshot reads `null` for those, `[]` for `agents` and `0` for the counts. A live session also gets `files_all`, the uncapped file rows from its detail file (`files` stays the capped summary), and `loops`: `{title, iteration, status}` for each loop registered on its `root`, a finished or unreadable loop left out. `collisions` lists each `{repo, path}` that two or more writers changed among the live sessions — a writer is a session or one of its sub-agents (`{sid, by, root, install}`), and sessions from different installs collide too — with `kind: "same-worktree"` when two of them share a `root`, else `"cross-worktree"`. A file outside the root is stored with `path: null` (its `file` keeps the basename) and takes no part in a collision. Roots and paths compare case-folded on Windows, and a session root is resolved to its real path before the loop join, as the loop registry stores it. `/api/activity/<id>?host=&path=` returns the same fields for one session of the install the pair names (the console's link carries it), an archived one included; with no pair it reads the default install (the one chosen on the Installs page, else the first active one). `POST /api/activity` with `{enabled, host, path}` turns tracking on or off for that install only.
20
20
 
21
21
  **What you see.** A card per live session in **Activity** (`geneseed web`).
22
22
 
@@ -12,15 +12,20 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
12
12
 
13
13
  - **Injected in full (eager):** root `README.md`, `CONTRIBUTING.md` (or `README.adoc`, `CONTRIBUTING.adoc`), `.cursorrules`, `user-rules.md`, `PROFILE.md`. Budget-capped; an oversized file is listed instead, never silently truncated. (`AGENT.md`, `AGENTS.md` and `CLAUDE.md` are not injected — OpenCode already loads them.)
14
14
  - **Listed (lazy, path + first heading, read on demand):** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/`, and `packages/*/README.md` / `apps/*/README.md` in a monorepo, AsciiDoc `.adoc` docs included. `node_modules`, `.git`, `dist`, `build`, `vendor` and similar are never scanned.
15
+ - **Shared tier:** a global install reads `user-rules.md`, `PROFILE.md`, the memory index and the wiki manifest from [the shared tier](../concepts/shared-tier.md) first. A project install built `--shared-tier on` reads it too, unless a global OpenCode install already does.
15
16
  - **Machine wiki:** the wikis declared in `geneseed-wiki.jsonc` ride in the same block, on the same budgets. See [Wiki](../guides/wiki.md).
16
17
  - **Explicit manifest:** `$GENESEED_CONTEXT`, `.harness/context.json` or a root `context.json` takes over from discovery; `"extend": true` layers it on top instead. See [Project context](../guides/project-context.md).
17
18
 
18
19
  **When it runs.** On every request: the context rides invisibly in the request's message list, so it also survives compaction. If your OpenCode build lacks that (experimental) hook, the plugin notices and falls back to one visible message at session start, re-pushed when the session compacts.
19
20
 
21
+ **The weakened-test reminder.** A write tool call that adds a skip marker to a test file or removes an assertion (the rule in [Hooks](../concepts/hooks.md)) makes the next request carry one invisible message citing *Cure the Cause*, on OpenCode 1 and 2. It is advisory, needs no checks, and an install built `--no-done-gate` does not say it. The call is read before it runs, so one the guard then refuses is still named.
22
+
20
23
  **The done gate's reminder.** The project's checks come from `.geneseed/done-checks.txt`, or, without that file, are inferred from the manifests at the project's git root (see [Hooks](../concepts/hooks.md)). A request that follows a turn which edited files without every check passing since gets one more invisible message naming the checks owed (inferred ones marked advisory). OpenCode has no turn-end event a plugin can block on, so this is a reminder, not a block. OpenCode 1 only: on OpenCode 2 the turn is not judged, and with a listed file the plugin logs that once. The context block also opens with one line naming the checks and their source (`Done gate: …`), ending `(reminder)` for a listed file or `(advisory)` for inferred checks on OpenCode 1, and `(not judged on this host)` on OpenCode 2. `GENESEED_CONTEXT_INJECT=off` does not turn the reminder off; a done list that lists nothing does, and so does an install built `--no-done-gate` (`Done gate: off` in its `AGENT.md`, read once when OpenCode starts), which also silences the OpenCode 2 log line and the context line.
21
24
 
22
25
  **The ownership decline line.** In an application repo whose root `AGENTS.md` has no `## Ownership` section, a `Setup: declined <YYYY-MM-DD>` line in the personal `.geneseed/ownership.md` of the main worktree (the main checkout's, from a linked git worktree) adds one line beside the done line: `Ownership: setup declined since <date> — not set up; say "set up ownership" to run it`. An install built `--no-ownership-gate` (`Ownership gate: off` in its `AGENT.md`, read once when OpenCode starts) prints no such line.
23
26
 
27
+ **The runtime floor line.** A git root whose `package.json` has no `engines` field adds one line after those: `Runtime floor: package.json declares no engines — name the supported runtime before you add a dependency or a language feature.` There is no line when `engines` exists, when there is no `package.json`, or when the file is not a JSON object.
28
+
24
29
  **What you see.** Normally nothing — the context is there, but not shown. With the visible fallback, a `PROJECT CONTEXT` block at the top of the session.
25
30
 
26
31
  **Switches.**
@@ -10,18 +10,26 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
10
10
 
11
11
  **What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
12
12
 
13
- - **Blocks** writes to private-key and credential files and writes whose content carries a credential (*Sealed Secrets*; an install built `--no-secrets-gate` carries `Secrets gate: off` in its `AGENT.md`, read once at load, and both stop blocking), catastrophic shell commands such as deleting the filesystem root and every command that would really lose data — a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, a protected branch force-moved off commits nothing else holds, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, files git cannot restore removed — judged against the repository's state, the same decisions the Claude/Bob hook makes (*Deletion Is Deliberate*; `reflog expire` and `gc --prune` are left to the `permission.bash` ask; an install built `--no-deletion-gate` carries `Deletion gate: off` in its `AGENT.md`, which the plugin reads once at load and then stops blocking real loss — catastrophic commands still block), a recursive scan rooted at a whole filesystem such as `find /` (*Commands Must Return* — search a specific directory instead), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
14
- - **Refuses once** the first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the [ownership](../concepts/ownership.md) setup first; the next write passes, and a sub-agent's session never triggers it. Off per repo with `mode: off` in that section, or for one developer with a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`; an install built `--no-ownership-gate` carries `Ownership gate: off` in its `AGENT.md`, read once at load.
13
+ - **Blocks** writes to private-key and credential files and writes whose content carries a credential (*Sealed Secrets*; an install built `--no-secrets-gate` carries `Secrets gate: off` in its `AGENT.md`, read once at load, and both stop blocking), catastrophic shell commands such as deleting the filesystem root and every command that would really lose data — a protected branch deleted or force-pushed, an unpushed unmerged branch deleted, a protected branch force-moved off commits nothing else holds, unpushed commits abandoned by `reset --hard`, uncommitted work discarded other than by `reset --hard`, a stash dropped, files git cannot restore removed — judged against the repository's state, the same decisions the Claude/Bob hook makes (*Deletion Is Deliberate*; `reflog expire` and `gc --prune` are left to the `permission.bash` ask; an install built `--no-deletion-gate` carries `Deletion gate: off` in its `AGENT.md`, which the plugin reads once at load and then stops blocking real loss — catastrophic commands still block), a recursive scan rooted at a whole filesystem such as `find /` (*Commands Must Return* — search a specific directory instead), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `geneseed-wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)). The guard also refuses a write to the other hosts' Geneseed-only files (their `excludes.json`, `AGENT.md` and manifests) and to the shared exclude list in `~/.config/geneseed/`; OpenCode's own config and the shared hook settings get `permission.edit` "ask" keys in `opencode.json` instead, so you see OpenCode's prompt. A shell write is read as well: the targets of `>`, `>>`, `tee`, `sed -i`, `cp`, `mv` and `rm` get the same path checks, by path only. `permission.edit` never sees a shell command and this hook has no ask tier, so a shell write to those "ask" files is refused too.
14
+ - **Reminds, once:** it refuses the first write of a session in an application repo (a git root holding a build manifest) whose root `AGENTS.md` has no `## Ownership` section, so the agent proposes the [ownership](../concepts/ownership.md) setup first. This is a reminder, not a gate: the next write passes whatever the agent did, and a sub-agent's session never triggers it. Off per repo with `mode: off` in that section, or for one developer with a personal `Setup: declined <YYYY-MM-DD>` line in `.geneseed/ownership.md`; an install built `--no-ownership-gate` carries `Ownership gate: off` in its `AGENT.md`, read once at load.
15
15
  - **Warns** (logged, allowed) on `.env` writes.
16
- - **Speed-bumps** the *first* write to `user-rules.md` or a memory file: it is refused once, naming *Persist Insight* — whether something is a standing rule or a fact to remember is your call, settled through the `rule` skill. The re-issued write goes through.
16
+ - **Leaves to OpenCode's own prompt** a write to `user-rules.md`, `user-rules.draft.md` or a memory file (the install's own `memory/` or the shared one under `~/.config/geneseed/`), because whether something is a standing rule or a fact to remember is your call (*Persist Insight*). The emit writes `permission.edit` "ask" keys for them, so OpenCode asks you inside its edit, write and patch tools. On OpenCode 2 the `permission.hook("evaluate")` hook asks as well, even over an earlier "always". On OpenCode 1 the guard reads the merged config and refuses the write when it would not make the host ask. The check reads the file a write lands on: `..` and `//` folded, links followed and, on Windows, a stream or trailing dots and spaces taken off. It covers a project install's own store beside its `AGENT.md` (`Harness/memory` by default) and the stores `$GENESEED_HARNESS` and `$GENESEED_MEMORY` name. A file-tool write the host cannot prompt for is refused, so a re-issue changes nothing: any tool other than OpenCode's own edit tools and a named read set (the path-like arguments it carries are read), a config or an agent's own rules with no ask for that path, and on OpenCode 1 any write after you answered "always" to an edit.
17
17
 
18
- It ships whole on every install, whatever [doctrine packs](../concepts/rules.md) you chose. On Claude Code and Bob the same checks are hooks, which can *ask* you instead of refusing; OpenCode's tool hook has no ask tier. Protected wiki folders are enforced only here — on the other hosts they are an instruction.
18
+ **Shell is not a boundary.** The guard reads only the parsed forms: a redirect, `tee`, `cp`, `mv`, `rm` and `sed -i`. One that lands in a store gets OpenCode's prompt on OpenCode 2, through `evaluate` on the shell tool's own permission check, and is refused on OpenCode 1, which cannot ask. Everything else in a command goes unread: `bash -c`, an interpreter, `dd`, `curl -o`, a variable. The host's own command permission (`permission.bash`) is the backstop for those, and the [change report](../concepts/hooks.md#the-change-report) tells you afterwards. It detects; it does not prevent.
19
19
 
20
- There is no DYNAMIC loop/* exemption on OpenCode — it declares a `permission.ask` plugin hook but never calls it, so this guard cannot let a loop's own commit through the way the Claude/Bob git-gate's `loopExempt` does. A loop's commit on OpenCode still gets the static `permission.bash` ask, every time. A push to a `loop/*` branch does not: pushing a loop branch is not pushing `main`/`master`, so [`js/hosts/settings.mjs`](../../js/README.md) wires a static `allow` for the exact refspec shapes the loop engine pushes (`git push [-u] <remote> HEAD:loop/<slug>`, and the `refs/heads/` spelling) — never `main`/`master`, and a force push, a `+refspec`, or a `--delete`/bare-`:` push to a `loop/*` branch still asks, through the push chain's own tiers or the blanket `git push*` ask.
20
+ It ships whole on every install, whatever [doctrine packs](../concepts/rules.md) you chose. On Claude Code the same checks are hooks, which can *ask* you instead of refusing; Bob has no ask tier, so its hook blocks or warns; OpenCode's tool hook has no ask tier either, so an ask there comes from `permission.edit`.
21
+
22
+ **"Always" on OpenCode 1.** Its edit tools offer "always" with the pattern `*`, which approves every edit until OpenCode restarts. The host would then ask nothing, so the guard refuses rule and memory writes from that answer on, and writes to the files `permission.edit` asks about, such as `opencode.json` and the guard itself. Restart OpenCode to get the prompt back. The guard sees only an answer it heard: one given in this OpenCode instance after the plugin loaded. OpenCode 2 asks whatever you answered before.
23
+
24
+ **Agents on OpenCode 1.** The tool hook does not name the agent, so the guard reads every agent's rules through `client.app.agents()` and passes a write only if none of them allows it outright. One agent with its own `edit: allow` therefore refuses these writes for all of them.
25
+
26
+ Protected wiki folders are enforced only here — on the other hosts they are an instruction.
27
+
28
+ There is no DYNAMIC loop/* exemption on OpenCode — OpenCode 1 declares a `permission.ask` plugin hook but never calls it, so this guard cannot let a loop's own commit through the way the Claude/Bob git-gate's `loopExempt` does. A loop's commit on OpenCode still gets the static `permission.bash` ask, every time. A push to a `loop/*` branch does not: pushing a loop branch is not pushing `main`/`master`, so [`js/hosts/settings.mjs`](../../js/README.md) wires a static `allow` for the exact refspec shapes the loop engine pushes (`git push [-u] <remote> HEAD:loop/<slug>`, and the `refs/heads/` spelling) — never `main`/`master`, and a force push, a `+refspec`, or a `--delete`/bare-`:` push to a `loop/*` branch still asks, through the push chain's own tiers or the blanket `git push*` ask.
21
29
 
22
30
  **When it runs.** Before every tool call (`tool.execute.before`).
23
31
 
24
- **What you see.** A refused tool call: `[geneseed-guard] blocked: <reason>`. The reason never names the switches below: the agent reads it, and a switch named there reads as leave to get round the block. The *Persist Insight* reason tells the agent to ask you and, once you answer, re-issue the same refused edit — never to write the file another way (through a shell command, say). Warnings go to stderr.
32
+ **What you see.** A refused tool call: `[geneseed-guard] blocked: <reason>`. OpenCode 2 refuses by renaming the call and prints `No tool named "<name>"`, so there the name opens `BLOCKED, not a missing tool: `. The reason never names the switches below: the agent reads it, and a switch named there reads as leave to get round the block. The *Persist Insight* reason tells the agent to ask you and that a re-issue changes nothing — never to write the file another way (through a shell command, say). Warnings go to stderr.
25
33
 
26
34
  **Switches.**
27
35
  - `GENESEED_GUARD=warn` — log every block, allow the call.
@@ -4,11 +4,11 @@ kind: "concept"
4
4
  section: "OpenCode plugins"
5
5
  order: 15
6
6
  title: "geneseed-learn"
7
- description: "Distils durable facts into memory/ once a session goes quiet."
7
+ description: "Distils durable facts into the memory store once a session goes quiet."
8
8
  ---
9
9
  One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed in [Context and memory variables](env-context.md).
10
10
 
11
- **What it does.** Distils durable memories from the conversation into the install's `memory/` directory and keeps its two-level index (`MEMORY.md` and `topics/`) up to date. It never writes a twin of a stored fact: it updates that fact with the merged text instead (keeping the old version in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It is the OpenCode counterpart of the Claude Code `Stop` hook, but needs no API key and no model CLI: it distils with the **same model the session used**, through your OpenCode provider config. See [Memory](../concepts/memory.md).
11
+ **What it does.** Distils durable memories from the conversation into the memory store and keeps its two-level index (`MEMORY.md` and `topics/`) up to date. It never writes a twin of a stored fact: it updates that fact with the merged text instead (keeping the old version in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It is the OpenCode counterpart of the Claude Code `Stop` hook, but needs no API key and no model CLI: it distils with the **same model the session used**, through your OpenCode provider config. See [Memory](../concepts/memory.md).
12
12
 
13
13
  **When it runs.** After the session goes quiet. OpenCode signals "idle" after every turn, so each idle re-arms a timer and the distil runs once nothing has happened for `GENESEED_LEARN_DEBOUNCE_MS` (default 60 s). Trivial sessions are skipped.
14
14
 
@@ -16,11 +16,18 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
16
16
 
17
17
  **Where it writes** — the first that resolves:
18
18
  1. `GENESEED_MEMORY` — an explicit memory dir;
19
- 2. `$GENESEED_HARNESS/memory` (`/anamnesis` for the imperial theme);
20
- 3. the `memory/` beside the plugin's own install (the global install's store);
21
- 4. `./memory` or `./Harness/memory`, when the bundle lives in the project.
19
+ 2. `$GENESEED_HARNESS/memory`;
20
+ 3. the install's own target: a global install uses the shared store, `<machine dir>/memory`, when
21
+ it exists, else the `memory/` beside the plugin; a project install uses its own `memory/`;
22
+ 4. `./memory` or `./Harness/memory` in the repo, last, so a repo's own `memory/` folder never
23
+ takes the facts of a global session.
22
24
 
23
- So a global install needs nothing set; use `GENESEED_HARNESS` only to pin the location. If none resolves, it logs `no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY.` and does nothing.
25
+ The Stop hook of a global install passes `--memory <cfg>/memory` and `learn` swaps in the shared
26
+ store when it exists. A `--memory` you type yourself is never swapped: the swap applies only to a
27
+ hook call, which names its event. The plugin counts an install as global when its marker says so
28
+ or when it is the host's own config dir, as the hook does.
29
+
30
+ So a global install needs nothing set. `GENESEED_HARNESS` and `GENESEED_MEMORY` are deprecated, with removal planned for 6.0. If none resolves, it logs `no memory dir — this install has no memory/ folder, and neither does the shared tier or this repo.` and does nothing.
24
31
 
25
32
  **Switches.**
26
33
  - `GENESEED_MODEL=provider/model` — fallback when the session's model can't be read. Without it you get `could not determine a model`.
@@ -119,13 +119,13 @@ and unset `GENESEED_CONTEXT_INJECT`.
119
119
 
120
120
  **Cause.** The learn plugin found no memory directory, or it did not load.
121
121
 
122
- **Fix.** Pin the store, then restart OpenCode:
122
+ **Fix.** Run a global emit so the shared store `~/.config/geneseed/memory/` exists, then restart OpenCode. Confirm the `geneseed-*.js` files are in the plugins dir. A project install with no `memory/`, or a store elsewhere, needs one named:
123
123
 
124
124
  ```bash
125
- export GENESEED_HARNESS=~/.config/opencode
125
+ export GENESEED_MEMORY=/abs/path/to/memory
126
126
  ```
127
127
 
128
- (or `GENESEED_MEMORY` for an explicit directory), and confirm the `geneseed-*.js` files are in the plugins dir.
128
+ This variable and `GENESEED_HARNESS` win over the shared store, so leave them unset on a global install. Both are deprecated, with removal planned for 6.0.
129
129
 
130
130
  **Confirm.** About a minute after the session goes quiet, stderr shows `[geneseed-learn] wrote N memory file(s): …` or a `skipped:` reason. Total silence means the plugin did not load.
131
131
  <!--/harness-->
@@ -21,3 +21,17 @@ The upgrade is a `git pull`, so it first checks the folder. Each refusal says wh
21
21
  | ``Your branch has no upstream — set one with `git branch --set-upstream-to`.`` | `git branch --set-upstream-to=origin/main`. |
22
22
 
23
23
  **Confirm.** `geneseed upgrade` completes and `geneseed version` shows the new version. See [Upgrade](../guides/upgrade.md).
24
+
25
+ ## After an upgrade to 5.0
26
+
27
+ | What you see | Cause and fix |
28
+ | --- | --- |
29
+ | `geneseed: error: invalid choice: 'sync-self'.` | The verb is gone. Run `geneseed upgrade`. |
30
+ | `geneseed: error: unrecognized arguments: imperial` from `upgrade main imperial` | `upgrade` takes only a theme. Run `geneseed upgrade imperial`. |
31
+ | A host's `memory/` folder holds only its seed | Expected: [the fold](../concepts/shared-tier.md#the-fold) moved the facts to `~/.config/geneseed/memory/`. `geneseed memory list` shows them, and the old store is in `archived-memory/<stamp>/`. |
32
+ | `[shared] <host>: … rules to approve` | Those rules wait in `user-rules.draft.md` and still bind from the host file. Ask the agent to review the pending rules; the `rule` skill decides them. |
33
+ | `[shared] <host>: fold stopped at …` | One step failed. What it did not finish stays in place, and the next emit retries. Fix the cause the line names, then run `geneseed rebuild-all`. |
34
+ | A fact named `<name>-<host>.md` | Two hosts held different text under one name. Nothing was lost. The `memory-curator` agent can merge them. |
35
+ | `[shared-tier] <host>: the carrier renders …` from `doctor` | The tier moved, for example with `$XDG_CONFIG_HOME`. Run `geneseed rebuild-all`. |
36
+
37
+ **Confirm.** `geneseed migrate --dry-run` prints `nothing to fold` for each host. See [Upgrade to 5.0](../guides/upgrade-to-5.md).
@@ -38,8 +38,9 @@ never puts them, and none reached the session at all. The
38
38
  eager-injection path is budget-capped on every host. The SessionStart hook (Claude Code,
39
39
  Bob, OpenClaude) keeps its whole payload under 9,000 characters: Claude Code persists a
40
40
  hook output past ~10k to a file and shows the model a 2 KB preview, so until 2026-10 a
41
- doc-heavy repo's context was cut off unannounced. Session files come first, eager docs
42
- are injected whole or listed lazy with the reason. The OpenCode plugin has no such cap
41
+ doc-heavy repo's context was cut off unannounced. Session files come first, in the order
42
+ rules, profile, wiki, memory map, notebook, and a global install counts the shared tier's
43
+ layers with its own. Eager docs are injected whole or listed lazy with the reason. The OpenCode plugin has no such cap
43
44
  and keeps 16 KB per file / 48 KB per session. Both fold a lazy listing: three or more
44
45
  docs in one folder become one `dir/ — N docs` line. The hook also **never injects
45
46
  the root file the host loads by itself** (`CLAUDE.md` on Claude Code,
@@ -92,7 +93,7 @@ until 2026-09 it did, and the whole harness was paid twice per session.
92
93
  - **User-only skills leave the catalogue.** A skill whose source carries
93
94
  `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
94
95
  Code and Bob then drop its description from the always-on skill metadata and
95
- only `/name` opens it. The three teaching skills (`teach`, `quiz`, `learn-mode`)
96
+ only `/name` opens it. The two teaching skills (`teach`, `learn-mode`)
96
97
  carry it today.
97
98
  - **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
98
99
  ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
@@ -12,7 +12,7 @@ Start with one prompt on your first day:
12
12
 
13
13
  > *"Use the profile skill."*
14
14
 
15
- The agent interviews you briefly and drafts `PROFILE.md`: your role, your stack, and whether you want terse answers or explanations. From then on every session starts with it.
15
+ The agent interviews you briefly and drafts `PROFILE.md`, once for all your tools on a global install: your role, your stack, and whether you want terse answers or explanations. From then on every session starts with it.
16
16
 
17
17
  ### 1. The agent tries to push
18
18
 
@@ -55,7 +55,7 @@ The reviewer reads the change, runs the tests, and comes back with findings orde
55
55
 
56
56
  When a session winds down, the **learn** step reads the conversation and keeps what is worth remembering. On OpenCode this happens by itself, with the model the session already uses. On Claude Code it is off until you set `GENESEED_LLM` to a model command, for example `claude -p`.
57
57
 
58
- A new file appears in the install's `memory/` folder:
58
+ A new file appears in the memory store. On a global install that is `~/.config/geneseed/memory/`, so every host on the machine sees it; a project install keeps its own `memory/` folder:
59
59
 
60
60
  ```markdown
61
61
  ---
@@ -16,4 +16,5 @@ What Geneseed writes on your machine, and how it takes it back. Part of [Why Gen
16
16
  - **The installers check for Node and git and never install them.** Installing a prerequisite would make Geneseed a package manager on machines where software arrives through IT; the installer names what is missing and where to get it. See [From a clone](../guides/install-clone.md).
17
17
  - **A `--config-dir` preview is never registered, and the only dry run is `geneseed validate`.** A registered preview folder would be rebuilt by every `rebuild-all`, and the generator may not start the process a dry run needs. See [Verify it works](../guides/verify.md) and [Environment variables](../reference/environment.md).
18
18
  - **Uninstalling one host from a shared repo hands the root marker to the host that remains.** The marker names the install, so leaving the removed host's name there would drop the other host from the registry. See [Uninstall](../guides/uninstall.md).
19
- - **The old wiki file name, `wiki.jsonc`, is still read when `geneseed-wiki.jsonc` is absent, with no end date.** Removing the fallback would silently lose a wiki configured under the old name. See [Context and memory variables](../reference/env-context.md) and [Connect your wiki](../guides/wiki.md).
19
+ - **What you teach the agent lives once per machine, not once per host.** A global install reads and writes a shared tier, and existing stores fold into it in the emit, moved aside and never deleted. See [The shared tier](../concepts/shared-tier.md) and [ADR 0011](../adr/0011-shared-tier.md).
20
+ - **The old wiki file name, `wiki.jsonc`, is still read when `geneseed-wiki.jsonc` is absent, with no end date.** Removing the fallback would silently lose a wiki configured under the old name, so `status` and `rebuild-all` warn first, and name what the file renames to. See [Context and memory variables](../reference/env-context.md) and [Connect your wiki](../guides/wiki.md).
@@ -27,12 +27,13 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
27
27
  - **A scan of a whole filesystem**: a recursive `find`, `du`, `grep -r`, `rg` or `Get-ChildItem -Recurse` rooted at `/`, `/c` or `C:\`, which in Git Bash walks every drive for hours. Wired in every build.
28
28
  - **Credentials**: a write or edit whose content looks like a real key (AWS, GitHub, Anthropic, Slack, or a private-key block), anywhere except a `.env` file.
29
29
  - **Your rules and memory**: any write by the agent to `user-rules.md` or to the memory store. Whether something is a standing rule or a fact to remember is your call.
30
- - **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up now, skip this session, or skip in this repo until you ask. Off per repo with `mode: off`, for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, per install with `--no-ownership-gate`.
31
- - **Ending a turn without the proof**: only in a project that lists its checks in `.geneseed/done-checks.txt`. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped once, then the turn may end. Without that file, Geneseed infers the checks from the project's manifest (`package.json` scripts, Maven, Gradle, `pyproject.toml`, `Cargo.toml`, `go.mod`): you get a warning when a turn ends without them, but the turn is not stopped.
30
+ - **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, as a reminder rather than a gate, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up now, skip this session, or skip in this repo until you ask. Off per repo with `mode: off`, for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, per install with `--no-ownership-gate`.
31
+ - **The checks you are judged by, and the gates' own switches**: a write to a file listed in `.geneseed/protected-checks.txt`, to the done gate's list, or to a file that can switch a gate off (the hook settings, `excludes.json`, a gate marker in `AGENT.md`, the hook shim). You get a prompt. A shell write counts too, for the common forms: `>`, `>>`, `tee`, `sed -i`, `cp`, `mv`, `rm`. A script or an interpreter's inline code is not seen, so run the checks in CI as well.
32
+ - **Ending a turn without the proof**: only in a project whose `.geneseed/done-checks.txt` lists at least one check; a file that lists none turns the gate off for that project. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped once, then the turn may end. Without that file, Geneseed infers the checks from the project's manifest (`package.json` scripts, Maven, Gradle, `pyproject.toml`, `Cargo.toml`, `go.mod`): you get a warning when a turn ends without them, but the turn is not stopped.
32
33
 
33
34
  If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands go through Claude Code's normal permission flow; an `rm` of files git cannot restore is the real-loss case above.
34
35
 
35
- **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, and a write under a project's own protected-checks list. The commit/push and memory checks become a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
36
+ **Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and memory checks become a log line, and the call goes through. The ownership gate also refuses with exit 2, but once: the same write passes after you answer. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
36
37
 
37
38
  <!--/harness-->
38
39
  <!--harness:opencode-->
@@ -8,7 +8,9 @@ description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, a
8
8
  ---
9
9
  Bob and the plain bundle carry the same rules, agents and skills as the other hosts. What differs is where they land and how much of it is enforced. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
10
10
 
11
- **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, and a write under a project's own protected-checks list. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
11
+ **Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, a write under a project's own protected-checks list, and writes that would switch a gate off. The commit/push and memory questions become log lines. One more refusal happens only once: in an application repo whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused so the agent proposes the [ownership](../concepts/ownership.md) setup, and the same write passes after you answer. Turn it off per repo with `mode: off` in that section, for yourself in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, or per install with `--no-ownership-gate`.
12
+
13
+ **Shared by every host.** A global Bob install reads and writes the same machine-wide folder as the other hosts, `~/.config/geneseed/`: your rules, profile, memory, wiki manifest, exclude paths and notes. See [The shared tier](../concepts/shared-tier.md).
12
14
 
13
15
  **Plain bundle.** The `files` target writes `AGENT.md` and the same folders into `./Harness/` for any tool that reads `AGENT.md`. It installs no hooks and no plugins, so nothing in it is enforced.
14
16
 
@@ -12,16 +12,16 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
12
12
  | Piece | What it does for you | Kind | Cost | Turn it off |
13
13
  |---|---|---|---|---|
14
14
  | `CLAUDE.md` (managed block) | The rules, the pointers to agents and skills, and how memory works. Geneseed writes only its own block; your own lines in the file stay | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
15
- | `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
- | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
15
+ | `user-rules.md` | Your own standing rules, read every session. A global install reads the [shared](../concepts/shared-tier.md) file first, then this one, which can narrow it. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
+ | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill. On a global install it lives in the shared tier, and a filled host file replaces the shared one | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `geneseed exclude add <folder>` silences every hook in that folder |
18
18
  | git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a command that would really lose data — a force-push to `main`, a `reset --hard` that abandons unpushed commits, `branch -D` of an unpushed branch, an `rm` git cannot undo | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
19
19
  | rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
- | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into `memory/`. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
20
+ | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into the memory store. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
21
21
  | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
22
22
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
23
- | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
24
- | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
23
+ | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects. A global install keeps them in the shared `~/.config/geneseed/memory/`; this folder holds only the convention and a seeded index | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
24
+ | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl`. It stays per host; on a global install only the self-improvement notes live in the shared `notes/` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
25
25
  | hook shim | `~/.geneseed/bin/geneseed-hook`, the one stable path every hook calls, so moving the Geneseed checkout does not break your hooks | automatic | Nothing on its own | Not removed by uninstall, since every install on the machine shares it. `GENESEED_HOME` moves it |
26
26
 
27
27
  ## Where the files are
@@ -30,6 +30,8 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
30
30
 
31
31
  **OpenClaude.** Same pieces as Claude Code, under `~/.openclaude/` or `OPENCLAUDE_CONFIG_DIR`. A per-repo install uses `.openclaude/`, with the hooks in `.openclaude/settings.local.json`.
32
32
 
33
+ **Shared by every host.** Each global install also reads and writes one machine-wide folder, `~/.config/geneseed/`: your rules, profile, memory, wiki manifest, exclude paths and notes. See [The shared tier](../concepts/shared-tier.md). A per-repo install keeps its own copies.
34
+
33
35
  ---
34
36
 
35
37
  **Next:** [On Bob, or any AGENT.md tool](machine-bob.md) · [Taking it back out](take-it-out.md)