@mnemom/mnemom 0.16.2 → 0.16.3

package/dist/commands/onboard.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `mnemom onboard` — self-onboard the CALLING coding agent end-to-end (MNE-933,
+ * A2, epic MNE-931). Job #1 of the skill lane.
+ *
+ * Walks the canonical `become_sovereign` sequence for the agent that is calling
+ * right now — scan its trust posture, claim its identity, declare an alignment
+ * card, surface its Trust Rating, and hand back a public badge URL — in one
+ * command, with no manifest and no hand-assembled sub-command chain.
+ *
+ *   scan_trust → claim → alignment → rating → badge
+ *
+ * AUTH MODEL (the confirmed MNE-944 contract):
+ *   - The calling agent authenticates as ITS OWN principal via the device-grant
+ *     OAuth flow (`loginWithDeviceFlow`) — deliberately NOT the human's full
+ *     org-membership session (the MNE-870 lesson).
+ *   - The per-agent `agent:<id>:cards:write` scope is standing, minted server-
+ *     side at claim; that scope alone authorizes the alignment PUT. No separate
+ *     protection-capability mint, no protection card, no grant handoff, no
+ *     dojo bind — those belong to the try-me / dojo flow, not this skill.
+ *   - Claiming needs a proof of key possession. The claim endpoint's client
+ *     contract (`claimAgent`) requires a `hash_proof` on every call regardless
+ *     of the OAuth principal, so `--key` (or `--hash-proof`) is REQUIRED to
+ *     claim a not-yet-claimed agent; an already-claimed agent skips the claim
+ *     entirely (idempotency). Claiming lands in the agent's PERSONAL org by
+ *     default (`getMyPersonalOrg`), never silently into a shared org.
+ *
+ * HUMAN-IN-THE-LOOP: the only mutation is the agent's own alignment-card
+ * declaration, authorized by its own standing scoped token. Every privileged
+ * act (protection card, grant, dojo bind, org move) stays server/human-gated
+ * and is intentionally out of scope here.
+ *
+ * The Trust Rating surfaced here is the CLI-reachable `integrity_score`. On a
+ * clean-machine first run the agent has 0 traces, so the rating is reported as
+ * `provisional` — never a bare perfect score. The SIGNED Trust Rating and the
+ * rendered public badge are computed server-side (observer / mnemom-api, post-
+ * hoc) and become authoritative once the observer pipeline generates traces.
+ *
+ * See SKILL-RUNNER-CONTRACT.md §2–§4 for the lifecycle + --json output contract.
+ */
+export interface OnboardOptions {
+    /** Machine-readable output (implies non-interactive). */
+    json?: boolean;
+    /** Non-interactive: accept defaults, skip all prompts. */
+    yes?: boolean;
+    /** The calling agent's id (else agent-config → MNEMOM_AGENT → prompt). */
+    agent?: string;
+    /** Commander `--no-open` sets this false → never auto-open the badge URL. */
+    open?: boolean;
+    /** The agent's provider API key — the CLI derives the claim hash proof from it. */
+    key?: string;
+    /** A pre-computed 64-hex hash proof (advanced/CI; alternative to --key). */
+    hashProof?: string;
+}
+/**
+ * Entry point for `mnemom onboard`. Throws on a fatal error (caught by the
+ * index.ts wrapper, which prints + exits non-zero); non-fatal steps degrade to
+ * `skipped`/`error` and the run still reports a `partial` verdict.
+ */
+export declare function onboardCommand(options?: OnboardOptions): Promise<void>;

package/dist/commands/onboard.js

