@markstanden/opencode-docs-plugin 0.2.1 → 0.4.0

package/CONVENTION.md

@@ -12,6 +12,13 @@ area: `<area>/<name>.md` (the root is the plugin's `root` option; default
 are `plans/` (scratch, gitignored, deleted when the work lands),
 `requirements/` and `wiki/` (vendored mirrors).
 
+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,
+headings and code spans) and are **search-only**: they are never written by
+`add`, validated by `check`, or eligible as near-twins. `.gitignore` decides
+which directories are skipped; outside git, dependency and build directories
+are skipped by name.
+
 ## Front-matter
 
 Every doc opens with a `---` front-matter block. The fields, in canonical order:

package/README.md

@@ -3,13 +3,20 @@
 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 the writing convention those docs follow.
+`<location>/docs`), plus nested `README.md` files in the project tree, 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; `add` writes knowledge through a typed DTO;
-  `check` validates the tree against the convention.
+  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
+  `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
@@ -58,7 +65,18 @@ point every project at one shared tree:
 ```
 
 Relative paths resolve against the location's directory; absolute paths pass
-through. Restart OpenCode after editing the config — it isn't hot-reloaded.
+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.
 
 ## Status
 

package/package.json

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

package/src/SKILL.md

@@ -5,9 +5,9 @@ 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).
 
-Call the `docs` tool directly at top level. It is a plugin-registered tool and
-is **not** reachable from the `execute` (Code Mode) catalog — do not try to
-batch it inside `execute`, and do not be misled by the unknown-tool suggestion.
+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 —
+so batch it with the rest of the catalog there.
 
 ## Find it
 
@@ -27,15 +27,24 @@ Call the `docs` tool:
 - **exactly `help`** — plain text explaining the weights, the hit qualities and
   the outcomes, instead of a search.
 
-Then open the match with the built-in `read` tool. The tool only discovers; it
-never returns a doc's body. `/docs [search]` runs the same search into the
-session (`/docs search <text>` is the explicit form).
+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.
+
 ## Read it
 
 - Consult matching docs before a broad grep: they are the curated knowledge.
@@ -59,6 +68,10 @@ Before writing:
    doc into per-topic files; after any split, merge or move, grep for inbound
    references and repoint them, leaving a stub if needed.
 
+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.
+
 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`).

package/src/index.ts

@@ -4,9 +4,10 @@ import type {
     CommandDefinition,
     CommandInvocation,
 } from "@opencode/plugin/promise/command";
-import type { Info } from "@opencode/plugin/promise/tool";
+import type { Info, Result } from "@opencode/plugin/promise/tool";
 import { spawnSync } from "node:child_process";
 import {
+    type Dirent,
     existsSync,
     mkdirSync,
     readFileSync,
@@ -15,7 +16,7 @@ import {
     writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Schema } from "effect";
 
@@ -105,6 +106,12 @@ export const DOCS_INPUT = Schema.Struct({
                 "Validate every doc under the docs root against the convention: required front-matter, an H1, claim sections, no hand-maintained Date, a distinctive H1+Keywords identity, a Supersedes naming a doc in the tree, and same-area near-twins. An empty report means compliant.",
         }),
     ),
+    read: Schema.optional(
+        Schema.String.annotate({
+            description:
+                "A root-relative doc path to return verbatim — front-matter and body — so find-then-read is one call. Lake docs only: project files and READMEs stay with the built-in `read` tool.",
+        }),
+    ),
 });
 
 /**
@@ -595,26 +602,29 @@ export function explainRanking(): string {
         `- 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}.`,
         `- 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.`,
+        "- Search also covers nested `README.md` files in the project tree, honouring `.gitignore` (dependency and build directories are skipped when the project is not in git). They are searchable only: `add` and `check` ignore them.",
         `- 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."`,
         '- Outcomes: a blank query lists the most recently changed docs; a doc carrying every term ranks the full matches; otherwise the docs matching any term as a substring are listed under "Closest matches"; nothing hits is "No knowledge docs matched."',
     ].join("\n");
 }
 
-/** A resolved `docs` tool call: exactly one verb wins (`add` > `check` > `help` > `search`). */
+/** A resolved `docs` tool call: exactly one verb wins (`add` > `check` > `read` > `help` > `search`). */
 export type DocsRequest =
     | { verb: "add"; add: DocsAdd }
     | { verb: "check" }
+    | { verb: "read"; read: string }
     | { verb: "help" }
     | { verb: "search"; search: string };
 
 /**
  * Resolve a tool call to one verb. An explicit `add` is never downgraded; a
- * `check` outranks a search; a lone `help` search explains the ranking;
- * anything else searches.
+ * `check` outranks a read; a non-blank `read` outranks a search; a lone `help`
+ * search explains the ranking; anything else searches.
  * @param input The raw tool input.
  * @param input.search The raw search text, when given.
  * @param input.add The typed add DTO, when given.
  * @param input.check The check flag, when given.
+ * @param input.read The root-relative doc path to read, when given.
  * @returns The single resolved request.
  */
 export function resolveRequest(input: DocsInput): DocsRequest {
@@ -624,6 +634,10 @@ export function resolveRequest(input: DocsInput): DocsRequest {
     if (input.check === true) {
         return { verb: "check" };
     }
+    const read = input.read?.trim() ?? "";
+    if (read !== "") {
+        return { verb: "read", read };
+    }
     if (isHelp(input.search ?? "")) {
         return { verb: "help" };
     }
@@ -738,6 +752,132 @@ export function collectDocs(
     );
 }
 
+/**
+ * Directory names the fallback README walk never enters, for a project outside
+ * a git work tree (inside one, `.gitignore` decides; dot-directories are always
+ * skipped). Kept to dependencies and build output — the usual noise — rather
+ * than every convention going.
+ */
+export const README_EXCLUDED_DIRS = [
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "target",
+    "vendor",
+    "__pycache__",
+] as const;
+
+/**
+ * Whether `path` is `root` itself or sits beneath it. Only an exact `..` path
+ * segment escapes the root — a `..`-prefixed name like `..drafts` does not.
+ */
+function isUnder(path: string, root: string): boolean {
+    const rest = relative(root, path);
+    return (
+        rest === "" ||
+        (rest !== ".." && !rest.startsWith(`..${sep}`) && !isAbsolute(rest))
+    );
+}
+
+/** Whether a file name is a README in any case (`README.md`, `readme.md`). */
+function isReadme(name: string): boolean {
+    return name.toLowerCase() === "readme.md";
+}
+
+/**
+ * The project's nested README paths, relative to `location`. Inside a git work
+ * tree git supplies the list — tracked plus untracked, honouring `.gitignore` —
+ * so dependency, build and scratch directories follow the project's own rules.
+ * Outside one, a walk skips {@link README_EXCLUDED_DIRS} and dot-directories.
+ * Paths under `skip` (the lake root) are dropped: they are already lake docs.
+ * A tracked file deleted from disk is dropped too — git still lists it.
+ * @param location The project directory the plugin loaded in.
+ * @param skip Absolute roots whose READMEs are collected elsewhere.
+ * @returns Project-relative README paths, ordered by path.
+ */
+export function readmePaths(
+    location: string,
+    skip: readonly string[] = [],
+): string[] {
+    const candidates = gitReadmePaths(location) ?? walkedReadmePaths(location);
+    return candidates
+        .filter((path) => existsSync(join(location, path)))
+        .filter(
+            (path) => !skip.some((root) => isUnder(join(location, path), root)),
+        )
+        .sort();
+}
+
+/**
+ * README paths from git's index and untracked non-ignored files, or undefined
+ * when `location` is not inside a git work tree.
+ */
+function gitReadmePaths(location: string): string[] | undefined {
+    const result = spawnSync(
+        "git",
+        ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+        { cwd: location, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
+    );
+    if (result.status !== 0) {
+        return undefined;
+    }
+    return (result.stdout ?? "")
+        .split("\0")
+        .filter((path) => path !== "" && isReadme(path.split("/").pop() ?? ""));
+}
+
+/** README paths from a directory walk, for a location outside a work tree. */
+function walkedReadmePaths(location: string): string[] {
+    const paths: string[] = [];
+    const excluded = README_EXCLUDED_DIRS as readonly string[];
+    const walk = (directory: string): void => {
+        let entries: Dirent[];
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const item of entries) {
+            const path = join(directory, item.name);
+            if (item.isDirectory()) {
+                if (item.name.startsWith(".") || excluded.includes(item.name)) {
+                    continue;
+                }
+                walk(path);
+            } else if (item.isFile() && isReadme(item.name)) {
+                paths.push(relative(location, path));
+            }
+        }
+    };
+    walk(location);
+    return paths;
+}
+
+/**
+ * Collect the project's nested READMEs as search entries, with the same shape
+ * as lake docs: H1 title, path-derived area, no front-matter.
+ * @param location The project directory the plugin loaded in.
+ * @param resolve Resolves every path's date in one batched call.
+ * @param skip Absolute roots whose READMEs are collected elsewhere.
+ * @returns Entries ordered by path, or none when the project is unreadable.
+ */
+export function collectReadmes(
+    location: string,
+    resolve: (paths: readonly string[]) => ReadonlyMap<string, string>,
+    skip: readonly string[] = [],
+): DocEntry[] {
+    const paths = readmePaths(location, skip);
+    const dates = resolve(paths);
+    return paths.map((path) =>
+        toEntry(
+            path,
+            readFileSync(join(location, path), "utf8"),
+            dates.get(path) ?? "",
+        ),
+    );
+}
+
 /**
  * Kebab-case a doc title into a file-name slug: lower-cased word characters,
  * everything else collapsed to single dashes, dashes trimmed.
@@ -1106,9 +1246,150 @@ export function checkDocs(
         : lines.join("\n");
 }
 
+/** The built-in tools the miss-nudge watches: content searches, both miss-prone. */
+export const NUDGED_TOOLS = ["grep", "glob"] as const;
+
+/**
+ * The text of a tool result's content: the string itself, or its text parts
+ * joined. Non-text parts and foreign shapes contribute nothing.
+ * @param content A `Tool.Result` content of any provenance.
+ * @returns The searchable text, possibly empty.
+ */
+function contentText(content: unknown): string {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        return content
+            .map((part) =>
+                typeof part === "object" &&
+                part !== null &&
+                "text" in part &&
+                typeof (part as { text: unknown }).text === "string"
+                    ? (part as { text: string }).text
+                    : "",
+            )
+            .join("\n");
+    }
+    return "";
+}
+
+/**
+ * Whether a grep/glob result reads as a search miss. Raw rg prints nothing
+ * on a miss (exit 1, empty stdout) — "No matches found" and "No files found"
+ * are the host wrapper's phrasings — so emptiness is the primary signal and
+ * the phrases are a bonus that keeps working if the wrapper rewords.
+ * @param content The tool result's content (string or content parts).
+ * @returns True when the result is a miss.
+ */
+export function isSearchMiss(content: unknown): boolean {
+    const trimmed = contentText(content).trim();
+    return trimmed === "" || /no (matches|files) found/i.test(trimmed);
+}
+
+/** The grep/glob call's `pattern`, when the input carries a string one. */
+function patternOf(input: unknown): string {
+    if (typeof input === "object" && input !== null && "pattern" in input) {
+        const pattern = (input as { pattern: unknown }).pattern;
+        if (typeof pattern === "string") {
+            return pattern.trim();
+        }
+    }
+    return "";
+}
+
+/**
+ * The one-line pointer appended to a grep/glob miss: the docs tool indexes
+ * the same knowledge, so echo the failed pattern when there is one.
+ * @param pattern The failed call's pattern, possibly blank.
+ * @returns The nudge line.
+ */
+export function missNudge(pattern: string): string {
+    const suggestion =
+        pattern === ""
+            ? "a knowledge question may already be answered there."
+            : `try \`docs search\` with terms from "${pattern}".`;
+    return (
+        "Note: the `docs` tool also indexes the knowledge docs and project " +
+        `READMEs before you move on — ${suggestion}`
+    );
+}
+
+/** One tool call, as the miss-nudge decision sees it. */
+export interface NudgeCall {
+    /** The tool's registered name. */
+    readonly tool: string;
+    /** `"completed"` results only — an errored call is not a knowledge miss. */
+    readonly status: "completed" | "error";
+    /** The result's content (string or parts). */
+    readonly content: unknown;
+    /** The call's input, for the failed pattern. */
+    readonly input: unknown;
+}
+
+/**
+ * The nudge line for a tool call, or null when the call deserves none: not a
+ * watched tool, an errored call, a genuine hit, or a session that has already
+ * been nudged (or already used the lake).
+ * @param call The tool call to judge.
+ * @param alreadyNudged Whether the session was nudged — or used the docs
+ * tool — already.
+ * @returns The line to append, or null.
+ */
+export function missNudgeFor(
+    call: NudgeCall,
+    alreadyNudged: boolean,
+): string | null {
+    if (alreadyNudged || call.status !== "completed") {
+        return null;
+    }
+    if (!(NUDGED_TOOLS as readonly string[]).includes(call.tool)) {
+        return null;
+    }
+    if (!isSearchMiss(call.content)) {
+        return null;
+    }
+    return missNudge(patternOf(call.input));
+}
+
+/**
+ * The system part injected into compaction requests: the summariser has no
+ * tools, so it cannot record — instead it shapes each durable finding as its
+ * own record-ready block for the continuing agent, one artifact per topic,
+ * 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 — " +
+    "never one session dump. Each block names its own artifact's `Area`, " +
+    "`H1` title and `Keywords`, plus a one-line what-and-why, so the next " +
+    "agent can persist each as a separate focused doc.";
+
+/**
+ * Resolve the plugin's `nudge` option: unset means on; a boolean passes
+ * through; anything else throws, matching `root`'s loud-failure precedent.
+ * @param configured The raw option value as the host delivers it.
+ * @returns Whether the runtime nudges are active.
+ */
+export function resolveNudge(configured: unknown): boolean {
+    if (configured === undefined) {
+        return true;
+    }
+    if (typeof configured === "boolean") {
+        return configured;
+    }
+    throw new Error(
+        `docs plugin option 'nudge' must be a boolean, ` +
+            `got ${JSON.stringify(configured)}.`,
+    );
+}
+
 export interface DocsToolDeps {
-    /** Collects the docs to serve; injected so the tool is testable. */
+    /** Collects the lake docs; `add` and `check` use only these. */
     collect: () => DocEntry[];
+    /** Collects everything searchable — lake docs plus local READMEs; defaults to `collect`. */
+    search?: () => DocEntry[];
     /** Whether a root-relative doc path exists; injected so writes are testable. */
     exists: (path: string) => boolean;
     /** Writes a root-relative doc path; injected so writes are testable. */
@@ -1126,8 +1407,10 @@ export type PromptSender = (
 ) => Promise<unknown>;
 
 export interface DocsCommandDeps {
-    /** Collects the docs to serve; injected so the command is testable. */
+    /** Collects the lake docs; `add` and `check` use only these. */
     collect: () => DocEntry[];
+    /** Collects everything searchable — lake docs plus local READMEs; defaults to `collect`. */
+    search?: () => DocEntry[];
     /** Reads a root-relative doc path's raw contents; injected so `check` is testable. */
     read: (path: string) => string;
     /** Environment notes appended to the `check` report; injected for testability. */
@@ -1136,19 +1419,45 @@ export interface DocsCommandDeps {
     prompt: PromptSender;
 }
 
+/**
+ * The twin's description: the Code Mode catalog is injected into every
+ * `execute` prompt, so it pays its way in a short paragraph — the verbs, not
+ * the full doctrine the native `docs` description carries.
+ */
+const TWIN_DESCRIPTION =
+    "Search, read, add and check the knowledge docs under the configured " +
+    "docs root (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 " +
+    "convention.";
+
 /**
  * Build the `docs` tool from its dependencies.
  *
- * Registered with `codemode: false` so the tool stays on the provider's native
- * tool list. That option is exclusive: a tool defaults into Code Mode
- * (`codemode` defaults true) and is dropped from the native list; only
- * `codemode: false` keeps it natively callable. This tool is called directly,
- * so it opts out.
+ * By default the tool is registered with `codemode: false` so it stays on the
+ * provider's native tool list. That option is exclusive: a tool defaults into
+ * Code Mode (`codemode` defaults true) and is dropped from the native list;
+ * only `codemode: false` keeps it natively callable — and `codemode: true`
+ * with a `namespace` is how the host's own plugins expose tools to `execute`
+ * (the catalog renders `tools.<namespace>.<name>(…)`). Pass a distinct
+ * `name` and `codemode: true` to register a Code Mode twin of the same core;
+ * the registry is name-keyed, so the twin cannot also be called `docs`.
  * @param deps Runtime seams used on each call: the docs to serve, and the
  * write seam {@link DocsToolDeps} for `add`.
+ * @param options Registration shape.
+ * @param options.name The tool name (default `"docs"`); a Code Mode twin
+ * passes a distinct name — the registry is name-keyed, so two tools cannot
+ * share one.
+ * @param options.codemode True to register for the `execute` catalog under
+ * the `docs` namespace (default `false` — the native tool list).
  * @returns The tool the host registers.
  */
-export function createDocsTool(deps: DocsToolDeps): Info<typeof DOCS_INPUT> {
+export function createDocsTool(
+    deps: DocsToolDeps,
+    options: { name?: string; codemode?: boolean } = {},
+): Info<typeof DOCS_INPUT> {
+    const { name = "docs", codemode = false } = options;
     const addDoc = (add: DocsAdd) => {
         const outcome = prepareAdd(add, deps.collect());
         if (outcome.action === "refuse") {
@@ -1166,17 +1475,45 @@ export function createDocsTool(deps: DocsToolDeps): Info<typeof DOCS_INPUT> {
             metadata: { written: true },
         };
     };
+    const readDoc = (given: string) => {
+        // The same guard an explicit `add` path passes: relative, inside the
+        // root, a `.md` file — the read verb never widens the surface.
+        const target = explicitTarget(given.trim());
+        if ("reason" in target) {
+            return {
+                content: `${REFUSE} ${target.reason}`,
+                metadata: { read: null },
+            };
+        }
+        if (!deps.exists(target.path)) {
+            return {
+                content: `No doc at ${target.path}.`,
+                metadata: { read: null },
+            };
+        }
+        const raw = deps.read(target.path);
+        const { body } = parseFrontMatter(raw);
+        return {
+            content: `${target.path} — ${titleOf(target.path, body)}\n\n${raw}`,
+            metadata: { read: target.path },
+        };
+    };
     return {
-        name: "docs",
-        description:
-            "Discover the knowledge docs under the configured docs root " +
-            "(default: the location's `docs/` directory). 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 and summary, falling back to the closest matches. Every call returns at most " +
-            MAX_RESULTS +
-            " results and counts the rest. Search exactly `help` explains the ranking. `add` writes a new knowledge doc (or wholesale-replaces the doc at `path`) from a typed DTO — metadata becomes front-matter, the body must start with an H1; blank required fields, path traversal, non-.md targets and same-area near-twins are refused. `check` validates every doc against the convention (required front-matter, H1, claim sections, no hand-maintained Date, distinctive H1+Keywords, a Supersedes naming a doc in the tree, near-twins) and reports findings; an empty report means compliant. Read a matched file with the read tool.",
+        name,
+        description: codemode
+            ? TWIN_DESCRIPTION
+            : "Discover the knowledge docs under the configured docs root " +
+              "(default: the location's `docs/` directory), 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 and summary, falling back to the closest matches. Every call returns at most " +
+              MAX_RESULTS +
+              " results and counts the rest. Search exactly `help` explains the ranking. `read` returns a matched doc verbatim (front-matter and body). `add` writes a new knowledge doc (or wholesale-replaces the doc at `path`) from a typed DTO — metadata becomes front-matter, the body must start with an H1; blank required fields, path traversal, non-.md targets and same-area near-twins are refused. `check` validates every doc against the convention (required front-matter, H1, claim sections, no hand-maintained Date, distinctive H1+Keywords, a Supersedes naming a doc in the tree, near-twins) and reports findings; an empty report means compliant. Local READMEs are search-only: `add` and `check` ignore them. Read a matched project file with the built-in read tool.",
         input: DOCS_INPUT,
-        options: { codemode: false },
+        options: codemode
+            ? { namespace: "docs", codemode: true }
+            : { codemode: false },
         async execute(input) {
             const request = resolveRequest(input);
             if (request.verb === "add") {
@@ -1189,6 +1526,9 @@ export function createDocsTool(deps: DocsToolDeps): Info<typeof DOCS_INPUT> {
                     metadata: { checked: entries.length },
                 };
             }
+            if (request.verb === "read") {
+                return readDoc(request.read);
+            }
             if (request.verb === "help") {
                 return {
                     content: explainRanking(),
@@ -1196,7 +1536,7 @@ export function createDocsTool(deps: DocsToolDeps): Info<typeof DOCS_INPUT> {
                 };
             }
             const { entries, closest, omitted } = rankDocs(
-                deps.collect(),
+                (deps.search ?? deps.collect)(),
                 request.search,
             );
             return {
@@ -1243,7 +1583,7 @@ export function createDocsCommand(deps: DocsCommandDeps): CommandDefinition {
     return {
         name: "docs",
         description:
-            "Search the knowledge docs under the configured docs root, ranked; `add <text>` records new knowledge through the tool's typed `add`; `check` validates the convention; a blank search lists the " +
+            "Search the knowledge docs under the configured docs root, ranked, plus nested project `README.md` files (search only); `add <text>` records new knowledge through the tool's typed `add`; `check` validates the convention; a blank search lists the " +
             MAX_RESULTS +
             " most recently changed.",
         async execute({ sessionID, prompt }) {
@@ -1267,7 +1607,7 @@ export function createDocsCommand(deps: DocsCommandDeps): CommandDefinition {
             }
             const query = lower === SEARCH_VERB ? rest.join(" ") : text;
             const { entries, closest, omitted } = rankDocs(
-                deps.collect(),
+                (deps.search ?? deps.collect)(),
                 query,
             );
             await deps.prompt(sessionID, render(entries, { closest, omitted }));
@@ -1277,10 +1617,12 @@ export function createDocsCommand(deps: DocsCommandDeps): CommandDefinition {
 
 /**
  * Resolve the plugin's docs root from its `root` option. Unset → the
- * location's `docs/` directory; `~` or `~/…` expands against the home
+ * location's `docs/` directory — a blank string counts as unset, since it is
+ * almost always an empty environment variable or half-finished config rather
+ * than a deliberate path; `~` or `~/…` expands against the home
  * directory; absolute paths pass through; anything else resolves against the
  * plugin location. The resolved value is the knowledge tree itself — no
- * segment is appended. A non-string or blank value throws: a mistyped option
+ * segment is appended. A non-string value throws: a mistyped option
  * must fail loudly, not silently fall back to the wrong tree.
  * @param configured The raw option value as the host delivers it.
  * @param locationDirectory The directory the plugin instance loaded in.
@@ -1293,13 +1635,16 @@ export function resolveRoot(
     if (configured === undefined) {
         return join(locationDirectory, "docs");
     }
-    if (typeof configured !== "string" || configured.trim() === "") {
+    if (typeof configured !== "string") {
         throw new Error(
             `docs plugin option 'root' must be a non-empty string path, ` +
                 `got ${JSON.stringify(configured)}.`,
         );
     }
     const given = configured.trim();
+    if (given === "") {
+        return join(locationDirectory, "docs");
+    }
     const expanded =
         given === "~" || given.startsWith("~/")
             ? join(homedir(), given.slice(1))
@@ -1336,6 +1681,27 @@ export function unversionedNote(root: string): readonly string[] {
 interface DocsPluginOptions {
     /** The docs root override; defaults to `docs` beside the plugin. */
     root?: unknown;
+    /** The runtime nudges' switch; defaults to on. */
+    nudge?: unknown;
+}
+
+/** The registered tool names that count as using the lake. */
+const DOCS_TOOL_NAMES = new Set(["docs", "docs_search"]);
+
+/**
+ * Content with `line` appended: string concatenation, or one extra text part.
+ * @param content The tool result's content, when it has one.
+ * @param line The nudge line.
+ * @returns The content to write back.
+ */
+function appendLine(
+    content: NonNullable<Result["content"]> | undefined,
+    line: string,
+): NonNullable<Result["content"]> {
+    if (typeof content === "string" || content === undefined) {
+        return `${content ?? ""}\n\n${line}`;
+    }
+    return [...content, { type: "text", text: line }];
 }
 
 export default Plugin.define({
@@ -1343,22 +1709,41 @@ export default Plugin.define({
     async setup(ctx) {
         const options = ctx.options as DocsPluginOptions | undefined;
         const root = resolveRoot(options?.root, ctx.location.directory);
+        const nudge = resolveNudge(options?.nudge);
         const notes = unversionedNote(root);
         const collect = () =>
             collectDocs(root, (paths) => fallbackDates(root, paths));
+        const search = () => [
+            ...collect(),
+            ...collectReadmes(
+                ctx.location.directory,
+                (paths) => fallbackDates(ctx.location.directory, paths),
+                [root],
+            ),
+        ];
         const read = (path: string) => readFileSync(join(root, path), "utf8");
+        const toolDeps = {
+            collect,
+            search,
+            exists: (path: string) => existsSync(join(root, path)),
+            write: (path: string, contents: string) => {
+                const target = join(root, path);
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, contents);
+            },
+            read,
+            notes,
+        };
+        // Two registrations of one core: the native `docs` for direct calls,
+        // and the Code Mode twin `docs_search` so `execute` reaches the same
+        // lake as `tools.docs.docs_search(…)`. The registry is name-keyed, so
+        // the twin must carry its own name.
         await ctx.tool.transform((editor) => {
+            editor.add(createDocsTool(toolDeps));
             editor.add(
-                createDocsTool({
-                    collect,
-                    exists: (path) => existsSync(join(root, path)),
-                    write: (path, contents) => {
-                        const target = join(root, path);
-                        mkdirSync(dirname(target), { recursive: true });
-                        writeFileSync(target, contents);
-                    },
-                    read,
-                    notes,
+                createDocsTool(toolDeps, {
+                    name: "docs_search",
+                    codemode: true,
                 }),
             );
         });
@@ -1366,13 +1751,58 @@ export default Plugin.define({
             editor.add(
                 createDocsCommand({
                     collect,
+                    search,
                     read,
                     notes,
-                    prompt: (sessionID, text) =>
-                        ctx.session.prompt({ sessionID, text }),
+                    prompt: (sessionID, text) => {
+                        // Any `/docs` use counts as consulting the lake.
+                        nudged.add(sessionID);
+                        return ctx.session.prompt({ sessionID, text });
+                    },
                 }),
             );
         });
+        // The nudges (default on; `nudge: false` restores silence). The
+        // miss-nudge fires once per session, at the first grep/glob miss, and
+        // is fail-quiet by construction — it must never break the tool it
+        // wraps. The record-nudge rides compaction: the summariser has no
+        // tools, so it shapes record-ready blocks for the continuing agent.
+        const nudged = new Set<string>();
+        if (nudge) {
+            await ctx.tool.hook("execute.after", (event) => {
+                try {
+                    if (event.status !== "completed") {
+                        return;
+                    }
+                    if (DOCS_TOOL_NAMES.has(event.tool)) {
+                        nudged.add(event.sessionID);
+                        return;
+                    }
+                    const line = missNudgeFor(
+                        {
+                            tool: event.tool,
+                            status: event.status,
+                            content: event.result.content,
+                            input: event.input,
+                        },
+                        nudged.has(event.sessionID),
+                    );
+                    if (line === null) {
+                        return;
+                    }
+                    nudged.add(event.sessionID);
+                    event.result = {
+                        ...event.result,
+                        content: appendLine(event.result.content, line),
+                    };
+                } catch {
+                    // Fail-quiet: a nudge must never break the wrapped tool.
+                }
+            });
+            await ctx.session.hook("compaction", (compaction) => {
+                compaction.system.push({ type: "text", text: RECORD_NUDGE });
+            });
+        }
         // The skill is the doctrine's runtime face. Its content ships next to
         // this module and is resolved through `import.meta.url`, so it works
         // whether the plugin is loaded from a local path or an installed
@@ -1385,11 +1815,16 @@ export default Plugin.define({
                 name: Skill.Name.make("Docs"),
                 description:
                     "The entry point to the knowledge docs under the " +
-                    "configured docs root: find the right file with the docs " +
-                    "tool, read it, and record plans and task documentation " +
-                    "for the next human or agent. Use at the start of " +
-                    "unfamiliar work, when hunting for prior decisions or " +
-                    "traps, and when closing out a session.",
+                    "configured docs root, plus the project's nested " +
+                    "README.md files (search only): find the right file with " +
+                    "the docs tool, read it, and record plans and task " +
+                    "documentation for the next human or agent. 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.",
                 path: AbsolutePath.make(fileURLToPath(skillURL)),
                 content: skill,
             });