geneseed 3.10.0 → 3.11.0

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).