opencode-diane 0.0.5

package/dist/utils/file-log.js

@@ -0,0 +1,215 @@
+/**
+ * Rich, structured logging to disk. A second log sink alongside
+ * OpenCode's own session log channel — the existing `log()` callback
+ * keeps piping human-readable lines into OpenCode's UI, and this
+ * module mirrors them (plus structured events) to a JSONL file under
+ * `os.tmpdir()/opencode-diane/` by default, or `$OPENCODE_DIANE_LOG_DIR`
+ * if set (use the env var when running inside Docker — point it at a
+ * mounted volume and your logs survive the container). The file is
+ * per-session and per-PID, so parallel OpenCode sessions never
+ * interleave; each line is a standalone JSON object so the whole file
+ * is greppable AND `jq`-able.
+ *
+ * Why not into OpenCode's log alone:
+ *   - OpenCode's log is human-oriented (single-line strings) and is
+ *     scoped to a session's UI panel — easy to lose between turns.
+ *   - For debugging the plugin itself (a flush that took 200ms, an
+ *     ingester that skipped half its commits, an eviction that fired
+ *     under budget) you want timestamped, machine-readable, persistent
+ *     records you can keep across sessions and diff.
+ *
+ * Why JSONL not a text log:
+ *   - One line per record, never multi-line, so `tail -f` works.
+ *   - Each line is valid JSON, so `jq '.event == "ingest.git"'` works.
+ *   - Streams append cleanly even from multiple writers (each line is
+ *     atomic on POSIX up to PIPE_BUF, and our records are well under).
+ *
+ * Failure model: every disk operation can fail (full disk, permission
+ * lost, tmpdir on a flaky volume). A failure HERE must never propagate
+ * to the host plugin — the file logger is a debugging aid, not a
+ * correctness dependency. We try once, drop the stream on any error,
+ * and go silent. The OpenCode log channel is unaffected.
+ *
+ * Retention is the user's problem: we never delete; files accumulate
+ * in `os.tmpdir()/opencode-diane/` until the OS clears tmp. On Linux
+ * that's typically at reboot or via systemd-tmpfiles; on macOS every
+ * few days. Documented in WIKI.
+ */
+import { mkdirSync, openSync, writeSync, closeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Directory the logger writes into.
+ *
+ * Honours `OPENCODE_DIANE_LOG_DIR` if set — point it at a mounted
+ * volume when running under Docker (`-e OPENCODE_DIANE_LOG_DIR=/logs
+ * -v $PWD/logs:/logs`) so logs survive the container and can be read
+ * with `analyze-logs.py --dir /logs` from outside. Falls back to
+ * `os.tmpdir()/opencode-diane/` everywhere else; on a fresh host that
+ * is `/tmp/opencode-diane/` on Linux and a per-user temp folder on
+ * macOS / Windows. Exported for tests + docs.
+ */
+export function richLogsDir() {
+    const override = process.env.OPENCODE_DIANE_LOG_DIR;
+    if (override && override.length > 0)
+        return override;
+    return join(tmpdir(), "opencode-diane");
+}
+/**
+ * Best-effort sanitiser for values put on a structured event payload —
+ * trims long strings to keep the log file manageable and caps arrays
+ * at a sensible length. Used to shape the `args` field of a
+ * `tool.call` event before it lands on disk: a tool's free-form
+ * `query` or `content` field could in principle be many KB, and we
+ * don't want a single log line to dominate the file. The marker
+ * `…(+N chars)` / `…(+N items)` is preserved so a reader knows the
+ * truncation happened. Returns the trimmed value; doesn't mutate the
+ * input. Shallow-recurses through plain objects and arrays — there's
+ * no cycle protection because tool args are flat data, but a try
+ * around the caller's `JSON.stringify` still catches anything weird.
+ */
+export function truncateForLog(value, maxStringLength = 500) {
+    if (typeof value === "string") {
+        if (value.length <= maxStringLength)
+            return value;
+        return value.slice(0, maxStringLength) + `…(+${value.length - maxStringLength} chars)`;
+    }
+    if (Array.isArray(value)) {
+        const MAX_ITEMS = 20;
+        const head = value.slice(0, MAX_ITEMS).map((v) => truncateForLog(v, maxStringLength));
+        return value.length > MAX_ITEMS
+            ? [...head, `…(+${value.length - MAX_ITEMS} items)`]
+            : head;
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = truncateForLog(v, maxStringLength);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Build the per-session filename. Public so tests can predict the
+ * shape (the timestamp is "now" and the pid is `process.pid`, so the
+ * test doesn't actually call this — it reads `logger.path()`). The
+ * ISO timestamp has its colons and dots replaced with dashes so the
+ * filename is portable across filesystems.
+ */
+function buildFilename(service, when, pid) {
+    const ts = when.toISOString().replace(/[:.]/g, "-");
+    return `${service}-${ts}-pid${pid}.jsonl`;
+}
+class FileLoggerImpl {
+    /** Open file descriptor, or null once a write fails / after close. */
+    fd;
+    filePath;
+    base;
+    constructor(opts) {
+        // `service` is part of the filename, so a stray slash or NUL would
+        // be a path-injection foot-gun. Tolerate weird values by sanitising.
+        const safeService = opts.service.replace(/[^A-Za-z0-9._-]/g, "_") || "service";
+        const dir = richLogsDir();
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            /* tolerated — openSync below will throw, we'll go silent */
+        }
+        this.filePath = join(dir, buildFilename(safeService, new Date(), process.pid));
+        this.base = { service: opts.service, ...(opts.base ?? {}) };
+        // Synchronous open + write semantics. Why not createWriteStream:
+        // WriteStream buffers writes (16KB highWaterMark by default) and
+        // flushes asynchronously; an event "logged" right before a crash
+        // can be lost, and the very test below this code initially flaked
+        // on that. For debug logs reliability beats per-write speed —
+        // log lines are at human pace, not microseconds. A single openSync
+        // at construction + writeSync per record gives us atomic appends
+        // (POSIX guarantees this for writes ≤ PIPE_BUF, our records are
+        // ~200 bytes) and durability on syscall return.
+        //
+        // "a" flag = O_APPEND | O_CREAT | O_WRONLY. Append is the right
+        // semantics here: multiple loggers (parallel sessions) can target
+        // the same path without clobbering, and the kernel serialises
+        // appends so lines never interleave mid-record.
+        let fd = null;
+        try {
+            fd = openSync(this.filePath, "a");
+        }
+        catch {
+            fd = null;
+        }
+        this.fd = fd;
+        // Header record — gives any reader of the file immediate context
+        // (which plugin, which process, which node version, which cwd).
+        this.event("session.start", {
+            pid: process.pid,
+            node: process.version,
+            platform: process.platform,
+            cwd: process.cwd(),
+        });
+    }
+    log(level, message) {
+        this.write({ level, message });
+    }
+    event(name, data) {
+        this.write({ event: name, ...(data ?? {}) });
+    }
+    write(fields) {
+        if (this.fd === null)
+            return;
+        // Order matters for readability: ts and service first, then base
+        // fields (root, etc.), then the event-specific payload last. Use
+        // ISO time with ms — coarser timestamps make ordering ambiguous
+        // when multiple events fire in the same loop tick.
+        let line;
+        try {
+            const rec = { ts: new Date().toISOString(), ...this.base, ...fields };
+            line = JSON.stringify(rec) + "\n";
+        }
+        catch {
+            // Unserialisable payload (e.g. a value containing a BigInt or a
+            // circular reference). Fall back to a safe placeholder rather
+            // than swallowing the event entirely.
+            line =
+                JSON.stringify({
+                    ts: new Date().toISOString(),
+                    ...this.base,
+                    event: "log.write_failed",
+                    attempted: String(fields.event ?? fields.level ?? "?"),
+                }) + "\n";
+        }
+        try {
+            writeSync(this.fd, line);
+        }
+        catch {
+            // Disk full, fd closed underneath us, etc. — drop the fd and go
+            // silent for the rest of the session. Never propagate.
+            try {
+                closeSync(this.fd);
+            }
+            catch {
+                /* ignore */
+            }
+            this.fd = null;
+        }
+    }
+    path() {
+        return this.filePath;
+    }
+    close() {
+        if (this.fd === null)
+            return;
+        try {
+            closeSync(this.fd);
+        }
+        catch {
+            /* ignore — we're shutting down anyway */
+        }
+        this.fd = null;
+    }
+}
+export function createFileLogger(opts) {
+    return new FileLoggerImpl(opts);
+}

package/dist/utils/peer-detection.d.ts

@@ -0,0 +1,45 @@
+/**
+ * peer-detection.ts — detect known coexisting OpenCode plugins by
+ * reading the user's `opencode.json` config(s). Pure result: a record
+ * naming which peers are listed alongside us, used to apply
+ * compatibility defaults at startup.
+ *
+ * **Conservative by design.** This file knows only about plugins we
+ * have actually validated against (oh-my-opencode and caveman today)
+ * and only triggers when the user has listed them explicitly. It
+ * never sniffs running processes, never imports peer packages, and
+ * never modifies anything on disk. Standalone — when no peer is
+ * found — behaviour is byte-for-byte the documented default.
+ *
+ * Why detect at all: two compatibility decisions need to be made at
+ * startup, not at recall-time:
+ *   - whether to install the `tool.execute.after` nudge (oh-my-opencode
+ *     also rewrites tool output and two plugins both touching
+ *     `output.output` interleave unpredictably);
+ *   - whether to namespace mined skill subdirectories so we don't
+ *     write into the same slugs caveman creates (`caveman`,
+ *     `caveman-commit`, etc.) under the shared `.opencode/skills/`
+ *     directory OpenCode discovers from.
+ *
+ * Both are also user-overrideable via explicit config — auto-detection
+ * fills the option ONLY when the user didn't.
+ */
+export interface PeerPlugins {
+    /** oh-my-opencode (or its newer rename oh-my-openagent, or the slim
+     *  fork) is listed in an opencode config we can see. */
+    ohMyOpencode: boolean;
+    /** A caveman variant is listed. Multiple npm packages exist
+     *  (`caveman-opencode-plugin`, `caveman-opencode`, `opencode-caveman`,
+     *  and the in-repo `caveman` plugin from JuliusBrussee/caveman) so
+     *  we match any of them. */
+    caveman: boolean;
+    /** Raw list of plugin names we read, for the startup log line. */
+    found: string[];
+}
+/**
+ * Read project-local and user-global opencode config files and return
+ * which known peers appear in the `plugin` array. Plugin entries can
+ * be either a string `"name"` or an array `["name", options]`; we
+ * pick out the name in either shape.
+ */
+export declare function detectPeerPlugins(projectRoot: string): PeerPlugins;

package/dist/utils/peer-detection.js

@@ -0,0 +1,90 @@
+/**
+ * peer-detection.ts — detect known coexisting OpenCode plugins by
+ * reading the user's `opencode.json` config(s). Pure result: a record
+ * naming which peers are listed alongside us, used to apply
+ * compatibility defaults at startup.
+ *
+ * **Conservative by design.** This file knows only about plugins we
+ * have actually validated against (oh-my-opencode and caveman today)
+ * and only triggers when the user has listed them explicitly. It
+ * never sniffs running processes, never imports peer packages, and
+ * never modifies anything on disk. Standalone — when no peer is
+ * found — behaviour is byte-for-byte the documented default.
+ *
+ * Why detect at all: two compatibility decisions need to be made at
+ * startup, not at recall-time:
+ *   - whether to install the `tool.execute.after` nudge (oh-my-opencode
+ *     also rewrites tool output and two plugins both touching
+ *     `output.output` interleave unpredictably);
+ *   - whether to namespace mined skill subdirectories so we don't
+ *     write into the same slugs caveman creates (`caveman`,
+ *     `caveman-commit`, etc.) under the shared `.opencode/skills/`
+ *     directory OpenCode discovers from.
+ *
+ * Both are also user-overrideable via explicit config — auto-detection
+ * fills the option ONLY when the user didn't.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const OH_MY_OPENCODE = /^(oh-my-opencode(-slim)?|oh-my-openagent)$/i;
+const CAVEMAN = /(^|\/|@)(caveman-opencode(-plugin)?|opencode-caveman|caveman)$/i;
+/**
+ * Read project-local and user-global opencode config files and return
+ * which known peers appear in the `plugin` array. Plugin entries can
+ * be either a string `"name"` or an array `["name", options]`; we
+ * pick out the name in either shape.
+ */
+export function detectPeerPlugins(projectRoot) {
+    // Same search path OpenCode itself uses: project first, then global.
+    // We take the UNION — if a plugin is listed in either, it counts.
+    const candidates = [
+        join(projectRoot, "opencode.json"),
+        join(projectRoot, "opencode.jsonc"),
+        join(homedir(), ".config", "opencode", "opencode.json"),
+        join(homedir(), ".config", "opencode", "opencode.jsonc"),
+    ];
+    const names = [];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const text = readFileSync(path, "utf-8");
+            const cfg = JSON.parse(stripJsoncComments(text));
+            const arr = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+            for (const entry of arr) {
+                if (typeof entry === "string") {
+                    names.push(entry);
+                }
+                else if (Array.isArray(entry) && typeof entry[0] === "string") {
+                    names.push(entry[0]);
+                }
+                else if (entry && typeof entry === "object" && typeof entry.name === "string") {
+                    names.push(entry.name);
+                }
+            }
+        }
+        catch {
+            // Unreadable or non-JSON config — move on; this is best-effort
+            // detection, not a validation pass.
+        }
+    }
+    const unique = Array.from(new Set(names));
+    return {
+        ohMyOpencode: unique.some((n) => OH_MY_OPENCODE.test(n)),
+        caveman: unique.some((n) => CAVEMAN.test(n)),
+        found: unique,
+    };
+}
+/**
+ * Strip `/* ... *\/` and `//` line comments from a JSONC-style string.
+ * Conservative — doesn't handle `//` inside string literals, which is
+ * effectively never the case in an `opencode.json` plugin array. If
+ * JSON.parse still fails after stripping, the caller treats the file
+ * as unreadable and moves on.
+ */
+function stripJsoncComments(text) {
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/^\s*\/\/.*$/gm, "");
+}

