@markstanden/opencode-docs-plugin 0.4.0 → 0.5.0

package/CONVENTION.md

@@ -4,13 +4,42 @@ This plugin owns this convention: it is what the `docs` tool's `add` writes,
 what `check` validates, and what the registered `docs` skill teaches. A
 repository that adopts the plugin takes the convention with it.
 
+## Classes and scope
+
+Every doc belongs to exactly one class. The class is fixed by the lake it lives
+in, so a doc cannot mix scopes.
+
+| Class              | Where                               | Reader                       | Writes                                |
+| ------------------ | ----------------------------------- | ---------------------------- | ------------------------------------- |
+| **Instructions**   | nested `README.md` files            | code-local how-to            | never by the tool                     |
+| **RepoContext**    | `<repo>/docs` by default            | this repo                    | yes                                   |
+| **MachineContext** | a personal lake such as `~/doclake` | this person, across machines | yes                                   |
+| **GlobalContext**  | an organisation lake                | every team, every repo       | yes, lock down with `writable: false` |
+| **Wiki**           | a human-readable wiki checkout      | humans first, agents second  | no                                    |
+
+Place at the **narrowest scope where the whole claim is true**:
+
+1. Command or step to build, run, test, deploy → Instructions.
+2. True only for this repo → RepoContext.
+3. True for you across machines → MachineContext.
+4. True for the org across repos → GlobalContext.
+5. Human-facing narrative → Wiki.
+
+Two answers mean two focused docs, one per class. A doc that needs a placement
+debate is not focused enough.
+
 ## Where knowledge lives
 
