geneseed 3.12.0 → 3.13.0

package/docs/reference/troubleshooting.md

@@ -1,10 +1,12 @@
 ---
 group: reference
-order: 4
-title: "Troubleshooting"
 kind: "concept"
+section: "Troubleshooting"
+order: 5
+title: "Troubleshooting"
+description: "Problems organised by what you see, and the first command to run."
 ---
-Find what you are seeing below. Each entry gives the likely cause, the fix, and how to confirm it worked. Messages in quotes are what Geneseed actually prints.
+Find what you are seeing on the pages below. Each entry gives the likely cause, the fix, and how to confirm it worked. Messages in quotes are what Geneseed actually prints.
 
 First stop for almost anything: `geneseed doctor`. It renders the harness into a temp directory and reports every problem it finds without touching your install.
 
@@ -12,339 +14,13 @@ First stop for almost anything: `geneseed doctor`. It renders the harness into a
 geneseed doctor
 ```
 
-## Installing
-
-### `Node.js not found` or `Node vX is too old`
-
-The one-step installer (`./install`, `install.cmd`, `install.command`) checks Node first and stops:
-
-> `xx  Node v20.11.0 is too old — Geneseed needs 22.3 or newer.`
-
-**Cause.** No Node on PATH, or an older one — Linux distribution packages are often behind.
-
-**Fix.** Install the current Node.js LTS from <https://nodejs.org/> (macOS: `brew install node`; Linux: nvm or NodeSource). Open a **new** terminal, then run the installer again.
-
-**Confirm.**
-
-```bash
-node --version
-```
-
-prints 22.3 or newer, and the installer's first line reads `ok  Node v…`.
-
-### `geneseed needs Node 22.3 or newer`
-
-Run without the installer — `npx geneseed`, a global npm install, or a hook — on an older Node, every Geneseed command stops with one sentence:
-
-> `geneseed needs Node 22.3 or newer; this is Node 20.18.1. Install a current Node from https://nodejs.org (or your package manager), then run the command again.`
-
-**Cause.** The `node` on PATH is older than 22.3. npm only *warns* about the engine requirement, so a global install succeeds anyway. A hook prints the same sentence and lets the tool call through rather than block it, so on Claude Code, Bob or OpenClaude the hooks are off until Node is upgraded.
-
-**Fix.** Install the current Node.js LTS (see above), open a **new** terminal, and run the command again.
-
-**Confirm.** `geneseed version` prints the version instead of the sentence.
-
-### `setup` says it needs an interactive terminal
-
-> `[setup] needs an interactive terminal. Non-interactive? e.g.:`
-> `  geneseed build --emit opencode-global --theme neutral`
-
-**Cause.** `geneseed setup` is a wizard and refuses to run when its input is not a terminal — in CI, through a pipe, or from a tool that runs commands without a TTY.
-
-**Fix.** Run it from a real terminal, or skip the wizard and build directly with the flags it would have asked for:
-
-```bash
-geneseed build --emit opencode-global --theme neutral
-```
-
-See [Install](../guides/install.md) for the emit target that matches your tool.
-
-**Confirm.** `geneseed status` lists the install.
-
-### `setup` lists a tool as missing — or present — when it isn't
-
-Setup opens with `AI coding tools on this machine:` and an `ok` or `--` per tool.
-
-**Cause.** The check only asks whether the command (`opencode`, `claude`, `bob`, `openclaude`) is on your PATH. A desktop-only install with no command shows as missing; an unrelated program with the same name shows as present.
-
-**Fix.** Nothing to fix — the line is advisory. Pick the install mode for the tool you actually use; a missing tool among several present is just a line, and you can continue without one.
-
-**Confirm.** Open the tool and check for the readiness sigil (see "The agent never shows the readiness sigil" below).
-
-### `Java 21+ (jdtls) missing`
-
-Shown in setup's summary for OpenCode installs:
-
-> `Java 21+ (jdtls) missing — install a JDK 21+ — e.g. brew install openjdk@21, SDKMAN sdk install java 21-tem, or your distro's package`
-
-**Cause.** OpenCode's Java language server needs a JDK 21 or newer, and it is the one language server OpenCode cannot download for you. See [LSP](../concepts/lsp.md).
-
-**Fix.** Install a JDK 21+ if you work in Java; ignore the line otherwise. Everything else works without it.
-
-**Confirm.**
-
-```bash
-java -version
-```
-
-reports `version "21` or higher.
-
-### `geneseed: command not found`
-
-**Cause.** The `geneseed` launcher is not on your PATH. A git clone is not put there automatically (an `npm install -g geneseed` install is).
-
-**Fix.** From the cloned folder:
-
-```bash
-./geneseed link
-```
-
-```bat
-.\geneseed.cmd link
-```
-
-On Windows, `link` writes to `%LOCALAPPDATA%\Geneseed\bin` and adds it to your user PATH — only **new** terminals see it, so close and reopen yours.
-
-**Confirm.**
-
-```bash
-geneseed version
-```
-
-works from any directory. See [Run anywhere](../guides/run-anywhere.md).
-
-## Hooks, context and memory
-
-### Hooks stopped firing
-
-The agent loads its rules, but nothing is enforced and no memory is written — on Claude Code, Bob or OpenClaude.
-
-Every `geneseed` command now says so first, on stderr:
-
-> `[geneseed] ⚠ hooks are off on this machine: the hook shim points at <path>, which no longer exists. Fix: geneseed rebuild-all`
-
-and the `gates` row of `geneseed status` reads `DEAD — hook shim points at <path>; run: geneseed rebuild-all`. A script that must not see the line can set `GENESEED_NO_SHIM_CHECK=1`.
-
-**Cause.** Almost always a **stale hook shim**. Your tool's settings call `geneseed-hook` through one small script, `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows), which holds the absolute path of your Geneseed folder. Move or delete that folder and the shim points at nothing: the hooks still fire, fail, and every gate goes silently dead. `geneseed doctor` reports it as:
-
-> `[shim] <path> pointed at <old path>, which does not exist — every hook in every install was dead (the checkout most likely moved).`
-
-**Fix.** Re-emit from where Geneseed lives now — any build rewrites the shim:
-
-```bash
-geneseed rebuild-all
-```
-
-If you moved the shim itself with `GENESEED_HOME`, set it the same way before rebuilding.
-
-**Confirm.** `geneseed doctor` prints no `[shim]` line, and a new session opens with the readiness sigil and your project docs in context.
-
-### The agent never shows the readiness sigil
-
-The first reply of a session should open with the readiness sigil (`✅` in the neutral theme) — the agent's sign that it loaded the harness.
-
-**Cause.** The tool is not loading the root file. On OpenCode, `opencode.json` `instructions` does not point at `AGENT.md`; on another tool, its rules setting does not.
-
-**Fix.** Rebuild the install so its config is merged again:
-
-```bash
-geneseed rebuild-all
-```
-
-For a tool Geneseed does not wire itself, point its rules setting at the bundle's `AGENT.md`.
-
-**Confirm.** Start a **new** session; the first reply opens with the sigil. See [Verify](../guides/verify.md).
-
-<!--harness:opencode-->
-*(OpenCode only)*
-
-### The agent doesn't load my project docs
-
-**Cause.** The `geneseed-context` plugin is not in OpenCode's plugins directory, or injection is switched off (`GENESEED_CONTEXT_INJECT=off`).
-
-**Fix.**
-
-```bash
-geneseed build --emit opencode-global
-```
-
-and unset `GENESEED_CONTEXT_INJECT`.
-
-**Confirm.** `ls ~/.config/opencode/plugins/` shows the `geneseed-*.js` files, and a session started with `GENESEED_DEBUG=1` logs what the plugin discovered. See [OpenCode plugins](opencode-plugins.md).
-
-### `PROJECT CONTEXT` appears twice
-
-**Cause.** Two copies of the context plugin — the global one and a leftover `.opencode/plugins/` in the repo. OpenCode loads both.
-
-**Fix.** Delete the project copy (`.opencode/plugins/geneseed-context.js`), or uninstall the project-scoped install.
-
-**Confirm.** A new session shows the block at most once.
-
-### The full `PROJECT CONTEXT` block shows in the terminal
-
-**Cause.** Either `GENESEED_CONTEXT_VISIBLE=1` (or legacy `GENESEED_CONTEXT_TRANSFORM=0`) is set, or your OpenCode build lacks the experimental hook for invisible delivery and the plugin fell back to the visible block.
-
-**Fix.** Unset the variable. If it still shows, your OpenCode build is the reason — update OpenCode, or live with the visible block; the context is the same.
-
-**Confirm.** Run with `GENESEED_DEBUG=1`; the plugin's log says which delivery it used.
-
-### No memory is written after a session
-
-**Cause.** The learn plugin found no memory directory, or it did not load.
-
-**Fix.** Pin the store, then restart OpenCode:
-
-```bash
-export GENESEED_HARNESS=~/.config/opencode
-```
-
-(or `GENESEED_MEMORY` for an explicit directory), and confirm the `geneseed-*.js` files are in the plugins dir.
-
-**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.
-<!--/harness-->
-
-### `could not determine a model`
-
-**Cause.** The learn step could not read which model the session used.
-
-**Fix.** Give it a fallback:
-
-```bash
-export GENESEED_MODEL=provider/model
-```
-
-**Confirm.** The next session end writes memory instead of logging the message.
-
-### A read-only agent won't run a command
-
-**Cause.** By design: read-only agents are denied the shell. The few that must run read-only commands (the reviewer, security) are allowed it in their own spec.
-
-**Fix.** Hand the task to an agent that can run commands, or run it yourself. See [Agents](../concepts/agents.md).
-
-### PDFs and Office documents are ignored
-
-**Cause.** Agents read text. Binary documents need converting first.
-
-**Fix.** Use the `ingest` skill with a converter installed (MarkItDown, Pandoc or Docling), or wire MarkItDown as an MCP server — see [MCP servers](../guides/mcp.md).
-
-### An MCP server is listed but won't connect
-
-See [MCP servers](../guides/mcp.md) — each server has its own checks there.
-
-## Updating
-
-### `geneseed upgrade` refuses to run
-
-The upgrade is a `git pull`, so it first checks the folder. Each refusal says what to do:
-
-| Message | Fix |
-| --- | --- |
-| `git is not installed or not on PATH — install git to enable updates.` | Install git, open a new terminal, retry. |
-| ``This Geneseed install isn't a git checkout — update it with `npm install -g geneseed@latest`, or re-clone it with git.`` | Use the npm command for an npm install; otherwise re-clone (`git clone https://github.com/Arylmera/Geneseed.git`). |
-| `You have local changes in the Geneseed folder. Commit or stash them, then update.` | `git stash` in the Geneseed folder, upgrade, then `git stash pop`. |
-| ``HEAD is detached (a tag/commit is checked out). Run `git checkout <branch>` to re-enable updates.`` | `git checkout main`. |
-| ``Your branch has no upstream — set one with `git branch --set-upstream-to`.`` | `git branch --set-upstream-to=origin/main`. |
-
-**Confirm.** `geneseed upgrade` completes and `geneseed version` shows the new version. See [Upgrade](../guides/upgrade.md).
-
-## Doctor findings
-
-### `unresolved token … in …`
-
-**Cause.** A theme JSON lacks a key the templates use — usually a custom theme that fell behind.
-
-**Fix.** Compare it with `themes/neutral.json`: every key there must exist in your theme. Then re-render:
-
-```bash
-geneseed build --theme <yours>
-```
-
-**Confirm.** `geneseed doctor --theme <yours>` is clean.
-
-### A committed `Harness/` bundle drifted from `src/`
-
-**Cause.** A bundle committed to a repo was rendered from an older `src/`, or was edited in place.
-
-**Fix.** Re-render and commit it:
-
-```bash
-geneseed build
-git add Harness
-```
-
-If the drift is your own edits, export them first — `geneseed diff` (or the console's **Changes** page) writes them up so they can be folded back into `src/`.
-
-**Confirm.** `geneseed doctor` no longer reports the bundle.
-
-### `registry.json unreadable` / `registry.json is not valid JSON`
-
-> `[authoring] registry.json unreadable: …`
-
-**Cause.** The Geneseed folder's `registry.json` is missing or damaged — typically a bad merge or a hand edit. The web console stays up, but every entity's status badge reads "unknown".
-
-**Fix.** Restore the shipped copy (this discards any local edit to that one file):
-
-```bash
-git -C <geneseed folder> restore registry.json
-```
-
-**Confirm.** `geneseed doctor` no longer names `registry.json`, and the badges come back.
-
-## Web console
-
-### `web/dist is missing`
-
-> `[web] web/dist is missing. Build the UI first:`
-> `        cd web && npm install && npm run build`
-
-**Cause.** The built console ships in the repo, so this only happens on a partial checkout. On an interactive terminal `geneseed web` offers to build it for you.
-
-**Fix.** Build it from the Geneseed folder:
-
-```bash
-cd web && npm install && npm run build
-```
-
-If it instead says `web/ sources are missing`, run `geneseed upgrade` (twice on an old install).
-
-**Confirm.** `geneseed web` opens the console.
-
-### The console looks broken after an upgrade
-
-Pages fail to load, or the console shows a banner: *This console is running code from before your last upgrade.* `geneseed web status` adds:
-
-> `[web] running OLD code (started before the last upgrade) — geneseed web restart`
-
-**Cause.** The console server serves the page it started with. An `npm install -g geneseed@latest` or a `git pull` replaces `web/dist/`, and the old page asks for files that no longer exist. `geneseed upgrade` and `geneseed rebuild-all` restart a stale console themselves; other upgrade paths do not.
-
-**Fix.** Click **Restart** on the banner, or:
-
-```bash
-geneseed web restart
-```
-
-A browser refresh is not enough — the server, not the page, is out of date.
-
-**Confirm.** `geneseed web status` prints no `OLD code` line and the banner is gone.
-
-### The console says `no deployed harness`
-
-> `[web] no deployed harness at <dir>.`
-
-**Cause.** Nothing is installed where the console looks. It still serves, read-only, with most actions disabled.
-
-**Fix.**
-
-```bash
-geneseed setup
-```
-
-**Confirm.** Restart the console — `geneseed web restart` — and the warning is gone.
-
-### Skills or agents not tracked in git
-
-**Cause.** A parent `.gitignore` blanket-ignores the bundle directory.
+## By where it happens
 
-**Fix.** Remove the bare `Harness/` line from the parent `.gitignore`; the bundle's own `.gitignore` already scopes what to skip.
+- [Install problems](troubleshoot-install.md): Node, `setup`, `command not found`.
+- [Hook, context and memory problems](troubleshoot-hooks.md): hooks that stop firing, missing project docs, no memory.
+- [Model, agent and MCP problems](troubleshoot-tools.md): no model for learn, a read-only agent, ignored PDFs, an MCP server that will not connect.
+- [Update problems](troubleshoot-update.md): when `geneseed upgrade` refuses to run.
+- [Doctor findings](troubleshoot-doctor.md): what `geneseed doctor` reports, and the fix.
+- [Web console problems](troubleshoot-web.md): a missing build, a stale page, no deployed harness.
 
-**Confirm.** `git status` lists the bundle's files.
+A loop that misbehaves has its own table in [Finish a loop](../guides/loop-finish.md).

package/docs/understand/a-day.md

@@ -1,8 +1,10 @@
 ---
 group: understand
-order: 3
+order: 7
 title: "A day with the harness"
 kind: "concept"
+section: "Day to day"
+description: "The moments you will actually meet: a push that asks first, a skill, a delegation, a memory."
 ---
 After the install you talk to your tool the way you always did. What changes is what the agent already knows when you start, and what happens at a few specific moments. Here are four of them.
 

package/docs/understand/enforced-vs-asked.md

@@ -1,8 +1,10 @@
 ---
 group: understand
-order: 4
+order: 8
 title: "Enforced vs. asked"
 kind: "concept"
+section: "Day to day"
+description: "What is guaranteed by code, and what the model is only asked to do."
 ---
 Geneseed gives your agent two kinds of instruction, and it matters which kind you are relying on.
 

package/docs/understand/harness.md

@@ -3,6 +3,8 @@ group: understand
 order: 1
 title: "What a harness is"
 kind: "concept"
+section: "Start here"
+description: "Git hooks, CI and a runbook, but for your AI agent: what a harness is and why you would want one."
 ---
 Your coding agent starts every session knowing nothing about how you work. It does not know that you never push without looking at the diff first, that secrets live in `.env`, or that this repo's docs explain the build. You tell it again, or it guesses.
 

package/docs/understand/machine-bob.md

@@ -0,0 +1,17 @@
+---
+group: understand
+order: 5
+title: "On Bob, or any AGENT.md tool"
+kind: "concept"
+section: "On your machine"
+description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, and how little is enforced there."
+---
+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).
+
+**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 credentials and destructive git. The commit/push and memory questions become log lines.
+
+**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.
+
+---
+
+**Next:** [Taking it back out](take-it-out.md)

