@mnemom/mnemom 0.15.1-next.1 → 0.16.0

package/dist/commands/skills.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `mnemom skills` (MNE-1324) — discover the CLI's skill surface.
+ *
+ *   mnemom skills            list available + planned skills (default)
+ *   mnemom skills list       (same)
+ *   mnemom skills describe <name>   usage + details for one skill
+ *
+ * Reads the registry (`lib/skills.ts`) — the single source of truth — so the
+ * discoverable surface never drifts from the actual commands. Both subcommands
+ * support `--json`.
+ */
+export declare function skillsListCommand(opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function skillsDescribeCommand(name: string, opts: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/skills.js

@@ -0,0 +1,61 @@
+/**
+ * `mnemom skills` (MNE-1324) — discover the CLI's skill surface.
+ *
+ *   mnemom skills            list available + planned skills (default)
+ *   mnemom skills list       (same)
+ *   mnemom skills describe <name>   usage + details for one skill
+ *
+ * Reads the registry (`lib/skills.ts`) — the single source of truth — so the
+ * discoverable surface never drifts from the actual commands. Both subcommands
+ * support `--json`.
+ */
+import chalk from "chalk";
+import { fmt } from "../lib/format.js";
+import { listSkills, getSkill } from "../lib/skills.js";
+function statusBadge(s) {
+    return s.status === "available"
+        ? fmt.badge("available", "green")
+        : fmt.badge("planned", "yellow");
+}
+export async function skillsListCommand(opts) {
+    const skills = listSkills();
+    if (opts.json) {
+        // Plain JSON — machine-readable regardless of TTY (fmt.json is colorized).
+        console.log(JSON.stringify({ skills }, null, 2));
+        return;
+    }
+    console.log(fmt.header("Mnemom CLI skills"));
+    console.log(fmt.dim("  Zero-install — run any skill with: npx @mnemom/mnemom@latest <skill>\n"));
+    for (const s of skills) {
+        console.log(`  ${chalk.bold(s.name)} ${statusBadge(s)}`);
+        console.log(`    ${s.summary}`);
+    }
+    console.log(`\n${fmt.dim("  Details: mnemom skills describe <name>")}`);
+}
+export async function skillsDescribeCommand(name, opts) {
+    const skill = getSkill(name);
+    if (!skill) {
+        // Throw — index.ts's action wrapper prints "Error: …" and exits 1. Keeps the
+        // handler pure/testable (no process.exit) and gives a discoverable hint.
+        const known = listSkills()
+            .map((s) => s.name)
+            .join(", ");
+        throw new Error(`Unknown skill "${name}". Run \`mnemom skills list\` — known skills: ${known}.`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(skill, null, 2));
+        return;
+    }
+    console.log(fmt.header(`${skill.name}  ${skill.status === "available" ? "(available)" : "(planned)"}`));
+    console.log(`  ${skill.summary}\n`);
+    console.log(fmt.label("  Usage:", skill.usage));
+    console.log(`\n  ${skill.description.replace(/\n/g, "\n  ")}`);
+    if (skill.examples && skill.examples.length > 0) {
+        console.log(fmt.section("  Examples"));
+        for (const ex of skill.examples)
+            console.log(`  ${chalk.cyan(ex)}`);
+    }
+    if (skill.status === "planned" && skill.ref) {
+        console.log(`\n${fmt.dim(`  Planned — tracked as ${skill.ref}.`)}`);
+    }
+}

package/dist/index.js

@@ -20,6 +20,7 @@ import { apiKeyListCommand, apiKeyCreateCommand, apiKeyRotateCommand, apiKeyRevo
 import { webhooksListCommand, webhooksGetCommand, webhooksCreateCommand, webhooksUpdateCommand, webhooksDeleteCommand, webhooksRotateSecretCommand, webhooksTriggerCommand, webhooksListDeliveriesCommand, webhooksRedeliverCommand, webhooksReplayCommand, } from "./commands/webhooks.js";
 import { listenCommand } from "./commands/listen.js";
 import { tryMeCommand } from "./commands/try-me.js";
+import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
@@ -70,6 +71,53 @@ program
         process.exit(1);
     }
 });