package/dist/utils/shell.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tiny exec wrapper for synchronous git calls during ingestion.
+ *
+ * - returns stdout as a string when the command exits 0
+ * - returns null if git isn't installed or the command failed
+ *   (never throws — ingestion is best-effort)
+ */
+export declare function runGit(args: string[], cwd: string, maxBufferMB?: number): Promise<string | null>;
+/** True if `git` is on PATH and `cwd` is inside a git work tree. */
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+/**
+ * The current HEAD commit SHA, or null if the repo has no commits yet
+ * or git isn't available. Cheap (microseconds for git itself, dominated
+ * by the process-spawn overhead). Suitable for post-bash polling to
+ * detect pull/merge/rebase/reset/checkout side effects.
+ */
+export declare function currentHead(cwd: string): Promise<string | null>;
+/**
+ * Files modified or newly created in the working tree, parsed from
+ * `git status --porcelain=v1`. Returns an empty array if not a git
+ * repo or if the call fails — never throws.
+ *
+ * Selection rules:
+ *   - Modified, added, copied, untracked files → included (returned path
+ *     is the on-disk one).
+ *   - Renames (`R`) → the destination path is returned (the old name has
+ *     nothing on disk to re-index).
+ *   - Deletions in EITHER staging column → skipped (no file on disk).
+ *
+ * Path handling:
+ *   - C-quoted paths (git's escape for spaces / control chars in
+ *     filenames) are unquoted with `JSON.parse`. Unparseable quoting
+ *     falls back to the raw form.
+ *   - Trailing `\r` from CRLF line endings is stripped (defensive — git
+ *     normally outputs LF even on Windows, but third-party tools that
+ *     pipe through `cmd.exe` can introduce it).
+ *
+ * Intended use: poll right after a `bash` tool call to find files the
+ * shell command touched that the code-map index does not know about.
+ * Cap callers' usage with their own per-call file limit — `bash`
+ * commands like `git checkout other-branch` can return thousands.
+ */
+export declare function changedFilesInWorktree(cwd: string): Promise<string[]>;

