@mnemom/mnemom 0.16.1 → 0.16.3

package/dist/commands/wrap.js

@@ -0,0 +1,331 @@
+/**
+ * `mnemom wrap` — instrument an existing production agent through the Mnemom gateway (MNE-935, A4).
+ *
+ * Asks the developer for their provider + framework + agent name, makes a birth
+ * call to the gateway to provision the agent identity, seeds starter alignment +
+ * protection cards, and emits a drop-in code example. No reasoning change to the
+ * host agent.
+ *
+ * AUTH MODEL: Two credentials are involved:
+ *   - Mnemom auth (MNEMOM_API_KEY or `mnemom login` JWT) — used for card writes
+ *   - Provider API key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY) — used
+ *     for the one-time gateway birth call; this is the same key the user's agent
+ *     already holds, so the birth requires no new credential
+ *
+ * See SKILL-RUNNER-CONTRACT.md §2–§4 for the lifecycle + output contract.
+ */
+import { requireAuth } from "../lib/auth.js";
+import { putAlignmentCard, putProtectionCard, MnemomApiError } from "../lib/api.js";
+import { mergeAgentConfig } from "../lib/agent-config.js";
+import { askSelect, askInput, isInteractive } from "../lib/prompt.js";
+import { getGatewayUrl } from "../lib/config.js";
+import { fmt } from "../lib/format.js";
+const AGENT_HEADER = "x-mnemom-agent";
+const PROVIDERS = {
+    anthropic: {
+        label: "Anthropic",
+        keyEnv: "ANTHROPIC_API_KEY",
+        keyHeader: "x-api-key",
+        defaultModel: "claude-haiku-4-5-20251001",
+        basePath: "/anthropic",
+    },
+    openai: {
+        label: "OpenAI",
+        keyEnv: "OPENAI_API_KEY",
+        keyHeader: "Authorization",
+        defaultModel: "gpt-4o-mini",
+        basePath: "/openai",
+    },
+    gemini: {
+        label: "Google Gemini",
+        keyEnv: "GOOGLE_API_KEY",
+        keyHeader: "x-goog-api-key",
+        defaultModel: "gemini-2.0-flash",
+        basePath: "/gemini",
+    },
+};
+export async function wrapCommand(options = {}) {
+    const json = !!options.json;
+    const nonInteractive = !!options.yes || json || !isInteractive();
+    const steps = [];
+    const say = (line = "") => {
+        if (!json)
+            console.log(line);
+    };
+    say(fmt.header("Mnemom — wrap"));
+    say();
+    say(fmt.dim("Instrument your existing agent through the Mnemom gateway."));
+    say();
+    // Phase 1 — Resolve + Auth (Mnemom session for card writes)
+    await requireAuth();
+    const gatewayUrl = getGatewayUrl().replace(/\/$/, "");
+    const provider = await resolveProvider(options, nonInteractive);
+    const framework = await resolveFramework(options, nonInteractive);
+    const agentName = await resolveAgentName(options, nonInteractive);
+    const providerKey = await resolveProviderKey(options, PROVIDERS[provider], nonInteractive, say);
+    steps.push({
+        step: "resolve",
+        status: "ok",
+        detail: `provider=${provider} framework=${framework} name=${agentName}`,
+    });
+    // Phase 2 — Birth: one gateway call to provision the identity
+    say();
+    say(`${fmt.badge("birth", "cyan")} Provisioning ${fmt.badge(agentName, "magenta")} through the gateway…`);
+    let agentId;
+    try {
+        agentId = await birthThroughGateway(gatewayUrl, provider, agentName, providerKey);
+        steps.push({ step: "birth", status: "ok", detail: agentId });
+        say(fmt.success(`Provisioned → ${agentId}`));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "birth", status: "error", detail: msg });
+        if (json) {
+            console.log(JSON.stringify({
+                skill: "wrap",
+                verdict: "error",
+                agent_id: null,
+                gateway_base_url: gatewayUrl,
+                next_step: null,
+                steps,
+            }, null, 2));
+        }
+        throw new Error(`Gateway birth failed: ${msg}`, { cause: err });
+    }
+    mergeAgentConfig({ agent_id: agentId, agent_name: agentName, gateway_url: gatewayUrl });
+    // Phase 2 — Seed alignment card
+    say();
+    say(`${fmt.badge("alignment", "cyan")} Seeding starter alignment card…`);
+    try {
+        await putAlignmentCard(agentId, JSON.stringify(buildStarterAlignmentCard(agentId)), "application/json");
+        steps.push({ step: "alignment", status: "ok" });
+        say(fmt.success("Alignment card set."));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "alignment", status: "error", detail: msg });
+        say(fmt.warn(`Alignment card skipped — set it later with \`mnemom card publish\`. (${msg})`));
+    }
+    // Phase 2 — Seed protection card
+    say();
+    say(`${fmt.badge("protection", "cyan")} Seeding starter protection card…`);
+    try {
+        await putProtectionCard(agentId, JSON.stringify(buildStarterProtectionCard(agentId)), "application/json");
+        steps.push({ step: "protection", status: "ok" });
+        say(fmt.success("Protection card set."));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "protection", status: "error", detail: msg });
+        say(fmt.warn(`Protection card skipped — set it later with \`mnemom protection publish\`. (${msg})`));
+    }
+    // Phase 3 — Report
+    say();
+    say(renderCodeExample(framework, provider, gatewayUrl, agentName));
+    say();
+    say(renderClaimInstructions(agentId));
+    if (json) {
+        console.log(JSON.stringify({
+            skill: "wrap",
+            verdict: "ok",
+            agent_id: agentId,
+            gateway_base_url: gatewayUrl,
+            next_step: "claim",
+            steps,
+        }, null, 2));
+    }
+}
+// ── Phase 1 resolvers ─────────────────────────────────────────────────────────
+async function resolveProvider(options, nonInteractive) {
+    if (options.provider) {
+        const p = options.provider.toLowerCase();
+        if (!PROVIDERS[p]) {
+            throw new Error(`Unknown provider "${options.provider}". Choose: anthropic, openai, gemini`);
+        }
+        return p;
+    }
+    if (nonInteractive)
+        return "anthropic";
+    const choice = await askSelect("Which AI provider does your agent use?", [
+        "Anthropic (Claude)",
+        "OpenAI (GPT)",
+        "Google Gemini",
+    ]);
+    if (choice?.startsWith("OpenAI"))
+        return "openai";
+    if (choice?.startsWith("Google"))
+        return "gemini";
+    return "anthropic";
+}
+async function resolveFramework(options, nonInteractive) {
+    if (options.framework) {
+        const f = options.framework.toLowerCase();
+        if (f === "python" || f === "py")
+            return "python";
+        if (f === "node" || f === "nodejs" || f === "js" || f === "ts" || f === "typescript")
+            return "node";
+        throw new Error(`Unknown framework "${options.framework}". Choose: python, node`);
+    }
+    if (nonInteractive)
+        return "python";
+    const choice = await askSelect("Which language/framework is your agent using?", [
+        "Python",
+        "Node.js / TypeScript",
+    ]);
+    return choice?.startsWith("Node") ? "node" : "python";
+}
+async function resolveAgentName(options, nonInteractive) {
+    if (options.name?.trim())
+        return options.name.trim();
+    if (nonInteractive)
+        return "my-agent";
+    const name = (await askInput("What should we call this agent? (x-mnemom-agent value)")).trim();
+    return name || "my-agent";
+}
+async function resolveProviderKey(options, prov, nonInteractive, say) {
+    if (options.providerKey?.trim())
+        return options.providerKey.trim();
+    const fromEnv = process.env[prov.keyEnv]?.trim();
+    if (fromEnv) {
+        say(fmt.dim(`Using ${prov.keyEnv} from environment.`));
+        return fromEnv;
+    }
+    if (nonInteractive) {
+        throw new Error(`No ${prov.label} API key found. Set ${prov.keyEnv} or pass --provider-key <key>.`);
+    }
+    const key = (await askInput(`Enter your ${prov.label} API key (one-time birth call — never stored):`)).trim();
+    if (!key)
+        throw new Error(`A ${prov.label} API key is required to birth the agent.`);
+    return key;
+}
+// ── Birth call ────────────────────────────────────────────────────────────────
+async function birthThroughGateway(gatewayUrl, provider, agentName, providerKey) {
+    const prov = PROVIDERS[provider];
+    const authValue = provider === "openai" ? `Bearer ${providerKey}` : providerKey;
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        [prov.keyHeader]: authValue,
+        [AGENT_HEADER]: agentName,
+    };
+    if (provider === "anthropic") {
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    let url;
+    let body;
+    switch (provider) {
+        case "openai":
+            url = `${gatewayUrl}${prov.basePath}/v1/chat/completions`;
+            body = JSON.stringify({
+                model: prov.defaultModel,
+                max_tokens: 16,
+                messages: [{ role: "user", content: "hello" }],
+            });
+            break;
+        case "gemini":
+            url = `${gatewayUrl}${prov.basePath}/v1beta/models/${prov.defaultModel}:generateContent`;
+            body = JSON.stringify({ contents: [{ parts: [{ text: "hello" }] }] });
+            break;
+        case "anthropic":
+        default:
+            url = `${gatewayUrl}${prov.basePath}/v1/messages`;
+            body = JSON.stringify({
+                model: prov.defaultModel,
+                max_tokens: 16,
+                messages: [{ role: "user", content: "hello" }],
+            });
+    }
+    const response = await fetch(url, { method: "POST", headers, body });
+    const agentId = response.headers.get(AGENT_HEADER);
+    if (!response.ok && !agentId) {
+        const text = await response.text().catch(() => "");
+        throw new MnemomApiError(response.status, `Gateway returned ${response.status}: ${text.slice(0, 300)}`);
+    }
+    if (!agentId || !/^mnm-/.test(agentId)) {
+        throw new Error(`Gateway returned no mnm- agent id on the ${AGENT_HEADER} response header (status ${response.status}).`);
+    }
+    return agentId;
+}
+// ── Starter cards ─────────────────────────────────────────────────────────────
+function buildStarterAlignmentCard(agentId) {
+    return {
+        card_version: "unified/2026-04-26",
+        agent_id: agentId,
+        autonomy_mode: "observe",
+        integrity_mode: "observe",
+        principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
+        values: { declared: ["transparency", "safety", "honesty"] },
+        autonomy: {
+            bounded_actions: ["respond_to_prompts"],
+            forbidden_actions: [],
+            escalation_triggers: [],
+        },
+        audit: { retention_days: 30, queryable: false, trace_format: "otel" },
+    };
+}
+function buildStarterProtectionCard(agentId) {
+    return {
+        card_version: "protection/2026-04-26",
+        agent_id: agentId,
+        mode: "observe",
+        thresholds: { warn: 0.3, quarantine: 0.6, block: 0.9 },
+        screen_surfaces: {
+            incoming: true,
+            outgoing: true,
+            tool_calls: true,
+            tool_responses: true,
+        },
+        trusted_sources: { domains: [], agent_ids: [], ip_ranges: [] },
+    };
+}
+// ── Code example rendering ────────────────────────────────────────────────────
+function renderCodeExample(framework, provider, gatewayUrl, agentName) {
+    const prov = PROVIDERS[provider];
+    const lines = [fmt.section("Drop-in gateway wrapper"), ""];
+    if (framework === "python") {
+        renderPythonSnippet(lines, provider, prov, gatewayUrl, agentName);
+    }
+    else {
+        renderNodeSnippet(lines, provider, prov, gatewayUrl, agentName);
+    }
+    lines.push("", fmt.dim("No other changes needed — your agent logic is unchanged."));
+    return lines.join("\n");
+}
+function renderPythonSnippet(lines, provider, prov, gatewayUrl, agentName) {
+    const base = `${gatewayUrl}${prov.basePath}`;
+    if (provider === "anthropic") {
+        lines.push("  import anthropic", "", "  client = anthropic.Anthropic(", `      base_url="${base}",`, `      default_headers={"x-mnemom-agent": "${agentName}"},`, "  )");
+    }
+    else if (provider === "openai") {
+        lines.push("  from openai import OpenAI", "", "  client = OpenAI(", `      base_url="${base}/v1",`, `      default_headers={"x-mnemom-agent": "${agentName}"},`, "  )");
+    }
+    else {
+        lines.push("  # Google Gemini via Mnemom gateway", `  # Set base URL to: ${base}`, `  # Add header: x-mnemom-agent: ${agentName}`);
+    }
+}
+function renderNodeSnippet(lines, provider, prov, gatewayUrl, agentName) {
+    const base = `${gatewayUrl}${prov.basePath}`;
+    if (provider === "anthropic") {
+        lines.push('  import Anthropic from "@anthropic-ai/sdk";', "", "  const client = new Anthropic({", `    baseURL: "${base}",`, `    defaultHeaders: { "x-mnemom-agent": "${agentName}" },`, "  });");
+    }
+    else if (provider === "openai") {
+        lines.push('  import OpenAI from "openai";', "", "  const client = new OpenAI({", `    baseURL: "${base}/v1",`, `    defaultHeaders: { "x-mnemom-agent": "${agentName}" },`, "  });");
+    }
+    else {
+        lines.push("  // Google Gemini via Mnemom gateway", `  // Set base URL to: ${base}`, `  // Add header: "x-mnemom-agent": "${agentName}"`);
+    }
+}
+function renderClaimInstructions(agentId) {
+    const lines = [
+        fmt.section("Next step — claim this agent"),
+        "",
+        fmt.label("  Agent ID:", agentId),
+        "",
+        fmt.dim("  Claim this agent so you own its identity on the platform:"),
+        "",
+        `    mnemom agents claim ${agentId}`,
+        "",
+        fmt.dim("  After claiming, traces appear in `mnemom logs`."),
+    ];
+    return lines.join("\n");
+}

