geneseed 3.10.0 → 3.11.0

package/docs/reference/troubleshooting.md

@@ -0,0 +1,350 @@
+---
+group: reference
+order: 4
+title: "Troubleshooting"
+kind: "concept"
+---
+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.
+
+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.
+
+```bash
+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.
+
+**Fix.** Remove the bare `Harness/` line from the parent `.gitignore`; the bundle's own `.gitignore` already scopes what to skip.
+
+**Confirm.** `git status` lists the bundle's files.

package/docs/understand/a-day.md

@@ -0,0 +1,77 @@
+---
+group: understand
+order: 3
+title: "A day with the harness"
+kind: "concept"
+---
+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.
+
+Start with one prompt on your first day:
+
+> *"Use the profile skill."*
+
+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.
+
+### 1. The agent tries to push
+
+You ask the agent to clean up a branch and it decides to force-push. A gate runs before the shell does, so the command waits for you. On Claude Code it looks like this (the prompt's layout depends on your version; the reason text is Geneseed's):
+
+```text
+● Bash(git push --force origin feature/login)
+  Geneseed (Deletion Is Deliberate) — a history-rewriting or discarding git act
+  needs confirmation bound to this specific command
+  Do you want to proceed?  Yes / No
+```
+
+An ordinary `git commit` or `git push` gets a milder question when the **process** pack is on: *"Geneseed (Consent Before Push) — every git commit/push needs explicit approval; to see the change first, use the explain-changes skill"*. If you answer no, the command does not run, however the model phrased its reasoning.
+
+Bob has no prompt, so the same force-push is refused outright:
+
+```text
+[geneseed] BLOCKED: Geneseed (Deletion Is Deliberate) — a history-rewriting or discarding git act needs confirmation bound to this specific command
+```
+
+On OpenCode the question comes from OpenCode's own permission prompt, which Geneseed configures in `opencode.json`. Every catch goes into a log, and `geneseed status` counts the catches by rule.
+
+### 2. You call a skill by name
+
+A **skill** is a written procedure the agent follows step by step. You call it in plain English:
+
+> *"Use the brainstorm skill on this feature request."*
+
+The agent loads the skill's full text only now. Until then it carried just the skill's name and one-line description. `brainstorm` turns a raw idea into a design you approve before any code is written. Skills chain together: *"Use brainstorm, then plan, for how to add rate limiting."*
+
+### 3. You hand work to a specialist
+
+An **agent** is a specialist with a narrow job and its own instructions. The main agent delegates to it:
+
+> *"Delegate to the reviewer agent on the staged diff."*
+
+The reviewer reads the change, runs the tests, and comes back with findings ordered correctness-first, each pointing at a `file:line`. It ends with a one-line verdict: ship, fix-then-ship, or block. The reviewer only reads; it does not edit your code.
+
+### 4. The session teaches the next one
+
+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`.
+
+A new file appears in the install's `memory/` folder:
+
+```markdown
+---
+name: integration-tests-need-docker
+description: the integration suite needs a running Docker daemon
+type: project
+---
+The integration tests start Postgres in a container; run `docker info` before the suite.
+```
+
+and one line is added to `memory/MEMORY.md`:
+
+```markdown
+- [integration-tests-need-docker](integration-tests-need-docker.md) — the integration suite needs a running Docker daemon
+```
+
+Next session, that index is in front of the agent before your first message. Memory stays on your machine. `geneseed memory list` shows every fact and `geneseed memory rm <name>` removes one.
+
+---
+
+**Next:** [Enforced vs. asked](enforced-vs-asked.md)

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

