geneseed 2.0.0

package/adapters/opencode/GLOBAL-HARNESS-SPEC.md

@@ -0,0 +1,434 @@
+# Global Harness + Convention-Glob Context — Spec
+
+Status: **implemented** (build emitter + context plugin v2 landed; docs synced).
+Target adapter: OpenCode. A *second deployment mode* ("everything global, zero
+per-repo files") plus the context-discovery redesign that makes it safe.
+
+It does **not** replace the portable bundle or the Claude Code adapter. The
+factory (`Geneseed/`) stays the single source of truth; this adds a way to render
+it straight into OpenCode's global config dir and discover each repo's docs by
+convention instead of by a committed `context.json`.
+
+---
+
+## 0. Why this exists (the principle it must not break)
+
+The harness enforces project context by **injection, not instruction** — eager
+docs are put *in context before turn 1*, never "left to agent discipline"
+([geneseed-context.js](plugins/geneseed-context.js) header;
+`project_geneseed_enforcement` memory). A pure "law: read the docs folder"
+approach regresses to instruction — the model reads *if* it obeys, *if* the law
+names the right folder, and re-reads every session.
+
+This spec keeps injection while removing the per-repo `context.json`: the **global
+plugin discovers the current repo's docs by convention at session start** and
+injects them. Per-project knowledge moves from a committed manifest into the
+plugin's runtime glob. A fallback Law (§8) covers tools/repos the plugin can't.
+
+Three tiers, and where this lands:
+
+| Tier | Global? | Per-repo file? | Enforcement |
+|---|---|---|---|
+| Law only ("read docs/") | ✅ | none | ❌ soft |
+| **Convention-glob plugin (this spec)** | ✅ | none (optional override) | ✅ injected |
+| Per-repo `context.json` (today) | plugin global, manifest local | yes | ✅ injected, declarative |
+
+---
+
+## 1. Deployment model — everything global
+
+Render the harness contents straight into OpenCode's global config dir. Nothing
+is committed into a work repo.
+
+| Piece | Global location | Loaded by |
+|---|---|---|
+| Entrypoint rules | `~/.config/opencode/AGENT.md` | `opencode.json` `instructions` (absolute path) |
+| Laws | inlined in `AGENT.md` (already) | via above |
+| Subagents | `~/.config/opencode/agents/*.md` | OpenCode global agents dir |
+| Skills | `~/.config/opencode/skills/<name>/SKILL.md` | native `skill` tool (model-invoked) — see §9.1 |
+| Plugins | `~/.config/opencode/plugins/*.js` | OpenCode auto-load |
+| Memory store | `$GENESEED_HARNESS/memory` (or `$GENESEED_MEMORY`) | learn plugin |
+| Project context | **auto-discovered per repo** by the context plugin | this spec |
+
+`~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["/home/<user>/.config/opencode/AGENT.md"]
+}
+```
+
+> Use an **absolute** path. A repo-relative `"AGENT.md"` in a *global* config
+> would resolve against each repo's root and usually miss.
+
+**Confirmed (OpenCode docs — config + plugins).** `~/.config/opencode/` loads
+`agents/`, `commands/`, `plugins/`, and `skills/`. Notes that shape this spec:
+
+- **Subdir names are plural** (`agents/`, `commands/`, `modes/`, `plugins/`,
+  `skills/`, `tools/`, `themes/`). Singular (`agent/`, `command/`) is *backwards-
+  compat only* — the current Geneseed build emits singular; the global emit (§9)
+  must write **plural**.
+- **Native `skills/` dir exists** — OpenCode has first-class skills *separate* from
+  commands. Today the harness maps skills → commands; globally we may map them →
+  `skills/` instead (§12 open question).
+- **`OPENCODE_CONFIG_DIR`** relocates the *entire* config dir (searched for
+  `agents/`, `commands/`, `modes/`, `plugins/` like `.opencode`). Use it to keep
+  the global harness in a **git-tracked** folder instead of `~/.config/opencode`.
+- **Precedence:** global config < project config < `OPENCODE_CONFIG_DIR` <
+  inline/managed. A project `opencode.json` still overrides the global one.
+
+---
+
+## 2. Context plugin — responsibilities (every block)
+
+The redesigned `geneseed-context.js` must cover all of the following. Blocks
+marked **(new)** are added on top of today's behavior.
+
+1. **Resolve source** — pick override manifest *or* auto-discovery (§3.1).
+2. **Auto-discovery** **(new)** — glob the repo cwd by convention (§3.2).
+3. **Classify** — split candidates into `eager` / `lazy` (§3.2 table).
+4. **Budget & demote** **(new)** — enforce size caps; demote oversized eager → lazy (§3.3).
+5. **Override merge** **(new)** — `.harness` / `context.json` add, pin, or exclude (§3.4).
+6. **Build injection block** — header, eager bodies, lazy listing, idempotency marker (§3.5).
+7. **Idempotency** **(new)** — per-instance dedup *and* cross-instance transcript check (§4).
+8. **Event + session gating** — fire on `session.created`; skip `geneseed-*` sessions (§5).
+9. **Inject** — `session.prompt({ noReply: true })`.
+10. **Error handling** — swallow everything; never block a session (§6).
+11. **Logging** — one structured stderr line per outcome (§7).
+
+---
+
+## 3. Context discovery — the core
+
+### 3.1 Resolution order (first match wins)
+
+```
+1. $GENESEED_CONTEXT                 explicit manifest path  -> declarative mode
+2. ./.harness/context.json           per-repo override       -> declarative mode
+3. ./context.json                    legacy per-repo manifest -> declarative mode
+4. (none of the above)               -> AUTO-DISCOVERY (convention glob)
+```
+
+- **Declarative mode** = today's behavior, extended to accept glob `path`s and an
+  `exclude` array (§3.4). Back-compatible: an existing flat `context.json` still works.
+- **Auto-discovery** = the new default. Zero per-repo files.
+
+Discovery always runs against the **repo root** = the session's `directory` /
+`worktree` (walk up from cwd to the git root; fall back to cwd).
+
+### 3.2 Auto-discovery convention
+
+Scanned relative to the repo root. **Eager** = injected in full. **Lazy** = only
+*listed* (path + first H1/description) so the agent knows it exists and reads on demand.
+
+| Class | Patterns (root-relative) | Rationale |
+|---|---|---|
+| **eager** | `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `.cursorrules`, `.harness/*.md` | agent-directed rules, small, always relevant |
+| **eager** | `README.md` (root only), `CONTRIBUTING.md` (root only) | canonical entry doc |
+| **lazy** | `docs/**/*.md`, `doc/**/*.md`, `documentation/**/*.md` | doc trees — large, occasional |
+| **lazy** | `**/ADR/**/*.md`, `**/adr/**/*.md`, `architecture/**/*.md` | decision records |
+| **lazy** | root `*.md` other than the eager ones (e.g. `CHANGELOG.md`) | misc root docs |
+| **lazy** | `packages/*/README.md`, `apps/*/README.md` | monorepo package entry docs |
+| **exclude (always)** | `node_modules/**`, `.git/**`, `dist/**`, `build/**`, `vendor/**`, `**/*.min.md` | never scan |
+
+Rules:
+- **Dedup against `instructions`.** If the repo's own `AGENTS.md`/`AGENT.md` is the
+  same file OpenCode already loads via `instructions`, skip it (avoid the
+  double-load class of bug). Compare resolved absolute paths.
+- **Globs are dependency-free.** Implement a tiny matcher (`**`, `*`) in the
+  plugin — do not add an npm dep. Cap directory recursion depth (e.g. 6) so a
+  pathological tree can't hang discovery.
+- **Determinism.** Sort matches lexicographically before injecting so the block is
+  stable across sessions (cache-friendly, diffable).
+
+### 3.3 Size & token budget
+
+Injection happens every session — it must not blow the window.
+
+| Cap | Default | Behavior on exceed |
+|---|---|---|
+| Per eager file | 16 KB | demote to **lazy** (list it, don't inject); log the demotion |
+| Total eager budget | 48 KB | stop injecting eager bodies once hit; remaining eager → listed as lazy |
+| Lazy listing | name + first H1 line only | never inject lazy bodies |
+| Max files scanned | 2000 | stop walking; log truncation |
+
+All caps overridable via env (`GENESEED_EAGER_FILE_KB`, `GENESEED_EAGER_TOTAL_KB`).
+**No silent truncation** — every demotion/cap hit logs (Lex: no silent caps).
+
+### 3.4 Override / escape-hatch schema
+
+`./.harness/context.json` (preferred) or `./context.json`. Same schema as today,
+plus two additions. Any override file switches off auto-discovery unless it sets
+`"extend": true`.
+
+```jsonc
+{
+  // optional: keep auto-discovery AND apply these rules on top of it
+  "extend": true,
+  "context": [
+    { "path": "docs/architecture.md", "load": "eager", "description": "system overview" },
+    { "path": "docs/**/*.md",         "load": "lazy" },                 // globs allowed
+    { "path": "internal/secrets.md",  "load": "exclude" }              // hard exclude
+  ]
+}
+```
+
+- `load`: `eager` | `lazy` | `exclude` (new).
+- `path`: absolute, repo-relative, or a glob.
+- `extend`: `false`/absent → manifest is the *complete* list (today's semantics).
+  `true` → auto-discovery runs first, then manifest entries add/override/exclude.
+- Precedence within merge: explicit manifest entry > auto-discovered classification.
+
+This is the `.harness` hatch the design calls for: drop one tiny file only when a
+repo's layout defeats the convention.
+
+### 3.5 Injection block format (mirror `harness.py cmd_context`)
+
+Byte-identical structure to [harness.py:237-263](../../rituals/harness.py) so both
+enforcement paths read the same. Adds a machine marker (first line) for §4.
+
+```
+<!-- geneseed-context:v2 -->
+=== PROJECT CONTEXT — binding for this repo per Law XVIII ===
+
+----- <path> — <description> -----
+<full file contents, trailing newlines stripped>
+
+----- <path2> -----
+<...>
+
+--- Lazy entries (load only when the task needs them) ---
+  - docs/architecture/overview.md — RF pipeline
+  - CHANGELOG.md
+  - [demoted: README.md exceeded 16 KB — read on demand]
+```
+
+- Header keeps the exact `=== PROJECT CONTEXT … Law XVIII ===` wording.
+- A `MISSING` eager file emits `[context] MISSING eager file: <err>` inline (as today).
+- The `<!-- geneseed-context:v2 -->` marker is the idempotency sentinel.
+
+---
+
+## 4. Idempotency & dedup (kills the double-injection)
+
+Two layers:
+
+1. **Per-instance** — keep the `done` Set keyed by session id (today's guard).
+   Stops one plugin instance re-firing on a repeated `session.created`.
+2. **Cross-instance (new)** — before injecting, read the transcript
+   (`client.session.messages({ path: { id } })`) and skip if any message part
+   already contains `<!-- geneseed-context:v2 -->`. This catches a global + leftover
+   project copy both firing.
+
+> **Docs-confirmed why this is needed:** OpenCode dedups plugins *by npm package
+> name+version only* — "a local plugin and an npm plugin with similar names are
+> both loaded separately," and global plugins load before project plugins. Two
+> local `.js` copies (global `~/.config/opencode/plugins/` + project
+> `.opencode/plugins/`) **always** both load. So the marker check is mandatory and
+> single-install (§9–10) is the only hard guarantee.
+
+**Honest limit:** if two instances fire *simultaneously* they can both read an
+empty transcript and both inject (race). The transcript check shrinks the window
+but does not close it. The real guarantee is **single global install** — §9 emits
+exactly one copy and the setup guide (§10) removes project copies. Document this.
+
+---
+
+## 5. Events & session gating
+
+- Fire only on `event.type === "session.created"`.
+- Extract sid from `properties.sessionID | payload.sessionID | properties.info.id |
+  payload.info.id` (as today).
+- **Skip throwaway sessions:** if `session.get(...).title` starts with `geneseed-`,
+  return (don't pollute the learn plugin's distil sessions).
+- Inject via `client.session.prompt({ path: { id }, body: { noReply: true, parts: [{ type: "text", text: block }] } })`.
+
+---
+
+## 6. Error handling
+
+- Every step wrapped; any failure → log to stderr, return, **never throw**. A
+  broken discovery must not block a session start (matches `cmd_context` exit-0
+  contract).
+- Missing repo root → fall back to cwd. No docs found → inject nothing (silent
+  except one debug log).
+
+---
+
+## 7. Logging (stderr, one line per outcome)
+
+```
+[geneseed-context] injected: 3 eager (41 KB), 12 lazy listed  [repo=/path]
+[geneseed-context] demoted README.md -> lazy (18 KB > 16 KB cap)
+[geneseed-context] skipped: already injected (marker present)
+[geneseed-context] skipped: geneseed-* session
+[geneseed-context] no docs discovered in <repo>
+[geneseed-context] error: <message>
+```
+
+---
+
+## 8. Fallback Law (for tools without the plugin)
+
+Add to the universal laws so non-OpenCode tools and uncovered repos still get
+project context — the *instruction* tier behind the *injection* tier:
+
+> **Law (Project Context Discovery).** When project context has not already been
+> injected, before substantive work read the repo's agent-directed rules and entry
+> docs — `AGENTS.md`/`AGENT.md`/`CLAUDE.md`, root `README.md`, and any `.harness/`
+> manifest — and treat `docs/`, `adr/`, and architecture notes as lazy: consult
+> them when the task touches their area. Prefer an injected PROJECT CONTEXT block
+> when present; this Law is the fallback, not the primary path.
+
+This is the "rely on the rule" path — kept as a safety net, not the main mechanism.
+
+---
+
+## 9. Build / emit changes
+
+Add an emit target so the factory can render straight into the global dir.
+
+`geneseed build --emit opencode-global [--theme NAME]` — **self-contained**: it
+writes ONLY into `<cfg>` and builds **no sibling `Harness/`** (plural subdir names —
+canonical):
+
+1. Render `AGENT.md` straight to `<cfg>/AGENT.md` (no Harness staging/copy).
+2. `agents/*.md` → `<cfg>/agents/*.md` (read-only agents keep `tools: { write:false, edit:false }`).
+3. skills → `<cfg>/skills/<name>/SKILL.md` (**native skills**, model-invoked — see §9.1).
+4. `plugins/*.js` → `<cfg>/plugins/*.js` (**single copy** — the fix).
+5. **Memory store** → `<cfg>/memory` (always classic English — never themed, like
+   `agents/`/`skills/`; a legacy themed `anamnesis/` is migrated into it): if it already has files,
+   left alone; else migrated once from a legacy `Harness/memory` (so a host moving
+   off a sibling bundle loses nothing), else seeded from the `src/memory` template.
+   The store is **not** owned-tracked — never deleted on re-emit. Point the learn
+   plugin at it with `GENESEED_HARNESS=<cfg>`.
+6. Write/merge `<cfg>/opencode.json` with the **absolute** `AGENT.md` path; never
+   clobbers a user-edited config — merges the `instructions` entry only.
+7. **No** `context.json` (auto-discovery is the default).
+8. `.geneseed-emit` marker written in `<cfg>` (build.py persists it regardless of
+   entrypoint), so a later bare `geneseed upgrade` keeps emitting globally.
+
+### 9.1 Skills → native `skills/` (decided)
+
+Skills emit as **native OpenCode skills**, not slash commands:
+
+- **Shape:** one directory per skill, `skills/<name>/SKILL.md` (not a flat
+  `commands/<name>.md`).
+- **Frontmatter:** skill schema — `name`, `description` (+ optional `license`,
+  `metadata`). Drop the command-only `agent:` / `model:`
+  keys. Geneseed's `src/skills/*.md` frontmatter is transformed on emit.
+- **Invocation:** model-invoked via the native `skill` tool with progressive
+  disclosure (the agent sees `description`s, loads the body on demand) — **not** a
+  user-typed `/name`. Each skill's `description` is therefore trigger-critical and
+  must be written to fire at the right moment.
+- **Trade-off:** loses per-skill `agent:`/`model:` pinning that commands allowed
+  (the old `agent: build`); a skill runs in the current agent/model context. Audit
+  `src/skills/` for any that depended on it before emit.
+- **Cross-adapter win:** `SKILL.md` is the *same artifact shape Claude Code uses*,
+  and OpenCode also auto-discovers `~/.claude/skills/*/SKILL.md` and
+  `~/.agents/skills/*/SKILL.md`. One skill source can feed both tools — collapsing
+  the two divergent emit paths and killing adapter drift. Optional: emit into
+  `~/.claude/skills/` for a single dir served to Claude Code *and* OpenCode.
+- **Migration:** existing per-repo `.opencode/command/*.md` emits go stale; update
+  the adapter README, HOW-OPENCODE-LOADS, and `src/skills/_template.md`.
+
+`<cfg>` resolution: `$OPENCODE_CONFIG_DIR` if set (lets the harness live in a
+git-tracked folder), else `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode`.
+
+`geneseed upgrade`: add `GENESEED_EMIT=opencode-global` to re-render globally on upgrade.
+
+> **Windows config path: confirmed.** Modern OpenCode uses the same homedir-relative
+> location on every OS, so `~/.config/opencode` resolves to `C:\Users\<user>\.config\opencode`
+> on Windows — exactly what `_opencode_config_dir()` (`Path.home() / ".config" / "opencode"`)
+> produces there. No `%APPDATA%` special case is needed (that was an old docs bug).
+> `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME` still override, as on Unix.
+
+---
+
+## 10. How to set up (global, zero per-repo)
+
+**One-time, on the machine that runs OpenCode.**
+
+1. **Emit globally** (from the Geneseed folder). No separate bundle build — this is
+   self-contained:
+   ```bash
+   cd /path/to/Geneseed
+   GENESEED_EMIT=opencode-global ./geneseed upgrade imperial   # or any other theme
+   ```
+   This populates `~/.config/opencode/{AGENT.md,agents/,skills/,plugins/,memory/}`,
+   wires `opencode.json` to the absolute `AGENT.md`, and remembers the mode in
+   `<cfg>/.geneseed-emit` — so every later bare `geneseed upgrade` stays global.
+   (Direct equivalent: `geneseed build --emit opencode-global`.)
+
+   **Windows (PowerShell)** — same flow, no bash:
+   ```powershell
+   cd C:\path\to\Geneseed
+   $env:GENESEED_EMIT = "opencode-global"
+   .\geneseed.cmd upgrade main imperial      # PowerShell runs a .cmd directly
+   ```
+   This populates `C:\Users\<user>\.config\opencode\{AGENT.md,agents,skills,plugins,memory}`.
+
+2. **Point the learn plugin at the in-config memory store** (once):
+   ```bash
+   export GENESEED_HARNESS="$HOME/.config/opencode"        # so it writes <cfg>/memory
+   echo "export GENESEED_HARNESS=\"$HOME/.config/opencode\"" >> ~/.zshrc
+   ```
+   On **Windows (PowerShell)**:
+   ```powershell
+   setx GENESEED_HARNESS "$env:USERPROFILE\.config\opencode"   # persists for new shells
+   ```
+   (Or `$OPENCODE_CONFIG_DIR` if you relocated the config dir.) The learn plugin also
+   auto-locates the in-config store, so this is only needed to pin it explicitly.
+
+3. **Remove every per-repo copy** (the source of the double-injection):
+   ```bash
+   # in each repo you previously ran --emit opencode in:
+   rm -rf .opencode/plugins .opencode/agents .opencode/agent .opencode/skills \
+          .opencode/command opencode.json context.json
+   # and confirm only ONE global plugin copy exists:
+   ls ~/.config/opencode/plugins/        # geneseed-context.js + geneseed-learn.js, once each
+   ```
+
+4. **Verify** (§11). A stray sibling `Harness/` from an older global build is now
+   unused — safe to delete once memory has migrated into `<cfg>/memory`.
+
+**Per repo afterwards: nothing.** Open OpenCode in any repo — the global AGENT.md,
+agents, and skills load, and the context plugin auto-discovers that repo's docs.
+Only drop a `./.harness/context.json` (§3.4) in a repo whose layout defeats the
+convention.
+
+---
+
+## 11. Acceptance checklist
+
+- [x] Fresh repo with a `README.md` + `docs/` → exactly **one** PROJECT CONTEXT
+      block, README eager, `docs/**` listed lazy. *(verified — node fixture test)*
+- [x] Repo with no docs → no block, one `no docs discovered` log, session starts clean.
+- [x] Global + leftover project plugin copy → still **one** block (marker dedup). *(verified)*
+- [x] >16 KB README → demoted to lazy, demotion logged, eager budget respected. *(verified)*
+- [x] `.harness/context.json` with `extend:true` + `exclude` + pin → merged correctly. *(verified)*
+- [x] `geneseed-*` distil session → no injection.
+- [x] Plugin adds **no** npm dependency. *(stdlib `node:fs`/`node:path`/`node:url` only)*
+- [x] Global re-emit removes stale owned files, preserves user files, writes no
+      `context.json`. *(verified — manifest cleanup test)*
+- [ ] Malformed `.harness/context.json` → error logged, session still starts. *(swallowed by readJson; not explicitly tested)*
+- [ ] Live OpenCode session on the work laptop (field-test caveat — event/SDK field names).
+
+---
+
+## 12. Non-goals / open questions
+
+- **Not** removing the portable bundle or the per-repo `context.json` tier — both stay.
+- **Race** on simultaneous dual-instance injection is mitigated, not eliminated
+  (§4) — single install is the guarantee (docs-confirmed: local plugins never dedup).
+- **Resolved:** OpenCode global `agents/` + `commands/` + `skills/` loading is
+  confirmed (§1). Subdir names are plural (singular = back-compat).
+- **Resolved:** Windows config-dir path is the same homedir-relative
+  `~/.config/opencode` (→ `C:\Users\<user>\.config\opencode`); no `%APPDATA%` case (§9).
+- **Decided:** skills emit as **native `skills/<name>/SKILL.md`** (§9.1) — model-
+  invoked, progressive disclosure, same shape as Claude Code skills. Cost: no slash
+  trigger, no per-skill `agent:`/`model:` pinning.
+- **Open:** whether eager auto-discovery of a repo's `AGENTS.md` should be dropped
+  entirely (since `instructions` may already load it) or kept with path-dedup —
+  spec currently keeps it with dedup.

package/adapters/opencode/HOW-OPENCODE-LOADS.md

@@ -0,0 +1,158 @@
+# How OpenCode loads a project
+
+A reference for what OpenCode reads at startup, how Geneseed plugs into each
+mechanism, and why a file can appear **listed twice**. Field names and event lists
+are confirmed against the current OpenCode plugin + SDK docs; they can still shift
+between versions, and the plugins degrade quietly if one does.
+
+## 1. Config discovery & merge
+
+OpenCode does not read a single config — it **merges several**:
+
+- **Global:** `~/.config/opencode/opencode.json` (on Windows, the same homedir-relative
+  path: `C:\Users\<user>\.config\opencode\opencode.json`).
+- **Project:** `./opencode.json` or `./.opencode/opencode.json`, found by walking up
+  from the current directory to the worktree root.
+- Project config **overrides** global on direct conflicts.
+
+It also auto-loads an **`AGENTS.md`** at the project root with no config at all.
+
+Because these sources merge rather than replace, **anything referenced in two of
+them loads from each** — which is exactly why a file can show up twice (see §7).
+
+## 2. `instructions` — the rule/context files
+
+The `instructions` array names files loaded into **every session** as ambient
+rules. It accepts:
+
+- absolute paths,
+- repo-relative paths,
+- globs (`"laws/*.md"`),
+- URLs.
+
+Geneseed points it at the bundle's **`AGENT.md`** (which inlines the laws). That is
+all you need there — the rest of the harness is loaded by the plugins below.
+
+## 3. Plugins — event-driven JS/TS
+
+Plugins are **auto-loaded** from a plugins directory at startup. **No entry in
+`opencode.json` is required** (the `"plugin"` array is only for *npm-package*
+plugins). Local plugin directories:
+
+- **Global:** `~/.config/opencode/plugins/`
+- **Project:** `.opencode/plugins/`
+
+The folder is **`plugins`** (plural), both `.js` and `.ts` are accepted, and it does
+**not** exist by default — create it the first time.
+
+A plugin is an async function that receives a context object and returns hook
+implementations:
+
+```js
+export const MyPlugin = async ({ client, $, directory, worktree }) => ({
+  event: async ({ event }) => {
+    if (event.type === "session.idle") { /* … */ }
+  },
+})
+```
+
+- **`event({ event })`** — the catch-all; filter on `event.type`. Session events
+  include `session.created`, `session.idle`, `session.updated`, `session.compacted`,
+  `session.error`, plus `message.updated`, `tool.execute.before/after`, and more.
+- **`client`** — the OpenCode SDK. Read a session's transcript with
+  `client.session.messages({ path: { id } })` → `{ info, parts }[]`; inject context
+  **without** triggering a reply with `client.session.prompt({ path, body: { noReply: true, parts } })`.
+- **`$`** — a shell executor for running commands.
+
+## 4. Subagents, skills & commands
+
+Subdir names are **plural** canonically (`agents/`, `skills/`, `commands/`,
+`plugins/`, …); singular (`agent/`, `command/`) is back-compat only.
+
+- `.opencode/agents/<name>.md` → a **subagent** (frontmatter: `description`,
+  `mode: subagent`, optional `permission:` to deny edit/bash/webfetch — Geneseed uses
+  this to make read-only agents truly read-only, shell included).
+- `.opencode/skills/<name>/SKILL.md` → a **native skill** (frontmatter: `name`,
+  `description`) — model-invoked via the `skill` tool, progressive disclosure.
+- `.opencode/commands/<name>.md` → a **slash command** (user-invoked `/name`).
+
+Geneseed generates subagents and native skills from `src/` via `geneseed build
+--emit opencode` (or globally with `--emit opencode-global`) — zero drift. It maps skills
+to native **skills**, not slash commands (same `SKILL.md` shape as Claude Code).
+
+## 5. How Geneseed maps onto OpenCode
+
+| OpenCode mechanism | Geneseed piece |
+| --- | --- |
+| `instructions` → `AGENT.md` | the rules, loaded every session |
+| `.opencode/agents/`, `.opencode/skills/` | capability agents and native skills |
+| plugin on `session.created` | **context plugin (v2)** — auto-discovers & injects the repo's `eager` docs |
+| plugin on `experimental.session.compacting` | **context plugin** — re-pushes the `eager` docs so they survive compaction |
+| plugin on `session.idle` | **learn plugin** — distils memory into `memory/` (debounced to fire once, at session end) |
+| plugin on `tool.execute.before` | **guard plugin** — blocks secret-file writes and catastrophic shell (Laws I & IV; `GENESEED_GUARD=off\|warn`) |
+| plugin registering a custom tool | **workflow plugin** — the `workflow` tool runs saved orchestration scripts from `workflows/` |
+| `context.json` / `.harness/` (manifest) | *optional* override when discovery doesn't fit |
+
+## 6. LSP — diagnostics, not a tool
+
+Geneseed sets `"lsp": true`, so OpenCode auto-starts a language server matching
+each file's extension **when the file is opened**, and feeds its diagnostics back
+to the model as ambient context.
+
+The thing to know: **the LSP is not a tool the model can call.** There is no
+"use the LSP" action — the model's toolset is `bash`/`read`/`write`/`edit`/`grep`/
+`glob`/`task`/`webfetch` and nothing else. Diagnostics arrive as injected feedback
+when a file is opened or edited; the model cannot summon them on demand. So a model
+that says *"I have no LSP tool"* is **correct**, not broken — asking it to "trigger
+the React LSP" can't be honored as a tool call.
+
+OpenCode's own docs steer you the same way: language servers drift and eat memory,
+so *"it is often better to have the agent run lint, typecheck, or other diagnostic
+CLI tools directly."* A clean `eslint` (and `tsc --noEmit` where there's a TS
+project) is the **same signal** the LSP would inject — just fetched on purpose
+instead of ambiently. That is exactly what a model running `npx eslint <file>` is
+doing, and it's the recommended path.
+
+**JS/JSX caveat (e.g. `web/`):** the bundled TypeScript server attaches to `.jsx`
+by extension even with no config, but only in loose single-file mode. A minimal
+`web/jsconfig.json` (no `checkJs`) scopes the directory as a project so the server
+resolves imports and JSX properly — present in this repo for that reason. Real-bug
+detection still lives in `eslint.config.js`; `jsconfig.json` only makes the LSP
+attach as a project, it does not turn on type-checking.
+
+## 7. "Why is `context.json` (or `AGENT.md`) listed twice?"
+
+Because OpenCode **merges every `opencode.json` it finds** — global, project, and
+any discovered while walking up the tree. If the same file is named in two
+`instructions` arrays, it is loaded once **per source**. This is harmless (just
+duplicated context), but to clean it up, name each file in **one** config only.
+
+Geneseed's emit lists **only `AGENT.md`** in `instructions` (never `context.json` —
+the context plugin handles project docs by auto-discovery), so the classic
+"manifest listed twice" no longer happens. Keep:
+
+```json
+{ "instructions": ["/abs/path/to/AGENT.md"] }
+```
+
+If you still see `AGENT.md` loaded twice, it is named in two merged `opencode.json`
+files — find and de-dup:
+
+```bash
+for f in ~/.config/opencode/opencode.json ./opencode.json ./.opencode/opencode.json; do
+  echo "== $f =="; cat "$f" 2>/dev/null; echo
+done
+```
+
+### The PROJECT CONTEXT block twice
+
+The modern cause of a *doubled injection* is **two copies of the context plugin**
+(global `~/.config/opencode/plugins/` + a leftover project `.opencode/plugins/`) —
+OpenCode dedups plugins by npm name+version only, so two local `.js` files both
+load. The v2 plugin guards against this with a transcript marker
+(`<!-- geneseed-context:v2 -->`) — it skips a session that already carries it — but
+the clean fix is a single install. Remove the stray project copy:
+
+```bash
+rm -rf .opencode/plugins .opencode/agents .opencode/skills .opencode/command .opencode/agent
+```