package/dist/utils/shell.js

@@ -0,0 +1,110 @@
+/**
+ * Tiny exec wrapper for synchronous git calls during ingestion.
+ *
+ * - returns stdout as a string when the command exits 0
+ * - returns null if git isn't installed or the command failed
+ *   (never throws — ingestion is best-effort)
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+export async function runGit(args, cwd, maxBufferMB = 16) {
+    try {
+        const { stdout } = await execFileP("git", args, {
+            cwd,
+            maxBuffer: maxBufferMB * 1024 * 1024,
+            timeout: 30_000,
+        });
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if `git` is on PATH and `cwd` is inside a git work tree. */
+export async function isGitRepo(cwd) {
+    const out = await runGit(["rev-parse", "--is-inside-work-tree"], cwd);
+    return out !== null && out.trim() === "true";
+}
+/**
+ * The current HEAD commit SHA, or null if the repo has no commits yet
+ * or git isn't available. Cheap (microseconds for git itself, dominated
+ * by the process-spawn overhead). Suitable for post-bash polling to
+ * detect pull/merge/rebase/reset/checkout side effects.
+ */
+export async function currentHead(cwd) {
+    const out = await runGit(["rev-parse", "HEAD"], cwd);
+    if (out === null)
+        return null;
+    const trimmed = out.trim();
+    // `rev-parse HEAD` on an empty repo emits the literal string "HEAD"
+    // to stderr and exits non-zero, so a non-null result here is already
+    // a real SHA. Belt-and-braces sanity check on length.
+    return trimmed.length >= 7 && /^[0-9a-f]+$/i.test(trimmed) ? trimmed : null;
+}
+/**
+ * Files modified or newly created in the working tree, parsed from
+ * `git status --porcelain=v1`. Returns an empty array if not a git
+ * repo or if the call fails — never throws.
+ *
+ * Selection rules:
+ *   - Modified, added, copied, untracked files → included (returned path
+ *     is the on-disk one).
+ *   - Renames (`R`) → the destination path is returned (the old name has
+ *     nothing on disk to re-index).
+ *   - Deletions in EITHER staging column → skipped (no file on disk).
+ *
+ * Path handling:
+ *   - C-quoted paths (git's escape for spaces / control chars in
+ *     filenames) are unquoted with `JSON.parse`. Unparseable quoting
+ *     falls back to the raw form.
+ *   - Trailing `\r` from CRLF line endings is stripped (defensive — git
+ *     normally outputs LF even on Windows, but third-party tools that
+ *     pipe through `cmd.exe` can introduce it).
+ *
+ * Intended use: poll right after a `bash` tool call to find files the
+ * shell command touched that the code-map index does not know about.
+ * Cap callers' usage with their own per-call file limit — `bash`
+ * commands like `git checkout other-branch` can return thousands.
+ */
+export async function changedFilesInWorktree(cwd) {
+    const out = await runGit(["status", "--porcelain=v1", "--untracked-files=all"], cwd);
+    if (out === null)
+        return [];
+    const files = [];
+    for (const rawLine of out.split("\n")) {
+        // Normalise CRLF defensively.
+        const line = rawLine.replace(/\r$/, "");
+        // Porcelain v1 format: XY<space>path[ -> renamed_path]
+        // Minimum well-formed line is `XY p` (4 chars).
+        if (line.length < 4)
+            continue;
+        const xy = line.slice(0, 2);
+        let path = line.slice(3);
+        // Skip any line where EITHER column indicates a deletion — that file
+        // is gone from disk (or about to be) and there's nothing to refresh.
+        // Covers `D `, ` D`, `DD`, `MD`, `AD`, `RD`, `CD`, …
+        if (xy[0] === "D" || xy[1] === "D")
+            continue;
+        // Renames / copies: `R` or `C` in column 0. The path looks like
+        // `src/old.ts -> src/new.ts`; keep the destination (the file that
+        // exists on disk).
+        if (xy[0] === "R" || xy[0] === "C") {
+            const arrow = path.indexOf(" -> ");
+            if (arrow >= 0)
+                path = path.slice(arrow + 4);
+        }
+        // Unquote git's C-quoted paths (when path contains special chars).
+        if (path.startsWith('"') && path.endsWith('"')) {
+            try {
+                path = JSON.parse(path);
+            }
+            catch {
+                /* unparseable quoting — keep the raw form */
+            }
+        }
+        if (path.length > 0)
+            files.push(path);
+    }
+    return files;
+}

