@ahood/cli 0.11.0 → 0.12.1

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|doc] [--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" && kind !== "doc") {
-        throw new UsageError(`--kind must be "skill", "agent", "mcp", or "doc" (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,56 +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 docMdPath = join(path, "DOC.md");
+        const skillMdPath = join(path, KINDS.skill.rootDoc);
         const hasSkillMd = existsSync(skillMdPath);
-        const hasAgentMd = existsSync(agentMdPath);
-        const hasServerJson = existsSync(serverJsonPath);
-        const hasDocMd = existsSync(docMdPath);
-        let resolvedKind = kind;
-        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.`);
-        }
-        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",
-                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, --kind mcp, or --kind doc to disambiguate.`);
-            }
-            if (present.length === 0) {
-                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
-            }
-            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')
-        }
+        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

package/dist/commands/remove.js

@@ -1,10 +1,10 @@
 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, docPath, MCP_CONFIG_PATH } from "../spec.js";
+import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, docPath, pinnedFilePath, 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";
+import { assertKind, ensureRemoteKind, KindMismatchError, describeKind, isPinnedFileKind, localInstalledKind, strictKind, } from "../kinds.js";
 // `ahood agent remove` / `ahood mcp remove` (ahood-cli#172): decide whether
 // this install really is the scope's kind BEFORE the prompt and every delete
 // below. Local evidence first -- remove has always worked offline, and the
@@ -46,10 +46,12 @@ 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];
+    // A doc or project guide installs as one pinned file (ahood-cli#182, #185).
+    // A doc's path is derived from its own key, so it is found even without a
+    // pin; the project guide's path is shared, so only this key's pin claims it.
+    const pinnedFile = isPinnedFileKind(lockEntry?.kind) ? pinnedFilePath(lockEntry.kind, owner, skill) : docPath(owner, skill);
+    const pinnedFileExisted = existsSync(pinnedFile);
     const hadLockfileEntry = lockEntry !== undefined;
     // A pin whose install left nothing on disk is the defining shape of an
     // mcp-kind install: its only footprint is this pin plus a live .mcp.json
@@ -58,8 +60,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 && !docExisted && lockEntry?.kind !== "doc" && hadLockfileEntry;
-    if (!dirExisted && !agentExisted && !docExisted && !hadLockfileEntry) {
+    const hadNoOnDiskFootprint = !dirExisted && !agentExisted && !pinnedFileExisted && !isPinnedFileKind(lockEntry?.kind) && hadLockfileEntry;
+    if (!dirExisted && !agentExisted && !pinnedFileExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
         return;
@@ -96,8 +98,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 });
+    if (pinnedFileExisted)
+        rmSync(pinnedFile, { 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

@@ -2,7 +2,7 @@ import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
 import { add, fetchVersionMeta, readMcpConfig, updateMcpEntry } from "./add.js";
 import { UsageError } from "../usage-error.js";
-import { assertKind, isCliKind, KINDS, localInstalledKind, strictKind } from "../kinds.js";
+import { assertKind, isCliKind, isPinnedFileKind, KINDS, localInstalledKind, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]";
 function toPreview(ownerSlashSkill, currentVersion, meta) {
     const upToDate = currentVersion === meta.version;
@@ -214,13 +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.
+            // A doc or project pin under legacy `ahood skill update` is moved
+            // forward through its own scope (ahood-cli#182, #185): legacy add
+            // refuses those kinds, but legacy update has always covered every pin.
             if (kind)
                 await add([ownerSlashSkill], scope);
-            else if (meta.kind === "doc")
-                await add([ownerSlashSkill], { noun: "doc", kind: "doc" });
+            else if (isPinnedFileKind(meta.kind))
+                await add([ownerSlashSkill], { noun: meta.kind, kind: meta.kind });
             else
                 await add([ownerSlashSkill]);
         }

package/dist/help.js

@@ -121,8 +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. A doc is refused " +
-            "here; install it with `ahood doc add`.",
+            "environment variables its server.json declares that aren't already set in your shell. A doc or project " +
+            "guide is refused here; install it with `ahood doc add` or `ahood project add`.",
         examples: ["ahood skill add alice/pdf-tools", "ahood skill add alice/pdf-tools@1.2.0"],
     },
     {
@@ -207,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|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). " +
+        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]",
+        summary: "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.",
+        desc: "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. If the artifact " +
+            "doesn't exist yet, this creates it first -- pass --name to set its display name, and --kind agent, --kind mcp, --kind doc, or --kind project if " +
+            "publishing an AGENT.md, server.json, DOC.md, or PROJECT.md (auto-detected from the folder contents when only one of SKILL.md/AGENT.md/server.json/DOC.md/PROJECT.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|doc    What kind of artifact this is. Auto-detected from SKILL.md/AGENT.md/server.json/DOC.md when omitted.",
+            "--kind <kind>                 skill, agent, mcp, doc, or project. Auto-detected from the folder's root doc 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.",
@@ -241,21 +241,16 @@ 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" },
-};
+// Placeholders and examples come from the kind table (kind-info.ts KINDS).
 function registryCommandsHelp(kind) {
     const info = KINDS[kind];
-    const n = PLACEHOLDER[kind];
+    const n = info.placeholder;
     const p = `ahood ${kind}`;
     const label = info.label;
     const a = info.article;
     const plural = info.plural;
     const doc = info.rootDoc;
-    const ex = EXAMPLE[kind].slug;
+    const ex = info.example.slug;
     const kindRefusal = `Refused, before anything else happens, when the target is not ${a} ${label}.`;
     return [
         {
@@ -385,12 +380,41 @@ 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 "${EXAMPLE[kind].name}"`],
+            examples: [`${p} publish ${ex}@1.0.0 --name "${info.example.name}"`],
         },
     ];
 }
 export const AGENT_COMMANDS_HELP = registryCommandsHelp("agent");
 export const DOC_COMMANDS_HELP = registryCommandsHelp("doc");
