@ahood/cli 0.11.0 → 0.12.0

package/README.md

@@ -189,9 +189,9 @@ 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, MCP servers, and docs
+## Kinds: skills, agents, MCP servers, docs, and project guides
 
-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:
+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 |
 | --- | --- | --- | --- |
@@ -199,6 +199,7 @@ The registry holds four kinds of artifact, each with its own command group. All
 | 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
@@ -208,14 +209,18 @@ $ ahood mcp init github-server          # ./github-server/server.json, a safe pl
 $ 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`, `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.
+- **`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.
 
@@ -260,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\|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. |
+| `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
 
@@ -333,6 +338,30 @@ alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood s
 | `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, docPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.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, strictKind } 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,26 +865,27 @@ 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
+// `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 installDoc(owner, skill, meta, buffer) {
+async function installPinnedFile(kind, owner, skill, meta, buffer) {
     const key = `${owner}/${skill}`;
-    const content = await extractSingleFileContent(buffer, "DOC.md");
-    const destPath = docPath(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: "doc",
+            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 doc remove ${key}\` to clean it up.`);
+        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));
         }
@@ -892,6 +893,27 @@ async function installDoc(owner, skill, meta, buffer) {
     }
     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)
@@ -903,25 +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");
-    // 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. 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.");
+    // 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
@@ -947,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.kind !== "doc" && 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);
@@ -980,8 +997,8 @@ export async function add(args, scope) {
         await installMcpEntry(owner, skill, meta, buffer);
         return;
     }
