@markstanden/opencode-docs-plugin 0.5.0 → 0.6.0

package/CONVENTION.md

@@ -53,11 +53,11 @@ are skipped by name.
 Every knowledge doc opens with a `---` front-matter block. The fields, in
 canonical order:
 
-| Field      | Required | Meaning                                                                 |
-| ---------- | -------- | ----------------------------------------------------------------------- |
-| `Area`     | yes      | One top-level path segment; the doc's group.                            |
-| `Keywords` | yes      | Comma-separated search terms; the second half of the doc's identity.    |
-| `Summary`  | yes      | One self-contained sentence: enough to decide whether to open the file. |
+| Field      | Required | Meaning                                                                                                     |
+| ---------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `Area`     | yes      | One top-level path segment; the doc's group.                                                                |
+| `Keywords` | yes      | Comma-separated search terms; the second half of the doc's identity.                                        |
+| `Summary`  | yes      | One self-contained sentence that lets a reader decide whether to open the file — not a second introduction. |
 
 `Date` is **derived, never written**: the file's last git commit date, falling
 back to mtime. A hand-maintained `Date` is a finding, not a field.
@@ -79,6 +79,12 @@ git. Optional invisible metadata may be added later; it is not required.
 - At least one claim section as an `H2`/`H3` heading — `Facts`, `Inferred`,
   `Tested`, `Failed approaches`, `Open questions` — so a reader knows how much
   to rely on each claim. Group claims by section rather than mixing them.
+- Include only the sections the doc actually needs. An empty heading is noise;
+  leave it out.
+- Write so the next reader decides fast: lead with the actionable fact, include
+  its reason, limits and evidence where they affect its use, and omit discovery
+  chronology, repeated conclusions and empty sections. Under `Tested`, record
+  the check, its result and the conditions that mattered.
 - A failed attempt is a valid current doc or section: state what was tried, why
   it failed, what is true now, and what not to retry. Do not keep a doc whose
   claims are no longer true.
@@ -92,6 +98,11 @@ git. Optional invisible metadata may be added later; it is not required.
   `add` refuses a near-twin write and returns the candidates to reconcile
   against — edit before add, merge near-twins, split a bloated doc into
   per-topic files.
+- The reconcile applies to a **create**: with `path` omitted, the target is
+  derived and the near-twin guard runs. An explicit `path` is the update
+  contract and skips it, which is how you replace a doc in place. Passing an
+  explicit _new_ path is therefore a deliberate override, not a protected
+  write.
 - Near-twins are per lake. The same topic at repo and global scope is
   legitimate; the narrower doc states its delta and links up.
 
@@ -129,7 +140,12 @@ knowledge when it records the outcome and the current truth.
 
 ## Adopting it
 
-Run `check` to audit an existing tree, and the gate's `defined comply` before
-proposing a commit. A missing lake root is a note, not an error: the plugin
-scans what is there and reports per-doc findings for what is not. Wiki lakes
-are read-only and are reported as not validated, never silently skipped.
+Run `check` to audit an existing tree, and the project's own tests before
+proposing a commit. `add` enforces the per-doc structural rules at the write
+boundary — front-matter, `H1`, claim section, identity term floor, and the
+near-twin guard on a create — while the cross-document audits (near-twin pairs
+and relative links) stay with `check`. A missing lake root is a note, not an
+error: the plugin scans what is there, search and help flag the absent path, and
+`add` refuses rather than creating a tree at a mistyped root. Create the
+directory deliberately. Wiki lakes are read-only and are reported as not
+validated, never silently skipped.

package/README.md

@@ -80,7 +80,7 @@ The simplest setup uses `root` — one repo lake:
         {
             "package": "@markstanden/opencode-docs-plugin",
             "options": {
-                "root": "~/doclake",
+                "root": "./docs",
             },
         },
     ],
@@ -159,6 +159,12 @@ Lake paths never follow symlinks: a symlinked doc is skipped by search and
 `check`, refused by `read`, and refused by `add`. The configured `root` itself
 may be a symlink; the content beneath it must be real.
 
