geneseed 4.32.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 (245) hide show
  1. package/CHANGELOG.md +85 -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 +4 -2
  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 +116 -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 +126 -68
  67. package/harness.config.json +1 -1
  68. package/js/README.md +10 -6
  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/source.mjs +4 -1
  79. package/js/build/stubs.mjs +70 -9
  80. package/js/build/version.mjs +10 -10
  81. package/js/cli-table.json +23 -83
  82. package/js/hosts/activity.mjs +2 -2
  83. package/js/hosts/geneseed-dir.mjs +1 -1
  84. package/js/hosts/hooks-context.mjs +389 -99
  85. package/js/hosts/hooks-learn.mjs +38 -7
  86. package/js/hosts/hooks-prims.mjs +4 -2
  87. package/js/hosts/hooks.mjs +114 -39
  88. package/js/hosts/hosts.mjs +150 -51
  89. package/js/hosts/installs.mjs +55 -167
  90. package/js/hosts/link.mjs +3 -5
  91. package/js/hosts/mcp.mjs +1 -1
  92. package/js/hosts/memory-files.mjs +219 -17
  93. package/js/hosts/ownership-gate.mjs +1 -1
  94. package/js/hosts/settings.mjs +18 -13
  95. package/js/hosts/shim.mjs +4 -33
  96. package/js/hosts/store-watch.mjs +189 -0
  97. package/js/inspect/checks-authoring.mjs +3 -3
  98. package/js/inspect/checks-build.mjs +45 -18
  99. package/js/inspect/checks-counts.mjs +4 -4
  100. package/js/inspect/checks-repo.mjs +13 -14
  101. package/js/inspect/cost.mjs +24 -2
  102. package/js/inspect/diff.mjs +123 -123
  103. package/js/inspect/doctor.mjs +22 -27
  104. package/js/inspect/excludes.mjs +181 -62
  105. package/js/inspect/inventory.mjs +22 -27
  106. package/js/inspect/registry.mjs +106 -30
  107. package/js/inspect/scan.mjs +5 -5
  108. package/js/inspect/status.mjs +141 -119
  109. package/js/inspect/validate.mjs +22 -24
  110. package/js/lib/fs.mjs +47 -50
  111. package/js/lib/json.mjs +10 -17
  112. package/js/lib/machine-dir.mjs +73 -0
  113. package/js/lib/paths.mjs +22 -33
  114. package/js/lib/proc.mjs +1 -1
  115. package/js/lib/prompt.mjs +19 -27
  116. package/js/lib/text.mjs +8 -12
  117. package/js/lib/udiff.mjs +11 -15
  118. package/js/loop/catalog.mjs +2 -3
  119. package/js/maintain/memory.mjs +17 -17
  120. package/js/maintain/migrate.mjs +79 -89
  121. package/js/maintain/setup.mjs +43 -32
  122. package/js/maintain/uninstall.mjs +43 -61
  123. package/js/maintain/update.mjs +200 -93
  124. package/js/ui/anim.mjs +21 -35
  125. package/js/ui/cli.mjs +36 -58
  126. package/js/ui/menu.mjs +22 -45
  127. package/js/ui/tui.mjs +27 -67
  128. package/js/web/actions.mjs +34 -34
  129. package/js/web/api.mjs +130 -74
  130. package/js/web/catalog.mjs +175 -46
  131. package/js/web/docs.mjs +33 -12
  132. package/js/web/doctor-worker.mjs +14 -0
  133. package/js/web/handler.mjs +14 -5
  134. package/js/web/routes.mjs +17 -19
  135. package/js/web/state.mjs +78 -19
  136. package/js/web/update-check.mjs +25 -10
  137. package/js/web/user-files.mjs +50 -105
  138. package/package.json +7 -4
  139. package/registry.json +48 -55
  140. package/src/AGENT.md.tmpl +13 -14
  141. package/src/agents/_self-improvement.md +1 -1
  142. package/src/agents/_template.md +1 -1
  143. package/src/agents/advocate.md +1 -1
  144. package/src/agents/architect.md +1 -1
  145. package/src/agents/developer.md +1 -1
  146. package/src/agents/devops-engineer.md +1 -1
  147. package/src/agents/docker-expert.md +1 -1
  148. package/src/agents/docs.md +1 -1
  149. package/src/agents/empiricist.md +1 -1
  150. package/src/agents/explorer.md +1 -1
  151. package/src/agents/framer.md +1 -1
  152. package/src/agents/historian.md +1 -1
  153. package/src/agents/kubernetes-specialist.md +1 -1
  154. package/src/agents/memory-curator.md +2 -2
  155. package/src/agents/operator.md +1 -1
  156. package/src/agents/performance.md +1 -1
  157. package/src/agents/pragmatist.md +1 -1
  158. package/src/agents/react-engineer.md +1 -1
  159. package/src/agents/react-reviewer.md +1 -1
  160. package/src/agents/researcher.md +1 -1
  161. package/src/agents/reviewer.md +1 -1
  162. package/src/agents/security.md +1 -1
  163. package/src/agents/skeptic.md +1 -1
  164. package/src/agents/spring-boot-engineer.md +1 -1
  165. package/src/agents/spring-reviewer.md +1 -1
  166. package/src/agents/spring-security.md +1 -1
  167. package/src/agents/steward.md +1 -1
  168. package/src/agents/tester.md +1 -1
  169. package/src/agents/user-advocate.md +1 -1
  170. package/src/agents/visionary.md +1 -1
  171. package/src/memory/README.md +1 -1
  172. package/src/skills/_self-improvement.md +2 -2
  173. package/src/skills/daydream/SKILL.md +2 -2
  174. package/src/skills/daydream/instructions.md +1 -1
  175. package/src/skills/geneseed.md +1 -1
  176. package/src/skills/learn-mode.md +1 -2
  177. package/src/skills/profile.md +2 -2
  178. package/src/skills/rule/approve.md +69 -0
  179. package/src/skills/rule/consolidate.md +3 -3
  180. package/src/skills/rule.md +13 -5
  181. package/src/skills/skill-forge.md +1 -1
  182. package/src/skills/teach.md +29 -12
  183. package/src/skills/wiki.md +1 -1
  184. package/themes/_TEMPLATE.json +1 -2
  185. package/themes/biker.json +1 -2
  186. package/themes/commentator.json +1 -2
  187. package/themes/cyberpunk.json +1 -2
  188. package/themes/gamer.json +1 -2
  189. package/themes/imperial.json +1 -2
  190. package/themes/joker.json +1 -2
  191. package/themes/marvin.json +1 -2
  192. package/themes/mean.json +1 -2
  193. package/themes/military.json +1 -2
  194. package/themes/neutral.json +1 -2
  195. package/themes/pirate.json +1 -2
  196. package/themes/sports.json +1 -2
  197. package/themes/verstappen.json +1 -2
  198. package/themes/wizard.json +1 -2
  199. package/web/dist/assets/Activity-D8G4eClY.js +1 -0
  200. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
  201. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  202. package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
  203. package/web/dist/assets/{CopyButton-C5Li6awl.js → CopyButton-CHQte7Ap.js} +1 -1
  204. package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
  205. package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
  206. package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
  207. package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
  208. package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
  209. package/web/dist/assets/Kits-CoITzxWM.js +1 -0
  210. package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
  211. package/web/dist/assets/Library-DNwHYVXt.js +3 -0
  212. package/web/dist/assets/{Loops-CzitjxGV.js → Loops-S85PMQ8m.js} +2 -2
  213. package/web/dist/assets/{Markdown-C4S4tTA7.js → Markdown-0ORz7tAc.js} +21 -21
  214. package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
  215. package/web/dist/assets/Personal-afJNwvRS.js +2 -0
  216. package/web/dist/assets/{RailCats-D5weYPCS.js → RailCats-AW92uhsX.js} +1 -1
  217. package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
  218. package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
  219. package/web/dist/assets/api-C46vAuqp.js +1 -0
  220. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  221. package/web/dist/assets/index-COTd4TRZ.js +3 -0
  222. package/web/dist/assets/index-CtorA7uK.css +1 -0
  223. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  224. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  225. package/web/dist/index.html +5 -5
  226. package/src/skills/quiz.md +0 -44
  227. package/web/dist/assets/Activity-Bjy64wHC.js +0 -1
  228. package/web/dist/assets/ActivityDetail-B0AaipP8.js +0 -1
  229. package/web/dist/assets/Bonsai-CJniRqaH.js +0 -1
  230. package/web/dist/assets/Dashboard-B-6DTmae.js +0 -2
  231. package/web/dist/assets/Docs-LRc30XL9.js +0 -5
  232. package/web/dist/assets/GreenhouseView-CcoYlaWo.js +0 -1
  233. package/web/dist/assets/Installs-dp1epTcE.js +0 -3
  234. package/web/dist/assets/JournalView-nFP4poCf.js +0 -1
  235. package/web/dist/assets/KitApply-DwyZUj57.js +0 -1
  236. package/web/dist/assets/Kits-C0IEdZXe.js +0 -1
  237. package/web/dist/assets/Laws-CkykmQWu.js +0 -3
  238. package/web/dist/assets/Library-Guh9HBZU.js +0 -2
  239. package/web/dist/assets/OperatorHudView-DLGNulIY.js +0 -1
  240. package/web/dist/assets/Personal-BMtberL8.js +0 -2
  241. package/web/dist/assets/Tabs-uYJqfuQt.js +0 -1
  242. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  243. package/web/dist/assets/index-DA7BiaE5.js +0 -3
  244. package/web/dist/assets/index-dbbDGFDq.css +0 -1
  245. package/web/dist/assets/motion-Bccx3zE8.js +0 -1
