@ahood/cli 0.10.1 → 0.12.0

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, 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
@@ -47,6 +47,11 @@ export async function remove(args, scope) {
     const agentFile = agentPath(owner, skill);
     const agentExisted = existsSync(agentFile);
     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
@@ -55,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 && hadLockfileEntry;
-    if (!dirExisted && !agentExisted && !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;
@@ -93,6 +98,8 @@ export async function remove(args, scope) {
         rmSync(dir, { recursive: true, force: true });
     if (agentExisted)
         rmSync(agentFile, { 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,8 +214,13 @@ export async function update(args, scope) {
             }
             // no @version -- resolves to latest again. A strict scope is passed on so
             // add() re-checks the kind it resolves itself before writing anything.
+            // A doc 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 (isPinnedFileKind(meta.kind))
+                await add([ownerSlashSkill], { noun: meta.kind, kind: meta.kind });
             else
                 await add([ownerSlashSkill]);
         }

package/dist/help.js

@@ -121,7 +121,8 @@ export const SKILL_COMMANDS_HELP = [
             "installs instead as a single file at .claude/agents/<owner>@<skill>.md (Claude Code's own subagent " +
             "loader scans .claude/agents/*.md as flat files), not a .claude/skills/ directory. An artifact published " +
             "with --kind mcp installs by merging an entry into .mcp.json instead, prompting for any secret " +
-            "environment variables its server.json declares that aren't already set in your shell.",
+            "environment variables its server.json declares that aren't already set in your shell. A doc 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"],
     },
     {
@@ -206,17 +207,17 @@ export const SKILL_COMMANDS_HELP = [
         examples: ["ahood skill init pdf-tools", "ahood skill init"],
     },
     {
-        usage: "ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]",
-        summary: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist.",
-        desc: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json. If the artifact " +
-            "doesn't exist yet, this creates it first -- pass --name to set its display name, and --kind agent or --kind mcp if " +
-            "publishing an AGENT.md or server.json (auto-detected from the folder contents when only one of SKILL.md/AGENT.md/server.json is present). " +
+        usage: "ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp|doc|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        What kind of artifact this is. Auto-detected from SKILL.md/AGENT.md/server.json 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.",
@@ -240,15 +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.
+// Placeholders and examples come from the kind table (kind-info.ts KINDS).
 function registryCommandsHelp(kind) {
     const info = KINDS[kind];
-    const n = kind === "agent" ? "<agent>" : "<server>";
+    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 = kind === "agent" ? "alice/code-reviewer" : "alice/github-server";
+    const ex = info.example.slug;
     const kindRefusal = `Refused, before anything else happens, when the target is not ${a} ${label}.`;
     return [
         {
@@ -378,11 +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 "${kind === "agent" ? "Code Reviewer" : "GitHub Server"}"`],
+            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;
@@ -585,6 +617,8 @@ const ENTITY_COMMANDS_HELP = {
     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,
 };
@@ -709,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 <verb>` / `ahood mcp <verb>`, or add",
-        "`--kind skill|agent|mcp` to any verb below (`--kind all` spells out the legacy behavior).",
+        "working. For one kind only, use `ahood agent|mcp|doc|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:",
@@ -751,12 +785,31 @@ export function formatMcpHelp() {
 }
 // One entry point for every registry noun's group help, so dispatch and
 // `ahood help <noun>` can't disagree about which listing a noun gets.
+export function formatDocHelp() {
+    return formatRegistryKindHelp("ahood doc -- docs (DOC.md) in the ahood registry", [
+        "Every verb here acts on docs only: a target of another kind is refused before anything",
+        "is downloaded, prompted for, written, or sent. Installs land in .claude/docs/<owner>@<doc>.md.",
+        "To look at a doc without installing it, use `ahood doc read`.",
+    ], DOC_COMMANDS_HELP, "doc");
+}
+export function 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();
-    return formatSkillHelp();
+    return KIND_HELP[noun]();
 }
 // `ahood group --help` -- the group-level listing for every group verb.
 export function formatGroupHelp() {
@@ -793,6 +846,10 @@ export function formatHelp() {
     const agentGroupSummary = "The same verbs, for agent definitions only -- run `ahood agent --help` for the full list.";
     const mcpGroupUsage = "ahood mcp <command>";
     const mcpGroupSummary = "The same verbs, for MCP server manifests only; bare `ahood mcp` or `ahood mcp serve` starts the local MCP server.";
+    const docGroupUsage = "ahood doc <command>";
+    const docGroupSummary = "The same verbs, for docs (DOC.md) only -- run `ahood doc --help` for the full list.";
+    const 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>";
@@ -802,6 +859,8 @@ export function formatHelp() {
         { usage: skillGroupUsage, summary: skillGroupSummary },
         { usage: agentGroupUsage, summary: agentGroupSummary },
         { usage: mcpGroupUsage, summary: mcpGroupSummary },
+        { usage: docGroupUsage, summary: docGroupSummary },
+        { usage: projectGroupUsage, summary: projectGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
         { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
@@ -823,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` for the kind-scoped agent and MCP 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";
@@ -96,6 +97,8 @@ const COMMANDS = {
     mcp: dispatchMcp,
     skill: dispatchSkill,
     agent: dispatchAgent,
+    doc: dispatchDoc,
+    project: dispatchProject,
     group: dispatchGroup,
     snap: dispatchSnap,
 };
@@ -107,8 +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).
-const GROUP_COMMANDS = new Set(["skill", "agent", "mcp", "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++)
@@ -146,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) --
+// `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
@@ -210,6 +214,21 @@ async function dispatchSkill(args) {
 async function dispatchAgent(args) {
     await dispatchRegistry("agent", 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
@@ -312,7 +331,7 @@ async function main() {
             process.stdout.write(content);
             return;
         }
-        if (sub === "skill" || sub === "agent" || sub === "mcp") {
+        if (isCliKind(sub)) {
             const verb = args[1];
             const entry = verb ? findCommandHelp(sub, verb) : undefined;
             console.log(entry ? formatCommandHelp(entry) : formatKindHelp(sub));
@@ -394,4 +413,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchAgent, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };
+export { main, dispatchSkill, dispatchAgent, dispatchDoc, 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. This
-// CLI has a noun group for three of them. `doc` is a real registry kind left
-// out of this CLI's scope on purpose; adding it means one entry in KINDS
-// below plus its help/init template, not a new dispatcher.
+// -- so the kind an entry reports now is the kind it has always had. Each
+// kind has a noun group (`ahood skill|agent|mcp|doc <verb>`), all run by one
+// shared dispatcher. `doc` joined as the fourth in ahood-cli#182: it installs
+// as one flat Markdown file, its DOC.md, the same shape an agent has.
+// `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,9 +41,39 @@ 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",
+        article: "a",
+        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,6 +62,9 @@ export async function ensureRemoteKind(scope, owner, skill, verb, action) {
 // skill whose directory was deleted by hand) is undefined: unknown, and the
 // caller must ask the registry rather than guess.
 export function localInstalledKind(owner, skill, entry) {
+    // A doc 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)
@@ -102,8 +105,8 @@ export function extractKindFlag(args) {
 // Resolves the scope for `ahood <noun> <verb> [--kind <k>]`.
 //   skill noun, no --kind or --kind all  -> legacy (cross-kind)
 //   skill noun, --kind <k>               -> strict <k>
-//   agent/mcp noun, no --kind or --kind <same> -> strict <noun>
-//   agent/mcp noun, any other --kind     -> usage error (contradiction)
+//   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/lockfile.js

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

package/dist/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

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