@@ -0,0 +1,64 @@
+---
+group: understand
+order: 4
+title: "Enforced vs. asked"
+kind: "concept"
+---
+Geneseed gives your agent two kinds of instruction, and it matters which kind you are relying on.
+
+- **Enforced.** A hook (Claude Code, Bob, OpenClaude) or a plugin (OpenCode) runs *before* the action, looks at the command or the file about to be written, and can stop it. The model cannot talk its way past it: the check is code, not a request.
+- **Asked.** Text in the root rules file (`CLAUDE.md`, `AGENT.md`, `AGENTS.md`). The model reads it every session and usually follows it. Nothing guarantees it.
+
+> **You already know this:** a failing CI check versus a line in `CONTRIBUTING.md`. Both say "do not merge untested code". Only one of them actually blocks the merge.
+
+Most of the harness is *asked*. A few rules, where one mistake is expensive and the bad action is easy to recognise, are also *enforced*.
+
+### What is enforced, per host
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+On Claude Code and OpenClaude the hooks never block silently. They make the host **ask you**, with the reason shown:
+
+- **Destructive git**: a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`. Wired in every build.
+- **Commit and push**: every `git commit` and `git push`, including chained one-liners and `git -C <path>`. This question belongs to the **process** pack. Build without it and the git gate stays wired. Only this question goes away, and destructive git is still caught.
+- **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.
+- **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.
+
+If a gate crashes, it asks instead of letting the call through. Other shell commands, `rm -rf` included, go through Claude Code's normal permission flow.
+
+**Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for two rules: credentials and destructive git. The commit/push and memory checks become a log line, and the call goes through. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
+
+<!--/harness-->
+<!--harness:opencode-->
+*(OpenCode only)*
+
+On OpenCode, two mechanisms enforce rules:
+
+- **OpenCode's own permission prompt**, which Geneseed configures in `opencode.json`. It asks you before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` and `checkout --`, and, when the **process** pack is on, before every commit and push.
+- **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through.
+
+The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: if your `opencode.json` already has a `git commit*` entry, a rebuild without the pack leaves that entry in place and reports it. Geneseed cannot tell its own entry from one you typed.
+
+<!--/harness-->
+
+**Protected wiki folders** are blocked only on OpenCode. On Claude Code, Bob and OpenClaude they are an instruction the model reads. A **plain bundle** installs no hooks or plugins, so everything in it is asked.
+
+Everything else, from "verify before you claim it works" to every practice in the doctrine packs, is asked on every host. In a folder you exclude with `geneseed exclude add <folder>`, the gates stand down too.
+
+### Why not enforce everything
+
+A gate sees one tool call: a command string, or a file path and its content. It cannot see whether the agent read the docs, checked its claim, or planned before acting. Most rules are about judgement, and no pattern can check judgement.
+
+The patterns that do exist are deliberately narrow. A gate that fired on every hash or lockfile would get allow-listed within a day and then protect nothing. A narrow gate that fires rarely stays switched on. Each gate also costs about 14 ms per tool call, on every call.
+
+### What the harness does not do
+
+- **It does not make the model smarter.** It gives the same model better instructions and a few guard rails.
+- **It does not check facts.** The rules tell the agent to verify before asserting. Nothing confirms that it did.
+- **It does not review code on its own.** The reviewer agent runs when you or the agent ask for it, not on every change.
+- **It is not a sandbox.** A destructive command that matches no pattern runs like any other. Your host's own permission settings still apply on top.
+
+---
+
+**Where next:** [Install it](../guides/install.md) · [The rules in detail](../concepts/rules.md) · [Glossary](../reference/glossary.md)

package/docs/understand/harness.md

@@ -0,0 +1,36 @@
+---
+group: understand
+order: 1
+title: "What a harness is"
+kind: "concept"
+---
+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.
+
+The usual fix is a `CLAUDE.md` or `AGENTS.md`: a page of instructions the tool loads at the start of each session. That helps, but it has two weaknesses. It is prose, so the model reads it and usually follows it, but nothing makes it. And you copy it into every repo, where each copy slowly drifts from the others.
+
+A **harness** is everything around the model that shapes how it works: the instructions it loads, the specialists it can hand work to, the routines it can follow, what it remembers between sessions, and the checks that run before it acts. Every Geneseed term is defined in the [glossary](../reference/glossary.md).
+
+> **You already know this:** git hooks, CI, and a team runbook, but for the agent. The runbook says how work is done. The hooks and CI stop the mistakes that matter before they land.
+
+### What Geneseed is
+
+Geneseed is a build that produces a harness. One source renders:
+
+- **the rules**: a short set of rules the agent always follows, plus practice packs you choose ([Rules](../concepts/rules.md));
+- **agents**: specialists such as a reviewer or a tester that the main agent can delegate to ([Agents](../concepts/agents.md));
+- **skills**: written procedures you call by name, such as `brainstorm` or `plan` ([Skills](../concepts/skills.md));
+- **a memory convention**: one fact per file, kept on your machine between sessions ([Memory](../concepts/memory.md)).
+
+It renders them for OpenCode, Claude Code, Bob, OpenClaude, or as a plain bundle for any tool that reads `AGENT.md`. The content is the same on every host. Only the wiring differs.
+
+Where the host lets it, Geneseed also installs **gates**: small programs that run before a tool call and stop a few things outright, such as a force-push or a credential written into a tracked file. Those rules do not depend on the model remembering them. [Enforced vs. asked](enforced-vs-asked.md) explains which rules a gate stops and which ones the model is only told about.
+
+### Install once, use everywhere
+
+You install it once, at the user level, and every repo you open inherits it. There is nothing to copy into each project. When the source changes, you rebuild and every install picks up the change, so no copy drifts.
+
+The name comes from Warhammer 40,000, where gene-seed is implanted once and the rest grows from it. That is the only lore you need. The default theme is neutral.
+
+---
+
+**Next:** [What lands on your machine](on-your-machine.md)

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