-    if (docInstall) {
-        await installDoc(owner, skill, meta, buffer);
+    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

package/dist/commands/completion.js

@@ -1,14 +1,15 @@
-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 { 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; doc -- #182) 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],
 ];
@@ -22,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/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
@@ -121,11 +123,28 @@ TODO -- write the documentation here. Plain Markdown; this whole file, frontmatt
 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."],
@@ -136,8 +155,33 @@ const NEXT_STEPS = {
         '"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."],
 };
-const PLACEHOLDERS = { skill: "<skill>", agent: "<agent>", mcp: "<server>", doc: "<doc>" };
+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
@@ -149,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);
@@ -197,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 = PLACEHOLDERS[kind];
+    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|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)) {

package/dist/project-remote.js

@@ -0,0 +1,80 @@
+// Git remotes for project guides (ahood-cli#185): reading this repository's
+// origin, and normalizing a remote to the `host/owner/repo` form the ahood
+// server stores and matches on. normalizeProjectRemote is a line-for-line port
+// of the server's lib/projects/normalize-project-remote.ts (ahood#778) -- the
+// two must agree, or `project init` writes a remote the lookup never matches.
+// tests/project-remote.test.ts runs the server's own test table against it.
+import { execFileSync } from "node:child_process";
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const PATH_SEGMENT = /^[a-z0-9._-]+$/;
+const ALLOWED_SCHEMES = ["https", "http", "ssh", "git"];
+const MAX_PROJECT_REMOTE_LENGTH = 255;
+const MAX_PATH_SEGMENTS = 8;
+// Never echoes the input back: a rejected remote can still carry a
+// credential (`https://user:token@...`).
+const INVALID = {
+    ok: false,
+    reason: "not a git remote; expected host/owner/repo, e.g. github.com/owner/repo",
+};
+// Strips the scheme, any userinfo (`user:token@`), the port, a trailing
+// `.git` and trailing slashes, then lowercases everything.
+export function normalizeProjectRemote(raw) {
+    const input = raw.trim();
+    if (!input || input.length > MAX_PROJECT_REMOTE_LENGTH)
+        return INVALID;
+    if (/[\s?#\\]/.test(input))
+        return INVALID;
+    let rest;
+    const scheme = input.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+    if (scheme) {
+        if (!ALLOWED_SCHEMES.includes(scheme[1].toLowerCase()))
+            return INVALID;
+        rest = input.slice(scheme[0].length);
+    }
+    else {
+        // scp-like form: [user@]host:path, where the path does not start with "/".
+        const scp = input.match(/^(?:[^@/:]+@)?([^@/:]+):(?!\/)(.+)$/);
+        rest = scp ? `${scp[1]}/${scp[2]}` : input;
+    }
+    const slash = rest.indexOf("/");
+    if (slash <= 0)
+        return INVALID;
+    let host = rest.slice(0, slash);
+    const at = host.lastIndexOf("@");
+    if (at !== -1)
+        host = host.slice(at + 1);
+    host = host.replace(/:\d+$/, "").toLowerCase();
+    const labels = host.split(".");
+    if (labels.length < 2 || !labels.every((label) => HOST_LABEL.test(label)))
+        return INVALID;
+    const path = rest
+        .slice(slash + 1)
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "")
+        .replace(/\/+$/, "")
+        .toLowerCase();
+    const segments = path.split("/");
+    if (segments.length < 2 || segments.length > MAX_PATH_SEGMENTS)
+        return INVALID;
+    if (!segments.every((s) => s !== "." && s !== ".." && PATH_SEGMENT.test(s)))
+        return INVALID;
+    return { ok: true, value: `${host}/${segments.join("/")}` };
+}
+// The current repository's origin, normalized, or undefined when there is no
+// git, no repository, no origin, or an origin that is not a shareable remote.
+// The raw URL never leaves this function: it can carry a token.
+export function detectProjectRemote() {
+    let raw;
+    try {
+        raw = execFileSync("git", ["remote", "get-url", "origin"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const normalized = normalizeProjectRemote(raw);
+    return normalized.ok ? normalized.value : undefined;
+}

package/dist/spec.js

@@ -129,3 +129,12 @@ export function docPath(owner, doc) {
     validateSegment(doc, "skill", spec);
     return join(DOCS_ROOT, `${owner}@${doc}.md`);
 }
+// A project guide installs to one fixed path per repository (ahood-cli#185),
+// beside CLAUDE.md/AGENTS.md rather than inside them, so ahood never edits a
+// file the user owns. Being shared, the path is claimed by exactly one pin:
+// add.ts refuses a second guide while another is pinned.
+export const PROJECT_GUIDE_PATH = join(".claude", "project.md");
+// Where a pinned-file kind's install lives (kind-info.ts PINNED_FILE_KINDS).
+export function pinnedFilePath(kind, owner, slug) {
+    return kind === "doc" ? docPath(owner, slug) : PROJECT_GUIDE_PATH;
+}

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), 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.
+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), docs (DOC.md), and project guides (PROJECT.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, project guide, publish a skill, ahood mcp, ahood doc, ahood project, AHOOD_TOKEN.
 ---
 
 # ahood
@@ -13,7 +13,7 @@ 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.
 
-## Four kinds, four command groups
+## Five kinds, five command groups
 
 | Kind | Root file | Installs to | Commands |
 |---|---|---|---|
@@ -21,23 +21,29 @@ version (`ahood --version`). It needs no login or network to print.
 | 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>` |
 
-All four groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
+All five 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>`, `ahood mcp <verb>` and `ahood doc <verb>` act on their own kind only.
+- `ahood agent <verb>`, `ahood mcp <verb>`, `ahood doc <verb>` and `ahood project <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, 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;
+  they resolve, except a doc or project guide: `skill add` refuses one and points at
+  `ahood doc add` / `ahood project add`.
+  Add `--kind skill` (or `agent`, `mcp`, `doc`, `project`) 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.
 - 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.
+- A project guide is how to work in one repository: conventions, verification, traps. Run bare
+  `ahood project` inside a repository to list the guides naming its git remote;
+  `ahood project add alice/acme-api` saves one to `.claude/project.md` (pinned, one per
+  repository) and never touches `CLAUDE.md` or `AGENTS.md` -- point those at it yourself.
 
 ## Find, inspect, then install
 
@@ -87,7 +93,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`/`doc` `update` and `outdated` consider only installed pins of that
+With no target, `agent`/`mcp`/`doc`/`project` `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.
 
@@ -100,13 +106,14 @@ 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 project init acme-api            # ./acme-api/PROJECT.md, `project:` filled from git origin
 
 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`/`doc publish` imply the kind and refuse a contradictory `--kind`
+  account. `agent publish`/`mcp publish`/`doc publish`/`project 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`.
@@ -153,7 +160,7 @@ ahood skill publish alice/pdf-tools@1.1.0 --path pdf-tools --changelog "Adds spl
 3. **The hosted registry MCP endpoint**, `https://www.ahood.dev/api/mcp`: Streamable HTTP,
    stateless (POST only), `Authorization: Bearer <token>`. It has write tools too:
    `search_skills`, `get_skill`, `fetch_skill`, `read_skill`, `list_skill_versions`,
-   `list_my_skills`, `search_collections`, `get_collection`, `create_skill`, `update_skill`,
+   `list_my_skills`, `search_collections`, `get_collection`, `get_project_guide`, `create_skill`, `update_skill`,
    `report_skill`, `delete_skill`, `yank_version`, and snap tools (`create_snap`,
    `list_snaps`, `get_snap`, `set_snap_tags`, `delete_snap`, `share_snap`, `unshare_snap`).
    A client that opens with a legacy-SSE `GET` gets a 405 -- use a Streamable HTTP client.

package/package.json

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