geneseed 3.9.0 → 3.11.0

package/docs/guides/run-anywhere.md

@@ -0,0 +1,45 @@
+---
+group: guides
+order: 9
+title: "Run geneseed from anywhere"
+kind: "concept"
+---
+**Installed from npm? You have nothing to do.** `npm install -g geneseed` already puts `geneseed`, `geneseed-build` and `geneseed-hook` on your `PATH`.
+
+From a clone, you call the launcher inside the clone: `./geneseed` (Windows: `.\geneseed.cmd`). To type plain `geneseed` from any folder, link it.
+
+## macOS and Linux
+
+```
+./geneseed link                    # a launcher in ~/.local/bin, no sudo
+./geneseed link /usr/local/bin     # or another bin folder (may ask for sudo)
+```
+
+`link` writes a small shell launcher that runs this clone by its absolute path. It also tells you whether the target folder is on your `PATH`, and if it is not, the one line to add to your shell profile. Then:
+
+```
+geneseed            # the web console (or the command list), from any folder
+geneseed build      # and every other command
+```
+
+If you prefer a shell function, add one to your `~/.zshrc` or `~/.bashrc` from inside the clone instead:
+
+```
+echo 'geneseed() { "'"$PWD"'/geneseed" "$@"; }' >> ~/.zshrc
+```
+
+## Windows
+
+```powershell
+.\geneseed.cmd link
+```
+
+This writes a `geneseed.cmd` launcher into `%LOCALAPPDATA%\Geneseed\bin` and adds that folder to your user `PATH`. You need neither admin rights nor symlinks. Open a new terminal, then call `geneseed` from any folder.
+
+## Undo it
+
+```
+geneseed unlink
+```
+
+`unlink` removes the launchers that `link` wrote. It leaves alone any `geneseed` it did not write itself. In the web console, **Settings** has the same link and unlink controls.

package/docs/guides/uninstall.md

@@ -0,0 +1,51 @@
+---
+group: guides
+order: 5
+title: "Uninstall"
+kind: "concept"
+---
+`geneseed uninstall` removes one install at a time. It deletes only what Geneseed wrote and keeps anything you would not be able to rebuild.
+
+## Remove an install
+
+```
+geneseed uninstall                          # the project install in this folder, else the OpenCode global one
+geneseed uninstall --target /path/to/repo   # a project install
+geneseed uninstall --target ~/.claude       # a global install: pass its config directory
+```
+
+Without `--target`, the command picks the project install in the current folder if there is one, and the OpenCode global install otherwise. It prints what it will remove and asks before going on. Pass `--yes` to skip the question. In a shell without an interactive terminal, `--yes` is required: without it, the command refuses and exits 1.
+
+To see where each install lives, run `geneseed status`. The web console's **Harnesses** page can also uninstall.
+
+## What it removes
+
+Each install keeps a manifest, a list of the files Geneseed wrote. **Uninstall deletes exactly those files and nothing else**, then removes any folders they leave empty. A file of yours that sits in the same folder stays.
+
+- **OpenCode global:** `AGENT.md`, `agents/`, `skills/`, `plugins/`, the marker files, and the `instructions` entry in `opencode.json`.
+- **OpenCode per repo:** `AGENT.md`, `.opencode/`, `laws/`, `agents/`, `skills/`, and the `instructions` entry in `opencode.json`.
+- **Claude Code, Bob, OpenClaude:** `agents/`, `skills/`, the marker files, Geneseed's managed block in the instructions file (`CLAUDE.md` or `AGENTS.md`), and Geneseed's own hooks and exclusions in `settings.json`. Your own settings keys and hooks stay.
+
+It also removes the install's row from the registry of installs. Start a new session in your tool afterwards so it stops loading the old files.
+
+## What it keeps
+
+- **`memory/` and `notebook/`.** These are never deleted. `--archive-memory` moves both aside, into sibling `archived-memory/<timestamp>/` and `archived-notebook/<timestamp>/` folders, instead of leaving them in place. Even then they are moved, not deleted.
+- **`wiki.jsonc`**, **`context.json`** and the **`improvements/`** folder. None of these are in the manifest.
+- **Other installs.** Removing the global install does not touch any project install. Uninstall lists the project installs that remain, each with the command that removes it. If a repo carries installs for several hosts, uninstall removes one and tells you to run it again for the next.
+
+## The hook shim
+
+Claude Code, Bob and OpenClaude hooks all run through one shared file, the hook shim at `~/.geneseed/bin/geneseed-hook` (or under `$GENESEED_HOME`). Uninstalling an install removes that install's hooks but leaves the shim, because other installs may still use it. Once no install is left, you can delete the `~/.geneseed` folder yourself.
+
+## Remove the `geneseed` command
+
+The commands themselves are removed separately:
+
+```
+npm uninstall -g geneseed     # installed from npm
+```
+
+From a clone, `geneseed unlink` removes the launcher that `geneseed link` put on your `PATH` (see [Run geneseed from anywhere](run-anywhere.md)). Then delete the clone folder.
+
+If you set the web console to start at login, delete that login item too. It is a file you created, and Geneseed never removes it (see [Start the web console at login](autostart.md)).

package/docs/guides/upgrade.md

@@ -0,0 +1,65 @@
+---
+group: guides
+order: 4
+title: "Upgrade"
+kind: "concept"
+---
+Upgrading happens in two steps: get the new Geneseed, then rebuild every install from it. Editing or updating Geneseed changes nothing on your machine until something rebuilds. The route depends on how you installed.
+
+## Installed from npm
+
+```
+npm install -g geneseed@latest     # get the new version
+geneseed rebuild-all               # rebuild every install with its own settings
+```
+
+`rebuild-all` re-renders each registered install in place, keeping its own theme, host, footprint, posture, mode, packs and rule exclusions. It is best-effort: when one install fails, it reports the failure and carries on with the rest.
+
+`upgrade`, `update`, `sync-self` and `bootstrap` are the clone route. Run from an npm install, they stop before touching anything and point you to `npm install -g geneseed@latest` instead.
+
+## Installed from a clone
+
+```
+geneseed upgrade              # pull, check, rebuild; keeps theme and install mode
+geneseed upgrade imperial     # the same, switching the theme
+```
+
+`upgrade` does three things:
+
+1. It runs a fast-forward-only `git pull` from the clone's own remote, on the current branch.
+2. It runs a blocking `doctor` pass over the result, and rolls back if it fails.
+3. It rebuilds the bundle and every install in place.
+
+A dirty working tree, or a folder that is not a git clone, is reported rather than force-updated. `update` and `sync-self` are aliases of `upgrade`. `bootstrap` does the same and then opens the setup wizard (`--no-setup` skips the wizard).
+
+## What an upgrade keeps
+
+A rebuild only replaces files the install's manifest says Geneseed owns. It leaves these alone:
+
+- the `memory/` and `notebook/` stores;
+- your `context.json` and `wiki.jsonc`;
+- the marker files that record each install's choices (theme, footprint, packs, excluded rules), which every rebuild reads back;
+- your own agents, skills, plugins and hooks, and any `opencode.json` or `settings.json` keys you wrote yourself;
+- the `improvements/` folder (see below).
+
+## Local edits, and the improvements file
+
+The agent can refine its own deployed agent and skill files as it works, and so can you. A rebuild would overwrite those edits, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
+
+To see the drift yourself, or to export it on demand:
+
+```
+geneseed diff                          # file-level summary of what diverged
+geneseed diff --full                   # with line-level diffs
+geneseed diff --out improvements.md    # write the improvements file
+```
+
+`diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
+
+## Moving from a clone to npm
+
+If you installed from a clone and now want the npm package, `geneseed migrate` moves every install across in one pass. See [Migrate to npm](migrate.md).
+
+---
+
+**Next:** [Verify it works](verify.md) · [Uninstall](uninstall.md)

package/docs/guides/verify.md

@@ -0,0 +1,65 @@
+---
+group: guides
+order: 3
+title: "Verify it works"
+kind: "concept"
+---
+Four checks, from quickest to most thorough. The first one alone tells you whether the harness loaded.
+
+## 1. The readiness sigil
+
+Open your agent in any repo and say anything. The first reply opens with the readiness line: `✅` for the neutral theme, `🧬` for imperial, or your theme's own sigil.
+
+If the sigil is missing, the tool is not loading `AGENT.md`. Check that your tool's instructions setting points at it. On OpenCode, that is the `instructions` key in `opencode.json`.
+
+## 2. `geneseed doctor`
+
+```
+geneseed doctor
+```
+
+`npx geneseed doctor` runs the same check without installing anything. Doctor renders the harness and checks the result for unresolved theme tokens, dead links, missing files and drift from the source. It checks the theme you installed, unless you pass `--theme NAME` for another theme or `--all` for every theme. A clean run ends with a line like this:
+
+```
+[doctor] ok — 1 theme(s) clean: no unresolved tokens, no dead …
+```
+
+Every failure comes with a hint for fixing it. Doctor also reports a stale hook shim, the file every Claude Code, Bob and OpenClaude hook goes through. If that shim points at a folder that no longer exists, the hooks stop silently. One `geneseed build` (or `geneseed rebuild-all`) rewrites it.
+
+## 3. `geneseed status`
+
+```
+geneseed status
+```
+
+This prints a dashboard with your theme, the components installed, the memory store, the version, the active doctrine packs, and one row per install with its host, scope, theme, footprint, posture, mode and packs. A healthy install reads `active`. If the bottom of the dashboard says the installed build differs from the current source, run `geneseed rebuild-all` (see [Upgrade](upgrade.md)).
+
+The `gates` row counts how often a gate asked or blocked, per rule. It shows the hooks are actually firing. `geneseed status --json` prints the same data as JSON, including the exact `geneseed build` command that rebuilds each install.
+
+## 4. Context delivery
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+Start a session with `GENESEED_DEBUG=1` set. The context plugin then logs what it discovered and injected, and you should see the repo's `README.md` and its docs listed. To check memory, do a little work and end the session. After a quiet period, the learn plugin logs `wrote N memory file(s)` or the reason it skipped. Total silence means the plugin did not load.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+At session start, the context hook adds the repo's docs to the conversation. Ask the agent what project context it received. It should name your `README.md` and list your `docs/`.
+<!--/harness-->
+
+## Dry-run a build before you write it
+
+`geneseed validate` takes the same flags as `geneseed build`. It renders into a throwaway sandbox and runs every doctor check against the result. Nothing is written under the real `--out` or `--root`: no marker files, no settings merge, no registry record.
+
+```
+geneseed validate --theme imperial --emit opencode --out /path/to/repo/Harness
+```
+
+It prints how many files each layer would get (`-v` lists the paths), exits `0` when the build is clean, and exits non-zero on any problem. It is useful in CI, or before you point a real build at a repo you do not want to touch yet. The generator itself (`geneseed-build`) has no dry-run flag. `validate` is a separate command because it runs doctor, and the generator is not allowed to start processes.
+
+---
+
+Something wrong? See [Troubleshooting](../reference/troubleshooting.md).

package/docs/guides/wiki.md

@@ -0,0 +1,69 @@
+---
+group: guides
+order: 7
+title: "Connect your wiki"
+kind: "concept"
+---
+If you keep a personal knowledge base on this machine, such as an Obsidian vault or any folder of interlinked markdown, you can declare it once. The agent then reads from it and writes to it while following your own structure. This is optional. Until you declare a wiki, the feature stays off.
+
+> **You already know this:** a wiki is a shared drive with a README that says "read me before you add anything". The agent reads that note first, files new notes where your structure says they belong, and keeps out of the folders you marked off-limits.
+
+## Wiki, memory, notebook: three different stores
+
+- **[Memory](../concepts/memory.md)**: small facts the agent learns, one per file, private to this machine.
+- **[Notebook](../concepts/notebook.md)**: the agent's own scratch space.
+- **Wiki**: durable knowledge that spans projects, which **you** own and curate.
+
+When a memory fact or a notebook note hardens into knowledge worth keeping across projects, the agent promotes it into the wiki, so the truth lives in one place.
+
+## Declare it in `wiki.jsonc`
+
+The build writes a `wiki.jsonc` stub beside `AGENT.md` (for the OpenCode global install, `~/.config/opencode/wiki.jsonc`) and never overwrites it. The file is JSONC, so comments and trailing commas are fine. The stub contains this example, commented out:
+
+```json
+{
+  "wikis": [{
+    "name": "Brain",
+    "path": "/home/me/Documents/Brain",
+    "description": "my machine-wide knowledge base",
+    "entries": [
+      { "path": "ARCHITECTURE.md", "load": "eager", "description": "the root map" },
+      { "path": ".", "load": "lazy" }
+    ],
+    "conventions": "STYLE.md",
+    "inbox": "Inbox/",
+    "protected": ["Journal/"]
+  }]
+}
+```
+
+- **`path`**: the vault root, absolute. On Windows, use forward slashes (`C:/Users/me/Brain`).
+- **`entries`**: notes the agent sees each session, with the same `eager` and `lazy` meaning as [project context](project-context.md). An eager note is loaded in full. A lazy note is only listed, and the agent reads it on demand. An entry can be one note or a folder (`"."` is the whole vault; dot-folders like `.obsidian` are skipped). A file entry overrides its folder's mode, and `"load": "exclude"` removes a note or folder from the list. The example above is the usual shape: the root index eager, everything else lazy.
+- **`conventions`**: the note the agent must read before its first write, so new notes match your naming, frontmatter and folder rules.
+- **`inbox`**: where the agent drops a note it cannot confidently file, instead of guessing.
+- **`protected`**: folders the agent must never write to.
+
+You can declare several wikis. An empty `wikis` list keeps the feature off. The file may hold private paths. It is specific to this machine and must never be committed. A project install's own `.gitignore` already lists it.
+
+Geneseed looks for the file in this order: `$GENESEED_WIKI`, then `$GENESEED_HARNESS/wiki.jsonc`, then beside the installed `AGENT.md`. A `wiki.json` left by an older install is still read at each of those places.
+
+## How each host honours it
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+The context plugin loads your eager entries and lists your lazy ones at session start. A big vault's lazy list stops at 200 notes and shows a count of the rest (`GENESEED_WIKI_LAZY_LIMIT` changes the limit). The guard plugin **blocks** any write into a `protected` folder at the tool boundary, before the write happens. `GENESEED_GUARD=warn` turns the block into a warning, and `GENESEED_GUARD=off` disables the guard.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+No hook reads the wiki. The instructions in your harness tell the agent to read `wiki.jsonc` at session start and to honour it, including the `protected` folders. That is an instruction the model follows, not a block. Nothing stops a write at the tool boundary. The same applies to Bob, OpenClaude and plain `AGENT.md` tools. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
+<!--/harness-->
+
+## What the agent does with it
+
+The `wiki` skill drives the procedure.
+
+- **Reading.** The agent starts from your entry notes and moves outward by your own structure, following `[[wikilinks]]` and index notes, instead of reading the whole vault. It treats what it reads as true when written, and checks it against the live system before building on it.
+- **Writing.** Durable, reusable facts that span projects go back into the wiki as proper notes: wikilinked, in your house style, filed where your structure says (or in the inbox). Session details stay in memory, and secrets are never written anywhere. The agent never restructures the vault. Moving and renaming notes is your call.

package/docs/guides/worktree.md

@@ -0,0 +1,47 @@
+---
+group: guides
+order: 12
+title: "Add git-worktree isolation"
+kind: "concept"
+harness: "opencode"
+---
+This is a third-party, optional OpenCode plugin. Geneseed does not ship it or install it.
+
+[`opencode-worktree`](https://github.com/kdcokenny/opencode-worktree) gives the agent two tools:
+
+- `worktree_create(branch, baseBranch?)` creates an isolated git worktree under `~/.local/share/opencode/worktree/<project-id>/<branch>/` and opens a terminal with OpenCode already running in it.
+- `worktree_delete(reason)` commits and cleans up the worktree.
+
+It suits parallel work when you want separate *files* on disk, not just separate sessions. It coexists with Geneseed's plugins: it registers two tools and hooks no event they use, so nothing fires twice.
+
+It cannot ride Geneseed's install. Geneseed's plugins are single dependency-free files. This one is multi-file TypeScript with npm dependencies and Bun-only APIs, so it installs on its own track.
+
+## Install
+
+1. **Install [OCX](https://github.com/kdcokenny/ocx)**, the package manager that distributes the plugin, if you do not have it.
+2. **Add the plugin:**
+   ```bash
+   ocx add kdco/worktree --from https://registry.kdco.dev
+   ```
+   OCX manages the plugin's dependencies and updates. You do not need a separate Bun install, because OpenCode already runs on Bun.
+3. **Configure it.** On first use the plugin creates `.opencode/worktree.jsonc`. Fill in what each new worktree should inherit and run. For a Node repo, for example:
+   ```jsonc
+   {
+     "sync": {
+       "copyFiles": [".env", ".env.local"],   // copied from the main worktree
+       "symlinkDirs": ["node_modules"],        // symlinked, not duplicated
+       "exclude": []
+     },
+     "hooks": {
+       "postCreate": ["pnpm install"],         // after the worktree is created
+       "preDelete": []                          // before it is removed
+     }
+   }
+   ```
+4. **Optional: a terminal multiplexer.** The plugin detects your terminal on macOS, Linux and Windows. It prefers `tmux` when you are already inside it, and [`cmux`](https://www.cmux.dev/) for agent workflows. Neither is required. Without them, it uses your OS default terminal.
+
+**Without OCX**, you can copy the plugin's `src/` into `.opencode/plugin/` and install `jsonc-parser` yourself. You then lose dependency management and automatic updates, and you have to re-copy the plugin to upgrade it.
+
+## Consent
+
+`worktree_delete` **commits before it removes the worktree.** The harness's *Consent Before Push* rule (when the `process` pack is built in) asks before a *shell* `git commit` through `opencode.json` permissions. This plugin commits through its own tool, so that gate never sees the commit. Before you call delete, review what it will commit, or keep the worktree and commit yourself.

package/docs/reference/about.md

@@ -0,0 +1,7 @@
+---
+group: reference
+order: 6
+title: "About — version, license, links"
+kind: "about"
+---
+The console fills this page from your install: the version, the deployed theme and host, and where updates come from. Geneseed is MIT-licensed; the source is at [github.com/Arylmera/Geneseed](https://github.com/Arylmera/Geneseed).

package/docs/reference/cli.md

@@ -0,0 +1,7 @@
+---
+group: reference
+order: 1
+title: "CLI — every subcommand"
+kind: "cli"
+---
+The console renders this page from `js/cli-table.json`, the CLI's own description of itself, so it is always in step with the installed version. Outside the console, `geneseed --help` lists every command and `geneseed <command> --help` describes one.

package/docs/reference/environment.md

@@ -0,0 +1,99 @@
+---
+group: reference
+order: 2
+title: "Environment variables"
+kind: "concept"
+---
+Every environment variable Geneseed reads, grouped by what it changes. None is required: an install works with all of them unset. Set one in your shell profile (or your tool's environment) when you need to move a default.
+
+"Plugin" means one of the OpenCode plugins — see [OpenCode plugins](opencode-plugins.md). "Hook" means `geneseed-hook`, the small binary your tool's settings call on Claude Code, Bob and OpenClaude (see the [glossary](glossary.md)).
+
+### Where things install
+
+Where Geneseed writes an install, and what an upgrade re-renders.
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_HOME` | build / hooks | Directory holding the hook shim `bin/geneseed-hook` (default `~/.geneseed`). Change it, then rebuild, so the emitted hooks point at the new location. |
+| `GENESEED_NO_SHIM_CHECK` | CLI | `1` silences the warning every `geneseed` command prints when the hook shim points at a path that no longer exists. For scripted callers; the `status` gates row still says `DEAD`. |
+| `OPENCODE_CONFIG_DIR` | OpenCode emits, `diff`, plugins | OpenCode's config dir — where the global install is written. |
+| `XDG_CONFIG_HOME` | OpenCode emits, plugins | Used when `OPENCODE_CONFIG_DIR` is unset: the install goes to `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). |
+| `BOB_CONFIG_DIR` | Bob emits | Bob's config dir (default `~/.bob`). |
+| `OPENCLAUDE_CONFIG_DIR` | OpenClaude emits | OpenClaude's own config-dir variable (default `~/.openclaude`); also moves `.openclaude.json`. |
+| `GENESEED_EMIT` | `geneseed upgrade` | Which emit target to re-render (e.g. `opencode-global`). Unset, it is read from the install's `.geneseed-emit` marker, else the plain bundle. |
+| `GENESEED_OUT` | `geneseed upgrade` | Bundle location for a plain-bundle install (default `Harness/` beside the checkout). |
+| `GENESEED_ROOT` | `geneseed upgrade` | Project root for that bundle (default: the bundle's parent). |
+| `GENESEED_PRIMARY` | `geneseed build` | `1` also emits the primary orchestrator agent (OpenCode). |
+| `GENESEED_COMMANDS` | `geneseed build` | `1` also emits the `/slash` command layer (OpenCode). |
+
+### Context injection
+
+What gets loaded into the agent's context at session start — your project's docs and your machine wiki. See [Project context](../guides/project-context.md).
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_CONTEXT` | context plugin, context hook | Explicit `context.json` manifest path; overrides discovery. |
+| `GENESEED_ROOT` | context hook | Repo root to discover docs from (default: the current directory). |
+| `GENESEED_WIKI` | context + guard plugins, context hook, web console | Explicit `wiki.jsonc` path (default `$GENESEED_HARNESS/wiki.jsonc`, else beside the install). |
+| `GENESEED_STACK_GLOBAL` | context hook, Claude Code project build | `1` lets a global and a project install of the same host both inject. By default the project install makes the global one stand down. Rebuild the project install after changing it. |
+| `GENESEED_CONTEXT_INJECT` | context plugin | `off` disables injection; the agent is only *asked* to read the docs. |
+| `GENESEED_CONTEXT_VISIBLE` | context plugin | `1` shows the visible `PROJECT CONTEXT` block instead of the invisible per-request delivery. |
+| `GENESEED_CONTEXT_TRANSFORM` | context plugin | Legacy. `0`/`off` = same as `GENESEED_CONTEXT_VISIBLE=1`; `1` matches the default. |
+| `GENESEED_EAGER_FILE_KB` / `GENESEED_EAGER_TOTAL_KB` | context plugin | Per-file / total budget for docs injected in full (default 16 / 48). An oversized file is listed instead, never truncated. |
+| `GENESEED_LAZY_HEADINGS` | context plugin | Cap on headings read for listed docs per session (default 64). |
+| `GENESEED_WIKI_LAZY_LIMIT` | context plugin | Cap on wiki notes listed per wiki per session (default 200; beyond it the listing ends with a count). |
+
+### Memory and learn
+
+Where distilled memories land at session end, and which model distils them. See [Memory](../concepts/memory.md).
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `wiki.jsonc` is looked up). Optional — the plugin finds the in-config store by itself; set it to pin the location. |
+| `GENESEED_MEMORY` | learn plugin, CLI | Explicit memory dir; wins over `GENESEED_HARNESS`. |
+| `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
+| `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, the hook prints the prompt instead of distilling. |
+| `GENESEED_LEARN_DEBOUNCE_MS` | learn plugin | Quiet period before distilling, in ms (default 60000). |
+
+### Guard
+
+The OpenCode safety guard. On Claude Code, Bob and OpenClaude the same gates are hooks and have no environment switch.
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_GUARD` | guard plugin | `warn` downgrades every block to a logged warning; `off` disables the guard. |
+
+### Notifications
+
+The desktop ping when a long turn finishes (OpenCode).
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_NOTIFY` | notify plugin | `off` disables notifications. |
+| `GENESEED_NOTIFY_MIN_SECONDS` | notify plugin | Minimum turn length before notifying (default 30; `0` = every turn). |
+| `GENESEED_NOTIFY_TITLE` | notify plugin | Notification title (default `Geneseed`). |
+
+### Other OpenCode plugins
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_PONYTAIL` | ponytail plugin | Starting minimal-code level: `lite` \| `full` \| `ultra` \| `off` (default `off`; switch live with `/ponytail <level>`). |
+| `GENESEED_WORKFLOWS_DIR` | workflow plugin | Directory the `workflow` tool loads saved scripts from. |
+| `GENESEED_ACTIVITY` | activity plugin | `off` stops writing the live-activity files the web console reads. |
+| `GENESEED_DEBUG` | every plugin but guard and learn (which always log) | `1` logs what each plugin decided to stderr. |
+| `OPENCODE_DISABLE_LSP_DOWNLOAD` | OpenCode itself | `true` stops OpenCode downloading language servers — for air-gapped machines; install each server yourself. |
+
+### Web console and CLI
+
+How the `geneseed` command behaves and prints.
+
+| Variable | Read by | Effect |
+| --- | --- | --- |
+| `GENESEED_NO_WEB` | `geneseed` (bare) | `1` stops bare `geneseed` opening the web console; it falls back to the terminal menu. |
+| `GENESEED_NODE` | `./geneseed`, `geneseed.cmd`, `install` scripts | Node interpreter to run (default `node` on PATH). |
+| `GENESEED_TUI_ASCII` | CLI output | Pure-ASCII output: no box-drawing or emoji. |
+| `GENESEED_TUI_PLAIN` | CLI output | Drop emoji and animation. |
+| `GENESEED_NO_ANIM` | install animation | Disable the themed install animation. |
+| `NO_COLOR` | `geneseed status` | Any value disables colour. |
+| `GENESEED_LOG` | `geneseed upgrade` | Install/upgrade log path (default `~/.geneseed-install.log`). |
+| `GENESEED_NET_TIMEOUT` | `geneseed upgrade` | Seconds before the network fetch gives up (default 120, minimum 30). |

package/docs/reference/glossary.md

@@ -0,0 +1,33 @@
+---
+group: reference
+order: 3
+title: "Glossary"
+kind: "glossary"
+---
+Every word Geneseed uses that you would not find in a general programming glossary. The console shows this table in your installed theme's voice beside the neutral words; on GitHub you read the neutral ones.
+
+| Term | Theme key | Meaning | In dev terms |
+|---|---|---|---|
+| Harness | — | everything Geneseed installs around the model: the rules it loads, the gates that run before its actions, the workflows it can call | git hooks + CI + a runbook, for an agent |
+| Hook | — | a command your tool runs before or after an agent action; Geneseed's hooks gate risky actions and load context | a git hook, fired on every tool call |
+| Ethos (Ontology) | ONTOLOGY | the always-on worldview under the rules — telos, evidence, decisions, conduct; it holds the Pact | the team's engineering principles |
+| Rule (Law) | LAW | one of the nine always-on invariants: what is never done | a lint rule set to error |
+| Rules (Laws) | LAWS | the body of always-on invariants | the error-level rule set |
+| Doctrine | DOCTRINE | one practice rule, cited `<pack> <n>` — how work is done here | a team convention in CONTRIBUTING.md |
+| Doctrines | DOCTRINES | the practice packs, chosen at build time; inactive packs still ship in the bundle | opt-in lint presets |
+| Agent | AGENT | a capability specialist | a colleague you hand a ticket to |
+| Agents | AGENTS | the roster of specialists | the team |
+| Skill | SKILL | a repeatable workflow | a runbook |
+| Skills | SKILLS | the catalogue of workflows | the runbook folder |
+| Memory | MEMORY | durable, one-fact-per-file knowledge | a team wiki the agent writes |
+| Notebook | NOTEBOOK | the agent's sovereign space | the agent's scratch branch |
+| Wiki | WIKI | the machine-wide knowledge base | your personal notes, shared with the agent |
+| Pact | PACT | the two-way collaboration contract, stated in Telos, the first Ethos section | a working agreement |
+| Posture | — | the relationship register the agent works in (peer, mentor, expert, assistant, artisan) | pairing style |
+| Mode | — | how work gets executed — direct (the agent works every task itself) or foreman (substantial tasks spawn an isolated pipeline) | solo vs. delegating to a sub-team |
+| Footprint | — | how much of the Rules loads inline each turn (full vs lean) | eager vs. lazy loading |
+| Profile | — | who you are — seeded once, colours but never binds | your onboarding notes |
+| Memory force | — | a memory's binding strength (constraint, choice, conviction, tempered) | MUST / SHOULD / MAY |
+| Tagline | TAGLINE | the one-line essence of the theme | — |
+| Loaded sigil | LOADED_SIGIL | what the agent emits when ready | a health-check line |
+| Benediction | BENEDICTION | the closing line of an install | — |

package/docs/reference/opencode-plugins.md

@@ -0,0 +1,131 @@
+---
+group: reference
+order: 5
+title: "OpenCode plugins"
+kind: "concept"
+---
+On OpenCode, Geneseed's automation runs as {N_PLUGINS} plugins: small JavaScript files OpenCode loads from its `plugins/` directory at startup. They are what turns a rule from *asked* into *enforced* — the context load, the safety gates, memory distillation. On Claude Code, Bob and OpenClaude the same jobs are done by hooks instead (see [Hooks](../concepts/hooks.md)).
+
+> **You already know this:** a plugin is a git hook for your agent — code that runs on an event (session start, before a tool call, session idle), not text the model may or may not follow.
+
+Every plugin installs in the same step as the rest of the harness: `geneseed setup`, or `geneseed build --emit opencode-global` (global, into `~/.config/opencode/plugins/`) / `--emit opencode` (per-repo, into `.opencode/plugins/`). Installing by hand is covered in [Install](../guides/install.md). Keep **one** copy of each: OpenCode loads two local copies of the same plugin twice.
+
+Every plugin swallows its own errors — none can block or crash a session. Each variable below is also listed in [Environment variables](environment.md).
+
+## geneseed-context
+
+**What it does.** Puts your project's documentation (and your machine wiki) into the agent's context before your first turn, so the agent never has to be trusted to read it. It needs **no per-repo file**: it discovers docs by convention.
+
+- **Injected in full (eager):** root `README.md`, `CONTRIBUTING.md`, `.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.)
+- **Listed (lazy, path + first heading, read on demand):** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/`, and `packages/*/README.md` / `apps/*/README.md` in a monorepo. `node_modules`, `.git`, `dist`, `build`, `vendor` and similar are never scanned.
+- **Machine wiki:** the wikis declared in `wiki.jsonc` ride in the same block, on the same budgets. See [Wiki](../guides/wiki.md).
+- **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).
+
+**When it runs.** On every request: the context rides invisibly in the request's message list, so it also survives compaction. If your OpenCode build lacks that (experimental) hook, the plugin notices and falls back to one visible message at session start, re-pushed when the session compacts.
+
+**What you see.** Normally nothing — the context is there, but not shown. With the visible fallback, a `PROJECT CONTEXT` block at the top of the session.
+
+**Switches.**
+- `GENESEED_CONTEXT_INJECT=off` — no injection; the agent is only *asked* to read the docs.
+- `GENESEED_CONTEXT_VISIBLE=1` — force the visible block (legacy `GENESEED_CONTEXT_TRANSFORM=0` does the same).
+- `GENESEED_EAGER_FILE_KB` / `GENESEED_EAGER_TOTAL_KB` (default 16 / 48), `GENESEED_LAZY_HEADINGS` (64), `GENESEED_WIKI_LAZY_LIMIT` (200) — budgets.
+- `GENESEED_WIKI` — explicit `wiki.jsonc` path.
+- `GENESEED_DEBUG=1` — log what it discovered and injected to stderr. Silence with this set means the plugin did not load.
+
+## geneseed-guard
+
+**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.
+
+- **Blocks** writes to private-key and credential files (*Sealed Secrets*), catastrophic shell commands such as deleting the filesystem root (*Deletion Is Deliberate*), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `wiki.jsonc`.
+- **Warns** (logged, allowed) on `.env` writes and force-push.
+- **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.
+
+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.
+
+**When it runs.** Before every tool call (`tool.execute.before`).
+
+**What you see.** A refused tool call: `[geneseed-guard] blocked: <reason> — set GENESEED_GUARD=off to allow`. Warnings go to stderr.
+
+**Switches.**
+- `GENESEED_GUARD=warn` — log every block, allow the call.
+- `GENESEED_GUARD=off` — disable the guard.
+
+## geneseed-learn
+
+**What it does.** Distils durable memories from the conversation into the install's `memory/` directory and keeps `MEMORY.md` up to date, de-duplicating against what is already stored. 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).
+
+**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.
+
+**What you see.** On stderr: `[geneseed-learn] wrote N memory file(s): …`, or `skipped: <reason>`. Total silence means it did not load.
+
+**Where it writes** — the first that resolves:
+1. `GENESEED_MEMORY` — an explicit memory dir;
+2. `$GENESEED_HARNESS/memory` (`/anamnesis` for the imperial theme);
+3. the `memory/` beside the plugin's own install (the global install's store);
+4. `./memory` or `./Harness/memory`, when the bundle lives in the project.
+
+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.
+
+**Switches.**
+- `GENESEED_MODEL=provider/model` — fallback when the session's model can't be read. Without it you get `could not determine a model`.
+- `GENESEED_LEARN_DEBOUNCE_MS` — the quiet period.
+
+## geneseed-workflow
+
+**What it does.** Registers one tool, `workflow`, that runs saved orchestration scripts. The script — not the model — drives the control flow: the deterministic counterpart of the `council` and `parallel-agents` skills.
+
+- **Saved scripts only.** It loads `<name>.js` from the `workflows/` directory beside `plugins/`; nothing the model writes is evaluated. Shipped: `council`, `dispatch`, `research-plan-implement`, `review`.
+- **Call shape:** `workflow({ name, args })`; with no name it lists what is available.
+- **Isolation:** a script can run a child agent in its own git worktree on its own branch. A worktree with no change is removed; one with changes is kept, and the summary lists every kept branch and every file more than one agent changed. Nothing is merged or committed for you. Without git, such a child fails rather than falling back to the shared tree.
+
+**When it runs.** When the agent calls the `workflow` tool — usually because you asked for one.
+
+**What you see.** The tool's summary in the conversation. A phase-by-phase trace and the full result land in `.geneseed/workflow-runs/<runId>.log`.
+
+**Switches.**
+- `GENESEED_WORKFLOWS_DIR` — load scripts from another directory.
+- `GENESEED_DEBUG=1` — log to stderr.
+
+Ask the agent to *"list available workflows"* to check it loaded.
+
+## geneseed-notify
+
+**What it does.** Sends a native desktop notification when the agent finishes a long turn, so you can start a run, walk away, and be called back. macOS uses `osascript`, Linux `notify-send` (install `libnotify` if nothing appears), Windows a PowerShell balloon.
+
+**When it runs.** When a session goes idle, and only if the turn took longer than `GENESEED_NOTIFY_MIN_SECONDS` (default 30) since your last prompt. Sub-agent sessions and the learn plugin's own sessions are skipped.
+
+**What you see.** A notification titled `Geneseed`. With `GENESEED_DEBUG=1`, `[geneseed-notify] notified for …` on stderr.
+
+**Switches.**
+- `GENESEED_NOTIFY=off` — disable.
+- `GENESEED_NOTIFY_MIN_SECONDS=N` — threshold (`0` = every turn).
+- `GENESEED_NOTIFY_TITLE="…"` — the title.
+
+## geneseed-ponytail
+
+**What it does.** Holds an opt-in minimal-code mode: once on, it appends the "laziest solution that works" ruleset to the system prompt **every turn**, so the agent doesn't drift back to over-building mid-session. It is the sustained form of the `ponytail` skill, and it is not part of the [rules](../concepts/rules.md): nothing about it applies until you switch it on.
+
+**When it runs.** Every turn, while a level is set. It starts `off`.
+
+**What you see.** Replies that favour the smallest working change. Switch with `/ponytail lite|full|ultra|off` (bare `/ponytail` means `full`); the level is saved to `.geneseed-ponytail` beside OpenCode's config and applies from the next turn. On an OpenCode build without the experimental system-prompt hook it never injects; the skill still works.
+
+**Switches.**
+- `GENESEED_PONYTAIL=lite|full|ultra` — the starting level (default `off`).
+- `GENESEED_DEBUG=1` — logs `[geneseed-ponytail] ponytail <level>` on each switch.
+
+## geneseed-activity
+
+**What it does.** Feeds the web console's **Activity** view: one small JSON file per session under `activity/` beside OpenCode's config, recording what the session is doing — phase, model, token and cost totals, files touched, plan, last error. The console reads and prunes those files; the two only meet on disk, so a crash on either side never blocks a session.
+
+**When it runs.** On session events, for top-level sessions only (sub-agents and learn's sessions are skipped). Entries whose process died or went stale are pruned by the reader.
+
+**What you see.** A card per live session in **Activity** (`geneseed web`).
+
+**Switches.**
+- `GENESEED_ACTIVITY=off` — kill switch at startup.
+- The Activity page's own toggle writes a `.geneseed-activity` flag file, read per event — no restart needed.
+- `GENESEED_DEBUG=1` — logs each write as `[geneseed-activity] …`.
+
+## Excluded folders
+
+`geneseed-context`, `geneseed-guard` and `geneseed-learn` go dormant inside a folder listed in the global install's `excludes.json` (managed by `geneseed exclude`). See [Exclusions](../concepts/exclusions.md).