package/docs/understand/machine-claude.md

@@ -0,0 +1,35 @@
+---
+group: understand
+order: 4
+title: "On Claude Code and OpenClaude"
+kind: "map"
+harness: ["claude", "openclaude"]
+section: "On your machine"
+description: "Every file and hook a Claude Code or OpenClaude install writes: what it does, what it costs, how to turn it off."
+---
+What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
+
+| Piece | What it does for you | Kind | Cost | Turn it off |
+|---|---|---|---|---|
+| `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` |
+| `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
+| `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 |
+| 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 |
+| git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --` | 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` |
+| 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 | enforced | ~14 ms per write | `geneseed exclude add <folder>` |
+| 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) |
+| `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 |
+| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
+| `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>` |
+| `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 |
+| 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 |
+
+## Where the files are
+
+**Claude Code.** A global install writes to `~/.claude/`, and its hooks go into `~/.claude/settings.json`, next to any hooks of your own. A per-repo install uses the repo's `.claude/` folder, with the hooks in `.claude/settings.local.json`.
+
+**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`.
+
+---
+
+**Next:** [On Bob, or any AGENT.md tool](machine-bob.md) · [Taking it back out](take-it-out.md)

package/docs/understand/machine-opencode.md

@@ -0,0 +1,36 @@
+---
+group: understand
+order: 3
+title: "On OpenCode"
+kind: "map"
+harness: "opencode"
+section: "On your machine"
+description: "Every file and plugin an OpenCode install writes: what it does, what it costs, how to turn it off."
+---
+What an OpenCode install writes, piece by piece. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
+
+| Piece | What it does for you | Kind | Cost | Turn it off |
+|---|---|---|---|---|
+| `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` |
+| `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
+| `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 |
+| `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`, and before every commit and push when the **process** pack is on | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
+| 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` |
+| guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block |
+| 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 |
+| activity plugin | Writes one small file per session that the web console's Activity view shows | automatic | No tokens | `GENESEED_ACTIVITY=off` |
+| notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
+| 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` |
+| workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
+| `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 |
+| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
+| `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>` |
+| `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 |
+
+## Where the files are
+
+**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.
+
+---
+
+**Next:** [On Bob, or any AGENT.md tool](machine-bob.md) · [Taking it back out](take-it-out.md)

package/docs/understand/on-your-machine.md

@@ -2,9 +2,11 @@
 group: understand
 order: 2
 title: "What lands on your machine"
-kind: "map"
+kind: "concept"
+section: "On your machine"
+description: "What an install writes and wires, and the four kinds of piece: enforced, automatic, asked, on demand."
 ---
-An install writes a handful of files into your host's config folder and, where the host allows it, wires small programs that run at fixed moments: when a session starts, before a tool call, when a session ends. Everything below says what each piece does for you, when it runs, what it costs, and how to turn it off. The **Kind** column uses four words:
+An install writes a handful of files into your host's config folder and, where the host allows it, wires small programs that run at fixed moments: when a session starts, before a tool call, when a session ends. The page for your host says what each piece does for you, when it runs, what it costs, and how to turn it off. Its **Kind** column uses four words:
 
 - **enforced**: code runs before the action and can stop it. The model cannot argue past it.
 - **automatic**: runs by itself at a fixed moment, such as session start or session end.
@@ -13,64 +15,19 @@ An install writes a handful of files into your host's config folder and, where t
 
 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.
 
-<!--harness:claude-->
-*(Claude Code only)*
+## One page per host
 
-| Piece | What it does for you | Kind | Cost | Turn it off |
-|---|---|---|---|---|
-| `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` |
-| `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
-| `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 |
-| 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 |
-| git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --` | 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` |
-| 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 | enforced | ~14 ms per write | `geneseed exclude add <folder>` |
-| 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) |
-| `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 |
-| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
-| `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>` |
-| `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 |
-| 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 |
-
-<!--/harness-->
 <!--harness:opencode-->
 *(OpenCode only)*
 
-| Piece | What it does for you | Kind | Cost | Turn it off |
-|---|---|---|---|---|
-| `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` |
-| `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
-| `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 |
-| `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`, and before every commit and push when the **process** pack is on | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
-| 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` |
-| guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block |
-| 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 |
-| activity plugin | Writes one small file per session that the web console's Activity view shows | automatic | No tokens | `GENESEED_ACTIVITY=off` |
-| notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |
-| 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` |
-| workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
-| `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 |
-| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
-| `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>` |
-| `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 |
+- [On OpenCode](machine-opencode.md): the plugins and the `opencode.json` entries, piece by piece.
 
 <!--/harness-->
+<!--harness:claude,openclaude-->
+*(Claude Code and OpenClaude only)*
 
-### Where the files are
-
-**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.
-
-**Claude Code.** A global install writes to `~/.claude/`, and its hooks go into `~/.claude/settings.json`, next to any hooks of your own. A per-repo install uses the repo's `.claude/` folder, with the hooks in `.claude/settings.local.json`.
-
-**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 credentials and destructive git. The commit/push and memory questions become log lines.
-
-**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`.
+- [On Claude Code and OpenClaude](machine-claude.md): the hooks in `settings.json`, piece by piece.
 
-**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.
-
-### Taking it back out
-
-`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`, `wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
-
----
-
-**Next:** [A day with the harness](a-day.md)
+<!--/harness-->
+- [On Bob, or any AGENT.md tool](machine-bob.md): where the files go, and what is enforced there.
+- [Taking it back out](take-it-out.md): what `geneseed uninstall` removes, and what it keeps.

package/docs/understand/take-it-out.md

@@ -0,0 +1,13 @@
+---
+group: understand
+order: 6
+title: "Taking it back out"
+kind: "concept"
+section: "On your machine"
+description: "What geneseed uninstall removes, and what it keeps for you."
+---
+`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`, `wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
+
+---
+
+**Next:** [A day with the harness](a-day.md)