package/dist/utils/usage-skill.d.ts

@@ -0,0 +1,42 @@
+/**
+ * usage-skill.ts — soft-forces the agent to actually USE Diane.
+ *
+ * OpenCode discovers any `.opencode/skills/<name>/SKILL.md` in the
+ * project and surfaces its content to the agent at session start, so
+ * a skill file is the highest-signal place to put "here's how to use
+ * this plugin, here's when to call which tool" instructions. This
+ * module writes that file at plugin startup.
+ *
+ * **Soft, not hard.** The skill is installed ONLY when the file does
+ * not already exist, so a user can:
+ *   - delete the file to remove the nudge (it won't come back unless
+ *     they re-enable installation explicitly with a fresh repo),
+ *   - edit the file to customise the wording (their edits survive
+ *     every subsequent startup),
+ *   - set `installUsageSkill: false` to never write it at all.
+ *
+ * The skill content is fixed text (no codegen, no templating) so the
+ * agent's instructions don't churn version-over-version.
+ */
+/** Subdirectory name relative to `skillsOutputDir`. The prefix
+ *  (`""` standalone, `"diane-"` when a peer plugin is detected) is
+ *  applied at the call site so this stays one name in one place. */
+export declare const USAGE_SKILL_SLUG = "using-memory";
+/**
+ * Write the SKILL.md if (and only if) it does not already exist.
+ * Returns one of three outcomes for the caller to log:
+ *
+ *   - "installed"  — file did not exist; we wrote it.
+ *   - "preserved"  — file already exists; we left it alone (user
+ *                    customisation, or already installed).
+ *   - "failed"     — write threw (read-only project root, etc.);
+ *                    the error is returned so the caller logs it.
+ *                    Never propagates: a failed soft-force is a
+ *                    quality-of-life regression, not a reason to
+ *                    crash the plugin.
+ */
+export declare function installUsageSkill(root: string, skillsOutputDir: string, slugPrefix: string): {
+    outcome: "installed" | "preserved" | "failed";
+    path: string;
+    error?: unknown;
+};

