@ahood/cli 0.8.8 → 0.10.0

package/dist/commands/whoami.js

@@ -4,14 +4,22 @@ import { resolveToken } from "../credentials.js";
 // still authenticate?", which is already settled by the time this runs.
 // A failure here (network blip, an otherwise-valid token hitting a 500 on
 // this specific route, etc.) must never turn a successful auth check into a
-// command failure -- so every error is swallowed and callers fall back to
-// the plain "Authenticated..." message instead.
+// command failure -- so most errors are swallowed and callers fall back to
+// the plain "Authenticated..." message instead. The one exception is a 404,
+// which carries a `provisioning` flag worth reading rather than discarding:
+// see ProfileOutcome above.
 async function fetchProfile() {
     try {
-        return await apiJson("/api/v1/profile");
+        const profile = await apiJson("/api/v1/profile");
+        return { profile };
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error instanceof ApiError && error.status === 404) {
+            const body = error.body;
+            const provisioning = !!body && typeof body === "object" && body.provisioning === true;
+            return { profileStatus: provisioning ? "provisioning" : "not_found" };
+        }
+        return {};
     }
 }
 // Pure auth-status check: no console output, no process.exitCode -- callers
@@ -38,13 +46,13 @@ export async function checkAuth() {
         await apiJson("/api/v1/auth/tokens");
         // A session-backed caller (only reachable if this ever runs against a
         // cookie-bearing client) -- the token list came back.
-        const profile = await fetchProfile();
-        return { authenticated: true, mode: "session", profile };
+        const profileOutcome = await fetchProfile();
+        return { authenticated: true, mode: "session", ...profileOutcome };
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 403) {
-            const profile = await fetchProfile();
-            return { authenticated: true, mode: "token", profile };
+            const profileOutcome = await fetchProfile();
+            return { authenticated: true, mode: "token", ...profileOutcome };
         }
         if (error instanceof ApiError && error.status === 401) {
             return { authenticated: false, reason: "invalid_token" };
@@ -89,6 +97,39 @@ export async function whoami(args = []) {
         process.exitCode = 1;
         return;
     }
+    const asToken = result.mode === "token";
+    if (result.profileStatus === "not_found") {
+        // Distinct from "provisioning" below: the server saw a 404 for this
+        // caller's profile and did NOT flag it as the expected provisioning
+        // window (ahood#340) -- authentication is genuinely fine (we got this
+        // far), but something about the account's profile is actually wrong
+        // rather than merely not-created-yet. Exit 5 ("Not found"), the same
+        // code exitCodeFor() already gives an ApiError 404 elsewhere -- this is
+        // that same class of failure, just decided locally since checkAuth()
+        // never throws.
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: true, mode: result.mode, profileStatus: "not_found" }));
+        else {
+            console.error(`Authenticated${asToken ? " with a personal API token" : ""}, but no profile was found for this account -- ` +
+                "this is not the usual just-signed-up delay, so something is actually wrong. Try `ahood login` again, and " +
+                "if it keeps happening, contact support.");
+        }
+        process.exitCode = 5;
+        return;
+    }
+    if (result.profileStatus === "provisioning") {
+        // The expected, self-resolving window between signup and the profile
+        // row being created (ahood#336, ahood#340) -- not a failure of any kind,
+        // so this stays exit 0. "Refresh this page" (the web copy's hint) makes
+        // no sense here; re-running the command is the CLI-native equivalent.
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: true, mode: result.mode, profileStatus: "provisioning" }));
+        else {
+            console.log(`Authenticated${asToken ? " with a personal API token" : ""}. Your account is still being set up -- ` +
+                "this finishes on its own and needs nothing from you. Run `ahood whoami` again in a bit to see your profile.");
+        }
+        return;
+    }
     if (wantsJson) {
         console.log(JSON.stringify({ authenticated: true, mode: result.mode, ...result.profile }));
         return;

package/dist/flags.js

@@ -11,22 +11,114 @@ import { UsageError } from "./usage-error.js";
 //                    value, verbatim, even if it starts with "--" -- this is
 //                    the unambiguous escape hatch for values that genuinely
 //                    start with "--" (e.g. a tagline like "--fast and cheap").
+// A repeated value flag is refused rather than resolved. `flagValue` used to
+// return the FIRST match and stop, while the stripping below skipped EVERY
+// occurrence's neighbour, so `snap search foo --tags a --tags bar` searched for
+// "foo" tagged "a" and deleted "bar" from the query outright -- the user got
+// results for a command they did not type, at exit 0 (ahood-cli#136). Both
+// last-wins and first-wins are silent guesses about which fragment of a
+// command reassembled from shell history is the stale one; the CLI already
+// refuses flags it doesn't recognize, and refusing here is the only option that
+// cannot discard a value the user typed. The cost is one retry with the
+// duplicate deleted, which is also the edit the user has to make anyway.
+function assertFirstOccurrence(seen, flag) {
+    if (seen.has(flag)) {
+        throw new UsageError(`${flag} given more than once. Pass it once -- repeating it would silently discard one of the values` +
+            // Safe to say unconditionally for --tags: every --tags in this CLI
+            // (publish/edit/snap create/list/search) is one comma-separated value,
+            // and "it accumulates" is the misconception that produces the repeat.
+            (flag === "--tags" ? `; pass multiple tags as one comma-separated value (--tags a,b)` : "") +
+            `.`);
+    }
+    seen.add(flag);
+}
 export function flagValue(args, flag) {
     const prefix = `${flag}=`;
+    const seen = new Set();
+    let found;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg.startsWith(prefix)) {
-            return arg.slice(prefix.length);
+            assertFirstOccurrence(seen, flag);
+            found = arg.slice(prefix.length);
+            continue;
         }
         if (arg === flag) {
             const value = args[i + 1];
             if (value === undefined || value.startsWith("--")) {
                 throw new UsageError(`${flag} requires a value.`);
             }
-            return value;
+            assertFirstOccurrence(seen, flag);
+            found = value;
+        }
+    }
+    return found;
+}
+// Returns the tokens left over after stripping the flags a command declares:
+// `booleanFlags` stand alone (--json), `valueFlags` consume the following token
+// and also accept the --flag=value form. Whatever remains is something the
+// command does NOT accept -- an unrecognized "--" flag or a stray positional --
+// and it's the caller's job to reject it (or, for a query/id command, to
+// interpret it as the positional).
+//
+// Lives here rather than inline in each command because hand-rolling this check
+// per command is exactly how `snap list` ended up with no check at all while
+// its sibling `snap search` had one, so `snap list --tag ci` (singular typo)
+// issued an UNFILTERED request and printed every snap as though it were the
+// filtered set (ahood-cli#135). parseSearchQuery below is now a caller of this
+// helper rather than a second copy of it (folded in by ahood-cli#136, whose bug
+// existed in both copies); tagsSnap still carries its own inline copy -- fold it
+// in when the queued snap-parsing fixes (ahood-cli#137/#138) next touch it,
+// rather than growing a third variant again.
+export function unrecognizedArgs(args, booleanFlags, valueFlags) {
+    return unrecognizedIndices(args, booleanFlags, valueFlags).map((i) => args[i]);
+}
+// The same stripping rules as unrecognizedArgs, reporting WHERE the leftovers
+// sat rather than what they were -- and the primitive the two share, so there
+// is still exactly one copy of those rules (the whole point of #135's helper;
+// a second hand-rolled variant is the mistake it exists to stop).
+//
+// `snap create` needs the positions, not just the tokens: its leftovers are the
+// words of a freeform note, so "starts with --" is the only thing it can reject
+// outright, and the one remaining signal that a bare token was misplaced is that
+// the leftovers sit on BOTH sides of a flag the command consumed -- which is
+// precisely `snap create "note" --tags deploy bugfix` folding "bugfix" into the
+// note body (ahood-cli#134). Positions are the only way to see that gap.
+export function unrecognizedIndices(args, booleanFlags, valueFlags) {
+    const indices = [];
+    const seen = new Set();
+    // Which index (if any) the value flag just seen actually consumed. The test
+    // used to be `valueFlags.includes(args[i - 1])`, which stripped the neighbour
+    // of EVERY occurrence -- so a repeated --tags ate a word nothing had read
+    // (ahood-cli#136). Tracking the consuming occurrence means exactly one token
+    // per accepted flag disappears, and assertFirstOccurrence refuses the repeat
+    // with the same message flagValue gives, so a caller that reaches this helper
+    // first can't report the duplicate as "Unknown flag: --tags" instead.
+    let consumedAt = -1;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (i === consumedAt)
+            continue;
+        if (booleanFlags.includes(arg))
+            continue;
+        if (valueFlags.includes(arg)) {
+            assertFirstOccurrence(seen, arg);
+            // Same swallow-protection as flagValue: a following "--" token is not
+            // this flag's value, it's the next flag, so leave it to be judged on its
+            // own (flagValue throws "requires a value" for it first in every caller).
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("--"))
+                consumedAt = i + 1;
+            continue;
+        }
+        const equalsForm = valueFlags.find((f) => arg.startsWith(`${f}=`));
+        if (equalsForm !== undefined) {
+            assertFirstOccurrence(seen, equalsForm);
+            continue;
         }