+// ── skills (MNE-1324) — discover the zero-install skill surface ──────────────
+const skills = program
+    .command("skills")
+    .description("List and describe the Mnemom CLI skills (npx @mnemom/mnemom@latest <skill>)")
+    // Bare `mnemom skills` lists; but an unknown subcommand or stray arg must ERROR
+    // (exit 1) like every other command group — NOT silently print the list (the
+    // `{ isDefault }` footgun caught in the MNE-1324 review, F1). A parent .action()
+    // handles the bare case; allowExcessArguments(false) rejects `skills bogus`.
+    .option("--json", "Emit the registry as JSON")
+    .allowExcessArguments(false)
+    .action(async (opts) => {
+    try {
+        await skillsListCommand(opts);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+skills
+    .command("list")
+    .description("List available + planned skills")
+    .option("--json", "Emit the registry as JSON")
+    .allowExcessArguments(false)
+    .action(async (opts) => {
+    try {
+        await skillsListCommand(opts);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+skills
+    .command("describe <name>")
+    .description("Show a skill's usage + details")
+    .option("--json", "Emit the skill as JSON")
+    .allowExcessArguments(false)
+    .action(async (name, opts) => {
+    try {
+        await skillsDescribeCommand(name, opts);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 program
     .command("status")
     .description("Show agent status and connection info")

package/dist/lib/skills.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Skill registry (MNE-1324) — the contract behind `npx @mnemom/mnemom <skill>`.
+ *
+ * A "skill" is a named, self-contained capability the CLI exposes as a verb
+ * (the Microsoft-Agent-365-style "get the thing, then call a skill" model). The
+ * registry is the single source of truth that `mnemom skills list/describe`
+ * reads, so the discoverable surface and the actual commands never drift.
+ *
+ * This is metadata only — the runnable logic for each available skill lives in
+ * its existing command (e.g. `commands/try-me.ts`); the registry just describes
+ * it and is reused, not re-implemented. `planned` entries advertise the lane's
+ * roadmap (A2 `onboard`, A4 `wrap`) without pretending to run.
+ *
+ * Drift note: the skill NAMES here are the source of truth for `skills
+ * list`/`describe`; the `usage`/`description` strings are hand-written
+ * illustrative prose (not derived from the command's option parser), so treat
+ * them as a summary, not an exhaustive flag reference — `mnemom <skill> --help`
+ * is always authoritative for the full option set.
+ */
+export type SkillStatus = "available" | "planned";
+export interface Skill {
+    /** The verb: `mnemom <name>` (and `npx @mnemom/mnemom@latest <name>`). */
+    name: string;
+    /** One-line summary for `skills list`. */
+    summary: string;
+    /** Canonical invocation shown in `skills describe`. */
+    usage: string;
+    /** Longer, multi-line description for `skills describe`. */
+    description: string;
+    /** `available` = runnable today; `planned` = on the roadmap, not yet shipped. */
+    status: SkillStatus;
+    /** Copy-pasteable examples. */
+    examples?: string[];
+    /** Tracking reference (Linear id) for a planned skill. */
+    ref?: string;
+}
+/**
+ * The registry. `try-me` is the first registered skill (MNE-934, shipped); it is
+ * NOT re-implemented here — `mnemom try-me <token>` keeps working exactly as
+ * before, and this entry simply makes it discoverable. `onboard`/`wrap` are the
+ * planned next skills (MNE-933 / MNE-935).
+ */
+export declare const SKILLS: readonly Skill[];
+/** All registered skills, in registry order. */
+export declare function listSkills(): readonly Skill[];
+/** Look up a skill by its exact verb name; undefined if unknown. */
+export declare function getSkill(name: string): Skill | undefined;

package/dist/lib/skills.js

@@ -0,0 +1,71 @@
+/**
+ * Skill registry (MNE-1324) — the contract behind `npx @mnemom/mnemom <skill>`.
+ *
+ * A "skill" is a named, self-contained capability the CLI exposes as a verb
+ * (the Microsoft-Agent-365-style "get the thing, then call a skill" model). The
+ * registry is the single source of truth that `mnemom skills list/describe`
+ * reads, so the discoverable surface and the actual commands never drift.
+ *
+ * This is metadata only — the runnable logic for each available skill lives in
+ * its existing command (e.g. `commands/try-me.ts`); the registry just describes
+ * it and is reused, not re-implemented. `planned` entries advertise the lane's
+ * roadmap (A2 `onboard`, A4 `wrap`) without pretending to run.
+ *
+ * Drift note: the skill NAMES here are the source of truth for `skills
+ * list`/`describe`; the `usage`/`description` strings are hand-written
+ * illustrative prose (not derived from the command's option parser), so treat
+ * them as a summary, not an exhaustive flag reference — `mnemom <skill> --help`
+ * is always authoritative for the full option set.
+ */
+/**
+ * The registry. `try-me` is the first registered skill (MNE-934, shipped); it is
+ * NOT re-implemented here — `mnemom try-me <token>` keeps working exactly as
+ * before, and this entry simply makes it discoverable. `onboard`/`wrap` are the
+ * planned next skills (MNE-933 / MNE-935).
+ */
+export const SKILLS = [
+    {
+        name: "try-me",
+        status: "available",
+        summary: "Run the Mnemom Dojo onboarding for a /try-me invite token.",
+        usage: "mnemom try-me <token> [--api <url>] [--name <name>] [--resume <agent_id>] " +
+            "[--yes] [--json] [--dry-run] [--no-open] [--poll-timeout <s>]",
+        description: "Zero-install onboarding for the Mnemom Dojo: resolve a /try-me invite token, " +
+            "birth an agent identity, claim it, declare its starter alignment + protection " +
+            "cards, and report ready for the sparring sim — born → claim → declare → spar. " +
+            "Drives the dojo's HTTPS surface directly (no MCP setup required), so it runs the " +
+            "same way on any fresh machine.",
+        examples: [
+            "npx @mnemom/mnemom@latest try-me tryme_xxxxxxxxxxxx",
+            "mnemom try-me tryme_xxxxxxxxxxxx --name Atlas",
+        ],
+    },
+    {
+        name: "onboard",
+        status: "planned",
+        ref: "MNE-933",
+        summary: "Self-onboard the calling agent end-to-end (scan → claim → declare → badge).",
+        usage: "mnemom onboard",
+        description: "Runs the sovereignty path for the calling agent itself: scan its trust posture, " +
+            "claim its identity, declare an alignment card, and earn a verifiable Trust Rating — " +
+            "one command, no manifest. Planned (MNE-933).",
+    },
+    {
+        name: "wrap",
+        status: "planned",
+        ref: "MNE-935",
+        summary: "Instrument an existing production agent through the Mnemom gateway.",
+        usage: "mnemom wrap",
+        description: "Points an existing agent's provider calls at the Mnemom gateway, claims/births its " +
+            "identity, and seeds starter alignment + protection cards — bring-your-own-agent " +
+            "onboarding. Planned (MNE-935).",
+    },
+];
+/** All registered skills, in registry order. */
+export function listSkills() {
+    return SKILLS;
+}
+/** Look up a skill by its exact verb name; undefined if unknown. */
+export function getSkill(name) {
+    return SKILLS.find((s) => s.name === name);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.15.1-next.1",
+  "version": "0.16.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {