@ahood/cli 0.10.1 → 0.12.0

package/README.md

@@ -189,15 +189,17 @@ 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, docs, and project guides
 
-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 five kinds of artifact, each with its own command group. All five 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>` |
+| project | `PROJECT.md` | `.claude/project.md` (one per repository) | `ahood project <verb>` |
 
 ```
 $ ahood agent search review
@@ -205,14 +207,20 @@ $ 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 project                         # project guides for this repo's git remote
+$ ahood project add alice/acme-api      # ./.claude/project.md, pinned
+$ ahood project init acme-api           # ./acme-api/PROJECT.md, `project:` filled from git origin
 $ 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`, `ahood doc` and `ahood project` 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`/`project 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 or project 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 exceptions are a doc and a project guide: `ahood skill add` refuses them and points at `ahood doc add` / `ahood project add`. Add `--kind skill|agent|mcp|doc|project` 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`).
+- **A project guide is one pinned file per repository.** `ahood project add` saves the guide's `PROJECT.md` to `.claude/project.md` and pins it with `"kind": "project"`. It never touches `CLAUDE.md` or `AGENTS.md` (point those at `.claude/project.md` yourself), refuses to overwrite an unpinned `.claude/project.md`, and refuses a second guide while another is pinned (`ahood project remove` it first). `ahood project init` fills the optional `project` frontmatter field from `git remote get-url origin`, normalized to `host/owner/repo` exactly as the registry does (credentials stripped; `--project <remote>` or `--no-project` to override). Bare `ahood project` lists the guides you can see for this repository's remote, through the hosted `get_project_guide` MCP tool.
 
 **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 +265,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\|project] [--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, doc, or project guide from a folder containing SKILL.md, AGENT.md, server.json, DOC.md, or PROJECT.md, creating the skill first if it doesn't already exist. |
 
 ### Agent
 
@@ -307,6 +315,53 @@ 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. |
+
+### Project
+
+| Command | What it does |
+| --- | --- |
+| `ahood project [--remote <git-remote>] [--json]` | List the project guides you can see for this repository's git remote. |
+| `ahood project search <query> [--json] [--limit <n>]` | Search published project guides. |
+| `ahood project view\|show <owner>/<slug> [--json] [--web]` | Show a single project guide's details without installing it (alias: ahood project show). |
+| `ahood project read <owner>/<slug> [--json]` | Print a published project guide's PROJECT.md, without installing it. |
+| `ahood project versions <owner>/<slug> [--json]` | List a project guide's published-version history. |
+| `ahood project diff <owner>/<slug> <versionA> <versionB> [--json]` | Show what changed between two published versions of a project guide. |
+| `ahood project list [--json]` | List your own project guides, public and private. |
+| `ahood project add <owner>/<slug>[@version]` | Install a project guide into .claude/project.md, pinned in the lockfile. |
+| `ahood project update [<owner>/<slug> ...] [--dry-run] [--json]` | Move project guide pins forward to the latest version. |
+| `ahood project outdated [<owner>/<slug> ...] [--json]` | Read-only staleness check for installed project guides. |
+| `ahood project remove <owner>/<slug> [--yes]` | Uninstall and unpin a project guide (local only, prompts unless --yes is passed). |
+| `ahood project edit <owner>/<slug> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a project guide you own, changing only the flags you pass. |
+| `ahood project unpublish <owner>/<slug>[@version] [--yes]` | Delete a project guide from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood project star <owner>/<slug>` | Star a project guide. |
+| `ahood project unstar <owner>/<slug>` | Remove your star from a project guide. |
+| `ahood project share <owner>/<slug> --group <group>` | Share a project guide you own with a group, without changing its visibility. |
+| `ahood project unshare <owner>/<slug> --group <group>` | Stop sharing a project guide you own with a group. |
+| `ahood project init [name] [--project <git-remote> \| --no-project]` | Scaffold a new project guide folder with a minimal, valid PROJECT.md. |
+| `ahood project publish <owner>/<slug>@<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 project guide from a folder containing PROJECT.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, pinnedFilePath, 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, describeKind, isPinnedFileKind, KINDS, 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,55 @@ export async function downloadVerifiedArchive(owner, skill, meta) {
     }
     return buffer;
 }
+// `ahood doc add` (ahood-cli#182) and `ahood project add` (#185): only the
+// root doc (DOC.md / PROJECT.md) is extracted, written atomically to the
+// kind's pinned file (spec.ts pinnedFilePath), and pinned with its kind 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 installPinnedFile(kind, owner, skill, meta, buffer) {
+    const key = `${owner}/${skill}`;
+    const content = await extractSingleFileContent(buffer, KINDS[kind].rootDoc);
+    const destPath = pinnedFilePath(kind, 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,
+        });
+    }
+    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 ${kind} 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}`);
+}
+// Refuses a pinned-file install before the download when its path is not
+// this key's to write: a file no pin claims was not written by ahood, and a
+// path another pin claims (a second project guide) belongs to that pin.
+function assertPinnedFileIsOurs(kind, owner, skill) {
+    const key = `${owner}/${skill}`;
+    const destPath = pinnedFilePath(kind, owner, skill);
+    const holder = Object.entries(readLockfile(LOCKFILE_PATH)).find(([pinKey, pin]) => {
+        if (!isPinnedFileKind(pin.kind))
+            return false;
+        const [pinOwner, pinSlug] = pinKey.split("/");
+        return pinnedFilePath(pin.kind, pinOwner, pinSlug) === destPath;
+    })?.[0];
+    if (holder !== undefined && holder !== key) {
+        throw new Error(`${holder} is already installed at ${destPath} -- refusing to replace it with ${key}. ` +
+            `Run \`ahood ${kind} remove ${holder}\` first.`);
+    }
+    if (holder === undefined && existsSync(destPath)) {
+        throw new Error(`${destPath} already exists and is not pinned as ${key} in ${LOCKFILE_PATH} -- refusing to overwrite it. ` +
+            "Move or delete it first.");
+    }
+}
 export async function add(args, scope) {
     const spec = args[0];
     if (!spec)
@@ -876,17 +925,20 @@ 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
-    // .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\`.`);
+    // Legacy cross-kind `ahood skill add` of a doc or project guide stays
+    // refused (ahood-cli#175, #185): it used to fall through to the skill path
+    // and extract it into .claude/skills/<owner>@<slug>/ with no SKILL.md --
+    // not a working skill, with nothing telling the user. These kinds install
+    // only through their own scope (`ahood doc add`, `ahood project add`),
+    // which writes the one pinned file below. Refused before the download, the
+    // lockfile and any write. Entries with NO kind keep the legacy behaviour.
+    const pinnedKind = isPinnedFileKind(meta.kind) ? meta.kind : undefined;
+    if (pinnedKind !== undefined && strictKind(scope) !== pinnedKind) {
+        throw new UsageError(`${key} is ${describeKind(pinnedKind)} (${KINDS[pinnedKind].about}), not a skill. ` +
+            `Install it with \`ahood ${pinnedKind} add ${key}\`, or read it without installing with \`ahood ${pinnedKind} read ${key}\`.`);
     }
+    if (pinnedKind !== undefined)
+        assertPinnedFileIsOurs(pinnedKind, owner, skill);
     // A lockfile entry records the checksum this exact version was installed
     // with; if a later fetch of the "same" version disagrees, either the
     // published artifact changed after being pinned or the registry response
@@ -912,7 +964,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" && pinnedKind === undefined && 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 +997,10 @@ export async function add(args, scope) {
         await installMcpEntry(owner, skill, meta, buffer);
         return;
     }