@@ -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,6 +12,7 @@ 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
 
@@ -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)). The guard also refuses a write to the other hosts' Geneseed-only files (their `excludes.json`, `AGENT.md` and manifests); 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
- - **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,7 +27,7 @@ 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`.
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
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
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.
33
33
 
@@ -10,6 +10,8 @@ Bob and the plain bundle carry the same rules, agents and skills as the other ho
10
10
 
11
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
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).
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
 
15
17
  ---
@@ -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)
@@ -12,25 +12,27 @@ What an OpenCode install writes, piece by piece. The **Kind** words are explaine
12
12
  | Piece | What it does for you | Kind | Cost | Turn it off |
13
13
  |---|---|---|---|---|
14
14
  | `AGENT.md` | The rules, the pointers to agents and skills, and how memory works | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
15
- | `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
- | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
15
+ | `user-rules.md` | Your own standing rules, read every session. A global install reads the [shared](../concepts/shared-tier.md) file first, then this one, which can narrow it. Seeded empty | asked | 0 until you write in it | Leave it empty |
16
+ | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill. On a global install it lives in the shared tier, and a filled host file replaces the shared one | asked | 0 until you fill it | Leave the seeded text untouched |
17
17
  | `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `git reflog expire`, `git gc --prune` or a force-push or delete of `main`/`master`, and before every commit and push when the **process** pack is on. `permission.skill` denies each user-only skill, so the model never starts it but `/name` still runs it; Geneseed takes back only the denies it wrote | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
18
18
  | context plugin | Puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `GENESEED_CONTEXT_INJECT=off` |
19
19
  | guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), every other real data loss judged against the repository's state, a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours. In an application repo with no `## Ownership` section in its root `AGENTS.md`, refuses the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block; the ownership refusal alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
