dotmd-cli 0.74.5 → 0.75.0

package/README.md

@@ -23,9 +23,23 @@ npx dotmd-cli init          # try it without installing
 Maintainer release automation is POSIX-only because it uses Bash and POSIX
 command-line tools. The published Node.js CLI remains cross-platform.
 
+### Agent host setup
+
+The CLI alone gives an agent no orientation and no session identity. Install the
+integration for whichever host you run:
+
+```bash
+dotmd install             # what's installed for each host
+dotmd install claude      # Claude Code plugin (marketplace + plugin)
+dotmd install opencode    # OpenCode plugin (one auto-discovered file)
+dotmd doctor --session    # what identity dotmd sees here, and from where
+```
+
+Both are one-time and global; `dotmd update` keeps them in step with the CLI.
+
 ### Claude Code Plugin
 
-The recommended Claude Code setup is the dotmd plugin:
+`dotmd install claude` runs the two steps below for you. From inside a session:
 
 ```text
 /plugin marketplace add reowens/dotmd
@@ -36,6 +50,23 @@ The plugin provides SessionStart and SubagentStart orientation, a PreToolUse
 guard, the canonical workflow skill, and `/plans`, `/docs`, `/prompts`, and
 `/baton` commands.
 
+### OpenCode Plugin
+
+`dotmd install opencode` writes one plugin file into OpenCode's global config
+directory, where OpenCode auto-discovers it — no `opencode.json` edit. It
+supplies the two things the CLI cannot get on its own:
+
+- **Per-session plan ownership.** OpenCode exports no session id to a tool
+  shell. Without the plugin, dotmd falls back to `OPENCODE_PID`, which names the
+  OpenCode *process* — so every session in one OpenCode instance shares an
+  identity and can release the others' in-session plans.
+- **A session-start briefing**, the equivalent of Claude Code's SessionStart
+  hook. OpenCode's Claude Code compatibility covers skills and the system
+  prompt, not hooks, so nothing else runs `dotmd hud`.
+
+Restart OpenCode after installing. The file is version-stamped; a `dotmd.js`
+without that stamp is treated as hand-authored and is never overwritten.
+
 The plugin requires a global CLI install because its hooks resolve `dotmd` from
 `PATH`. A project devDependency is useful for npm scripts but does not put the
 CLI on the hook's `PATH`.

package/assets/opencode/plugin.js

@@ -0,0 +1,97 @@
+// dotmd's OpenCode integration. Installed by `dotmd install opencode`, which
+// copies this file (with a version banner prepended) to the OpenCode plugin
+// directory, where OpenCode auto-discovers it — it globs
+// `{plugin,plugins}/*.{ts,js}` under `.opencode/` and the global config dir, so
+// no `opencode.json` edit is needed.
+//
+// TWO CONSTRAINTS, both load-bearing:
+//
+//  1. EXACTLY ONE EXPORT. OpenCode treats every export of a plugin module as a
+//     plugin factory and throws `Plugin export is not a function` on anything
+//     that isn't one — so an exported helper wouldn't just be untidy, it would
+//     be *called* as a second plugin. Helpers stay module-local.
+//
+//  2. NO HOOK MAY THROW. OpenCode awaits hook callbacks inside the request it
+//     is serving; a rejected promise fails the user's chat turn. Every hook
+//     body is wrapped, and a failure degrades to "dotmd does nothing here"
+//     rather than to a broken session.
+//
+// Runs under Bun inside the OpenCode process. Node builtins only, no deps.
+
+import { execFile } from 'node:child_process';
+
+// The primer is a nicety; identity is a correctness invariant. They are split
+// across two hooks deliberately: `shell.env` is stable API, while
+// `experimental.chat.system.transform` may be renamed by OpenCode. If it is,
+// priming stops and ownership keeps working — the failure lands on the half
+// that can afford it.
+const PRIMER_TTL_MS = 60_000;
+const PRIMER_TIMEOUT_MS = 5_000;
+
+function dotmdExecutable() {
+  return process.platform === 'win32' ? 'dotmd.cmd' : 'dotmd';
+}
+
+function runHud(directory) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = value => { if (!settled) { settled = true; resolve(value); } };
+    try {
+      execFile(dotmdExecutable(), ['hud'], {
+        cwd: directory,
+        timeout: PRIMER_TIMEOUT_MS,
+        windowsHide: true,
+        env: { ...process.env, NO_COLOR: '1' },
+      }, (error, stdout) => done(error ? '' : (stdout ?? '').trim()));
+    } catch {
+      // `dotmd` not on PATH, spawn refused — no primer, no noise.
+      done('');
+    }
+  });
+}
+
+export default async function dotmdOpencodePlugin({ directory }) {
+  // Keyed by session so a subagent session primes independently, the way
+  // SubagentStart does under Claude Code.
+  const primers = new Map();
+
+  async function primerFor(sessionId) {
+    const key = sessionId ?? '';
+    const cached = primers.get(key);
+    // Refreshed on a TTL rather than cached for the session's life: OpenCode
+    // rebuilds the system prompt every turn, so a once-only push would reach
+    // only the first request — and a never-refreshed one would keep announcing
+    // a pending prompt this session already consumed.
+    if (cached && Date.now() - cached.at < PRIMER_TTL_MS) return cached.text;
+    const text = await runHud(directory);
+    primers.set(key, { text, at: Date.now() });
+    return text;
+  }
+
+  return {
+    // Ownership identity. OpenCode sets no session-id variable of its own, and
+    // `OPENCODE_PID` — what dotmd falls back to without this plugin — names the
+    // OpenCode *process*, so every session in one TUI shares it and can release
+    // the others' plans. This is the only place the real session id is
+    // available to a tool shell.
+    'shell.env': async (input, output) => {
+      try {
+        if (input?.sessionID) output.env.DOTMD_SESSION_ID = `opencode:${input.sessionID}`;
+        // The OpenCode server process hosts the session and outlives every tool
+        // shell, so it is the process whose liveness answers "is this claim's
+        // owner still there?" — `dotmd doctor --claims` probes exactly this.
+        output.env.DOTMD_SESSION_PID = String(process.pid);
+      } catch { /* never break a shell over this */ }
+    },
+
+    // Session priming — the equivalent of the SessionStart hook that runs
+    // `dotmd hud` under Claude Code. Silent outside a dotmd repo (hud prints
+    // nothing and exits 0), so this is inert in unrelated projects.
+    'experimental.chat.system.transform': async (input, output) => {
+      try {
+        const text = await primerFor(input?.sessionID);
+        if (text) output.system.push(text);
+      } catch { /* priming is best-effort */ }
+    },
+  };
+}

