@ahood/cli 0.10.1 → 0.11.0

package/README.md

@@ -189,15 +189,16 @@ Shared alice/pdf-tools with design-team.
 Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private visibility, it just makes it visible to everyone in `design-team` too. On the other side, whoever received the link runs `ahood group join <the link>` to join.
 </details>
 
-## Kinds: skills, agents, and MCP servers
+## Kinds: skills, agents, MCP servers, and docs
 
-The registry holds three kinds of artifact this CLI works with, each with its own command group. All three take the same verbs (`search`, `list`, `view`/`show`, `read`, `versions`, `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`, `share`, `unshare`, `init`, `publish`), run by the same code:
+The registry holds four kinds of artifact, each with its own command group. All four take the same verbs (`search`, `list`, `view`/`show`, `read`, `versions`, `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`, `share`, `unshare`, `init`, `publish`), run by the same code:
 
 | Kind | Root file | `add` installs to | Group |
 | --- | --- | --- | --- |
 | skill | `SKILL.md` | `.claude/skills/<owner>@<skill>/` | `ahood skill <verb>` |
 | agent | `AGENT.md` | `.claude/agents/<owner>@<agent>.md` | `ahood agent <verb>` |
 | mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
+| doc | `DOC.md` | `.claude/docs/<owner>@<doc>.md` | `ahood doc <verb>` |
 
 ```
 $ ahood agent search review
@@ -205,14 +206,16 @@ $ ahood agent init code-reviewer        # ./code-reviewer/AGENT.md
 $ ahood agent publish alice/code-reviewer@1.0.0 --path code-reviewer --name "Code Reviewer"
 $ ahood mcp init github-server          # ./github-server/server.json, a safe placeholder starter
 $ ahood mcp add alice/github-server
+$ ahood doc read alice/setup-guide      # print a doc without installing it
+$ ahood doc add alice/setup-guide       # ./.claude/docs/alice@setup-guide.md, pinned
 $ ahood agent add alice/pdf-tools
 alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood skill add alice/pdf-tools` instead.
 ```
 
-- **`ahood agent` and `ahood mcp` are strict.** A target of another kind is refused -- exit code `2`, naming the kind it found -- before anything is downloaded, prompted for, written, or sent. That covers `add`, `update`, `remove`, `edit`, `unpublish`, `share`/`unshare`, `star`/`unstar`, and `publish` (an existing entry of another kind is refused before anything is packed or uploaded); the read-only verbs refuse too, rather than show the wrong kind. `search` asks the registry for that kind only, `list` keeps only that kind of your own entries, and `update`/`outdated` with no argument consider only installed pins of that kind. `agent publish`/`mcp publish` imply their kind and reject a contradictory `--kind`.
-- **Missing or unexpected kind metadata is refused, never guessed.** If the registry's answer carries no kind (or one this CLI doesn't handle), a kind-scoped command stops with exit `1` and points at the legacy form. `remove` reads the kind from the project's own files (the skill directory, the agent file, or the mcp fingerprint in the lockfile) and asks the registry only when those can't tell; if neither can, nothing is removed.
-- **`ahood skill` is legacy and cross-kind in this release.** `ahood skill search` and `ahood skill list` include every kind, and `ahood skill add`/`update`/`remove`/... act on whatever kind the target is, exactly as before -- including `--json` output and exit codes -- so existing scripts keep working. Add `--kind skill|agent|mcp` to any `ahood skill` verb (except `publish`, whose `--kind` keeps its original meaning) to scope it, or `--kind all` to spell out the cross-kind behavior.
-- **Not in scope: `doc`.** The registry also has a `doc` kind (documentation pages); this CLI has no `ahood doc` group. Kind dispatch is table-driven (`src/kind-info.ts`), so adding one is an entry there plus its help and `init` template.
+- **`ahood agent`, `ahood mcp` and `ahood doc` are strict.** A target of another kind is refused -- exit code `2`, naming the kind it found -- before anything is downloaded, prompted for, written, or sent. That covers `add`, `update`, `remove`, `edit`, `unpublish`, `share`/`unshare`, `star`/`unstar`, and `publish` (an existing entry of another kind is refused before anything is packed or uploaded); the read-only verbs refuse too, rather than show the wrong kind. `search` asks the registry for that kind only, `list` keeps only that kind of your own entries, and `update`/`outdated` with no argument consider only installed pins of that kind. `agent publish`/`mcp publish`/`doc publish` imply their kind and reject a contradictory `--kind`.
+- **Missing or unexpected kind metadata is refused, never guessed.** If the registry's answer carries no kind (or one this CLI doesn't handle), a kind-scoped command stops with exit `1` and points at the legacy form. `remove` reads the kind from the project's own files (the skill directory, the agent file, the mcp fingerprint in the lockfile, or a doc pin's recorded `kind`) and asks the registry only when those can't tell; if neither can, nothing is removed.
+- **`ahood skill` is legacy and cross-kind in this release.** `ahood skill search` and `ahood skill list` include every kind, and `ahood skill add`/`update`/`remove`/... act on whatever kind the target is, exactly as before -- including `--json` output and exit codes -- so existing scripts keep working. The one exception is a doc: `ahood skill add` refuses it and points at `ahood doc add`. Add `--kind skill|agent|mcp|doc` to any `ahood skill` verb (except `publish`, whose `--kind` keeps its original meaning) to scope it, or `--kind all` to spell out the cross-kind behavior.
+- **Docs install as one pinned file.** `ahood doc add` saves a doc's `DOC.md` to `.claude/docs/<owner>@<doc>.md` and pins it in `.claude/skills.lock.json` with `"kind": "doc"`. It refuses to overwrite a file at that path that isn't pinned as that doc. `ahood doc update`/`outdated`/`remove` manage those pins like any other kind. Kind dispatch is table-driven (`src/kind-info.ts`).
 
 **Migration plan for a strict `ahood skill`.** A future major version will make `ahood skill <verb>` skills-only by default, matching `agent` and `mcp`. Until then: (1) this release adds the strict groups and `--kind`, and labels `ahood skill` as legacy in `--help`; (2) a following minor release prints a stderr deprecation note when an `ahood skill` command actually touches a non-skill entry (stdout and `--json` unchanged); (3) the major release flips the default, keeping `ahood skill <verb> --kind all` as the explicit cross-kind escape hatch. Scripts that want today's behavior forever can pass `--kind all` now.
 
@@ -257,7 +260,7 @@ alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood s
 | `ahood skill share <owner>/<skill> --group <group>` | Share a skill you own with a group, without changing its public/private visibility. |
 | `ahood skill unshare <owner>/<skill> --group <group>` | Stop sharing a skill you own with a group. |
 | `ahood skill init [name]` | Scaffold a new skill folder with a minimal, valid SKILL.md. |
-| `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill\|agent\|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist. |
+| `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill\|agent\|mcp\|doc] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a skill, agent, mcp server manifest, or doc from a folder containing SKILL.md, AGENT.md, server.json, or DOC.md, creating the skill first if it doesn't already exist. |
 
 ### Agent
 
@@ -307,6 +310,29 @@ alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood s
 | `ahood mcp init [name]` | Scaffold a new MCP server manifest folder with a minimal, valid server.json. |
 | `ahood mcp publish <owner>/<server>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of an MCP server manifest from a folder containing server.json, creating it first if it doesn't exist yet. |
 
