@markstanden/opencode-docs-plugin 0.10.0 → 0.12.0

package/src/index.ts

@@ -1,5 +1,6 @@
 import { Plugin, Skill } from "@opencode/plugin";
 import { AbsolutePath } from "@opencode/schema/schema";
+import { createHash } from "node:crypto";
 import type {
     CommandDefinition,
     CommandInvocation,
@@ -7,15 +8,20 @@ import type {
 import type { Info, Result } from "@opencode/plugin/promise/tool";
 import { spawnSync } from "node:child_process";
 import {
+    closeSync,
     type Dirent,
     existsSync,
     lstatSync,
     mkdirSync,
+    openSync,
     readFileSync,
     readdirSync,
     realpathSync,
+    renameSync,
     statSync,
+    unlinkSync,
     writeFileSync,
+    writeSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import {
@@ -50,6 +56,21 @@ import { Schema } from "effect";
 /** The doc classes the plugin serves. `instructions` is the implicit README source. */
 export type DocClass = "instructions" | "repo" | "machine" | "global" | "wiki";
 
+/** The shape of a content revision: SHA-256, hex-encoded. */
+export const REVISION_PATTERN = /^[0-9a-f]{64}$/;
+
+/**
+ * A doc's content revision: the SHA-256 of the exact stored UTF-8 bytes,
+ * front-matter and newline bytes included. It represents the bytes, not an
+ * edit history — the same bytes hash to the same revision — and it is never
+ * persisted into the doc.
+ * @param raw The exact file contents.
+ * @returns The hex digest.
+ */
+export function revisionOf(raw: string): string {
+    return createHash("sha256").update(raw, "utf8").digest("hex");
+}
+
 /** The classes that can be a configured lake. */
 export type LakeClass = Exclude<DocClass, "instructions">;
 
@@ -89,21 +110,37 @@ export const DOCS_INPUT = Schema.Struct({
     search: Schema.optional(
         Schema.String.annotate({
             description:
-                "Case-insensitive search over title, path, keywords, headings, code spans, area, summary and wiki prose. Blank lists the most recently changed docs; a partial match returns the closest.",
+                "Case-insensitive search over title, path, keywords, headings, code spans, area, summary and wiki prose. Blank lists recent docs; a partial match returns the closest.",
         }),
     ),
     lake: Schema.optional(
         Schema.String.annotate({
             description:
-                "Optional lake name: search and check are limited to it, read and add target it. Omit to search every lake, read the unique match, or add to the first writable repo lake.",
+                "Optional lake name: search and check are limited to it; read and add target it. Omit to search or read the unique match; add writes the sole writable lake, refusing with candidates otherwise.",
         }),
     ),
     add: Schema.optional(
         Schema.Struct({
+            mode: Schema.Literals(["create", "replace"]).annotate({
+                description:
+                    "Required: create (a new doc; never overwrites) or replace (wholesale-replaces the doc at path).",
+            }),
             path: Schema.optional(
                 Schema.String.annotate({
                     description:
-                        "Update target, e.g. `guides/getting-started.md`, relative to the lake root: replaces that doc wholesale, so omitted body content is lost, and skips the near-twin reconcile. Omit to create `<Area>/<slug>.md` from the H1.",
+                        "create: optional; derived from Area and the H1 when omitted. replace: required; the doc to replace.",
+                }),
+            ),
+            allowNearTwinReason: Schema.optional(
+                Schema.String.annotate({
+                    description:
+                        "create only: non-blank reason to write despite a same-area near-twin; bypasses only that guard.",
+                }),
+            ),
+            expectedRevision: Schema.optional(
+                Schema.String.annotate({
+                    description:
+                        "replace only: the revision token from your last read or write; stale or missing refuses.",
                 }),
             ),
             metadata: Schema.Struct({
@@ -112,27 +149,27 @@ export const DOCS_INPUT = Schema.Struct({
                 Summary: Schema.String,
             }).annotate({
                 description:
-                    "Front-matter metadata; serialised, never copied. All three are required and must not be blank.",
+                    "Front-matter metadata, serialised; all three required, never blank.",
             }),
             body: Schema.String.annotate({
                 description:
-                    "Markdown body: an H1 title, plus at least one claim section as an H2/H3 — Facts, Inferred, Tested, Failed approaches, Open questions.",
+                    "Markdown body: an H1 title plus a claim section as an H2/H3 — Facts, Inferred, Tested, Failed approaches, Open questions.",
             }),
         }).annotate({
             description:
-                "The only mutating mode: writes a new knowledge doc, or wholesale-replaces the doc at `path`. Refused: blank metadata, path traversal, a non-.md or symlinked target, no claim section, and a same-area near-twin when `path` is omitted. Wiki lakes are read-only.",
+                "create: the target must not exist; explicit paths get the same checks as derived ones. replace: path names an existing doc whose bytes must match expectedRevision — never creates. Refused: blank metadata, traversal, a non-.md or symlinked target, no claim section, unreconciled near-twins. Wiki lakes are read-only.",
         }),
     ),
     check: Schema.optional(
         Schema.Boolean.annotate({
             description:
-                "Validate every knowledge doc: front-matter, an H1, a claim section, no hand-maintained Date, a distinctive H1+Keywords identity, near-twins, broken relative links, a soft length note. Only writable knowledge lakes are validated; read-only lakes, wiki lakes and READMEs are not, and skipped lakes are named.",
+                "Validate knowledge docs: front-matter, an H1, a claim section, no hand-maintained Date, a distinctive identity, near-twins, broken relative links, a soft length note. Only writable knowledge lakes are validated; skipped lakes are named.",
         }),
     ),
     read: Schema.optional(
         Schema.String.annotate({
             description:
-                "A root-relative doc path, or `lake:path`: returns the doc verbatim, front-matter and body, so find-then-read is one call. Lake docs and wiki pages only; project READMEs use the built-in `read` tool.",
+                "Root-relative path, or `lake:path`: the doc verbatim. Lake and wiki pages only; project READMEs use the built-in `read` tool. Knowledge reads end with a revision line, the replace token.",
         }),
     ),
 });
@@ -145,12 +182,16 @@ export const DOCS_INPUT = Schema.Struct({
 export type DocsInput = Schema.Schema.Type<typeof DOCS_INPUT>;
 
 /**
- * The `add` mode's typed DTO: the single writer's whole input. Pass `path` to
- * update (`docs/<area>/<name>.md`); omit it to create `docs/<Area>/<slug>.md`
- * from the H1.
+ * The `add` mode's typed DTO: the single writer's whole input. `mode` picks
+ * the contract: `create` derives `<Area>/<slug>.md` from the H1 unless an
+ * explicit `path` is given, and never overwrites; `replace` requires the
+ * `path` of an existing doc and replaces it wholesale.
  */
 export type DocsAdd = NonNullable<DocsInput["add"]>;
 
+/** The two mutation modes of {@link DocsAdd}. */
+export type AddMode = DocsAdd["mode"];
+
 /** The typed metadata of a knowledge doc, serialised to front-matter. */
 export type DocMetadata = DocsAdd["metadata"];
 
@@ -912,11 +953,15 @@ export interface LakeInfo {
     validated: boolean;
     /** Whether the root is absent, so the lake contributes nothing yet. */
     missing?: boolean;
+    /** What belongs there, as configured; absent lakes use the class guidance. */
+    description?: string;
 }
 
 /**
  * Describe the configured lakes, then the ranking. The agent learns where
- * knowledge lives without loading the full convention.
+ * knowledge lives without loading the full convention. Each line pairs the
+ * human scope label with its config value, and carries the lake's description
+ * (or the class guidance) so a write destination is chosen deliberately.
  * @param lakes The configured lakes.
  * @returns The help text.
  */
@@ -926,15 +971,30 @@ export function helpText(lakes: readonly LakeInfo[]): string {
         const access = lake.writable ? "writable" : "read-only";
         const checked = lake.validated ? "checked" : "not checked";
         const missing = lake.missing === true ? " — missing" : "";
+        const label =
+            lake.class in CLASS_LABELS
+                ? `${CLASS_LABELS[lake.class as LakeClass]} [${lake.class}]`
+                : lake.class;
+        const description =
+            lake.description ?? classGuidance(lake.class as LakeClass);
         lines.push(
-            `- ${lake.name} (${lake.class}, ${access}, ${checked}): ${lake.root}${missing}`,
+            `- ${lake.name} (${label}, ${access}, ${checked}): ${lake.root}${missing}`,
         );
+        lines.push(`  ${description}`);
     }
     lines.push(
         "- instructions (read-only, not checked): nested project README.md " +
             "files; results are prefixed `instructions:` and read with the " +
             "built-in read tool",
     );
+    lines.push(
+        "add writes to the sole writable knowledge lake when `lake` is " +
+            "omitted; with several, pass lake — one of the names above.",
+    );
+    lines.push(
+        "reads of knowledge docs end with a docs: revision line — pass its " +
+            "hash as expectedRevision when replacing that doc.",
+    );
     return `${lines.join("\n")}\n\n${explainRanking()}`;
 }
 
@@ -1400,6 +1460,8 @@ export function slugify(text: string): string {
 export type AddOutcome =
     | {
           action: "write";
+          /** The mutation mode the write follows. */
+          mode: AddMode;
           /** Root-relative target. */
           path: string;
           /** The serialised file contents. */
@@ -1439,6 +1501,41 @@ function blankRequiredField(metadata: DocMetadata): string | null {
     return null;
 }
 
+/**
+ * The mutation mode of an `add` request, guarded for direct core callers:
+ * the typed schema requires `mode`, but nothing stops a JS caller bypassing
+ * it, so the core refuses rather than guessing.
+ * @param add The typed request, as delivered.
+ * @returns The mode, or the refusal reason.
+ */
+function modeOf(add: DocsAdd): AddMode | { reason: string } {
+    if (add.mode === "create" || add.mode === "replace") {
+        return add.mode;
+    }
+    return {
+        reason:
+            'mode is required and must be "create" (write a new doc) or ' +
+            '"replace" (wholesale-replace the doc at path).',
+    };
+}
+
+/**
+ * Whether a create's deliberate near-twin override is present: a non-blank,
+ * non-empty explanation. It bypasses only the semantic near-twin guard, never
+ * the structural checks or the target state.
+ * @param add The typed request.
+ * @returns True when the override may be used in this mode.
+ */
+function overrideGiven(add: DocsAdd): boolean {
+    if (add.mode !== "create") {
+        return false;
+    }
+    return (
+        typeof add.allowNearTwinReason === "string" &&
+        add.allowNearTwinReason.trim() !== ""
+    );
+}
+
 /**
  * Validate an explicit `add` path: relative, inside the lake root, naming a
  * `.md` file.
@@ -1468,8 +1565,9 @@ function explicitTarget(given: string): { path: string } | { reason: string } {
 
 /**
  * The root-relative target path for an `add`, or the reason it is refused.
- * An explicit path must stay inside the lake root and name a `.md` file; an
- * omitted path derives `<Area>/<slug>.md` from the H1.
+ * An explicit path must stay inside the lake root and name a `.md` file; a
+ * create with no path derives `<Area>/<slug>.md` from the H1; a replace has
+ * no path to derive — its `path` is required.
  * @param add The typed request.
  * @returns The target path, or the refusal reason.
  */
@@ -1478,6 +1576,11 @@ function targetOf(add: DocsAdd): { path: string } | { reason: string } {
     if (given !== "") {
         return explicitTarget(given);
     }
+    if (add.mode === "replace") {
+        return {
+            reason: "replace requires the path of the existing doc to replace.",
+        };
+    }
     const slug = slugify(h1Of(add.body) ?? "");
     if (slug === "") {
         return { reason: "The H1 does not yield a usable file name." };
@@ -1546,8 +1649,10 @@ export function nearTwins(
 }
 
 /**
- * The near-twin refusal for an `add`, or null when the write may proceed.
- * An explicit path is the update contract and skips reconcile.
+ * The near-twin refusal for a create, or null when the write may proceed.
+ * Every create reconciles — derived and explicit paths alike — unless the
+ * caller supplies a non-blank {@link DocsAdd.allowNearTwinReason}; replace is
+ * the deliberate update contract and has no create guard.
  * @param add The typed request.
  * @param entries The current docs.
  * @returns The refusal, or null.
@@ -1556,7 +1661,7 @@ function nearTwinRefusal(
     add: DocsAdd,
     entries: readonly DocEntry[],
 ): AddOutcome | null {
-    if ((add.path?.trim() ?? "") !== "") {
+    if (add.mode !== "create" || overrideGiven(add)) {
         return null;
     }
     const nearTwinDocs = nearTwins(
@@ -1571,23 +1676,123 @@ function nearTwinRefusal(
         action: "refuse",
         reason:
             `${REFUSE} ${add.metadata.Area} already holds a near-twin of ` +
-            "this doc. Pass its path to update it, or a different path " +
-            "to write anyway:\n\n" +
+            'this doc. Pass its path with mode:"replace" to replace it, ' +
+            "or a non-blank allowNearTwinReason to write a deliberate " +
+            "distinct doc:\n\n" +
             render(nearTwinDocs),
         candidates: nearTwinDocs,
     };
 }
 
+/**
+ * The refusal for a misused `allowNearTwinReason`, or null. Replace has no
+ * near-twin guard, so the field is meaningless there; a create must explain
+ * the override in non-blank prose.
+ * @param add The typed request.
+ * @returns The refusal reason, or null when the field is acceptable.
+ */
+function overrideRefusal(add: DocsAdd): string | null {
+    if (add.allowNearTwinReason === undefined) {
+        return null;
+    }
+    if (add.mode === "replace") {
+        return (
+            "allowNearTwinReason is create-only; replace has no " +
+            "near-twin guard to bypass."
+        );
+    }
+    if (
+        typeof add.allowNearTwinReason !== "string" ||
+        add.allowNearTwinReason.trim() === ""
+    ) {
+        return (
+            "allowNearTwinReason must be a non-blank explanation of why " +
+            "this doc is distinct from its near-twin."
+        );
+    }
+    return null;
+}
+
+/**
+ * The refusal for a misused `expectedRevision`, or null. Replace requires the
+ * revision token of the doc being replaced — its stale-write guard; create
+ * carries a not-exists precondition instead and rejects the field outright.
+ * @param add The typed request.
+ * @returns The refusal reason, or null when the field is acceptable.
+ */
+function revisionRefusal(add: DocsAdd): string | null {
+    if (add.mode === "create") {
+        return add.expectedRevision === undefined
+            ? null
+            : "expectedRevision is replace-only; a create's precondition is " +
+                  "that the target does not exist.";
+    }
+    const given = add.expectedRevision?.trim() ?? "";
+    if (given === "") {
+        return (
+            "replace requires expectedRevision — the revision returned with " +
+            "your last read or write of the doc, so a stale whole-doc " +
+            "replacement refuses instead of overwriting a newer edit."
+        );
+    }
+    if (!REVISION_PATTERN.test(given)) {
+        return (
+            "expectedRevision must be the SHA-256 hex digest returned with " +
+            "the doc you read; reread it and resubmit."
+        );
+    }
+    return null;
+}
+
+/**
+ * The refusal for DTO content a knowledge doc may not carry: blank required
+ * metadata, an `Area` off the root, a missing `H1`, no claim section, or an
+ * identity too weak to reconcile.
+ * @param add The typed request.
+ * @returns The refusal reason, or null when the content is acceptable.
+ */
+function contentRefusal(add: DocsAdd): string | null {
+    const blank = blankRequiredField(add.metadata);
+    if (blank !== null) {
+        return `${blank} is required and must not be blank.`;
+    }
+    if (/[/\\]|\.\./.test(add.metadata.Area)) {
+        return "Area must be a single folder name under the lake root.";
+    }
+    if (h1Of(add.body) === undefined) {
+        return "The body must carry an H1 (`# Title`).";
+    }
+    // The same rule `check` applies, enforced before anything touches disk: a
+    // doc that `check` would flag on the next run should never be written.
+    if (!hasClaimSection(add.body)) {
+        return (
+            "the body carries no claim section; add an H2/H3 headed Facts, " +
+            "Inferred, Tested, Failed approaches or Open questions."
+        );
+    }
+    if (!hasDistinctiveIdentity(reconcileQuery(add))) {
+        return (
+            `the H1 and Keywords together carry no term of MIN_TERM_LENGTH ` +
+            `(${MIN_TERM_LENGTH}) or longer; add a distinctive term so ` +
+            "reconcile can tell this doc apart."
+        );
+    }
+    return null;
+}
+
 /**
  * Validate an `add` request and prepare it for writing — pure, no fs.
  *
- * Trust boundary: the caller is a model. Blank required metadata, a body
- * without an H1, a path or `Area` escaping the lake root, a non-`.md` target
- * and a title that yields no slug are all refused. With `path` omitted the
- * target is `<Area>/<slug>.md` and a same-area near-twin — a doc matching every
- * reconcile query term ({@link reconcileQuery}) — refuses the write with the
- * candidates attached; an explicit `path` is the update contract (wholesale
- * replacement) and skips reconcile.
+ * Trust boundary: the caller is a model. `mode` is required: `create` derives
+ * the target from `Area` and the H1 unless an explicit `path` is given, and
+ * reconciles against same-area near-twins either way; `replace` requires the
+ * path of an existing doc. Blank required metadata, a body without an H1, a
+ * path or `Area` escaping the lake root, a non-`.md` target and a title that
+ * yields no slug are all refused. A same-area near-twin — a doc matching every
+ * reconcile query term ({@link reconcileQuery}) — refuses a create unless a
+ * non-blank `allowNearTwinReason` explains the deliberate distinct doc.
+ * Target existence is the caller seam's to verify: creates must not overwrite
+ * and replaces must exist.
  * @param add The typed request.
  * @param entries The current docs, for reconcile and neighbours.
  * @param options Soft-limit configuration.
@@ -1605,30 +1810,21 @@ export function prepareAdd(
         candidates: [],
     });
 
-    const blank = blankRequiredField(add.metadata);
-    if (blank !== null) {
-        return refuse(`${blank} is required and must not be blank.`);
+    const mode = modeOf(add);
+    if (typeof mode !== "string") {
+        return refuse(mode.reason);
     }
-    if (/[/\\]|\.\./.test(add.metadata.Area)) {
-        return refuse("Area must be a single folder name under the lake root.");
+    const override = overrideRefusal(add);
+    if (override !== null) {
+        return refuse(override);
     }
-    if (h1Of(add.body) === undefined) {
-        return refuse("The body must carry an H1 (`# Title`).");
-    }
-    // The same rule `check` applies, enforced before anything touches disk: a
-    // doc that `check` would flag on the next run should never be written.
-    if (!hasClaimSection(add.body)) {
-        return refuse(
-            "the body carries no claim section; add an H2/H3 headed Facts, " +
-                "Inferred, Tested, Failed approaches or Open questions.",
-        );
+    const revision = revisionRefusal(add);
+    if (revision !== null) {
+        return refuse(revision);
     }
-    if (!hasDistinctiveIdentity(reconcileQuery(add))) {
-        return refuse(
-            `the H1 and Keywords together carry no term of MIN_TERM_LENGTH ` +
-                `(${MIN_TERM_LENGTH}) or longer; add a distinctive term so ` +
-                "reconcile can tell this doc apart.",
-        );
+    const content = contentRefusal(add);
+    if (content !== null) {
+        return refuse(content);
     }
     const target = targetOf(add);
     if ("reason" in target) {
@@ -1647,6 +1843,7 @@ export function prepareAdd(
         .slice(0, MAX_RESULTS);
     return {
         action: "write",
+        mode,
         path: target.path,
         contents: serializeDoc(add.metadata, add.body),
         neighbours,
@@ -2181,12 +2378,13 @@ export const RECORD_NUDGE =
     "behaviour), add one `Record with docs add:` block per durable topic and " +
     "scope — coalesce related findings rather than one block per observation, " +
     "never one session dump, and never one mixed-scope doc. Each block names " +
-    "its class (repo, machine or global), `Area`, `H1` title and `Keywords`, and " +
-    "keeps what was learned, why it matters, the evidence or status, any " +
-    "unresolved uncertainty and the intended scope, so the next agent can " +
-    "reconcile before writing. Reference a finding already recorded by path " +
-    "rather than restating it, and assume persistence only where the session " +
-    "confirms it.";
+    "its scope (Repository/Personal/Organisation — config repo, machine or " +
+    "global), `Area`, `H1` title and `Keywords`, and keeps what was learned, " +
+    "why it matters, the evidence or status, any unresolved uncertainty and " +
+    "the intended scope, so the next agent can reconcile before writing and " +
+    "confirm the destination fits. Reference a finding already recorded by " +
+    "path rather than restating it, and assume persistence only where the " +
+    "session confirms it.";
 
 /**
  * Resolve the plugin's `nudge` option: unset means on; a boolean passes
@@ -2219,6 +2417,13 @@ export interface LakeSpec {
     profile: LakeProfile;
     /** Whether `add` may write to it. */
     writable: boolean;
+    /**
+     * What belongs in this particular destination, as configured. Absent lakes
+     * fall back to the class guidance ({@link classGuidance}); it is
+     * descriptive data shown in help and refusal candidate lists, never
+     * indexed for search.
+     */
+    description?: string;
 }
 
 /**
@@ -2245,6 +2450,21 @@ export interface Lake extends LakeSpec {
      * existing root; throws when the root is absent rather than creating it.
      */
     write: (path: string, contents: string) => void;
+    /**
+     * The guarded publication route for real lakes: lock, re-verify, and
+     * publish the whole document — a no-overwrite create, or an atomic
+     * whole-file replacement against `expectedRevision`. Legacy closure lakes
+     * omit it and fall back to the plain `write` seam.
+     */
+    publish?: (
+        path: string,
+        contents: string,
+        options: {
+            mode: AddMode;
+            expectedRevision?: string | undefined;
+            label: string;
+        },
+    ) => { revision: string } | { reason: string };
     /**
      * Legacy seam notes only. Real lakes compute their environment notes at
      * call time — a root that appears, disappears or gains a git checkout is
@@ -2315,17 +2535,713 @@ function safeLakeTarget(root: string, path: string): string | null {
     return target;
 }
 
+/**
+ * A held target lock. Release it on every ordinary exit; a lock left by an
+ * interrupted process is never stolen automatically — the refusal names its
+ * owner and the recovery is manual.
+ */
+interface TargetLock {
+    /** Removes the lock file; best effort. */
+    release: () => void;
+}
+
+/**
+ * The physical identity of a target: its deepest existing ancestor, real-pathed,
+ * plus the exact remaining segments. Two configured roots that reach the same
+ * tree by different routes resolve to one prefix and one tail, so their locks
+ * and identities cannot silently diverge. The key is stable across the
+ * target-or-parent-creation transition: real-pathing the existing prefix and
+ * joining the missing tail yields the same absolute path before and after the
+ * missing segments appear.
+ * @param target The absolute target path.
+ * @returns The existing real prefix and the missing tail.
+ */
+function physicalRouteOf(target: string): {
+    realPrefix: string;
+    tail: readonly string[];
+} {
+    const tail: string[] = [];
+    let head = target;
+    while (!existsSync(head)) {
+        tail.unshift(basename(head));
+        const parent = dirname(head);
+        if (parent === head) {
+            break;
+        }
+        head = parent;
+    }
+    return { realPrefix: realpathSync(head), tail };
+}
+
+/**
+ * The canonical on-disk identity of a target: its resolved existing prefix
+ * plus the missing tail joined. Every configured route to the same file
+ * produces this one string.
+ * @param target The absolute target path.
+ * @returns The real-path key.
+ */
+export function physicalTargetKey(target: string): string {
+    const { realPrefix, tail } = physicalRouteOf(target);
+    return join(realPrefix, ...tail);
+}
+
+/**
+ * The lock directory for a target: a hidden `.docs-lock` inside the deepest
+ * existing ancestor that can hold it — the target's own directory once the
+ * target exists, its existing parent otherwise. Siting the lock beside the
+ * physical target keeps all configured routes (and separately configured
+ * processes) on one directory: aliasing roots resolve the same real prefix,
+ * and nothing about the lock location depends on the current runtime's lake
+ * list. Search and `check` skip dot-directories at every level, so the lock
+ * directory is never mistaken for content.
+ * @param target The absolute target path.
+ * @returns The lock directory path.
+ */
+export function targetLockDirectory(target: string): string {
+    const { realPrefix, tail } = physicalRouteOf(target);
+    // The existing prefix is real-pathed already: for an existing target it
+    // is the file itself (lock beside it), for a missing target it is the
+    // deepest existing ancestor directory.
+    return join(
+        tail.length === 0 ? dirname(realPrefix) : realPrefix,
+        ".docs-lock",
+    );
+}
+
+/**
+ * The lock file for a target: keyed by the target's canonical physical key and
+ * sited beside it (see {@link targetLockDirectory}). Exported for diagnostics
+ * and tests: refusals name the manual recovery path, and tests must consult
+ * the real protocol's location rather than re-deriving it.
+ * @param target The absolute target path.
+ * @returns The lock file path.
+ */
+export function targetLockPath(target: string): string {
+    return join(
+        targetLockDirectory(target),
+        `${createHash("sha256")
+            .update(physicalTargetKey(target), "utf8")
+            .digest("hex")}.lock`,
+    );
+}
+
+/**
+ * Prepare the lock directory without touching anything but what is ours: an
+ * existing directory is kept, any other object (including a symlink) refuses
+ * without being read, followed, truncated or removed, and a missing directory
+ * is created one level inside the already-existing ancestor. Bounded — one
+ * creation attempt, then a post-EEXIST re-stat; no spin, no cleanup of
+ * foreign objects.
+ * @param lockDir The computed lock directory.
+ * @returns undefined when the directory is usable, or the refusal reason.
+ */
+function ensureLockDirectory(lockDir: string): { error: string } | undefined {
+    try {
+        const stats = lstatSync(lockDir);
+        if (stats.isDirectory()) {
+            return undefined;
+        }
+        return {
+            error:
+                `the lock directory ${lockDir} is occupied by a ` +
+                `${stats.isSymbolicLink() ? "symlink" : "non-directory"}; ` +
+                "nothing was written. Remove or repair it deliberately.",
+        };
+    } catch {
+        // Absent — create it, contended creation tolerated below.
+    }
+    try {
+        mkdirSync(lockDir);
+        return undefined;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+            return {
+                error: `could not create the lock directory ${lockDir}: ${String(error)}.`,
+            };
+        }
+        try {
+            return lstatSync(lockDir).isDirectory()
+                ? undefined
+                : {
+                      error: `the lock directory ${lockDir} appeared and is not a directory.`,
+                  };
+        } catch {
+            return {
+                error: `the lock directory ${lockDir} vanished while locking.`,
+            };
+        }
+    }
+}
+
+/**
+ * Acquire a target's publication lock with an exclusive create. A held lock
+ * refuses busy with its recorded owner; it is never stolen, however old —
+ * an interrupted process is recovered by a human confirming the owner is
+ * gone and removing the file.
+ * @param target The absolute target path.
+ * @returns The held lock, or the busy reason.
+ */
+function acquireTargetLock(target: string): TargetLock | { busy: string } {
+    const lockPath = targetLockPath(target);
+    const problem = ensureLockDirectory(dirname(lockPath));
+    if (problem !== undefined) {
+        return { busy: problem.error };
+    }
+    try {
+        const fd = openSync(lockPath, "wx");
+        try {
+            writeFullBytes(
+                fd,
+                JSON.stringify({
+                    pid: process.pid,
+                    acquiredAt: new Date().toISOString(),
+                }),
+            );
+        } finally {
+            closeSync(fd);
+        }
+        return {
+            release: (): void => {
+                try {
+                    unlinkSync(lockPath);
+                } catch {
+                    // Best effort: a later refusal names the surviving lock.
+                }
+            },
+        };
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+            throw error;
+        }
+        let owner = "details unreadable";
+        try {
+            const raw = readFileSync(lockPath, "utf8").trim();
+            if (raw !== "") {
+                owner = raw;
+            }
+        } catch {
+            // Keep the fallback text.
+        }
+        return {
+            busy:
+                `another writer holds the target lock (${owner}); retry ` +
+                `later, or after confirming that process is gone remove ` +
+                `${lockPath}.`,
+        };
+    }
+}
+
+/**
+ * Write the whole byte sequence through an open descriptor. A short write is
+ * looped — regular files rarely short-write, but nothing here reports a
+ * revision for bytes it did not fully store: a mid-loop failure propagates
+ * and the publication never renames.
+ * @param fd The descriptor to write through, positioned by the OS.
+ * @param contents The full serialised document.
+ * @param write The single write primitive; injected for short-write tests.
+ */
+export function writeFullBytes(
+    fd: number,
+    contents: string,
+    write: typeof writeSync = writeSync,
+): void {
+    const buffer = Buffer.from(contents, "utf8");
+    let offset = 0;
+    while (offset < buffer.length) {
+        const written = write(fd, buffer, offset, buffer.length - offset);
+        if (typeof written !== "number" || written <= 0) {
+            throw new Error(
+                `write stalled after ${offset} of ${buffer.length} bytes`,
+            );
+        }
+        offset += written;
+    }
+}
+
+/** A temp file this operation exclusively created and owns. */
+interface OwnedTemp {
+    /** The exclusive-create descriptor; all writes go through it. */
+    fd: number;
+    /** The temp's path, for the atomic rename. */
+    path: string;
+}
+
+/**
+ * The exclusive temp-name selection seam: create one new regular file at a
+ * name this operation owns, or throw `EEXIST` when a foreign object already
+ * occupies the candidate. It is never reopened by pathname for writing — the
+ * returned descriptor is the only write route — and a pre-existing symlink,
+ * regular file or directory is never followed, truncated or removed.
+ */
+export type TempFactory = (target: string) => OwnedTemp;
+
+/** The attempts made on distinct exclusive temp names before giving up. */
+export const MAX_TEMP_ATTEMPTS = 8;
+
+/** The module-level temp-file counter: unique publication temps per process. */
+let publishTempCounter = 0;
+
+/**
+ * The default temp selection: `${target}.${pid}.${counter}.tmp` created
+ * exclusively. A pre-existing object at a candidate name — including a
+ * symlink seeded in advance — makes the create fail without touching it, and
+ * the retry loop below moves to the next fresh name. The counter never
+ * repeats within a process, so ordinary contention cannot exhaust the bound.
+ * @param target The absolute target path.
+ * @returns The owned temp descriptor and path.
+ */
+const defaultTempFactory: TempFactory = (target) => {
+    const path = `${target}.${process.pid}.${publishTempCounter++}.tmp`;
+    const fd = openSync(path, "wx");
+    return { fd, path };
+};
+
+/**
+ * The publication seams: the narrow, injectable primitives the guarded
+ * publication uses, exercised by default against the real filesystem. Tests
+ * inject them to make collisions and mid-publication failures deterministic;
+ * production code never reopens a claimed temp, and every seam default
+ * satisfies the exclusive-create and full-write contracts.
+ */
+export interface PublicationSeams {
+    /** Exclusive temp selection; defaults to {@link defaultTempFactory}. */
+    temp?: TempFactory;
+    /** The full-write primitive; defaults to {@link writeFullBytes}. */
+    writeFull?: (fd: number, contents: string) => void;
+    /** The atomic rename; defaults to `renameSync`. */
+    rename?: (temp: string, target: string) => void;
+    /** Stage observation for coordination and failure injection. */
+    onStage?: (stage: PublicationStage) => void;
+}
+
+/** The observations a guarded publication announces. */
+export type PublicationStage =
+    | "locked"
+    | "verified"
+    | /** create only: the target is exclusively open, bytes not yet written */ "targetOpen"
+    | "published";
+
+/**
+ * The bounded retry over exclusive temp names: each attempt is a fresh name
+ * the factory must exclusively create; an `EEXIST` retry is bounded and never
+ * touches the foreign object it collided with.
+ * @param make The temp seam in use.
+ * @param target The absolute target path, for the candidate names.
+ * @returns An owned temp, or null when every attempt collided.
+ */
+function acquireTemp(make: TempFactory, target: string): OwnedTemp | null {
+    for (let remaining = MAX_TEMP_ATTEMPTS; remaining > 0; remaining -= 1) {
+        try {
+            return { ...make(target) };
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Verify the replace contract while the target lock is held: the target must
+ * be a regular file (a vanished target is a conflict, never an implicit
+ * create) and its current bytes must match the caller's token, so two
+ * differently routed replace calls verify the same physical bytes under the
+ * same lock.
+ * @param target The absolute, guarded target path.
+ * @param options Publication options.
+ * @param options.expectedRevision The replace's stale-write token.
+ * @param options.label The qualified target label, for refusals.
+ * @returns null when the write may proceed, else the refusal reason.
+ */
+function verifyUnderLock(
+    target: string,
+    options: { expectedRevision?: string | undefined; label: string },
+): string | null {
+    let present: boolean;
+    try {
+        present = lstatSync(target).isFile();
+    } catch {
+        present = false;
+    }
+    if (!present) {
+        return (
+            `${REFUSE} no doc at ${options.label} — replace never ` +
+            'creates; pass mode:"create" for a new doc.'
+        );
+    }
+    const found = revisionOf(readFileSync(target, "utf8"));
+    if (found !== options.expectedRevision) {
+        const short = (value: string | undefined): string =>
+            (value ?? "none").slice(0, 12);
+        return (
+            `${REFUSE} ${options.label} changed since you read it ` +
+            `(expected ${short(options.expectedRevision)}, found ` +
+            `${short(found)}). Read it again, reconcile, and ` +
+            "resubmit the replacement deliberately."
+        );
+    }
+    return null;
+}
+
+/**
+ * The refusal for a caught publication error, or null when the error is not
+ * one the caller should see as a refusal: a losing create's EEXIST, or an
+ * unwritable lake's EACCES/EPERM. Everything else propagates.
+ * @param label The qualified target label, for refusals.
+ * @param mode The mutation mode the write follows.
+ * @param error The caught error.
+ * @returns The refusal reason, or null to rethrow.
+ */
+function publicationErrorRefusal(
+    label: string,
+    mode: AddMode,
+    error: unknown,
+): string | null {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (mode === "create" && code === "EEXIST") {
+        return (
+            `${REFUSE} ${label} already exists — read it and pass ` +
+            'mode:"replace" to overwrite it deliberately.'
+        );
+    }
+    if (code === "EACCES" || code === "EPERM") {
+        return (
+            `${REFUSE} could not publish ${label}: ${String(error)}. ` +
+            "The lake or its directories are not writable by this process."
+        );
+    }
+    return null;
+}
+
+/**
+ * The publication state/ownership sketch (one replace call):
+ *
+ *   acquire lock    exclusive create beside the physical target
+ *   onStage locked
+ *   verify          current bytes re-read under the lock (stale refusal)
+ *   onStage verified
+ *   create temp     exclusive create beside the target; owned fd retained
+ *   write full      through the fd only; short writes loop or fail
+ *   rename          atomic temp → target; the file published is ours
+ *   onStage published
+ *   release lock
+ *   cleanup duties: on any ordinary failure, unlink ONLY the temp this
+ *   operation created; the lock release in the outer finally; never a
+ *   foreign temp, lock or document path.
+ *
+ * The guarantee covers cooperating plugin writers; a manual editor can still
+ * race any filesystem operation, and a local attacker able to swap
+ * directories between individual syscalls is outside this threat model
+ * (documented, not fought with privileged machinery).
+ * @param spec The lake spec.
+ * @param target The absolute, guarded target path.
+ * @param contents The serialised file contents.
+ * @param options Publication options.
+ * @param options.mode The mutation mode.
+ * @param options.expectedRevision The replace's stale-write token.
+ * @param options.label The qualified target label, for refusals.
+ * @param options.seams The injectable publication primitives.
+ * @returns The new revision, or the refusal reason.
+ */
+/** The resources one guarded publication has claimed so far. */
+interface PublicationLedger {
+    /** The temp this operation exclusively created, while unpublished. */
+    owned: OwnedTemp | null;
+    /** Whether the submitted bytes are durably at the target. */
+    published: boolean;
+    /** Whether the target file is this operation's own `wx` create. */
+    createdTarget: boolean;
+}
+
+/**
+ * The guarded create: exclusive open, full write through the descriptor, no
+ * overwrite. Sets the ledger on the way through; throws on failure so the
+ * caller's cleanup owns the partial file.
+ * @param target The absolute, guarded target path.
+ * @param contents The serialised file contents.
+ * @param ledger The claimed resources, updated in place.
+ * @param writeFull The full-write primitive.
+ * @param onStage Stage observation.
+ */
+function publishCreate(
+    target: string,
+    contents: string,
+    ledger: PublicationLedger,
+    writeFull: (fd: number, contents: string) => void,
+    onStage: (stage: PublicationStage) => void,
+): void {
+    mkdirSync(dirname(target), { recursive: true });
+    const fd = openSync(target, "wx");
+    // From here the file at the target is this operation's own exclusive
+    // create: a failure owns and removes it, never a rival's `EEXIST` loss.
+    ledger.createdTarget = true;
+    // Deliberately observable window: a create's guarantees are exclusive
+    // naming and eventually-complete bytes, not the replacement path's
+    // all-or-nothing swap — "targetOpen" marks the readers-see-it-first state
+    // for coordination and tests.
+    onStage("targetOpen");
+    try {
+        writeFull(fd, contents);
+    } finally {
+        closeSync(fd);
+    }
+    // The whole sequence succeeded: the no-overwrite create contract, now
+    // with a full-write guarantee.
+    ledger.published = true;
+    onStage("published");
+}
+
+/**
+ * The guarded replace under the held lock: re-verify the token, exclusively
+ * create a fresh temp, write the whole sequence through its descriptor and
+ * swap atomically.
+ * @param target The absolute, guarded target path.
+ * @param contents The serialised file contents.
+ * @param ledger The claimed resources, updated in place.
+ * @param options Publication options.
+ * @param options.expectedRevision The replace's stale-write token.
+ * @param options.label The qualified target label, for refusals.
+ * @param seams The publication seams.
+ * @returns null when the bytes are published, else the refusal reason.
+ */
+function publishReplace(
+    target: string,
+    contents: string,
+    ledger: PublicationLedger,
+    options: { expectedRevision?: string | undefined; label: string },
+    seams: PublicationSeams,
+): string | null {
+    const refusal = verifyUnderLock(target, options);
+    if (refusal !== null) {
+        return refusal;
+    }
+    seams.onStage?.("verified");
+    const temp = acquireTemp(seams.temp ?? defaultTempFactory, target);
+    if (temp === null) {
+        return (
+            `${REFUSE} could not publish ${options.label}: every ` +
+            "candidate temp name was occupied by an object this " +
+            "operation does not own; nothing was changed."
+        );
+    }
+    ledger.owned = temp;
+    try {
+        (seams.writeFull ?? writeFullBytes)(temp.fd, contents);
+    } finally {
+        closeSync(temp.fd);
+    }
+    (seams.rename ?? renameSync)(temp.path, target);
+    // From here the temp path no longer holds our bytes.
+    ledger.owned = null;
+    ledger.published = true;
+    seams.onStage?.("published");
+    return null;
+}
+
+/**
+ * The publication state/ownership sketch (one call):
+ *
+ *   acquire lock    exclusive create beside the physical target
+ *   onStage locked
+ *   verify          replace: current bytes re-read under the lock
+ *   onStage verified
+ *   open target     create: `wx` open, this operation's file, no bytes yet
+ *   onStage targetOpen (create only — readers can observe the empty file)
+ *   write full      through the fd only; short writes loop or fail
+ *   rename          replace: atomic temp → target; the file published is ours
+ *   onStage published
+ *   release lock
+ *   cleanup duties: on any ordinary failure, unlink ONLY the temp this
+ *   operation created (and its own partial create target); the lock release
+ *   in the outer finally; never a foreign temp, lock or document path.
+ *
+ * The guarantee covers cooperating plugin writers; a manual editor can still
+ * race any filesystem operation, and a local attacker able to swap
+ * directories between individual syscalls is outside this threat model
+ * (documented, not fought with privileged machinery).
+ * @param target The absolute, guarded target path. (The lake's identity is
+ * implied by the guard.)
+ * @param contents The serialised file contents.
+ * @param options Publication options.
+ * @param options.mode The mutation mode.
+ * @param options.expectedRevision The replace's stale-write token.
+ * @param options.label The qualified target label, for refusals.
+ * @param options.seams The injectable publication primitives.
+ * @returns The new revision, or the refusal reason.
+ */
+function publishTarget(
+    target: string,
+    contents: string,
+    options: {
+        mode: AddMode;
+        expectedRevision?: string | undefined;
+        label: string;
+        seams?: PublicationSeams;
+    },
+): { revision: string } | { reason: string } {
+    const seams = options.seams ?? {};
+    const lock = acquireTargetLock(target);
+    if ("busy" in lock) {
+        return { reason: `${REFUSE} ${lock.busy}` };
+    }
+    // The resource ledger: only the temp this operation exclusively created
+    // is ever unlinked (and only while unpublished), and only a target file
+    // this operation created itself is removed on a create failure — never a
+    // rival's `EEXIST` loss.
+    const ledger: PublicationLedger = {
+        owned: null,
+        published: false,
+        createdTarget: false,
+    };
+    const onStage = (stage: PublicationStage): void => {
+        seams.onStage?.(stage);
+    };
+    try {
+        onStage("locked");
+        if (options.mode === "create") {
+            publishCreate(
+                target,
+                contents,
+                ledger,
+                seams.writeFull ?? writeFullBytes,
+                onStage,
+            );
+        } else {
+            const refusal = publishReplace(
+                target,
+                contents,
+                ledger,
+                options,
+                seams,
+            );
+            if (refusal !== null) {
+                return { reason: refusal };
+            }
+        }
+        return { revision: revisionOf(contents) };
+    } catch (error) {
+        const handled = publicationFailure(target, ledger, options, error);
+        if (handled !== null) {
+            return { reason: handled };
+        }
+        throw error;
+    } finally {
+        if (ledger.owned !== null) {
+            try {
+                unlinkSync(ledger.owned.path);
+            } catch {
+                // Owned temp may already be gone with its rename.
+            }
+        }
+        lock.release();
+    }
+}
+
+/**
+ * Handle one caught publication error: remove the partial file this
+ * operation created itself, translate the mapped refusal codes, and leave
+ * everything else for the caller to rethrow.
+ * @param target The absolute, guarded target path.
+ * @param ledger The claimed resources.
+ * @param options Publication options.
+ * @param options.label The qualified target label, for refusals.
+ * @param options.mode The mutation mode the write follows.
+ * @param error The caught error.
+ * @returns The refusal reason, or null to rethrow.
+ */
+function publicationFailure(
+    target: string,
+    ledger: PublicationLedger,
+    options: { label: string; mode: AddMode },
+    error: unknown,
+): string | null {
+    if (ledger.createdTarget && !ledger.published) {
+        // A create that opened `wx` then failed owns its own partial file;
+        // remove it, and never the rival's.
+        try {
+            unlinkSync(target);
+        } catch {
+            // Best effort; the failure already reports itself.
+        }
+    }
+    return publicationErrorRefusal(options.label, options.mode, error);
+}
+
+/** One other configured lake, for publishing's physical containment checks. */
+export interface Containment {
+    /** The other lake's identity and writability. */
+    lake: { name: string; root: string; writable: boolean };
+    /** The other lake's real (symlink-resolved) root. */
+    realRoot: string;
+}
+
+/**
+ * The refusal for a public write whose physical target reaches a nested
+ * lake's tree through the selected lake's route, or null. The owner is the
+ * deepest enclosing configured lake: addressing content physically inside
+ * another lake's root through an outer alias would mutate a subtree the outer
+ * lake never indexes, and a read-only owner's tree must not become writable
+ * by reaching it through a writable outer lake. Naming the correct owner
+ * leaves the caller one explicit re-address away.
+ * @param spec The selected lake being published through.
+ * @param target The absolute, guarded target path.
+ * @param others The other configured lakes' real roots.
+ * @returns The refusal reason, or null when the selected lake owns the tree.
+ */
+function containmentRefusal(
+    spec: LakeSpec,
+    target: string,
+    others: readonly Containment[],
+): string | null {
+    const own = realPathOf(spec.root);
+    const key = physicalTargetKey(target);
+    let deepest: Containment | undefined;
+    for (const other of others) {
+        if (other.realRoot === own) {
+            continue;
+        }
+        if (
+            isUnder(other.realRoot, own) &&
+            isUnder(key, other.realRoot) &&
+            (deepest === undefined || isUnder(other.realRoot, deepest.realRoot))
+        ) {
+            deepest = other;
+        }
+    }
+    if (deepest === undefined) {
+        return null;
+    }
+    const access = deepest.lake.writable
+        ? `address it through lake:'${deepest.lake.name}' so it lands in the tree that indexes that address`
+        : `its owner lake '${deepest.lake.name}' is read-only, so this content cannot be written`;
+    return (
+        `${REFUSE} the addressed file physically resolves inside lake ` +
+        `'${deepest.lake.name}' (${deepest.lake.root}; ` +
+        `${deepest.lake.writable ? "writable" : "read-only"}) — ${access}.`
+    );
+}
+
 /**
  * Attach the filesystem seams to a lake spec.
  * @param spec The configured lake.
  * @param options Runtime options.
  * @param options.skip Absolute roots of other lakes, so a nested lake is not
  * collected twice.
+ * @param options.containment The other lakes' real roots, for the publish
+ * containment guard; omitted by direct callers that carry one lake only.
+ * @param options.seams Injectable publication primitives; the real
+ * filesystem defaults are used when absent, and tests inject them to make
+ * collisions and failures deterministic.
  * @returns The lake the tool serves.
  */
 export function createLake(
     spec: LakeSpec,
-    options: { skip?: readonly string[] } = {},
+    options: {
+        skip?: readonly string[];
+        containment?: readonly Containment[];
+        seams?: PublicationSeams;
+    } = {},
 ): Lake {
     const guarded = (path: string): string => {
         const target = safeLakeTarget(spec.root, path);
@@ -2362,18 +3278,49 @@ export function createLake(
             mkdirSync(dirname(target), { recursive: true });
             writeFileSync(target, contents);
         },
+        publish: (path, contents, publishOptions) => {
+            const target = guarded(path);
+            if (!existsSync(spec.root)) {
+                return {
+                    reason: `lake '${spec.name}' root ${spec.root} does not exist; create it first.`,
+                };
+            }
+            if (options.containment !== undefined) {
+                const refusal = containmentRefusal(
+                    spec,
+                    target,
+                    options.containment,
+                );
+                if (refusal !== null) {
+                    return { reason: refusal };
+                }
+            }
+            return publishTarget(target, contents, {
+                ...publishOptions,
+                ...(options.seams !== undefined
+                    ? { seams: options.seams }
+                    : {}),
+            });
+        },
     };
 }
 
 /**
  * Build every configured lake, each aware of the others so a nested root is
- * collected once. Nesting is decided on real paths, so a symlinked root cannot
- * defeat containment: the skip paths handed to the walker are re-anchored
- * under the collecting lake's configured root.
+ * collected once and never published through an outer alias. Nesting is
+ * decided on real paths, so a symlinked root cannot defeat containment: the
+ * skip paths handed to the walker are re-anchored under the collecting lake's
+ * configured root.
  * @param specs The configured lakes.
+ * @param options Runtime options.
+ * @param options.seams The publication seams observed by every lake's
+ * guarded publication.
  * @returns The runtime lakes.
  */
-export function createLakes(specs: readonly LakeSpec[]): Lake[] {
+export function createLakes(
+    specs: readonly LakeSpec[],
+    options: { seams?: PublicationSeams } = {},
+): Lake[] {
     const realRoots = specs.map((spec) => realPathOf(spec.root));
     return specs.map((spec, index) => {
         const own = realRoots[index] ?? spec.root;
@@ -2386,13 +3333,63 @@ export function createLakes(specs: readonly LakeSpec[]): Lake[] {
                 ? [join(spec.root, relative(own, otherRoot))]
                 : [];
         });
-        return createLake(spec, { skip });
+        const containment: Containment[] = specs.flatMap(
+            (other, otherIndex) => {
+                if (otherIndex === index) {
+                    return [];
+                }
+                return [
+                    {
+                        lake: {
+                            name: other.name,
+                            root: other.root,
+                            writable: other.writable,
+                        },
+                        realRoot: realRoots[otherIndex] ?? other.root,
+                    },
+                ];
+            },
+        );
+        return createLake(spec, {
+            skip,
+            ...(containment.length > 0 ? { containment } : {}),
+            ...(options.seams !== undefined ? { seams: options.seams } : {}),
+        });
     });
 }
 
 /** The lake classes the configuration accepts. */
 export const LAKE_CLASSES = ["repo", "machine", "global", "wiki"] as const;
 
+/**
+ * The human-facing scope label per class, shown beside the config value in
+ * help and candidate lists so agents can connect the two. Configuration
+ * values never change: `repo`, `machine`, `global`, `wiki`.
+ */
+export const CLASS_LABELS: Readonly<Record<LakeClass, string>> = {
+    repo: "Repository",
+    machine: "Personal",
+    global: "Organisation",
+    wiki: "Wiki",
+};
+
+/**
+ * The ownership guidance for a class, used when a lake carries no configured
+ * description. Generic by design: domain-specific ownership is never inferred
+ * from a path or a name.
+ * @param lakeClass The lake's class.
+ * @returns The concise default guidance.
+ */
+export function classGuidance(lakeClass: LakeClass): string {
+    const guidance: Record<LakeClass, string> = {
+        repo: "knowledge needed to understand or maintain this repository",
+        machine: "knowledge tied to one person's devices, accounts and setup",
+        global: "organisation-wide standards, services and integrations",
+        wiki: "human-facing reference and narrative",
+    };
+    return guidance[lakeClass];
+}
+
 /** The repo-local lake additions file, relative to the location. */
 export const REPO_LAKES_FILE = ".opencode/docs-lakes.json";
 
@@ -2402,6 +3399,8 @@ export interface DocsPluginOptions {
     root?: unknown;
     /** The `root` lake's name; defaults to the root folder name. Needs `root`. */
     name?: unknown;
+    /** The `root` lake's description; what belongs there. Needs `root`. */
+    description?: unknown;
     /** Base lake declarations, merged after `lakesFile` and the repo file. */
     lakes?: unknown;
     /** A JSON file of base lakes (`{ "lakes": [...] }`). */
@@ -2511,6 +3510,7 @@ interface RawLake {
     root?: unknown;
     name?: unknown;
     writable?: unknown;
+    description?: unknown;
 }
 
 /** Narrow an unknown lake declaration to its raw shape. */
@@ -2629,6 +3629,27 @@ function lakeWritableOf(
     return writable;
 }
 
+/**
+ * Resolve a lake description: trimmed when present, absent when blank. A
+ * non-string fails loudly — a mistyped description must not become lake prose.
+ * @param entry The raw declaration.
+ * @param name The resolved lake name, for the error.
+ * @returns The trimmed description, or undefined when absent.
+ */
+function lakeDescriptionOf(entry: RawLake, name: string): string | undefined {
+    if (entry.description === undefined) {
+        return undefined;
+    }
+    if (typeof entry.description !== "string") {
+        throw new Error(
+            `docs plugin lake '${name}' description must be a string, ` +
+                `got ${JSON.stringify(entry.description)}.`,
+        );
+    }
+    const trimmed = entry.description.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+
 /**
  * Validate one raw lake declaration and resolve its defaults.
  * @param raw The raw entry from a config file or inline option.
@@ -2646,12 +3667,14 @@ function lakeSpecFrom(
     const lakeClass = lakeClassOf(entry, fromRepoFile);
     const root = lakeRootOf(entry, lakeClass, location, fromRepoFile);
     const name = lakeNameOf(entry, root, lakeClass);
+    const description = lakeDescriptionOf(entry, name);
     return {
         name,
         class: lakeClass,
         root,
         profile: lakeClass === "wiki" ? "wiki" : "knowledge",
         writable: lakeWritableOf(entry, lakeClass, name),
+        ...(description !== undefined ? { description } : {}),
     };
 }
 
@@ -2684,6 +3707,12 @@ function assertLakesOptions(options: DocsPluginOptions): void {
                 "set 'name' inside a 'lakes' entry instead.",
         );
     }
+    if (options.description !== undefined && options.root === undefined) {
+        throw new Error(
+            "docs plugin option 'description' describes the 'root' lake; " +
+                "set 'description' inside a 'lakes' entry instead.",
+        );
+    }
 }
 
 /** Map raw lake entries from a file to specs. */
@@ -2760,7 +3789,12 @@ export function resolveLakes(
     if (options.root !== undefined) {
         specs.push(
             lakeSpecFrom(
-                { class: "repo", root: options.root, name: options.name },
+                {
+                    class: "repo",
+                    root: options.root,
+                    name: options.name,
+                    description: options.description,
+                },
                 location,
                 false,
             ),
@@ -2887,7 +3921,37 @@ function nestingDepth(lake: Lake, lakes: readonly Lake[]): number {
     }).length;
 }
 
-/** The lake `add` writes to, or the refusal reason. */
+/**
+ * One candidate line for a destination refusal: name, scope label beside the
+ * config value, root, availability, and the configured description or the
+ * class guidance — everything an agent needs to choose deliberately.
+ * @param lake The candidate lake.
+ * @returns The rendered line.
+ */
+function candidateLine(lake: Lake): string {
+    const label = `${CLASS_LABELS[lake.class]} [${lake.class}]`;
+    const missing = lakeMissing(lake) ? " — missing root" : "";
+    const description = lake.description ?? classGuidance(lake.class);
+    return `- ${lake.name} (${label}): ${lake.root}${missing} — ${description}`;
+}
+
+/**
+ * The lake `add` writes to, or the refusal reason.
+ *
+ * An explicit name selects that exact lake or refuses — read-only, unknown
+ * and (later, in `addDoc`) missing-root lakes never fall back elsewhere.
+ * With `lake` omitted the write needs exactly one deliberate destination: the
+ * sole configured writable knowledge lake. When two or more writable
+ * knowledge lakes are configured the omission refuses with every candidate —
+ * nesting, class, configuration order and current root existence change
+ * nothing, because folder depth cannot infer the semantic owner of a claim.
+ * Nesting still resolves the physical owner of an already named target (see
+ * {@link uniqueHolder} and the publication containment guard); destination
+ * choice and physical ownership are deliberately separate decisions.
+ * @param lakes The configured lakes.
+ * @param name The explicit lake selector, when given.
+ * @returns The target lake, or the refusal reason.
+ */
 function writableLake(
     lakes: readonly Lake[],
     name: string | undefined,
@@ -2904,34 +3968,26 @@ function writableLake(
         }
         return lake;
     }
-    // The narrowest writable knowledge lake wins: with nested roots the inner
-    // lake owns the file, so an outer read-only lake must not hijack the write.
-    const repos = lakes.filter(
-        (lake) => lake.class === "repo" && lake.writable,
+    const pool = lakes.filter(
+        (lake) => lake.profile === "knowledge" && lake.writable,
     );
-    const pool =
-        repos.length > 0
-            ? repos
-            : lakes.filter(
-                  (lake) => lake.profile === "knowledge" && lake.writable,
-              );
     if (pool.length === 0) {
         return {
             reason:
                 `${REFUSE} no writable knowledge lake is configured; ` +
-                "add a repo, machine, or global lake.",
+                "wiki and read-only lakes are never written — add a repo, " +
+                "machine or global lake.",
         };
     }
-    let target = pool[0] as Lake;
-    let depth = nestingDepth(target, lakes);
-    for (const candidate of pool.slice(1)) {
-        const candidateDepth = nestingDepth(candidate, lakes);
-        if (candidateDepth > depth) {
-            target = candidate;
-            depth = candidateDepth;
-        }
+    if (pool.length > 1) {
+        return {
+            reason:
+                `${REFUSE} ${pool.length} writable knowledge lakes could ` +
+                "take this write; pass lake — one of:\n" +
+                pool.map((lake) => candidateLine(lake)).join("\n"),
+        };
     }
-    return target;
+    return pool[0] as Lake;
 }
 
 /** Qualify a path with its lake when more than one lake is configured. */
@@ -3093,55 +4149,267 @@ function checkLakes(
     return { content: assembleCheck(reports, skipped), checked };
 }
 
-/** Add a doc to the target lake. */
-function addDoc(
-    runtime: Runtime,
-    add: DocsAdd,
+/**
+ * The refusal for a legacy-seam write whose target is in the wrong state:
+ * a create whose target exists (never an implicit overwrite), a replace whose
+ * target vanished (never an implicit create), or a replace whose current
+ * bytes no longer match the caller's `expectedRevision`. Legacy closure
+ * seams cannot exclude other processes, so this route is in-process only.
+ * @param target The lake the write lands in.
+ * @param outcome The prepared write.
+ * @param outcome.mode The mutation mode the write follows.
+ * @param outcome.path The root-relative target path.
+ * @param expected The caller's revision token, when replacing.
+ * @param labelled The qualified target label, for refusals.
+ * @returns The refusal, or null when the target state allows the write.
+ */
+function legacyPublicationRefusal(
+    target: Lake,
+    outcome: { mode: AddMode; path: string },
+    expected: string | undefined,
+    labelled: string,
+): string | null {
+    const present = target.exists(outcome.path);
+    if (outcome.mode === "create") {
+        return present
+            ? `${REFUSE} ${labelled} already exists — read it and pass ` +
+                  'mode:"replace" to overwrite it deliberately.'
+            : null;
+    }
+    if (!present) {
+        return (
+            `${REFUSE} no doc at ${labelled} — replace never creates; ` +
+            'pass mode:"create" for a new doc.'
+        );
+    }
+    const found = revisionOf(target.read(outcome.path));
+    return found === expected
+        ? null
+        : `${REFUSE} ${labelled} changed since you read it (expected ` +
+              `${(expected ?? "none").slice(0, 12)}, found ` +
+              `${found.slice(0, 12)}). Read it again, reconcile, and ` +
+              "resubmit the replacement deliberately.";
+}
+
+/**
+ * The lake a write lands in, with its root verified present: the destination
+ * refusal ({@link writableLake}) plus the dormant-root refusal in one step, so
+ * a mistyped root never bootstraps a tree.
+ * @param lakes The configured lakes.
+ * @param lakeName The explicit lake selector, when given.
+ * @returns The verified lake, or the refusal reason.
+ */
+function writeTarget(
+    lakes: readonly Lake[],
     lakeName: string | undefined,
-): { content: string; written: boolean } {
-    const target = writableLake(runtime.lakes, lakeName);
+): Lake | { reason: string } {
+    const target = writableLake(lakes, lakeName);
     if ("reason" in target) {
-        return { content: target.reason, written: false };
+        return target;
     }
-    // A typo'd root must not bootstrap a new tree; the area directories below
-    // an existing root still create on write.
     if (target.root !== "" && !existsSync(target.root)) {
         return {
-            content:
+            reason:
                 `${REFUSE} lake '${target.name}' root ${target.root} does ` +
                 "not exist — create it first.",
-            written: false,
         };
     }
-    const entries = target.collect();
-    const outcome = prepareAdd(add, entries, {
-        maxDocLines: runtime.maxDocLines,
-    });
-    if (outcome.action === "refuse") {
-        return { content: outcome.reason, written: false };
-    }
-    let updated: boolean;
+    return target;
+}
+
+/**
+ * Publish a prepared write through a legacy lake's plain write seam,
+ * translating the seam's path-safety error into a refusal.
+ * @param target The lake the write lands in.
+ * @param outcome The prepared write.
+ * @param outcome.path The root-relative target path.
+ * @param outcome.contents The serialised file contents.
+ * @returns The refusal on an unsafe path, or null once written.
+ */
+function publishLegacy(
+    target: Lake,
+    outcome: { path: string; contents: string },
+): string | null {
     try {
-        updated = target.exists(outcome.path);
         target.write(outcome.path, outcome.contents);
     } catch (error) {
         if (error instanceof UnsafePathError) {
-            return {
-                content: `${REFUSE} ${error.message}`,
-                written: false,
-            };
+            return `${REFUSE} ${error.message}`;
+        }
+        throw error;
+    }
+    return null;
+}
+
+/**
+ * Publish through a lake's guarded protocol seam, translating its path-safety
+ * error into a refusal.
+ * @param publish The lake's publication seam.
+ * @param outcome The prepared write.
+ * @param outcome.mode The mutation mode the write follows.
+ * @param outcome.path The root-relative target path.
+ * @param outcome.contents The serialised file contents.
+ * @param expected The caller's revision token, when replacing.
+ * @param label The qualified target label, for refusals.
+ * @returns The new revision, or the refusal reason.
+ */
+function guardedPublish(
+    publish: NonNullable<Lake["publish"]>,
+    outcome: { mode: AddMode; path: string; contents: string },
+    expected: string | undefined,
+    label: string,
+): { revision: string } | { reason: string } {
+    try {
+        return publish(outcome.path, outcome.contents, {
+            mode: outcome.mode,
+            expectedRevision: expected,
+            label,
+        });
+    } catch (error) {
+        if (error instanceof UnsafePathError) {
+            return { reason: `${REFUSE} ${error.message}` };
         }
         throw error;
     }
-    const head = `${address(target, outcome.path, runtime.lakes)} — ${
-        updated ? "updated" : "created"
-    }.`;
+}
+
+/**
+ * The one-line success report: the qualified target, the outcome, and an
+ * override note when a near-twin was crossed deliberately.
+ * @param outcome The prepared write.
+ * @param outcome.mode The mutation mode the write follows.
+ * @param label The qualified target label.
+ * @param overridden Whether a near-twin override was used.
+ * @returns The report head.
+ */
+function successHead(
+    outcome: { mode: AddMode },
+    label: string,
+    overridden: boolean,
+): string {
+    return (
+        `${label} — ${outcome.mode === "replace" ? "replaced" : "created"}.` +
+        (overridden ? " near-twin overridden." : "")
+    );
+}
+
+/**
+ * The success metadata: the written flag, the resolved lake and path, and the
+ * new content revision when the route produced one.
+ * @param target The lake the write landed in.
+ * @param outcome The prepared write.
+ * @param outcome.path The root-relative target path.
+ * @param revision The new revision, when the route produced one.
+ * @returns The metadata object.
+ */
+function successMetadata(
+    target: Lake,
+    outcome: { path: string },
+    revision: string | undefined,
+): Record<string, unknown> {
+    return {
+        written: true,
+        lake: target.name,
+        path: outcome.path,
+        ...(revision !== undefined ? { revision } : {}),
+    };
+}
+
+/**
+ * Publish a prepared write through the target lake's route: real lakes use
+ * the guarded {@link publishTarget} protocol (lock, re-verify, atomic
+ * publish); legacy closure lakes fall back to the plain seam with the same
+ * contracts, in-process only.
+ * @param target The verified destination lake.
+ * @param outcome The prepared write.
+ * @param outcome.mode The mutation mode the write follows.
+ * @param outcome.path The root-relative target path.
+ * @param outcome.contents The serialised file contents.
+ * @param expected The caller's revision token, when replacing.
+ * @param label The qualified target label, for refusals.
+ * @returns The new revision, or the refusal reason.
+ */
+function publishPrepared(
+    target: Lake,
+    outcome: {
+        /** The mutation mode the write follows. */
+        mode: AddMode;
+        /** The root-relative target path. */
+        path: string;
+        /** The serialised file contents. */
+        contents: string;
+    },
+    expected: string | undefined,
+    label: string,
+): { revision?: string; reason?: string } {
+    if (target.publish !== undefined) {
+        const result = guardedPublish(target.publish, outcome, expected, label);
+        return "reason" in result
+            ? { reason: result.reason }
+            : { revision: result.revision };
+    }
+    const legacy = legacyPublicationRefusal(target, outcome, expected, label);
+    if (legacy !== null) {
+        return { reason: legacy };
+    }
+    const unsafe = publishLegacy(target, outcome);
+    return unsafe === null ? {} : { reason: unsafe };
+}
+
+/**
+ * Add a doc to the target lake through its publication route: real lakes use
+ * the guarded {@link publishTarget} protocol (lock, re-verify, atomic
+ * publish); legacy closure lakes fall back to the plain seam with the same
+ * contracts, in-process only.
+ * @param runtime The resolved runtime.
+ * @param add The typed request.
+ * @param lakeName The explicit lake selector, when given.
+ * @returns The result content, written flag and success metadata.
+ */
+function addDoc(
+    runtime: Runtime,
+    add: DocsAdd,
+    lakeName: string | undefined,
+): {
+    content: string;
+    written: boolean;
+    metadata?: Record<string, unknown>;
+} {
+    const target = writeTarget(runtime.lakes, lakeName);
+    if ("reason" in target) {
+        return { content: target.reason, written: false };
+    }
+    const entries = target.collect();
+    const outcome = prepareAdd(add, entries, {
+        maxDocLines: runtime.maxDocLines,
+    });
+    if (outcome.action === "refuse") {
+        return { content: outcome.reason, written: false };
+    }
+    const label = address(target, outcome.path, runtime.lakes);
+    const expected = add.expectedRevision?.trim();
+    const published = publishPrepared(target, outcome, expected, label);
+    if (published.reason !== undefined) {
+        return { content: published.reason, written: false };
+    }
+    const revision = published.revision;
+    const head = successHead(
+        outcome,
+        label,
+        outcome.mode === "create" && overrideGiven(add),
+    );
     // The path and outcome are the answer; a list of same-area neighbours was
     // unsolicited context that grew with the area and was picked by collection
     // order, not relevance. Refusals still carry their candidates.
     const notes =
         outcome.notes.length > 0 ? `\n\n${outcome.notes.join("\n")}` : "";
-    return { content: `${head}${notes}`, written: true };
+    return {
+        content:
+            `${head}${notes}` +
+            (revision !== undefined ? revisionNote(revision, true) : ""),
+        written: true,
+        metadata: successMetadata(target, outcome, revision),
+    };
 }
 
 /** A parsed read request: the lake (when known) and the path. */
@@ -3222,7 +4490,13 @@ function readDoc(
     runtime: Runtime,
     given: string,
     lakeName: string | undefined,
-): { content: string; read: string | null } {
+): {
+    content: string;
+    read: string | null;
+    lake?: string;
+    path?: string;
+    revision?: string;
+} {
     const target = readTargetOf(runtime, given, lakeName);
     if (target.reason !== undefined) {
         return { content: target.reason, read: null };
@@ -3251,12 +4525,45 @@ function readDoc(
     const raw = selected.read(guarded.path);
     const { body } = parseFrontMatter(raw);
     const label = address(selected, guarded.path, runtime.lakes);
+    const revision =
+        selected.profile === "knowledge" ? revisionOf(raw) : undefined;
     return {
-        content: `${label} — ${titleOf(guarded.path, body)}\n\n${raw}`,
+        content:
+            `${label} — ${titleOf(guarded.path, body)}\n\n${raw}` +
+            (revision !== undefined ? revisionNote(revision, false) : ""),
         read: label,
+        lake: selected.name,
+        path: guarded.path,
+        // Wiki pages are read-only reference and promise no write-capable
+        // revision workflow; knowledge docs carry their content hash.
+        ...(revision !== undefined ? { revision } : {}),
     };
 }
 
+/**
+ * The model-facing revision note: the one line that makes an optimistic-
+ * concurrency token visible through every real host path, stored per-call
+ * metadata kept alongside it for UI and programmatic callers. Host evidence
+ * (opencode v2.2.5): a plugin tool's result reaches the model only through its
+ * `content` — `Session.Tool.Success` persists metadata as optional UI data,
+ * the model-facing lowering (`to-llm-message.ts` → `toolResult()`) serialises
+ * only `content`, and the Code Mode twin's `resultValue()` drops `metadata`
+ * for tools without an output schema. Content text is the one channel both
+ * surfaces forward, so the token rides it. The note sits after an explicit
+ * blank separator, never inside the verbatim document body.
+ * @param revision The content's SHA-256 revision.
+ * @param fresh False for a caller's read; true when a replacement just
+ * published these bytes.
+ * @returns The note text with its leading blank-line separator.
+ */
+function revisionNote(revision: string, fresh: boolean): string {
+    return (
+        `\n\ndocs: revision ${revision} — ` +
+        (fresh ? "the newly published bytes" : "these bytes") +
+        "; cite it as expectedRevision when replacing (a stale token refuses)."
+    );
+}
+
 /** The lake help view shared by the tool and command. */
 function lakeInfo(lakes: readonly Lake[]): LakeInfo[] {
     return lakes.map((lake) => ({
@@ -3266,6 +4573,9 @@ function lakeInfo(lakes: readonly Lake[]): LakeInfo[] {
         writable: lake.writable,
         validated: lakeValidated(lake),
         missing: lakeMissing(lake),
+        ...(lake.description !== undefined
+            ? { description: lake.description }
+            : {}),
     }));
 }
 
@@ -3308,7 +4618,7 @@ function executeRequest(runtime: Runtime, input: DocsInput): Result {
         const result = addDoc(runtime, request.add, request.lake);
         return {
             content: result.content,
-            metadata: { written: result.written },
+            metadata: result.metadata ?? { written: result.written },
         };
     }
     if (request.verb === "check") {
@@ -3322,7 +4632,14 @@ function executeRequest(runtime: Runtime, input: DocsInput): Result {
         const result = readDoc(runtime, request.read, request.lake);
         return {
             content: result.content,
-            metadata: { read: result.read },
+            metadata: {
+                read: result.read,
+                ...(result.lake !== undefined ? { lake: result.lake } : {}),
+                ...(result.path !== undefined ? { path: result.path } : {}),
+                ...(result.revision !== undefined
+                    ? { revision: result.revision }
+                    : {}),
+            },
         };
     }
     if (request.verb === "help") {
@@ -3372,12 +4689,13 @@ export function createDocsTool(
         description: codemode
             ? TWIN_DESCRIPTION
             : "Search the configured knowledge lakes and nested project " +
-              "`README.md` files before a broad grep for how-to knowledge, " +
-              "decisions or known problems. A blank search lists recent docs; " +
-              "`help` shows the lakes and ranking. `read` returns a lake doc " +
-              "verbatim; project `instructions:` results open with the built-in " +
-              "read tool. `add` writes or replaces a knowledge doc; `check` " +
-              "audits convention compliance.",
+              "`README.md` files before a broad grep for how-to knowledge. " +
+              "A blank search lists recent docs; `help` shows the lakes and " +
+              "ranking. `read` returns a lake doc verbatim plus its " +
+              "revision token; `instructions:` results open with the " +
+              "built-in read tool. `add` creates or replaces a knowledge " +
+              "doc (replace needs that revision); `check` audits " +
+              "convention compliance.",
         input: DOCS_INPUT,
         options: codemode
             ? { namespace: "docs", codemode: true }
@@ -3406,8 +4724,9 @@ function addPrompt(subject: string): string {
     }
     return (
         "Record this as durable knowledge in the docs lakes: call the `docs` " +
-        "tool's `add` with a typed DTO (metadata Area/Keywords/Summary, body starting " +
-        "with an H1) for:\n\n" +
+        'tool\'s `add` with a typed DTO — mode:"create" for a new doc, ' +
+        "metadata (Area/Keywords/Summary) and a body starting with an H1 — " +
+        "for:\n\n" +
         subject
     );
 }
@@ -3673,9 +4992,9 @@ export default Plugin.define({
                     "Entry point to the configured knowledge lakes " +
                     "(repo, machine, global, read-only wiki) and nested project " +
                     "README.md files: find and read the right doc, then record " +
-                    "focused knowledge at the narrowest true scope. Use before " +
-                    "searching the codebase for how-to knowledge, or when a " +
-                    "session learns something durable.",
+                    "focused knowledge at the narrowest justified scope. Use " +
+                    "before searching the codebase for how-to knowledge, or " +
+                    "when a session learns something durable.",
                 path: AbsolutePath.make(fileURLToPath(skillURL)),
                 content: skill,
             });