@@ -0,0 +1,395 @@
+/**
+ * `mnemom onboard` — self-onboard the CALLING coding agent end-to-end (MNE-933,
+ * A2, epic MNE-931). Job #1 of the skill lane.
+ *
+ * Walks the canonical `become_sovereign` sequence for the agent that is calling
+ * right now — scan its trust posture, claim its identity, declare an alignment
+ * card, surface its Trust Rating, and hand back a public badge URL — in one
+ * command, with no manifest and no hand-assembled sub-command chain.
+ *
+ *   scan_trust → claim → alignment → rating → badge
+ *
+ * AUTH MODEL (the confirmed MNE-944 contract):
+ *   - The calling agent authenticates as ITS OWN principal via the device-grant
+ *     OAuth flow (`loginWithDeviceFlow`) — deliberately NOT the human's full
+ *     org-membership session (the MNE-870 lesson).
+ *   - The per-agent `agent:<id>:cards:write` scope is standing, minted server-
+ *     side at claim; that scope alone authorizes the alignment PUT. No separate
+ *     protection-capability mint, no protection card, no grant handoff, no
+ *     dojo bind — those belong to the try-me / dojo flow, not this skill.
+ *   - Claiming needs a proof of key possession. The claim endpoint's client
+ *     contract (`claimAgent`) requires a `hash_proof` on every call regardless
+ *     of the OAuth principal, so `--key` (or `--hash-proof`) is REQUIRED to
+ *     claim a not-yet-claimed agent; an already-claimed agent skips the claim
+ *     entirely (idempotency). Claiming lands in the agent's PERSONAL org by
+ *     default (`getMyPersonalOrg`), never silently into a shared org.
+ *
+ * HUMAN-IN-THE-LOOP: the only mutation is the agent's own alignment-card
+ * declaration, authorized by its own standing scoped token. Every privileged
+ * act (protection card, grant, dojo bind, org move) stays server/human-gated
+ * and is intentionally out of scope here.
+ *
+ * The Trust Rating surfaced here is the CLI-reachable `integrity_score`. On a
+ * clean-machine first run the agent has 0 traces, so the rating is reported as
+ * `provisional` — never a bare perfect score. The SIGNED Trust Rating and the
+ * rendered public badge are computed server-side (observer / mnemom-api, post-
+ * hoc) and become authoritative once the observer pipeline generates traces.
+ *
+ * See SKILL-RUNNER-CONTRACT.md §2–§4 for the lifecycle + --json output contract.
+ */
+import { getAgent, getIntegrity, claimAgent, putAlignmentCard, getMyPersonalOrg, MnemomApiError, } from "../lib/api.js";
+import { resolveAuth, loginWithDeviceFlow } from "../lib/auth.js";
+import { getAgentId, getAgentName, mergeAgentConfig } from "../lib/agent-config.js";
+import { deriveHashProof } from "./agents.js";
+import { isInteractive, askInput, askYesNo } from "../lib/prompt.js";
+import { getWebsiteUrl } from "../lib/config.js";
+import { openBrowser } from "../lib/oauth.js";
+import { fmt } from "../lib/format.js";
+const FULL_PROOF_RE = /^[0-9a-f]{64}$/;
+/**
+ * Entry point for `mnemom onboard`. Throws on a fatal error (caught by the
+ * index.ts wrapper, which prints + exits non-zero); non-fatal steps degrade to
+ * `skipped`/`error` and the run still reports a `partial` verdict.
+ */
+export async function onboardCommand(options = {}) {
+    const json = !!options.json;
+    const nonInteractive = !!options.yes || json || !isInteractive();
+    const autoOpen = options.open !== false; // --no-open → false
+    const steps = [];
+    // A human-facing log that is silenced in --json mode (the JSON is the output).
+    const say = (line = "") => {
+        if (!json)
+            console.log(line);
+    };
+    const result = {
+        skill: "onboard",
+        verdict: "error",
+        agent_id: null,
+        claimed: false,
+        card_published: false,
+        rating: null,
+        badge_url: null,
+        next_step: null,
+        steps,
+    };
+    say(fmt.header("Mnemom — onboard"));
+    say();
+    say(fmt.dim("Self-onboard this agent: scan → claim → declare → rating → badge."));
+    // Resolve the calling agent's id (no network).
+    const agentId = await resolveCallingAgentId(options, nonInteractive, say);
+    result.agent_id = agentId;
+    // ── State 1: scan_trust ─────────────────────────────────────────────────────
+    const posture = await scanTrust(agentId, steps, say);
+    // ── State 2: claim identity ─────────────────────────────────────────────────
+    await ensureAgentSession(nonInteractive, result, json, say);
+    if (posture.alreadyClaimed) {
+        result.claimed = true;
+        steps.push({ step: "claim", status: "skipped", detail: "already claimed" });
+        say(fmt.success("Already claimed — nothing to do."));
+    }
+    else {
+        await claimIdentity(agentId, posture.name, options, result, json, steps, say);
+    }
+    // ── State 3: declare alignment card ─────────────────────────────────────────
+    say();
+    say(`${fmt.badge("alignment", "cyan")} Declaring your alignment card…`);
+    try {
+        await putAlignmentCard(agentId, JSON.stringify(buildStarterAlignmentCard(agentId)), "application/json", 
+        // A STABLE key so a re-run replays the same server-side reservation
+        // (idempotent no-op) rather than writing a divergent duplicate card.
+        { idempotencyKey: `onboard-alignment-${agentId}` });
+        result.card_published = true;
+        steps.push({ step: "alignment", status: "ok" });
+        say(fmt.success("Alignment card declared."));
+    }
+    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 — declare it later with \`mnemom card publish\`. (${msg})`));
+    }
+    // ── State 4: earn Trust Rating ──────────────────────────────────────────────
+    result.rating = await earnRating(agentId, steps, say);
+    // ── State 5: badge ──────────────────────────────────────────────────────────
+    const badgeUrl = `${getWebsiteUrl().replace(/\/$/, "")}/agents/${encodeURIComponent(agentId)}`;
+    result.badge_url = badgeUrl;
+    steps.push({ step: "badge", status: "ok", detail: badgeUrl });
+    say();
+    say(`${fmt.badge("badge", "cyan")} Your public agent page:`);
+    say(fmt.label("  Badge:", badgeUrl));
+    if (!nonInteractive && autoOpen) {
+        const open = await askYesNo("Open your badge page in a browser?", true);
+        if (open)
+            openBrowser(badgeUrl);
+    }
+    // ── Report ──────────────────────────────────────────────────────────────────
+    result.verdict = result.claimed && result.card_published ? "ok" : "partial";
+    result.next_step = result.card_published ? null : "declare";
+    say();
+    say(renderRecount(result));
+    if (json)
+        console.log(JSON.stringify(result, null, 2));
+}
+// ── identity resolution ────────────────────────────────────────────────────────
+/**
+ * Resolve the calling agent's id: --agent → agent-config (`getAgentId`) →
+ * MNEMOM_AGENT → an interactive prompt. Fails CLOSED with a clear, actionable
+ * error when nothing is available and we can't prompt — never proceeds silently.
+ */
+async function resolveCallingAgentId(options, nonInteractive, say) {
+    const fromFlag = options.agent?.trim();
+    if (fromFlag)
+        return fromFlag;
+    const fromConfig = getAgentId();
+    if (fromConfig) {
+        say(fmt.dim(`Using saved agent id ${fromConfig} (override with --agent).`));
+        return fromConfig;
+    }
+    const fromEnv = process.env.MNEMOM_AGENT?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (nonInteractive) {
+        throw new Error("No agent identity to onboard. Pass --agent <id>, set MNEMOM_AGENT, or run " +
+            "`mnemom wrap` first to provision one.");
+    }
+    const typed = (await askInput("Which agent id should I onboard?")).trim();
+    if (!typed) {
+        throw new Error("An agent id is required. Pass --agent <id>, set MNEMOM_AGENT, or run `mnemom wrap` first.");
+    }
+    return typed;
+}
+// ── State 1: scan_trust ────────────────────────────────────────────────────────
+/**
+ * Read the calling agent's CURRENT posture before we claim/declare, so the run
+ * can report "here is what you look like now" first. A not-yet-visible or
+ * unclaimed agent is a cold read that must degrade gracefully (report
+ * `unclaimed`/`unknown`, status `ok` with a detail — never crash the run).
+ */
+async function scanTrust(agentId, steps, say) {
+    say();
+    say(`${fmt.badge("scan_trust", "cyan")} Reading your current trust posture…`);
+    let alreadyClaimed = false;
+    let name;
+    const parts = [];
+    try {
+        const agent = await getAgent(agentId);
+        alreadyClaimed = agent.claimed === true || !!agent.claimed_by;
+        name = agent.name ?? undefined;
+        parts.push(alreadyClaimed ? "claimed" : "unclaimed");
+    }
+    catch {
+        // Cold read: the agent isn't visible to us yet (unclaimed/unknown/offline).
+        parts.push("unknown (not yet visible)");
+    }
+    try {
+        const integ = await getIntegrity(agentId);
+        parts.push(`integrity_score ${integ.integrity_score.toFixed(2)} (${integ.total_traces} traces)`);
+    }
+    catch {
+        parts.push("integrity unavailable");
+    }
+    const detail = parts.join(", ");
+    steps.push({ step: "scan_trust", status: "ok", detail });
+    say(fmt.dim(`  ${detail}`));
+    return { alreadyClaimed, name: name ?? getAgentName() };
+}
+// ── State 2: claim identity ────────────────────────────────────────────────────
+/**
+ * Ensure a device-grant session as the AGENT principal before the claim/declare
+ * mutations. If no credential is present, run the device-grant OAuth flow (the
+ * agent's own principal — never the human's full org-membership creds, MNE-944 /
+ * MNE-870). In non-interactive mode with no session we fail CLOSED with a clear
+ * error rather than hanging or silently degrading.
+ */
+async function ensureAgentSession(nonInteractive, result, json, say) {
+    const cred = await resolveAuth();
+    if (cred.type !== "none")
+        return;
+    if (nonInteractive) {
+        result.steps.push({ step: "claim", status: "error", detail: "no session" });
+        if (json)
+            console.log(JSON.stringify(result, null, 2));
+        throw new Error("Authentication required. Run `mnemom login`, or set MNEMOM_TOKEN / MNEMOM_API_KEY, " +
+            "then re-run `mnemom onboard`.");
+    }
+    say();
+    say(fmt.dim("Signing this agent in via the device-grant flow (its own principal)…"));
+    await loginWithDeviceFlow();
+    say(fmt.success("Signed in."));
+}
+/**
+ * Claim the agent into the caller's PERSONAL org, deriving the hash proof from
+ * `--key` (or accepting `--hash-proof` directly). The claim endpoint requires a
+ * proof on every call, so a fresh claim needs one; an already-claimed agent
+ * never reaches here (the caller skips claim on `posture.alreadyClaimed`). The
+ * 403/409/503 taxonomy is mapped to the same teaching errors `agents.ts` uses.
+ */
+async function claimIdentity(agentId, scannedName, options, result, json, steps, say) {
+    say();
+    say(`${fmt.badge("claim", "cyan")} Claiming your identity…`);
+    const hashProof = resolveHashProof(options, scannedName);
+    if (!hashProof) {
+        steps.push({ step: "claim", status: "error", detail: "no key proof" });
+        if (json)
+            console.log(JSON.stringify(result, null, 2));
+        throw new Error("Claiming needs proof you hold the agent's key. Pass --key <agent-api-key> (the CLI " +
+            "derives the proof), or --hash-proof <64-hex> directly.");
+    }
+    // Land in the agent's personal org by default — never a shared org silently.
+    let orgId;
+    try {
+        orgId = (await getMyPersonalOrg()).org_id;
+    }
+    catch {
+        // Fall back to the server default (personal org) rather than aborting; the
+        // claim below still lands personal when orgId is omitted.
+        orgId = undefined;
+    }
+    try {
+        const claim = await claimAgent(agentId, { hashProof, orgId });
+        result.claimed = claim.claimed;
+        steps.push({ step: "claim", status: "ok", detail: agentId });
+        mergeAgentConfig({ agent_id: agentId, org_id: claim.org_id ?? orgId });
+        say(fmt.success(`Claimed ${claim.agent_id}.`));
+    }
+    catch (err) {
+        if (err instanceof MnemomApiError) {
+            const status = err.effectiveStatus;
+            // Specific 403 taxonomy + 503 are classified FIRST, before the idempotency
+            // branch. A cross-tenant/org-not-member 403 carries an "already claimed"
+            // message, so matching that message loosely here would misclassify a
+            // genuine failure as a harmless skip (fail-open) — so idempotency is gated
+            // on status/code only, and comes last.
+            if (status === 403 &&
+                (err.code === "invalid_hash_proof" || /hash[ _]?proof/i.test(err.message))) {
+                throw teachingClaimError(agentId, "the --key (and agent name) didn't match the agent's stored proof (invalid hash proof).", "Confirm --key is the exact provider key the agent runs with. If the name couldn't be " +
+                    `auto-resolved, pass it via \`mnemom agents claim ${agentId} --key <key> --name <name>\`.`, json, result, steps);
+            }
+            if (status === 403 && err.code === "agent_cross_tenant") {
+                throw teachingClaimError(agentId, "this agent is already claimed by a different owner.", "Onboard an agent you own, or provision a fresh one with `mnemom wrap`.", json, result, steps);
+            }
+            if (status === 403 &&
+                (err.code === "agent_org_not_member" || /not[ _]?member/i.test(err.code ?? ""))) {
+                throw teachingClaimError(agentId, "you are not a member of the target org.", "Run `mnemom org list` to see the orgs you belong to; onboard lands in your personal org by default.", json, result, steps);
+            }
+            if (status === 503) {
+                throw teachingClaimError(agentId, "your personal org is still being set up.", "Give it a moment, then re-run `mnemom onboard`.", json, result, steps);
+            }
+            // Idempotency (LAST): a same-owner re-claim that raced the scan. Gated on
+            // status/code — NOT a loose message match — so the specific 403s above are
+            // never swallowed here.
+            if (status === 409 || err.code === "agent_already_claimed") {
+                result.claimed = true;
+                steps.push({ step: "claim", status: "skipped", detail: "already claimed" });
+                mergeAgentConfig({ agent_id: agentId, org_id: orgId });
+                say(fmt.success("Already claimed — nothing to do."));
+                return;
+            }
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw teachingClaimError(agentId, msg, null, json, result, steps);
+    }
+}
+/** Resolve the claim hash proof from --hash-proof (raw) or --key (derived). */
+function resolveHashProof(options, derivationName) {
+    if (options.hashProof) {
+        const proof = options.hashProof.trim().toLowerCase();
+        if (!FULL_PROOF_RE.test(proof)) {
+            throw new Error("--hash-proof must be the full 64-character hex SHA-256 proof.");
+        }
+        return proof;
+    }
+    if (options.key)
+        return deriveHashProof(options.key, derivationName);
+    return undefined;
+}
+/**
+ * Build a fatal claim error that also records the failed step and emits the
+ * --json envelope before throwing (so a machine caller still gets valid output
+ * on the failure path — MNE-442 fail-closed, never a bare hang).
+ */
+function teachingClaimError(agentId, reason, hint, json, result, steps) {
+    steps.push({ step: "claim", status: "error", detail: reason });
+    if (json)
+        console.log(JSON.stringify(result, null, 2));
+    const message = hint
+        ? `Failed to claim ${agentId}: ${reason}\n  ${hint}`
+        : `Failed to claim ${agentId}: ${reason}`;
+    return new Error(message);
+}
+// ── State 4: earn Trust Rating ─────────────────────────────────────────────────
+/**
+ * Re-read the agent's integrity and surface it as an HONEST rating: a cold-start
+ * agent (0 traces) is `provisional`, never a bare perfect score (MNE-439). The
+ * signed Trust Rating remains server-computed; this is the CLI-reachable view.
+ */
+async function earnRating(agentId, steps, say) {
+    say();
+    say(`${fmt.badge("rating", "cyan")} Reading your Trust Rating…`);
+    try {
+        const integ = await getIntegrity(agentId);
+        const rating = {
+            score: integ.integrity_score,
+            total_traces: integ.total_traces,
+            verified_traces: integ.verified_traces,
+            status: integ.total_traces === 0 ? "provisional" : "rated",
+        };
+        steps.push({
+            step: "rating",
+            status: "ok",
+            detail: `${rating.status} — score ${rating.score.toFixed(2)} (${rating.total_traces} traces)`,
+        });
+        say(fmt.dim(rating.status === "provisional"
+            ? `  Provisional — the signed rating lands once the observer pipeline generates traces.`
+            : `  Rated — score ${rating.score.toFixed(2)} across ${rating.total_traces} traces.`));
+        return rating;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        steps.push({ step: "rating", status: "error", detail: msg });
+        say(fmt.warn(`Trust Rating unavailable right now — check \`mnemom status\` later. (${msg})`));
+        return null;
+    }
+}
+// ── starter alignment card ──────────────────────────────────────────────────────
+/**
+ * A starter alignment card in `observe` mode — the honest, minimal declaration
+ * of intent for a freshly-onboarded agent. Mirrors the shape `wrap` seeds so the
+ * two skill-runners produce a consistent first card.
+ */
+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" },
+    };
+}
+// ── report ──────────────────────────────────────────────────────────────────────
+/** The closing recount for human mode. */
+function renderRecount(result) {
+    const L = [fmt.section("Onboarding summary"), ""];
+    L.push(fmt.label("  Agent:   ", result.agent_id ?? "(unknown)"));
+    L.push(fmt.label("  Claimed: ", result.claimed ? "yes" : "no"));
+    L.push(fmt.label("  Card:    ", result.card_published ? "declared" : "not declared"));
+    if (result.rating) {
+        L.push(fmt.label("  Rating:  ", `${result.rating.status} (score ${result.rating.score.toFixed(2)}, ${result.rating.total_traces} traces)`));
+    }
+    if (result.badge_url)
+        L.push(fmt.label("  Badge:   ", result.badge_url));
+    L.push("");
+    if (result.verdict === "ok") {
+        L.push(fmt.dim("You're a claimed, value-declared agent. Traces will appear in `mnemom logs`."));
+    }
+    else {
+        L.push(fmt.dim("Partly done — re-run `mnemom onboard` to finish the remaining step(s)."));
+    }
+    return L.join("\n");
+}

package/dist/commands/org.d.ts

@@ -1,3 +1,16 @@
+/**
+ * `mnemom org use <slug|id>` / `mnemom org use --clear`
+ *
+ * Record (or forget) the ACTIVE ORG — the durable default that org-scoped
+ * commands fall back to when `--org` is omitted. `mnemom login` binds no org
+ * (the OAuth token carries only scope), so without this every claim landed
+ * silently in the caller's personal org. The value is validated against the
+ * caller's live memberships before it is persisted; membership drift after
+ * that is caught by the server (403 + teaching list) at use time.
+ */
+export declare function orgUseCommand(slugOrId: string | undefined, opts: {
+    clear?: boolean;
+}): Promise<void>;
 /**
  * `mnemom org list`
  *

package/dist/commands/org.js

@@ -1,6 +1,63 @@
 import { listMyOrgs, getMyPersonalOrg } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
+import { getActiveOrg, setActiveOrg } from "../lib/cli-config.js";
 import { fmt } from "../lib/format.js";
+/**
+ * `mnemom org use <slug|id>` / `mnemom org use --clear`
+ *
+ * Record (or forget) the ACTIVE ORG — the durable default that org-scoped
+ * commands fall back to when `--org` is omitted. `mnemom login` binds no org
+ * (the OAuth token carries only scope), so without this every claim landed
+ * silently in the caller's personal org. The value is validated against the
+ * caller's live memberships before it is persisted; membership drift after
+ * that is caught by the server (403 + teaching list) at use time.
+ */
+export async function orgUseCommand(slugOrId, opts) {
+    if (opts.clear) {
+        setActiveOrg(null);
+        console.log(fmt.success("Active org cleared.") +
+            "\n  Org-scoped commands now default to your personal org (pass --org to override).\n");
+        return;
+    }
+    if (!slugOrId) {
+        // No arg, no --clear → show the current setting (mirrors `git config`).
+        const active = getActiveOrg();
+        if (active) {
+            console.log(fmt.label("Active org:", `${active.name} (${active.slug}, ${active.org_id})`));
+        }
+        else {
+            console.log(fmt.warn("No active org set.") +
+                "\n  Set one with: mnemom org use <slug>   (see: mnemom org list)\n");
+        }
+        return;
+    }
+    const cred = await requireAuth();
+    if (cred?.type === "api-key") {
+        console.log(fmt.warn("API keys are agent-scoped; run mnemom login for org/key management"));
+        return;
+    }
+    let orgs;
+    try {
+        orgs = await listMyOrgs();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(fmt.error(`Failed to list orgs: ${msg}`) + "\n");
+        process.exit(1);
+        return;
+    }
+    const needle = slugOrId.trim();
+    const match = orgs.find((o) => o.slug === needle) ?? orgs.find((o) => o.org_id === needle);
+    if (!match) {
+        const choices = orgs.map((o) => `    ${o.slug.padEnd(24)} ${o.name}`).join("\n");
+        console.log(fmt.error(`No org of yours matches '${needle}'. Your organizations:\n${choices}`) + "\n");
+        process.exit(1);
+        return;
+    }
+    setActiveOrg({ org_id: match.org_id, slug: match.slug, name: match.name });
+    console.log(fmt.success(`Active org set to ${match.name} (${match.slug}).`) +
+        "\n  Org-scoped commands (e.g. agents claim) now default here. Clear with: mnemom org use --clear\n");
+}
 /**
  * `mnemom org list`
  *
@@ -41,15 +98,19 @@ export async function orgListCommand(opts) {
     const header = "Name".padEnd(nameW) + "ID".padEnd(idW) + "Role".padEnd(roleW) + "Owner".padEnd(ownerW);
     console.log(`  ${header}`);
     console.log(`  ${"─".repeat(nameW + idW + roleW + ownerW)}`);
+    const activeOrgId = getActiveOrg()?.org_id;
     for (const org of orgs) {
-        const tag = org.is_personal ? " (personal)" : "";
-        const name = `${org.name}${tag}`.slice(0, nameW - 2).padEnd(nameW);
+        const tags = (org.is_personal ? " (personal)" : "") + (org.org_id === activeOrgId ? " *active" : "");
+        const name = `${org.name}${tags}`.slice(0, nameW - 2).padEnd(nameW);
         const id = org.org_id.slice(0, idW - 2).padEnd(idW);
         const role = (org.role ?? "-").padEnd(roleW);
         const owner = (org.is_owner ? "yes" : "no").padEnd(ownerW);
         console.log(`  ${name}${id}${role}${owner}`);
     }
     console.log(`\n  Total: ${orgs.length} organization(s)\n`);
+    if (!activeOrgId) {
+        console.log(fmt.dim("  Tip: set a default for org-scoped commands with `mnemom org use <slug>`.") + "\n");
+    }
 }
 /**
  * `mnemom org show [<org_id>]` or `mnemom org show --personal`

package/dist/commands/protection.d.ts

@@ -24,3 +24,13 @@ export declare function protectionValidateCommand(file: string, opts?: {
 export declare function protectionEditCommand(agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;
+/**
+ * Compare a committed protection-card snapshot against the live CANONICAL
+ * (composed) card. Read-only: never writes, never publishes.
+ *
+ * Exit 0 = no drift, exit 1 = drift or error, so a scheduled job can gate on it.
+ */
+export declare function protectionDriftCommand(file: string, agentName?: string, opts?: {
+    strict?: boolean;
+    json?: boolean;
+}): Promise<void>;