package/dist/index.js

@@ -8,9 +8,9 @@ import { logsCommand } from "./commands/logs.js";
 import { licenseActivateCommand, licenseStatusCommand, licenseDeactivateCommand, } from "./commands/license.js";
 import { cardShowCommand, cardPublishCommand, cardValidateCommand, cardEditCommand, cardEvaluateCommand, } from "./commands/card.js";
 import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyListCommand, policyTestCommand, policyEvaluateCommand, } from "./commands/policy.js";
-import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, } from "./commands/protection.js";
-import { agentsListCommand, agentsClaimCommand } from "./commands/agents.js";
-import { orgListCommand, orgShowCommand } from "./commands/org.js";
+import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, protectionDriftCommand, } from "./commands/protection.js";
+import { agentsListCommand, agentsClaimCommand, agentsMoveCommand } from "./commands/agents.js";
+import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
 import { postureListCommand, postureShowCommand, postureCreateCommand, postureUpdateCommand, postureCloneCommand, postureRevisionsCommand, postureDiffCommand, postureAssignCommand, postureUnassignCommand, posturePreviewComposeCommand, postureDeleteCommand, } from "./commands/posture.js";
@@ -20,7 +20,10 @@ 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 { wrapCommand } from "./commands/wrap.js";
+import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
+import { usageCommand, parseNumericFlag, parseDaysFlag } from "./commands/usage.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
@@ -71,6 +74,78 @@ program
         process.exit(1);
     }
 });
