@ahood/cli 0.8.8 → 0.10.0

package/README.md

@@ -28,8 +28,10 @@ Installed alice/pdf-tools@1.4.0 to .claude/skills/alice@pdf-tools
 - [Why ahood](#why-ahood)
 - [Configuration](#configuration)
 - [Usage examples](#usage-examples)
+- [Kinds: skills, agents, and MCP servers](#kinds-skills-agents-and-mcp-servers)
 - [Commands](#commands)
 - [Exit codes](#exit-codes)
+- [Compatibility](#compatibility)
 - [Shell completion](#shell-completion)
 - [Using ahood from an AI agent](#using-ahood-from-an-ai-agent)
 - [Development](#development)
@@ -187,6 +189,35 @@ Shared alice/pdf-tools with design-team.
 Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private visibility, it just makes it visible to everyone in `design-team` too. On the other side, whoever received the link runs `ahood group join <the link>` to join.
 </details>
 
+## Kinds: skills, agents, and MCP servers
+
+The registry holds three kinds of artifact this CLI works with, each with its own command group. All three take the same verbs (`search`, `list`, `view`/`show`, `read`, `versions`, `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`, `share`, `unshare`, `init`, `publish`), run by the same code:
+
+| Kind | Root file | `add` installs to | Group |
+| --- | --- | --- | --- |
+| skill | `SKILL.md` | `.claude/skills/<owner>@<skill>/` | `ahood skill <verb>` |
+| agent | `AGENT.md` | `.claude/agents/<owner>@<agent>.md` | `ahood agent <verb>` |
+| mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
+
+```
+$ ahood agent search review
+$ ahood agent init code-reviewer        # ./code-reviewer/AGENT.md
+$ ahood agent publish alice/code-reviewer@1.0.0 --path code-reviewer --name "Code Reviewer"
+$ ahood mcp init github-server          # ./github-server/server.json, a safe placeholder starter
+$ ahood mcp add alice/github-server
+$ ahood agent add alice/pdf-tools
+alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood skill add alice/pdf-tools` instead.
+```
+
+- **`ahood agent` and `ahood mcp` are strict.** A target of another kind is refused -- exit code `2`, naming the kind it found -- before anything is downloaded, prompted for, written, or sent. That covers `add`, `update`, `remove`, `edit`, `unpublish`, `share`/`unshare`, `star`/`unstar`, and `publish` (an existing entry of another kind is refused before anything is packed or uploaded); the read-only verbs refuse too, rather than show the wrong kind. `search` asks the registry for that kind only, `list` keeps only that kind of your own entries, and `update`/`outdated` with no argument consider only installed pins of that kind. `agent publish`/`mcp publish` imply their kind and reject a contradictory `--kind`.
+- **Missing or unexpected kind metadata is refused, never guessed.** If the registry's answer carries no kind (or one this CLI doesn't handle), a kind-scoped command stops with exit `1` and points at the legacy form. `remove` reads the kind from the project's own files (the skill directory, the agent file, or the mcp fingerprint in the lockfile) and asks the registry only when those can't tell; if neither can, nothing is removed.
+- **`ahood skill` is legacy and cross-kind in this release.** `ahood skill search` and `ahood skill list` include every kind, and `ahood skill add`/`update`/`remove`/... act on whatever kind the target is, exactly as before -- including `--json` output and exit codes -- so existing scripts keep working. Add `--kind skill|agent|mcp` to any `ahood skill` verb (except `publish`, whose `--kind` keeps its original meaning) to scope it, or `--kind all` to spell out the cross-kind behavior.
+- **Not in scope: `doc`.** The registry also has a `doc` kind (documentation pages); this CLI has no `ahood doc` group. Kind dispatch is table-driven (`src/kind-info.ts`), so adding one is an entry there plus its help and `init` template.
+
+**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.
+
+**`ahood mcp` has two meanings.** With no arguments, or as `ahood mcp serve` (the preferred spelling), it starts this CLI's local, read-only MCP server over stdio -- unchanged, so existing MCP host configurations keep working with no edits. With a registry verb it manages MCP server manifests. Anything else (`ahood mcp srve`, `ahood mcp --flag`) fails with usage and a suggestion instead of starting a server. Neither is the hosted registry MCP endpoint at `https://ahood.vercel.app/api/mcp`.
+
 ## Commands
 
 <!-- Generated from src/help.ts's COMMANDS_HELP by scripts/sync-readme.mjs --
@@ -203,9 +234,9 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood whoami [--json]` | Reports whether your stored token still authenticates. |
 | `ahood token create <name>\|list [--json]\|revoke <id> [--yes]` | Manage personal API tokens. |
 | `ahood completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |
-| `ahood mcp` | Start an MCP server exposing read-only skill commands as tools over stdio. |
+| `ahood help useme` | Print the bundled ahood SKILL.md for an AI agent -- raw, offline, no login needed. |
 
-### Skill
+### Skill (legacy, cross-kind)
 
 | Command | What it does |
 | --- | --- |
@@ -228,6 +259,54 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood skill init [name]` | Scaffold a new skill folder with a minimal, valid SKILL.md. |
 | `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill\|agent\|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist. |
 
+### Agent
+
+| Command | What it does |
+| --- | --- |
+| `ahood agent search <query> [--json] [--limit <n>]` | Search published agents. |
+| `ahood agent view\|show <owner>/<agent> [--json] [--web]` | Show a single agent's details without installing it (alias: ahood agent show). |
+| `ahood agent read <owner>/<agent> [--json]` | Print a published agent's AGENT.md, without installing it. |
+| `ahood agent versions <owner>/<agent> [--json]` | List a agent's published-version history. |
+| `ahood agent diff <owner>/<agent> <versionA> <versionB> [--json]` | Show what changed between two published versions of an agent. |
+| `ahood agent list [--json]` | List your own agents, public and private. |
+| `ahood agent add <owner>/<agent>[@version]` | Install an agent into .claude/agents/<owner>@<agent>.md, pinned in the lockfile. |
+| `ahood agent update [<owner>/<agent> ...] [--dry-run] [--json]` | Move agent pins forward to the latest version. |
+| `ahood agent outdated [<owner>/<agent> ...] [--json]` | Read-only staleness check for installed agents. |
+| `ahood agent remove <owner>/<agent> [--yes]` | Uninstall and unpin an agent (local only, prompts unless --yes is passed). |
+| `ahood agent edit <owner>/<agent> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update an agent you own, changing only the flags you pass. |
+| `ahood agent unpublish <owner>/<agent>[@version] [--yes]` | Delete an agent from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood agent star <owner>/<agent>` | Star an agent. |
+| `ahood agent unstar <owner>/<agent>` | Remove your star from an agent. |
+| `ahood agent share <owner>/<agent> --group <group>` | Share an agent you own with a group, without changing its visibility. |
+| `ahood agent unshare <owner>/<agent> --group <group>` | Stop sharing an agent you own with a group. |
+| `ahood agent init [name]` | Scaffold a new agent folder with a minimal, valid AGENT.md. |
+| `ahood agent publish <owner>/<agent>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of an agent from a folder containing AGENT.md, creating it first if it doesn't exist yet. |
+
+### MCP (local server and server manifests)
+
+| Command | What it does |
+| --- | --- |
+| `ahood mcp serve` | Start the local, read-only ahood MCP server over stdio (preferred spelling). |
+| `ahood mcp` | Same as `ahood mcp serve`, kept byte-for-byte so existing MCP host configs keep working. |
+| `ahood mcp search <query> [--json] [--limit <n>]` | Search published MCP server manifests. |
+| `ahood mcp view\|show <owner>/<server> [--json] [--web]` | Show a single MCP server manifest's details without installing it (alias: ahood mcp show). |
+| `ahood mcp read <owner>/<server> [--json]` | Print a published MCP server manifest's server.json, without installing it. |
+| `ahood mcp versions <owner>/<server> [--json]` | List a MCP server manifest's published-version history. |
+| `ahood mcp diff <owner>/<server> <versionA> <versionB> [--json]` | Show what changed between two published versions of an MCP server manifest. |
+| `ahood mcp list [--json]` | List your own MCP server manifests, public and private. |
+| `ahood mcp add <owner>/<server>[@version]` | Install an MCP server manifest into an entry in .mcp.json, pinned in the lockfile. |
+| `ahood mcp update [<owner>/<server> ...] [--dry-run] [--json]` | Move MCP server manifest pins forward to the latest version. |
+| `ahood mcp outdated [<owner>/<server> ...] [--json]` | Read-only staleness check for installed MCP server manifests. |
+| `ahood mcp remove <owner>/<server> [--yes]` | Uninstall and unpin an MCP server manifest (local only, prompts unless --yes is passed). |
+| `ahood mcp edit <owner>/<server> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update an MCP server manifest you own, changing only the flags you pass. |
+| `ahood mcp unpublish <owner>/<server>[@version] [--yes]` | Delete an MCP server manifest from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood mcp star <owner>/<server>` | Star an MCP server manifest. |
+| `ahood mcp unstar <owner>/<server>` | Remove your star from an MCP server manifest. |
+| `ahood mcp share <owner>/<server> --group <group>` | Share an MCP server manifest you own with a group, without changing its visibility. |
+| `ahood mcp unshare <owner>/<server> --group <group>` | Stop sharing an MCP server manifest you own with a group. |
+| `ahood mcp init [name]` | Scaffold a new MCP server manifest folder with a minimal, valid server.json. |
+| `ahood mcp publish <owner>/<server>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of an MCP server manifest from a folder containing server.json, creating it first if it doesn't exist yet. |
+
 ### Group
 
 | Command | What it does |
@@ -252,10 +331,10 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood snap remove <id> [--yes]` | Permanently delete a snap (prompts for confirmation unless --yes is passed). |
 | `ahood snap share <id> [--json]` | Mint (or return the existing) shareable link for a snap. |
 | `ahood snap unshare <id> [--yes]` | Revoke a snap's share link (the snap itself is untouched; prompts for confirmation unless --yes is passed). |
-| `ahood snap tags <id> [tag1,tag2,...] [--json]` | Replace a snap's tags (omit the tag list, or pass an empty one, to clear all tags). |
+| `ahood snap tags <id> [tag ...] [--clear] [--json]` | Print a snap's tags, or replace them with the tags given. |
 <!-- COMMANDS_TABLE_END -->
 
-Run `ahood --help`, `ahood skill --help`, `ahood group --help`, `ahood snap --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>` / `ahood help group <verb>` / `ahood help snap <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
+Run `ahood --help`, `ahood skill --help`, `ahood agent --help`, `ahood mcp --help`, `ahood group --help`, `ahood snap --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help <skill|agent|mcp|group|snap> <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
 
 ## Exit codes
 
@@ -270,6 +349,12 @@ Stable across releases, safe to branch on in a script:
 | `5` | Not found |
 | `6` | Network/transport error, or an upstream server (5xx) error |
 
+## Compatibility
+
+Surfaces that are stable across releases on purpose, because something outside this codebase depends on their exact shape:
+
+- **`User-Agent` header.** Every request sends `User-Agent: @ahood/cli/<version>` (e.g. `@ahood/cli/0.9.0`), built in `src/http.ts` from this package's own `name` and `version` in `package.json`. This is deliberately a plain, stable, parseable string rather than an opaque one, because it is exactly what a WAF/firewall allowlist rule needs to scope a rate limit or block rule to browser page traffic without also catching the CLI. **Changing this header's shape (its format, delimiter, or what it's derived from) is a breaking change** for anyone who has written a rule against it, even though nothing in this CLI's own test suite would fail — treat it with the same care as the [exit codes](#exit-codes) below. If it ever needs to carry more than name/version (for example OS or Node version, to make a spoofed string easier to tell apart from a real one), that's a deliberate compatibility change too and belongs in this same section, documented to match exactly what the code sends.
+
 ## Shell completion
 
 ```
@@ -290,8 +375,9 @@ ahood completion fish > ~/.config/fish/completions/ahood.fish
 - **No interactive login required.** Set `AHOOD_TOKEN` once (a personal API token from `ahood token create <name>`) and every command works non-interactively.
 - **Structured output everywhere.** `--json` is available on every read command and on `publish`/`update`, so an agent never has to scrape human-formatted text.
 - **Predictable failure.** A stable, documented [exit code](#exit-codes) per failure class, and error messages that never leak raw upstream infrastructure details — safe to surface directly to an agent's reasoning loop.
-- **A real "start here."** `ahood skill init <name>` scaffolds a valid `SKILL.md` an agent can extend, rather than requiring it to know the frontmatter format up front.
-- **A native MCP server, for agents that prefer tool calls to subprocess parsing.** `ahood mcp` starts a Model Context Protocol server over stdio, exposing `skill_search`, `skill_view`, `skill_read`, `skill_versions`, `skill_list`, and `whoami` as typed tools -- the same data the `--json` flags above already return, reachable as structured tool calls instead. Configure your MCP-aware agent host to run `ahood mcp` (or `npx @ahood/cli@latest mcp`) as a stdio server.
+- **A built-in guide for the agent itself.** `ahood help useme` prints a complete `SKILL.md` teaching an agent when and how to use ahood -- kinds, search -> read -> add -> update, publishing, `--json`, exit codes, `AHOOD_TOKEN`, the MCP options, and which commands are destructive. It is bundled with the installed CLI version, so it needs no login, no network, and writes nothing: stdout is the raw file and nothing else (diagnostics go to stderr), ready to paste into an agent's context or for an agent with a shell to read directly (`ahood help useme > ahood-SKILL.md` saves it). That is separate from `ahood skill add alexkay/ahood`, which optionally installs the registry-published ahood skill into a project as its own pinned skill.
+- **A real "start here."** `ahood skill init <name>`, `ahood agent init <name>`, and `ahood mcp init <name>` scaffold a `SKILL.md`, `AGENT.md`, or `server.json` that passes the registry's publish validation, rather than requiring an agent to know each format up front.
+- **A native MCP server, for agents that prefer tool calls to subprocess parsing.** `ahood mcp serve` (or bare `ahood mcp`, unchanged for existing configs) starts a Model Context Protocol server over stdio, exposing `skill_search`, `skill_view`, `skill_read`, `skill_versions`, `skill_list`, `skill_outdated`, and `whoami` as typed, read-only tools -- the same data the `--json` flags above already return, reachable as structured tool calls instead. Configure your MCP-aware agent host to run `ahood mcp serve` (or `npx @ahood/cli@latest mcp serve`) as a stdio server, e.g. `claude mcp add ahood -- ahood mcp serve`.
 
 ## Development
 

package/dist/commands/add.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, renameSync, rmSync, rmdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import * as tarStream from "tar-stream";
 import { gunzipSync } from "node:zlib";
@@ -7,7 +7,9 @@ import { apiFetch, apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.js";
 import { readLockfile, withLock, writeJsonFileAtomic, writeLockfileEntryVerifyingChecksum, LockfileChecksumConflictError, } from "../lockfile.js";
 import { promptSecret } from "../secret-prompt.js";
+import { sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind } 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
@@ -237,25 +239,6 @@ export async function extractSingleFileContent(buffer, entryName) {
         throw new Error(`${entryName} not found in the downloaded archive`);
     return found;
 }
-// Every manifest field used below -- and every tar entry name extractTarGz
-// quotes back in an error above -- reaches the terminal (an error message, or
-// -- worse -- the text printed immediately before a masked secret prompt)
-// but comes verbatim from a third-party-published archive: server-side
-// validation only checks these are strings, not that they're free of
-// control/escape characters. A malicious description could otherwise smuggle
-// a terminal control sequence (cursor movement, line-clear) that repaints
-// what the user sees at the exact moment they're about to type a credential.
-// Strips C0/C1 control characters (including ESC, \x1b) and caps length so a
-// single field can't also flood the terminal.
-//
-// Takes `unknown` rather than `string` because every caller's "string" is a
-// declared type over an unchecked `as ServerManifest` cast of downloaded JSON,
-// not a guarantee: calling .replace() directly on a `registry_type: 123` would
-// turn a diagnosable message into the raw TypeError ahood-cli#121 removed from
-// this same path (ahood-cli#122).
-function sanitizeForTerminal(text) {
-    return String(text).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
-}
 // Only npm+npx is supported in v1 (docs/superpowers/specs/2026-09-03-mcp-server-artifacts-design.md) --
 // server-side publish validation (lib/publish/parse-server-manifest.ts) already
 // rejects anything else, so this check is defense-in-depth against a
@@ -533,19 +516,51 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
     const serverConfig = buildMcpServerConfig(manifest, env);
     return { manifest, serverConfig, secretNames };
 }
+// Whether the config that was (or is about to be) written to disk actually
+// carries a credential: `env` also holds non-secret configuration now
+// (ahood-cli#120), so only names the manifest declared as secrets count.
+// Load-bearing in two places since ahood-cli#158: the install/update paths
+// consult it to request 0600 for a .mcp.json they are about to CREATE, and
+// warnIfSecretsWereWritten consults it to decide whether anything secret-
+// sensitive was written at all.
+function secretsLanded(serverConfig, secretNames) {
+    const env = serverConfig.env;
+    if (!env)
+        return false;
+    return secretNames.some((name) => Object.prototype.hasOwnProperty.call(env, name));
+}
 // The plaintext-secret warning printed after a successful mcp install/update.
 // Still derived from the config that actually landed on disk -- the property
 // the old bare `serverConfig.env` check was chosen for -- but intersected with
 // the manifest's declared secrets, because `env` now also holds non-secret
 // configuration (ahood-cli#120) and would otherwise warn about credentials
 // for a server that declares none.
+//
+// ahood-cli#158 composes a second piece onto it. A brand-new .mcp.json is
+// created 0600 when a secret landed (see installMcpEntry/updateMcpEntry), but
+// an EXISTING file keeps its pre-existing mode (#119) -- deliberately, since
+// tightening it could break another tool or user that reads the shared config.
+// So when the credential landed in a file that is still group/world-readable,
+// the warning says so and suggests chmod 600, leaving the decision with the
+// user who knows their environment, instead of the CLI chmod-ing behind their
+// back.
 function warnIfSecretsWereWritten(serverConfig, secretNames) {
-    const env = serverConfig.env;
-    if (!env)
-        return;
-    if (!secretNames.some((name) => Object.prototype.hasOwnProperty.call(env, name)))
+    if (!secretsLanded(serverConfig, secretNames))
         return;
-    console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
+    let warning = `WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`;
+    // statSync rather than lstat on purpose: a symlinked .mcp.json is written
+    // THROUGH (#144), so the mode that matters is the real file's. Best-effort:
+    // the write has already succeeded, so a stat that somehow fails must not
+    // surface as a second error -- the plaintext warning above still stands.
+    try {
+        if (statSync(MCP_CONFIG_PATH).mode & 0o077) {
+            warning += ` It is also readable by other users on this machine -- consider \`chmod 600 ${MCP_CONFIG_PATH}\`.`;
+        }
+    }
+    catch {
+        // advisory only, see comment above
+    }
+    console.warn(warning);
 }
 // Fingerprint of exactly what ahood wrote into .mcp.json's mcpServers.<skill>
 // entry, stored in the lockfile alongside the version/checksum pin. Lets
@@ -617,6 +632,22 @@ function readMcpEntryEnv(entry) {
     }
     return result;
 }
+// Every install path below undoes its own on-disk write when the lockfile
+// write that would have pinned it fails. This runs that undo so that a
+// failure IN the undo can never replace the original error: a rollback fails
+// for the same reasons the write did (the lock still contended, the disk
+// still full), and letting that escape would hand the user an EACCES or a
+// lock timeout in place of the checksum-conflict message that actually
+// explains what happened (ahood-cli#132). The warning is the consolation
+// prize -- it has to name what was left behind, since nothing else will.
+function rollbackOrWarn(rollback, warning) {
+    try {
+        rollback();
+    }
+    catch {
+        console.warn(warning);
+    }
+}
 async function installMcpEntry(owner, skill, meta, buffer) {
     // Check for an existing .mcp.json collision BEFORE resolving secrets --
     // matches resolveMcpServerConfig's own "don't cost the user a prompt for
@@ -624,6 +655,11 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     // collision check specifically rather than the manifest-shape check.
     assertNoCollision(readMcpConfig(), owner, skill);
     const { serverConfig, secretNames } = await resolveMcpServerConfig(buffer);
+    // Whether a credential landed decides two things now (ahood-cli#158): the
+    // mode a brand-new .mcp.json is created with below, and the warning after.
+    // 0600 applies to creation only -- an existing file keeps its pre-existing
+    // mode (#119) and gets the readability advisory in the warning instead.
+    const wroteSecrets = secretsLanded(serverConfig, secretNames);
     // Read-modify-write under an advisory lock, mirroring lockfile.ts's own
     // writeLockfileEntry: .mcp.json sits right next to the lockfile and can
     // hold other servers' secrets, so it gets the same protection against a
@@ -637,7 +673,7 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         const fileContents = readMcpConfig();
         assertNoCollision(fileContents, owner, skill);
         fileContents.mcpServers[skill] = serverConfig;
-        writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+        writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents, wroteSecrets ? 0o600 : undefined);
     });
     const mcpKey = `${owner}/${skill}`;
     try {
@@ -648,16 +684,43 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         });
     }
     catch (error) {
-        if (!(error instanceof LockfileChecksumConflictError))
-            throw error;
         // Roll back the .mcp.json merge above under the same lock pattern --
         // re-read+delete rather than assuming nothing else changed it since.
-        withLock(MCP_CONFIG_PATH, () => {
-            const fileContents = readMcpConfig();
-            delete fileContents.mcpServers[skill];
-            writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
-        });
-        throw new Error(checksumConflictMessage(mcpKey, meta, error.existing));
+        //
+        // Runs for EVERY lockfile failure, not just a checksum conflict
+        // (ahood-cli#132) -- the same widening updateMcpEntry below already got,
+        // for the same reason. A rethrow-before-rollback here left the entry
+        // this function just merged in -- including, on the npm+npx path, the
+        // plaintext secret the user had just typed at the prompt -- sitting in
+        // .mcp.json with no lockfile pin at all. `remove` then bails at its
+        // `!dirExisted && !agentExisted && !hadLockfileEntry` check ("was not
+        // installed -- nothing to remove") before it ever reaches its .mcp.json
+        // cleanup, and a retried `add` refuses forever at assertNoCollision:
+        // the credential is removable only by hand-editing .mcp.json, and
+        // nothing tells the user it is there. Reachable from nothing worse than
+        // withLock's 5s timeout against a concurrent ahood, or an EACCES/ENOSPC
+        // on the write.
+        //
+        // Deletes, where updateMcpEntry's rollback restores: assertNoCollision
+        // has already established there was no entry under this key before this
+        // install wrote one, so there is nothing to put back. Deletes it
+        // unconditionally rather than re-fingerprinting it first the way
+        // remove.ts does -- remove is deciding about an entry of unknown age
+        // that may hold an intentional local edit, while this one was written
+        // by this same process moments ago and cannot be anyone else's work.
+        // Re-verifying here would only reintroduce the stranded-secret dead end
+        // above for whatever raced us.
+        rollbackOrWarn(() => {
+            withLock(MCP_CONFIG_PATH, () => {
+                const fileContents = readMcpConfig();
+                delete fileContents.mcpServers[skill];
+                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents, wroteSecrets ? 0o600 : undefined);
+            });
+        }, `WARNING: could not roll back ${MCP_CONFIG_PATH} after ${mcpKey}'s install failed -- its mcpServers."${skill}" entry (which may contain a secret you entered) may still be present while ${LOCKFILE_PATH} has no pin for it. Delete that entry by hand before re-running \`ahood skill add ${mcpKey}\`.`);
+        if (error instanceof LockfileChecksumConflictError) {
+            throw new Error(checksumConflictMessage(mcpKey, meta, error.existing));
+        }
+        throw error;
     }
     console.log(`Installed ${owner}/${skill}@${meta.version} into ${MCP_CONFIG_PATH} as "${skill}"`);
     // Only the npm+npx package path ever carries secrets into `env` (headers
@@ -709,6 +772,11 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
     // prompt is correct.
     const existingEnv = readMcpEntryEnv(existingOnDisk);
     const { serverConfig, secretNames } = await resolveMcpServerConfig(buffer, { existingEnv, allowNonTtyPrompt: false });
+    // Same dual use as installMcpEntry's (ahood-cli#158): the self-heal case can
+    // CREATE a .mcp.json that just resolved a secret (the carried-forward env is
+    // gone with a hand-deleted entry, so a genuine resolution just happened),
+    // and the warning needs the same fact afterward.
+    const wroteSecrets = secretsLanded(serverConfig, secretNames);
     // Read-modify-write under an advisory lock, mirroring installMcpEntry's
     // own pattern. Re-checks the fingerprint here too (not just above) since
     // arbitrary time may have passed since the pre-check -- the download, and
@@ -724,7 +792,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         }
         previousOnDisk = freshExisting;
         freshServers[skill] = serverConfig;
-        writeJsonFileAtomic(MCP_CONFIG_PATH, fresh);
+        writeJsonFileAtomic(MCP_CONFIG_PATH, fresh, wroteSecrets ? 0o600 : undefined);
     });
     try {
         writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, {
@@ -747,7 +815,12 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         // `remove` permanently refuse -- the exact dead end the comments above
         // exist to prevent, reachable from nothing worse than withLock's 5s
         // timeout against a concurrent ahood, or an EACCES/ENOSPC on the write.
-        try {
+        //
+        // The rollback itself can fail for the same reason the write did (lock
+        // still contended, disk still full), so it goes through rollbackOrWarn:
+        // the original error below is the more actionable one, and masking it
+        // with this one would hide why the update failed in the first place.
+        rollbackOrWarn(() => {
             withLock(MCP_CONFIG_PATH, () => {
                 const fileContents = readMcpConfig();
                 const mcpServers = fileContents.mcpServers;
@@ -757,16 +830,9 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
                 else {
                     mcpServers[skill] = previousOnDisk;
                 }
-                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents, wroteSecrets ? 0o600 : undefined);
             });
-        }
-        catch {
-            // The rollback can fail for the same reason the write did (lock still
-            // contended, disk still full). Warn rather than throw: the original
-            // error below is the more actionable one, and masking it with this
-            // one would hide why the update failed in the first place.
-            console.warn(`WARNING: could not roll back ${MCP_CONFIG_PATH} after ${key}'s update failed -- its mcpServers."${skill}" entry may be on the new version while ${LOCKFILE_PATH} still pins the old one. Delete that entry by hand and run \`ahood skill add ${key}\` to reinstall.`);
-        }
+        }, `WARNING: could not roll back ${MCP_CONFIG_PATH} after ${key}'s update failed -- its mcpServers."${skill}" entry may be on the new version while ${LOCKFILE_PATH} still pins the old one. Delete that entry by hand and run \`ahood skill add ${key}\` to reinstall.`);
         if (error instanceof LockfileChecksumConflictError) {
             throw new Error(checksumConflictMessage(key, meta, error.existing));
         }
@@ -799,13 +865,28 @@ export async function downloadVerifiedArchive(owner, skill, meta) {
     }
     return buffer;
 }
-export async function add(args) {
+export async function add(args, scope) {
     const spec = args[0];
     if (!spec)
         throw new UsageError(USAGE);
     const { owner, skill, version: requestedVersion } = parseOwnerSkillVersion(spec, USAGE);
     const key = `${owner}/${skill}`;
     const meta = await fetchVersionMeta(owner, skill, requestedVersion);
+    // Kind-scoped install (`ahood agent add`, `ahood mcp add`, ahood-cli#172):
+    // refused here, before the download, the lockfile and every write below.
+    // Both metadata routes report the entry's kind, so this costs no request.
+    assertKind(scope, key, meta.kind, "add", "install");
+    // A doc has no local install target (ahood-cli#175): only skill, agent and
+    // mcp entries map to a place on disk. Legacy cross-kind `ahood skill add`
+    // used to fall through to the skill path and extract a doc into
+    // .claude/skills/<owner>@<slug>/ with no SKILL.md -- not a working skill,
+    // with nothing telling the user. Refused here, on every path, before the
+    // download, the lockfile and any write. Entries with NO kind keep the
+    // legacy skill behaviour.
+    if (meta.kind === "doc") {
+        throw new UsageError(`${key} is a doc (a documentation page), which has no local install target. ` +
+            `Read it with \`ahood skill read ${key}\`, or open it with \`ahood skill view ${key} --web\`.`);
+    }
     // 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
@@ -844,10 +925,18 @@ export async function add(args) {
             writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
         }
         catch (error) {
-            if (!(error instanceof LockfileChecksumConflictError))
-                throw error;
-            rmSync(destPath, { force: true });
-            throw new Error(checksumConflictMessage(key, meta, error.existing));
+            // Widened past the checksum-conflict case with installMcpEntry's own
+            // rollback (ahood-cli#132): an agent file left behind by a lock
+            // timeout is less dangerous than a stranded mcp secret -- `remove`
+            // finds it via agentExisted even with no pin -- but "a failed install
+            // installs nothing" is the invariant worth having at all three sites,
+            // and the previous version's content is gone either way, overwritten
+            // by the writeFileSync above before the pin was ever attempted.
+            rollbackOrWarn(() => rmSync(destPath, { force: true }), `WARNING: could not remove ${destPath} after ${key}'s install failed -- it may be left behind with no ${LOCKFILE_PATH} pin. Run \`ahood skill remove ${key}\` to clean it up.`);
+            if (error instanceof LockfileChecksumConflictError) {
+                throw new Error(checksumConflictMessage(key, meta, error.existing));
+            }
+            throw error;
         }
         console.log(`Installed ${key}@${meta.version} to ${destPath}`);
         return;
@@ -867,10 +956,14 @@ export async function add(args) {
         });
     }
     catch (error) {
-        if (!(error instanceof LockfileChecksumConflictError))
-            throw error;
-        rmSync(destDir, { recursive: true, force: true });
-        throw new Error(checksumConflictMessage(key, meta, error.existing));
+        // Same widening as the agent path above (ahood-cli#132). extractFreshVersion
+        // has already cleared any previous version out of this directory, so the
+        // only thing this deletes is what this failed install just put there.
+        rollbackOrWarn(() => rmSync(destDir, { recursive: true, force: true }), `WARNING: could not remove ${destDir} after ${key}'s install failed -- it may be left behind with no ${LOCKFILE_PATH} pin. Run \`ahood skill remove ${key}\` to clean it up.`);
+        if (error instanceof LockfileChecksumConflictError) {
+            throw new Error(checksumConflictMessage(key, meta, error.existing));
+        }
+        throw error;
     }
     console.log(`Installed ${key}@${meta.version} to ${destDir}`);
 }

package/dist/commands/completion.js

@@ -1,57 +1,81 @@
-import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, COMMAND_ALIASES } from "../help.js";
+import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, AGENT_COMMANDS_HELP, MCP_COMMANDS_HELP, GROUP_COMMANDS_HELP, SNAP_COMMANDS_HELP, COMMAND_ALIASES, } from "../help.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood completion <bash|zsh|fish>";
+// Every entity noun with its own verb list, in the order completion offers
+// them. Registry nouns (skill, agent, mcp -- ahood-cli#172) come first; group
+// 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],
+    ["group", GROUP_COMMANDS_HELP],
+    ["snap", SNAP_COMMANDS_HELP],
+];
+function unique(names) {
+    return [...new Set(names.filter(Boolean))];
+}
 // Position 1 (the word right after "ahood"): every top-level command plus
-// the "skill" entity group itself.
+// every entity noun.
 function topLevelNames() {
-    return [...TOP_LEVEL_COMMANDS_HELP.map((c) => c.usage.split(" ")[1]), "skill"];
+    return unique([...TOP_LEVEL_COMMANDS_HELP.map((c) => c.usage.split(" ")[1]), ...NOUNS.map(([noun]) => noun)]);
+}
+// 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.
+function verbNames(entries) {
+    const primary = entries.map((c) => c.usage.split(" ")[2] ?? "");
+    const aliases = Object.keys(COMMAND_ALIASES).filter((alias) => primary.includes(COMMAND_ALIASES[alias]));
+    return unique([...primary, ...aliases]);
 }
-// Position 2+, once "skill" has been typed: every skill verb, plus alias
-// names (e.g. "show" for "view") so completion offers every name a user
-// might type, not just the ones with their own SKILL_COMMANDS_HELP entry.
-function skillNames() {
-    const primary = SKILL_COMMANDS_HELP.map((c) => c.usage.split(" ")[2]);
-    return [...primary, ...Object.keys(COMMAND_ALIASES)];
+// After `ahood help`: the self-skill guide plus every noun.
+function helpNames() {
+    return ["useme", ...NOUNS.map(([noun]) => noun)];
 }
 function bashCompletion() {
-    const top = topLevelNames().join(" ");
-    const skill = skillNames().join(" ");
-    return [
+    const lines = [
         "_ahood_completions() {",
         '  local cur="${COMP_WORDS[COMP_CWORD]}"',
-        `  local top_words="${top}"`,
-        `  local skill_words="${skill}"`,
-        '  if [[ "${COMP_WORDS[1]}" == "skill" && $COMP_CWORD -ge 2 ]]; then',
-        '    COMPREPLY=($(compgen -W "$skill_words" -- "$cur"))',
-        "  else",
-        '    COMPREPLY=($(compgen -W "$top_words" -- "$cur"))',
-        "  fi",
-        "}",
-        "complete -F _ahood_completions ahood",
-    ].join("\n");
+        `  local top_words="${topLevelNames().join(" ")}"`,
+        ...NOUNS.map(([noun, entries]) => `  local ${noun}_words="${verbNames(entries).join(" ")}"`),
+        `  local help_words="${helpNames().join(" ")}"`,
+    ];
+    NOUNS.forEach(([noun], i) => {
+        lines.push(`  ${i === 0 ? "if" : "elif"} [[ "\${COMP_WORDS[1]}" == "${noun}" && $COMP_CWORD -ge 2 ]]; then`);
+        lines.push(`    COMPREPLY=($(compgen -W "$${noun}_words" -- "$cur"))`);
+    });
+    lines.push('  elif [[ "${COMP_WORDS[1]}" == "help" && $COMP_CWORD -eq 2 ]]; then');
+    lines.push('    COMPREPLY=($(compgen -W "$help_words" -- "$cur"))');
+    lines.push("  else");
+    lines.push('    COMPREPLY=($(compgen -W "$top_words" -- "$cur"))');
+    lines.push("  fi");
+    lines.push("}");
+    lines.push("complete -F _ahood_completions ahood");
+    return lines.join("\n");
 }
 function zshCompletion() {
-    const top = topLevelNames().join(" ");
-    const skill = skillNames().join(" ");
-    return [
+    const lines = [
         "#compdef ahood",
-        "local -a top_cmds skill_cmds",
-        `top_cmds=(${top})`,
-        `skill_cmds=(${skill})`,
+        `local -a top_cmds ${NOUNS.map(([noun]) => `${noun}_cmds`).join(" ")} help_cmds`,
+        `top_cmds=(${topLevelNames().join(" ")})`,
+        ...NOUNS.map(([noun, entries]) => `${noun}_cmds=(${verbNames(entries).join(" ")})`),
+        `help_cmds=(${helpNames().join(" ")})`,
         "case $words[2] in",
-        "  skill)",
-        '    _describe "skill command" skill_cmds',
-        "    ;;",
-        "  *)",
-        '    _describe "command" top_cmds',
-        "    ;;",
-        "esac",
-    ].join("\n");
+    ];
+    for (const [noun] of NOUNS) {
+        lines.push(`  ${noun})`);
+        lines.push(`    _describe "${noun} command" ${noun}_cmds`);
+        lines.push("    ;;");
+    }
+    lines.push("  help)", '    _describe "help topic" help_cmds', "    ;;");
+    lines.push("  *)", '    _describe "command" top_cmds', "    ;;", "esac");
+    return lines.join("\n");
 }
 function fishCompletion() {
     return [
         ...topLevelNames().map((name) => `complete -c ahood -n "__fish_use_subcommand" -a "${name}"`),
-        ...skillNames().map((name) => `complete -c ahood -n "__fish_seen_subcommand_from skill" -a "${name}"`),
+        ...NOUNS.flatMap(([noun, entries]) => verbNames(entries).map((name) => `complete -c ahood -n "__fish_seen_subcommand_from ${noun}" -a "${name}"`)),
+        ...helpNames().map((name) => `complete -c ahood -n "__fish_seen_subcommand_from help" -a "${name}"`),
     ].join("\n");
 }
 // Position-aware command-name completion (not per-command flags) -- still

package/dist/commands/diff.js

@@ -2,6 +2,7 @@ import { createPatch } from "diff";
 import { fetchVersionMeta, downloadVerifiedArchive, extractSingleFileContent } from "./add.js";
 import { parseOwnerSkill, SEMVER_RE } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill diff <owner>/<skill> <versionA> <versionB> [--json]";
 // Both versions must be explicit semver here, unlike `add`'s
 // parseOwnerSkillVersion which lets "latest" default the version -- a diff
@@ -45,7 +46,7 @@ function diffManifests(manifestA, manifestB, skillMdChanged) {
     }
     return { added, removed, changed };
 }
-export async function diff(args) {
+export async function diff(args, scope) {
     const jsonOutput = args.includes("--json");
     const positional = args.filter((a) => !a.startsWith("--"));
     const [spec, versionA, versionB] = positional;
@@ -58,6 +59,8 @@ export async function diff(args) {
         fetchVersionMeta(owner, skill, versionA),
         fetchVersionMeta(owner, skill, versionB),
     ]);
+    // Both version responses carry the entry's kind; checked before either archive is downloaded.
+    assertKind(scope, `${owner}/${skill}`, metaA.kind, "diff", "diff");
     const [contentA, contentB] = await Promise.all([
         fetchSkillMdContent(owner, skill, metaA),
         fetchSkillMdContent(owner, skill, metaB),