@g3nomaly/g3n-skills 0.1.3 → 0.1.5

package/.claude-plugin/marketplace.json

@@ -17,11 +17,12 @@
     {
       "name": "coding",
       "source": "./skills/coding",
-      "description": "How to write, check and document code, per language, and query a repository with analyze.",
+      "description": "How to write, check and document code, per language, query a repository with analyze, and keep its glossary.",
       "skills": [
         "./code",
         "./document",
-        "./analyze"
+        "./analyze",
+        "./vocabulary"
       ]
     },
     {
@@ -49,13 +50,26 @@
     {
       "name": "task-manager",
       "source": "./skills/task-manager",
-      "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions and the project vocabulary kept beside them.",
+      "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions kept beside them.",
       "skills": [
         "./task-manager",
-        "./vocabulary",
         "./decisions"
       ]
     },
+    {
+      "name": "teach",
+      "source": "./skills/teach",
+      "description": "Teach through real work: build, explain, dive deep, decide architecture, debug and review while the user learns the reasoning.",
+      "skills": [
+        "./teaching",
+        "./learn-by-building",
+        "./explain",
+        "./deep-dive",
+        "./architecture",
+        "./guided-debugging",
+        "./guided-review"
+      ]
+    },
     {
       "name": "using-hooks",
       "source": "./skills/using-hooks",

package/README.md

@@ -1,6 +1,6 @@
 # @g3nomaly/g3n-skills
 
-The g3n skills for Claude Code and Codex: 31 skills in 8 groups. This package holds the skills and has no CLI. Install them with [`@g3nomaly/skills`](https://www.npmjs.com/package/@g3nomaly/skills), which reads this package as its built-in source, or read it as a Claude Code plugin marketplace.
+The g3n skills for Claude Code and Codex: 38 skills in 9 groups. This package holds the skills and has no CLI. Install them with [`@g3nomaly/skills`](https://www.npmjs.com/package/@g3nomaly/skills), which reads this package as its built-in source, or read it as a Claude Code plugin marketplace.
 
 Some skills carry their own hooks. A hook is a TypeScript file in the skill's `hooks/` folder, and the agent runs it with `bun`. The task-manager hooks keep plans, phases and tasks as Markdown files that the agent reaches only through those hooks. The workflow hooks decide when a step of a phase is finished.
 
@@ -54,6 +54,7 @@ Skills marked _manual_ run only when you type their command, such as `/grill-me`
 | `coding` | `code` | Rules for writing and checking code, with a toolchain reference per language |
 | `coding` | `document` | Docstrings and comments for functions and classes, and where the reasons behind code go |
 | `coding` | `analyze` | Query a repository's model with `g3n-analyze` and rebuild its documentation site in `analyze_out/` |
+| `coding` | `vocabulary` | One word per concept, recorded in `docs/glossary.md`, so names don't drift between sessions |
 | `grilling` | `grilling` | Interview the user relentlessly to stress-test a plan, decision or idea |
 | `grilling` | `grill-me` | _Manual._ Starts a `/grilling` session |
 | `grilling` | `grill-with-docs` | _Manual._ A grilling session that writes ADRs and a glossary as it goes |
@@ -63,8 +64,14 @@ Skills marked _manual_ run only when you type their command, such as `/grill-me`
 | `speech` | `plain-language` | Write text readers can find, understand and use on the first read, following ISO 24495-1 |
 | `speech` | `no-questions` | Replies end without questions or offers; a Stop hook refuses a reply that asks one |
 | `task-manager` | `task-manager` | Query plans, phases and tasks and change their status through hooks |
-| `task-manager` | `vocabulary` | One word per concept, stored in the task-manager tree, so names don't drift between sessions |
 | `task-manager` | `decisions` | Record and look up a plan's decisions as numbered files inside the plan |
+| `teach` | `teaching` | The teaching principles every teach skill follows: real work, causality, mental models and guidance per concept |
+| `teach` | `learn-by-building` | Learn a subject while completing a real task on the user's own system |
+| `teach` | `explain` | Explain existing material through its purpose, mental model, flow and failure modes |
+| `teach` | `deep-dive` | Trace the layers beneath an abstraction, only as deep as the question needs |
+| `teach` | `architecture` | Reason from forces and options to an architecture decision and its consequences |
+| `teach` | `guided-debugging` | Find a failure's root cause through hypotheses and small experiments, teaching the method |
+| `teach` | `guided-review` | Review work by consequence and explain the principle behind each finding |
 | `using-hooks` | `hook-pre-tool-use` | _Manual._ Writing a `PreToolUse` hook, which can allow, deny or escalate a tool call |
 | `using-hooks` | `hook-post-tool-use` | _Manual._ Writing a `PostToolUse` hook, which reacts to a finished tool call |
 | `using-hooks` | `hook-stop` | _Manual._ Writing a `Stop` hook, which can refuse to let the agent end its turn |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-skills",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "The g3n skills, each with its own hooks: a skill source for @g3nomaly/skills and a Claude Code plugin marketplace.",
   "type": "module",
   "files": [
@@ -15,7 +15,7 @@
     "test:clean": "CLEAN_TMP=1 bun test"
   },
   "devDependencies": {
-    "@g3nomaly/core": "^0.3.3",
+    "@g3nomaly/core": "^0.3.5",
     "@types/bun": "^1.4.0",
     "typescript": "~7.0.2",
     "zod": "^4.4.3"

package/skills/coding/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "coding",
-  "description": "How to write, check and document code, per language, and query a repository with analyze.",
+  "description": "How to write, check and document code, per language, query a repository with analyze, and keep its glossary.",
   "version": "0.1.0",
   "license": "UNLICENSED",
-  "skills": ["./code", "./document", "./analyze"]
+  "skills": ["./code", "./document", "./analyze", "./vocabulary"]
 }

package/skills/coding/code/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: false
 Apply SOLID principles, DRY, and KISS. Use descriptive names for variables, functions, and classes.
 
 - **One domain per file**: schemas, selectors and business logic live in separate files. Split god objects.
-- **Strict typing**: per the language reference. Python passes `mypy` or `pyright`.
+- **Strict typing**: per the language reference.
 - **Production grade**: handle errors explicitly, validate external input at the boundary, leave no dead code.
 - **No shims**: on a rename or refactor, update every call site. Leave no aliases.
 - **Config from the environment**: read configuration from environment variables through a schema.
@@ -26,3 +26,6 @@ Each language has a reference that names its toolchain, its commands and its rul
 | Language | Reference | Files |
 |---|---|---|
 | TypeScript | [`references/typescript.md`](references/typescript.md) | `.ts` `.tsx` |
+| Python | [`references/python.md`](references/python.md) | `.py` |
+| C++ | [`references/cpp.md`](references/cpp.md) | `.cpp` `.cc` `.hpp` `.h` |
+| Rust | [`references/rust.md`](references/rust.md) | `.rs` |

package/skills/coding/code/references/cpp.md

@@ -0,0 +1,43 @@
+# C++
+
+CMake configures and builds with clang. vcpkg supplies dependencies in manifest mode, from `vcpkg.json`. Run commands from inside the project directory, where `CMakeLists.txt` lives.
+
+| Task | Command |
+|---|---|
+| Configure | `cmake --preset <preset>` when `CMakePresets.json` exists, otherwise `cmake -S . -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` |
+| Add a dependency | `vcpkg add port <pkg>`, then `find_package` and `target_link_libraries` in `CMakeLists.txt` |
+| Build | `cmake --build build` |
+| Run | the target's binary under `build/` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Build | `cmake --build build` | always |
+| Format | `clang-format --dry-run --Werror <files>`, or `clang-format -i <files>` to fix | always |
+| Lint | see [clang-tidy](#clang-tidy) | always |
+| Test | `ctest --test-dir build --output-on-failure` | when the project has tests |
+
+## clang-tidy
+
+Its output is long enough to be cut off in a tool result, and it exits `0` on warnings. Never judge it from the terminal output.
+
+1. Run it in the foreground, all output to a log:
+
+   ```bash
+   clang-tidy -p build --quiet --warnings-as-errors='*' <files> > build/clang-tidy.log 2>&1; echo "exit $?"
+   ```
+
+2. Count the findings: `grep -cE ':[0-9]+:[0-9]+: (warning|error):' build/clang-tidy.log`.
+3. List them: `grep -nE ':[0-9]+:[0-9]+: (warning|error):' build/clang-tidy.log`. When the list itself is long, page through it with `sed -n '1,100p'`, then the next 100, until the line count matches step 2.
+
+The check passes only when the exit code is `0` **and** the count is `0`. Never pipe clang-tidy into `head` or `tail`, and never run it in the background.
+
+## Rules
+
+- Never install libraries with `apt` or vendor them by hand. vcpkg owns dependencies.
+- `.clang-format` and `.clang-tidy` at the project root set the style. Fix the code, not the config, to pass a check.
+- The C++ standard is set once in `CMakeLists.txt`. Do not raise it without asking.
+- Targets compile with `-Wall -Wextra -Wpedantic -Werror`.
+- RAII for every resource. Ownership goes through `std::unique_ptr` or `std::shared_ptr`, never a raw `new` or `delete`.
+- External input is parsed into typed objects at the boundary.

package/skills/coding/code/references/python.md

@@ -0,0 +1,28 @@
+# Python
+
+uv handles install, run and build. Run commands from inside the project directory, where `pyproject.toml` lives.
+
+| Task | Command |
+|---|---|
+| Install | `uv sync` |
+| Add a dependency | `uv add <pkg>`, or `uv add --dev <pkg>` for dev |
+| Run a file | `uv run <file>` |
+| Run a tool once | `uvx <tool>` |
+| Build | `uv build` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Typecheck | `uv run ty check` | always |
+| Lint | `uv run ruff check --fix`, then fix what remains by hand | always |
+| Format | `uv run ruff format --check`, or `uv run ruff format` to fix | always |
+| Test | `uv run pytest` | when the project has tests |
+
+## Rules
+
+- Never `pip`, `python -m venv` or `poetry`. uv owns the environment.
+- Ruff and ty read their settings from `pyproject.toml`. Fix the code, not the config, to pass a check.
+- Every function signature has type hints, including the return type.
+- `object` and narrowing in place of `Any`.
+- External input is parsed into typed objects at the boundary.

package/skills/coding/code/references/rust.md

@@ -0,0 +1,26 @@
+# Rust
+
+Cargo handles install, run, test and build. Run commands from inside the crate or workspace directory, where `Cargo.toml` lives.
+
+| Task | Command |
+|---|---|
+| Install | `cargo fetch`, or let `cargo build` fetch |
+| Add a dependency | `cargo add <crate>`, or `cargo add --dev <crate>` for dev |
+| Run | `cargo run` |
+| Build | `cargo build`, or `cargo build --release` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Typecheck | `cargo check` | always |
+| Lint | `cargo clippy --all-targets -- -D warnings` | always |
+| Format | `cargo fmt --check`, or `cargo fmt` to fix | always |
+| Test | `cargo test` | when the crate has tests |
+
+## Rules
+
+- Fix the code, not the lint config, to pass a check. No `#[allow(...)]` to silence clippy.
+- Errors return as `Result` and travel with `?`. No `unwrap` or `expect` outside tests.
+- No `unsafe` without asking.
+- External input is parsed into typed structs at the boundary, e.g. with `serde`.

package/skills/coding/document/SKILL.md

@@ -54,3 +54,13 @@ A decision is a choice **the user** made, with its _why_, never the _how_. A cho
 The syntax for each language:
 
 - TypeScript: [`references/typescript.md`](references/typescript.md)
+- Python: [`references/python.md`](references/python.md)
+- C++: [`references/cpp.md`](references/cpp.md)
+- Rust: [`references/rust.md`](references/rust.md)
+
+## Editor highlighting
+
+Only when the user asks for docstring highlighting in VS Code. `<document-dir>` is the folder holding this `SKILL.md`.
+
+1. **Install**: `bun <document-dir>/hooks/install-highlighting.ts`. It installs the extension in `vscode/`, which colours Rust doc sections and Python docstring sections like JSDoc tags, and turns off rust-analyzer's comment tokens that would cover them. On exit `1`, report its message.
+2. **Reload**: tell the user to run `Developer: Reload Window`. Done when they see the colours.

package/skills/coding/document/hooks/install-highlighting.ts

@@ -0,0 +1,136 @@
+// packages/g3n-skills/skills/coding/document/hooks/install-highlighting.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The editor setting that lets rust-analyzer paint over every grammar inside comments. */
+const RUST_COMMENT_TOKENS = "rust-analyzer.semanticHighlighting.comments.enable";
+
+/** Folder of the grammar-only extension this hook installs. */
+const EXTENSION_DIR = path.join(import.meta.dir, "..", "vscode");
+
+/**
+ * @brief Identity of the extension, read from its `package.json`.
+ *
+ * @property id - `publisher.name`, e.g. `g3nomaly.g3n-doc-tags`.
+ * @property version - Version from `package.json`, e.g. `0.1.0`.
+ */
+type Extension = { id: string; version: string };
+
+/**
+ * @brief Reads the id and version of the extension in `EXTENSION_DIR`.
+ *
+ * @returns The extension's identity.
+ * @throws Error when `package.json` lacks `publisher`, `name` or `version`.
+ */
+function readExtension(): Extension {
+  const manifest: unknown = JSON.parse(fs.readFileSync(path.join(EXTENSION_DIR, "package.json"), "utf8"));
+  if (typeof manifest !== "object" || manifest === null) throw new Error("vscode/package.json is not an object");
+  const { publisher, name, version } = manifest as Record<string, unknown>;
+  if (typeof publisher !== "string" || typeof name !== "string" || typeof version !== "string") {
+    throw new Error("vscode/package.json needs publisher, name and version");
+  }
+  return { id: `${publisher}.${name}`, version };
+}
+
+/**
+ * @brief Runs a command and fails with its output when it exits non-zero.
+ *
+ * @param command - Program and arguments, e.g. `["code", "--install-extension", "x.vsix"]`.
+ * @param cwd - Working directory of the command.
+ * @throws Error with the command's stderr when it exits non-zero.
+ */
+function run(command: string[], cwd: string): void {
+  const result = Bun.spawnSync(command, { cwd, stdout: "pipe", stderr: "pipe" });
+  if (result.exitCode !== 0) {
+    throw new Error(`${command.join(" ")} failed:\n${result.stderr.toString() || result.stdout.toString()}`);
+  }
+}
+
+/**
+ * @brief Packages the extension into a `.vsix` in a fresh temporary folder, so the skill folder stays untouched.
+ *
+ * @param extension - Identity of the extension, which names the file.
+ * @returns Absolute path of the `.vsix`.
+ */
+function packageExtension(extension: Extension): string {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "g3n-doc-tags-"));
+  const source = path.join(work, "extension");
+  fs.cpSync(EXTENSION_DIR, source, { recursive: true });
+
+  const vsix = path.join(work, `${extension.id}-${extension.version}.vsix`);
+  run(["bunx", "@vscode/vsce@3", "package", "--no-dependencies", "--skip-license", "--allow-missing-repository", "--out", vsix], source);
+  return vsix;
+}
+
+/**
+ * @brief Finds the settings file VS Code reads on this machine: the WSL machine settings when a VS Code server
+ * runs here, otherwise the user settings.
+ *
+ * @returns Absolute path of the settings file, which may not exist yet.
+ */
+function settingsPath(): string {
+  const home = os.homedir();
+  if (fs.existsSync(path.join(home, ".vscode-server"))) return path.join(home, ".vscode-server", "data", "Machine", "settings.json");
+  if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "Code", "User", "settings.json");
+  return path.join(home, ".config", "Code", "User", "settings.json");
+}
+
+/**
+ * @brief Turns off rust-analyzer's comment tokens in `file`, so the extension's colours show. Writes the file
+ * only when the setting is not already `false`.
+ *
+ * @param file - Absolute path of a VS Code settings file.
+ * @returns True when the file was written.
+ * @throws Error when the file is not plain JSON, such as a file with comments, naming the setting to add by hand.
+ */
+function disableRustCommentTokens(file: string): boolean {
+  const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "{}";
+  let settings: unknown;
+  try {
+    settings = JSON.parse(text.trim() === "" ? "{}" : text);
+  } catch {
+    settings = null;
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    throw new Error(`${file} is not plain JSON. Add by hand: "${RUST_COMMENT_TOKENS}": false`);
+  }
+
+  const record = settings as Record<string, unknown>;
+  if (record[RUST_COMMENT_TOKENS] === false) return false;
+  record[RUST_COMMENT_TOKENS] = false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+  return true;
+}
+
+/**
+ * @brief Installs the doc tag highlighting: packages the extension, installs it with VS Code's `code` command,
+ * and turns off rust-analyzer's comment tokens in the VS Code settings. Writes the settings file.
+ *
+ * @param argv - Arguments of the hook. `--pretty` indents the JSON.
+ * @throws Error when `code` is not on the PATH, packaging or installing fails, or the settings are not plain JSON.
+ */
+function main(argv: readonly string[]): void {
+  const code = Bun.which("code");
+  if (code === null) throw new Error("VS Code's `code` command is not on the PATH. Run this from a VS Code terminal.");
+
+  const extension = readExtension();
+  const vsix = packageExtension(extension);
+  run([code, "--install-extension", vsix, "--force"], path.dirname(vsix));
+  fs.rmSync(path.dirname(vsix), { recursive: true, force: true });
+
+  const settings = settingsPath();
+  const settingsChanged = disableRustCommentTokens(settings);
+
+  const result = { extension: `${extension.id}@${extension.version}`, settings, settingsChanged };
+  console.log(JSON.stringify(result, null, argv.includes("--pretty") ? 2 : undefined));
+  console.error("Run `Developer: Reload Window` in VS Code to load the highlighting.");
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/skills/coding/document/references/cpp.md

@@ -0,0 +1,105 @@
+# C++
+
+Doxygen: a `/** */` block directly above the declaration, in the header.
+
+- **Line 1**: `// src/users/user_store.hpp`, the relative path. No `@file` block.
+- **Declarations with a docstring**: functions, classes, structs, enums, type aliases and concepts. The header declaration carries it; the definition in the `.cpp` does not repeat it.
+- **Summary**: `/** Adds two numbers. */` on one line. A longer block opens with `@brief` and the summary.
+- **Tags**: `@param name text`, `@return text`, `@throws Type When ...`, and for the members of a class, struct or enum `@property name text`. Any other tag that fits is fine: `@tparam T text`, `@example`, `@see`, `@deprecated`, `@since`.
+- **Throws**: a function that can throw has one `@throws` tag per exception type, with its full name, e.g. `std::filesystem::filesystem_error`.
+- **Example**: `@example` with the code on the lines below it. Not `@code` ... `@endcode`, which analyze does not read.
+
+```cpp
+/** Adds two numbers. */
+[[nodiscard]] int add(int a, int b);
+
+/**
+ * @brief Retrieves a user by id.
+ *
+ * @param user_id Surrogate key from the `users` table, not the auth provider's id.
+ * @return Custom User class used by the authentication service, or `std::nullopt` when no row matches.
+ */
+[[nodiscard]] std::optional<User> get_user(std::int64_t user_id);
+
+/**
+ * @brief Reads a file and checks it against its schema.
+ *
+ * @param path Absolute path of the file, e.g. `/home/me/app/docs/auth.md`.
+ * @return Custom Tree struct with one node per section of the file.
+ * @throws FileValidationError When a field does not match the schema.
+ * @throws std::filesystem::filesystem_error When the file cannot be read.
+ */
+[[nodiscard]] Tree parse_file(const std::filesystem::path& path);
+
+/**
+ * @brief Error for a file on disk that does not match its schema.
+ *
+ * Holds the path of the file and one issue per rejected field, and `what()`
+ * lists them all. Thrown by `parse_file` and by the readers in `filetree/`,
+ * `decisions/` and `vocabulary/` that check a file's layout by hand. Callers
+ * tell it apart from other errors with `catch (const FileValidationError&)`.
+ *
+ * @property file Absolute path of the file that failed, e.g. `/home/me/app/docs/auth.md`.
+ * @property issues Rejected fields, e.g. `{ "phases.0.status", "is required" }`.
+ *
+ * @example
+ * throw FileValidationError("/home/me/app/docs/auth.md", {{"status", "is \"done\""}});
+ */
+class FileValidationError : public std::runtime_error {
+public:
+    /** Builds the message from the file path and every issue. */
+    FileValidationError(std::filesystem::path file, std::vector<FileValidationIssue> issues);
+
+    const std::filesystem::path file;
+    const std::vector<FileValidationIssue> issues;
+};
+
+/**
+ * @brief Entries a set of requests resolved to, and the requests that did not resolve.
+ *
+ * @property entries Resolved entries by key, e.g. `emphasise`.
+ * @property unknown Requests no source offers, e.g. `ghost@mine`.
+ * @property notes Why an entry nobody named is in the set, e.g. `{ "vocabulary", "dep of plan" }`.
+ */
+struct Resolution {
+    std::unordered_map<std::string, SourceOffer> entries;
+    std::vector<std::string> unknown;
+    std::unordered_map<std::string, std::string> notes;
+};
+```
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```cpp
+struct Resolution {
+    std::vector<std::string> unknown; ///< Requests no source offers.
+};
+```
+A trailing `///<` docstring on a member. Members go in the struct's docstring as `@property` tags.
+
+```cpp
+// Retrieves a user by id.
+std::optional<User> get_user(std::int64_t user_id);
+```
+A plain `//` comment in place of a docstring. Doxygen and clangd only read `/** */`.
+
+```cpp
+/**
+ * @brief Reads a file and checks it against its schema.
+ *
+ * @return The parsed tree. Throws when the file is invalid.
+ */
+[[nodiscard]] Tree parse_file(const std::filesystem::path& path);
+```
+The exception is prose inside `@return`, with no type. Each exception gets its own `@throws` tag, as in `parse_file` above.
+
+```cpp
+/**
+ * Resolves the dependencies of one entry against every offer.
+ *
+ * @param preferred Source to take a key from when several offer it.
+ */
+```
+More than one line without `@brief`. It opens with `@brief Resolves the dependencies...`.

package/skills/coding/document/references/python.md

@@ -0,0 +1,95 @@
+# Python
+
+Google-style docstrings: a `"""` block as the first statement inside the declaration.
+
+- **Line 1**: `# src/app/users.py`, the relative path. No module docstring, so ruff's `D100` and `D104` stay off.
+- **Declarations with a docstring**: functions, methods, classes, dataclasses, `TypedDict`s, `Protocol`s and enums.
+- **Summary**: `"""Adds two numbers."""` on one line. The first line is the `@brief`: a longer block opens with the summary, then a blank line.
+- **Tags**: sections `Args:`, `Returns:`, `Raises:` and `Example:`. The fields of a class, dataclass, `TypedDict` or enum go under `Attributes:` in its docstring.
+
+```python
+def add(a: int, b: int) -> int:
+    """Adds two numbers."""
+    return a + b
+
+
+async def get_user(user_id: int) -> User | None:
+    """Retrieves a user by id.
+
+    Args:
+        user_id: Surrogate key from the `users` table, not the auth provider's id.
+
+    Returns:
+        Custom User class used by the authentication service, or `None` when no row matches.
+    """
+    ...
+
+
+class FileValidationError(Exception):
+    """Error for a file on disk that does not match its schema.
+
+    Holds the path of the file and one issue per rejected field, and its message
+    lists them all. Raised by `parse_file` and by the readers in `filetree/`,
+    `decisions/` and `vocabulary/` that check a file's layout by hand. Callers
+    tell it apart from other errors with `except FileValidationError`.
+
+    Attributes:
+        file: Absolute path of the file that failed, e.g. `/home/me/app/docs/auth.md`.
+        issues: Rejected fields, e.g. `FileValidationIssue(field="phases.0.status", message="is required")`.
+
+    Example:
+        raise FileValidationError("/home/me/app/docs/auth.md", [
+            FileValidationIssue(field="status", message='is "done"'),
+        ])
+    """
+
+    def __init__(self, file: str, issues: list[FileValidationIssue]) -> None:
+        """Builds the message from the file path and every issue."""
+        ...
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """Entries a set of requests resolved to, and the requests that did not resolve.
+
+    Attributes:
+        entries: Resolved entries by key, e.g. `emphasise`.
+        unknown: Requests no source offers, e.g. `ghost@mine`.
+        notes: Why an entry nobody named is in the set, e.g. `{"vocabulary": "dep of plan"}`.
+    """
+
+    entries: dict[str, SourceOffer]
+    unknown: list[str]
+    notes: dict[str, str]
+```
+
+`__init__` gets a summary only when the class docstring already tags its arguments as attributes.
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```python
+@dataclass
+class Resolution:
+    """Entries a set of requests resolved to."""
+
+    entries: dict[str, SourceOffer]
+    """Resolved entries by key."""
+```
+A docstring on a field. Fields go in the class docstring under `Attributes:`.
+
+```python
+def get_user(user_id: int) -> User | None:
+    # Looks the user up by surrogate key.
+    """Retrieves a user by id."""
+```
+A comment that says what a tag can say. It goes under `Args:`.
+
+```python
+def matches(request: EntryRequest, offers: Sequence[SourceOffer]) -> Match:
+    """
+    Finds the entries one request names.
+    """
+```
+The summary starts on line 2, and the custom types `EntryRequest`, `SourceOffer` and `Match` have no `Args:` or `Returns:` entry.