@markstanden/opencode-docs-plugin 0.5.0 → 0.6.2

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.2",
     "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,62 @@ 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. Terms shorter than `MIN_TERM_LENGTH` (3) are dropped
+when longer terms exist; otherwise all query terms are kept. `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. Knowledge lakes exclude `plans/`,
+`requirements/` and `wiki/` at the root; wiki lakes exclude only
+dot-directories and `node_modules`.
 
-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.",
         }),
     ),
 });
@@ -250,9 +250,77 @@ function splitKeywords(value: string): string[] {
         .filter((keyword) => keyword !== "");
 }
 
-/** Whether a line opens or closes a fenced code block. */
-function isFence(line: string): boolean {
-    return line.trimStart().startsWith("```");
+/**
+ * An open fenced code block: the opener's delimiter character and run length.
+ * The length and character are remembered so a shorter or different-character
+ * run inside the block cannot close it.
+ */
+interface Fence {
+    readonly char: "`" | "~";
+    readonly length: number;
+}
+
+/**
+ * The supported Markdown fence subset: a backtick or tilde run of three or
+ * more, indented by at most three spaces. A backtick opener's info string may
+ * not contain a backtick. Four-space indentation is an indented code block, not
+ * a fence, and is not modelled; nor are tab-indented fences or the full
+ * CommonMark block grammar.
+ * @param line One source line.
+ * @returns The opened fence, or null when the line is not an opener.
+ */
+function fenceOpener(line: string): Fence | null {
+    const match = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (match === null) {
+        return null;
+    }
+    const run = match[1] ?? "";
+    const info = line.slice(match[0].length);
+    const char = run[0] as Fence["char"];
+    if (char === "`" && info.includes("`")) {
+        return null;
+    }
+    return { char, length: run.length };
+}
+
+/**
+ * Whether a line closes `fence`: the same delimiter character, a run at least
+ * as long as the opener, and nothing after it but spaces or tabs.
+ * @param line One source line.
+ * @param fence The open fence.
+ * @returns True when the line closes the block.
+ */
+function closesFence(line: string, fence: Fence): boolean {
+    const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+    if (match === null) {
+        return false;
+    }
+    const run = match[1] ?? "";
+    return run.startsWith(fence.char) && run.length >= fence.length;
+}
+
+/**
+ * The body's lines outside fenced code blocks, fence delimiters included in
+ * neither. An unclosed fence keeps every remaining line inside the block.
+ * @param body Doc body, front-matter already stripped.
+ * @returns Source lines with fenced blocks removed.
+ */
+function outsideFenceLines(body: string): string[] {
+    const lines: string[] = [];
+    let fence: Fence | null = null;
+    for (const line of body.split("\n")) {
+        if (fence === null) {
+            const opener = fenceOpener(line);
+            if (opener !== null) {
+                fence = opener;
+                continue;
+            }
+            lines.push(line);
+        } else if (closesFence(line, fence)) {
+            fence = null;
+        }
+    }
+    return lines;
 }
 
 /** Drop an ATX heading's trailing `#` decoration (and any trailing spaces). */