@@ -0,0 +1,76 @@
+---
+group: understand
+order: 2
+title: "What lands on your machine"
+kind: "map"
+---
+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:
+
+- **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.
+- **asked**: text the model reads every session. It usually follows it, but nothing makes it.
+- **on demand**: loads only when you or the agent call it by name.
+
+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)*
+
+| 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 |
+
+<!--/harness-->
+
+### 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`.
+
+**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)

package/docs/web-ui.md

@@ -4,7 +4,7 @@
 
 **Every view in the local browser console, what it shows, and how to drive it.**
 
-[← README](../README.md) · [Setup](../SETUP.md) · [What's shipped](../SHIPPED.md)
+[← README](../README.md) · [Docs](README.md) · [What's shipped](../SHIPPED.md)
 
 </div>
 

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.10.0"
+  "version": "3.11.0"
 }

package/js/README.md

@@ -118,6 +118,7 @@ into files users have committed, so change the test that states it in the same c
 | `text.mjs` | String primitives: `codePointLength`, `WHITESPACE`, `parseIntStrict`, `percentDecode` |
 | `udiff.mjs` | `geneseed diff`'s own difflib clone — the alignment IS the printed hunks — plus `splitLines` |
 | `proc.mjs` | One constant: the `windowsHide` flag every spawn in `js/` must reuse |
+| `node-floor.mjs` | The first import of all three binaries: below Node 22.3, one sentence on stderr and exit 1 (0 in the hook) instead of a stack trace |
 
 **Before editing:** parse with `parseJson`, never `JSON.parse` — the latter collapses int `1` and
 float `1.0` into one double, and that value gets written into a user's file. Do not swap in a diff
@@ -168,7 +169,7 @@ the deployed harness as JSON.
 | `actions.mjs` | The mutating endpoints — rules, profile, memory, MCP, excludes — plus install/deploy argv |
 | `daemon.mjs` | Detached web start/stop/status/restart, the `.geneseed-web.json` record, and `openUrl` |
 | `jobs.mjs` | `JobManager` and the action→argv table. The only module here that spawns job children |
-| `docs.mjs` | The Docs tab: the `docs/web/` page registry, `?harness=` filtering, the five page kinds |
+| `docs.mjs` | The Docs tab: the `docs/<folder>/` page registry, `?harness=` filtering, link rewriting, the six page kinds |
 | `activity.mjs` | The `activity/` session files: pid-liveness prune, list, detail, and the on/off flag |
 
 **Before editing:** `makeHandler(state, jm, token, dist, holder)`'s arity is load-bearing — three
@@ -190,6 +191,6 @@ and inline lists are held against a surface list written out in
 | a web endpoint | GET → `js/web/api.mjs`; POST → `js/web/actions.mjs` | declare it in `js/web/routes.mjs`; the partition test probes the real handler |
 | a CLI verb | `js/cli-table.json` — the table IS the parser | the `VERBS` row in `bin/geneseed-cli.mjs`, the row count in `cli_table.test.mjs`, `NATIVE` in **two** test files |
 | a hook verb | `js/hosts/hooks.mjs` | `claudeHookGroups` in `settings.mjs`, `VERBS` in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
-| a console doc page | `docs/web/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
+| a console doc page | `docs/<understand|guides|concepts|reference>/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
 | an OpenCode plugin | `adapters/opencode/plugins/geneseed-<name>.js` | `docs/extending.md` §4a — the `geneseed-` prefix is mechanically load-bearing |
 | to change a `js/lib/` primitive | `tests/fixtures/pure_probe.mjs` **first** | the docblock says which Node default it deliberately departs from — change that sentence too, or the next reader restores the default |