+    if (pinnedKind !== undefined) {
+        await installPinnedFile(pinnedKind, 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,15 @@
-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, PROJECT_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; project -- #185) 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],
+    ["project", PROJECT_COMMANDS_HELP],
     ["group", GROUP_COMMANDS_HELP],
     ["snap", SNAP_COMMANDS_HELP],
 ];
@@ -21,10 +23,10 @@ function topLevelNames() {
 }
 // Position 2+, once a noun has been typed: that noun's verbs, plus alias
 // names (e.g. "show" for "view") wherever the aliased verb exists, so
-// completion offers every name a user might type. A bare `ahood mcp` entry
-// has no verb word and contributes nothing.
+// completion offers every name a user might type. A bare `ahood mcp` or
+// `ahood project [--remote ...]` entry has no verb word and contributes nothing.
 function verbNames(entries) {
-    const primary = entries.map((c) => c.usage.split(" ")[2] ?? "");
+    const primary = entries.map((c) => c.usage.split(" ")[2] ?? "").filter((word) => /^[a-z]/.test(word));
     const aliases = Object.keys(COMMAND_ALIASES).filter((alias) => primary.includes(COMMAND_ALIASES[alias]));
     return unique([...primary, ...aliases]);
 }

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

@@ -2,6 +2,8 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, join, resolve, sep } from "node:path";
 import { UsageError } from "../usage-error.js";
 import { CLI_KINDS, KINDS, strictKind } from "../kinds.js";