+        indices.push(i);
     }
-    return undefined;
+    return indices;
 }
 // Shared by every "<verb> <query> [--json] [--limit <n>]" command (skill
 // search, snap search) -- factored out after this exact logic was
@@ -43,11 +135,11 @@ export function flagValue(args, flag) {
 // a flag that command doesn't implement instead of silently ignoring it and
 // returning unfiltered results.
 export function parseSearchQuery(args, usage, valueFlags = []) {
-    const stripped = ["--limit", ...valueFlags];
-    const queryParts = args.filter((a, i) => a !== "--json" &&
-        !stripped.includes(a) &&
-        !stripped.some((f) => a.startsWith(`${f}=`)) &&
-        !stripped.includes(args[i - 1]));
+    // Delegated to unrecognizedArgs rather than re-filtering here: this was the
+    // second hand-rolled copy of those stripping rules, and it carried the same
+    // repeated-flag bug (ahood-cli#136) that the first one did -- which is the
+    // duplication hazard #135's helper was extracted to end.
+    const queryParts = unrecognizedArgs(args, ["--json"], ["--limit", ...valueFlags]);
     const unknownFlag = queryParts.find((a) => a.startsWith("--"));
     if (unknownFlag)
         throw new UsageError(`Unknown flag: ${unknownFlag}\n${usage}`);

package/dist/help.js

@@ -1,3 +1,27 @@
+// Canonical command list for terminal --help output. Kept in sync by hand
+// with cli/README.md's table and app/docs/page.tsx's COMMANDS array (three
+// copies of the same list, none of which can literally import from this
+// file -- README.md is plain markdown and the docs page is a separate
+// Next.js app) -- a comment in each of those two places points back here so
+// a future command addition doesn't update only one.
+//
+// The command surface is split into two tiers, gh-style:
+//   - TOP_LEVEL_COMMANDS_HELP: account/auth-scoped commands that stay flat
+//     (login, logout, whoami, token, completion) -- same reasoning
+//     `gh auth login` isn't `gh account login`.
+//   - SKILL_COMMANDS_HELP: every registry verb, reached as `ahood skill
+//     <verb>` -- legacy and cross-kind in this release (ahood-cli#172).
+//   - AGENT_COMMANDS_HELP / MCP_COMMANDS_HELP: the same verbs, kind-scoped,
+//     generated from one template (registryCommandsHelp); MCP's list also
+//     carries `ahood mcp` / `ahood mcp serve`, the local stdio server.
+//   - GROUP_COMMANDS_HELP / SNAP_COMMANDS_HELP: the other entity nouns.
+//
+// `summary` is a genuinely one-sentence blurb used only by the top-level
+// `ahood --help` / `ahood skill --help` listings. `desc` is the full
+// (possibly multi-sentence) description rendered in full by `ahood help
+// <command>` / `ahood skill <verb> --help`. Keep `summary` self-contained --
+// it must not depend on the reader having also seen `desc`.
+import { KINDS } from "./kind-info.js";
 export const TOP_LEVEL_COMMANDS_HELP = [
     {
         usage: "ahood login",
@@ -27,12 +51,15 @@ export const TOP_LEVEL_COMMANDS_HELP = [
         examples: ["ahood completion bash >> ~/.bashrc"],
     },
     {
-        usage: "ahood mcp",
-        summary: "Start an MCP server exposing read-only skill commands as tools over stdio.",
-        desc: "Start a Model Context Protocol server over stdio, exposing skill_search, skill_view, skill_read, " +
-            "skill_versions, skill_list, skill_outdated, and whoami as MCP tools -- the same data ahood's --json " +
-            "commands already return, reachable as typed tool calls instead of parsed CLI output. Meant to be " +
-            "launched by an MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively.",
+        usage: "ahood help useme",
+        summary: "Print the bundled ahood SKILL.md for an AI agent -- raw, offline, no login needed.",
+        desc: "Print the ahood self-skill bundled with this exact CLI version: a complete SKILL.md teaching an AI agent " +
+            "(or a human) when and how to use ahood. Stdout is the raw file and nothing else -- no banner, no colors -- " +
+            "so it can be pasted into an agent's context, redirected into a file, or read directly by an agent with " +
+            "shell access. Works offline and without credentials, and never writes to your project. It is not the " +
+            "same as `ahood skill add alexkay/ahood`, which installs the registry-published copy as a separate, " +
+            "pinned project skill.",
+        examples: ["ahood help useme", "ahood help useme > ahood-SKILL.md"],
     },
 ];
 export const SKILL_COMMANDS_HELP = [
@@ -206,6 +233,182 @@ export const SKILL_COMMANDS_HELP = [
         ],
     },
 ];
+// Kind-scoped registry verbs (ahood-cli#172): `ahood agent <verb>` and
+// `ahood mcp <verb>` take the same verbs as `ahood skill <verb>`, run by the
+// same handlers, but strictly for their own kind -- a target of another kind
+// is refused before any side effect. Generated from one template per verb
+// 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.
+function registryCommandsHelp(kind) {
+    const info = KINDS[kind];
+    const n = kind === "agent" ? "<agent>" : "<server>";
+    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 kindRefusal = `Refused, before anything else happens, when the target is not ${a} ${label}.`;
+    return [
+        {
+            usage: `${p} search <query> [--json] [--limit <n>]`,
+            summary: `Search published ${plural}.`,
+            desc: `Search published ${plural} only (the registry's ?kind=${kind} filter). Same output and --json shape as \`ahood skill search\`.`,
+            flags: ["--json        Emit the raw result objects instead of formatted lines.", "--limit <n>   Cap the number of results."],
+            examples: [`${p} search github`],
+        },
+        {
+            usage: `${p} view <owner>/${n} [--json] [--web]`,
+            summary: `Show a single ${label}'s details without installing it (alias: ${p} show).`,
+            desc: `Show a single ${label}'s details without installing it. Alias: ${p} show. ${kindRefusal}`,
+            flags: ["--json   Emit the raw object instead of formatted lines.", "--web    Open its page in your browser instead of printing."],
+        },
+        {
+            usage: `${p} read <owner>/${n} [--json]`,
+            summary: `Print a published ${label}'s ${doc}, without installing it.`,
+            desc: `Print the ${doc} of a published ${label} verbatim, without installing it -- read it before you add it. ${kindRefusal}`,
+            flags: ["--json    Emit {version, content} as a single line instead of the raw content."],
+            examples: [`${p} read ${ex}`],
+        },
+        {
+            usage: `${p} versions <owner>/${n} [--json]`,
+            summary: `List a ${label}'s published-version history.`,
+            desc: `List a ${label}'s published-version history: version, changelog, size, and publish date. ${kindRefusal}`,
+            flags: ["--json    Emit the raw version objects instead of formatted text."],
+        },
+        {
+            usage: `${p} diff <owner>/${n} <versionA> <versionB> [--json]`,
+            summary: `Show what changed between two published versions of ${a} ${label}.`,
+            desc: `Show what changed between two published versions, exactly like \`ahood skill diff\`. Both versions must be explicit semver. ${kindRefusal}`,
+            flags: ["--json    Emit {skillmd_diff, manifest: {added, removed, changed}} instead of formatted text."],
+        },
+        {
+            usage: `${p} list [--json]`,
+            summary: `List your own ${plural}, public and private.`,
+            desc: `List your own ${plural}, public and private. The registry returns every entry you own; this keeps only the ${kind} ones ` +
+                "(an entry with no kind in the response is left out, with a warning on stderr). --json keeps `ahood skill list --json`'s shape.",
+            flags: ["--json    Emit the raw objects instead of formatted lines."],
+        },
+        {
+            usage: `${p} add <owner>/${n}[@version]`,
+            summary: `Install ${a} ${label} into ${info.installsTo}, pinned in the lockfile.`,
+            desc: `Install ${a} ${label} into ${info.installsTo}, pinned in .claude/skills.lock.json. ` +
+                (kind === "mcp" ? "Prompts for any secret environment variables its server.json declares that aren't already set. " : "") +
+                `Refused before anything is downloaded or written when the target is not ${a} ${label}.`,
+            examples: [`${p} add ${ex}`, `${p} add ${ex}@1.2.0`],
+        },
+        {
+            usage: `${p} update [<owner>/${n} ...] [--dry-run] [--json]`,
+            summary: `Move ${label} pins forward to the latest version.`,
+            desc: `Move lockfile pins forward to the latest version. With no argument, considers only the installed ${plural} ` +
+                `in this project -- other kinds' pins are left alone. A named target that is not ${a} ${label} is refused and counted as a failure.`,
+            flags: [
+                "--dry-run   Preview current vs. latest version (and the changelog) without installing anything.",
+                "--json      With --dry-run, emit structured preview objects instead of a formatted table.",
+            ],
+        },
+        {
+            usage: `${p} outdated [<owner>/${n} ...] [--json]`,
+            summary: `Read-only staleness check for installed ${plural}.`,
+            desc: `Read-only staleness check -- equivalent to \`${p} update --dry-run\`. With no argument, checks only the installed ${plural}.`,
+            flags: ["--json    Emit structured preview objects instead of a formatted table."],
+        },
+        {
+            usage: `${p} remove <owner>/${n} [--yes]`,
+            summary: `Uninstall and unpin ${a} ${label} (local only, prompts unless --yes is passed).`,
+            desc: `Uninstall and unpin ${a} ${label} from this project (local only). Refused, before the prompt and before anything is deleted, ` +
+                `when the install is another kind; the kind is read from the project's own files, and from the registry only when they can't tell.`,
+            flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+        },
+        {
+            usage: `${p} edit <owner>/${n} [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]`,
+            summary: `Update ${a} ${label} you own, changing only the flags you pass.`,
+            desc: `Update ${a} ${label} you own; same flags as \`ahood skill edit\`. ${kindRefusal}`,
+            flags: [
+                "--tagline <text>              Short one-line description.",
+                "--tags <comma,separated>      Replaces the tag list.",
+                "--license <id>                An SPDX license identifier, e.g. MIT.",
+                "--visibility public|private   Who can see and install it.",
+                "--homepage <url>              Homepage URL.",
+                "--repository <url>            Source repository URL.",
+            ],
+        },
+        {
+            usage: `${p} unpublish <owner>/${n}[@version] [--yes]`,
+            summary: `Delete ${a} ${label} from the registry for every consumer, or yank one version (prompts unless --yes is passed).`,
+            desc: `Without @version: delete ${a} ${label} from the registry for every consumer. With @version: yank that version. ` +
+                `Refused before the prompt when the target is not ${a} ${label}.`,
+            flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+        },
+        { usage: `${p} star <owner>/${n}`, summary: `Star ${a} ${label}.`, desc: `Star ${a} ${label}. ${kindRefusal}` },
+        { usage: `${p} unstar <owner>/${n}`, summary: `Remove your star from ${a} ${label}.`, desc: `Remove your star from ${a} ${label}. ${kindRefusal}` },
+        {
+            usage: `${p} share <owner>/${n} --group <group>`,
+            summary: `Share ${a} ${label} you own with a group, without changing its visibility.`,
+            desc: `Share ${a} ${label} you own with a group you belong to. ${kindRefusal}`,
+            flags: ["--group <group>   The group's slug (from `ahood group list`)."],
+        },
+        {
+            usage: `${p} unshare <owner>/${n} --group <group>`,
+            summary: `Stop sharing ${a} ${label} you own with a group.`,
+            desc: `Stop sharing ${a} ${label} you own with a group. ${kindRefusal}`,
+            flags: ["--group <group>   The group's slug."],
+        },
+        {
+            usage: `${p} init [name]`,
+            summary: `Scaffold a new ${label} folder with a minimal, valid ${doc}.`,
+            desc: `Scaffold a minimal ${doc} that passes the registry's publish validation: ./<name>/${doc} with a name, or ./${doc} without. ` +
+                (kind === "mcp"
+                    ? "The starter points at a reserved example.com URL, so it can never install anyone's real server until you edit it. "
+                    : "") +
+                `Refuses to overwrite an existing ${doc}, or to add one to a folder that already holds another kind's root document. ` +
+                "Names are slug-normalized and must stay inside the current directory.",
+            examples: [`${p} init ${ex.split("/")[1]}`, `${p} init`],
+        },
+        {
+            usage: `${p} publish <owner>/${n}@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]`,
+            summary: `Publish a new version of ${a} ${label} from a folder containing ${doc}, creating it first if it doesn't exist yet.`,
+            desc: `Publish a new version from a folder containing ${doc}; the kind is implied, and a contradictory --kind is refused. ` +
+                `If the entry already exists as another kind, this stops before anything is packed or uploaded. ` +
+                "If it doesn't exist yet, it is created first -- pass --name for that. Otherwise the same flags and --json output as `ahood skill publish`.",
+            flags: [
+                "--path <dir>                  Folder to publish (default: the current directory).",
+                "--name <text>                 Required only when creating the entry on this publish.",
+                "--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"}"`],
+        },
+    ];
+}
+export const AGENT_COMMANDS_HELP = registryCommandsHelp("agent");
+// `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;
+// with a registry verb it manages mcp-kind registry entries (server.json
+// manifests). Both are listed here so `ahood mcp --help` explains both.
+export const MCP_SERVE_HELP = [
+    {
+        usage: "ahood mcp serve",
+        summary: "Start the local, read-only ahood MCP server over stdio (preferred spelling).",
+        desc: "Start a Model Context Protocol server over stdio, exposing skill_search, skill_view, skill_read, " +
+            "skill_versions, skill_list, skill_outdated, and whoami as MCP tools -- the same data ahood's --json " +
+            "commands already return, reachable as typed tool calls instead of parsed CLI output. Meant to be " +
+            "launched by an MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively. " +
+            "Read-only by design. This is not the hosted registry MCP endpoint (https://ahood.vercel.app/api/mcp), which " +
+            "is a separate server with write tools.",
+        examples: ['claude mcp add ahood -- ahood mcp serve', "npx @ahood/cli@latest mcp serve"],
+    },
+    {
+        usage: "ahood mcp",
+        summary: "Same as `ahood mcp serve`, kept byte-for-byte so existing MCP host configs keep working.",
+        desc: "With no arguments at all, `ahood mcp` starts the same stdio server as `ahood mcp serve` -- nothing is printed " +
+            "to stdout before the protocol starts, and no login or network is needed to start it. Any other first word must " +
+            "be `serve`, `--help`, or a registry verb below; anything unrecognized fails with usage instead of starting a server.",
+    },
+];
+export const MCP_COMMANDS_HELP = [...MCP_SERVE_HELP, ...registryCommandsHelp("mcp")];
 // Every group-entity verb, all reached as `ahood group <verb>` -- mirrors
 // SKILL_COMMANDS_HELP above, just for the "Groups" feature: private groups,
 // shareable invite links, and sharing your own skills with a group without
@@ -283,14 +486,17 @@ export const SNAP_COMMANDS_HELP = [
         summary: "Capture a new private snap, from an argument or piped stdin.",
         desc: "Capture a new private snap. Pass the content as an argument, or omit it and pipe content on stdin " +
             "(e.g. `echo \"...\" | ahood snap create`, or a piped heredoc) -- useful for capturing a whole session's " +
-            "worth of freeform text at once. Prints the new snap's id on success.",
+            "worth of freeform text at once. Prints the new snap's id on success. An unrecognized flag is refused " +
+            "rather than folded into the note; pass content that itself starts with `--` after a bare `--`.",
         flags: [
             "--tags <comma,separated>   Attach tags to the new snap.",
             "--json                     Emit {id, created_at} instead of just the bare id.",
+            "--                         End of options: everything after it is content, verbatim.",
         ],
         examples: [
             'ahood snap create "Debugged the flaky CI step, root cause was a race in the cache key." --tags deploy,bugfix',
             'echo "..." | ahood snap create',
+            'ahood snap create -- "--json broke the parser"',
         ],
     },
     {
@@ -346,13 +552,24 @@ export const SNAP_COMMANDS_HELP = [
         flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
     {
-        usage: "ahood snap tags <id> [tag1,tag2,...] [--json]",
-        summary: "Replace a snap's tags (omit the tag list, or pass an empty one, to clear all tags).",
-        desc: "Replace the full set of tags on a snap -- this is not a merge, so any existing tags not listed are " +
-            "dropped. Omitting the tag list entirely, or passing an empty string, clears all tags. No confirmation " +
-            "prompt: unlike remove/unshare this only touches metadata, never the snap's content or shareability.",
-        flags: ["--json    Emit {id, tags} instead of a plain-text summary."],
-        examples: ["ahood snap tags snap_123 deploy,bugfix", 'ahood snap tags snap_123 ""'],
+        usage: "ahood snap tags <id> [tag ...] [--clear] [--json]",
+        summary: "Print a snap's tags, or replace them with the tags given.",
+        desc: "With no tag list, prints the snap's current tags and changes nothing. With a tag list, replaces the " +
+            "full set -- this is not a merge, so any existing tags not listed are dropped. Tags may be given as " +
+            "separate arguments, comma-separated, or both; quote a tag that contains a space. Clearing every tag " +
+            "is explicit: pass --clear or an empty string. Each tag prints quoted, so one multi-word tag never " +
+            "looks like two. No confirmation prompt: unlike remove/unshare this only touches metadata, never the " +
+            "snap's content or shareability, and the tags it replaces can be read back first.",
+        flags: [
+            "--clear   Remove every tag from the snap.",
+            "--json    Emit {id, tags} instead of a plain-text summary.",
+        ],
+        examples: [
+            "ahood snap tags snap_123",
+            "ahood snap tags snap_123 deploy bugfix",
+            "ahood snap tags snap_123 deploy,bugfix",
+            "ahood snap tags snap_123 --clear",
+        ],
     },
 ];
 // Exported so other consumers of the command list (e.g. shell completion) can
@@ -366,6 +583,8 @@ export const COMMAND_ALIASES = { show: "view" };
 // only has to be added here once, not re-special-cased in both places.
 const ENTITY_COMMANDS_HELP = {
     skill: SKILL_COMMANDS_HELP,
+    agent: AGENT_COMMANDS_HELP,
+    mcp: MCP_COMMANDS_HELP,
     group: GROUP_COMMANDS_HELP,
     snap: SNAP_COMMANDS_HELP,
 };
@@ -487,12 +706,58 @@ export function formatSkillHelp() {
     return [
         "ahood skill -- manage skills in the ahood registry",
         "",
+        "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).",
+        "A future major version will make `ahood skill` skills-only.",
+        "",
         "Commands:",
         ...lines,
         "",
         "Run `ahood skill <command> --help` for a single command's flags and examples.",
     ].join("\n");
 }
+// `ahood agent --help` / `ahood mcp --help` -- kind-scoped registry verbs.
+function formatRegistryKindHelp(header, intro, entries, noun) {
+    const lines = formatCommandTable(entries.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
+    return [
+        header,
+        "",
+        ...intro,
+        "",
+        "Commands:",
+        ...lines,
+        "",
+        `Run \`ahood ${noun} <command> --help\` for a single command's flags and examples.`,
+    ].join("\n");
+}
+export function formatAgentHelp() {
+    return formatRegistryKindHelp("ahood agent -- manage agent definitions (AGENT.md) in the ahood registry", [
+        "Every verb here acts on agents only: a target of another kind is refused before anything",
+        "is downloaded, prompted for, written, or sent. Installs land in .claude/agents/<owner>@<agent>.md.",
+    ], AGENT_COMMANDS_HELP, "agent");
+}
+export function formatMcpHelp() {
+    return formatRegistryKindHelp("ahood mcp -- the local MCP server, and MCP server manifests (server.json) in the ahood registry", [
+        "Two meanings, told apart by the first word:",
+        "  ahood mcp / ahood mcp serve   start this CLI's local, read-only MCP server over stdio",
+        "                                (what MCP host configs launch; `serve` is the preferred spelling)",
+        "  ahood mcp <verb>              manage mcp-kind registry entries (installs merge into .mcp.json)",
+        "Neither is the hosted registry MCP endpoint, https://ahood.vercel.app/api/mcp.",
+        "Registry verbs act on MCP server manifests only; another kind is refused before any side effect.",
+    ], MCP_COMMANDS_HELP, "mcp");
+}
+// 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 formatKindHelp(noun) {
+    if (noun === "agent")
+        return formatAgentHelp();
+    if (noun === "mcp")
+        return formatMcpHelp();
+    return formatSkillHelp();
+}
 // `ahood group --help` -- the group-level listing for every group verb.
 export function formatGroupHelp() {
     const lines = formatCommandTable(GROUP_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
@@ -523,7 +788,11 @@ export function formatSnapHelp() {
 // entity command lists.
 export function formatHelp() {
     const skillGroupUsage = "ahood skill <command>";
-    const skillGroupSummary = "Search, install, and publish skills -- run `ahood skill --help` for the full list.";
+    const skillGroupSummary = "Search, install, and publish skills (legacy: also any other kind) -- run `ahood skill --help` for the full list.";
+    const agentGroupUsage = "ahood agent <command>";
+    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 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>";
@@ -531,6 +800,8 @@ export function formatHelp() {
     const lines = formatCommandTable([
         ...TOP_LEVEL_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })),
         { usage: skillGroupUsage, summary: skillGroupSummary },
+        { usage: agentGroupUsage, summary: agentGroupSummary },
+        { usage: mcpGroupUsage, summary: mcpGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
         { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
@@ -542,11 +813,17 @@ export function formatHelp() {
         "  ahood skill search <something>",
         "  ahood skill add <owner>/<skill>",
         "",
+        "Use ahood with an AI agent:",
+        "  ahood help useme    Print a complete SKILL.md teaching an agent how to use ahood.",
+        "                      Raw stdout, offline, no login -- paste it to an agent, or let an",
+        "                      agent with a shell run it.",
+        "",
         "Commands:",
         ...lines,
         "",
         "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 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.",