package/dist/utils/usage-skill.js

@@ -0,0 +1,129 @@
+/**
+ * usage-skill.ts — soft-forces the agent to actually USE Diane.
+ *
+ * OpenCode discovers any `.opencode/skills/<name>/SKILL.md` in the
+ * project and surfaces its content to the agent at session start, so
+ * a skill file is the highest-signal place to put "here's how to use
+ * this plugin, here's when to call which tool" instructions. This
+ * module writes that file at plugin startup.
+ *
+ * **Soft, not hard.** The skill is installed ONLY when the file does
+ * not already exist, so a user can:
+ *   - delete the file to remove the nudge (it won't come back unless
+ *     they re-enable installation explicitly with a fresh repo),
+ *   - edit the file to customise the wording (their edits survive
+ *     every subsequent startup),
+ *   - set `installUsageSkill: false` to never write it at all.
+ *
+ * The skill content is fixed text (no codegen, no templating) so the
+ * agent's instructions don't churn version-over-version.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Subdirectory name relative to `skillsOutputDir`. The prefix
+ *  (`""` standalone, `"diane-"` when a peer plugin is detected) is
+ *  applied at the call site so this stays one name in one place. */
+export const USAGE_SKILL_SLUG = "using-memory";
+/** Filename inside the slug directory. OpenCode's skill discovery
+ *  expects this name; do not rename. */
+const SKILL_FILENAME = "SKILL.md";
+/**
+ * Skill content surfaced to the agent. Hand-tuned wording — short,
+ * directive, ordered by what the agent does first.
+ *
+ * Three design notes for future editors:
+ *   1. Lead with the workflow, not the architecture. The agent needs
+ *      to know *what to do first*, not *how the recall is scored*.
+ *   2. Quantify the savings ("typically replaces 3-8 raw calls") so
+ *      the agent has a concrete reason to choose recall over grep.
+ *   3. Keep the tool list flat. Every line is one tool, one purpose;
+ *      do not group or nest, the agent reads this fast.
+ */
+function skillContent() {
+    return `---
+name: using-memory
+description: ALWAYS call memory_recall before raw code discovery (grep, glob, read). The opencode-diane plugin keeps a persistent searchable store of this repo's structure, git history, project facts, and past sessions — a single recall typically replaces 3-8 raw discovery calls.
+---
+
+# Using opencode-diane's memory
+
+This project has the \`opencode-diane\` plugin loaded. It keeps a
+persistent, searchable store of structural facts about this repo so
+the same things don't have to be re-discovered every session.
+
+## Workflow — do this in order
+
+For ANY task that touches existing code, your first step is **always**:
+
+1. **\`memory_recall { query: "<what you're looking for>" }\`** — a
+   single recall typically replaces 3-8 raw \`grep\`/\`glob\`/\`read\`
+   calls. The store already knows the code map, git history, project
+   facts, and lessons from past sessions in this repo. Try it first;
+   only fall back to raw discovery if it returns nothing relevant.
+
+2. **Targeted file reads** — after recall, \`read\` only the specific
+   files the recall pointed at. Skip directory-wide grepping unless
+   recall came up dry.
+
+3. **\`memory_remember { content: "..." }\`** — when you discover
+   something worth keeping (an invariant, a non-obvious connection,
+   a file you'll touch again), save it so the next session inherits
+   the finding instead of re-deriving it.
+
+## Tools available
+
+- \`memory_recall\` — query the store. **Call this first.**
+- \`memory_status\` — store size, last-ingest times, plugin version.
+  Useful to confirm the plugin is actually loaded.
+- \`memory_remember\` — save a fact for future sessions.
+- \`memory_code_map\` — tree-sitter signatures for any file or
+  directory; the structural shape of the codebase.
+- \`memory_outline\` — compact outline of one file.
+- \`memory_ingest_sessions\` — pull lessons from past OpenCode sessions.
+- \`memory_ingest_code_health\` — lint/typecheck/test signal as
+  memories.
+- \`memory_mine_skills\` — distill recurring task patterns into
+  \`SKILL.md\` files.
+- \`memory_skill\` — read one mined skill.
+
+## When NOT to use memory
+
+- Trivial one-off file reads (\`read package.json\`) — skip recall.
+- Writing brand-new code with no existing context — recall first
+  anyway, but the answer may be empty; that's fine.
+
+This skill file was written by the plugin on first install. Delete it
+to remove the nudge; edit it to customise; set
+\`installUsageSkill: false\` in your \`opencode.json\` to never write
+it at all.
+`;
+}
+/**
+ * Write the SKILL.md if (and only if) it does not already exist.
+ * Returns one of three outcomes for the caller to log:
+ *
+ *   - "installed"  — file did not exist; we wrote it.
+ *   - "preserved"  — file already exists; we left it alone (user
+ *                    customisation, or already installed).
+ *   - "failed"     — write threw (read-only project root, etc.);
+ *                    the error is returned so the caller logs it.
+ *                    Never propagates: a failed soft-force is a
+ *                    quality-of-life regression, not a reason to
+ *                    crash the plugin.
+ */
+export function installUsageSkill(root, skillsOutputDir, slugPrefix) {
+    const slug = `${slugPrefix}${USAGE_SKILL_SLUG}`;
+    const dir = join(root, skillsOutputDir, slug);
+    const path = join(dir, SKILL_FILENAME);
+    if (existsSync(path)) {
+        return { outcome: "preserved", path };
+    }
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, skillContent(), "utf-8");
+        return { outcome: "installed", path };
+    }
+    catch (error) {
+        return { outcome: "failed", path, error };
+    }
+}