+import { flagValue } from "../flags.js";
+import { detectProjectRemote, normalizeProjectRemote } from "../project-remote.js";
 const USAGE = "Usage: ahood skill init [name]";
 // Mirrors the server's slug convention referenced by ahood-cli#60 (and the
 // same shape as spec.ts's SEGMENT_RE, minus "." and "_" -- skill slugs are
@@ -102,10 +104,47 @@ 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.
+`;
+}
+// PROJECT.md, for `ahood project init` (ahood-cli#185). The backend's
+// validator (lib/publish/parse-project-frontmatter.ts) is DOC.md's flat
+// reader plus one optional field, `project`: a git remote, normalized there
+// to host/owner/repo. It is written already normalized, or left out.
+function buildProjectMd(name, project) {
+    return `---
+name: ${name}
+description: TODO -- one line saying which repository this guide is for and when an agent should read it.
+${project ? `project: ${project}\n` : ""}---
+
+# ${name}
+
+TODO -- how to work in this repository: conventions, how to verify a change, and the
+traps. Plain Markdown; \`ahood project add\` saves this whole file to .claude/project.md.
+`;
+}
 const TEMPLATES = {
     skill: buildSkillMd,
     agent: buildAgentMd,
     mcp: buildServerJson,
+    doc: buildDocMd,
+    project: buildProjectMd,
 };
 const NEXT_STEPS = {
     skill: ["Fill in the description, then flesh out the ## Instructions section."],
@@ -115,7 +154,34 @@ 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."],
+    project: ["Fill in the description, then write the guide below the frontmatter."],
 };
+function parseProjectFlags(args) {
+    const raw = flagValue(args, "--project");
+    const skip = args.includes("--no-project");
+    if (skip && raw !== undefined)
+        throw new UsageError("Pass --project <remote> or --no-project, not both.");
+    const rest = args.filter((a, i) => a !== "--no-project" && a !== "--project" && !a.startsWith("--project=") && args[i - 1] !== "--project");
+    if (raw === undefined)
+        return { rest, skip };
+    const normalized = normalizeProjectRemote(raw);
+    if (!normalized.ok)
+        throw new UsageError(`--project is ${normalized.reason}.`);
+    return { rest, explicit: normalized.value, skip };
+}
+// The field's value: the flags' choice, else this repository's origin. Only
+// the normalized remote is ever printed or written.
+function resolveProjectField(flags) {
+    if (flags.skip)
+        return undefined;
+    if (flags.explicit !== undefined)
+        return flags.explicit;
+    const detected = detectProjectRemote();
+    if (detected)
+        console.log(`Filled project: ${detected} (from \`git remote get-url origin\`; pass --no-project to leave it out).`);
+    return detected;
+}
 // 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
@@ -127,6 +193,9 @@ function skillNameFor(dirPath, fallback = "my-skill") {
 export async function init(args, scope) {
     const strict = strictKind(scope);
     const kind = strict ?? "skill";
+    const projectFlags = kind === "project" ? parseProjectFlags(args) : undefined;
+    if (projectFlags)
+        args = projectFlags.rest;
     let name = args[0];
     if (name !== undefined && name.startsWith("-"))
         throw new UsageError(USAGE);
@@ -175,11 +244,12 @@ export async function init(args, scope) {
             }
         }
     }