-Durable knowledge is one Markdown file per topic under the docs root, grouped by
-area: `<area>/<name>.md` (the root is the plugin's `root` option; default
-`<location>/docs`). The excluded areas — never scanned, never validated —
-are `plans/` (scratch, gitignored, deleted when the work lands),
-`requirements/` and `wiki/` (vendored mirrors).
+Durable knowledge is one Markdown file per topic under a lake root, grouped by
+area: `<area>/<name>.md`. The default repo lake is `<location>/docs`; its docs
+are RepoContext. A repo adds other local roots in
+`.opencode/docs-lakes.json`; a personal or managed base file lists the
+machine, global and wiki lakes.
+
+The excluded areas — never scanned, never validated in a knowledge lake — are
+`plans/` (scratch, gitignored, deleted when the work lands), `requirements/`
+and `wiki/` (vendored mirrors). The wiki profile has no such exclusions; only
+dot-directories and `node_modules` are skipped there.
 
 Search also covers `README.md` files nested in the project tree, so an agent
 finds the map beside the code. They are indexed as they stand (H1 title,
@@ -21,27 +50,38 @@ are skipped by name.
 
 ## Front-matter
 
-Every doc opens with a `---` front-matter block. The fields, in canonical order:
+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. |
-| `Status`     | no       | `active` (the default) or `superseded`.                                 |
-| `Supersedes` | no       | The doc this one replaces.                                              |
+| 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. |
 
 `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.
 
+There is no lifecycle field. `Status` and `Supersedes` are **obsolete**; `check`
+reports them as notes so an existing lake can be cleaned once. A doc is current
+or deleted: git is the archive.
+
 The tool serialises the front-matter — never copy it by hand.
 
+Wiki pages carry no front-matter. ADO renders YAML as raw text, and a human wiki
+should read cleanly. The wiki profile derives the title from the H1, the area
+from the folder, the summary from the first prose paragraph, and the date from
+git. Optional invisible metadata may be added later; it is not required.
+
 ## Body
 
 - An `H1` title: the first half of the doc's identity.
 - At least one claim section as an `H2`/`H3` heading — `Facts`, `Inferred`,
-  `Tested`, `Open questions` — so a reader knows how much to rely on each claim.
-  Group claims by section rather than mixing them.
+  `Tested`, `Failed approaches`, `Open questions` — so a reader knows how much
+  to rely on each claim. Group claims by section rather than mixing them.
+- 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.
 
 ## Identity and duplicates
 
@@ -52,16 +92,44 @@ The tool serialises the front-matter — never copy it by hand.
   `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.
+- Near-twins are per lake. The same topic at repo and global scope is
+  legitimate; the narrower doc states its delta and links up.
+
+## Focus, ownership and promotion
+
+- One question per doc. One topic per doc.
+- More than one H2 aimed at different topics or audiences means split.
+- Never write an omnibus notes doc to avoid choosing a class.
+- The narrowest true scope owns the claim. A broader class owns the general
+  rule; the narrower doc states only its delta and links up.
+- Do not copy between knowledge classes. Move or link.
+- Instructions own commands. Knowledge docs own reasons and link to the
+  command. Knowledge docs link to the wiki page for human narrative.
+- Wiki duplication is expected, not a defect. If a wiki page drifts from a
+  knowledge doc, report it and name both pages; do not edit the wiki.
+- Promotion is a move: the general claim goes up, the local delta stays. Delete
+  the emptied doc and repoint every in-repo link. No superseded stubs. An
+  unrepointable external link is reported for a human to fix.
+- A soft note appears when a body exceeds `maxDocLines` (default 200,
+  configurable). A note, not a refusal. Reference tables are judged by review.
+
+## Safety
+
+- No secrets, credentials, tokens, or customer data. Name the vault or variable,
+  never the value.
+- No personal data in GlobalContext or Wiki.
+- The wiki profile is read-only to the tool. Its own owners review changes.
 
 ## Lifecycle
 
-`Status` and `Supersedes` are load-bearing, not decoration. A doc marked
-`Status: superseded` is flagged `(superseded)` in search results and ranks below
-an active doc on a tie; `check` flags a `Supersedes` that names no doc in the
-tree.
+A doc is current or deleted. Correct a wrong doc by replacing it in place with
+`add` and an explicit `path`. Delete an obsolete doc through the shell with
+explicit approval; there is no `delete` verb. A failed attempt is still valid
+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 docs root is not an error: the plugin scans
-what is there and reports per-doc findings for what is not.
+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.

package/README.md

@@ -1,28 +1,49 @@
 # opencode-docs-plugin
 
-An [OpenCode](https://opencode.ai) V2 plugin that gives an agent a knowledge
-tree it can actually use: a `docs` tool and a `/docs` command over the
-configured docs root's `*.md` files (the `root` plugin option; default
-`<location>/docs`), plus nested `README.md` files in the project tree, and the
+An [OpenCode](https://opencode.ai) V2 plugin that gives an agent a set of
+knowledge **lakes** it can actually use: a `docs` tool and a `/docs` command
+over configured Markdown trees, nested `README.md` files in the project, and the
 writing convention those docs follow.
 
-- `docs` (tool) — blank search lists the 10 most recently changed docs
-  (`path — Area — date — Summary`); a search ranks docs over their
-  front-matter, path and body identifiers, falling back to the closest
-  matches rather than a dead end; `read` returns a matched doc verbatim
-  (front-matter and body), so find-then-read is one call; `add` writes
-  knowledge through a typed DTO; `check` validates the tree against the
-  convention. Nested project `README.md` files are indexed too —
-  `.gitignore` rules decide what is skipped — but only for search: `add`
-  and `check` never touch them. A Code Mode twin, `docs_search`, registers
-  alongside it, so `execute` reaches the same lake as
+Docs are grouped by **class**:
+
+| Class              | Where                           | Use it for                              | Writes        |
+| ------------------ | ------------------------------- | --------------------------------------- | ------------- |
+| **Instructions**   | nested `README.md`              | build, run, test, deploy this code      | never         |
+| **RepoContext**    | `<repo>/docs` by default        | this repo's traps, decisions, landmines | yes           |
+| **MachineContext** | personal lake, e.g. `~/doclake` | tooling and traps across your machines  | yes           |
+| **GlobalContext**  | organisation lake               | standards and integrations across repos | yes, reviewed |
+| **Wiki**           | human-readable wiki checkout    | narrative for humans                    | read-only     |
+
+Place knowledge at the narrowest scope where the whole claim is true. A doc that
+spans scopes is split into focused docs, one per class. The full rulebook is
+[CONVENTION.md](CONVENTION.md); the registered `docs` skill carries the working
+version.
+
+## The tool and command
+
+- `docs` (tool) — blank search lists the most recently changed docs
+  (`path — Area — date — Summary`); a search ranks docs over their front-matter,
+  path and body identifiers (plus wiki prose), falling back to the closest
+  matches rather than a dead end; `read` returns a doc verbatim and accepts a
+  `lake` or `lake:path`; `add` writes knowledge through a typed DTO; `check`
+  validates the knowledge lakes. Nested project `README.md` files are indexed
+  too — `.gitignore` rules decide what is skipped — but only for search: `add`
+  and `check` never touch them, and their results are prefixed `instructions:`
+  and read with the built-in `read` tool. A Code Mode twin, `docs_search`,
+  registers alongside it, so `execute` reaches the same lakes as
   `tools.docs.docs_search(…)`.
 - `/docs` (command) — the same core, driven from the prompt:
   `search <text>` (bare text searches too), `add <text>`, `check`, `help`.
 - The plugin also registers the `docs` skill, so the convention travels with
   the tool rather than living in always-loaded prose.
 
-Reading a matched doc stays OpenCode's built-in `read`.
+Reading a matched project file stays OpenCode's built-in `read`. The tool's own
+`read` serves lake docs and wiki pages.
+
+Every source reserves a few results (default 3 per source) before the rest of
+the cap fills by score, so a broad wiki cannot bury a focused repo doc. The
+cap is 10 results; the cut is counted.
 
 ## Installation
 
@@ -42,17 +63,19 @@ or as a `plugins` entry in `opencode.json(c)` (global, project or `.opencode/`):
 ```
 
 Unpinned entries update on the next server start or `opencode plugin update`;
-an exact version (e.g. `@0.2.0`) stays pinned.
+an exact version (e.g. `@0.5.0`) stays pinned.
 
 ## Configuration
 
-The docs root defaults to `<location>/docs`. Set the `root` option with the
-object form — `~` expands against the home directory, so a global config can
-point every project at one shared tree:
+One docs plugin entry, in the global or managed config. **Do not repeat the
+entry at project level**: the same package loads twice and both copies receive
+the project options, losing the base lakes. Add per-repo lakes through the repo
+file instead.
+
+The simplest setup uses `root` — one repo lake:
 
 ```jsonc
 {
-    "$schema": "https://opencode.ai/config.json",
     "plugins": [
         {
             "package": "@markstanden/opencode-docs-plugin",
@@ -64,19 +87,103 @@ point every project at one shared tree:
 }
 ```
 
-Relative paths resolve against the location's directory; absolute paths pass
-through. A blank `root` value counts as unset and uses the default; a
-non-string value fails at startup. The root directory itself need not exist in
-advance — it is created on the first `add`, and a search or `check` over a
-still-empty tree simply reports nothing. Restart OpenCode after editing the
-config — it isn't hot-reloaded.
-
-The runtime nudges default on: a one-line pointer appended to the first
-grep/glob miss of a session (suggesting a `docs search`), and a record-ready
-block format injected into compaction summarisation, so durable findings are
-shaped as separate focused docs — one artifact per topic, never a session
-dump. Set `"nudge": false` to restore silence; a non-boolean value fails at
-startup.
+`root` expands `~`, resolves a relative path against the location, and defaults
+to `<location>/docs`. A blank value counts as unset. `root` declares a **repo**
+lake; for a personal or global lake, use `lakes` with the class instead.
+
+For several lakes, list them inline, in a base file, or both. The base file is
+usually a personal or managed file; the repo file adds local lakes:
+
+```jsonc
+{
+    "plugins": [
+        {
+            "package": "@markstanden/opencode-docs-plugin",
+            "options": {
+                "lakesFile": "~/.config/opencode/docs-lakes.json",
+                "lakes": [{ "class": "repo", "root": "./docs" }],
+                "maxDocLines": 200,
+                "perLakeQuota": 3,
+            },
+        },
+    ],
+}
+```
+
+`~/.config/opencode/docs-lakes.json`:
+
+```jsonc
+{
+    "lakes": [
+        { "class": "machine", "root": "~/doclake", "name": "doclake" },
+        { "class": "global", "root": "~/org-docs", "name": "global" },
+        { "class": "wiki", "root": "~/org-wiki", "name": "wiki" },
+    ],
+}
+```
+
+A repo adds its own lakes in `.opencode/docs-lakes.json`, checked into the repo:
+
+```jsonc
+{
+    "lakes": [
+        { "root": "documentation", "name": "docs" },
+        { "root": "reference", "name": "reference", "writable": false },
+    ],
+}
+```
+
+Repo-file rules:
+
+- only `repo` lakes;
+- roots must resolve inside the location;
+- an absent file is ignored; a malformed file fails at startup.
+
+A sibling repository's docs belong in the base `lakesFile`, not the repo file.
+
+Merge order: base `lakesFile`, repo file, inline `lakes`, then `root`. Duplicate
+lake names fail at startup. If no repo lake is configured, one implicit repo
+lake at `<location>/docs` is added — so a repo needs no lake file unless its
+docs live elsewhere.
+
+Lake entries:
+
+| Field      | Meaning                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------ |
+| `class`    | `repo`, `machine`, `global` or `wiki`; default `repo`.                                           |
+| `root`     | The lake root. Required for `machine`/`global`/`wiki`; defaults to `<location>/docs` for `repo`. |
+| `name`     | Lower-case dashes; defaults to the root folder name. `instructions` is reserved.                 |
+| `writable` | Defaults true for knowledge classes, fixed false for `wiki`.                                     |
+
+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.
+
+`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.
+
+## Wiki lakes
+
+Wiki pages are read-only reference. They carry no required front-matter: the
+title comes from the H1, the area from the folder, the summary from the first
+prose paragraph, and the date from git. Prose and tables are indexed so a page
+that names an Azure region only in a table is still searchable. Wiki lakes are
+never validated. If a wiki page drifts from a knowledge doc, report it; the
+wiki's owners decide.
+
+## Check
+
+`check` validates the knowledge lakes: required front-matter, an H1, at least
+one claim section (`Facts`, `Inferred`, `Tested`, `Failed approaches`,
+`Open questions`), no hand-maintained `Date`, a distinctive H1+Keywords
+identity, same-area near-twins, and broken relative `.md` links. Obsolete
+`Status`/`Supersedes` fields, long docs, and unversioned or missing roots are
+**notes**, not findings. An empty findings list means compliant.
+
+There is no lifecycle field. A doc is current or deleted; git is the archive.
+Correct a wrong doc by replacing it in place. A failed attempt is valid
+knowledge when it records the outcome and what is true now.
 
 ## Status
 

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.4.0",
+    "version": "0.5.0",
     "type": "module",
-    "description": "OpenCode V2 plugin: a `docs` tool and `/docs` command over a repository's knowledge tree and the project's nested README.md files (search only), with the writing convention it owns",
+    "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": {
         "type": "git",
         "url": "git+https://github.com/markstanden/opencode-docs-plugin.git"

package/src/SKILL.md

@@ -1,98 +1,115 @@
 # Docs
 
-Durable knowledge lives under the configured docs root (the plugin's `root`
-option; default `<location>/docs`). This skill covers both
-halves of the loop: **find** (discover with the `docs` tool, read the match) and
-**record** (write or update a doc for the current task).
+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 lake —
+is reachable as the twin `tools.docs.docs_search(…)` — same verbs, same lakes —
 so batch it with the rest of the catalog there.
 
+## Classes
+
+| Class              | Where                       | Use it for                              | Writes        |
+| ------------------ | --------------------------- | --------------------------------------- | ------------- |
+| **Instructions**   | nested `README.md`          | build, run, test, deploy this code      | never         |
+| **RepoContext**    | `<repo>/docs`               | this repo's traps, decisions, landmines | yes           |
+| **MachineContext** | personal lake (`~/doclake`) | tooling and traps across your machines  | yes           |
+| **GlobalContext**  | organisation lake           | standards and integrations across repos | yes, reviewed |
+| **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.
+
 ## Find it
 
 Call the `docs` tool:
 
 - **blank `search`** — the most recently changed docs, one line per doc
   (`path — Area — date — Summary`).
-- **a `search`** — those docs ranked over title, path, keywords, body headings
-  and code spans, area and summary. 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, so filler words cannot drag in the catalogue.
-- **every call** caps at `MAX_RESULTS` (10), preferring the best matches and
-  then the most recent edits, and ends with `… and N more not shown.` when
-  anything was cut.
-- **exactly `help`** — plain text explaining the weights, the hit qualities and
-  the outcomes, instead of a search.
-
-Then open the match: either the built-in `read` tool (project files and
-READMEs), or the tool's own `read` verb — pass the root-relative path and it
-returns the doc verbatim, front-matter and body, in one call.
-`/docs [search]` runs the same search into the session (`/docs search <text>`
-is the explicit form).
-
-Every `*.md` under the root is covered except the excluded areas — scratch (`plans/`)
-and vendored mirrors (`requirements/`, `wiki/`). `Area` comes from the path,
-`date` from git. A doc marked `Status: superseded` carries a `(superseded)`
-marker in results and ranks below an active doc on a tie.
-
-Search also covers nested `README.md` files in the project tree — the map lives
-beside the code. They are indexed as they stand (H1 title, headings, code
-spans) and are **search-only**: `add` and `check` never touch them.
-`.gitignore` decides which directories are skipped; outside git, dependency and
-build directories are skipped by name. The lake root is skipped when it sits
-inside the project, since those READMEs are already knowledge docs.
+- **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.
 
 ## Record it
 
 Write durable findings and task documentation to `<area>/<title>.md` under the
-root so the
-next human or agent skips the rediscovery. The convention is this plugin's
-`CONVENTION.md`, restated here.
+right lake so the next human or agent skips the rediscovery. The convention is
+this plugin's `CONVENTION.md`, restated here.
 
 Before writing:
 
-1. **Read first, never duplicate.** List the tree with the `docs` tool 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. **Reconcile, then add.** Edit before add; merge near-twins; split a bloated
+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.
+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, leaving a stub if needed.
+   references and repoint them. Delete the emptied doc — no superseded stubs.
 
-One artifact per topic: 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.
+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`; optionally `Status`/`Supersedes`) plus a body carrying an
-`H1` and the claim sections (`Facts`, `Inferred`, `Tested`, `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`, and a same-area
-near-twin (returning the candidates to reconcile against). A plan for an
-in-flight effort is scratch, not a doc — a `plans/` area, excluded from the
-index and deleted when the work lands. `/docs add <text>` runs this record
-loop for a fact supplied inline.
+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.
 
 ## Check it
 
-To audit the tree instead of writing it, call the tool's `check` (`/docs check`
-runs it into the session): it validates every doc against the convention —
-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, a `Supersedes` naming a doc in the tree, and same-area near-twins — and
-reports findings per doc. An empty report means compliant. `add` enforces the
-same rules at the trust boundary.
+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