@markstanden/opencode-docs-plugin 0.2.0 → 0.3.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,16 @@
 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.
+  `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.
 - `/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
@@ -17,6 +20,53 @@ configured docs root's `*.md` files (the `root` plugin option; default
 
 Reading a matched doc stays OpenCode's built-in `read`.
 
+## Installation
+
+From npm:
+
+```sh
+opencode plugin add @markstanden/opencode-docs-plugin
+```
+
+or as a `plugins` entry in `opencode.json(c)` (global, project or `.opencode/`):
+
+```jsonc
+{
+    "$schema": "https://opencode.ai/config.json",
+    "plugins": ["@markstanden/opencode-docs-plugin"],
+}
+```
+
+Unpinned entries update on the next server start or `opencode plugin update`;
+an exact version (e.g. `@0.2.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:
+
+```jsonc
+{
+    "$schema": "https://opencode.ai/config.json",
+    "plugins": [
+        {
+            "package": "@markstanden/opencode-docs-plugin",
+            "options": {
+                "root": "~/doclake",
+            },
+        },
+    ],
+}
+```
+
+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.
+
 ## Status
 
 Standalone extract of the docs tooling, under active development.

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.2.0",
+    "version": "0.3.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

@@ -36,6 +36,13 @@ 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.

package/src/index.ts

@@ -7,6 +7,7 @@ import type {
 import type { Info } 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";
 
@@ -595,6 +596,7 @@ 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");
@@ -738,6 +740,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.
@@ -1107,8 +1235,10 @@ export function checkDocs(
 }
 
 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 +1256,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. */
@@ -1170,11 +1302,12 @@ export function createDocsTool(deps: DocsToolDeps): Info<typeof DOCS_INPUT> {
         name: "docs",
         description:
             "Discover the knowledge docs under the configured docs root " +
-            "(default: the location's `docs/` directory). A blank search lists the " +
+            "(default: the location's `docs/` directory), plus nested `README.md` " +
+            "files in the project tree. 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.",
+            " 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. Local READMEs are search-only: `add` and `check` ignore them. Read a matched file with the read tool.",
         input: DOCS_INPUT,
         options: { codemode: false },
         async execute(input) {
@@ -1196,7 +1329,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 +1376,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 +1400,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 +1410,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 +1428,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))
@@ -1346,11 +1484,20 @@ export default Plugin.define({
         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");
         await ctx.tool.transform((editor) => {
             editor.add(
                 createDocsTool({
                     collect,
+                    search,
                     exists: (path) => existsSync(join(root, path)),
                     write: (path, contents) => {
                         const target = join(root, path);
@@ -1366,6 +1513,7 @@ export default Plugin.define({
             editor.add(
                 createDocsCommand({
                     collect,
+                    search,
                     read,
                     notes,
                     prompt: (sessionID, text) =>
@@ -1385,11 +1533,12 @@ 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 at the " +
+                    "start of unfamiliar work, when hunting for prior " +
+                    "decisions or traps, and when closing out a session.",
                 path: AbsolutePath.make(fileURLToPath(skillURL)),
                 content: skill,
             });