+    const project = projectFlags ? resolveProjectField(projectFlags) : undefined;
     mkdirSync(targetDir, { recursive: true });
-    writeFileSync(docPath, TEMPLATES[kind](name ?? skillNameFor(targetDir, `my-${kind}`)));
+    writeFileSync(docPath, TEMPLATES[kind](name ?? skillNameFor(targetDir, `my-${kind}`), project));
     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 = KINDS[kind].placeholder;
     console.log(`Run \`ahood ${strict ?? "skill"} publish <owner>/${placeholder}@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
 }

package/dist/commands/project-guides.js

@@ -0,0 +1,47 @@
+// Bare `ahood project` (ahood-cli#185): the project guides that name this
+// repository's git remote, via the hosted get_project_guide tool. Read-only:
+// nothing is installed or written. The remote is normalized before it is
+// sent or printed, so a token in origin's URL never leaves this machine.
+import { flagValue } from "../flags.js";
+import { callHostedTool } from "../hosted-mcp.js";
+import { detectProjectRemote, normalizeProjectRemote } from "../project-remote.js";
+import { sanitizeForTerminal } from "../terminal-safe.js";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood project [--remote <git-remote>] [--json]";
+function resolveRemote(args) {
+    const explicit = flagValue(args, "--remote");
+    if (explicit !== undefined) {
+        const normalized = normalizeProjectRemote(explicit);
+        if (!normalized.ok)
+            throw new UsageError(`--remote is ${normalized.reason}.\n${USAGE}`);
+        return normalized.value;
+    }
+    const detected = detectProjectRemote();
+    if (!detected) {
+        throw new UsageError(`No git remote found: this is not a git repository with an "origin" remote ahood can read. Pass --remote <git-remote>.\n${USAGE}`);
+    }
+    return detected;
+}
+export async function findProjectGuides(args) {
+    const unknown = args.filter((a, i) => a.startsWith("-") && a !== "--json" && a !== "--remote" && !a.startsWith("--remote=") && args[i - 1] !== "--remote");
+    if (unknown.length > 0)
+        throw new UsageError(`Unknown flag ${unknown[0]}.\n${USAGE}`);
+    const remote = resolveRemote(args);
+    const result = await callHostedTool("get_project_guide", { remote });
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    if (result.guides.length === 0) {
+        console.log(`No project guides found for ${remote}. Write one with \`ahood project init\`.`);
+        return;
+    }
+    console.log(`Project guides for ${remote}:`);
+    for (const g of result.guides) {
+        const tagline = g.tagline ? ` -- ${sanitizeForTerminal(g.tagline)}` : "";
+        const mine = g.mine ? " (yours)" : "";
+        console.log(`  ${g.owner}/${g.slug}@${g.version}  ${sanitizeForTerminal(g.name)}${tagline} [${g.visibility}]${mine}`);
+    }
+    const first = result.guides[0];
+    console.log(`Install one with \`ahood project add ${first.owner}/${first.slug}\` (saved to .claude/project.md).`);
+}

package/dist/commands/publish.js

@@ -6,7 +6,7 @@ import { apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, SEMVER_RE, validateExternalUrl } from "../spec.js";
 import { UsageError } from "../usage-error.js";
-import { assertKind, strictKind } from "../kinds.js";
+import { assertKind, CLI_KINDS, isCliKind, KINDS, strictKind } from "../kinds.js";
 // `ahood agent publish` / `ahood mcp publish` (ahood-cli#172): an existing
 // entry of another kind must be refused before anything is packed, created,
 // or uploaded. The upload would fail server-side anyway -- the processing