package/bin/dotmd.mjs

@@ -142,6 +142,44 @@ guard entirely with DOTMD_GUARD=0. Read the log with \`dotmd misuse\`; when one
 rule trips ≥3× in 7 days in a repo, \`dotmd hud\` opens the next session there
 with a one-line recap naming the habit to break.`,
 
+  install: `dotmd install [<host>] — install dotmd's integration into an agent host
+
+  dotmd install                report what is installed for each known host
+  dotmd install claude         install the Claude Code plugin (marketplace + plugin)
+  dotmd install opencode       install/refresh the OpenCode plugin (global config dir)
+  dotmd install <host> --remove
+  dotmd install opencode --path <dir>   write to a specific plugin directory
+  dotmd install opencode --force        overwrite a dotmd.js dotmd did not write
+
+The CLI on its own gives an agent no orientation and no session identity. Each
+host gets that a different way:
+
+  claude    Drives \`claude plugin marketplace add ${'reowens/dotmd'}\` +
+            \`claude plugin install dotmd@dotmd\`. This is the FIRST install;
+            \`dotmd update\` only refreshes a plugin already present (it skips
+            with "plugin not installed"), and the README's slash commands only
+            work from inside a session. Without the \`claude\` CLI on PATH the
+            two in-session commands are printed instead.
+
+  opencode  Writes one auto-discovered plugin file. OpenCode has no plugin
+            registry but globs \`{plugin,plugins}/*.{ts,js}\` under its global
+            config dir, so no opencode.json edit is needed. It supplies two
+            things the CLI cannot get on its own:
+              - Per-session ownership identity. OpenCode exports no session id
+                to a tool shell, so without it every session in one OpenCode
+                process shares one identity and can release the others'
+                in-session plans.
+              - The \`dotmd hud\` primer at session start, the equivalent of
+                Claude Code's SessionStart hook. OpenCode's Claude Code
+                compatibility covers skills and the system prompt — not hooks —
+                so nothing else runs it.
+            The file is version-stamped and refreshed by \`dotmd update\`. A
+            \`dotmd.js\` without that stamp is treated as hand-authored and is
+            never overwritten or removed without --force.
+
+Writing outside the repo is why this is an explicit verb: \`dotmd doctor\`
+reports a missing integration but never installs one.`,
+
   update: `dotmd update — update the dotmd CLI and the Claude Code plugin together
 
   dotmd update                 npm i -g dotmd-cli  +  claude plugin update dotmd@dotmd
@@ -232,6 +270,7 @@ Create & Export:
 
 Setup:
   init                              Create starter config + docs directory
+  install [opencode]                Install the agent-host integration (no arg = status)
   update [--check|--cli-only|--plugin-only]  Update the CLI + Claude Code plugin (--check reports skew, no network)
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
   help statuses                     Full status vocabulary + unstuck-actions + transitions
@@ -464,8 +503,9 @@ another session's work.
 a unique bare slug / basename across the doc roots (\`set paused auth-revamp\`).
 Ambiguous slugs error with the candidate list instead of guessing.
 When the path is omitted, exactly one plan must be owned by this session.
-Claude Code and OpenCode session IDs are recognized automatically. Other hosts
-must set DOTMD_SESSION_ID; anonymous ownership mutations fail closed.
+Claude Code session IDs are recognized automatically, as is OpenCode (via
+OPENCODE_PID — per OpenCode process, not per session). Other hosts must set
+DOTMD_SESSION_ID; anonymous ownership mutations fail closed.
 Pickup hooks use at-least-once delivery with a stable operationId; hook side
 effects must deduplicate that ID.
 
@@ -743,6 +783,15 @@ Modes:
                          another machine — that are older than the duration.
                          That threshold is your judgement, not dotmd's: it
                          cannot tell a dead session from a slow one.
+  --session              Read-only: what session identity dotmd resolved, from
+                         which environment variable, and whether it names THIS
+                         session or something coarser that its siblings share
+                         (a host process, a terminal) — sessions sharing an id
+                         can release each other's plans. Also reports whether
+                         the current host's integration is installed. Run this
+                         when a verb says "No authoritative session identity",
+                         or on any host dotmd has never been tried on.
+  --session --json       Machine-readable identity + host-integration state.
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -1724,6 +1773,7 @@ async function main() {
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config, { dryRun }); return; }
   if (command === 'update') { const { runUpdate } = await import('../src/update.mjs'); runUpdate(restArgs, config, { dryRun }); return; }
+  if (command === 'install') { const { runInstall } = await import('../src/install.mjs'); runInstall(restArgs, config, { dryRun }); return; }
   if (command === 'misuse') { const { runMisuse } = await import('../src/misuse-read.mjs'); runMisuse(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup' || command === 'unpickup' || command === 'release' || command === 'finish') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.74.5",
+  "version": "0.75.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
   "files": [
     "bin/",
     "src/",
+    "assets/",
     "scripts/postinstall.mjs",
     "dotmd.config.example.mjs"
   ],

package/scripts/postinstall.mjs

@@ -24,6 +24,16 @@ try {
     } catch { return false; }
   })();
 
+  // OpenCode's integration is a file dotmd writes, and nothing else would ever
+  // mention it — an OpenCode user who installs only the CLI gets no primer and
+  // a process-scoped session identity, silently. One line, never an install.
+  const hasOpencode = (() => {
+    try {
+      const cmd = process.platform === 'win32' ? 'where' : 'which';
+      return spawnSync(cmd, ['opencode'], { encoding: 'utf8' }).status === 0;
+    } catch { return false; }
+  })();
+
   if (process.env.DOTMD_AUTO_PLUGIN_UPDATE === '1' && hasClaude) {
     spawnSync('claude', ['plugin', 'update', 'dotmd@dotmd'], { stdio: 'ignore', timeout: 60000 });
     process.stdout.write('dotmd: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n');
@@ -35,6 +45,9 @@ try {
       : 'dotmd CLI installed.';
     process.stdout.write(`${nudge}\n`);
   }
+  if (hasOpencode) {
+    process.stdout.write('dotmd: OpenCode detected — run `dotmd install opencode` for per-session plan ownership and a session-start briefing.\n');
+  }
 } catch {
   // Best effort only — never break the install.
 }

package/src/baton.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn } from './util.mjs';
@@ -206,6 +206,26 @@ export async function runBaton(argv, config, opts = {}) {
   }
   if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
+  // A release status can FILE the plan into a bucket (`lifecycle.filedStatuses`,
+  // e.g. paused → docs/plans/held/). The prompt is created inside the same
+  // transaction as that move, so its `plan:` link necessarily holds the
+  // pre-move path and is stale the instant it lands. The move's own reference
+  // rewrite does not cover it: `plan` is deliberately not a `referenceFields`
+  // entry, so nothing validates or repoints it. Retarget it here.
+  if (!dryRun && promptRepoPath && archiveResult?.newRepoPath && archiveResult.newRepoPath !== repoPath) {
+    const promptPath = path.join(config.repoRoot, promptRepoPath);
+    try {
+      const { frontmatter, body } = extractFrontmatter(readFileSync(promptPath, 'utf8'));
+      // Rewritten in place rather than through replaceFrontmatterField, which
+      // always emits a folded block scalar — right for prose fields, wrong for
+      // a path every other prompt carries on one line. Baton wrote this line
+      // itself moments ago, so the single-line form is guaranteed.
+      const rewritten = frontmatter.replace(/^plan:[ \t]*\S.*$/m, `plan: ${archiveResult.newRepoPath}`);
+      if (rewritten !== frontmatter) writeFileSync(promptPath, `---\n${rewritten}\n---\n${body}`, 'utf8');
+    }
+    catch (err) { warn(`Saved the prompt, but could not repoint its plan link to ${archiveResult.newRepoPath}: ${err.message}`); }
+  }
+
   const normalizeRepoPath = candidate => {
     if (!candidate) return null;
     return path.isAbsolute(candidate) ? toRepoPath(candidate, config.repoRoot) : candidate;

package/src/commands.mjs

@@ -114,6 +114,9 @@ const definitions = [
   command('export', mutates('external output path intentionally unrestricted'), 'mutate', [form('[file]', { args: positionals(0, 1), options: [value('--format'), value('--output'), value('--status'), value('--module'), value('--root'), value('--type')] })]),
   command('guard', mutates('global misuse log; no managed document writes'), 'mutate', [form('')]),
   command('update', mutates('global CLI and plugin installation state'), 'mutate', [form('', { options: [flag('--check'), flag('--cli-only'), flag('--plugin-only')] })]),
+  command('install', mutates('agent-host plugin directory outside the repo'), 'mutate', [
+    form('[host]', { args: positionals(0, 1), options: [flag('--remove'), flag('--force'), flag('--json'), value('--path')] }),
+  ]),
   command('status', mutates('managed source and same-root destination'), 'mutate', [form('<file> [status]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
   command('set', mutates('managed source and same-root destination'), 'mutate', [form('<status> [file]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
   command('ship', mutates('repository release/index paths and global release tooling'), 'mutate', [form('[patch|minor|major]', { args: positionals(0, 1) })]),
@@ -134,7 +137,7 @@ const definitions = [
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),
   command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
-  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
+  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
     form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),

package/src/doctor.mjs

@@ -7,15 +7,16 @@ import { runSet, runTouch } from './lifecycle.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { writeRenderedIndex } from './index-file.mjs';
 import { renderCheck, renderManualFixes } from './render.mjs';
-import { bold, dim, green, yellow } from './color.mjs';
+import { bold, dim, green, red, yellow } from './color.mjs';
 import { checkClaudeCommands, removeGeneratedSlashCommands } from './claude-commands.mjs';
 import { checkSkillDrift } from './skill-drift.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
 import { normalizeEol } from './frontmatter.mjs';
-import { die, relTime, toRepoPath } from './util.mjs';
+import { die, dotmdVersion, relTime, toRepoPath } from './util.mjs';
 import { inspectTransactions, resolveTransactions } from './atomic-mutation.mjs';
+import { describeSessionIdentity, opencodeStatus } from './host-integration.mjs';
 import { availableSessionId, releaseVanishedPlanClaim, surveyOwnershipClaims } from './pickup.mjs';
 
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
@@ -209,6 +210,29 @@ async function runDoctorClaims(argv, config, opts = {}) {
   }
 }
 
+// Read-only: what session identity does dotmd see, and is the current host's
+// integration installed? Never writes — installing lives behind `dotmd install`
+// because it touches state outside the repo.
+function runDoctorSession(argv) {
+  const identity = describeSessionIdentity({ version: dotmdVersion() });
+  const oc = opencodeStatus({ version: dotmdVersion() });
+  if (argv.includes('--json')) {
+    process.stdout.write(JSON.stringify({ identity, hosts: { opencode: oc } }, null, 2) + '\n');
+    return;
+  }
+  process.stdout.write(bold('Session identity\n'));
+  const mark = identity.scope === 'session' ? green('✓') : identity.id ? yellow('!') : red('✗');
+  process.stdout.write(`  ${mark} ${identity.id ?? dim('none')}\n`);
+  process.stdout.write(`    ${dim(identity.summary)}\n`);
+  for (const line of identity.advice) process.stdout.write(`    → ${line}\n`);
+
+  process.stdout.write('\n' + bold('Host integration\n'));
+  if (oc.foreign) process.stdout.write(`  ${yellow('!')} opencode: a dotmd.js dotmd did not write — ${oc.path}\n`);
+  else if (!oc.exists) process.stdout.write(`  ${dim('·')} opencode: not installed — ${dim(oc.path)}\n`);
+  else process.stdout.write(`  ${oc.stale ? yellow('!') : green('✓')} opencode: ${oc.version}${oc.stale ? ` (CLI is ${dotmdVersion()} — run \`dotmd update\`)` : ''}\n`);
+  process.stdout.write(dim('  Claude Code ships as a plugin — `dotmd install` reports both hosts.\n'));
+}
+
 export function runDoctor(argv, config, opts = {}) {
   if (argv.includes('--project')) {
     runDoctorProject(config, { json: argv.includes('--json') });
@@ -237,6 +261,10 @@ export function runDoctor(argv, config, opts = {}) {
   if (argv.includes('--claims')) {
     return runDoctorClaims(argv, config, opts);
   }
+  if (argv.includes('--session')) {
+    runDoctorSession(argv);
+    return;
+  }
 
   const { dryRun, testHooks } = opts;
   // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run
@@ -325,6 +353,18 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('\n' + bold('Closeout guidance') + '\n');
     process.stdout.write(manual);
   }
+
+  // Not a numbered step and never auto-fixed: installing touches state outside
+  // the repo, which is `dotmd install`'s job. Doctor's part is making sure a
+  // degraded identity is something you're told about rather than something you
+  // find out when a verb fails. Silent when there is nothing to say.
+  const identity = describeSessionIdentity({ version: dotmdVersion() });
+  if (identity.advice.length) {
+    process.stdout.write('\n' + bold('Session identity') + '\n');
+    process.stdout.write(`${yellow('!')} ${identity.summary}\n`);
+    for (const line of identity.advice) process.stdout.write(dim(`  → ${line}\n`));
+    process.stdout.write(dim('  `dotmd doctor --session` for the full picture.\n'));
+  }
 }
 
 function readJsonIfPresent(filePath) {

package/src/glossary.mjs

@@ -136,7 +136,7 @@ function renderEntry(entry, index, allEntries) {
   if (relatedDocs.length > 0) {
     lines.push('');
 
-    // Module entry point (the main module doc, e.g. situ.md)
+    // Module entry point (the main module doc, e.g. ledger.md)
     const entryPoint = relatedDocs.find(d =>
       d.root?.includes('modules') && path.basename(d.path, '.md') === entry.term.toLowerCase()
     );

package/src/host-integration.mjs

@@ -0,0 +1,211 @@
+// Installing dotmd's integration into agent hosts other than Claude Code.
+//
+// Claude Code gets its integration through a real plugin (`plugins/dotmd/`,
+// installed by `claude plugin`). OpenCode has no equivalent registry, but it
+// auto-discovers plugin files: it globs `{plugin,plugins}/*.{ts,js}` under the
+// global config dir and under a project's `.opencode/`, with no config entry
+// needed. So the integration ships as one generated file.
+//
+// It goes in the GLOBAL config dir, not per-repo. dotmd retired per-repo
+// generated scaffolding once already (`.claude/commands`, see
+// claude-commands.mjs) because a file copied into every repo drifts from the
+// CLI that wrote it. One global file covers every repo and is refreshed by
+// `dotmd update` in lockstep with the CLI.
+//
+// Writing outside the repo is why this is an explicit verb. `dotmd doctor`
+// reports that the integration is missing and names the command; it never
+// installs. Passive commands touch nothing.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hostSessionSource } from './util.mjs';
+
+export const GENERATED_MARKER = 'dotmd-generated:';
+const PLUGIN_FILENAME = 'dotmd.js';
+const ASSET = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'assets', 'opencode', 'plugin.js');
+
+// OpenCode's own resolution order for its global config directory. Verified
+// against the shipped binary: `OPENCODE_CONFIG_DIR` is an explicit override it
+// consults directly, and the default is the XDG location.
+export function opencodeConfigDir(env = process.env, homedir = os.homedir()) {
+  const explicit = env.OPENCODE_CONFIG_DIR?.trim();
+  if (explicit) return path.resolve(explicit);
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  return xdg ? path.join(path.resolve(xdg), 'opencode') : path.join(homedir, '.config', 'opencode');
+}
+
+// Both spellings are globbed, so an existing one is adopted rather than
+// creating a second plugin directory beside the user's own plugins.
+export function opencodePluginDir(configDir) {
+  for (const name of ['plugin', 'plugins']) {
+    const candidate = path.join(configDir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return path.join(configDir, 'plugin');
+}
+
+export function opencodePluginPath(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), dir } = opts;
+  if (dir) return path.join(path.resolve(dir), PLUGIN_FILENAME);
+  return path.join(opencodePluginDir(opencodeConfigDir(env, homedir)), PLUGIN_FILENAME);
+}
+
+function banner(version) {
+  return [
+    `// ${GENERATED_MARKER}${version}`,
+    '// Generated by `dotmd install opencode`. Refreshed by `dotmd update`.',
+    '// Hand edits are overwritten — remove with `dotmd install opencode --remove`.',
+    '',
+  ].join('\n');
+}
+
+export function renderOpencodePlugin(version) {
+  return banner(version) + readFileSync(ASSET, 'utf8');
+}
+
+// The version a generated file was written by, or null when the file is absent
+// or carries no dotmd banner. A file without the banner is the user's own and
+// is never written or removed — same rule the retired slash-command scaffolding
+// followed.
+export function installedVersion(filePath) {
+  let contents;
+  try { contents = readFileSync(filePath, 'utf8'); } catch { return null; }
+  const marker = contents.indexOf(GENERATED_MARKER);
+  if (marker < 0) return null;
+  const rest = contents.slice(marker + GENERATED_MARKER.length);
+  return rest.split('\n', 1)[0].trim() || null;
+}
+
+export function opencodeStatus(opts = {}) {
+  const { version, ...rest } = opts;
+  const filePath = opencodePluginPath(rest);
+  const exists = existsSync(filePath);
+  const installed = exists ? installedVersion(filePath) : null;
+  return {
+    path: filePath,
+    exists,
+    version: installed,
+    // Present but unmarked: the user put a `dotmd.js` there themselves.
+    foreign: exists && installed === null,
+    stale: installed !== null && version !== undefined && installed !== version,
+  };
+}
+
+// Is OpenCode plausibly in use on this machine? Used only to decide whether to
+// mention the integration — never to install anything.
+export function opencodeDetected(opts = {}) {
+  const { env = process.env, homedir = os.homedir() } = opts;
+  if (env.OPENCODE || env.OPENCODE_PID) return true;
+  const configDir = opencodeConfigDir(env, homedir);
+  if (!existsSync(configDir)) return false;
+  try { return readdirSync(configDir).length > 0; } catch { return false; }
+}
+
+export function installOpencodePlugin(opts = {}) {
+  const { version, dryRun = false, force = false, ...rest } = opts;
+  const status = opencodeStatus({ version, ...rest });
+  if (status.foreign && !force) {
+    return { ...status, action: 'refused', reason: 'a dotmd.js without a dotmd banner is already there — it was not written by dotmd' };
+  }
+  if (status.exists && !status.stale && !status.foreign) {
+    return { ...status, action: 'current' };
+  }
+  const action = status.exists ? 'updated' : 'installed';
+  if (!dryRun) {
+    mkdirSync(path.dirname(status.path), { recursive: true });
+    writeFileSync(status.path, renderOpencodePlugin(version), 'utf8');
+  }
+  return { ...status, action, version };
+}
+
+// What identity does dotmd actually see here, and can it tell this session
+// apart from its siblings? This report exists because the OpenCode breakage was
+// invisible until a verb failed: dotmd looked for variables OpenCode never set,
+// and nothing surfaced that until `use` refused to run. Anyone on any host can
+// now check what dotmd resolved instead of discovering it through a failure.
+export function describeSessionIdentity(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), version } = opts;
+  const source = hostSessionSource(env);
+  const opencode = opencodeStatus({ env, homedir, version });
+  const underOpencode = Boolean(env.OPENCODE || env.OPENCODE_PID);
+
+  if (!source) {
+    return {
+      id: null, scope: 'none', source: null, host: null,
+      summary: 'no session identity — `use`, `set`, `baton` and `archive` fail closed',
+      advice: underOpencode
+        ? ['dotmd install opencode', 'or set DOTMD_SESSION_ID for this shell']
+        : ['set DOTMD_SESSION_ID for this shell or host session', 'known hosts: dotmd install'],
+    };
+  }
+
+  const advice = [];
+  // The distinction that matters: a process- or terminal-scoped id is shared by
+  // every session under it, so those sessions can release each other's plans.
+  if (source.scope === 'process' && source.host === 'OpenCode') {
+    advice.push(opencode.exists
+      // The plugin is there but this shell was spawned before it loaded, so it
+      // still carries the old identity — say so rather than leave a warning
+      // marker with no explanation.
+      ? 'restart OpenCode — this session predates the installed integration'
+      : 'dotmd install opencode  — for a per-session identity');
+  } else if (source.scope === 'terminal') {
+    advice.push('every agent session in this terminal shares this id — set DOTMD_SESSION_ID per session');
+  }
+  return {
+    id: source.id,
+    scope: source.scope,
+    source: source.variable,
+    host: source.host,
+    summary: source.scope === 'session'
+      ? `per-session identity from ${source.variable}`
+      : `${source.scope}-scoped identity from ${source.variable} — sessions sharing it can release each other's plans`,
+    advice,
+  };
+}
+
+// --- Claude Code -----------------------------------------------------------
+//
+// Claude Code has a real plugin registry, so dotmd drives `claude plugin`
+// rather than writing files. What it lacked was any CLI path to the FIRST
+// install: `dotmd update` deliberately skips the plugin step when nothing is
+// installed ("dotmd plugin not installed"), and the README's two slash commands
+// only work from inside a session. So a user who installed the CLI from npm had
+// no way to discover, from the CLI, that the plugin exists.
+
+export const CLAUDE_MARKETPLACE = 'reowens/dotmd';
+export const CLAUDE_PLUGIN_ID = 'dotmd@dotmd';
+
+// Pure planner, mirroring planUpdate: the orchestration is unit-testable and
+// the side effects stay in the caller.
+export function planClaudeInstall({ installed, hasClaude, remove = false } = {}) {
+  if (remove) {
+    if (!installed) return [{ kind: 'skip', reason: 'dotmd plugin is not installed' }];
+    return hasClaude
+      ? [{ kind: 'run', cmd: ['claude', 'plugin', 'uninstall', installed.id] }]
+      : [{ kind: 'manual', lines: [`/plugin uninstall ${installed.id}`] }];
+  }
+  if (installed) return [{ kind: 'skip', reason: `dotmd plugin already installed (${installed.version ?? 'unknown version'})` }];
+  // The marketplace has to be registered before the plugin resolves; adding one
+  // already present is a no-op, so this stays safe to re-run.
+  if (!hasClaude) {
+    return [{ kind: 'manual', lines: [`/plugin marketplace add ${CLAUDE_MARKETPLACE}`, `/plugin install ${CLAUDE_PLUGIN_ID}`] }];
+  }
+  return [
+    { kind: 'run', cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] },
+    { kind: 'run', cmd: ['claude', 'plugin', 'install', CLAUDE_PLUGIN_ID] },
+  ];
+}
+
+export function removeOpencodePlugin(opts = {}) {
+  const { dryRun = false, force = false, ...rest } = opts;
+  const status = opencodeStatus(rest);
+  if (!status.exists) return { ...status, action: 'absent' };
+  if (status.foreign && !force) {
+    return { ...status, action: 'refused', reason: 'not a dotmd-generated file' };
+  }
+  if (!dryRun) rmSync(status.path, { force: true });
+  return { ...status, action: 'removed' };
+}