+// `ahood project` (ahood-cli#185): the shared verbs, with init's `project`
+// field flags, plus bare `ahood project` -- the guides for this repository.
+export const PROJECT_COMMANDS_HELP = [
+    {
+        usage: "ahood project [--remote <git-remote>] [--json]",
+        summary: "List the project guides you can see for this repository's git remote.",
+        desc: "List the project guides you can see that name this repository's git remote (`git remote get-url origin`, " +
+            "normalized to host/owner/repo -- any credentials in it are stripped and never sent), your own first. Read-only; " +
+            "needs `ahood login`. Asks the hosted get_project_guide tool.",
+        flags: [
+            "--remote <git-remote>   Look up this remote instead of origin's.",
+            "--json                  Emit {project, guides} (each guide with its PROJECT.md content) instead of formatted lines.",
+        ],
+        examples: ["ahood project", "ahood project --remote github.com/alice/acme-api"],
+    },
+    ...registryCommandsHelp("project").map((entry) => entry.usage.startsWith("ahood project init")
+        ? {
+            ...entry,
+            usage: "ahood project init [name] [--project <git-remote> | --no-project]",
+            desc: entry.desc +
+                " The optional `project` field (the repository's git remote, which is how get_project_guide finds the guide) " +
+                "is filled from `git remote get-url origin`, normalized to host/owner/repo.",
+            flags: [
+                "--project <git-remote>   Set the `project` field to this remote (normalized).",
+                "--no-project             Leave the `project` field out.",
+            ],
+        }
+        : entry),
+];
 // `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;
@@ -594,6 +618,7 @@ const ENTITY_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,
 };
@@ -718,8 +743,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|mcp|doc <verb>`, or add",
-        "`--kind skill|agent|mcp|doc` to any verb below (`--kind all` spells out the legacy behavior).",
+        "working. For one kind only, use `ahood agent|mcp|doc|project <verb>`, or add",
+        "`--kind skill|agent|mcp|doc|project` to any verb below (`--kind all` spells out the legacy behavior).",
         "A future major version will make `ahood skill` skills-only.",
         "",
         "Commands:",
@@ -767,14 +792,24 @@ export function formatDocHelp() {
         "To look at a doc without installing it, use `ahood doc read`.",
     ], DOC_COMMANDS_HELP, "doc");
 }
+export function formatProjectHelp() {
+    return formatRegistryKindHelp("ahood project -- project guides (PROJECT.md) in the ahood registry", [
+        "A project guide is how to work in one repository: conventions, verification, traps.",
+        "Every verb here acts on project guides only: a target of another kind is refused before anything",
+        "is downloaded, prompted for, written, or sent. `add` saves the guide to .claude/project.md, one per",
+        "repository, and never touches CLAUDE.md or AGENTS.md. Bare `ahood project` lists the guides for",
+        "this repository's git remote.",
+    ], PROJECT_COMMANDS_HELP, "project");
+}
+const KIND_HELP = {
+    skill: formatSkillHelp,
+    agent: formatAgentHelp,
+    mcp: formatMcpHelp,
+    doc: formatDocHelp,
+    project: formatProjectHelp,
+};
 export function formatKindHelp(noun) {
-    if (noun === "agent")
-        return formatAgentHelp();
-    if (noun === "mcp")
-        return formatMcpHelp();
-    if (noun === "doc")
-        return formatDocHelp();
-    return formatSkillHelp();
+    return KIND_HELP[noun]();
 }
 // `ahood group --help` -- the group-level listing for every group verb.
 export function formatGroupHelp() {
@@ -813,6 +848,8 @@ export function formatHelp() {
     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 projectGroupUsage = "ahood project <command>";
+    const projectGroupSummary = "The same verbs, for project guides (PROJECT.md) only; bare `ahood project` lists this repository's guides.";
     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>";
@@ -823,6 +860,7 @@ export function formatHelp() {
         { usage: agentGroupUsage, summary: agentGroupSummary },
         { usage: mcpGroupUsage, summary: mcpGroupSummary },
         { usage: docGroupUsage, summary: docGroupSummary },
+        { usage: projectGroupUsage, summary: projectGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
         { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
@@ -844,7 +882,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` / `ahood doc --help` for the kind-scoped agent, MCP and doc commands.",
+        "Run `ahood agent|mcp|doc|project --help` for the kind-scoped agent, MCP, doc and project guide 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/hosted-mcp.js

