@ahood/cli 0.11.0 → 0.12.1

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/archive-entries.js

@@ -0,0 +1,59 @@
+import { posix } from "node:path";
+import * as tarStream from "tar-stream";
+import { sanitizeForTerminal } from "./terminal-safe.js";
+// AlexKay28/ahood#792 -- the one archive-entry path rule, mirroring the
+// server's lib/publish/entry-path.ts. `SKILL.md` and `././SKILL.md` used to be
+// two entries to the server (which reads the FIRST) but one file to
+// extractTarGz (resolve() collapsed them and the LAST write won), so a hidden
+// later duplicate could overwrite the reviewed file at install. Every
+// extractor now refuses such an archive up front instead.
+/** True when `path` is already a canonical relative POSIX path: non-empty,
+ *  no backslash or NUL, not absolute, no empty / "." / ".." segment, and
+ *  unchanged by posix.normalize. */
+export function isCanonicalEntryPath(path) {
+    if (path === "" || path.includes("\\") || path.includes("\0"))
+        return false;
+    if (posix.isAbsolute(path) || posix.normalize(path) !== path)
+        return false;
+    return path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/** A tar header name relative to the archive root. `tar -C dir .` names
+ *  every entry `./x`, so exactly ONE leading "./" is dropped; whatever
+ *  remains must already be canonical (`././x` is rejected, not collapsed). */
+export function tarEntryPath(headerName) {
+    return headerName.startsWith("./") ? headerName.slice(2) : headerName;
+}
+/** Walks every header of an already-decompressed tar and throws unless each
+ *  non-directory entry has a canonical, unique path. Runs before an extractor
+ *  writes or returns anything, so a bad entry anywhere refuses the whole
+ *  archive. Directory entries (`./`, `./scripts/`) are not files and are
+ *  skipped. */
+export async function assertCanonicalEntryPaths(tar) {
+    const seen = new Set();
+    const extract = tarStream.extract();
+    await new Promise((resolvePromise, reject) => {
+        extract.on("entry", (header, stream, next) => {
+            stream.resume();
+            if (header.type === "directory") {
+                next();
+                return;
+            }
+            const path = tarEntryPath(header.name);
+            const problem = !isCanonicalEntryPath(path)
+                ? `Refusing to extract unsafe archive entry: ${sanitizeForTerminal(header.name)} (not a canonical relative path)`
+                : seen.has(path)
+                    ? `Refusing to extract archive: it has more than one entry for "${sanitizeForTerminal(path)}"`
+                    : null;
+            if (problem) {
+                reject(new Error(problem));
+                extract.destroy();
+                return;
+            }
+            seen.add(path);
+            next();
+        });
+        extract.on("finish", () => resolvePromise());
+        extract.on("error", reject);
+        extract.end(tar);
+    });
+}

package/dist/commands/add.js

@@ -4,12 +4,13 @@ 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 { assertCanonicalEntryPaths, tarEntryPath } from "../archive-entries.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
@@ -92,6 +93,10 @@ export async function extractTarGz(buffer, destDir) {
     catch (error) {
         throw new Error(`Archive decompresses to more than ${MAX_EXTRACTED_BYTES / (1024 * 1024)} MB, or is not valid gzip -- refusing to extract.`, { cause: error });
     }
+    // Every entry path is canonical and unique before the first write
+    // (AlexKay28/ahood#792): otherwise `././SKILL.md` lands on SKILL.md and the
+    // last of the two wins, while the server validated the first.
+    await assertCanonicalEntryPaths(decompressed);
     const extract = tarStream.extract();
     const resolvedDest = resolve(destDir);
     let entryCount = 0;
@@ -112,7 +117,7 @@ export async function extractTarGz(buffer, destDir) {
             // segments (and, on Windows, drive-absolute and backslash-separated
             // names) so the comparison catches every escape shape, not just a
             // literal leading "../".
-            const entryPath = header.name.replace(/^\.\//, "");
+            const entryPath = tarEntryPath(header.name);
             const fullPath = resolve(destDir, entryPath);
             if (fullPath !== resolvedDest && !fullPath.startsWith(resolvedDest + sep)) {
                 stream.resume();
@@ -198,27 +203,20 @@ export async function extractSingleFileContent(buffer, entryName) {
     catch (error) {
         throw new Error(`Archive decompresses to more than ${MAX_EXTRACTED_BYTES / (1024 * 1024)} MB, or is not valid gzip -- refusing to extract.`, { cause: error });
     }
+    // A duplicate or non-canonical entry anywhere refuses the archive, rather
+    // than this reader and extractTarGz picking different copies of one file
+    // (AlexKay28/ahood#792; this used to take the first, extractTarGz the last).
+    await assertCanonicalEntryPaths(decompressed);
     const extract = tarStream.extract();
     let found = null;
     await new Promise((resolvePromise, reject) => {
         extract.on("entry", (header, stream, next) => {
-            // Normalize a leading "./" the same way extractTarGz and the server's
-            // extract-and-checksum.ts normalizeEntryPath do -- a plain `tar czf`
-            // commonly prefixes entries with "./", which would otherwise pass
-            // server-side validation/publish but then fail to install here with
-            // "AGENT.md not found" (ahood-cli final review finding #3).
-            const normalizedName = header.name.replace(/^\.\//, "");
-            if (normalizedName !== entryName) {
-                stream.resume();
-                next();
-                return;
-            }
-            // Only take the FIRST matching entry, mirroring the server side's
-            // `files.find(...)` lookup -- otherwise a tar with two entries at the
-            // same normalized name would resolve to whichever one happens to come
-            // last here, diverging from what the server validated against
-            // (ahood-cli final review finding #4).
-            if (found !== null) {
+            // Drop tar's one leading "./" the same way extractTarGz and the server
+            // do -- a plain `tar czf` commonly prefixes entries with "./", which
+            // would otherwise pass server-side validation/publish but then fail to
+            // install here with "AGENT.md not found" (ahood-cli final review
+            // finding #3).
+            if (header.type === "directory" || tarEntryPath(header.name) !== entryName) {
                 stream.resume();
                 next();
                 return;
@@ -865,26 +863,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 +891,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 +923,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 +962,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 +995,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).`);
+}