+// ── wrap (MNE-935, A4) — instrument an existing agent through the gateway ────
+//
+// `mnemom wrap` is the "bring your production agent" skill: it asks for
+// provider + framework + agent name, births the agent through the gateway,
+// seeds starter alignment + protection cards, and emits a drop-in code snippet.
+// Extends the skill-runner contract from A1 (MNE-932). See commands/wrap.ts.
+// ─────────────────────────────────────────────────────────────────────────────
+program
+    .command("wrap")
+    .description("Instrument an existing agent through the Mnemom gateway (born → cards → snippet)")
+    .option("--provider <provider>", "AI provider: anthropic, openai, gemini (default: prompt)")
+    .option("--framework <framework>", "Language/framework: python, node (default: prompt)")
+    .option("--name <name>", "Agent name used as the x-mnemom-agent header value")
+    .option("--provider-key <key>", "Provider API key for the one-time birth call (default: reads env)")
+    .option("-y, --yes", "Non-interactive: accept defaults, skip all prompts")
+    .option("--json", "Emit machine-readable result (skill / verdict / agent_id / steps)")
+    .action(async (opts) => {
+    try {
+        await wrapCommand({
+            provider: opts.provider,
+            framework: opts.framework,
+            name: opts.name,
+            providerKey: opts.providerKey,
+            yes: opts.yes,
+            json: opts.json,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+// ── onboard (MNE-933, A2) — self-onboard the calling agent end-to-end ────────
+//
+// `mnemom onboard` runs the sovereignty path for the CALLING agent itself:
+// scan its trust posture → claim its identity → declare an alignment card →
+// surface its Trust Rating → hand back a public badge URL. One command, no
+// manifest. Additive + human-in-the-loop preserving: the only mutation is the
+// agent's own alignment-card declaration (its standing scoped token). The agent
+// authenticates as its OWN device-grant principal (MNE-944). The Trust Rating
+// is PROVISIONAL until the observer pipeline generates traces — the signed
+// rating + rendered badge are computed server-side, post-hoc. See
+// commands/onboard.ts for the auth model.
+// ─────────────────────────────────────────────────────────────────────────────
+program
+    .command("onboard")
+    .description("Self-onboard the calling agent (scan → claim → declare → rating → badge); the Trust Rating is provisional until the observer pipeline generates traces")
+    .option("--json", "Emit machine-readable step outcomes (implies non-interactive)")
+    .option("-y, --yes", "Non-interactive: accept defaults, skip all prompts")
+    .option("--key <key>", "The agent's provider API key — the CLI derives the claim hash proof")
+    .option("--hash-proof <hex>", "A pre-computed 64-hex hash proof (advanced/CI; alternative to --key)")
+    .option("--no-open", "Never auto-open the badge URL in a browser — just print it")
+    .action(async (opts) => {
+    try {
+        // The calling agent is selected via the program-level `--agent` (which
+        // shadows any subcommand `--agent` under commander@12 — the MNE-238
+        // class), mirroring how `status`/`logs` read it.
+        const parentOpts = program.opts();
+        await onboardCommand({
+            json: opts.json,
+            yes: opts.yes,
+            key: opts.key,
+            hashProof: opts.hashProof,
+            open: opts.open,
+            agent: parentOpts.agent,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ── skills (MNE-1324) — discover the zero-install skill surface ──────────────
 const skills = program
     .command("skills")
@@ -346,6 +421,25 @@ protectionCmd
         process.exit(1);
     }
 });
+protectionCmd
+    .command("drift")
+    .argument("<file>", "Path to a committed protection-card snapshot (YAML or JSON)")
+    .description("Compare a committed snapshot against the live canonical card (read-only)")
+    .option("--strict", "Also fail on live fields the snapshot does not record")
+    .option("--json", "Emit the drift result as JSON")
+    .action(async (file, subOpts) => {
+    try {
+        const opts = program.opts();
+        await protectionDriftCommand(file, opts.agent, {
+            strict: subOpts.strict,
+            json: subOpts.json,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ============================================================================
 // Policy commands (removed — stubs with migration guidance)
 // ============================================================================
@@ -418,15 +512,27 @@ const agentsCmd = program
 agentsCmd
     .command("claim <id-or-name>")
     .description("Claim an agent into an org (ADR-062 claim-to-org)")
-    .option("--org <slug>", "Org slug or id to claim into (default: your personal org)")
+    .option("--org <slug>", "Org slug or id to claim into (default: your ACTIVE org from `mnemom org use`, else your personal org)")
     .option("--key <key>", "The agent's provider API key — the CLI derives the hash proof from it")
     .option("--hash-proof <hex>", "A pre-computed 64-hex SHA-256 proof (advanced/CI; alternative to --key)")
     .option("--name <name>", "Provisioned agent name for proof derivation — auto-resolved from the agent id when possible; pass only to override")
     .option("--json", "Output JSON instead of human-readable text")
     .action(async (idOrName, opts) => {
     try {
+        // `agentsCmd` (the parent `agents` command) ALSO defines `--org` (for
+        // `mnemom agents --org <id>` list-scoping). Commander@12 binds a flag
+        // shared by a parent and a subcommand to whichever of the two owns it
+        // and runs first in the parse chain — here that's the parent — so
+        // `agents claim <id> --org <slug>` had its --org silently swallowed by
+        // `agentsCmd` before this subcommand's own `--org` option ever saw it
+        // (MNE-2496: confirmed live, the agent always landed in the caller's
+        // personal org regardless of --org). Same shadow class as the global
+        // `--agent` fix at MNE-238 (see the `advisories list`/`show` actions
+        // below) — resolve the local value first, falling back to the
+        // parent's captured value so either parse order still works.
+        const org = opts.org ?? agentsCmd.opts().org;
         await agentsClaimCommand(idOrName, {
-            org: opts.org,
+            org,
             key: opts.key,
             hashProof: opts.hashProof,
             name: opts.name,
@@ -438,6 +544,21 @@ agentsCmd
         process.exit(1);
     }
 });
+agentsCmd
+    .command("move <id-or-name>")
+    .description("Move an agent to another org — requires owner/admin in BOTH the current and destination org " +
+    "(role-based; no agent key needed, unlike re-claim)")
+    .option("--to <slug-or-id>", "Destination org (required; never defaults to the active org)")
+    .option("--json", "Output JSON instead of human-readable text")
+    .action(async (idOrName, opts) => {
+    try {
+        await agentsMoveCommand(idOrName, { to: opts.to, json: opts.json });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ============================================================================
 // Organization management (ADR-044, Piece 1 of T1-3.1)
 // ============================================================================
@@ -457,6 +578,21 @@ orgCmd
         process.exit(1);
     }
 });
+orgCmd
+    .command("use [slug-or-id]")
+    .description("Set the ACTIVE org — the default for org-scoped commands like `agents claim` " +
+    "(login binds no org; without this, claims land in your personal org). " +
+    "No argument shows the current setting.")
+    .option("--clear", "Forget the active org (org-scoped commands revert to your personal org)")
+    .action(async (slugOrId, options) => {
+    try {
+        await orgUseCommand(slugOrId, { clear: options.clear });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 orgCmd
     .command("show [org_id]")
     .description("Show details of an org (default: your personal org if --personal, else single membership)")
@@ -1060,7 +1196,8 @@ postureCmd
 // ============================================================================
 program
     .command("login")
-    .description("Authenticate with your Mnemom account")
+    .description("Authenticate with your Mnemom account (note: login binds no org — set a default " +
+    "for org-scoped commands with `mnemom org use <slug>`)")
     .option("--no-browser", "Use the device code flow instead of opening a browser")
     .action(async (options) => {
     try {
@@ -1443,6 +1580,55 @@ program
         process.exit(1);
     }
 });
+// ============================================================================
+// Usage attribution (MNE-3215 W6 / issue #1221)
+//
+// `mnemom usage --org <id>` shows per-person token and request consumption
+// for an org window. Gated by USAGE_ATTRIBUTION_API_ENABLED on the API side
+// (defaults off in every environment). Reports consumption only — no currency,
+// no spend, no cost.
+//
+// Every flag below maps 1:1 onto a query parameter the endpoint documents in
+// the API's `openapi.json` (`days`, `person_id`, `provider`, `model`, `limit`,
+// `cursor`). It is deliberately not a friendlier invented vocabulary: the first
+// version of this command offered `--period` and `--page`, neither of which the
+// endpoint accepts, so the server silently ignored both and returned an
+// unfiltered first page.
+// ============================================================================
+program
+    .command("usage")
+    .description("Show per-person token and request consumption for an org")
+    .requiredOption("--org <id>", "Org ID to show consumption for")
+    .option("--days <7|30|90>", "Reporting window in days (default: 30)")
+    .option("--person <id>", "Filter to one person's consumption")
+    .option("--provider <name>", "Filter to one provider")
+    .option("--model <name>", "Filter to one model")
+    .option("--limit <n>", "Max rows per page (default: 100, max 200)")
+    .option("--cursor <cursor>", "Continue from a previous page's cursor")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (options) => {
+    try {
+        // A miskeyed numeric flag (e.g. `--limit foo`, `--limit 2abc`,
+        // `--limit 0`, `--days 45`) warns and falls back to the default rather
+        // than silently acting on a value the user did not type. Both live in
+        // commands/usage.ts so their reject-and-warn arms are unit-testable
+        // without driving Commander.
+        await usageCommand({
+            org: options.org,
+            days: parseDaysFlag(options.days),
+            person: options.person,
+            provider: options.provider,
+            model: options.model,
+            limit: parseNumericFlag("--limit", options.limit),
+            cursor: options.cursor,
+            json: options.json,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // Export the fully-assembled commander program so tooling (e.g. the
 // command-tree snapshot generator in scripts/gen-command-tree.mjs) can
 // statically introspect the command surface WITHOUT executing the CLI.

package/dist/lib/agent-config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent identity config store — ~/.mnemom/agent.json.
+ *
+ * Persists the calling agent's resolved identity so skill verbs (try-me,
+ * onboard, wrap) write on first success and read thereafter — no re-prompt for
+ * identity on subsequent invocations (MNE-937).
+ *
+ * Co-located with auth.ts → auth.json. Separate by design: auth.json holds
+ * bearer credentials (wiped on logout); agent.json holds identity metadata
+ * that survives re-login and provider key rotation.
+ */
+export interface AgentConfig {
+    agent_id?: string;
+    agent_name?: string;
+    org_id?: string;
+    gateway_url?: string;
+}
+/** Load the agent config; a missing or corrupt file returns `{}`. */
+export declare function loadAgentConfig(): AgentConfig;
+/** Persist the full agent config (replaces the file). */
+export declare function saveAgentConfig(config: AgentConfig): void;
+/** Shallow-merge `partial` into the existing config and persist. */
+export declare function mergeAgentConfig(partial: Partial<AgentConfig>): void;
+export declare function getAgentId(): string | undefined;
+export declare function getAgentName(): string | undefined;
+export declare function getOrgId(): string | undefined;
+export declare function getGatewayUrl(): string | undefined;