@mnemom/mnemom 0.10.0 → 0.11.0

package/dist/commands/api-key.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `mnemom api-key ...` commands — capability-based API key management
+ * (ADR-049). Mirrors the dashboard scope picker and the API mint-time
+ * vocabulary; one CLI surface for the same key lifecycle operations.
+ *
+ *   mnemom api-key list                              — list active personal keys
+ *   mnemom api-key create --name <name> [--scopes a,b,c]
+ *                                                    — mint a new key
+ *   mnemom api-key rotate <key_id>                   — atomic mint-new + revoke-old
+ *   mnemom api-key revoke <key_id>                   — soft-delete
+ *
+ * Auth: any of the standard CLI auth methods — JWT (`mnemom login`),
+ * MNEMOM_API_KEY env, or a stored API key. Note the chicken-and-egg:
+ * to mint your first key you'll need a JWT (the website's create-key
+ * dialog is the alternative). After that, an `api:write` key can mint
+ * additional keys for itself.
+ */
+import { type ApiKeyScope } from "../lib/api.js";
+/**
+ * Exported for tests. Parses a comma-separated `--scopes` flag value,
+ * accepts legacy `api` for backward compat, and returns a typed array.
+ * Throws on unknown scope names so users get a clear error instead of
+ * silently dropping intent.
+ */
+export declare function parseScopes(input: string | undefined): ApiKeyScope[];
+export declare function apiKeyListCommand(opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyCreateCommand(opts: {
+    name?: string;
+    scopes?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyRotateCommand(keyId: string | undefined, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyRevokeCommand(keyId: string | undefined): Promise<void>;

package/dist/commands/api-key.js

@@ -0,0 +1,181 @@
+/**
+ * `mnemom api-key ...` commands — capability-based API key management
+ * (ADR-049). Mirrors the dashboard scope picker and the API mint-time
+ * vocabulary; one CLI surface for the same key lifecycle operations.
+ *
+ *   mnemom api-key list                              — list active personal keys
+ *   mnemom api-key create --name <name> [--scopes a,b,c]
+ *                                                    — mint a new key
+ *   mnemom api-key rotate <key_id>                   — atomic mint-new + revoke-old
+ *   mnemom api-key revoke <key_id>                   — soft-delete
+ *
+ * Auth: any of the standard CLI auth methods — JWT (`mnemom login`),
+ * MNEMOM_API_KEY env, or a stored API key. Note the chicken-and-egg:
+ * to mint your first key you'll need a JWT (the website's create-key
+ * dialog is the alternative). After that, an `api:write` key can mint
+ * additional keys for itself.
+ */
+import { listApiKeys, createApiKey, rotateApiKey, revokeApiKey, isLegacyScopeSet, API_KEY_SCOPES, DEFAULT_API_KEY_SCOPES, } from "../lib/api.js";
+import { requireAuth } from "../lib/auth.js";
+import { fmt } from "../lib/format.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Exported for tests. Parses a comma-separated `--scopes` flag value,
+ * accepts legacy `api` for backward compat, and returns a typed array.
+ * Throws on unknown scope names so users get a clear error instead of
+ * silently dropping intent.
+ */
+export function parseScopes(input) {
+    if (!input)
+        return [...DEFAULT_API_KEY_SCOPES];
+    const raw = input
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (raw.length === 0)
+        return [...DEFAULT_API_KEY_SCOPES];
+    const valid = new Set(API_KEY_SCOPES);
+    // Accept legacy 'api' input here so users who copy-paste from older
+    // docs/scripts get a clean canonicalization. The API also aliases.
+    valid.add("api");
+    const unknown = raw.filter((s) => !valid.has(s));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown scope(s): ${unknown.join(", ")}. ` +
+            `Valid: ${Array.from(API_KEY_SCOPES).join(", ")}`);
+    }
+    return raw;
+}
+function renderScopeBadge(scope) {
+    // Admin scopes get a visual marker so the audit trail in the CLI
+    // makes elevated keys obvious at a glance.
+    if (scope === "admin:platform" || scope === "admin:org") {
+        return fmt.warn(`[${scope}]`);
+    }
+    return `[${scope}]`;
+}
+function formatRow(key) {
+    const created = key.created_at
+        ? new Date(key.created_at).toISOString().slice(0, 10)
+        : "?";
+    const lastUsed = key.last_used_at
+        ? new Date(key.last_used_at).toISOString().slice(0, 10)
+        : "never";
+    const scopes = (key.scopes ?? []).map(renderScopeBadge).join(" ");
+    const legacy = isLegacyScopeSet(key.scopes) ? fmt.dim(" (legacy)") : "";
+    return `  ${key.key_id}  ${key.key_prefix}…  ${key.name.padEnd(24)}  ${scopes}${legacy}\n    created ${created} · last used ${lastUsed}`;
+}
+// ─── mnemom api-key list ─────────────────────────────────────────────────
+export async function apiKeyListCommand(opts) {
+    await requireAuth();
+    let keys;
+    try {
+        keys = await listApiKeys();
+    }
+    catch (err) {
+        console.error(fmt.error(`Failed to list api keys: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(keys, null, 2));
+        return;
+    }
+    if (keys.length === 0) {
+        console.log("\nNo active api keys.\n");
+        console.log("Create one with `mnemom api-key create --name <name>`.\n");
+        return;
+    }
+    console.log();
+    console.log(fmt.header(`Active api keys (${keys.length})`));
+    console.log();
+    for (const k of keys) {
+        console.log(formatRow(k));
+        console.log();
+    }
+}
+// ─── mnemom api-key create ───────────────────────────────────────────────
+export async function apiKeyCreateCommand(opts) {
+    await requireAuth();
+    if (!opts.name || opts.name.trim() === "") {
+        console.error(fmt.error("--name is required. Example: --name 'ci-prod'"));
+        process.exit(1);
+    }
+    let scopes;
+    try {
+        scopes = parseScopes(opts.scopes);
+    }
+    catch (err) {
+        console.error(fmt.error(err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+    let created;
+    try {
+        created = await createApiKey(opts.name.trim(), scopes);
+    }
+    catch (err) {
+        console.error(fmt.error(`Create failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(created, null, 2));
+        return;
+    }
+    console.log();
+    console.log(fmt.success(`Created ${created.key_id}`));
+    console.log();
+    console.log(fmt.label("  Name:    ", ` ${created.name}`));
+    console.log(fmt.label("  Scopes:  ", ` ${(created.scopes ?? []).join(", ")}`));
+    console.log(fmt.label("  Created: ", ` ${created.created_at}`));
+    console.log();
+    console.log(fmt.warn("  Cleartext (shown once — copy now):"));
+    console.log(`    ${created.key}`);
+    console.log();
+    console.log(fmt.dim("  This is the only time the cleartext is returned."));
+    console.log(fmt.dim("  Mnemom stores only the SHA-256 hash; the key cannot be retrieved later."));
+    console.log();
+}
+// ─── mnemom api-key rotate ───────────────────────────────────────────────
+export async function apiKeyRotateCommand(keyId, opts) {
+    await requireAuth();
+    if (!keyId) {
+        console.error(fmt.error("Usage: mnemom api-key rotate <key_id>"));
+        process.exit(1);
+    }
+    let rotated;
+    try {
+        rotated = await rotateApiKey(keyId);
+    }
+    catch (err) {
+        console.error(fmt.error(`Rotate failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(rotated, null, 2));
+        return;
+    }
+    console.log();
+    console.log(fmt.success(`Rotated. Old key ${keyId} is now revoked.`));
+    console.log();
+    console.log(fmt.label("  New key id:", ` ${rotated.key_id}`));
+    console.log(fmt.label("  Name:      ", ` ${rotated.name}`));
+    console.log(fmt.label("  Scopes:    ", ` ${(rotated.scopes ?? []).join(", ")}`));
+    console.log();
+    console.log(fmt.warn("  New cleartext (shown once — copy now):"));
+    console.log(`    ${rotated.key}`);
+    console.log();
+}
+// ─── mnemom api-key revoke ───────────────────────────────────────────────
+export async function apiKeyRevokeCommand(keyId) {
+    await requireAuth();
+    if (!keyId) {
+        console.error(fmt.error("Usage: mnemom api-key revoke <key_id>"));
+        process.exit(1);
+    }
+    try {
+        await revokeApiKey(keyId);
+    }
+    catch (err) {
+        console.error(fmt.error(`Revoke failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    console.log(fmt.success(`Revoked ${keyId}.`));
+}

package/dist/commands/governance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `mnemom governance` — operator CLI for governance signals (ADR-048).
+ *
+ * Subcommands:
+ *
+ *   signals      list | show | ack | resolve | dismiss
+ *   destinations list | add | remove | test
+ *   rules        list | add | remove
+ *
+ * The signal surface is operator-actionable: cron-driven sideband
+ * detections, future protection / posture observations. Distinct from
+ * `mnemom advisories list` (now narrowed to runtime.* / manual.* per
+ * ADR-048 §1).
+ */
+interface ListOpts {
+    org?: string;
+    team?: string;
+    agent?: string;
+    source?: string;
+    severity?: string;
+    status?: string;
+    scope?: string;
+    patternType?: string;
+    limit?: string;
+    since?: string;
+    json?: boolean;
+}
+interface AckOpts {
+    action?: string;
+    json?: boolean;
+}
+interface ResolveOpts {
+    status: string;
+    action?: string;
+    json?: boolean;
+}
+interface DismissOpts {
+    reason?: string;
+    json?: boolean;
+}
+interface DestAddOpts {
+    org: string;
+    channel: string;
+    config: string;
+    name?: string;
+    filter?: string;
+    json?: boolean;
+}
+interface RuleAddOpts {
+    org: string;
+    name: string;
+    predicate: string;
+    destinations: string;
+    json?: boolean;
+}
+export declare function governanceSignalsListCommand(opts: ListOpts): Promise<void>;
+export declare function governanceSignalsShowCommand(signalId: string, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceSignalsAckCommand(signalId: string, opts: AckOpts): Promise<void>;
+export declare function governanceSignalsResolveCommand(signalId: string, opts: ResolveOpts): Promise<void>;
+export declare function governanceSignalsDismissCommand(signalId: string, opts: DismissOpts): Promise<void>;
+export declare function governanceDestinationsListCommand(opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceDestinationsAddCommand(opts: DestAddOpts): Promise<void>;
+export declare function governanceDestinationsRemoveCommand(destinationId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceDestinationsTestCommand(destinationId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceRulesListCommand(opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceRulesAddCommand(opts: RuleAddOpts): Promise<void>;
+export declare function governanceRulesRemoveCommand(ruleId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/governance.js

@@ -0,0 +1,331 @@
+/**
+ * `mnemom governance` — operator CLI for governance signals (ADR-048).
+ *
+ * Subcommands:
+ *
+ *   signals      list | show | ack | resolve | dismiss
+ *   destinations list | add | remove | test
+ *   rules        list | add | remove
+ *
+ * The signal surface is operator-actionable: cron-driven sideband
+ * detections, future protection / posture observations. Distinct from
+ * `mnemom advisories list` (now narrowed to runtime.* / manual.* per
+ * ADR-048 §1).
+ */
+import chalk from "chalk";
+import { acknowledgeGovernanceSignal, createGovernanceDestination, createGovernanceRule, deleteGovernanceDestination, deleteGovernanceRule, dismissGovernanceSignal, getGovernanceSignal, listGovernanceDestinations, listGovernanceRules, listGovernanceSignalsForAgent, listGovernanceSignalsForOrg, listGovernanceSignalsForTeam, resolveGovernanceSignal, testGovernanceDestination, } from "../lib/api.js";
+import { requireAuth } from "../lib/auth.js";
+// ─── Formatting helpers ──────────────────────────────────────────────────
+function shortId(id) {
+    return id.length <= 16 ? id : id.slice(0, 13) + "...";
+}
+function severityColor(s) {
+    switch (s) {
+        case "critical":
+            return chalk.bgRed.white;
+        case "high":
+            return chalk.red;
+        case "warn":
+            return chalk.yellow;
+        default:
+            return chalk.cyan;
+    }
+}
+function statusBadge(s) {
+    switch (s) {
+        case "open":
+            return chalk.bold.red("OPEN");
+        case "acknowledged":
+            return chalk.yellow("ACK");
+        case "resolved":
+            return chalk.green("RESOLVED");
+        case "dismissed":
+            return chalk.dim("DISMISSED");
+        case "expired":
+            return chalk.dim("expired");
+        default:
+            return chalk.dim(s.toUpperCase());
+    }
+}
+function formatSignalRow(s) {
+    const sev = severityColor(s.severity)(s.severity.toUpperCase().padEnd(8));
+    return [
+        chalk.dim(shortId(s.id).padEnd(16)),
+        sev,
+        chalk.cyan(s.source.padEnd(22)),
+        chalk.magenta((s.pattern_type || "—").slice(0, 28).padEnd(28)),
+        statusBadge(s.status).padEnd(20),
+        chalk.dim(s.detected_at.replace("T", " ").replace(/\.\d+Z$/, "Z")),
+    ].join("  ");
+}
+// ─── signals list ────────────────────────────────────────────────────────
+export async function governanceSignalsListCommand(opts) {
+    await requireAuth();
+    const filters = {
+        source: opts.source,
+        severity: opts.severity,
+        status: opts.status,
+        scope: opts.scope,
+        pattern_type: opts.patternType,
+        since: opts.since,
+        limit: opts.limit ? parseInt(opts.limit, 10) : 100,
+    };
+    let result;
+    if (opts.org) {
+        result = await listGovernanceSignalsForOrg(opts.org, filters);
+    }
+    else if (opts.team) {
+        result = await listGovernanceSignalsForTeam(opts.team, filters);
+    }
+    else if (opts.agent) {
+        result = await listGovernanceSignalsForAgent(opts.agent, filters);
+    }
+    else {
+        throw new Error("One of --org, --team, --agent is required.");
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const signals = result.signals;
+    if (signals.length === 0) {
+        console.log(chalk.dim("(no governance signals match)"));
+        return;
+    }
+    console.log([
+        chalk.bold("ID".padEnd(16)),
+        chalk.bold("SEVERITY".padEnd(8)),
+        chalk.bold("SOURCE".padEnd(22)),
+        chalk.bold("PATTERN".padEnd(28)),
+        chalk.bold("STATUS".padEnd(20)),
+        chalk.bold("DETECTED"),
+    ].join("  "));
+    for (const s of signals)
+        console.log(formatSignalRow(s));
+    console.log("");
+    console.log(chalk.dim(`${signals.length} signal(s).`));
+}
+// ─── signals show ────────────────────────────────────────────────────────
+export async function governanceSignalsShowCommand(signalId, opts) {
+    await requireAuth();
+    const signal = await getGovernanceSignal(signalId);
+    if (opts.json) {
+        console.log(JSON.stringify(signal, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`Signal ${signal.id}`));
+    console.log(`  scope:     ${signal.scope} (${signal.scope_id})`);
+    console.log(`  source:    ${chalk.cyan(signal.source)}`);
+    console.log(`  pattern:   ${chalk.magenta(signal.pattern_type)}`);
+    console.log(`  severity:  ${severityColor(signal.severity)(signal.severity)}`);
+    console.log(`  status:    ${statusBadge(signal.status)}`);
+    console.log(`  detected:  ${signal.detected_at} by ${signal.detected_by}`);
+    console.log(`  org:       ${signal.org_id}`);
+    if (signal.team_id)
+        console.log(`  team:      ${signal.team_id}`);
+    console.log(`  agents:    ${signal.agent_ids.length === 0 ? "(none)" : signal.agent_ids.join(", ")}`);
+    if (signal.acknowledged_at) {
+        console.log(`  ack:       ${signal.acknowledged_at} (${signal.acknowledged_actor_role ?? "?"})${signal.acknowledged_by ? ` by ${signal.acknowledged_by}` : ""}`);
+    }
+    if (signal.resolved_at) {
+        console.log(`  resolved:  ${signal.resolved_at} (${signal.resolution_status ?? "?"})${signal.action_taken ? ` — ${signal.action_taken}` : ""}`);
+    }
+    if (Object.keys(signal.detail ?? {}).length > 0) {
+        console.log(chalk.dim("  detail:"));
+        console.log(JSON.stringify(signal.detail, null, 2)
+            .split("\n")
+            .map((l) => "    " + l)
+            .join("\n"));
+    }
+}
+// ─── signals ack/resolve/dismiss ─────────────────────────────────────────
+export async function governanceSignalsAckCommand(signalId, opts) {
+    await requireAuth();
+    const signal = await acknowledgeGovernanceSignal(signalId, {
+        action_taken: opts.action,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(signal, null, 2));
+        return;
+    }
+    console.log(chalk.green(`✓ Acknowledged ${signal.id} as ${signal.acknowledged_actor_role}.`));
+}
+export async function governanceSignalsResolveCommand(signalId, opts) {
+    await requireAuth();
+    const valid = [
+        "action_taken",
+        "wont_fix",
+        "duplicate",
+        "false_positive",
+        "self_resolved",
+    ];
+    if (!valid.includes(opts.status)) {
+        throw new Error(`--status must be one of: ${valid.join(", ")}`);
+    }
+    const signal = await resolveGovernanceSignal(signalId, {
+        resolution_status: opts.status,
+        action_taken: opts.action,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(signal, null, 2));
+        return;
+    }
+    console.log(chalk.green(`✓ Resolved ${signal.id} (${signal.resolution_status}).`));
+}
+export async function governanceSignalsDismissCommand(signalId, opts) {
+    await requireAuth();
+    const signal = await dismissGovernanceSignal(signalId, { reason: opts.reason });
+    if (opts.json) {
+        console.log(JSON.stringify(signal, null, 2));
+        return;
+    }
+    console.log(chalk.dim(`✓ Dismissed ${signal.id}.`));
+}
+// ─── destinations ────────────────────────────────────────────────────────
+function formatDestinationRow(d) {
+    return [
+        chalk.dim(shortId(d.id).padEnd(16)),
+        chalk.cyan(d.channel.padEnd(10)),
+        (d.display_name ?? "(unnamed)").slice(0, 32).padEnd(32),
+        d.enabled ? chalk.green("enabled") : chalk.dim("disabled"),
+        d.last_test_status === "ok"
+            ? chalk.green(`tested ✓ ${d.last_tested_at?.slice(0, 19) ?? ""}`)
+            : d.last_test_status === "failed"
+                ? chalk.red(`tested ✗ ${d.last_test_error?.slice(0, 64) ?? ""}`)
+                : chalk.dim("untested"),
+    ].join("  ");
+}
+export async function governanceDestinationsListCommand(opts) {
+    await requireAuth();
+    const result = await listGovernanceDestinations(opts.org);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.destinations.length === 0) {
+        console.log(chalk.dim("(no destinations configured for this org)"));
+        return;
+    }
+    for (const d of result.destinations)
+        console.log(formatDestinationRow(d));
+}
+export async function governanceDestinationsAddCommand(opts) {
+    await requireAuth();
+    const validChannels = [
+        "webhook",
+        "slack",
+        "email",
+        "pagerduty",
+    ];
+    if (!validChannels.includes(opts.channel)) {
+        throw new Error(`--channel must be one of: ${validChannels.join(", ")}`);
+    }
+    let config;
+    try {
+        config = JSON.parse(opts.config);
+    }
+    catch {
+        throw new Error("--config must be valid JSON");
+    }
+    let filter;
+    if (opts.filter) {
+        try {
+            filter = JSON.parse(opts.filter);
+        }
+        catch {
+            throw new Error("--filter must be valid JSON");
+        }
+    }
+    const dest = await createGovernanceDestination(opts.org, {
+        channel: opts.channel,
+        config,
+        filter,
+        display_name: opts.name,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(dest, null, 2));
+        return;
+    }
+    console.log(chalk.green(`✓ Created destination ${dest.id} (${dest.channel}).`));
+}
+export async function governanceDestinationsRemoveCommand(destinationId, opts) {
+    await requireAuth();
+    await deleteGovernanceDestination(opts.org, destinationId);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, removed: destinationId }, null, 2));
+        return;
+    }
+    console.log(chalk.green(`✓ Removed destination ${destinationId}.`));
+}
+export async function governanceDestinationsTestCommand(destinationId, opts) {
+    await requireAuth();
+    const result = await testGovernanceDestination(opts.org, destinationId);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.result.ok) {
+        console.log(chalk.green(`✓ Test signal delivered via ${result.channel} (${result.result.attempts} attempt).`));
+    }
+    else {
+        console.log(chalk.red(`✗ Test failed via ${result.channel}: ${result.result.last_error ?? "unknown"}`));
+        process.exitCode = 1;
+    }
+}
+// ─── rules ───────────────────────────────────────────────────────────────
+function formatRuleRow(r) {
+    return [
+        chalk.dim(shortId(r.id).padEnd(16)),
+        r.name.slice(0, 32).padEnd(32),
+        r.enabled ? chalk.green("enabled") : chalk.dim("disabled"),
+        chalk.dim(`fired ${r.fire_count}×`),
+        r.last_fired_at ? chalk.dim(`last ${r.last_fired_at.slice(0, 19)}`) : "",
+    ].join("  ");
+}
+export async function governanceRulesListCommand(opts) {
+    await requireAuth();
+    const result = await listGovernanceRules(opts.org);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.rules.length === 0) {
+        console.log(chalk.dim("(no escalation rules configured for this org)"));
+        return;
+    }
+    for (const r of result.rules)
+        console.log(formatRuleRow(r));
+}
+export async function governanceRulesAddCommand(opts) {
+    await requireAuth();
+    let predicate;
+    try {
+        predicate = JSON.parse(opts.predicate);
+    }
+    catch {
+        throw new Error("--predicate must be valid JSON");
+    }
+    const destinationIds = opts.destinations.split(",").map((s) => s.trim()).filter(Boolean);
+    if (destinationIds.length === 0) {
+        throw new Error("--destinations must list at least one destination ID (comma-separated)");
+    }
+    const rule = await createGovernanceRule(opts.org, {
+        name: opts.name,
+        predicate,
+        destination_ids: destinationIds,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(rule, null, 2));
+        return;
+    }
+    console.log(chalk.green(`✓ Created rule ${rule.id} ("${rule.name}").`));
+}
+export async function governanceRulesRemoveCommand(ruleId, opts) {
+    await requireAuth();
+    await deleteGovernanceRule(opts.org, ruleId);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, removed: ruleId }, null, 2));
+        return;
+    }
+    console.log(chalk.green(`✓ Removed rule ${ruleId}.`));
+}

package/dist/index.js

@@ -14,6 +14,7 @@ import { advisoriesListCommand, advisoriesShowCommand, } from "./commands/adviso
 import { postureListCommand, postureShowCommand, postureCreateCommand, postureUpdateCommand, postureCloneCommand, postureRevisionsCommand, postureDiffCommand, postureAssignCommand, postureUnassignCommand, posturePreviewComposeCommand, postureDeleteCommand, } from "./commands/posture.js";
 import { loginCommand, logoutCommand, whoamiCommand } from "./commands/auth.js";
 import { validateSafeHouseCommand } from "./commands/validate.js";
+import { apiKeyListCommand, apiKeyCreateCommand, apiKeyRotateCommand, apiKeyRevokeCommand, } from "./commands/api-key.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
@@ -521,6 +522,212 @@ advisoriesCmd
     }
 });
 // ============================================================================
+// Governance signals (ADR-048) — operator-actionable observation surface
+//
+// Distinct from `mnemom advisories list` (which now narrows to runtime.* /
+// manual.* per ADR-048 §1). Surfaces sideband.* + future protection.* /
+// posture.* signals from governance_signals: ack/resolve/dismiss workflow,
+// notification destinations (slack/email/pagerduty/webhook), escalation
+// rules.
+// ============================================================================
+import { governanceSignalsListCommand, governanceSignalsShowCommand, governanceSignalsAckCommand, governanceSignalsResolveCommand, governanceSignalsDismissCommand, governanceDestinationsListCommand, governanceDestinationsAddCommand, governanceDestinationsRemoveCommand, governanceDestinationsTestCommand, governanceRulesListCommand, governanceRulesAddCommand, governanceRulesRemoveCommand, } from "./commands/governance.js";
+const governanceCmd = program
+    .command("governance")
+    .description("Operator workflow for governance_signals (ADR-048)");
+const govSignalsCmd = governanceCmd
+    .command("signals")
+    .description("List, inspect, and transition governance_signals");
+govSignalsCmd
+    .command("list")
+    .description("List governance signals at platform/org/team/agent scope")
+    .option("--org <id>", "Org scope")
+    .option("--team <id>", "Team scope")
+    .option("--agent <id>", "Per-agent slice (signals affecting this agent)")
+    .option("--source <s>", "Filter by source (sideband.{drift,coherence,fault_line,fleet})")
+    .option("--severity <s>", "Filter by severity (info|warn|high|critical)")
+    .option("--status <s>", "Filter by status (open|acknowledged|resolved|dismissed|expired)")
+    .option("--scope <s>", "Filter by scope (platform|org|team|agent)")
+    .option("--pattern-type <s>", "Filter by pattern_type")
+    .option("--since <iso>", "Detected since (ISO timestamp)")
+    .option("--limit <n>", "Max rows (default 100, max 500)")
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+    try {
+        await governanceSignalsListCommand(options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govSignalsCmd
+    .command("show <signal_id>")
+    .description("Show one signal in detail")
+    .option("--json", "Output JSON")
+    .action(async (signalId, options) => {
+    try {
+        await governanceSignalsShowCommand(signalId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govSignalsCmd
+    .command("ack <signal_id>")
+    .description("Acknowledge an open signal (org_admin / org_owner)")
+    .option("--action <text>", "Operator-authored action note")
+    .option("--json", "Output JSON")
+    .action(async (signalId, options) => {
+    try {
+        await governanceSignalsAckCommand(signalId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govSignalsCmd
+    .command("resolve <signal_id>")
+    .description("Resolve a signal with a resolution status")
+    .requiredOption("--status <s>", "Resolution status (action_taken|wont_fix|duplicate|false_positive|self_resolved)")
+    .option("--action <text>", "Operator-authored action note")
+    .option("--json", "Output JSON")
+    .action(async (signalId, options) => {
+    try {
+        await governanceSignalsResolveCommand(signalId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govSignalsCmd
+    .command("dismiss <signal_id>")
+    .description("Dismiss a signal as not actionable")
+    .option("--reason <text>", "Operator-authored dismissal reason")
+    .option("--json", "Output JSON")
+    .action(async (signalId, options) => {
+    try {
+        await governanceSignalsDismissCommand(signalId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+const govDestCmd = governanceCmd
+    .command("destinations")
+    .description("Manage notification destinations (slack/email/pagerduty/webhook)");
+govDestCmd
+    .command("list")
+    .description("List destinations for an org")
+    .requiredOption("--org <id>", "Org ID")
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+    try {
+        await governanceDestinationsListCommand(options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govDestCmd
+    .command("add")
+    .description("Add a destination (channel + JSON config)")
+    .requiredOption("--org <id>", "Org ID")
+    .requiredOption("--channel <c>", "webhook|slack|email|pagerduty")
+    .requiredOption("--config <json>", "Channel config (e.g., '{\"url\":\"...\",\"signing_secret\":\"...\"}')")
+    .option("--name <n>", "Display name")
+    .option("--filter <json>", "Filter narrowing (sources/severities/etc)")
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+    try {
+        await governanceDestinationsAddCommand(options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govDestCmd
+    .command("remove <destination_id>")
+    .description("Remove a destination")
+    .requiredOption("--org <id>", "Org ID")
+    .option("--json", "Output JSON")
+    .action(async (id, options) => {
+    try {
+        await governanceDestinationsRemoveCommand(id, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govDestCmd
+    .command("test <destination_id>")
+    .description("Send a synthetic test signal through this destination")
+    .requiredOption("--org <id>", "Org ID")
+    .option("--json", "Output JSON")
+    .action(async (id, options) => {
+    try {
+        await governanceDestinationsTestCommand(id, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+const govRulesCmd = governanceCmd
+    .command("rules")
+    .description("Manage escalation rules (predicate → destinations)");
+govRulesCmd
+    .command("list")
+    .description("List escalation rules for an org")
+    .requiredOption("--org <id>", "Org ID")
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+    try {
+        await governanceRulesListCommand(options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govRulesCmd
+    .command("add")
+    .description("Add an escalation rule (predicate JSON + destination IDs)")
+    .requiredOption("--org <id>", "Org ID")
+    .requiredOption("--name <n>", "Rule name")
+    .requiredOption("--predicate <json>", "Predicate JSON (e.g., '{\"source\":\"sideband.fleet\",\"severity_min\":\"high\"}')")
+    .requiredOption("--destinations <ids>", "Comma-separated destination IDs")
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+    try {
+        await governanceRulesAddCommand(options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+govRulesCmd
+    .command("remove <rule_id>")
+    .description("Remove an escalation rule")
+    .requiredOption("--org <id>", "Org ID")
+    .option("--json", "Output JSON")
+    .action(async (id, options) => {
+    try {
+        await governanceRulesRemoveCommand(id, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+// ============================================================================
 // Trust Posture (Piece 3 of T1-3.1, ADR-045)
 //
 // Postures are team-scoped policy input that drives the observer's sideband
@@ -764,4 +971,68 @@ validateCmd
         process.exit(1);
     }
 });
+// ── api-key (ADR-049 capability-based scopes) ────────────────────────────
+const apiKeyCmd = program
+    .command("api-key")
+    .description("Manage personal API keys (capability-based scopes — ADR-049)");
+apiKeyCmd
+    .command("list")
+    .description("List your active personal API keys with their scope sets")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (options) => {
+    try {
+        await apiKeyListCommand({ json: options.json });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+apiKeyCmd
+    .command("create")
+    .description("Mint a new personal API key. Default scopes: gateway, api:read, api:write. " +
+    "Admin scopes (admin:org, admin:platform) are role-gated at mint time.")
+    .requiredOption("--name <name>", "Friendly name for the key (e.g. 'ci-prod')")
+    .option("--scopes <list>", "Comma-separated capability scopes. Valid: " +
+    "gateway, api:read, api:write, admin:org, admin:platform. " +
+    "Default: gateway,api:read,api:write")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (options) => {
+    try {
+        await apiKeyCreateCommand({
+            name: options.name,
+            scopes: options.scopes,
+            json: options.json,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+apiKeyCmd
+    .command("rotate <key_id>")
+    .description("Atomic mint-new + revoke-old. Returns the new cleartext once.")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (keyId, options) => {
+    try {
+        await apiKeyRotateCommand(keyId, { json: options.json });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+apiKeyCmd
+    .command("revoke <key_id>")
+    .description("Soft-revoke an active key. Action is immediate and irreversible.")
+    .action(async (keyId) => {
+    try {
+        await apiKeyRevokeCommand(keyId);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 program.parse();

package/dist/lib/api.d.ts

@@ -645,4 +645,187 @@ export declare function getSafeHouseHarnessState(): Promise<{
     full: HarnessRunSummary | null;
     fast: HarnessRunSummary | null;
 }>;
+export type GovernanceSignalScope = "platform" | "org" | "team" | "agent";
+export type GovernanceSignalSource = "sideband.drift" | "sideband.coherence" | "sideband.fault_line" | "sideband.fleet";
+export type GovernanceSignalSeverity = "info" | "warn" | "high" | "critical";
+export type GovernanceSignalStatus = "open" | "acknowledged" | "resolved" | "dismissed" | "expired";
+export type GovernanceResolutionStatus = "action_taken" | "wont_fix" | "duplicate" | "false_positive" | "self_resolved";
+export type GovernanceNotificationChannel = "webhook" | "slack" | "email" | "pagerduty";
+export interface GovernanceSignal {
+    id: string;
+    scope: GovernanceSignalScope;
+    scope_id: string;
+    source: GovernanceSignalSource;
+    pattern_type: string;
+    severity: GovernanceSignalSeverity;
+    detected_at: string;
+    detected_by: string;
+    org_id: string;
+    team_id: string | null;
+    agent_ids: string[];
+    detail: Record<string, unknown>;
+    source_ref: Record<string, unknown>;
+    status: GovernanceSignalStatus;
+    acknowledged_by: string | null;
+    acknowledged_at: string | null;
+    acknowledged_actor_role: string | null;
+    resolution_status: GovernanceResolutionStatus | null;
+    action_taken: string | null;
+    resolved_by: string | null;
+    resolved_at: string | null;
+    expires_at: string | null;
+    notification_state: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface GovernanceDestination {
+    id: string;
+    org_id: string;
+    channel: GovernanceNotificationChannel;
+    config: Record<string, unknown>;
+    filter: Record<string, unknown>;
+    enabled: boolean;
+    display_name: string | null;
+    last_tested_at: string | null;
+    last_test_status: "ok" | "failed" | null;
+    last_test_error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface GovernanceRule {
+    id: string;
+    org_id: string;
+    name: string;
+    predicate: Record<string, unknown>;
+    destination_ids: string[];
+    enabled: boolean;
+    last_fired_at: string | null;
+    fire_count: number;
+    created_at: string;
+    updated_at: string;
+}
+interface SignalListFilters {
+    source?: string;
+    severity?: string;
+    status?: string;
+    scope?: string;
+    pattern_type?: string;
+    since?: string;
+    limit?: number;
+}
+export declare function listGovernanceSignalsForOrg(orgId: string, opts?: SignalListFilters): Promise<{
+    org_id: string;
+    signals: GovernanceSignal[];
+}>;
+export declare function listGovernanceSignalsForTeam(teamId: string, opts?: SignalListFilters): Promise<{
+    team_id: string;
+    signals: GovernanceSignal[];
+}>;
+export declare function listGovernanceSignalsForAgent(agentId: string, opts?: SignalListFilters): Promise<{
+    agent_id: string;
+    signals: GovernanceSignal[];
+}>;
+export declare function getGovernanceSignal(id: string): Promise<GovernanceSignal>;
+export declare function acknowledgeGovernanceSignal(id: string, body?: {
+    action_taken?: string;
+}): Promise<GovernanceSignal>;
+export declare function resolveGovernanceSignal(id: string, body: {
+    resolution_status: GovernanceResolutionStatus;
+    action_taken?: string;
+}): Promise<GovernanceSignal>;
+export declare function dismissGovernanceSignal(id: string, body?: {
+    reason?: string;
+}): Promise<GovernanceSignal>;
+export declare function listGovernanceDestinations(orgId: string): Promise<{
+    org_id: string;
+    destinations: GovernanceDestination[];
+}>;
+export declare function createGovernanceDestination(orgId: string, body: {
+    channel: GovernanceNotificationChannel;
+    config: Record<string, unknown>;
+    filter?: Record<string, unknown>;
+    display_name?: string;
+    enabled?: boolean;
+}): Promise<GovernanceDestination>;
+export declare function deleteGovernanceDestination(orgId: string, destinationId: string): Promise<{
+    ok: true;
+}>;
+export declare function testGovernanceDestination(orgId: string, destinationId: string): Promise<{
+    destination_id: string;
+    channel: GovernanceNotificationChannel;
+    result: {
+        ok: boolean;
+        attempts: number;
+        delivered_at?: string;
+        last_error?: string;
+    };
+}>;
+export declare function listGovernanceRules(orgId: string): Promise<{
+    org_id: string;
+    rules: GovernanceRule[];
+}>;
+export declare function createGovernanceRule(orgId: string, body: {
+    name: string;
+    predicate: Record<string, unknown>;
+    destination_ids: string[];
+    enabled?: boolean;
+}): Promise<GovernanceRule>;
+export declare function deleteGovernanceRule(orgId: string, ruleId: string): Promise<{
+    ok: true;
+}>;
+/**
+ * Capability-based scope vocabulary (ADR-049). Mirrors the API's
+ * VALID_SCOPES exactly. Update both surfaces together when the
+ * vocabulary changes.
+ */
+export declare const API_KEY_SCOPES: readonly ["gateway", "api:read", "api:write", "admin:org", "admin:platform"];
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+export declare const DEFAULT_API_KEY_SCOPES: ApiKeyScope[];
+/**
+ * Recognize legacy two-scope sets so the CLI can annotate pre-ADR-049
+ * keys appropriately. Mirror of mnemom-api `expandLegacyScopes` logic
+ * for display purposes; the auth gate handles the actual aliasing.
+ */
+export declare function isLegacyScopeSet(scopes: string[] | undefined): boolean;
+export interface ApiKeyListItem {
+    key_id: string;
+    key_prefix: string;
+    name: string;
+    scopes: string[];
+    created_at: string;
+    last_used_at: string | null;
+    org_id?: string | null;
+}
+export interface ApiKeyCreated {
+    key_id: string;
+    key: string;
+    key_prefix: string;
+    name: string;
+    scopes: string[];
+    created_at: string;
+}
+/**
+ * GET /v1/api-keys — list the caller's active personal API keys.
+ */
+export declare function listApiKeys(): Promise<ApiKeyListItem[]>;
+/**
+ * POST /v1/api-keys — mint a new personal API key with explicit scopes.
+ *
+ * Returns the full secret only on this call. The mint-time ceiling
+ * rejects admin scopes the caller is not eligible for (admin:platform
+ * for non-staff, admin:org for users not in any org-admin role).
+ */
+export declare function createApiKey(name: string, scopes: ApiKeyScope[]): Promise<ApiKeyCreated>;
+/**
+ * POST /v1/api-keys/{key_id}/rotate — atomic mint-new + revoke-old.
+ * Returns the full new secret only on this call. The new key inherits
+ * the old key's name and scopes verbatim; the old key is revoked the
+ * moment this returns.
+ */
+export declare function rotateApiKey(keyId: string): Promise<ApiKeyCreated>;
+/**
+ * DELETE /v1/api-keys/{key_id} — soft-revoke. The key row stays for
+ * audit; `is_active` flips to false and `revoked_at` is timestamped.
+ */
+export declare function revokeApiKey(keyId: string): Promise<void>;
 export {};

package/dist/lib/api.js

@@ -1162,3 +1162,211 @@ export async function getSafeHouseHarnessState() {
     }
     return (await response.json());
 }
+function buildSignalListQuery(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.source)
+        params.set("source", opts.source);
+    if (opts.severity)
+        params.set("severity", opts.severity);
+    if (opts.status)
+        params.set("status", opts.status);
+    if (opts.scope)
+        params.set("scope", opts.scope);
+    if (opts.pattern_type)
+        params.set("pattern_type", opts.pattern_type);
+    if (opts.since)
+        params.set("since", opts.since);
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+async function gFetch(path, init = {}, notFoundLabel) {
+    const url = validateUrl(`${API_BASE}${path}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: init.method ?? "GET",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            ...(init.body ? { "Content-Type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+        },
+        body: init.body,
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error("Permission denied (need org admin / membership).");
+        if (response.status === 404 && notFoundLabel)
+            throw new Error(`${notFoundLabel} not found.`);
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+export async function listGovernanceSignalsForOrg(orgId, opts = {}) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Org");
+}
+export async function listGovernanceSignalsForTeam(teamId, opts = {}) {
+    return gFetch(`/v1/teams/${encodeURIComponent(teamId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Team");
+}
+export async function listGovernanceSignalsForAgent(agentId, opts = {}) {
+    return gFetch(`/v1/agents/${encodeURIComponent(agentId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Agent");
+}
+export async function getGovernanceSignal(id) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}`, {}, "Signal");
+}
+export async function acknowledgeGovernanceSignal(id, body = {}) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/acknowledge`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+}
+export async function resolveGovernanceSignal(id, body) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/resolve`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+}
+export async function dismissGovernanceSignal(id, body = {}) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/dismiss`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+}
+export async function listGovernanceDestinations(orgId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, {}, "Org");
+}
+export async function createGovernanceDestination(orgId, body) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, { method: "POST", body: JSON.stringify(body) }, "Org");
+}
+export async function deleteGovernanceDestination(orgId, destinationId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}`, { method: "DELETE" }, "Destination");
+}
+export async function testGovernanceDestination(orgId, destinationId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}/test`, { method: "POST", body: JSON.stringify({}) }, "Destination");
+}
+export async function listGovernanceRules(orgId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, {}, "Org");
+}
+export async function createGovernanceRule(orgId, body) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, { method: "POST", body: JSON.stringify(body) }, "Org");
+}
+export async function deleteGovernanceRule(orgId, ruleId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules/${encodeURIComponent(ruleId)}`, { method: "DELETE" }, "Rule");
+}
+// ─── api-keys (ADR-049) ─────────────────────────────────────────────────
+/**
+ * Capability-based scope vocabulary (ADR-049). Mirrors the API's
+ * VALID_SCOPES exactly. Update both surfaces together when the
+ * vocabulary changes.
+ */
+export const API_KEY_SCOPES = [
+    "gateway",
+    "api:read",
+    "api:write",
+    "admin:org",
+    "admin:platform",
+];
+export const DEFAULT_API_KEY_SCOPES = [
+    "gateway",
+    "api:read",
+    "api:write",
+];
+/**
+ * Recognize legacy two-scope sets so the CLI can annotate pre-ADR-049
+ * keys appropriately. Mirror of mnemom-api `expandLegacyScopes` logic
+ * for display purposes; the auth gate handles the actual aliasing.
+ */
+export function isLegacyScopeSet(scopes) {
+    if (!scopes || scopes.length === 0)
+        return false;
+    if (scopes.length === 2 && scopes.includes("gateway") && scopes.includes("api")) {
+        return true;
+    }
+    if (scopes.length === 1 && scopes[0] === "api")
+        return true;
+    return false;
+}
+/**
+ * GET /v1/api-keys — list the caller's active personal API keys.
+ */
+export async function listApiKeys() {
+    const url = validateUrl(`${API_BASE}/v1/api-keys`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Failed to list api keys: ${response.status}`);
+    }
+    const data = (await response.json());
+    return data.keys ?? [];
+}
+/**
+ * POST /v1/api-keys — mint a new personal API key with explicit scopes.
+ *
+ * Returns the full secret only on this call. The mint-time ceiling
+ * rejects admin scopes the caller is not eligible for (admin:platform
+ * for non-staff, admin:org for users not in any org-admin role).
+ */
+export async function createApiKey(name, scopes) {
+    const url = validateUrl(`${API_BASE}/v1/api-keys`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: { ...(await authHeaders()), "Content-Type": "application/json" },
+        body: JSON.stringify({ name, scopes }),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        const body = await response.text().catch(() => "");
+        if (response.status === 403) {
+            throw new Error(`Mint-time ceiling rejected scope: ${body}`);
+        }
+        if (response.status === 400) {
+            throw new Error(`Invalid scope(s): ${body}`);
+        }
+        throw new Error(`Failed to create api key: ${response.status} ${body}`);
+    }
+    return (await response.json());
+}
+/**
+ * POST /v1/api-keys/{key_id}/rotate — atomic mint-new + revoke-old.
+ * Returns the full new secret only on this call. The new key inherits
+ * the old key's name and scopes verbatim; the old key is revoked the
+ * moment this returns.
+ */
+export async function rotateApiKey(keyId) {
+    const url = validateUrl(`${API_BASE}/v1/api-keys/${encodeURIComponent(keyId)}/rotate`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: { ...(await authHeaders()), "Content-Type": "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        if (response.status === 404)
+            throw new Error(`Key not found: ${keyId}`);
+        const body = await response.text().catch(() => "");
+        throw new Error(`Failed to rotate api key: ${response.status} ${body}`);
+    }
+    return (await response.json());
+}
+/**
+ * DELETE /v1/api-keys/{key_id} — soft-revoke. The key row stays for
+ * audit; `is_active` flips to false and `revoked_at` is timestamped.
+ */
+export async function revokeApiKey(keyId) {
+    const url = validateUrl(`${API_BASE}/v1/api-keys/${encodeURIComponent(keyId)}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "DELETE",
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        if (response.status === 404)
+            throw new Error(`Key not found: ${keyId}`);
+        const body = await response.text().catch(() => "");
+        throw new Error(`Failed to revoke api key: ${response.status} ${body}`);
+    }
+}

package/dist/lib/format.d.ts

@@ -24,6 +24,10 @@ export declare const fmt: {
      * Dim label with value
      */
     label(key: string, val: string): string;
+    /**
+     * Dim text (for inline annotations and footnotes).
+     */
+    dim(text: string): string;
     /**
      * Syntax-highlighted JSON output
      */

package/dist/lib/format.js

@@ -38,6 +38,12 @@ export const fmt = {
     label(key, val) {
         return `${chalk.dim(key)} ${val}`;
     },
+    /**
+     * Dim text (for inline annotations and footnotes).
+     */
+    dim(text) {
+        return chalk.dim(text);
+    },
     /**
      * Syntax-highlighted JSON output
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {