geneseed 3.12.0 → 3.13.0

package/docs/guides/upgrade.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 4
+order: 25
 title: "Upgrade"
 kind: "concept"
+section: "Keep it running"
+description: "Get a new version onto every install, and keep your local edits."
 ---
 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.
 

package/docs/guides/verify.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 3
+order: 13
 title: "Verify it works"
 kind: "concept"
+section: "Set up"
+description: "Check an install works, right after installing or when something feels off."
 ---
 Four checks, from quickest to most thorough. The first one alone tells you whether the harness loaded.
 

package/docs/guides/wiki.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 7
+order: 15
 title: "Connect your wiki"
 kind: "concept"
+section: "Set up"
+description: "Give the agent your own notes, machine-wide."
 ---
 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.
 

package/docs/guides/worktree.md

@@ -1,8 +1,10 @@
 ---
 group: guides
-order: 12
+order: 30
 title: "Add git-worktree isolation"
 kind: "concept"
+section: "OpenCode extras"
+description: "Add the optional third-party git-worktree isolation to OpenCode."
 harness: "opencode"
 ---
 This is a third-party, optional OpenCode plugin. Geneseed does not ship it or install it.

package/docs/reference/about.md

@@ -1,7 +1,9 @@
 ---
 group: reference
-order: 6
+order: 21
 title: "About — version, license, links"
 kind: "about"
+section: "Glossary & about"
+description: "Your version, theme and host, the license, and where updates come from."
 ---
 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

@@ -3,5 +3,7 @@ group: reference
 order: 1
 title: "CLI — every subcommand"
 kind: "cli"
+section: "CLI & environment"
+description: "Every geneseed subcommand, from the CLI's own table."
 ---
 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/env-context.md

@@ -0,0 +1,40 @@
+---
+group: reference
+order: 4
+title: "Context and memory variables"
+kind: "concept"
+section: "CLI & environment"
+description: "The variables that steer what loads at session start and where memory is written."
+---
+The environment variables that steer context injection and memory. None is required. The rest are on [Environment variables](environment.md).
+
+"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)).
+
+## 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). |

package/docs/reference/environment.md

@@ -1,14 +1,18 @@
 ---
 group: reference
-order: 2
+order: 3
 title: "Environment variables"
 kind: "concept"
+section: "CLI & environment"
+description: "Where Geneseed installs, how the CLI and console behave, and where the other variables are listed."
 ---
-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.
+The environment variables Geneseed reads, grouped by what they change. 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
+The variables that steer context injection and memory are on [Context and memory variables](env-context.md).
+
+## Where things install
 
 Where Geneseed writes an install, and what an upgrade re-renders.
 
@@ -26,64 +30,11 @@ Where Geneseed writes an install, and what an upgrade re-renders.
 | `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.
+## OpenCode plugin variables
 
-| 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. |
+Each OpenCode plugin's page lists its own switches: [guard](plugin-guard.md) (`GENESEED_GUARD`), [notify](plugin-notify.md) (`GENESEED_NOTIFY`, `GENESEED_NOTIFY_MIN_SECONDS`, `GENESEED_NOTIFY_TITLE`), [ponytail](plugin-ponytail.md) (`GENESEED_PONYTAIL`), [workflow](plugin-workflow.md) (`GENESEED_WORKFLOWS_DIR`) and [activity](plugin-activity.md) (`GENESEED_ACTIVITY`). `GENESEED_DEBUG=1` makes every plugin but guard and learn (which always log) say what it decided on stderr. `OPENCODE_DISABLE_LSP_DOWNLOAD` belongs to OpenCode itself: see [Language servers](../concepts/lsp.md).
 
-### Web console and CLI
+## Web console and CLI
 
 How the `geneseed` command behaves and prints.
 

package/docs/reference/glossary.md

@@ -1,8 +1,10 @@
 ---
 group: reference
-order: 3
+order: 20
 title: "Glossary"
 kind: "glossary"
+section: "Glossary & about"
+description: "Every Geneseed word you won't find in a programming glossary, with a dev analogy."
 ---
 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.
 

package/docs/reference/loop-actions.md

@@ -0,0 +1,20 @@
+---
+group: reference
+order: 2
+title: "Loop actions"
+kind: "concept"
+section: "CLI & environment"
+description: "The geneseed loop actions, one line each."
+---
+The actions of `geneseed loop`, the state machine behind [Loops](../concepts/loops.md). The `loop` skill calls them for you; [Finish a loop](../guides/loop-finish.md) shows how to drive one by hand.
+
+| action | what it does |
+|---|---|
+| `check` | lists templates and every brick (available, unavailable, overridden); validates one graph file (`--graph`) or one brick file (`--brick`) |
+| `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
+| `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
+| `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
+| `record` | records a brick's reported outcome and advances the graph; `--note` or `--note-file <path>` carries a finding (a read brick's plan or review findings) into `LOOP.md`'s notes so it survives the unit |
+| `decide` | answers an `awaiting` validation with a verdict and a note |
+
+Run `geneseed loop --help` for the full flag list.

package/docs/reference/opencode-plugins.md

@@ -1,132 +1,28 @@
 ---
 group: reference
-order: 5
-title: "OpenCode plugins"
 kind: "concept"
+section: "OpenCode plugins"
+order: 12
+title: "OpenCode plugins"
+description: "What the OpenCode plugins are, how they install, and the folders that silence them."
 ---
 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.
-
-A `permission.ask` hook lets through only a fixed set of commit/push forms on a `loop/*` branch with a running loop — anything else still asks, same as the Claude/Bob git-gate's loop/* exemption.
-
-**When it runs.** Before every tool call (`tool.execute.before`), and before a static `permission.bash` ask is shown to you (`permission.ask`).
-
-**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.
+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 on OpenCode](../guides/install-opencode.md). Keep **one** copy of each: OpenCode loads two local copies of the same plugin twice.
 
-**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.
+Every plugin swallows its own errors — none can block or crash a session. Each plugin's page lists the variables that tune it.
 
-**What you see.** A card per live session in **Activity** (`geneseed web`).
+## The plugins
 
-**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] …`.
+- [geneseed-context](plugin-context.md): Puts your project docs, rules, profile, memory index and wiki in front of the agent.
+- [geneseed-guard](plugin-guard.md): Blocks credential files, catastrophic commands and protected wiki writes before they run.
+- [geneseed-learn](plugin-learn.md): Distils durable facts into memory/ once a session goes quiet.
+- [geneseed-workflow](plugin-workflow.md): Adds a workflow tool that runs saved orchestration scripts.
+- [geneseed-notify](plugin-notify.md): A desktop notification when a long turn finishes.
+- [geneseed-ponytail](plugin-ponytail.md): An opt-in minimal-code mode, re-applied every turn.
+- [geneseed-activity](plugin-activity.md): Feeds the web console's Activity view, one small file per session.
 
 ## Excluded folders
 

package/docs/reference/plugin-activity.md

@@ -0,0 +1,20 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 19
+title: "geneseed-activity"
+description: "Feeds the web console's Activity view, one small file per session."
+---
+One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](environment.md) points here for its switches.
+
+**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] …`.

package/docs/reference/plugin-context.md

@@ -0,0 +1,27 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 13
+title: "geneseed-context"
+description: "Puts your project docs, rules, profile, memory index and wiki in front of the agent."
+---
+One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed in [Context and memory variables](env-context.md).
+
+**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.

package/docs/reference/plugin-guard.md

@@ -0,0 +1,27 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 14
+title: "geneseed-guard"
+description: "Blocks credential files, catastrophic commands and protected wiki writes before they run."
+---
+One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](environment.md) points here for its switches.
+
+**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.
+
+A `permission.ask` hook lets through only a fixed set of commit/push forms on a `loop/*` branch with a running loop — anything else still asks, same as the Claude/Bob git-gate's loop/* exemption.
+
+**When it runs.** Before every tool call (`tool.execute.before`), and before a static `permission.bash` ask is shown to you (`permission.ask`).
+
+**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.

package/docs/reference/plugin-learn.md

@@ -0,0 +1,27 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 15
+title: "geneseed-learn"
+description: "Distils durable facts into memory/ once a session goes quiet."
+---
+One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed in [Context and memory variables](env-context.md).
+
+**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.

package/docs/reference/plugin-notify.md

@@ -0,0 +1,20 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 17
+title: "geneseed-notify"
+description: "A desktop notification when a long turn finishes."
+---
+One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](environment.md) points here for its switches.
+
+**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.

package/docs/reference/plugin-ponytail.md

@@ -0,0 +1,19 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 18
+title: "geneseed-ponytail"
+description: "An opt-in minimal-code mode, re-applied every turn."
+---
+One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](environment.md) points here for its switches.
+
+**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.

package/docs/reference/plugin-workflow.md

@@ -0,0 +1,25 @@
+---
+group: reference
+kind: "concept"
+section: "OpenCode plugins"
+order: 16
+title: "geneseed-workflow"
+description: "Adds a workflow tool that runs saved orchestration scripts."
+---
+One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](environment.md) points here for its switches.
+
+**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.

package/docs/reference/troubleshoot-doctor.md

@@ -0,0 +1,50 @@
+---
+group: reference
+kind: "concept"
+section: "Troubleshooting"
+order: 10
+title: "Doctor findings"
+description: "Unresolved tokens, a drifted Harness bundle, an unreadable registry.json."
+---
+Each entry gives the likely cause, the fix, and how to confirm it worked. First stop for almost anything: `geneseed doctor` (see [Troubleshooting](troubleshooting.md)).
+
+## `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.