@@ -279,19 +347,11 @@ interface BodyScan {
 function scanBody(body: string): BodyScan {
     const headings: string[] = [];
     const spans: string[] = [];
-    let fenced = false;
-    for (const line of body.split("\n")) {
-        if (isFence(line)) {
-            fenced = !fenced;
-            continue;
-        }
-        if (fenced) {
-            continue;
-        }
+    for (const line of outsideFenceLines(body)) {
         const heading = /^(#{2,3})\s+/.exec(line);
         if (heading !== null) {
             const text = stripTrailingHashes(
-                line.slice(heading[0].length).replace(/`/g, ""),
+                line.slice(heading[0].length).replaceAll("`", ""),
             ).trim();
             if (text !== "") {
                 headings.push(text);
@@ -358,18 +418,7 @@ function plainProse(text: string): string {
 
 /** The body with fenced code blocks removed. */
 function withoutFences(body: string): string {
-    const lines: string[] = [];
-    let fenced = false;
-    for (const line of body.split("\n")) {
-        if (isFence(line)) {
-            fenced = !fenced;
-            continue;
-        }
-        if (!fenced) {
-            lines.push(line);
-        }
-    }
-    return lines.join("\n");
+    return outsideFenceLines(body).join("\n");
 }
 
 /** Block prefixes that are never a wiki summary. */
@@ -752,6 +801,20 @@ export function rankDocs(
     };
 }
 
+/** The provenance prefix for a result: instructions, non-primary lake, or none. */
+function resultPrefix(
+    entry: DocEntry,
+    primaryLake: string | undefined,
+): string {
+    if (entry.class === "instructions") {
+        return "instructions";
+    }
+    if (entry.lake !== "" && entry.lake !== primaryLake) {
+        return entry.lake;
+    }
+    return "";
+}
+
 /**
  * Render matched docs as `path — Area — date` lines with the summary indented
  * beneath; a non-primary lake is prefixed `lake:` so provenance is clear. A
@@ -782,12 +845,8 @@ export function render(
             );
             const meta = parts.join(" — ");
             const head = meta === "" ? entry.path : `${entry.path} — ${meta}`;
-            const labelled =
-                entry.class === "instructions"
-                    ? `instructions:${head}`
-                    : entry.lake !== "" && entry.lake !== options.primaryLake
-                      ? `${entry.lake}:${head}`
-                      : head;
+            const prefix = resultPrefix(entry, options.primaryLake);
+            const labelled = prefix === "" ? head : `${prefix}:${head}`;
             return entry.summary === ""
                 ? labelled
                 : `${labelled}\n  ${entry.summary}`;
@@ -824,7 +883,7 @@ export function explainRanking(): string {
         "How docs search ranks:",
         `- Fields weighted: title ${FIELD_WEIGHTS.title} > path ${FIELD_WEIGHTS.path} > keywords ${FIELD_WEIGHTS.keywords} > identifiers ${FIELD_WEIGHTS.identifiers} > area ${FIELD_WEIGHTS.area} > summary ${FIELD_WEIGHTS.summary} > wiki prose ${FIELD_WEIGHTS.text}.`,
         `- Each term scores its best field as weight × quality; quality is exact > prefix > substring.`,
-        `- Terms shorter than MIN_TERM_LENGTH (${MIN_TERM_LENGTH}) are ignored unless they are the whole query.`,
+        `- Terms shorter than MIN_TERM_LENGTH (${MIN_TERM_LENGTH}) are dropped when longer terms exist; otherwise all query terms are kept.`,
         "- Search covers every configured lake and nested project `README.md` files, honouring `.gitignore` (dependency and build directories are skipped when the project is not in git). READMEs are searchable only: `add` and `check` ignore them, and their results are prefixed `instructions:` so they read with the built-in `read` tool.",
         `- Each source reserves up to ${DEFAULT_PER_LAKE_QUOTA} results (configurable), then leftover slots fill by score. Every call returns at most MAX_RESULTS (${MAX_RESULTS}), best matches first, then the most recently edited; anything cut is counted as "… and N more not shown."`,
         "- Class precedence on a tie: repo > instructions > global > machine > wiki.",
@@ -844,6 +903,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 +918,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(
@@ -942,7 +1004,7 @@ export function gitDates(
         return dates;
     }
     const result = spawnSync(
-        "git",
+        "git", // NOSONAR: portable git lookup; cwd is trusted local config, not model input.
         // `--relative` keeps the output paths root-relative to `cwd`; without
         // it a lake rooted at `<repo>/docs` maps `docs/foo.md` while the
         // requested paths are `foo.md`, silently falling back to mtimes.
@@ -1056,6 +1118,22 @@ function skipDirectory(
     return directory === root && excluded.includes(item.name);
 }
 
+/**
+ * Code-unit string order, matching the default sort but stated explicitly.
+ * @param a Left string.
+ * @param b Right string.
+ * @returns Negative, zero or positive in code-unit order.
+ */
+function compareText(a: string, b: string): number {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
 /**
  * Walk a lake root, returning its `.md` paths relative to the root. Dot
  * directories are skipped (which drops `.git` and `.attachments`), as are
@@ -1103,7 +1181,7 @@ export function collectDocPaths(
     if (existsSync(root)) {
         walk(root);
     }
-    return paths.sort();
+    return paths.sort(compareText);
 }
 
 /**
@@ -1218,7 +1296,7 @@ export function readmePaths(
         .filter(
             (path) => !skip.some((root) => isUnder(join(location, path), root)),
         )
-        .sort();
+        .sort(compareText);
 }
 
 /**
@@ -1227,7 +1305,7 @@ export function readmePaths(
  */
 function gitReadmePaths(location: string): string[] | undefined {
     const result = spawnSync(
-        "git",
+        "git", // NOSONAR: portable git lookup; cwd is trusted local config, not model input.
         ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
         { cwd: location, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
     );
@@ -1319,7 +1397,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 +1608,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 +1679,26 @@ 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 = new Set(
+        CLAIM_SECTIONS.map((section) => section.toLowerCase()),
+    );
+    return scanBody(body).headings.some((heading) =>
+        claims.has(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 +1743,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).",
         );
@@ -1668,7 +1775,7 @@ function nearTwinPairs(
         const query = identityQuery(doc.title, doc.keywords);
         const others = entries.filter((other) => other.path !== doc.path);
         for (const twin of nearTwins(query, doc.area, others)) {
-            const key = [doc.path, twin.path].sort().join("\n");
+            const key = [doc.path, twin.path].sort(compareText).join("\n");
             if (!pairs.has(key)) {
                 pairs.set(key, [doc, twin]);
             }
@@ -1702,26 +1809,47 @@ function resolveLink(from: string, target: string): string | null {
     return stack.join("/");
 }
 
+/** An inline link's destination and the index of its closing `)`. */
+interface InlineLink {
+    readonly destination: string | undefined;
+    readonly end: number;
+}
+
+/**
+ * Parse an inline `[text](target)` link starting at `start`.
+ * @param line One source line.
+ * @param start Index of the opening `[`.
+ * @returns The destination and closing index, or null when the link is incomplete.
+ */
+function inlineLinkAt(line: string, start: number): InlineLink | null {
+    const close = line.indexOf("](", start + 1);
+    if (close === -1) {
+        return null;
+    }
+    const end = line.indexOf(")", close + 2);
+    if (end === -1) {
+        return null;
+    }
+    const destination = line
+        .slice(close + 2, end)
+        .trim()
+        .split(/\s+/)[0];
+    return { destination, end };
+}
+
 /** Inline `[text](target)` destinations on one line; images are skipped. */
 function inlineTargets(line: string): string[] {
     const targets: string[] = [];
     let index = 0;
     while (index < line.length) {
         if (line[index] === "[" && line[index - 1] !== "!") {
-            const close = line.indexOf("](", index + 1);
-            if (close !== -1) {
-                const end = line.indexOf(")", close + 2);
-                if (end !== -1) {
-                    const destination = line
-                        .slice(close + 2, end)
-                        .trim()
-                        .split(/\s+/)[0];
-                    if (destination !== undefined && destination !== "") {
-                        targets.push(destination);
-                    }
-                    index = end + 1;
-                    continue;
+            const link = inlineLinkAt(line, index);
+            if (link !== null) {
+                if (link.destination !== undefined && link.destination !== "") {
+                    targets.push(link.destination);
                 }
+                index = link.end + 1;
+                continue;
             }
         }
         index += 1;
@@ -1738,15 +1866,7 @@ function inlineTargets(line: string): string[] {
  */
 export function markdownTargets(body: string): string[] {
     const targets: string[] = [];
-    let fenced = false;
-    for (const line of body.split("\n")) {
-        if (isFence(line)) {
-            fenced = !fenced;
-            continue;
-        }
-        if (fenced) {
-            continue;
-        }
+    for (const line of outsideFenceLines(body)) {
         targets.push(...inlineTargets(line));
         const reference = /^\s*\[[^\]]+\]:\s*(\S+)/.exec(line);
         if (reference?.[1] !== undefined) {
@@ -1932,7 +2052,8 @@ export function checkDocs(
     if (advisory.length === 0) {
         return head;
     }
-    return `${head}\n\nNotes:\n${advisory.map((note) => `- ${note}`).join("\n")}`;
+    const noteLines = advisory.map((note) => `- ${note}`).join("\n");
+    return `${head}\n\nNotes:\n${noteLines}`;
 }
 
 /** The built-in tools the miss-nudge watches: content searches, both miss-prone. */
@@ -2048,13 +2169,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 +2222,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 +2314,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 +2330,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);
         },
@@ -2314,13 +2450,20 @@ function readLakesJson(
             { cause: error },
         );
     }
-    const lakes = Array.isArray(parsed)
-        ? parsed
-        : typeof parsed === "object" && parsed !== null && "lakes" in parsed
-          ? (parsed as { lakes: unknown }).lakes
-          : undefined;
+    let lakes: unknown;
+    if (Array.isArray(parsed)) {
+        lakes = parsed;
+    } else if (
+        typeof parsed === "object" &&
+        parsed !== null &&
+        "lakes" in parsed
+    ) {
+        lakes = (parsed as { lakes: unknown }).lakes;
+    } else {
+        lakes = undefined;
+    }
     if (!Array.isArray(lakes)) {
-        throw new Error(
+        throw new TypeError(
             `docs plugin ${label} must contain a "lakes" array: ${path}.`,
         );
     }
@@ -2390,7 +2533,7 @@ function lakeRootOf(
         return join(location, "docs");
     }
     if (typeof entry.root !== "string") {
-        throw new Error(
+        throw new TypeError(
             `docs plugin ${lakeClass} lake root must be a string, ` +
                 `got ${JSON.stringify(entry.root)}.`,
         );
@@ -2411,12 +2554,14 @@ function lakeNameOf(
     lakeClass: LakeClass,
 ): string {
     const derived = slugify(basename(root)) || lakeClass;
-    const name =
-        entry.name === undefined
-            ? derived
-            : typeof entry.name === "string"
-              ? entry.name.trim()
-              : "";
+    let name: string;
+    if (entry.name === undefined) {
+        name = derived;
+    } else if (typeof entry.name === "string") {
+        name = entry.name.trim();
+    } else {
+        name = "";
+    }
     if (!LAKE_NAME.test(name)) {
         throw new Error(
             `docs plugin lake name must match ${LAKE_NAME}, ` +
@@ -2443,8 +2588,7 @@ function lakeWritableOf(
                 `got ${JSON.stringify(entry.writable)}.`,
         );
     }
-    const writable =
-        entry.writable === undefined ? lakeClass !== "wiki" : entry.writable;
+    const writable = entry.writable ?? lakeClass !== "wiki";
     if (lakeClass === "wiki" && writable) {
         throw new Error(
             `docs plugin lake '${name}' is a wiki lake and cannot be writable.`,
@@ -2725,12 +2869,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 +2964,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 +2997,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 +3114,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 +3139,56 @@ 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.";
+
+/**
+ * Run one resolved `docs` request against the runtime.
+ * @param runtime The resolved lakes and seams.
+ * @param input The typed tool input.
+ * @returns The tool result.
+ */
+function executeRequest(runtime: Runtime, input: DocsInput): Result {
+    const request = resolveRequest(input);
+    if (request.verb === "add") {
+        const result = addDoc(runtime, request.add, request.lake);
+        return {
+            content: result.content,
+            metadata: { written: result.written },
+        };
+    }
+    if (request.verb === "check") {
+        const result = checkLakes(runtime, request.lake);
+        return {
+            content: result.content,
+            metadata: { checked: result.checked },
+        };
+    }
+    if (request.verb === "read") {
+        const result = readDoc(runtime, request.read, request.lake);
+        return {
+            content: result.content,
+            metadata: { read: result.read },
+        };
+    }
+    if (request.verb === "help") {
+        return {
+            content: helpText(lakeInfo(runtime.lakes)),
+            metadata: { count: 0, omitted: 0 },
+        };
+    }
+    const result = searchDocs(runtime, request.search, request.lake);
+    return {
+        content: result.content,
+        metadata: {
+            count: result.count,
+            omitted: result.omitted,
+        },
+    };
+}
 
 /**
  * Build the `docs` tool from its dependencies.
@@ -3010,54 +3220,19 @@ 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 }
             : { codemode: false },
-        async execute(input) {
-            const request = resolveRequest(input);
-            if (request.verb === "add") {
-                const result = addDoc(runtime, request.add, request.lake);
-                return {
-                    content: result.content,
-                    metadata: { written: result.written },
-                };
-            }
-            if (request.verb === "check") {
-                const result = checkLakes(runtime, request.lake);
-                return {
-                    content: result.content,
-                    metadata: { checked: result.checked },
-                };
-            }
-            if (request.verb === "read") {
-                const result = readDoc(runtime, request.read, request.lake);
-                return {
-                    content: result.content,
-                    metadata: { read: result.read },
-                };
-            }
-            if (request.verb === "help") {
-                return {
-                    content: helpText(lakeInfo(runtime.lakes)),
-                    metadata: { count: 0, omitted: 0 },
-                };
-            }
-            const result = searchDocs(runtime, request.search, request.lake);
-            return {
-                content: result.content,
-                metadata: {
-                    count: result.count,
-                    omitted: result.omitted,
-                },
-            };
+        execute(input) {
+            return Promise.resolve(executeRequest(runtime, input));
         },
     };
 }
@@ -3099,9 +3274,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)) {
@@ -3149,7 +3322,7 @@ export function resolveRoot(
         return join(locationDirectory, "docs");
     }
     if (typeof configured !== "string") {
-        throw new Error(
+        throw new TypeError(
             `docs plugin option 'root' must be a non-empty string path, ` +
                 `got ${JSON.stringify(configured)}.`,
         );
@@ -3166,22 +3339,45 @@ 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,
-    });
+    const probe = spawnSync(
+        "git", // NOSONAR: portable git lookup; cwd is trusted local config.
+        ["rev-parse", "--show-toplevel"],
+        { cwd: root },
+    );
     if (probe.status === 0) {
         return [];
     }
@@ -3323,17 +3519,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,
             });