@@ -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|project] [--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 && !isCliKind(kind)) {
+        throw new UsageError(`--kind must be ${orList(CLI_KINDS.map((k) => `"${k}"`))} (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
@@ -355,6 +355,33 @@ async function initVersion(owner, skill, version, packageSizeBytes, changelog, c
         return { init, created };
     }
 }
+// "a, b, or c" -- for messages that enumerate every kind.
+function orList(items) {
+    return items.length <= 2 ? items.join(" or ") : `${items.slice(0, -1).join(", ")}, or ${items.at(-1)}`;
+}
+// Which kind a publish folder is, from the root docs it holds (KINDS[k].
+// rootDoc), so a new kind needs no branch here. An explicit kind must have
+// its root doc. With none, exactly one root doc must be present; SKILL.md
+// alone returns undefined, the pre-kind behaviour (the server defaults to
+// skill). Inference: agent/mcp (ahood-cli#172), doc (#182), project (#185).
+function resolvePublishKind(path, kind, via) {
+    if (kind !== undefined) {
+        const rootDocPath = join(path, KINDS[kind].rootDoc);
+        if (!existsSync(rootDocPath)) {
+            throw new Error(`No ${KINDS[kind].rootDoc} found at ${rootDocPath} -- ${via} must point at a folder containing ${KINDS[kind].rootDoc}.`);
+        }
+        return kind;
+    }
+    const present = CLI_KINDS.filter((k) => existsSync(join(path, KINDS[k].rootDoc)));
+    const rootDocs = CLI_KINDS.map((k) => KINDS[k].rootDoc);
+    if (present.length > 1) {
+        throw new Error(`Multiple root files found at ${path} (${present.map((k) => KINDS[k].rootDoc).join(", ")}) -- pass ${orList(CLI_KINDS.map((k) => `--kind ${k}`))} to disambiguate.`);
+    }
+    if (present.length === 0) {
+        throw new Error(`No ${orList(rootDocs)} found at ${path} -- publish must point at a ${orList(CLI_KINDS)} folder's root.`);
+    }
+    return present[0] === "skill" ? undefined : present[0];
+}
 // --json mode (ahood-cli#57): a CI/script caller needs one machine-readable
 // object on stdout, not the human progress lines below scraped with a
 // regex. jsonOutput therefore gates every intermediate console.log in this
@@ -374,42 +401,9 @@ export async function publish(args, scope) {
         const scopedKind = strictKind(scope);
         const kind = scopedKind ?? parsed.kind;
         const via = scopedKind ? `ahood ${scope.noun} publish` : `publish --kind ${kind}`;
-        const skillMdPath = join(path, "SKILL.md");
-        const agentMdPath = join(path, "AGENT.md");
-        const serverJsonPath = join(path, "server.json");
+        const skillMdPath = join(path, KINDS.skill.rootDoc);
         const hasSkillMd = existsSync(skillMdPath);
-        const hasAgentMd = existsSync(agentMdPath);
-        const hasServerJson = existsSync(serverJsonPath);
-        let resolvedKind = kind;
-        if (kind === "agent") {
-            if (!hasAgentMd)
-                throw new Error(`No AGENT.md found at ${agentMdPath} -- ${via} must point at a folder containing AGENT.md.`);
-        }
-        else if (kind === "skill") {
-            if (!hasSkillMd)
-                throw new Error(`No SKILL.md found at ${skillMdPath} -- ${via} must point at a folder containing SKILL.md.`);
-        }
-        else if (kind === "mcp") {
-            if (!hasServerJson)
-                throw new Error(`No server.json found at ${serverJsonPath} -- ${via} must point at a folder containing server.json.`);
-        }
-        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);
-            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.`);
-            }
-            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.`);
-            }
-            if (hasAgentMd) {
-                resolvedKind = "agent"; // inferred: only AGENT.md present, no --kind needed
-            }
-            else if (hasServerJson) {
-                resolvedKind = "mcp"; // inferred: only server.json present, no --kind needed
-            }
-            // else: hasSkillMd only -- resolvedKind stays undefined (unchanged existing behavior, server defaults to 'skill')
-        }
+        const resolvedKind = resolvePublishKind(path, kind, via);
         // ahood-cli#93: fires for an explicit --kind skill, and for the
         // inferred-skill case above (resolvedKind left undefined because
         // SKILL.md was the only root file present) -- but not when SKILL.md