+A missing lake root is flagged, never created. The lake stays dormant until the
+directory exists: `search` appends a note naming the lake and path, `help` marks
+it `— missing`, and `add` refuses with the path rather than bootstrapping a
+tree. Create the directory deliberately. Area folders beneath an existing root
+are still created on write.
+
 `maxDocLines` (default 200, `0` disables) is a **soft** note on a long doc, not a
 refusal. `perLakeQuota` (default 3, `0` disables) is the per-source result
 reservation.
@@ -195,7 +201,6 @@ Standalone extract of the docs tooling, under active development.
 npm install
 npm test          # node --test
 npm run typecheck
-defined comply    # the gate: bootstrap, repair and verify
 ```
 
 Tests run the plugin source directly under Node's type-stripping (`noEmit`,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "type": "module",
     "description": "OpenCode V2 plugin: a `docs` tool and `/docs` command over configurable knowledge lakes (repo, machine, global and read-only wiki), nested README.md search, and the writing convention they share",
     "repository": {

package/src/SKILL.md

@@ -1,13 +1,8 @@
 # Docs
 
-Durable knowledge lives in **lakes**. The plugin reads every configured lake
-and the project's nested `README.md` files. This skill covers both halves of the
-loop: **find** (search, then read) and **record** (write or update a focused
-doc at the narrowest true scope).
-
-Call the `docs` tool at top level. Inside `execute` (Code Mode) the same tool
-is reachable as the twin `tools.docs.docs_search(…)` — same verbs, same lakes —
-so batch it with the rest of the catalog there.
+Durable knowledge lives in **lakes**: **find** it (search, then read), or
+**record** one focused doc at the narrowest true scope. Call the `docs` tool;
+inside `execute` it is `tools.docs.docs_search(…)`, same verbs.
 
 ## Classes
 
@@ -20,98 +15,60 @@ so batch it with the rest of the catalog there.
 | **Wiki**           | human-readable wiki         | narrative for humans                    | read-only     |
 
 Record at the **narrowest scope where the whole claim is true**. Two scopes
-means two focused docs. Never one omnibus doc that is out of place.
+means two docs; one omnibus doc is out of place everywhere.
 
 ## Find it
 
-Call the `docs` tool:
-
-- **blank `search`** — the most recently changed docs, one line per doc
-  (`path — Area — date — Summary`).
-- **a `search`** — docs ranked over title, path, keywords, body headings and
-  code spans, area, summary and wiki prose. When no doc contains every term it
-  returns the closest matches under a `Closest matches` header rather than a
-  dead end. A term must appear as a **substring** to match — a typo returns
-  nothing, by design. Terms shorter than `MIN_TERM_LENGTH` (3) are ignored
-  unless they are the whole query.
-- **every call** reserves up to `perLakeQuota` results per source (default 3),
-  caps at `MAX_RESULTS` (10), and ends with `… and N more not shown.` when
-  anything was cut. The reservation keeps a broad wiki from burying a focused
-  repo doc.
-- **exactly `help`** — the configured lakes, their classes and writability,
-  then the ranking rules.
-
-Then open the match with the tool's `read` verb — pass the root-relative path,
-or `lake:path` when several lakes are configured. A project README result is
-prefixed `instructions:`; read it with the built-in `read` tool instead.
-`/docs [search]` runs the same search into the session (`/docs search <text>` is
-the explicit form).
-
-Every `*.md` under a knowledge lake is covered except the excluded areas —
-scratch (`plans/`) and vendored mirrors (`requirements/`, `wiki/`). `Area` comes
-from the path, `date` from git. Wiki lakes are read-only; their pages are
-indexed as prose and tables, and their summaries are derived from the first
-paragraph. A README is search-only, rendered as `instructions:path`, and is
-never validated.
-
-## Read it
-
-- Consult matching docs before a broad grep: they are the curated knowledge.
-- Class precedence on a tie is repo, instructions, global, machine, wiki. A
-  non-primary lake is prefixed (`global:platform/regions.md`,
-  `wiki:Integrations/Billing.md`).
-- A `Summary` is a self-contained sentence — enough to decide whether to open
-  the file.
+A **blank `search`** lists recent docs, one line each; a **`search`** ranks
+them, falling back to `Closest matches` and matching terms as **substrings** —
+so a typo finds nothing and terms under `MIN_TERM_LENGTH` (3) are ignored.
+`help` lists the lakes and ranking.
 
-## Record it
+Open the match with `read`: the root-relative path, or `lake:path` when several
+lakes exist. A README result is `instructions:path` and opens with the built-in
+`read`. Consult matching docs before a broad grep; a tie ranks repo,
+instructions, global, machine, wiki. Excluded areas: `plans/`, `requirements/`
+and `wiki/`.
 
-Write durable findings and task documentation to `<area>/<title>.md` under the
-right lake so the next human or agent skips the rediscovery. The convention is
-this plugin's `CONVENTION.md`, restated here.
+## Record it
 
-Before writing:
+Write to `<area>/<title>.md` under the right lake; `CONVENTION.md` is
+authoritative.
 
-1. **Read first, never duplicate.** Search the tree and read the docs relevant
-   to the task: the same `<area>/` neighbourhood, keyword hits on the task's
-   entities (service names, file paths, error strings, class names), or links
-   from touched docs.
-2. **Choose one class.** Repo-specific goes to RepoContext. Personal setup goes
-   to MachineContext. Cross-repo org knowledge goes to GlobalContext. How-to
-   commands stay in the README. Human narrative goes to the wiki, read-only.
+1. **Read first, never duplicate.** Read the docs relevant to the task: the same
+   area, keyword hits on its entities, or links from touched docs.
+2. **Choose one class** from the table — the narrowest that holds the claim.
 3. **Reconcile, then add.** Edit before add; merge near-twins; split a bloated
-   doc into per-topic files; after any split, merge or move, grep for inbound
-   references and repoint them. Delete the emptied doc — no superseded stubs.
-
-One artifact per topic, one class per artifact: a session's findings land as
-several focused docs, never one session dump — a compaction nudge hands you
-`Record with docs add:` blocks already shaped for this.
-
-Then record through the `docs` tool's typed `add`: metadata (`Area`, `Keywords`
-as a list, `Summary`) plus a body carrying an `H1` and a claim section (`Facts`,
-`Inferred`, `Tested`, `Failed approaches`, `Open questions`). The tool
-serialises the front-matter — never copy it — and derives the target
-(`<Area>/<slug>.md`) when `path` is omitted; pass `path` to update an existing
-doc, replacing its body wholesale. Its guardrails refuse blank metadata, path
-traversal, a body without an `H1`, a read-only wiki lake, and a same-area
-near-twin (returning the candidates to reconcile against).
-
-A doc is current or deleted. There is no `Status` or `Supersedes` field. A
-failed attempt is valid knowledge when it records what was tried, why it failed,
-what is true now, and what not to retry. `check` reports the old fields as
-obsolete notes so a lake can be cleaned once.
+   doc per topic; after a split, merge or move, repoint inbound references and
+   delete the emptied doc — no superseded stubs.
+
+One artifact per topic and class, never one dump; the compaction nudge shapes
+`Record with docs add:` blocks for this.
+
+Record through the typed `add`: metadata (`Area`, `Keywords`, `Summary`) and a
+body with an `H1` and a claim section — Facts, Inferred, Tested, Failed approaches, Open questions. Omit `path` to create `<Area>/<slug>.md`; pass `path` to replace **wholesale**, so omitted body content is lost and the near-twin reconcile is skipped. Refused: blank metadata, traversal, a non-`.md` or symlinked target, no claim section, and — only when `path` is omitted — a same-area near-twin.
+
+A doc is current or deleted; no `Status` or `Supersedes`. A failed attempt is
+valid knowledge when it records what was tried, why it failed, what is true now,
+and what not to retry.
+
+Lead with the actionable fact, keeping the reason, limits and evidence that
+affect using it; drop chronology, repeated conclusions and empty sections. Keep
+the service names, errors, paths and commands someone will search for. A
+`Summary` decides whether to open the file.
+
+Never record secrets, credentials, tokens or customer data — name the vault or
+variable, never the value — and no personal data in GlobalContext or Wiki.
 
 ## Check it
 
-To audit the knowledge lakes instead of writing them, call the tool's `check`
-(`/docs check` runs it into the session): it validates required front-matter, an
-`H1`, at least one claim section, no hand-maintained `Date`, an `H1`+`Keywords`
-identity with a term of `MIN_TERM_LENGTH` (3) or longer, same-area near-twins,
-and broken relative `.md` links. Obsolete fields, long docs and unversioned or
-missing roots are **notes**, not findings. Wiki lakes are read-only and are
-reported as not validated. `add` enforces the same structural rules at the
-trust boundary.
-
-Finally, run the repo's gate (`defined comply` where `.defined.json` exists,
-else what its README documents) before proposing a commit. Fix failures; never
-paper over a red gate with a docs commit. Prepare the commit and **wait for
+`check` audits the lakes: front-matter, an `H1`, a claim section, no
+hand-maintained `Date`, a distinctive identity, near-twins and broken relative
+links. Obsolete fields, long docs and missing roots are **notes**, not findings;
+wiki lakes are not validated. `add` enforces the structural rules at the write
+boundary; cross-document audits stay with `check`. `maxDocLines` (default 200,
+`0` disables) is a soft size signal, not a refusal.
+
+Run the project's tests and typecheck before proposing a commit, fixing
+failures rather than papering over them. Prepare the commit and **wait for
 explicit approval** — recording findings is not commit approval. Never push.

package/src/index.ts

@@ -89,13 +89,13 @@ export const DOCS_INPUT = Schema.Struct({
     search: Schema.optional(
         Schema.String.annotate({
             description:
-                "Case-insensitive search over title, path, keywords, body headings and code spans, area, summary and wiki prose. Omit or leave blank to list the most recently changed docs; a partial match returns the closest docs.",
+                "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.",
         }),
     ),
     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 every lake, read the unique match, or add to the first writable repo lake.",
         }),
     ),
     add: Schema.optional(
@@ -103,7 +103,7 @@ export const DOCS_INPUT = Schema.Struct({
             path: Schema.optional(
                 Schema.String.annotate({
                     description:
-                        "Update target, e.g. `guides/getting-started.md` (relative to the lake root). Omit to create `<Area>/<slug>.md` from the H1.",
+                        "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.",
                 }),
             ),
             metadata: Schema.Struct({
@@ -112,27 +112,27 @@ export const DOCS_INPUT = Schema.Struct({
                 Summary: Schema.String,
             }).annotate({
                 description:
-                    "Front-matter metadata; serialised, never copied. All three fields are required and must not be blank.",
+                    "Front-matter metadata; serialised, never copied. All three are required and must not be blank.",
             }),
             body: Schema.String.annotate({
                 description:
-                    "Markdown body: an H1, then the claim sections (Facts / Inferred / Tested / Failed approaches / Open questions).",
+                    "Markdown body: an H1 title, plus at least one 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`. Blank required metadata, path traversal, a non-.md target, a symlinked target, and a same-area near-twin (when `path` is omitted) are all refused. Wiki lakes are read-only.",
+                "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.",
         }),
     ),
     check: Schema.optional(
         Schema.Boolean.annotate({
             description:
-                "Validate every knowledge doc against the convention: required front-matter, an H1, claim sections, no hand-maintained Date, a distinctive H1+Keywords identity, same-area near-twins, broken relative links, and a soft length note. Wiki lakes and READMEs are not validated.",
+                "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. Wiki lakes and READMEs are not validated.",
         }),
     ),
     read: Schema.optional(
         Schema.String.annotate({
             description:
-                "A root-relative doc path, or `lake:path`, to return verbatim — front-matter and body — so find-then-read is one call. Lake docs and wiki pages only: project READMEs stay with the built-in `read` tool.",
+                "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.",
         }),
     ),
 });
@@ -844,6 +844,8 @@ export interface LakeInfo {
     writable: boolean;
     /** Whether `check` validates it. */
     validated: boolean;
+    /** Whether the root is absent, so the lake contributes nothing yet. */
+    missing?: boolean;
 }
 
 /**
@@ -857,8 +859,9 @@ export function helpText(lakes: readonly LakeInfo[]): string {
     for (const lake of lakes) {
         const access = lake.writable ? "writable" : "read-only";
         const checked = lake.validated ? "checked" : "not checked";
+        const missing = lake.missing === true ? " — missing" : "";
         lines.push(
-            `- ${lake.name} (${lake.class}, ${access}, ${checked}): ${lake.root}`,
+            `- ${lake.name} (${lake.class}, ${access}, ${checked}): ${lake.root}${missing}`,
         );
     }
     lines.push(
@@ -1319,7 +1322,11 @@ export type AddOutcome =
           path: string;
           /** The serialised file contents. */
           contents: string;
-          /** Same-area docs already on disk, shown alongside the write. */
+          /**
+           * Same-area docs already on disk. Not rendered in the tool result —
+           * the success path names the path and outcome only — but retained for
+           * programmatic callers that want the surrounding context.
+           */
           neighbours: readonly DocEntry[];
           /** Soft advisory lines (e.g. a long doc worth splitting). */
           notes: readonly string[];
@@ -1526,6 +1533,14 @@ export function prepareAdd(
     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.",
+        );
+    }
     if (!hasDistinctiveIdentity(reconcileQuery(add))) {
         return refuse(
             `the H1 and Keywords together carry no term of MIN_TERM_LENGTH ` +
@@ -1589,6 +1604,24 @@ export const CLAIM_SECTIONS = [
     "Open questions",
 ] as const;
 
+/**
+ * Whether a body carries at least one recognisable claim section as an H2/H3
+ * heading. This is the one rule {@link prepareAdd} and {@link validateDoc}
+ * share, so `add` cannot accept a doc that `check` would immediately flag.
+ *
+ * It reads through {@link scanBody}, so a fenced code block or an inline code
+ * span cannot masquerade as a section, and a `# H1` or `#### H4` does not
+ * satisfy it.
+ * @param body Markdown body, front-matter already stripped.
+ * @returns True when a claim-section heading is present.
+ */
+export function hasClaimSection(body: string): boolean {
+    const claims = CLAIM_SECTIONS.map((section) => section.toLowerCase());
+    return scanBody(body).headings.some((heading) =>
+        claims.includes(heading.toLowerCase()),
+    );
+}
+
 /**
  * The required front-matter fields that are blank in a raw doc: `Keywords` is
  * blank when it yields no terms (matching `add`'s typed rule in
@@ -1633,10 +1666,7 @@ export function validateDoc(path: string, raw: string): string[] {
             "hand-maintained `Date` — the date is derived by git, never written.",
         );
     }
-    const claims = CLAIM_SECTIONS.map((section) => section.toLowerCase());
-    if (
-        !scanBody(body).headings.some((h) => claims.includes(h.toLowerCase()))
-    ) {
+    if (!hasClaimSection(body)) {
         findings.push(
             "no claim section (Facts / Inferred / Tested / Failed approaches / Open questions).",
         );
@@ -2048,13 +2078,17 @@ export function missNudgeFor(
  * never a session dump (the near-twin guard catches duplicates, not dumps).
  */
 export const RECORD_NUDGE =
-    "Before summarising: if this session established durable knowledge " +
-    "(decisions, traps, runbooks, verified behaviour), open the " +
-    "continuation with one `Record with docs add:` block per finding — " +
+    "Before summarising, the active task comes first. If the session " +
+    "established durable knowledge (decisions, traps, runbooks, verified " +
+    "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 own artifact's class (repo, machine, or global), `Area`, `H1` title " +
-    "and `Keywords`, plus a one-line what-and-why, so the next agent can " +
-    "persist each as a separate focused doc at the narrowest true scope.";
+    "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.";
 
 /**
  * Resolve the plugin's `nudge` option: unset means on; a boolean passes
@@ -2097,7 +2131,10 @@ export interface Lake extends LakeSpec {
     read: (path: string) => string;
     /** Whether a root-relative path exists. */
     exists: (path: string) => boolean;
-    /** Writes a root-relative path, creating parent directories. */
+    /**
+     * Writes a root-relative path, creating parent directories beneath an
+     * existing root; throws when the root is absent rather than creating it.
+     */
     write: (path: string, contents: string) => void;
     /** Environment notes for `check` (missing root, unversioned root). */
     notes: readonly string[];
@@ -2186,7 +2223,7 @@ export function createLake(
     };
     return {
         ...spec,
-        notes: unversionedNote(spec.root),
+        notes: unversionedNote(spec.root, spec.name),
         linkCheck: true,
         collect: () =>
             collectDocs(spec.root, (paths) => fallbackDates(spec.root, paths), {
@@ -2202,6 +2239,14 @@ export function createLake(
         },
         write: (path, contents) => {
             const target = guarded(path);
+            // The root is configured, never invented: a mistyped path must not
+            // bootstrap a lake. `add` pre-checks for a friendlier refusal.
+            if (!existsSync(spec.root)) {
+                throw new Error(
+                    `lake '${spec.name}' root ${spec.root} does not exist; ` +
+                        "create it first.",
+                );
+            }
             mkdirSync(dirname(target), { recursive: true });
             writeFileSync(target, contents);
         },
@@ -2725,12 +2770,26 @@ function searchDocs(
         closest,
         omitted,
     } = rankDocs(entries, query, { perLakeQuota: runtime.perLakeQuota });
+    const content = render(ranked, {
+        closest,
+        omitted,
+        primaryLake: primaryLakeName(runtime.lakes) ?? "",
+    });
+    // A dormant lake contributes nothing, so without the note a typo'd root
+    // looks like an empty lake rather than a broken path.
+    const missing = runtime.lakes
+        .filter(
+            (lake) =>
+                lake.root !== "" &&
+                (lakeName === undefined || lakeName === lake.name) &&
+                !existsSync(lake.root),
+        )
+        .map((lake) => missingRootNote(lake.root, lake.name));
     return {
-        content: render(ranked, {
-            closest,
-            omitted,
-            primaryLake: primaryLakeName(runtime.lakes) ?? "",
-        }),
+        content:
+            missing.length > 0
+                ? `${content}\n\n${missing.join("\n")}`
+                : content,
         count: ranked.length,
         omitted,
     };
@@ -2806,6 +2865,16 @@ function addDoc(
     if ("reason" in target) {
         return { content: target.reason, written: false };
     }
+    // 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:
+                `${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,
@@ -2829,16 +2898,12 @@ function addDoc(
     const head = `${address(target, outcome.path, runtime.lakes)} — ${
         updated ? "updated" : "created"
     }.`;
-    const neighbours =
-        outcome.neighbours.length > 0
-            ? `\n\nNearby docs in the same area:\n\n${render(
-                  outcome.neighbours,
-                  { primaryLake: target.name },
-              )}`
-            : "";
+    // 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}${neighbours}${notes}`, written: true };
+    return { content: `${head}${notes}`, written: true };
 }
 
 /** A parsed read request: the lake (when known) and the path. */
@@ -2950,6 +3015,7 @@ function lakeInfo(lakes: readonly Lake[]): LakeInfo[] {
         root: lake.root,
         writable: lake.writable,
         validated: lake.profile === "knowledge",
+        missing: lake.root !== "" && !existsSync(lake.root),
     }));
 }
 
@@ -2974,11 +3040,11 @@ export interface DocsCommandDeps extends RuntimeInput {
  * the full doctrine the native `docs` description carries.
  */
 const TWIN_DESCRIPTION =
-    "Search, read, add and check the configured knowledge lakes (plus nested " +
-    "project `README.md` files, search-only) from inside `execute` — the " +
-    "`docs` tool's Code Mode twin. A blank search lists the most recently " +
-    "changed docs; `read` returns a matched doc verbatim; `add` writes through " +
-    "a typed DTO; `check` validates the knowledge lakes.";
+    "Search, read, add and check the configured knowledge lakes and nested " +
+    "project `README.md` files (search-only) from inside `execute` — the `docs` " +
+    "tool's Code Mode twin, same verbs and lakes. A blank search lists recent " +
+    "docs; `read` returns a matched doc verbatim; `add` writes through a typed " +
+    "DTO; `check` validates the lakes.";
 
 /**
  * Build the `docs` tool from its dependencies.
@@ -3010,13 +3076,13 @@ export function createDocsTool(
         name,
         description: codemode
             ? TWIN_DESCRIPTION
-            : "Discover the configured knowledge lakes plus nested `README.md` " +
-              "files in the project tree. Prefer it over a broad grep when the " +
-              "question is how-to knowledge rather than where code lives. A blank search lists the " +
-              MAX_RESULTS +
-              " most recently changed docs (path — Area — date — Summary); a search ranks docs over title, path, keywords, body headings and code spans, area, summary and wiki prose, falling back to the closest matches. Every source reserves a few results; every call caps at " +
-              MAX_RESULTS +
-              " and counts the rest. Search exactly `help` for the lakes and ranking. `read` returns a doc verbatim; pass a `lake` or a `lake:path`. `add` writes a new knowledge doc (or replaces the doc at `path`) from a typed DTO — metadata becomes front-matter, the body must start with an H1; blank fields, path traversal, non-.md targets, symlinked targets, read-only lakes and same-area near-twins are refused. `check` validates the knowledge lakes (front-matter, H1, claim sections, no hand-maintained Date, distinctive identity, near-twins, broken links, soft length note); wiki lakes are read-only and not validated. READMEs are search-only and render as `instructions:path`; read them with the built-in read tool.",
+            : "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.",
         input: DOCS_INPUT,
         options: codemode
             ? { namespace: "docs", codemode: true }
@@ -3099,9 +3165,7 @@ export function createDocsCommand(deps: DocsCommandDeps): CommandDefinition {
     return {
         name: "docs",
         description:
-            "Search the configured knowledge lakes, ranked, plus nested project `README.md` files (search only); `add <text>` records new knowledge through the tool's typed `add`; `check` validates the knowledge lakes; a blank search lists the " +
-            MAX_RESULTS +
-            " most recently changed.",
+            "Search the configured knowledge lakes, ranked, plus nested project `README.md` files (search only); `add <text>` records new knowledge through the tool's typed `add`; `check` validates the lakes; a blank search lists recent docs.",
         async execute({ sessionID, prompt }) {
             const text = prompt.text.trim();
             if (isHelp(text)) {
@@ -3166,18 +3230,39 @@ export function resolveRoot(
 }
 
 /**
- * Probe whether the lake root sits inside a git work tree, as `check`-report
- * notes. An unversioned root still works — dates fall back to file mtimes and
- * the knowledge has no history — so it is surfaced, not refused.
+ * The advisory note for a lake root that is absent. A missing root is a
+ * configuration smell, not a failure: the lake stays dormant until the
+ * directory exists, and `add` refuses rather than creating it.
+ * @param root The resolved lake root.
+ * @param lake The lake name, when known.
+ * @returns The note line.
+ */
+export function missingRootNote(root: string, lake?: string): string {
+    const subject =
+        lake === undefined
+            ? `lake root ${root}`
+            : `lake '${lake}' root ${root}`;
+    return (
+        `note: ${subject} does not exist — it is ignored until it does. ` +
+        "A missing root is not an error."
+    );
+}
+
+/**
+ * The environment notes for a lake root: missing, or unversioned. An absent
+ * root is flagged but tolerated; an unversioned root still works — dates fall
+ * back to file mtimes and the knowledge has no history — so it is surfaced,
+ * not refused.
  * @param root The lake root to probe.
- * @returns The note lines; empty when the root is version-controlled.
+ * @param lake The lake name, when known.
+ * @returns The note lines; empty when the root is present and version-controlled.
  */
-export function unversionedNote(root: string): readonly string[] {
+export function unversionedNote(
+    root: string,
+    lake?: string,
+): readonly string[] {
     if (!existsSync(root)) {
-        return [
-            "note: this lake root does not exist yet — it is ignored until " +
-                "it does. A missing root is not an error.",
-        ];
+        return [missingRootNote(root, lake)];
     }
     const probe = spawnSync("git", ["rev-parse", "--show-toplevel"], {
         cwd: root,
@@ -3323,17 +3408,12 @@ export default Plugin.define({
                 id: Skill.ID.make("docs"),
                 name: Skill.Name.make("Docs"),
                 description:
-                    "The entry point to the configured knowledge lakes " +
-                    "(repo, machine, global and read-only wiki), plus the " +
-                    "project's nested README.md files (search only): find the " +
-                    "right doc with the docs tool, read it, and record focused " +
-                    "task knowledge for the next human or agent at the " +
-                    "narrowest true scope. Use before searching the codebase " +
-                    "for how-to knowledge, when a task names a service, flag " +
-                    "or error string the lake may already explain, at the " +
-                    "start of unfamiliar work, when hunting for prior " +
-                    "decisions or traps, when a session learns something the " +
-                    "next one will need, and when closing out a session.",
+                    "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.",
                 path: AbsolutePath.make(fileURLToPath(skillURL)),
                 content: skill,
             });