geneseed 4.0.0 → 4.2.0

package/adapters/opencode/plugins/geneseed-learn.js

@@ -301,6 +301,23 @@ async function writeMemories(output, memDir, existing) {
   return written
 }
 
+// The distil's reply into the store: a child session's one agent lesson, else memory
+// files plus their MEMORY.md lines. Shared by the V1 and V2 runs.
+async function storeDistil(output, { isChild, memDir, agentName, existing }) {
+  if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
+  if (isChild) {
+    const lesson = output.trim().split("\n")[0].replace(/^[-*]\s*/, "").trim()
+    if (lesson.length < 10 || lesson.length > 300) return // junk / truncation guard
+    const f = await appendAgentLesson(memDir, agentName, lesson)
+    console.error(`[geneseed-learn] agent lesson -> ${f}`)
+    return
+  }
+  const written = await writeMemories(output, memDir, existing)
+  if (written.length) {
+    console.error(`[geneseed-learn] wrote ${written.length} memory file(s): ${written.join(", ")}`)
+  }
+}
+
 export const GeneseedLearn = async (ctx) => {
   const { client } = ctx ?? {}
   const ours = new Set()       // throwaway distil sessions — never mine our own output
@@ -376,18 +393,7 @@ export const GeneseedLearn = async (ctx) => {
         if (newId) await client.session.delete({ path: { id: newId } }).catch(() => {})
       }
 
-      if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
-      if (isChild) {
-        const lesson = output.trim().split("\n")[0].replace(/^[-*]\s*/, "").trim()
-        if (lesson.length < 10 || lesson.length > 300) return // junk / truncation guard
-        const f = await appendAgentLesson(memDir, agentName, lesson)
-        console.error(`[geneseed-learn] agent lesson -> ${f}`)
-        return
-      }
-      const written = await writeMemories(output, memDir, existing)
-      if (written.length) {
-        console.error(`[geneseed-learn] wrote ${written.length} memory file(s): ${written.join(", ")}`)
-      }
+      await storeDistil(output, { isChild, memDir, agentName, existing })
     } catch (err) {
       // Never break the session over a memory write.
       console.error(`[geneseed-learn] skipped: ${err?.message ?? err}`)
@@ -426,6 +432,113 @@ export const GeneseedLearn = async (ctx) => {
 
 // OpenCode treats every export as a plugin and rejects non-functions; hang the test
 // helpers off the factory instead — reachable via import, invisible to the loader.
-Object.assign(GeneseedLearn, { writeMemories, resolveAgentName, appendAgentLesson })
+Object.assign(GeneseedLearn, { writeMemories, resolveAgentName, appendAgentLesson, flattenV2 })
+
+// ---- OpenCode 2 ----------------------------------------------------------------
+// `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
+// each V1 hook's V2 counterpart: adapters/opencode/HOW-OPENCODE-LOADS.md.
+//
+// What differs on V2:
+//   - The debounce re-arms on `session.execution.succeeded`: V2 core never publishes
+//     `session.idle` (deprecated in its schema), and the execution pair is its turn
+//     boundary. Events are `{ type, data }`, not `{ type, properties }`.
+//   - The transcript is `session.context()` — the messages after the last compaction —
+//     typed `user` (text) / `assistant` (content parts, `model: { providerID, id }`).
+//   - The distil is one stateless `generate.text({ prompt, model })` call with the
+//     session's own model: no throwaway session to create, guard against and delete.
+function flattenV2(messages) {
+  const lines = []
+  let model = null
+  for (const m of messages || []) {
+    if (m?.type === "user") {
+      const text = String(m.text ?? "").trim()
+      if (text) lines.push(`user: ${text}`)
+    } else if (m?.type === "assistant") {
+      const text = (m.content || [])
+        .filter((p) => p?.type === "text" && typeof p.text === "string")
+        .map((p) => p.text).join("\n").trim()
+      if (text) lines.push(`assistant: ${text}`)
+      if (m.model?.providerID && m.model?.id) model = m.model
+    }
+  }
+  return { notes: lines.join("\n\n"), model }
+}
+
+async function setupV2(ctx) {
+  const root = ctx?.location?.project?.directory || ctx?.location?.directory || process.cwd()
+  const timers = new Map()
+  const inFlight = new Set()
+  let warnedNoDir = false
+
+  async function runDistill(sid) {
+    if (await sovereignBypass(root)) return
+    if (inFlight.has(sid)) return
+    inFlight.add(sid)
+    try {
+      const meta = await ctx.session.get({ sessionID: sid }).catch(() => null)
+      if (String(meta?.title ?? "").startsWith("geneseed-")) return
+      const isChild = !!meta?.parentID
+      const agentName = isChild ? resolveAgentName(meta) : null
+      if (isChild && !agentName) return
+
+      const memDir = await resolveMemoryDir()
+      if (!memDir) {
+        if (!warnedNoDir) {
+          warnedNoDir = true
+          console.error("[geneseed-learn] no memory dir — set $GENESEED_HARNESS or $GENESEED_MEMORY.")
+        }
+        return
+      }
+
+      let { notes, model } = flattenV2(await ctx.session.context({ sessionID: sid }))
+      if (notes.length < MIN_NOTES_CHARS) return
+      notes = notes.slice(-MAX_NOTES_CHARS)
+      if (!model) {
+        const env = envModel()
+        model = env ? { providerID: env.providerID, id: env.modelID } : null
+      }
+      if (!model) {
+        console.error("[geneseed-learn] could not determine a model — set $GENESEED_MODEL=provider/model.")
+        return
+      }
+
+      const existing = await existingSlugs(memDir)
+      const prompt = isChild
+        ? [AGENT_LESSON_PROMPT, "", "NOTES:", notes].join("\n")
+        : buildPrompt(notes, existing)
+      const reply = await ctx.generate.text({
+        prompt, model: { providerID: model.providerID, id: model.id, ...(model.variant ? { variant: model.variant } : {}) },
+      })
+      await storeDistil(String(reply?.text ?? ""), { isChild, memDir, agentName, existing })
+    } catch (err) {
+      console.error(`[geneseed-learn] skipped: ${err?.message ?? err}`)
+    } finally {
+      inFlight.delete(sid)
+    }
+  }
+
+  const controller = new AbortController()
+  void (async () => {
+    for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+      const sid = ev?.data?.sessionID
+      if (!sid) continue
+      if (ev.type === "session.deleted") {
+        const t = timers.get(sid)
+        if (t) clearTimeout(t)
+        timers.delete(sid)
+        continue
+      }
+      if (ev.type !== "session.execution.succeeded") continue
+      const prev = timers.get(sid)
+      if (prev) clearTimeout(prev)
+      timers.set(sid, setTimeout(() => { timers.delete(sid); runDistill(sid) }, DEBOUNCE_MS))
+    }
+  })().catch((err) => console.error(`[geneseed-learn] event stream ended: ${err?.message ?? err}`))
+  return () => {
+    controller.abort()
+    for (const t of timers.values()) clearTimeout(t)
+    timers.clear()
+  }
+}
 
-export default GeneseedLearn
+export default { id: "geneseed-learn", server: GeneseedLearn, setup: setupV2 }

package/adapters/opencode/plugins/geneseed-notify.js

@@ -157,4 +157,49 @@ export const GeneseedNotify = async ({ client }) => {
 // off the factory instead — reachable via `import`, invisible to the loader.
 Object.assign(GeneseedNotify, { lastUserMs, shouldNotify, notifyCommand })
 
-export default GeneseedNotify
+// ---- OpenCode 2 ----------------------------------------------------------------
+// `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
+// each V1 hook's V2 counterpart: adapters/opencode/HOW-OPENCODE-LOADS.md.
+//
+// V2 core never publishes `session.idle` (deprecated in its schema). The turn boundary is
+// the execution pair instead: `session.execution.started` stamps when the agent began,
+// `session.execution.succeeded`/`failed` ends it — so the turn length comes straight off
+// the events, no transcript read. An interrupted execution is the user's own doing (or a
+// shutdown) and is not announced. Events are `{ type, created, data }`, not V1's
+// `{ type, properties }`.
+async function setupV2(ctx) {
+  if (OFF) return
+  const started = new Map()
+  const controller = new AbortController()
+  void (async () => {
+    for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+      const sid = ev?.data?.sessionID
+      if (!sid) continue
+      if (ev.type === "session.execution.started") { started.set(sid, ev.created); continue }
+      if (ev.type === "session.execution.interrupted" || ev.type === "session.deleted") { started.delete(sid); continue }
+      if (ev.type !== "session.execution.succeeded" && ev.type !== "session.execution.failed") continue
+      const begin = started.get(sid) ?? null
+      started.delete(sid)
+      try {
+        let title = "", parentID
+        try {
+          const info = await ctx.session.get({ sessionID: sid })
+          title = info?.title ?? ""
+          parentID = info?.parentID
+        } catch {}
+        const now = typeof ev.created === "number" ? ev.created : Date.now()
+        if (!shouldNotify({ now, lastUserMs: begin, parentID, title, minMs: MIN_MS })) {
+          log(`skipped ${sid} (child/throwaway or turn under ${MIN_MS}ms)`)
+          continue
+        }
+        deliver(TITLE, title ? `Done: ${title}` : "Agent finished — your turn.")
+        log(`notified for ${sid}`)
+      } catch (err) {
+        log(`skipped: ${err?.message ?? err}`)
+      }
+    }
+  })().catch((err) => log(`event stream ended: ${err?.message ?? err}`))
+  return () => controller.abort()
+}
+
+export default { id: "geneseed-notify", server: GeneseedNotify, setup: setupV2 }

package/adapters/opencode/plugins/geneseed-ponytail.js

@@ -143,6 +143,48 @@ export const GeneseedPonytail = async () => ({
 // any that isn't a function — a bare helper export crashes startup ("null is not an
 // object") or logs "not a function". Hang the test helpers off the factory instead;
 // they ride along for `import`, invisible to the loader. Upgrade path: none needed.
-Object.assign(GeneseedPonytail, { normalizeMode, defaultMode, ponytailInstructions })
+Object.assign(GeneseedPonytail, { normalizeMode, defaultMode, ponytailInstructions, levelFromPrompt })
 
-export default GeneseedPonytail
+// --- OpenCode 2 --------------------------------------------------------------
+// `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
+// each V1 hook's V2 counterpart: adapters/opencode/HOW-OPENCODE-LOADS.md.
+//
+// V2 has neither hook. `session.hook("context")` carries the outgoing system parts (the
+// ruleset is pushed there), and there is no `command.execute.before`: a markdown command
+// expands its template into the prompt, so the switch is read off the prompt instead —
+// the first line of PONYTAIL_COMMAND_BODY (js/hosts/opencode.mjs), `Ponytail level
+// requested: <args>`. Change that line and this pattern together.
+const PONYTAIL_PROMPT_RE = /^Ponytail level requested:[ \t]*(.*)$/m
+
+// The level a `/ponytail` prompt asks for: undefined when the text is not one, null
+// when its argument is no known level, else the level (empty argument = `full`).
+function levelFromPrompt(text) {
+  const m = PONYTAIL_PROMPT_RE.exec(String(text ?? ""))
+  if (!m || m.index !== 0) return undefined
+  const arg = m[1].trim()
+  return normalizeMode(arg) || (arg ? null : "full")
+}
+
+async function setupV2(ctx) {
+  await ctx.session.hook("prompt", (event) => {
+    try {
+      const mode = levelFromPrompt(event?.prompt?.text)
+      if (mode === undefined) return
+      if (!mode) { log("ignored unknown level"); return }
+      writeMode(mode)
+      log(`ponytail ${mode}`)
+    } catch (err) {
+      log(`prompt hook error: ${err?.message ?? err}`)
+    }
+  })
+  await ctx.session.hook("context", (event) => {
+    try {
+      const text = ponytailInstructions(readMode())
+      if (text && Array.isArray(event?.system)) event.system.push({ type: "text", text })
+    } catch (err) {
+      log(`context hook error: ${err?.message ?? err}`)
+    }
+  })
+}
+
+export default { id: "geneseed-ponytail", server: GeneseedPonytail, setup: setupV2 }

package/adapters/opencode/plugins/geneseed-workflow.js

@@ -116,23 +116,10 @@ async function writeTrace(rootDir, runId, lines) {
   } catch (e) { dlog(`trace write failed: ${e?.message || e}`); return "(trace write failed)" }
 }
 
-export const GeneseedWorkflow = async (ctx) => {
-  const { client, directory, worktree } = ctx
+// The `workflow` tool's body, shared by the V1 and V2 registrations: `client` is the V1
+// SDK client, or on V2 the facade `v2Client` builds over the plugin context.
+function makeExecute({ client, directory, worktree }) {
   const rootDir = worktree || directory
-  let toolHelper
-  try { ({ tool: toolHelper } = await import("@opencode-ai/plugin")) }
-  catch { dlog("@opencode-ai/plugin tool helper unavailable — registering a raw tool def") }
-
-  // One-line load banner (always on) so a restart visibly confirms the plugin loaded
-  // and the `workflow` tool is registered — and WARNS if this OpenCode build lacks the
-  // custom-tool helper (the silent "tool never appears" failure).
-  try {
-    const names = await listWorkflows()
-    const warn = toolHelper ? ""
-      : " — WARN: @opencode-ai/plugin 'tool' helper missing; the workflow tool may NOT register on this OpenCode version"
-    console.error(`[geneseed-workflow] loaded — tool 'workflow' registered, ${names.length} workflow(s) [${names.join(", ") || "none"}] from ${WORKFLOWS_DIR}${warn}`)
-  } catch (e) { console.error(`[geneseed-workflow] loaded but could not list workflows: ${e?.message || e}`) }
-
   // Normalize the `args` parameter. OpenCode's tool layer can deliver a structured
   // object param as a JSON STRING (or drop it) when the schema is untyped — so coerce
   // a string back to an object and reject non-object shapes to `{}`. Without this, the
@@ -185,22 +172,52 @@ export const GeneseedWorkflow = async (ctx) => {
     return summarize(name, result, stats, tracePath)
   }
 
+  return execute
+}
+
+// The `workflow` tool as the model sees it, on both majors.
+const TOOL_DESCRIPTION =
+  "Run a saved, code-driven Geneseed workflow that orchestrates subagents " +
+  "deterministically (parallel fan-out, find→verify pipeline, phased handoff). " +
+  "Call with no name to list available workflows."
+const NAME_DESCRIPTION = "saved workflow name; omit to list available"
+const ARGS_DESCRIPTION = "inputs passed to the workflow script as `args` (object, or a JSON object string)"
+
+// One-line load banner (always on) so a restart visibly confirms the plugin loaded and the
+// `workflow` tool is registered. tests/host_canary.mjs reads it as V1's proof of load.
+async function loadBanner(warn = "") {
+  try {
+    const names = await listWorkflows()
+    console.error(`[geneseed-workflow] loaded — tool 'workflow' registered, ${names.length} workflow(s) [${names.join(", ") || "none"}] from ${WORKFLOWS_DIR}${warn}`)
+  } catch (e) { console.error(`[geneseed-workflow] loaded but could not list workflows: ${e?.message || e}`) }
+}
+
+export const GeneseedWorkflow = async (ctx) => {
+  const { client, directory, worktree } = ctx
+  let toolHelper
+  try { ({ tool: toolHelper } = await import("@opencode-ai/plugin")) }
+  catch { dlog("@opencode-ai/plugin tool helper unavailable — registering a raw tool def") }
+
+  // Warn when this OpenCode build lacks the custom-tool helper (the silent "tool never
+  // appears" failure).
+  await loadBanner(toolHelper ? ""
+    : " — WARN: @opencode-ai/plugin 'tool' helper missing; the workflow tool may NOT register on this OpenCode version")
+
+  const execute = makeExecute({ client, directory, worktree })
+
   const def = {
-    description:
-      "Run a saved, code-driven Geneseed workflow that orchestrates subagents " +
-      "deterministically (parallel fan-out, find→verify pipeline, phased handoff). " +
-      "Call with no name to list available workflows.",
+    description: TOOL_DESCRIPTION,
     args: toolHelper
       ? {
-          name: toolHelper.schema.string().optional().describe("saved workflow name; omit to list available"),
+          name: toolHelper.schema.string().optional().describe(NAME_DESCRIPTION),
           // Keep this `any()` — it's the only param shape known to register cleanly on
           // this OpenCode build (record()/object schemas wedged tool registration → every
           // session message stuck "queued"). The provider may still deliver the object as
           // a JSON string or empty; normalizeArgs() in execute() recovers both cases.
-          args: toolHelper.schema.any().optional().describe("inputs passed to the workflow script as `args` (object, or a JSON object string)"),
+          args: toolHelper.schema.any().optional().describe(ARGS_DESCRIPTION),
         }
       : {
-          name: { type: "string", description: "saved workflow name; omit to list available" },
+          name: { type: "string", description: NAME_DESCRIPTION },
           args: { type: "object", description: "inputs passed to the workflow script as `args`" },
         },
     async execute(argv) { return execute(argv) },
@@ -209,4 +226,87 @@ export const GeneseedWorkflow = async (ctx) => {
   return { tool: { workflow: toolHelper ? toolHelper(def) : def } }
 }
 
-export default GeneseedWorkflow
+// ---- OpenCode 2 ----------------------------------------------------------------
+// `export default { id, server, setup }` serves V1 (>= 1.3.4) and V2 from one file — why, and
+// each V1 hook's V2 counterpart: adapters/opencode/HOW-OPENCODE-LOADS.md.
+//
+// V2 registers tools through `tool.transform` with a plain JSON-schema `input` (no
+// `@opencode-ai/plugin` helper — that package is `@opencode/plugin` there, and not
+// needed). The runtime (`_runtime.js`) and every saved workflow speak the V1 SDK client,
+// so `v2Client` presents that client's few calls over the V2 session domain instead of
+// forking the runtime:
+//   create  → session.create (a worktree directory becomes the session's location)
+//   prompt  → switchAgent/switchModel when asked, then session.prompt — which only
+//             admits the input on V2 — then session.wait for the loop to go idle, and the
+//             last assistant message read back from session.context
+//   messages → session.context, reshaped to V1's `{ info, parts }`
+//   delete  → session.remove
+function v2Message(m) {
+  if (m?.type === "assistant") {
+    return {
+      info: { role: "assistant", tokens: m.tokens },
+      parts: (m.content || []).filter((p) => p?.type === "text").map((p) => ({ type: "text", text: p.text })),
+    }
+  }
+  return { info: { role: m?.type }, parts: typeof m?.text === "string" ? [{ type: "text", text: m.text }] : [] }
+}
+function v2ModelRef(model) {
+  if (typeof model === "string" && model.includes("/")) {
+    const [providerID, ...rest] = model.split("/")
+    return { providerID, id: rest.join("/") }
+  }
+  const id = model?.id ?? model?.modelID
+  return model?.providerID && id ? { providerID: model.providerID, id } : null
+}
+function v2Client(ctx) {
+  const context = async (sid) => (await ctx.session.context({ sessionID: sid })) || []
+  return {
+    session: {
+      create: async ({ body, query } = {}) => ctx.session.create({
+        ...(body?.title ? { title: body.title } : {}),
+        ...(query?.directory ? { location: { directory: query.directory } } : {}),
+      }),
+      prompt: async ({ path: p, body } = {}) => {
+        const sessionID = p?.id
+        if (body?.agent) await ctx.session.switchAgent({ sessionID, agent: body.agent })
+        const model = v2ModelRef(body?.model)
+        if (model) await ctx.session.switchModel({ sessionID, model })
+        const text = (body?.parts || []).filter((x) => x?.type === "text").map((x) => x.text).join("\n")
+        await ctx.session.prompt({ sessionID, text })
+        await ctx.session.wait({ sessionID })
+        const last = (await context(sessionID)).filter((m) => m?.type === "assistant").pop()
+        return last ? v2Message(last) : null
+      },
+      messages: async ({ path: p } = {}) => (await context(p?.id)).map(v2Message),
+      delete: async ({ path: p } = {}) => ctx.session.remove({ sessionID: p?.id }),
+    },
+  }
+}
+
+async function setupV2(ctx) {
+  const directory = ctx?.location?.directory
+  const worktree = ctx?.location?.project?.directory
+  const execute = makeExecute({ client: v2Client(ctx), directory, worktree })
+  await loadBanner()
+  await ctx.tool.transform((editor) => {
+    editor.add({
+      name: "workflow",
+      description: TOOL_DESCRIPTION,
+      input: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: NAME_DESCRIPTION },
+          args: { description: ARGS_DESCRIPTION },
+        },
+      },
+      // A rejected promise here is a defect that fails the whole agent step, not the call:
+      // every failure comes back as text, as the V1 tool's do.
+      execute: async (input) => {
+        try { return { content: await execute(input) } }
+        catch (e) { return { content: `Workflow failed: ${e?.message || e}` } }
+      },
+    })
+  })
+}
+
+export default { id: "geneseed-workflow", server: GeneseedWorkflow, setup: setupV2 }

package/docs/guides/mcp-filesystem.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "Set up"
 description: "File access limited to the folders you list, and the placeholder path to replace."
 ---
-One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+One of the [MCP servers](mcp.md) Geneseed documents. Where each host keeps the config, and how to check the server connected, are on that page.
 
 [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) gives the agent file access limited to the folders you list, through `npx`. **The allowed folders are command-line arguments.** The server refuses any path outside them, so grant the narrowest set that works, not `$HOME` or `/`.
 
@@ -34,7 +34,7 @@ One of the [MCP server](mcp.md) presets. Where each host keeps the config, and h
 ```
 <!--/harness-->
 
-> **Replace the placeholder.** The preset ships with the literal path `/path/to/allowed/dir`. If you enable the server without changing it, the server runs but can reach nothing. This is the classic "the filesystem MCP sees nothing" problem.
+> **Replace the placeholder.** The blocks above end with a sample path. If you register the server without changing it, the server runs but can reach nothing. This is the classic "the filesystem MCP sees nothing" problem.
 
 ---
 

package/docs/guides/mcp-gitlab.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "Set up"
 description: "Merge requests, issues and CI from the agent: token scopes, the config block, a second instance."
 ---
-One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+One of the [MCP servers](mcp.md) Geneseed documents. Where each host keeps the config, and how to check the server connected, are on that page.
 
 > **Never commit a real token.** The presets ship with an empty `GITLAB_PERSONAL_ACCESS_TOKEN` and a sample filesystem path. Fill them in your own config, never in a tracked file.
 
@@ -59,7 +59,7 @@ You can also register it with `claude mcp add`.
 
 Keep the `/api/v4` suffix on the URL.
 
-**A second instance** (gitlab.com plus a self-hosted server, for example) is a copy of the same block under a new name, such as `gitlab-acme`, with its own `GITLAB_API_URL` and token. The preset covers the first instance only. You add the copy by hand.
+**A second instance** (gitlab.com plus a self-hosted server, for example) is a copy of the same block under a new name, such as `gitlab-acme`, with its own `GITLAB_API_URL` and token. You add the copy by hand, like the first.
 
 ---
 

package/docs/guides/mcp-markitdown.md

@@ -6,13 +6,13 @@ kind: "concept"
 section: "Set up"
 description: "Convert PDF and Office files to markdown: uvx or pipx, OCR extras, corporate TLS."
 ---
-One of the [MCP server](mcp.md) presets. Where each host keeps the config, and how to check the server connected, are on that page.
+One of the [MCP servers](mcp.md) Geneseed documents. Where each host keeps the config, and how to check the server connected, are on that page.
 
 [MarkItDown](https://github.com/microsoft/markitdown) (Microsoft) converts PDF, Word, Excel, PowerPoint and HTML to markdown. It exposes one tool, `convert_to_markdown(uri)`, which accepts `file:`, `http:`, `https:` and `data:` URIs.
 
 **1. Make the command resolve.**
 
-- **`uvx` (recommended, nothing to install).** If you have [uv](https://docs.astral.sh/uv/), `uvx markitdown-mcp` fetches and caches the server on first use. This is the command the preset uses.
+- **`uvx` (recommended, nothing to install).** If you have [uv](https://docs.astral.sh/uv/), `uvx markitdown-mcp` fetches and caches the server on first use. This is the command the blocks in [MCP servers](mcp.md) use.
 - **`pipx`.** Without uv, run `pipx install markitdown-mcp`, then use `markitdown-mcp` alone as the command (OpenCode: `["markitdown-mcp"]`; Claude: `"command": "markitdown-mcp"`, no args).
 
 ```
@@ -29,7 +29,7 @@ export UV_SYSTEM_CERTS=true      # older uv: UV_NATIVE_TLS=true
 # fallback: export SSL_CERT_FILE=/path/to/corporate-root-ca.pem
 ```
 
-**3. Register it**, with the console toggle or one of the blocks in [MCP servers](mcp.md). Then restart your agent.
+**3. Register it** by adding one of the blocks in [MCP servers](mcp.md) to your config. Then restart your agent.
 
 ---
 

package/docs/guides/mcp.md

@@ -4,15 +4,15 @@ order: 16
 title: "MCP servers"
 kind: "concept"
 section: "Set up"
-description: "Where MCP config lives for each host, the three presets, and how to check a server connected."
+description: "Where MCP config lives for each host, three servers worth adding, and how to check a server connected."
 ---
-MCP (Model Context Protocol) servers give your agent extra tools: converting a PDF, opening a merge request, reading files outside the repo. Geneseed ships three ready-made server **presets** (MarkItDown, GitLab and Filesystem) that you can switch on without writing JSON by hand.
+MCP (Model Context Protocol) servers give your agent extra tools: converting a PDF, opening a merge request, reading files outside the repo. Geneseed documents three servers worth adding (MarkItDown, GitLab and Filesystem), with the config block for each host. You add them to your config yourself: which servers you need depends on you and on your host.
 
 > **You already know this:** an MCP entry is a line in a Procfile. It names a command the agent starts on demand. Writing the line does not install the program behind it.
 
-Each preset is a *local* server, a command your agent launches when it needs the server. Registering a preset only points the agent at that command. **You** install the tool behind it (or let `uvx` or `npx` fetch it) and you supply any credentials.
+Each of the three is a *local* server, a command your agent launches when it needs the server. Registering one only points the agent at that command. **You** install the tool behind it (or let `uvx` or `npx` fetch it) and you supply any credentials.
 
-> **Never commit a real token.** The presets ship with an empty `GITLAB_PERSONAL_ACCESS_TOKEN` and a sample filesystem path. Fill them in your own config, never in a tracked file.
+> **Never commit a real token.** The blocks here carry an empty `GITLAB_PERSONAL_ACCESS_TOKEN` and a sample filesystem path. Fill them in your own config, never in a tracked file.
 
 ## Where the config lives
 
@@ -35,11 +35,11 @@ The same MarkItDown server in both shapes:
 { "mcpServers": { "markitdown": { "command": "uvx", "args": ["markitdown-mcp"] } } }
 ```
 
-**Toggle instead of editing.** In the web console (`geneseed web`), **Settings → MCP servers** adds, enables, disables or removes any preset in the right file, already in the right shape. Not sure which file that is? The **Harnesses** page shows the config path for each install, and `geneseed mcp` prints the same paths and lists the servers each install has wired, without starting anything.
+**See what is wired.** Geneseed never writes these files. The web console (`geneseed web`) shows, for each active install, its config path and the servers it holds, enabled or disabled, with a button that opens the folder so you can edit the file. `geneseed mcp` prints the same in a terminal, without starting anything.
 
-The reference OpenCode config ships MarkItDown enabled and the GitLab and Filesystem entries disabled, so a merge never switches on a server that has no credentials yet. Fill in the blanks, then switch the server on.
+The reference OpenCode config ships MarkItDown enabled and the GitLab and Filesystem entries disabled, so a merge never switches on a server that has no credentials yet. Fill in the blanks, then set `enabled` to `true`.
 
-## The presets
+## Three servers worth adding
 
 - [MarkItDown](mcp-markitdown.md): converts PDF, Word, Excel, PowerPoint and HTML to markdown.
 - [GitLab](mcp-gitlab.md): repository, merge request, issue and CI tools over the GitLab API.

package/docs/guides/project-context.md

@@ -99,7 +99,7 @@ A line is simply left out when its source is missing.
 
 ## How OpenCode delivers it
 
-By default, the plugin delivers the context invisibly. It prepends the context to each request through OpenCode's experimental `experimental.chat.messages.transform` hook, so nothing appears in the conversation. Because it is re-sent with every request, the context also survives compaction. If your OpenCode build lacks that hook, the plugin notices and falls back to posting a visible `PROJECT CONTEXT` message.
+By default, the plugin delivers the context invisibly. It prepends the context to each request through OpenCode's experimental `experimental.chat.messages.transform` hook, so nothing appears in the conversation. Because it is re-sent with every request, the context also survives compaction. If your OpenCode build lacks that hook, the plugin notices and falls back to posting a visible `PROJECT CONTEXT` message. On OpenCode 2 the same invisible delivery goes through its stable per-request `context` hook, so no fallback is needed.
 
 - `GENESEED_CONTEXT_VISIBLE=1` always shows the visible block, so you can see what the agent received.
 - `GENESEED_CONTEXT_INJECT=off` turns injection off. The agent then relies on the instruction in `AGENT.md` to read the docs itself.

package/docs/guides/uninstall.md

@@ -28,6 +28,8 @@ Each install keeps a manifest, a list of the files Geneseed wrote. **Uninstall d
 - **OpenCode per repo:** `AGENT.md`, `.opencode/`, `laws/`, `agents/`, `skills/`, and the `instructions` entry in `opencode.json`.
 - **Claude Code, Bob, OpenClaude:** `agents/`, `skills/`, the marker files, Geneseed's managed block in the instructions file (`CLAUDE.md` or `AGENTS.md`), and Geneseed's own hooks and exclusions in `settings.json`. Your own settings keys and hooks stay.
 
+**A file Geneseed wrote that you have since edited is kept.** The manifest records each file's fingerprint, so uninstall can tell your edit apart from Geneseed's copy. It leaves the edited file in place, names it (`kept 1 file(s) you edited: ...`), and finishes the uninstall anyway: the file is yours now, and no later rebuild touches it. To delete edited files too, pass `--force`. Changing only the line endings, as a git checkout on another system does, is not an edit.
+
 It also removes the install's row from the registry of installs. Start a new session in your tool afterwards so it stops loading the old files.
 
 ## What it keeps

package/docs/guides/upgrade.md

@@ -48,6 +48,8 @@ A rebuild only replaces files the install's manifest says Geneseed owns. It leav
 
 The agent can refine its own deployed agent and skill files as it works, and so can you. A rebuild would overwrite those edits, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
 
+A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
+
 To see the drift yourself, or to export it on demand:
 
 ```

package/docs/reference/opencode-plugins.md

@@ -14,6 +14,15 @@ Every plugin installs in the same step as the rest of the harness: `geneseed set
 
 Every plugin swallows its own errors — none can block or crash a session. Each plugin's page lists the variables that tune it.
 
+## OpenCode 2
+
+The same files work on OpenCode 1 (1.3.4 or newer) and OpenCode 2. OpenCode 2 rewrote the plugin API, and each plugin carries both halves. You don't need to configure anything. Two differences show on OpenCode 2:
+
+- **A guard block shows up as a failed tool call.** The call never runs. The model gets an error that starts with `[geneseed-guard] blocked:` and gives the reason.
+- **The Activity view shows no todo list or files-touched count.** OpenCode 2 publishes no event for either.
+
+If a plugin seems silent on OpenCode 2, check that `~/.config/opencode/plugins/` holds the current files. Copies from before this change fail to load with *"Plugin must export a default definition with an id and an effect or setup function"*. Running `geneseed rebuild-all` replaces them.
+
 ## The plugins
 
 - [geneseed-context](plugin-context.md): Puts your project docs, rules, profile, memory index and wiki in front of the agent.

package/docs/token-footprint.md

@@ -93,7 +93,7 @@ until 2026-09 it did, and the whole harness was paid twice per session.
   `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
   Code and Bob then drop its description from the always-on skill metadata and
   only `/name` opens it. The three teaching skills (`teach`, `quiz`, `learn-mode`)
-  and `herdr` carry it today.
+  carry it today.
 - **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
   ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
   on OpenCode — never in the model's catalogue, so a rename or merge is free.

package/docs/understand/take-it-out.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "On your machine"
 description: "What geneseed uninstall removes, and what it keeps for you."
 ---
-`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
+`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. A file Geneseed wrote that you have since edited stays too, and becomes yours; add `--force` to delete edited files as well. See [Uninstall](../guides/uninstall.md).
 
 ---
 

package/harness.config.json

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