@plurnk/plurnk-schemes 0.29.3 → 0.29.4

package/README.md

@@ -42,6 +42,11 @@ Implement only the op methods you support — `read` / `find` / `edit` / `copy`
 ### 3. Declare the manifest — including self-doc
 
 ```ts
+import { readFile } from "node:fs/promises";
+
+// Deep doc lives in docs/foo.md (convention); loaded at module init.
+const documentation = await readFile(new URL("../docs/foo.md", import.meta.url), "utf-8");
+
 static manifest: SchemeManifest = {
   name: "foo",
   channels: { body: "text/markdown" },
@@ -53,12 +58,12 @@ static manifest: SchemeManifest = {
   modelVisible: true,
   glyph: "🦊",                          // display icon; omit → the name is shown
   example: "READ(foo://thing/42)",      // terse hot-path one-liner, rendered every turn
-  documentation: "# foo\n\nOps, channels, edge cases…" // deep doc, pulled at plurnk://docs/foo.md
+  documentation,                        // deep doc from docs/foo.md, pulled at plurnk://docs/foo.md
 };
 ```
 
 - **`example`** — the scheme's terse **hot-path** one-liner, rendered in the live catalogue every turn (like an execs runtime's `example`). Keep it to one canonical usage line; depth goes in `documentation`. Omit → not advertised.
-- **`documentation`** — the **deep doc** (ops, channels, edge cases). The consumer materializes it as a pull-able `plurnk://docs/<name>.md` entry the model READs on demand — off the hot path. Mirrors `ExecInfo.documentation`.
+- **`documentation`** — the **deep doc** (ops, channels, edge cases). The consumer materializes it as a pull-able `plurnk://docs/<name>.md` entry the model READs on demand — off the hot path. Mirrors `ExecInfo.documentation`. **Convention:** keep it in a **`docs/<name>.md`** file (root) and load it at module init with the snippet above — `../` resolves the same from `src/` (test) and `dist/` (built); add `docs/**/*` to `files`. A missing file fails-hard at import.
 - **`glyph`** — a display icon (emoji / nerdfont). Omit it and the scheme `name` is rendered in its place.
 
 ### 4. Self-doc: terse pushes, depth pulls

package/SPEC.md

@@ -50,6 +50,8 @@ class Known {
 
 **Self-doc split (terse pushes, depth pulls).** `example` + `glyph` are the hot-path listing rendered every turn — keep them terse. `documentation` is the deep prose (every op, channel, status code, gotcha); the consumer materializes it as a pull-able **`plurnk://docs/<name>.md`** entry the model READs on demand, off the hot path. Both live on the manifest; the consumer decides what's pushed vs pulled.
 
+**Authoring convention — `docs/<name>.md`.** The contract field stays a plain `string`, but a sibling SHOULD keep the deep doc in a **`docs/<name>.md`** file at the package root rather than inline, and load it into the manifest at module init — e.g. `documentation: await readFile(new URL("../docs/<name>.md", import.meta.url), "utf-8")` (top-level await; `../` resolves identically from `src/` in test and `dist/` once built). Ship it by adding `docs/**/*` to `files`. This keeps prose out of the handler source and gives editors real Markdown; the contract and the consumer's `plurnk://docs/<name>.md` materialization are unchanged. A missing file fails-hard at import (no silent empty doc).
+
 ## §2 Interface
 
 Sister scheme handlers implement op methods consumed by plurnk-service via dispatch: the engine calls `handler[statement.op.toLowerCase()](statement, ctx)` and returns **501** for any op whose method is absent. The op-dispatch surface is the exported **`SchemeHandler`** interface — every method optional, each `(statement, ctx) => Promise<SchemeResult>`, the per-op statement type from grammar:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-schemes",
-    "version": "0.29.3",
+    "version": "0.29.4",
     "description": "Framework + contract for the @plurnk/plurnk-schemes-* URI handler family.",
     "keywords": [
         "plurnk",