+### Doc
+
+| Command | What it does |
+| --- | --- |
+| `ahood doc search <query> [--json] [--limit <n>]` | Search published docs. |
+| `ahood doc view\|show <owner>/<doc> [--json] [--web]` | Show a single doc's details without installing it (alias: ahood doc show). |
+| `ahood doc read <owner>/<doc> [--json]` | Print a published doc's DOC.md, without installing it. |
+| `ahood doc versions <owner>/<doc> [--json]` | List a doc's published-version history. |
+| `ahood doc diff <owner>/<doc> <versionA> <versionB> [--json]` | Show what changed between two published versions of a doc. |
+| `ahood doc list [--json]` | List your own docs, public and private. |
+| `ahood doc add <owner>/<doc>[@version]` | Install a doc into .claude/docs/<owner>@<doc>.md, pinned in the lockfile. |
+| `ahood doc update [<owner>/<doc> ...] [--dry-run] [--json]` | Move doc pins forward to the latest version. |
+| `ahood doc outdated [<owner>/<doc> ...] [--json]` | Read-only staleness check for installed docs. |
+| `ahood doc remove <owner>/<doc> [--yes]` | Uninstall and unpin a doc (local only, prompts unless --yes is passed). |
+| `ahood doc edit <owner>/<doc> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a doc you own, changing only the flags you pass. |
+| `ahood doc unpublish <owner>/<doc>[@version] [--yes]` | Delete a doc from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood doc star <owner>/<doc>` | Star a doc. |
+| `ahood doc unstar <owner>/<doc>` | Remove your star from a doc. |
+| `ahood doc share <owner>/<doc> --group <group>` | Share a doc you own with a group, without changing its visibility. |
+| `ahood doc unshare <owner>/<doc> --group <group>` | Stop sharing a doc you own with a group. |
+| `ahood doc init [name]` | Scaffold a new doc folder with a minimal, valid DOC.md. |
+| `ahood doc publish <owner>/<doc>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a doc from a folder containing DOC.md, creating it first if it doesn't exist yet. |
+
 ### Group
 
 | Command | What it does |

package/dist/commands/add.js

@@ -4,12 +4,12 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 import * as tarStream from "tar-stream";
 import { gunzipSync } from "node:zlib";
 import { apiFetch, apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
-import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.js";
-import { readLockfile, withLock, writeJsonFileAtomic, writeLockfileEntryVerifyingChecksum, LockfileChecksumConflictError, } from "../lockfile.js";
+import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, docPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.js";
+import { readLockfile, withLock, writeFileAtomic, writeJsonFileAtomic, writeLockfileEntryVerifyingChecksum, LockfileChecksumConflictError, } from "../lockfile.js";
 import { promptSecret } from "../secret-prompt.js";
 import { sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
-import { assertKind } from "../kinds.js";
+import { assertKind, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill add <owner>/<skill>[@version]";
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB compressed
 const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024; // 200 MB decompressed
@@ -865,6 +865,33 @@ export async function downloadVerifiedArchive(owner, skill, meta) {
     }
     return buffer;
 }
+// `ahood doc add` (ahood-cli#182): only DOC.md is extracted, written
+// atomically to .claude/docs/<owner>@<doc>.md, and pinned with kind "doc" so
+// remove/update can tell the pin apart without asking the registry. If the
+// pin can't be written, the file goes back to what it was: the previous
+// version's content on an update, nothing on a fresh install.
+async function installDoc(owner, skill, meta, buffer) {
+    const key = `${owner}/${skill}`;
+    const content = await extractSingleFileContent(buffer, "DOC.md");
+    const destPath = docPath(owner, skill);
+    const previous = existsSync(destPath) ? readFileSync(destPath) : undefined;
+    writeFileAtomic(destPath, content);
+    try {
+        writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, {
+            version: meta.version,
+            checksum_sha256: meta.checksum_sha256,
+            kind: "doc",
+        });
+    }
+    catch (error) {
+        rollbackOrWarn(() => (previous === undefined ? rmSync(destPath, { force: true }) : writeFileAtomic(destPath, previous)), `WARNING: could not restore ${destPath} after ${key}'s install failed -- it may not match its ${LOCKFILE_PATH} pin. Run \`ahood doc remove ${key}\` to clean it up.`);
+        if (error instanceof LockfileChecksumConflictError) {
+            throw new Error(checksumConflictMessage(key, meta, error.existing));
+        }
+        throw error;
+    }
+    console.log(`Installed ${key}@${meta.version} to ${destPath}`);
+}
 export async function add(args, scope) {
     const spec = args[0];
     if (!spec)
@@ -876,16 +903,24 @@ export async function add(args, scope) {
     // refused here, before the download, the lockfile and every write below.
     // Both metadata routes report the entry's kind, so this costs no request.
     assertKind(scope, key, meta.kind, "add", "install");
-    // A doc has no local install target (ahood-cli#175): only skill, agent and
-    // mcp entries map to a place on disk. Legacy cross-kind `ahood skill add`
-    // used to fall through to the skill path and extract a doc into
+    // Legacy cross-kind `ahood skill add` of a doc stays refused (ahood-cli#175):
+    // it used to fall through to the skill path and extract a doc into
     // .claude/skills/<owner>@<slug>/ with no SKILL.md -- not a working skill,
-    // with nothing telling the user. Refused here, on every path, before the
-    // download, the lockfile and any write. Entries with NO kind keep the
-    // legacy skill behaviour.
-    if (meta.kind === "doc") {
-        throw new UsageError(`${key} is a doc (a documentation page), which has no local install target. ` +
-            `Read it with \`ahood skill read ${key}\`, or open it with \`ahood skill view ${key} --web\`.`);
+    // with nothing telling the user. Docs install only through the doc scope
+    // (`ahood doc add`, ahood-cli#182), which writes the one flat file below.
+    // Refused before the download, the lockfile and any write. Entries with NO
+    // kind keep the legacy skill behaviour.
+    const docInstall = meta.kind === "doc" && strictKind(scope) === "doc";
+    if (meta.kind === "doc" && !docInstall) {
+        throw new UsageError(`${key} is a doc (a documentation page), not a skill. ` +
+            `Install it with \`ahood doc add ${key}\`, or read it without installing with \`ahood doc read ${key}\`.`);
+    }
+    // No-overwrite: a file already at the doc's path that this project's
+    // lockfile does not pin as this doc was not written by ahood, so it is
+    // left alone. Checked before the download, like every refusal above.
+    if (docInstall && existsSync(docPath(owner, skill)) && readLockfile(LOCKFILE_PATH)[key]?.kind !== "doc") {
+        throw new Error(`${docPath(owner, skill)} already exists and is not pinned as ${key} in ${LOCKFILE_PATH} -- refusing to overwrite it. ` +
+            "Move or delete it first.");
     }
     // A lockfile entry records the checksum this exact version was installed
     // with; if a later fetch of the "same" version disagrees, either the
@@ -912,7 +947,7 @@ export async function add(args, scope) {
     // manifest can never actually land on disk there -- the warning would be
     // both mislabeled ("skill") and about a risk that can't materialize
     // (ahood-cli final review finding #5).
-    if (meta.kind !== "agent" && meta.kind !== "mcp" && meta.manifest.some((f) => f.path.startsWith("scripts/"))) {
+    if (meta.kind !== "agent" && meta.kind !== "mcp" && meta.kind !== "doc" && meta.manifest.some((f) => f.path.startsWith("scripts/"))) {
         console.warn("WARNING: this skill includes a scripts/ directory. Review its contents before use.");
     }
     const buffer = await downloadVerifiedArchive(owner, skill, meta);
@@ -945,6 +980,10 @@ export async function add(args, scope) {
         await installMcpEntry(owner, skill, meta, buffer);
         return;
     }
+    if (docInstall) {
+        await installDoc(owner, skill, meta, buffer);
+        return;
+    }
     // Flat, owner@skill-joined directory name so Claude Code's own one-level-deep
     // project-skill scan actually discovers it (see skillDir's comment in spec.ts).
     const destDir = skillDir(owner, skill);

package/dist/commands/completion.js

@@ -1,13 +1,14 @@
-import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, AGENT_COMMANDS_HELP, MCP_COMMANDS_HELP, GROUP_COMMANDS_HELP, SNAP_COMMANDS_HELP, COMMAND_ALIASES, } from "../help.js";
+import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, AGENT_COMMANDS_HELP, MCP_COMMANDS_HELP, DOC_COMMANDS_HELP, GROUP_COMMANDS_HELP, SNAP_COMMANDS_HELP, COMMAND_ALIASES, } from "../help.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood completion <bash|zsh|fish>";
 // Every entity noun with its own verb list, in the order completion offers
-// them. Registry nouns (skill, agent, mcp -- ahood-cli#172) come first; group
+// them. Registry nouns (skill, agent, mcp -- ahood-cli#172; doc -- #182) come first; group
 // and snap were already real nouns but had no completion at all before.
 const NOUNS = [
     ["skill", SKILL_COMMANDS_HELP],
     ["agent", AGENT_COMMANDS_HELP],
     ["mcp", MCP_COMMANDS_HELP],
+    ["doc", DOC_COMMANDS_HELP],
     ["group", GROUP_COMMANDS_HELP],
     ["snap", SNAP_COMMANDS_HELP],
 ];

package/dist/commands/diff.js

@@ -2,7 +2,7 @@ import { createPatch } from "diff";
 import { fetchVersionMeta, downloadVerifiedArchive, extractSingleFileContent } from "./add.js";
 import { parseOwnerSkill, SEMVER_RE } from "../spec.js";
 import { UsageError } from "../usage-error.js";
-import { assertKind } from "../kinds.js";
+import { assertKind, isCliKind, KINDS } from "../kinds.js";
 const USAGE = "Usage: ahood skill diff <owner>/<skill> <versionA> <versionB> [--json]";
 // Both versions must be explicit semver here, unlike `add`'s
 // parseOwnerSkillVersion which lets "latest" default the version -- a diff
@@ -20,12 +20,16 @@ function validateVersion(version, spec) {
 // SKILL.md's presence from the manifest we already fetched -- checked
 // up front so a missing file produces a clean message instead of
 // extractSingleFileContent's generic "not found in the downloaded archive".
-async function fetchSkillMdContent(owner, skill, meta) {
-    if (!meta.manifest.some((f) => f.path === "SKILL.md" || f.path === "./SKILL.md")) {
-        throw new Error(`${owner}/${skill}@${meta.version} has no SKILL.md in its manifest.`);
+//
+// The file is the entry's root document (ahood-cli#182): SKILL.md for a skill
+// or an entry with no kind (unchanged), AGENT.md, server.json or DOC.md for
+// the other kinds, which have no SKILL.md to diff.
+async function fetchSkillMdContent(owner, skill, meta, rootDoc) {
+    if (!meta.manifest.some((f) => f.path === rootDoc || f.path === `./${rootDoc}`)) {
+        throw new Error(`${owner}/${skill}@${meta.version} has no ${rootDoc} in its manifest.`);
     }
     const buffer = await downloadVerifiedArchive(owner, skill, meta);
-    const content = await extractSingleFileContent(buffer, "SKILL.md");
+    const content = await extractSingleFileContent(buffer, rootDoc);
     return content.toString("utf-8");
 }
 // Compares two versions' manifests by path. VersionMeta.manifest only
@@ -35,14 +39,14 @@ async function fetchSkillMdContent(owner, skill, meta) {
 // diffed above) -- there is no way to tell whether some other common path's
 // *content* differs without downloading and comparing it too, which is out
 // of scope for this command (see the resolution-plan comment on issue #88).
-function diffManifests(manifestA, manifestB, skillMdChanged) {
+function diffManifests(manifestA, manifestB, skillMdChanged, rootDoc) {
     const pathsA = new Set(manifestA.map((f) => f.path));
     const pathsB = new Set(manifestB.map((f) => f.path));
     const added = [...pathsB].filter((p) => !pathsA.has(p)).sort();
     const removed = [...pathsA].filter((p) => !pathsB.has(p)).sort();
     const changed = [];
-    if (skillMdChanged && pathsA.has("SKILL.md") && pathsB.has("SKILL.md")) {
-        changed.push("SKILL.md");
+    if (skillMdChanged && pathsA.has(rootDoc) && pathsB.has(rootDoc)) {
+        changed.push(rootDoc);
     }
     return { added, removed, changed };
 }
@@ -61,13 +65,16 @@ export async function diff(args, scope) {
     ]);
     // Both version responses carry the entry's kind; checked before either archive is downloaded.
     assertKind(scope, `${owner}/${skill}`, metaA.kind, "diff", "diff");
+    const rootDoc = isCliKind(metaA.kind) ? KINDS[metaA.kind].rootDoc : "SKILL.md";
     const [contentA, contentB] = await Promise.all([
-        fetchSkillMdContent(owner, skill, metaA),
-        fetchSkillMdContent(owner, skill, metaB),
+        fetchSkillMdContent(owner, skill, metaA, rootDoc),
+        fetchSkillMdContent(owner, skill, metaB, rootDoc),
     ]);
-    const skillmdDiff = createPatch("SKILL.md", contentA, contentB, versionA, versionB);
+    // The --json key stays `skillmd_diff` whatever the root document is, so
+    // the output shape never changes.
+    const skillmdDiff = createPatch(rootDoc, contentA, contentB, versionA, versionB);
     const skillMdChanged = contentA !== contentB;
-    const manifest = diffManifests(metaA.manifest, metaB.manifest, skillMdChanged);
+    const manifest = diffManifests(metaA.manifest, metaB.manifest, skillMdChanged, rootDoc);
     if (jsonOutput) {
         console.log(JSON.stringify({ skillmd_diff: skillMdChanged ? skillmdDiff : "", manifest }));
         return;
@@ -78,7 +85,7 @@ export async function diff(args, scope) {
         console.log(skillmdDiff);
     }
     else {
-        console.log("SKILL.md is unchanged between these versions.");
+        console.log(`${rootDoc} is unchanged between these versions.`);
     }
     const summaryParts = [];
     if (manifest.added.length > 0)

package/dist/commands/init.js

@@ -102,10 +102,30 @@ function buildServerJson(name) {
     return `${JSON.stringify(manifest, null, 2)}
 `;
 }
+// DOC.md, for `ahood doc init` (ahood-cli#182). The backend's publish
+// validator (lib/publish/parse-doc-frontmatter.ts in the ahood repo) is the
+// same hand-rolled flat `key: value` reader as AGENT.md's, minus the skills
+// list: the file must START with a `---` line, the closing `---` line must be
+// followed by a newline, and `name` and `description` must be non-empty. So
+// the same rules as buildAgentMd apply: nothing above the opening `---`, and
+// no colon in a comment line inside the frontmatter.
+function buildDocMd(name) {
+    return `---
+name: ${name}
+description: TODO -- one line saying what this doc covers and when an agent should read it.
+---
+
+# ${name}
+
+TODO -- write the documentation here. Plain Markdown; this whole file, frontmatter
+included, is what \`ahood doc read\` prints and \`ahood doc add\` saves.
+`;
+}
 const TEMPLATES = {
     skill: buildSkillMd,
     agent: buildAgentMd,
     mcp: buildServerJson,
+    doc: buildDocMd,
 };
 const NEXT_STEPS = {
     skill: ["Fill in the description, then flesh out the ## Instructions section."],
@@ -115,7 +135,9 @@ const NEXT_STEPS = {
         '"remotes" with one npm package: "packages": [{"registry_type": "npm", "runtime_hint": "npx",',
         '"identifier": "<npm-package>", "version": "<x.y.z>"}] (plus optional "environment_variables").',
     ],
+    doc: ["Fill in the description, then write the doc below the frontmatter."],
 };
+const PLACEHOLDERS = { skill: "<skill>", agent: "<agent>", mcp: "<server>", doc: "<doc>" };
 // Falls back to "my-skill" when the directory name itself isn't usable as a
 // bare YAML scalar (empty, or starting with a character like "-" or "@" that
 // would need quoting) -- e.g. running `ahood skill init` with no name directly in
@@ -180,6 +202,6 @@ export async function init(args, scope) {
     console.log(`Created ${docPath}`);
     for (const line of NEXT_STEPS[kind])
         console.log(line);
-    const placeholder = kind === "skill" ? "<skill>" : kind === "agent" ? "<agent>" : "<server>";
+    const placeholder = PLACEHOLDERS[kind];
     console.log(`Run \`ahood ${strict ?? "skill"} publish <owner>/${placeholder}@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
 }

package/dist/commands/publish.js

@@ -47,7 +47,7 @@ async function pollVersionStatus(owner, skill, version) {
     }
     throw new Error(`Still processing after ${POLL_TIMEOUT_MS / 1000}s -- check \`ahood skill view ${owner}/${skill}\` later for the result.`);
 }
-const USAGE = "Usage: ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]\n" +
+const USAGE = "Usage: ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp|doc] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]\n" +
     "   or: ahood skill publish <path> --owner <owner> --slug <skill> --version <x.y.z> [--json]";
 // Matched by ENTRY NAME at every depth, not by path prefix, so a nested
 // `vendor/thing/.git` is skipped the same as a top-level one. Not a
@@ -264,8 +264,8 @@ function parsePublishArgs(args) {
     if (!SEMVER_RE.test(version)) {
         throw new UsageError(`--version must be a semver like 1.2.3 (got "${version}").\n${USAGE}`);
     }
-    if (kind !== undefined && kind !== "skill" && kind !== "agent" && kind !== "mcp") {
-        throw new UsageError(`--kind must be "skill", "agent", or "mcp" (got "${kind}").\n${USAGE}`);
+    if (kind !== undefined && kind !== "skill" && kind !== "agent" && kind !== "mcp" && kind !== "doc") {
+        throw new UsageError(`--kind must be "skill", "agent", "mcp", or "doc" (got "${kind}").\n${USAGE}`);
     }
     // Validated here, before any network call (including the tar/gzip of the
     // skill directory) -- these only ever reach the server via
@@ -377,11 +377,17 @@ export async function publish(args, scope) {
         const skillMdPath = join(path, "SKILL.md");
         const agentMdPath = join(path, "AGENT.md");
         const serverJsonPath = join(path, "server.json");
+        const docMdPath = join(path, "DOC.md");
         const hasSkillMd = existsSync(skillMdPath);
         const hasAgentMd = existsSync(agentMdPath);
         const hasServerJson = existsSync(serverJsonPath);
+        const hasDocMd = existsSync(docMdPath);
         let resolvedKind = kind;
-        if (kind === "agent") {
+        if (kind === "doc") {
+            if (!hasDocMd)
+                throw new Error(`No DOC.md found at ${docMdPath} -- ${via} must point at a folder containing DOC.md.`);
+        }
+        else if (kind === "agent") {
             if (!hasAgentMd)
                 throw new Error(`No AGENT.md found at ${agentMdPath} -- ${via} must point at a folder containing AGENT.md.`);
         }
@@ -395,12 +401,17 @@ export async function publish(args, scope) {
         }
         else {
             // kind === undefined -- infer from whichever root file(s) are actually present
-            const present = [hasSkillMd && "SKILL.md", hasAgentMd && "AGENT.md", hasServerJson && "server.json"].filter(Boolean);
+            const present = [
+                hasSkillMd && "SKILL.md",
+                hasAgentMd && "AGENT.md",
+                hasServerJson && "server.json",
+                hasDocMd && "DOC.md",
+            ].filter(Boolean);
             if (present.length > 1) {
-                throw new Error(`Multiple root files found at ${path} (${present.join(", ")}) -- pass --kind skill, --kind agent, or --kind mcp to disambiguate.`);
+                throw new Error(`Multiple root files found at ${path} (${present.join(", ")}) -- pass --kind skill, --kind agent, --kind mcp, or --kind doc to disambiguate.`);
             }
             if (present.length === 0) {
-                throw new Error(`No SKILL.md, AGENT.md, or server.json found at ${path} -- publish must point at a skill, agent, or mcp folder's root.`);
+                throw new Error(`No SKILL.md, AGENT.md, server.json, or DOC.md found at ${path} -- publish must point at a skill, agent, mcp, or doc folder's root.`);
             }
             if (hasAgentMd) {
                 resolvedKind = "agent"; // inferred: only AGENT.md present, no --kind needed
@@ -408,6 +419,9 @@ export async function publish(args, scope) {
             else if (hasServerJson) {
                 resolvedKind = "mcp"; // inferred: only server.json present, no --kind needed
             }
+            else if (hasDocMd) {
+                resolvedKind = "doc"; // inferred: only DOC.md present (ahood-cli#182)
+            }
             // else: hasSkillMd only -- resolvedKind stays undefined (unchanged existing behavior, server defaults to 'skill')
         }
         // ahood-cli#93: fires for an explicit --kind skill, and for the

package/dist/commands/remove.js

@@ -1,7 +1,7 @@
 import { existsSync, rmSync } from "node:fs";
 import { confirm } from "../confirm.js";
 import { readLockfile, removeLockfileEntry, withLock, writeJsonFileAtomic } from "../lockfile.js";
-import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
+import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, docPath, MCP_CONFIG_PATH } from "../spec.js";
 import { readMcpConfig, matchesMcpConfigHash } from "./add.js";
 import { UsageError } from "../usage-error.js";
 import { assertKind, ensureRemoteKind, KindMismatchError, describeKind, localInstalledKind, strictKind, } from "../kinds.js";
@@ -46,6 +46,9 @@ export async function remove(args, scope) {
     // never a directory under .claude/skills/ -- distinct from the dir check above.
     const agentFile = agentPath(owner, skill);
     const agentExisted = existsSync(agentFile);
+    // A doc installs as one flat file under .claude/docs/ (ahood-cli#182).
+    const docFile = docPath(owner, skill);
+    const docExisted = existsSync(docFile);
     const lockEntry = readLockfile(LOCKFILE_PATH)[key];
     const hadLockfileEntry = lockEntry !== undefined;
     // A pin whose install left nothing on disk is the defining shape of an
@@ -55,8 +58,8 @@ export async function remove(args, scope) {
     // before that field did (lockfile.ts: "absent for any mcp entry installed
     // before this field existed") and it is computed HERE, above the .mcp.json
     // read -- so it survives the case where that read throws (ahood-cli#143).
-    const hadNoOnDiskFootprint = !dirExisted && !agentExisted && hadLockfileEntry;
-    if (!dirExisted && !agentExisted && !hadLockfileEntry) {
+    const hadNoOnDiskFootprint = !dirExisted && !agentExisted && !docExisted && lockEntry?.kind !== "doc" && hadLockfileEntry;
+    if (!dirExisted && !agentExisted && !docExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
         return;
@@ -93,6 +96,8 @@ export async function remove(args, scope) {
         rmSync(dir, { recursive: true, force: true });
     if (agentExisted)
         rmSync(agentFile, { force: true });
+    if (docExisted)
+        rmSync(docFile, { force: true });
     // An mcp-kind install has no directory or agent file on disk -- its only
     // footprint is the lockfile entry (cleared below, once this block has run)
     // and a live entry in .mcp.json (which add.ts's installMcpEntry merged in,

package/dist/commands/update.js

@@ -214,8 +214,13 @@ export async function update(args, scope) {
             }
             // no @version -- resolves to latest again. A strict scope is passed on so
             // add() re-checks the kind it resolves itself before writing anything.
+            // A doc pin under legacy `ahood skill update` is moved forward through
+            // the doc scope (ahood-cli#182): legacy add refuses docs, but legacy
+            // update has always covered every installed pin.
             if (kind)
                 await add([ownerSlashSkill], scope);
+            else if (meta.kind === "doc")
+                await add([ownerSlashSkill], { noun: "doc", kind: "doc" });
             else
                 await add([ownerSlashSkill]);
         }

package/dist/help.js

@@ -121,7 +121,8 @@ export const SKILL_COMMANDS_HELP = [
             "installs instead as a single file at .claude/agents/<owner>@<skill>.md (Claude Code's own subagent " +
             "loader scans .claude/agents/*.md as flat files), not a .claude/skills/ directory. An artifact published " +
             "with --kind mcp installs by merging an entry into .mcp.json instead, prompting for any secret " +
-            "environment variables its server.json declares that aren't already set in your shell.",
+            "environment variables its server.json declares that aren't already set in your shell. A doc is refused " +
+            "here; install it with `ahood doc add`.",
         examples: ["ahood skill add alice/pdf-tools", "ahood skill add alice/pdf-tools@1.2.0"],
     },
     {
@@ -206,17 +207,17 @@ export const SKILL_COMMANDS_HELP = [
         examples: ["ahood skill init pdf-tools", "ahood skill init"],
     },
     {
-        usage: "ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]",
-        summary: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist.",
-        desc: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json. If the artifact " +
-            "doesn't exist yet, this creates it first -- pass --name to set its display name, and --kind agent or --kind mcp if " +
-            "publishing an AGENT.md or server.json (auto-detected from the folder contents when only one of SKILL.md/AGENT.md/server.json is present). " +
+        usage: "ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp|doc] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]",
+        summary: "Publish a new version of a skill, agent, mcp server manifest, or doc from a folder containing SKILL.md, AGENT.md, server.json, or DOC.md, creating the skill first if it doesn't already exist.",
+        desc: "Publish a new version of a skill, agent, mcp server manifest, or doc from a folder containing SKILL.md, AGENT.md, server.json, or DOC.md. If the artifact " +
+            "doesn't exist yet, this creates it first -- pass --name to set its display name, and --kind agent, --kind mcp, or --kind doc if " +
+            "publishing an AGENT.md, server.json, or DOC.md (auto-detected from the folder contents when only one of SKILL.md/AGENT.md/server.json/DOC.md is present). " +
             "--name is required when creating; optionally also pass --tagline/--tags/--license/--homepage/--repository. " +
             "Processing happens server-side after upload; this command polls and reports the final published/failed status. " +
             "The legacy form `ahood skill publish <path> --owner <owner> --slug <skill> --version <x.y.z>` is still accepted. " +
             "Every flag also accepts the --flag=value form, needed when a value itself starts with --.",
         flags: [
-            "--kind skill|agent|mcp        What kind of artifact this is. Auto-detected from SKILL.md/AGENT.md/server.json when omitted.",
+            "--kind skill|agent|mcp|doc    What kind of artifact this is. Auto-detected from SKILL.md/AGENT.md/server.json/DOC.md when omitted.",
             "--name <text>                 Required only when creating the artifact on this publish.",
             "--tagline <text>              Short one-line description, used only when creating.",
             "--tags <comma,separated>      Initial tags, used only when creating.",
@@ -240,15 +241,21 @@ export const SKILL_COMMANDS_HELP = [
 // rather than hand-copied twice, so the two lists can't drift from each other.
 // SKILL_COMMANDS_HELP above stays hand-written: it documents the legacy,
 // cross-kind behavior `ahood skill` keeps in this release.
+const PLACEHOLDER = { agent: "<agent>", mcp: "<server>", doc: "<doc>" };
+const EXAMPLE = {
+    agent: { slug: "alice/code-reviewer", name: "Code Reviewer" },
+    mcp: { slug: "alice/github-server", name: "GitHub Server" },
+    doc: { slug: "alice/setup-guide", name: "Setup Guide" },
+};
 function registryCommandsHelp(kind) {
     const info = KINDS[kind];
-    const n = kind === "agent" ? "<agent>" : "<server>";
+    const n = PLACEHOLDER[kind];
     const p = `ahood ${kind}`;
     const label = info.label;
     const a = info.article;
     const plural = info.plural;
     const doc = info.rootDoc;
-    const ex = kind === "agent" ? "alice/code-reviewer" : "alice/github-server";
+    const ex = EXAMPLE[kind].slug;
     const kindRefusal = `Refused, before anything else happens, when the target is not ${a} ${label}.`;
     return [
         {
@@ -378,11 +385,12 @@ function registryCommandsHelp(kind) {
                 "--changelog <text>            What changed in this version.",
                 "--json                        Print one {version,status,...} JSON object on completion (or {error} on failure).",
             ],
-            examples: [`${p} publish ${ex}@1.0.0 --name "${kind === "agent" ? "Code Reviewer" : "GitHub Server"}"`],
+            examples: [`${p} publish ${ex}@1.0.0 --name "${EXAMPLE[kind].name}"`],
         },
     ];
 }
 export const AGENT_COMMANDS_HELP = registryCommandsHelp("agent");
+export const DOC_COMMANDS_HELP = registryCommandsHelp("doc");
 // `ahood mcp` is two things (ADR 0007 in the ahood repo separates the hosted
 // registry MCP endpoint from this CLI's local one): with no verb, or with
 // `serve`, it is the local, read-only stdio MCP server that MCP hosts spawn;
@@ -585,6 +593,7 @@ const ENTITY_COMMANDS_HELP = {
     skill: SKILL_COMMANDS_HELP,
     agent: AGENT_COMMANDS_HELP,
     mcp: MCP_COMMANDS_HELP,
+    doc: DOC_COMMANDS_HELP,
     group: GROUP_COMMANDS_HELP,
     snap: SNAP_COMMANDS_HELP,
 };
@@ -709,8 +718,8 @@ export function formatSkillHelp() {
         "Legacy, cross-kind: in this release `ahood skill <verb>` still acts on any registry kind",
         "(skills, agents, MCP server manifests) -- `skill list`/`skill search` include every kind, and",
         "`skill add`/`skill update` install whatever kind they resolve. Scripts relying on that keep",
-        "working. For one kind only, use `ahood agent <verb>` / `ahood mcp <verb>`, or add",
-        "`--kind skill|agent|mcp` to any verb below (`--kind all` spells out the legacy behavior).",
+        "working. For one kind only, use `ahood agent|mcp|doc <verb>`, or add",
+        "`--kind skill|agent|mcp|doc` to any verb below (`--kind all` spells out the legacy behavior).",
         "A future major version will make `ahood skill` skills-only.",
         "",
         "Commands:",
@@ -751,11 +760,20 @@ export function formatMcpHelp() {
 }
 // One entry point for every registry noun's group help, so dispatch and
 // `ahood help <noun>` can't disagree about which listing a noun gets.
+export function formatDocHelp() {
+    return formatRegistryKindHelp("ahood doc -- docs (DOC.md) in the ahood registry", [
+        "Every verb here acts on docs only: a target of another kind is refused before anything",
+        "is downloaded, prompted for, written, or sent. Installs land in .claude/docs/<owner>@<doc>.md.",
+        "To look at a doc without installing it, use `ahood doc read`.",
+    ], DOC_COMMANDS_HELP, "doc");
+}
 export function formatKindHelp(noun) {
     if (noun === "agent")
         return formatAgentHelp();
     if (noun === "mcp")
         return formatMcpHelp();
+    if (noun === "doc")
+        return formatDocHelp();
     return formatSkillHelp();
 }
 // `ahood group --help` -- the group-level listing for every group verb.
@@ -793,6 +811,8 @@ export function formatHelp() {
     const agentGroupSummary = "The same verbs, for agent definitions only -- run `ahood agent --help` for the full list.";
     const mcpGroupUsage = "ahood mcp <command>";
     const mcpGroupSummary = "The same verbs, for MCP server manifests only; bare `ahood mcp` or `ahood mcp serve` starts the local MCP server.";
+    const docGroupUsage = "ahood doc <command>";
+    const docGroupSummary = "The same verbs, for docs (DOC.md) only -- run `ahood doc --help` for the full list.";
     const groupGroupUsage = "ahood group <command>";
     const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
     const snapGroupUsage = "ahood snap <command>";
@@ -802,6 +822,7 @@ export function formatHelp() {
         { usage: skillGroupUsage, summary: skillGroupSummary },
         { usage: agentGroupUsage, summary: agentGroupSummary },
         { usage: mcpGroupUsage, summary: mcpGroupSummary },
+        { usage: docGroupUsage, summary: docGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
         { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
@@ -823,7 +844,7 @@ export function formatHelp() {
         "",
         "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
         "Run `ahood skill --help` for the full list of skill commands.",
-        "Run `ahood agent --help` / `ahood mcp --help` for the kind-scoped agent and MCP commands.",
+        "Run `ahood agent --help` / `ahood mcp --help` / `ahood doc --help` for the kind-scoped agent, MCP and doc commands.",
         "Run `ahood group --help` for the full list of group commands.",
         "Run `ahood snap --help` for the full list of snap commands.",
         "Run `ahood --version` to print the installed CLI version.",

package/dist/index.js

@@ -96,6 +96,7 @@ const COMMANDS = {
     mcp: dispatchMcp,
     skill: dispatchSkill,
     agent: dispatchAgent,
+    doc: dispatchDoc,
     group: dispatchGroup,
     snap: dispatchSnap,
 };
@@ -107,8 +108,9 @@ const COMMANDS = {
 // here just means "a command that owns its own sub-verb dispatch", the same
 // sense "skill" already used before "group" (the entity) existed. "snap"
 // joins this set for the exact same reason (ahood-cli#107).
-// "agent" and "mcp" join it as registry nouns (ahood-cli#172).
-const GROUP_COMMANDS = new Set(["skill", "agent", "mcp", "group", "snap"]);
+// "agent" and "mcp" join it as registry nouns (ahood-cli#172), "doc" too
+// (ahood-cli#182).
+const GROUP_COMMANDS = new Set(["skill", "agent", "mcp", "doc", "group", "snap"]);
 function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
     for (let i = 0; i <= a.length; i++)
@@ -146,7 +148,7 @@ function closestGroupVerb(input) {
 function closestSnapVerb(input) {
     return closestOf(input, Object.keys(SNAP_VERBS));
 }
-// `ahood <noun> <verb> [...]` for every registry noun (skill, agent, mcp) --
+// `ahood <noun> <verb> [...]` for every registry noun (skill, agent, mcp, doc) --
 // owns its own help handling at both the noun level (`ahood agent` /
 // `ahood agent --help`) and the per-verb level (`ahood agent <verb> --help`),
 // since neither should fall through to main()'s generic top-level --help
@@ -210,6 +212,9 @@ async function dispatchSkill(args) {
 async function dispatchAgent(args) {
     await dispatchRegistry("agent", args);
 }
+async function dispatchDoc(args) {
+    await dispatchRegistry("doc", args);
+}
 // `ahood mcp` keeps its original contract byte-for-byte: with NO arguments it
 // is the local stdio MCP server that existing host configs launch -- nothing
 // is printed and nothing else runs first. `ahood mcp serve` is the same
@@ -312,7 +317,7 @@ async function main() {
             process.stdout.write(content);
             return;
         }
-        if (sub === "skill" || sub === "agent" || sub === "mcp") {
+        if (sub === "skill" || sub === "agent" || sub === "mcp" || sub === "doc") {
             const verb = args[1];
             const entry = verb ? findCommandHelp(sub, verb) : undefined;
             console.log(entry ? formatCommandHelp(entry) : formatKindHelp(sub));
@@ -394,4 +399,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchAgent, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };
+export { main, dispatchSkill, dispatchAgent, dispatchDoc, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/kind-info.js

@@ -7,10 +7,10 @@
 // The registry stores four artifact kinds (the backend's
 // lib/skills/validation.ts ALLOWED_KINDS: skill, agent, mcp, doc), and a
 // kind is fixed when an entry is created -- PATCH's allow-list has no `kind`
-// -- so the kind an entry reports now is the kind it has always had. This
-// CLI has a noun group for three of them. `doc` is a real registry kind left
-// out of this CLI's scope on purpose; adding it means one entry in KINDS
-// below plus its help/init template, not a new dispatcher.
+// -- so the kind an entry reports now is the kind it has always had. Each
+// kind has a noun group (`ahood skill|agent|mcp|doc <verb>`), all run by one
+// shared dispatcher. `doc` joined as the fourth in ahood-cli#182: it installs
+// as one flat Markdown file, its DOC.md, the same shape an agent has.
 export const KINDS = {
     skill: {
         label: "skill",
@@ -33,6 +33,13 @@ export const KINDS = {
         rootDoc: "server.json",
         installsTo: "an entry in .mcp.json",
     },
+    doc: {
+        label: "doc",
+        article: "a",
+        plural: "docs",
+        rootDoc: "DOC.md",
+        installsTo: ".claude/docs/<owner>@<doc>.md",
+    },
 };
 export const CLI_KINDS = Object.keys(KINDS);
 export function isCliKind(value) {

package/dist/kinds.js

@@ -62,6 +62,9 @@ export async function ensureRemoteKind(scope, owner, skill, verb, action) {
 // skill whose directory was deleted by hand) is undefined: unknown, and the
 // caller must ask the registry rather than guess.
 export function localInstalledKind(owner, skill, entry) {
+    // A doc pin records its kind (ahood-cli#182), the one kind that does.
+    if (entry?.kind === "doc")
+        return "doc";
     const hasDir = existsSync(skillDir(owner, skill));
     const hasAgentFile = existsSync(agentPath(owner, skill));
     if (hasDir && !hasAgentFile)
@@ -102,8 +105,8 @@ export function extractKindFlag(args) {
 // Resolves the scope for `ahood <noun> <verb> [--kind <k>]`.
 //   skill noun, no --kind or --kind all  -> legacy (cross-kind)
 //   skill noun, --kind <k>               -> strict <k>
-//   agent/mcp noun, no --kind or --kind <same> -> strict <noun>
-//   agent/mcp noun, any other --kind     -> usage error (contradiction)
+//   agent/mcp/doc noun, no --kind or --kind <same> -> strict <noun>
+//   agent/mcp/doc noun, any other --kind     -> usage error (contradiction)
 export function resolveScope(noun, kindFlag) {
     const valid = [...CLI_KINDS, "all"].join(", ");
     if (kindFlag !== undefined && kindFlag !== "all" && !isCliKind(kindFlag)) {

package/dist/lockfile.js

@@ -146,6 +146,12 @@ function resolveWriteTarget(path) {
 // file it is creating must get what it asked for regardless of the ambient
 // umask.
 export function writeJsonFileAtomic(path, data, mode) {
+    writeFileAtomic(path, JSON.stringify(data, null, 2) + "\n", mode);
+}
+// The same write-then-rename for raw content. A doc install (ahood-cli#182)
+// writes its DOC.md through this, so an interrupted install never leaves a
+// truncated doc behind.
+export function writeFileAtomic(path, content, mode) {
     // Resolved before the mkdir so the directory that actually gets created is
     // the resolved target's, not the link's -- a link set up ahead of the first
     // install can point somewhere that doesn't exist yet -- and so that every
@@ -189,7 +195,7 @@ export function writeJsonFileAtomic(path, data, mode) {
         // 0600 from the moment of creation: for .mcp.json this temp file holds
         // resolved MCP server secrets, and it must never be world-readable, not
         // even for the instant before the rename (ahood-cli#119).
-        writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+        writeFileSync(tmpPath, content, { mode: 0o600 });
         renameSync(tmpPath, dest);
         try {
             chmodSync(dest, finalMode);

package/dist/spec.js

@@ -116,3 +116,16 @@ export function agentPath(owner, skill) {
 // file isn't under .claude/ at all, since it's a convention MCP clients
 // broadly share, not one specific to this CLI).
 export const MCP_CONFIG_PATH = ".mcp.json";
+// A doc installs as one flat file, .claude/docs/<owner>@<doc>.md
+// (ahood-cli#182), the same "@"-joined shape as agentPath above. Unlike
+// agentPath, both segments are validated again here: callers have already
+// parsed them through parseOwnerSkill, but this is the path a doc install
+// writes to, so the SEGMENT_RE containment is enforced where the path is
+// built too. `alice/..` can never resolve outside .claude/docs/.
+export const DOCS_ROOT = join(".claude", "docs");
+export function docPath(owner, doc) {
+    const spec = `${owner}/${doc}`;
+    validateSegment(owner, "owner", spec);
+    validateSegment(doc, "skill", spec);
+    return join(DOCS_ROOT, `${owner}@${doc}.md`);
+}

package/dist/useme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ahood
-description: How to use the ahood CLI (@ahood/cli), the registry for reusable AI-agent skills, subagent definitions (AGENT.md), and MCP server manifests (server.json). Load BEFORE running any ahood command; before writing a non-trivial reusable skill, subagent, or MCP integration from scratch (search the registry first); when installing, updating, removing, publishing, sharing, or unpublishing one; when wiring ahood into an MCP host; or when setting up headless/CI access with AHOOD_TOKEN. Triggers - ahood, skill registry, is there a skill for this, install a skill, install an agent, add an MCP server, publish a skill, ahood mcp, AHOOD_TOKEN.
+description: How to use the ahood CLI (@ahood/cli), the registry for reusable AI-agent skills, subagent definitions (AGENT.md), MCP server manifests (server.json), and docs (DOC.md). Load BEFORE running any ahood command; before writing a non-trivial reusable skill, subagent, or MCP integration from scratch (search the registry first); when installing, updating, removing, publishing, sharing, or unpublishing one; when wiring ahood into an MCP host; or when setting up headless/CI access with AHOOD_TOKEN. Triggers - ahood, skill registry, is there a skill for this, install a skill, install an agent, add an MCP server, read a doc, publish a skill, ahood mcp, ahood doc, AHOOD_TOKEN.
 ---
 
 # ahood
@@ -13,28 +13,31 @@ and only moves when someone runs an update.
 This guide ships inside the CLI itself (`ahood help useme`), so it matches the installed
 version (`ahood --version`). It needs no login or network to print.
 
-## Three kinds, three command groups
+## Four kinds, four command groups
 
 | Kind | Root file | Installs to | Commands |
 |---|---|---|---|
 | skill | `SKILL.md` | `.claude/skills/<owner>@<skill>/` | `ahood skill <verb>` |
 | agent | `AGENT.md` | `.claude/agents/<owner>@<agent>.md` | `ahood agent <verb>` |
 | mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
+| doc | `DOC.md` | `.claude/docs/<owner>@<doc>.md` | `ahood doc <verb>` |
 
-All three groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
+All four groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
 `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`,
 `share`, `unshare`, `init`, `publish`.
 
-- `ahood agent <verb>` and `ahood mcp <verb>` act on their own kind only. A target of another
-  kind is refused (exit 2) before anything is downloaded, prompted for, written, or sent,
-  and the error names the kind it found and the right command.
+- `ahood agent <verb>`, `ahood mcp <verb>` and `ahood doc <verb>` act on their own kind only.
+  A target of another kind is refused (exit 2) before anything is downloaded, prompted for,
+  written, or sent, and the error names the kind it found and the right command.
 - `ahood skill <verb>` is the **legacy, cross-kind** group in this CLI release: `skill search`
   and `skill list` include every kind, and `skill add`/`skill update` install whatever kind
-  they resolve. Add `--kind skill` (or `agent`, `mcp`) to any verb to scope it to one kind;
+  they resolve, except a doc: `skill add` refuses one and points at `ahood doc add`.
+  Add `--kind skill` (or `agent`, `mcp`, `doc`) to any verb to scope it to one kind;
   `--kind all` spells out the legacy behavior. Prefer the kind-specific form in anything new --
   a future major version makes `ahood skill` skills-only.
-- The registry also has a `doc` kind (documentation pages). This CLI has no `doc` group;
-  browse those on the website.
+- A doc is a documentation page. `ahood doc read alice/setup-guide` prints it without
+  installing anything; `ahood doc add alice/setup-guide` saves it as one pinned file under
+  `.claude/docs/`, which `ahood doc update` and `ahood doc remove` manage like any other pin.
 
 ## Find, inspect, then install
 
@@ -84,7 +87,7 @@ ahood skill update --dry-run --json    # preview, machine-readable
 ahood agent remove alice/code-reviewer # local uninstall; prompts unless --yes
 ```
 
-With no target, `agent`/`mcp` `update` and `outdated` consider only installed pins of that
+With no target, `agent`/`mcp`/`doc` `update` and `outdated` consider only installed pins of that
 kind; the legacy `skill update` covers every pin. Updates only affect the current project.
 An `.mcp.json` entry you edited by hand is refused rather than overwritten.
 
@@ -96,13 +99,14 @@ Scaffold a valid starter, edit it, then publish an immutable semver version:
 ahood skill init pdf-tools             # ./pdf-tools/SKILL.md
 ahood agent init code-reviewer         # ./code-reviewer/AGENT.md
 ahood mcp init github-server           # ./github-server/server.json (placeholder URL)
+ahood doc init setup-guide             # ./setup-guide/DOC.md
 
 ahood agent publish alice/code-reviewer@1.0.0 --path code-reviewer --name "Code Reviewer"
 ahood skill publish alice/pdf-tools@1.1.0 --path pdf-tools --changelog "Adds split"
 ```
 
 - `--name` is required only on the first publish, which creates the entry under your
-  account. `agent publish`/`mcp publish` imply the kind and refuse a contradictory `--kind`
+  account. `agent publish`/`mcp publish`/`doc publish` imply the kind and refuse a contradictory `--kind`
   or an existing entry of another kind before uploading anything.
 - **New entries are private.** Make one discoverable explicitly:
   `ahood skill edit alice/pdf-tools --visibility public`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",