20
- | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into `memory/` with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
20
+ | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into the memory store with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
21
21
  | activity plugin | Writes one small file per session that the web console's Activity view shows: what the session does now, its sub-agents, the files each of them changed (by path inside the repository), its turns, how full its context is and its compactions | automatic | No tokens | `GENESEED_ACTIVITY=off` |
22
22
  | notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
23
23
  | ponytail plugin | Minimal-code mode. `/ponytail lite`, `full` or `ultra` adds a short ruleset to every turn until you switch it off | on demand | 0 while off, which is the default | `/ponytail off` |
24
24
  | workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
25
25
  | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
26
26
  | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
27
- | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
28
- | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
27
+ | `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects. A global install keeps them in the shared `~/.config/geneseed/memory/`; this folder holds only the convention and a seeded index | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
28
+ | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl`. It stays per host; on a global install only the self-improvement notes live in the shared `notes/` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
29
29
 
30
30
  ## Where the files are
31
31
 
32
32
  **OpenCode.** A global install writes to `~/.config/opencode/`. Setting `OPENCODE_CONFIG_DIR` or `XDG_CONFIG_HOME` moves it. Geneseed merges its entries into your existing `opencode.json` and keeps every other key. A per-repo install writes into the repo instead.
33
33
 
34
+ **Shared by every host.** Each global install also reads and writes one machine-wide folder, `~/.config/geneseed/`: your rules, profile, memory, wiki manifest, exclude paths and notes. See [The shared tier](../concepts/shared-tier.md). A per-repo install keeps its own copies.
35
+
34
36
  ---
35
37
 
36
38
  **Next:** [On Bob, or any AGENT.md tool](machine-bob.md) · [Taking it back out](take-it-out.md)
@@ -15,6 +15,10 @@ An install writes a handful of files into your host's config folder and, where t
15
15
 
16
16
  Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about 5k on the rules file. For a live figure on your own install, ask the agent to use the `token-report` skill.
17
17
 
18
+ ## One folder for the whole machine
19
+
20
+ Host config folders are not the only place. Every global install shares `~/.config/geneseed/`, which holds what you teach the agent: your rules, profile, memory, wiki manifest, exclude paths and notes. Teach one tool something, and the others know it. See [The shared tier](../concepts/shared-tier.md). The rules text, agents, skills and kits stay in each host's own folder.
21
+
18
22
  ## One page per host
19
23
 
20
24
  <!--harness:opencode-->
@@ -6,7 +6,7 @@ kind: "concept"
6
6
  section: "On your machine"
7
7
  description: "What geneseed uninstall removes, and what it keeps for you."
8
8
  ---
9
- `geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. A file Geneseed wrote that you have since edited stays too, and becomes yours; add `--force` to delete edited files as well. See [Uninstall](../guides/uninstall.md).
9
+ `geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). It never touches the [shared tier](../concepts/shared-tier.md), `~/.config/geneseed/`, even for the last host: it prints where the tier lives, and removing it is your call. Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. A file Geneseed wrote that you have since edited stays too, and becomes yours; add `--force` to delete edited files as well. See [Uninstall](../guides/uninstall.md).
10
10
 
11
11
  ---
12
12