@@ -0,0 +1,36 @@
+// One call to a tool on the hosted registry MCP endpoint (/api/mcp), for the
+// reads that have no REST route -- today only get_project_guide
+// (ahood-cli#185). The endpoint is stateless and answers plain JSON
+// (enableJsonResponse), so a bare JSON-RPC `tools/call` through apiJson -- the
+// same auth, error mapping and retry as every REST call -- is the whole
+// client; no session or initialize handshake is needed.
+import { apiJson } from "./http.js";
+import { sanitizeForTerminal } from "./terminal-safe.js";
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function callHostedTool(name, args) {
+    const response = await apiJson("/api/mcp", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+    });
+    if (response.error)
+        throw new Error(`${name} failed: ${sanitizeForTerminal(response.error.message ?? "unknown error")}`);
+    const text = response.result?.content?.find((c) => c.type === "text")?.text;
+    if (text === undefined)
+        throw new Error(`${name} returned no content.`);
+    const payload = parseJson(text);
+    if (response.result?.isError) {
+        const reason = typeof payload?.error === "string" ? payload.error : text;
+        throw new Error(`${name} failed: ${sanitizeForTerminal(reason)}`);
+    }
+    if (payload === undefined)
+        throw new Error(`${name} returned a response that is not JSON.`);
+    return payload;
+}

package/dist/index.js

@@ -20,7 +20,8 @@ import { versions } from "./commands/versions.js";
 import { diff } from "./commands/diff.js";
 import { completion } from "./commands/completion.js";
 import { mcp } from "./commands/mcp.js";
-import { extractKindFlag, resolveScope } from "./kinds.js";
+import { CLI_KINDS, extractKindFlag, isCliKind, resolveScope } from "./kinds.js";
+import { findProjectGuides } from "./commands/project-guides.js";
 import { readUseme } from "./useme.js";
 import { UsageError } from "./usage-error.js";
 import { init } from "./commands/init.js";
@@ -97,6 +98,7 @@ const COMMANDS = {
     skill: dispatchSkill,
     agent: dispatchAgent,
     doc: dispatchDoc,
+    project: dispatchProject,
     group: dispatchGroup,
     snap: dispatchSnap,
 };
@@ -108,9 +110,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), "doc" too
-// (ahood-cli#182).
-const GROUP_COMMANDS = new Set(["skill", "agent", "mcp", "doc", "group", "snap"]);
+// Every registry noun joins it (ahood-cli#172), taken from the kind table so
+// a new kind (doc #182, project #185) needs no edit here.
+const GROUP_COMMANDS = new Set([...CLI_KINDS, "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++)
@@ -148,7 +150,7 @@ function closestGroupVerb(input) {
 function closestSnapVerb(input) {
     return closestOf(input, Object.keys(SNAP_VERBS));
 }
-// `ahood <noun> <verb> [...]` for every registry noun (skill, agent, mcp, doc) --
+// `ahood <noun> <verb> [...]` for every registry noun (kind-info.ts KINDS) --
 // 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
@@ -215,6 +217,18 @@ async function dispatchAgent(args) {
 async function dispatchDoc(args) {
     await dispatchRegistry("doc", args);
 }
+// `ahood project` (ahood-cli#185): with no verb -- nothing, or only its own
+// flags -- it lists the project guides for this repository's git remote
+// (commands/project-guides.ts). Everything else is the shared registry
+// dispatch, help included.
+async function dispatchProject(args) {
+    const first = args[0];
+    if (first === undefined || (first.startsWith("--") && first !== "--help")) {
+        await findProjectGuides(args);
+        return;
+    }
+    await dispatchRegistry("project", 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
@@ -317,7 +331,7 @@ async function main() {
             process.stdout.write(content);
             return;
         }
-        if (sub === "skill" || sub === "agent" || sub === "mcp" || sub === "doc") {
+        if (isCliKind(sub)) {
             const verb = args[1];
             const entry = verb ? findCommandHelp(sub, verb) : undefined;
             console.log(entry ? formatCommandHelp(entry) : formatKindHelp(sub));
@@ -399,4 +413,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchAgent, dispatchDoc, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };
+export { main, dispatchSkill, dispatchAgent, dispatchDoc, dispatchProject, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/kind-info.js

@@ -4,13 +4,18 @@
 //
 // Kind-aware registry commands (ahood-cli#172).
 //
-// The registry stores four artifact kinds (the backend's
-// lib/skills/validation.ts ALLOWED_KINDS: skill, agent, mcp, doc), and a
+// The registry stores five artifact kinds (the backend's
+// lib/skills/validation.ts ALLOWED_KINDS: skill, agent, mcp, doc, project), 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. 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.
+// `project` joined as the fifth in ahood-cli#185: one PROJECT.md per
+// repository, installed to the fixed path .claude/project.md.
+//
+// Per-kind facts live here, not in per-command branches: `placeholder` and
+// `example` feed help and init, `about` the legacy `skill add` refusal.
 export const KINDS = {
     skill: {
         label: "skill",
@@ -18,6 +23,8 @@ export const KINDS = {
         plural: "skills",
         rootDoc: "SKILL.md",
         installsTo: ".claude/skills/<owner>@<skill>/",
+        placeholder: "<skill>",
+        example: { slug: "alice/pdf-tools", name: "PDF Tools" },
     },
     agent: {
         label: "agent",
@@ -25,6 +32,8 @@ export const KINDS = {
         plural: "agents",
         rootDoc: "AGENT.md",
         installsTo: ".claude/agents/<owner>@<agent>.md",
+        placeholder: "<agent>",
+        example: { slug: "alice/code-reviewer", name: "Code Reviewer" },
     },
     mcp: {
         label: "MCP server manifest",
@@ -32,6 +41,8 @@ export const KINDS = {
         plural: "MCP server manifests",
         rootDoc: "server.json",
         installsTo: "an entry in .mcp.json",
+        placeholder: "<server>",
+        example: { slug: "alice/github-server", name: "GitHub Server" },
     },
     doc: {
         label: "doc",
@@ -39,9 +50,30 @@ export const KINDS = {
         plural: "docs",
         rootDoc: "DOC.md",
         installsTo: ".claude/docs/<owner>@<doc>.md",
+        placeholder: "<doc>",
+        example: { slug: "alice/setup-guide", name: "Setup Guide" },
+        about: "a documentation page",
+    },
+    project: {
+        label: "project guide",
+        article: "a",
+        plural: "project guides",
+        rootDoc: "PROJECT.md",
+        installsTo: ".claude/project.md",
+        placeholder: "<slug>",
+        example: { slug: "alice/acme-api", name: "Acme API" },
+        about: "a guide to working in one repository",
     },
 };
 export const CLI_KINDS = Object.keys(KINDS);
 export function isCliKind(value) {
     return typeof value === "string" && CLI_KINDS.includes(value);
 }
+// Kinds that install as one root-doc file pinned with its kind in the
+// lockfile (doc: ahood-cli#182, project: #185). The recorded kind is how
+// remove/update recognise the pin offline, and how a project guide's shared
+// path is claimed by exactly one pin. Legacy `skill add` refuses these.
+export const PINNED_FILE_KINDS = ["doc", "project"];
+export function isPinnedFileKind(value) {
+    return typeof value === "string" && PINNED_FILE_KINDS.includes(value);
+}

package/dist/kinds.js

@@ -5,8 +5,8 @@ import { existsSync } from "node:fs";
 import { apiJson } from "./http.js";
 import { agentPath, skillDir } from "./spec.js";
 import { UsageError } from "./usage-error.js";
-import { KINDS, CLI_KINDS, isCliKind } from "./kind-info.js";
-export { KINDS, CLI_KINDS, isCliKind };
+import { KINDS, CLI_KINDS, isCliKind, isPinnedFileKind } from "./kind-info.js";
+export { KINDS, CLI_KINDS, isCliKind, isPinnedFileKind };
 export const LEGACY_SCOPE = { noun: "skill", kind: "all" };
 export function strictKind(scope) {
     return scope && scope.kind !== "all" ? scope.kind : undefined;
@@ -62,9 +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";
+    // A doc or project pin records its kind (ahood-cli#182, #185).
+    if (isPinnedFileKind(entry?.kind))
+        return entry.kind;
     const hasDir = existsSync(skillDir(owner, skill));
     const hasAgentFile = existsSync(agentPath(owner, skill));
     if (hasDir && !hasAgentFile)
@@ -105,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/doc noun, no --kind or --kind <same> -> strict <noun>
-//   agent/mcp/doc noun, any other --kind     -> usage error (contradiction)
+//   any other noun, no --kind or --kind <same> -> strict <noun>
+//   any other 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)) {