@moda-ai/cli 1.27.0 → 1.28.0

package/dist/{cli-cjqzrp9k.js → cli-x1a56ws9.js}

@@ -546,14 +546,25 @@ async function runPromptsCommand(input, legacyFlags, legacyProfileOptions) {
   const profileOptions = legacyProfileOptions ?? { profile: context.profile, env: context.env };
   const subcommand = positionals[0] || "status";
   switch (subcommand) {
-    case "init":
-      await initPrompts({ silent: true });
+    case "init": {
+      const init = await initPrompts({ silent: true });
       context.output.writeData({
         manifest: MANIFEST_PATH,
+        manifestPath: init.manifestPath,
         lockfile: LOCK_PATH,
-        promptPaths: readManifest().promptPaths
+        lockPath: init.lockPath,
+        cwd: init.cwd,
+        created: init.created,
+        promptPaths: init.promptPaths
+      }, {
+        artifacts: [{
+          kind: "prompt_manifest",
+          path: init.manifestPath,
+          description: init.created ? "Prompt discovery manifest created by this run." : "Prompt discovery manifest already existed; left unchanged."
+        }]
       });
       break;
+    }
     case "status":
       context.output.writeData(await getPromptStatus());
       break;
@@ -577,8 +588,12 @@ async function runPromptsCommand(input, legacyFlags, legacyProfileOptions) {
   }
 }
 async function initPrompts(options = {}) {
+  const cwd = process.cwd();
+  const manifestPath = resolve3(cwd, MANIFEST_PATH);
+  const lockPath = resolve3(cwd, LOCK_PATH);
   mkdirSync(MODA_DIR, { recursive: true });
-  if (!existsSync2(MANIFEST_PATH)) {
+  const existed = existsSync2(MANIFEST_PATH);
+  if (!existed) {
     writeFileSync2(MANIFEST_PATH, [
       "version: 1",
       "prompt_paths:",
@@ -587,13 +602,28 @@ async function initPrompts(options = {}) {
     ].join(`
 `));
   }
+  if (!existsSync2(manifestPath)) {
+    throw new Error(`Could not write ${manifestPath}: the file is missing after init. Check directory permissions and available disk space.`);
+  }
+  const result = {
+    manifestPath,
+    lockPath,
+    cwd,
+    created: !existed,
+    promptPaths: readManifest().promptPaths
+  };
   if (!options.silent) {
     printJson({
       manifest: MANIFEST_PATH,
+      manifestPath,
       lockfile: LOCK_PATH,
-      promptPaths: readManifest().promptPaths
+      lockPath,
+      cwd,
+      created: result.created,
+      promptPaths: result.promptPaths
     });
   }
+  return result;
 }
 async function syncPrompts(flags, profileOptions, context) {
   if (flags.watch === "true") {

package/dist/cli.js

@@ -8,7 +8,7 @@ import {
   runPromptsCommand,
   runSkillsCommand,
   runStatusCommand
-} from "./cli-cjqzrp9k.js";
+} from "./cli-x1a56ws9.js";
 import {
   ApiError,
   HARNESS_REPORT_APPROVAL_PATH,
@@ -60,6 +60,7 @@ import {
   clearStoredApiKeyCredentials,
   createCliOutput,
   createCommandContext,
+  embeddedTenantIdFromApiKey,
   ensureSecretFilePermissions,
   getActiveProfile,
   getModaDir,
@@ -76,6 +77,7 @@ import {
   resolveTenantId,
   safeWriteStderr,
   safeWriteStdout,
+  saveCliConfig,
   secretFilePathFromRef,
   setActiveProfile,
   upsertProfile,
@@ -391,6 +393,7 @@ var FIX_USAGE = [
   "       moda fix verify <fix_id> [--prompt-file=PATH] [--no-wait] [--timeout=ms]",
   "       moda fix checkout <fix_id>",
   "       moda fix submit <fix_id> --pr | --local-ref=<branch>",
+  "       moda fix mark-applied <fix_id> [--note=TEXT]",
   "       moda fix dismiss <fix_id> --reason=TEXT"
 ].join(`
 `);
@@ -454,6 +457,8 @@ async function runFixCommand(context) {
       return runFixCheckout(context, profileOptions, tenantId);
     case "submit":
       return runFixSubmit(context, profileOptions, tenantId);
+    case "mark-applied":
+      return runFixMarkApplied(context, profileOptions, tenantId);
     case "dismiss":
       return runFixDismiss(context, profileOptions, tenantId);
     default:
@@ -645,6 +650,9 @@ async function runFixCheckout(context, profileOptions, tenantId) {
     throw new CliInputError("<fix_id> is required", "Usage: moda fix checkout <fix_id>");
   }
   const fix = await getFix(tenantId, fixId, profileOptions);
+  if (isArtifactFix(fix)) {
+    throw new CliInputError(`Fix MODA-FIX-${fix.shortRef} is a ${fix.fixType} fix — its candidate is applied in your own stack, not checked out. Run \`moda fix ${fixId} --packet\` for the candidate (written as local artifacts), apply it, then confirm with \`moda fix mark-applied ${fixId}\`.`);
+  }
   if (!fix.targetSourcePath) {
     throw new CliInputError(`Fix MODA-FIX-${fix.shortRef} has no target source path — ${fix.fixType} fixes are packet-only. Run \`moda fix ${fixId} --packet\` for the diagnosis packet.`);
   }
@@ -752,6 +760,38 @@ async function runFixSubmit(context, profileOptions, tenantId) {
   });
   return EXIT_OK;
 }
+async function runFixMarkApplied(context, profileOptions, tenantId) {
+  const usage = "Usage: moda fix mark-applied <fix_id> [--note=TEXT]";
+  const fixId = (context.positionals[1] || context.flags["fix-id"] || "").trim();
+  if (!fixId) {
+    throw new CliInputError("<fix_id> is required", usage);
+  }
+  const note = (context.flags.note ?? "").trim();
+  if (note.length > 600) {
+    throw new CliInputError(`--note must be 600 characters or fewer (got ${note.length})`, usage);
+  }
+  const fix = await callControlAPI(`${fixesBase(tenantId)}/${encodeURIComponent(fixId)}/mark-applied`, { method: "POST", body: JSON.stringify(note ? { note } : {}) }, profileOptions, { timeoutMs: 60000, retries: 0 });
+  if (context.outputMode === "human") {
+    process.stderr.write(fix.duplicate === true ? `Fix MODA-FIX-${fix.shortRef} was already confirmed (${fix.status}) — duplicate no-op; the mark_fixed feedback was re-posted.
+` : `Fix MODA-FIX-${fix.shortRef} marked applied (${fix.status}) — mark_fixed feedback posted, monitoring for recurrence.
+`);
+  }
+  context.output.writeData(fix, {
+    summary: {
+      text: fix.duplicate === true ? `Fix MODA-FIX-${fix.shortRef} was already confirmed (${fix.status}); mark-applied was a duplicate no-op.` : `Fix MODA-FIX-${fix.shortRef} marked applied — status ${fix.status}; the problem enters fixed-monitoring.`,
+      confidence: "high"
+    },
+    nextCommands: [
+      {
+        command: `moda fix ${fix.id}`,
+        purpose: "Track confirmation monitoring (HELD after 14 clean days; REGRESSED on reopen).",
+        mutability: "read",
+        requires_approval: false
+      }
+    ]
+  });
+  return EXIT_OK;
+}
 async function runFixDismiss(context, profileOptions, tenantId) {
   const usage = "Usage: moda fix dismiss <fix_id> --reason=TEXT";
   const fixId = (context.positionals[1] || context.flags["fix-id"] || "").trim();
@@ -778,8 +818,16 @@ async function runFixDismiss(context, profileOptions, tenantId) {
 async function runFixDetail(context, profileOptions, tenantId, fixId) {
   if (context.flags.packet === "true") {
     const packet = await callControlAPI(`${fixesBase(tenantId)}/${encodeURIComponent(fixId)}/packet`, { method: "GET" }, profileOptions);
+    const extras = materializePacketCandidates(packet, fixId, context.outputMode === "human");
     context.output.writeData(packet, {
-      summary: { text: `moda.fix_packet.v1 for fix ${fixId}.`, confidence: "high" }
+      summary: {
+        text: `moda.fix_packet.v1 for fix ${fixId}.${extras.summarySuffix}`,
+        confidence: "high"
+      },
+      ...extras.findings.length > 0 ? { findings: extras.findings } : {},
+      ...extras.artifacts.length > 0 ? { artifacts: extras.artifacts } : {},
+      ...extras.warnings.length > 0 ? { warnings: extras.warnings } : {},
+      ...extras.nextCommands.length > 0 ? { nextCommands: extras.nextCommands } : {}
     });
     return EXIT_OK;
   }
@@ -841,6 +889,9 @@ async function driveAdvance(args) {
     announce(fix);
     if (!ADVANCING_STATUSES.has(fix.status))
       break;
+    if (fix.status === "PROPOSED" && /gate (pending|unavailable)/i.test(fix.statusReason ?? "")) {
+      break;
+    }
     await sleep(fix.status === "GATING" ? args.pollIntervalMs : Math.min(STEP_DELAY_MS, args.pollIntervalMs));
   }
   return fix;
@@ -871,6 +922,112 @@ async function fetchPacketFailSoft(tenantId, fixId, profileOptions) {
     return null;
   }
 }
+function isArtifactFix(fix) {
+  return fix.fixType === "TOOL_SCHEMA" || fix.fixType === "SKILL";
+}
+function materializePacketCandidates(packet, fixId, human) {
+  const findings = [];
+  const artifacts = [];
+  const warnings = [];
+  const nextCommands = [];
+  const summaryParts = [];
+  const tool = packet.candidate_tool;
+  const skill = packet.candidate_skill;
+  const hasTool = typeof tool?.proposed_description === "string" && tool.proposed_description !== "";
+  const hasSkill = typeof skill?.skill_md === "string" && skill.skill_md !== "";
+  if (!hasTool && !hasSkill) {
+    return { findings, artifacts, warnings, nextCommands, summarySuffix: "" };
+  }
+  const rawRef = typeof packet.short_ref === "string" && packet.short_ref.trim() ? packet.short_ref : fixId;
+  const ref = rawRef.replace(/[^A-Za-z0-9._-]/g, "").replace(/^\.+/, "").slice(0, 64) || "fix";
+  const w = (line) => process.stderr.write(`${line}
+`);
+  const block = (label, text) => {
+    w(`  ${label}:`);
+    for (const line of (text || "(none)").split(`
+`))
+      w(`    ${line}`);
+  };
+  const writeCandidateFile = (name, content, kind, description) => {
+    const relPath = safeTargetSourcePath(`.moda/fixes/${ref}/${name}`);
+    const absPath = join(process.cwd(), relPath);
+    try {
+      assertRealpathContained(absPath, relPath);
+      writeContainedFile(absPath, relPath, content);
+      artifacts.push({ kind, path: relPath, description });
+      return relPath;
+    } catch (error) {
+      warnings.push(`Could not write ${relPath}: ${error instanceof Error ? error.message : String(error)} — the full candidate text is still in the packet payload.`);
+      return null;
+    }
+  };
+  if (hasTool && tool) {
+    const toolName = typeof tool.tool_name === "string" && tool.tool_name ? tool.tool_name : "unknown-tool";
+    const source = typeof tool.current_description_source === "string" ? tool.current_description_source : "";
+    const paramNotes = (Array.isArray(tool.param_notes) ? tool.param_notes : []).filter((note) => typeof note === "string" && note !== "");
+    const rationale = typeof tool.rationale === "string" ? tool.rationale : "";
+    const currentPath = writeCandidateFile("tool-description.current.md", typeof tool.current_description === "string" ? tool.current_description : "", "fix_tool_description_current", `Current description of tool '${toolName}'${source ? ` (from ${source})` : ""} — the diff base.`);
+    const proposedPath = writeCandidateFile("tool-description.proposed.md", tool.proposed_description ?? "", "fix_tool_description_proposed", `Proposed description for tool '${toolName}' — apply it to your tool definition, then \`moda fix mark-applied ${fixId}\`.`);
+    findings.push({
+      id: "fix:candidate_tool",
+      title: `tool '${toolName}' description candidate${source ? ` (current from ${source})` : ""}`,
+      status: "proposed",
+      severity: "info",
+      ...rationale || paramNotes.length > 0 ? {
+        description: [rationale, ...paramNotes.map((note) => `param note: ${note}`)].filter(Boolean).join(`
+`)
+      } : {}
+    });
+    summaryParts.push(`Includes a tool-description candidate for '${toolName}'.`);
+    if (human) {
+      w("");
+      w(`Tool-description candidate — '${toolName}'${source ? ` (current description from ${source})` : ""}`);
+      block("current ", tool.current_description ?? "");
+      block("proposed", tool.proposed_description ?? "");
+      if (paramNotes.length > 0)
+        block("param notes", paramNotes.join(`
+`));
+      if (rationale)
+        block("rationale", rationale);
+      if (currentPath && proposedPath) {
+        w(`  diff: diff ${currentPath} ${proposedPath}`);
+      }
+    }
+  }
+  if (hasSkill && skill) {
+    const skillName = typeof skill.skill_name === "string" && skill.skill_name ? skill.skill_name : "moda-fix-skill";
+    const skillPath = writeCandidateFile("SKILL.md", skill.skill_md ?? "", "fix_candidate_skill", `Drafted SKILL.md for '${skillName}' — install it (for example .claude/skills/${skillName}/SKILL.md), then \`moda fix mark-applied ${fixId}\`.`);
+    findings.push({
+      id: "fix:candidate_skill",
+      title: `skill '${skillName}' drafted (SKILL.md, ${(skill.skill_md ?? "").length} chars)`,
+      status: "proposed",
+      severity: "info",
+      description: `Install the skill in your agent, then confirm with \`moda fix mark-applied ${fixId}\`. Gating on the replay holdout stays pending until the skill is registered with the skill harness.`
+    });
+    summaryParts.push(`Includes a drafted SKILL.md candidate ('${skillName}').`);
+    if (human) {
+      w("");
+      w(`Skill candidate — '${skillName}'`);
+      if (skillPath)
+        w(`  SKILL.md written to ${skillPath}`);
+      w(`  install it (for example .claude/skills/${skillName}/SKILL.md), then confirm:`);
+      w(`  moda fix mark-applied ${fixId} --note="installed skill ${skillName}"`);
+    }
+  }
+  nextCommands.push({
+    command: `moda fix mark-applied ${fixId} --note="where/how you applied it"`,
+    purpose: "Confirm you applied the candidate in your own stack (no PR) — flips the fix to SHIPPED and starts recurrence monitoring.",
+    mutability: "write",
+    requires_approval: true
+  });
+  return {
+    findings,
+    artifacts,
+    warnings,
+    nextCommands,
+    summarySuffix: summaryParts.length > 0 ? ` ${summaryParts.join(" ")}` : ""
+  };
+}
 function gateFindings(fix) {
   const gateResult = fix.gateResult ?? null;
   if (!gateResult)
@@ -918,8 +1075,24 @@ function passLabel(value) {
   return value ? "pass" : "fail";
 }
 function nextCommandsFor(fix) {
+  const packetCommand = {
+    command: `moda fix ${fix.id} --packet`,
+    purpose: "Read the packet — the tool/skill candidate is written as local artifacts to apply in your own stack.",
+    mutability: "write",
+    requires_approval: false
+  };
+  const markAppliedCommand = {
+    command: `moda fix mark-applied ${fix.id} --note="where/how you applied it"`,
+    purpose: "Confirm you applied the candidate in your own stack (no PR) — flips the fix to SHIPPED and starts recurrence monitoring.",
+    mutability: "write",
+    requires_approval: true
+  };
+  const skillGatePending = fix.fixType === "SKILL" && fix.candidateRef?.kind === "skill" && !fix.candidateRef?.skillId;
   switch (fix.status) {
     case "VERIFIED":
+      if (isArtifactFix(fix)) {
+        return [packetCommand, markAppliedCommand];
+      }
       return [
         {
           command: `moda fix submit ${fix.id} --pr`,
@@ -935,6 +1108,9 @@ function nextCommandsFor(fix) {
         }
       ];
     case "PROPOSED":
+      if (skillGatePending) {
+        return [packetCommand, markAppliedCommand];
+      }
       return [
         {
           command: `moda fix verify ${fix.id}`,
@@ -944,6 +1120,17 @@ function nextCommandsFor(fix) {
         }
       ];
     case "GATE_FAILED":
+      if (isArtifactFix(fix)) {
+        return [
+          {
+            command: `moda fix verify ${fix.id}`,
+            purpose: "Re-gate the stored candidate on the frozen holdout.",
+            mutability: "write",
+            requires_approval: false
+          },
+          packetCommand
+        ];
+      }
       return [
         {
           command: `moda fix checkout ${fix.id}`,
@@ -1843,6 +2030,47 @@ function renderJsonSchemas() {
   }, null, 2);
 }
 
+// src/api-key-auth.ts
+var PROBE_TIMEOUT_MS = 1e4;
+function resolveApiKeyCredential(options = {}) {
+  const key = resolveApiKey(options);
+  if (!key)
+    return;
+  const env = options.env ?? process.env;
+  const source = env.MODA_API_KEY === key ? "env" : resolveApiKeyFromActiveProfile(options) === key ? "profile" : "config";
+  return { key, source, tenantId: embeddedTenantIdFromApiKey(key) };
+}
+function redactApiKey(key) {
+  if (key.length <= 12)
+    return "<redacted>";
+  return `${key.slice(0, 8)}...${key.slice(-4)}`;
+}
+async function probeApiKey(key, options = {}) {
+  let response;
+  try {
+    response = await fetch(`${resolveModaBaseUrl(options)}/api/v1/data/overview`, {
+      method: "GET",
+      headers: { "x-api-key": key },
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { outcome: "unreachable", reason };
+  }
+  if (response.status === 401 || response.status === 403) {
+    return { outcome: "rejected", status: response.status };
+  }
+  if (response.status !== 200) {
+    return { outcome: "unreachable", reason: `HTTP ${response.status}` };
+  }
+  try {
+    await response.json();
+  } catch {
+    return { outcome: "unreachable", reason: "non-JSON response from the Data API" };
+  }
+  return { outcome: "live" };
+}
+
 // src/keys.ts
 import { createHash } from "node:crypto";
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
@@ -2027,13 +2255,75 @@ function serializeProfile(profile, activeProfile) {
     auth_token_ref: profile.auth_token_ref
   };
 }
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+async function apiKeyLoginCandidate(context) {
+  if (boolFlag2(context, "api-key-stdin")) {
+    const piped = await readStdin();
+    if (piped)
+      return { key: piped, fromArgv: false };
+    throw new CliInputError("No API key received on stdin.", 'Pipe the key in, e.g. `printf %s "$KEY" | moda auth login --api-key-stdin`.');
+  }
+  const inline = flag(context, "api-key");
+  if (inline)
+    return { key: inline, fromArgv: true };
+  const env = context.env ?? process.env;
+  if (env.MODA_API_KEY)
+    return { key: env.MODA_API_KEY, fromArgv: false };
+  return;
+}
+async function loginWithApiKey(context, candidate) {
+  const { key } = candidate;
+  if (candidate.fromArgv) {
+    console.error('Warning: passing the key as --api-key=<key> exposes it in this process\'s command line and your shell history. Prefer MODA_API_KEY, or `printf %s "$KEY" | moda auth login --api-key-stdin`.');
+  }
+  const authOptions = { profile: context.profile, env: context.env };
+  const probe = await probeApiKey(key, authOptions);
+  if (probe.outcome === "rejected") {
+    throw new CliInputError(`API key rejected by the Moda API (HTTP ${probe.status}).`, 'The key is revoked, malformed, or belongs to another environment. Mint a new one with "moda provision --tenant-id=<org-id>", or check MODA_BASE_URL points at the right environment.');
+  }
+  if (probe.outcome === "unreachable") {
+    throw new CliInputError(`Could not validate the API key: ${probe.reason}.`, "The key was not saved. Check network access to the Moda API and retry; the key itself may still be valid.");
+  }
+  const tenantId = embeddedTenantIdFromApiKey(key);
+  saveCliConfig({ api_key: key, ...tenantId ? { tenant_id: tenantId } : {} }, authOptions);
+  const envKey = (context.env ?? process.env).MODA_API_KEY;
+  const shadowedByEnv = Boolean(envKey && envKey !== key);
+  if (shadowedByEnv) {
+    console.error(`Warning: MODA_API_KEY is set to a different key (${redactApiKey(envKey)}) and takes precedence over the key just saved. Later commands will use the environment key. Unset MODA_API_KEY to use the saved credential.`);
+  }
+  context.output.writeData({
+    status: "authenticated",
+    method: "api_key",
+    profile: context.profile ?? context.env?.MODA_PROFILE ?? process.env.MODA_PROFILE ?? null,
+    apiKeyCredential: { masked: redactApiKey(key) },
+    tenant_id: tenantId ?? null,
+    persisted: true,
+    shadowed_by_env: shadowedByEnv,
+    effective_credential: shadowedByEnv ? "env" : "saved"
+  }, shadowedByEnv ? { status: "degraded" } : undefined);
+  return { exitCode: shadowedByEnv ? EXIT_DEGRADED : EXIT_OK };
+}
 async function runAuthCommand(context) {
   switch (subcommand(context)) {
     case "login": {
+      const wantsApiKey = "api-key" in context.flags || boolFlag2(context, "api-key-stdin");
+      const nonInteractive = boolFlag2(context, "non-interactive");
+      const candidate = wantsApiKey || nonInteractive ? await apiKeyLoginCandidate(context) : undefined;
+      if (candidate)
+        return loginWithApiKey(context, candidate);
+      if (wantsApiKey || nonInteractive) {
+        throw new CliInputError("No API key available for non-interactive login.", 'Set MODA_API_KEY, pipe the key with "moda auth login --api-key-stdin", or pass "moda auth login --api-key=<key>" (exposes it in argv). Mint a key with "moda provision --tenant-id=<org-id>" (needs an existing browser session), or run "moda init".');
+      }
       const screen = flag(context, "screen") === "signup" ? "signup" : "login";
       await login(screen, { profile: context.profile, env: context.env });
       context.output.writeData({
         status: "authenticated",
+        method: "browser",
         profile: context.profile ?? process.env.MODA_PROFILE ?? null
       });
       return { exitCode: 0 };
@@ -2058,7 +2348,33 @@ async function runAuthCommand(context) {
     case "whoami": {
       const session = loadAuthSession({ profile: context.profile, env: context.env });
       if (!session) {
-        throw new CliInputError("Not authenticated.", 'Run "moda auth login" or "moda init".');
+        const credential = resolveApiKeyCredential({
+          profile: context.profile,
+          env: context.env
+        });
+        if (credential) {
+          const probe = await probeApiKey(credential.key, {
+            profile: context.profile,
+            env: context.env
+          });
+          if (probe.outcome === "rejected") {
+            throw new CliInputError(`API key rejected by the Moda API (HTTP ${probe.status}).`, 'The key is revoked or belongs to another environment. Mint a new one with "moda provision --tenant-id=<org-id>", or run "moda auth login".');
+          }
+          context.output.writeData({
+            profile: context.profile ?? process.env.MODA_PROFILE ?? null,
+            credential: "api_key",
+            apiKeyCredential: {
+              source: credential.source,
+              masked: redactApiKey(credential.key),
+              verified: probe.outcome === "live"
+            },
+            tenant_id: credential.tenantId ?? null,
+            session: null,
+            context: null
+          }, probe.outcome === "live" ? undefined : { status: "degraded" });
+          return { exitCode: probe.outcome === "live" ? EXIT_OK : EXIT_DEGRADED };
+        }
+        throw new CliInputError("Not authenticated.", 'Non-interactive: set MODA_API_KEY, or run "moda auth login --api-key=<key>". Interactive: run "moda auth login" or "moda init".');
       }
       const response = await authFetch("/api/cli/context", {}, { profile: context.profile, env: context.env });
       if (!response.ok) {
@@ -2080,8 +2396,17 @@ async function runAuthCommand(context) {
       const authOptions = { profile: context.profile, env: context.env };
       const session = loadAuthSession({ ...authOptions, includeExpired: true });
       const loggedIn = isAuthSessionValid(session);
+      const credential = resolveApiKeyCredential(authOptions);
       const data = {
         loggedIn,
+        authenticated: loggedIn || Boolean(credential),
+        apiKeyCredential: credential ? {
+          present: true,
+          source: credential.source,
+          masked: redactApiKey(credential.key),
+          tenantId: credential.tenantId ?? null,
+          verified: null
+        } : { present: false },
         profile: context.profile ?? context.env.MODA_PROFILE ?? session?.profile ?? null,
         expiresAt: session ? new Date(session.expires_at * 1000).toISOString() : null
       };
@@ -2101,9 +2426,16 @@ async function runAuthCommand(context) {
           }
         } catch {}
         data.online = online;
+        if (credential && data.apiKeyCredential.present) {
+          const probe = await probeApiKey(credential.key, authOptions);
+          data.apiKeyCredential.verified = probe.outcome === "live";
+          if (probe.outcome === "rejected") {
+            data.authenticated = loggedIn;
+          }
+        }
       }
       context.output.writeData(data);
-      return { exitCode: loggedIn ? EXIT_OK : EXIT_AUTH_REQUIRED };
+      return { exitCode: data.authenticated ? EXIT_OK : EXIT_AUTH_REQUIRED };
     }
     case "token": {
       const session = loadAuthSession({ profile: context.profile, env: context.env });
@@ -4609,7 +4941,7 @@ function buildResumeCommand(command, flags) {
   ];
 }
 function printHelp() {
-  console.error(`Usage: moda <command> [options]
+  console.log(`Usage: moda <command> [options]
 
 Commands:
   init                             Set up Moda in your project
@@ -4617,11 +4949,12 @@ Commands:
   status                           Show concise local Moda setup status
   manifest                         Describe the CLI machine protocol and commands
   doctor                           Diagnose local Moda setup and data flow
-  auth login                       Authenticate with Moda
-  auth status                      Show local auth session state (exit 4 when logged out); --online probes the API
+  auth login                       Authenticate with Moda (browser)
+  auth login --api-key             Non-interactive: validate MODA_API_KEY (or --api-key=<key>) and save it
+  auth status                      Show auth state for both credentials (exit 4 when neither is usable); --online probes the API
   auth token                       Print the raw bearer token for $(moda auth token)
   auth logout                      Clear cached Moda auth
-  auth whoami                      Show the authenticated Moda user
+  auth whoami                      Show the authenticated Moda identity (session or API key)
   profiles list                    List local Moda profiles
   profiles use <name>              Switch active Moda profile
   profiles create <name>           Create or update a local Moda profile
@@ -4692,7 +5025,8 @@ Commands:
 
   Fixes (a fix with proof):
   fixes                            Ranked Fix queue (--status=S --limit=N --cursor=TOKEN)
-  fix <fix_id>                     One Fix: status + gate result; --packet prints moda.fix_packet.v1;
+  fix <fix_id>                     One Fix: status + gate result; --packet prints moda.fix_packet.v1
+                                   (tool/skill candidates are also written under .moda/fixes/<ref>/);
                                    --wait drives a still-running pipeline to rest
   fix start <problem_id>           Draft a Fix from a Problem (--type=auto|prompt); --wait drives
                                    scope -> propose -> gate and prints the packet
@@ -4700,6 +5034,8 @@ Commands:
                                    (exit 0 pass / 1 fail with per-case findings / 3 degraded-inconclusive)
   fix checkout <fix_id>            Write the candidate at its target source path (never runs git)
   fix submit <fix_id>              Deliver: --pr opens a draft PR | --local-ref=<branch> records your branch
+  fix mark-applied <fix_id>        Confirm a candidate you applied in your own stack (--note=TEXT);
+                                   no PR needed — flips to SHIPPED and starts monitoring
   fix dismiss <fix_id>             Reject with --reason=TEXT (feeds problem feedback)
 
 Options:
@@ -4837,6 +5173,8 @@ Provision flags (headless; requires an existing "moda auth login" session):
 
 Examples:
   moda init
+  moda auth login --api-key=$MODA_API_KEY
+  moda auth whoami
   moda provision --tenant-id=<org-id>
   moda status
   moda manifest --json
@@ -4900,7 +5238,12 @@ Examples:
   moda skills pull
   moda fixes
   moda fix start <problem_id> --wait
-  moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md`);
+  moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md
+  moda fix mark-applied <fix_id> --note="tool description updated in our agent config"
+
+Run \`moda <command> --help\` for a command's subcommands, and
+\`moda <command> <subcommand> --help\` for that subcommand's flags
+(e.g. \`moda auth login --help\`).`);
 }
 function printCommandHelp(definition) {
   const lines = [];
@@ -4911,6 +5254,14 @@ function printCommandHelp(definition) {
   if (definition.mutability === "write") {
     lines.push("This command can mutate state.");
   }
+  if (definition.subcommands && definition.subcommands.length > 0) {
+    lines.push("", "Subcommands:");
+    const width = Math.max(...definition.subcommands.map((entry) => entry.name.length));
+    for (const entry of definition.subcommands) {
+      lines.push(`  ${entry.name.padEnd(width)}  ${entry.description}`);
+    }
+    lines.push("", `Run 'moda ${definition.name} <subcommand> --help' for that subcommand's flags.`);
+  }
   if (definition.examples.length > 0) {
     lines.push("", "Examples:");
     for (const example of definition.examples) {
@@ -4918,7 +5269,28 @@ function printCommandHelp(definition) {
     }
   }
   lines.push("", "Run 'moda --help' for the full command list and common flags", "(--json, --agent, --profile, --days-back, --limit, --time-range, ...).");
-  console.error(lines.join(`
+  console.log(lines.join(`
+`));
+}
+function printSubcommandHelp(parent, entry) {
+  const lines = [];
+  lines.push(`moda ${parent.name} ${entry.name} — ${entry.description}`, "");
+  lines.push(`Usage: ${entry.usage}`);
+  if (entry.flags && entry.flags.length > 0) {
+    lines.push("", "Options:");
+    const width = Math.max(...entry.flags.map((flag2) => flag2.name.length));
+    for (const flag2 of entry.flags) {
+      lines.push(`  ${flag2.name.padEnd(width)}  ${flag2.description}`);
+    }
+  }
+  if (entry.examples && entry.examples.length > 0) {
+    lines.push("", "Examples:");
+    for (const example of entry.examples) {
+      lines.push(`  ${example}`);
+    }
+  }
+  lines.push("", `Run 'moda ${parent.name} --help' for the other ${parent.name} subcommands.`);
+  console.log(lines.join(`
 `));
 }
 async function attachWindows(rows, windowSize) {
@@ -5670,6 +6042,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
   }
   return 0;
 }
+var OFFLINE_PROMPTS_SUBCOMMANDS = new Set(["init", "status", "diff"]);
 function legacyCommand(metadata) {
   return {
     ...metadata,
@@ -5763,7 +6136,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result",
     handler: async (context) => {
-      const { runInit } = await import("./index-fwxpt51s.js");
+      const { runInit } = await import("./index-g3gt62rm.js");
       if (context.outputMode === "agent-stream") {
         context.output.writeEvent({
           event: "started",
@@ -5836,15 +6209,81 @@ var commandRegistry = createCommandRegistry([
   },
   {
     name: "auth",
-    description: "Authenticate and inspect browser auth sessions",
+    description: "Authenticate (browser or API key) and inspect auth state",
     examples: [
       "moda auth login",
+      "moda auth login --api-key=$MODA_API_KEY",
       "moda auth status",
       "moda auth status --online",
       "moda auth token",
       "moda auth whoami",
       "moda auth logout"
     ],
+    subcommands: [
+      {
+        name: "login",
+        description: "Authenticate with Moda (browser by default, or an API key)",
+        usage: "moda auth login [--api-key[=<key>] | --api-key-stdin] [--non-interactive] [--screen=login|signup]",
+        flags: [
+          {
+            name: "--api-key",
+            description: "Authenticate non-interactively with the API key in MODA_API_KEY. Validates it, saves it, and never opens a browser."
+          },
+          {
+            name: "--api-key-stdin",
+            description: "Read the API key from stdin. Safest form: the key never appears in argv or shell history."
+          },
+          {
+            name: "--api-key=<key>",
+            description: "Supply the key inline. Exposes it in this process's command line and shell history; prefer MODA_API_KEY or --api-key-stdin."
+          },
+          {
+            name: "--non-interactive",
+            description: "Never open a browser. Uses MODA_API_KEY if set, otherwise fails with the commands that would mint a key."
+          },
+          {
+            name: "--screen=login|signup",
+            description: "Which browser screen to open (interactive flow only)."
+          }
+        ],
+        examples: [
+          "MODA_API_KEY=<key> moda auth login --non-interactive",
+          "moda auth login --api-key",
+          'printf %s "$KEY" | moda auth login --api-key-stdin',
+          "moda auth login"
+        ]
+      },
+      {
+        name: "status",
+        description: "Show local auth state for both credentials; exit 4 when neither is usable",
+        usage: "moda auth status [--online]",
+        flags: [
+          {
+            name: "--online",
+            description: "Also probe the API to confirm the browser session is accepted."
+          }
+        ],
+        examples: ["moda auth status", "moda auth status --online"]
+      },
+      {
+        name: "whoami",
+        description: "Show the authenticated identity (browser session, or API-key credential)",
+        usage: "moda auth whoami",
+        examples: ["moda auth whoami"]
+      },
+      {
+        name: "token",
+        description: "Print the raw browser session bearer token for $(moda auth token)",
+        usage: "moda auth token",
+        examples: ["moda auth token", 'curl -H "Authorization: Bearer $(moda auth token)" ...']
+      },
+      {
+        name: "logout",
+        description: "Revoke and clear the browser session and any stored API key",
+        usage: "moda auth logout",
+        examples: ["moda auth logout"]
+      }
+    ],
     auth: "none",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
@@ -6147,11 +6586,75 @@ var commandRegistry = createCommandRegistry([
   legacyCommand({
     name: "prompts",
     description: "Manage prompt versions and labels",
-    examples: ["moda prompts status", "moda prompts sync", "moda prompts ab --baseline=old.md --candidate=new.md"],
+    examples: ["moda prompts init", "moda prompts status", "moda prompts sync", "moda prompts ab --baseline=old.md --candidate=new.md"],
+    subcommands: [
+      {
+        name: "init",
+        description: "Create .moda/prompts.yml in the current directory (never overwrites)",
+        usage: "moda prompts init",
+        flags: [],
+        examples: ["moda prompts init", "cd /path/to/project && moda prompts init"]
+      },
+      {
+        name: "status",
+        description: "Show prompt files that changed since the last sync",
+        usage: "moda prompts status",
+        examples: ["moda prompts status"]
+      },
+      {
+        name: "diff",
+        description: "Alias of status: show local prompt changes",
+        usage: "moda prompts diff",
+        examples: ["moda prompts diff"]
+      },
+      {
+        name: "sync",
+        description: "Upload changed prompt versions to Moda Cloud",
+        usage: "moda prompts sync [--watch] [--dry-run]",
+        flags: [
+          { name: "--watch", description: "Re-upload whenever a prompt file changes." },
+          { name: "--dry-run", description: "Show what would be uploaded without writing." }
+        ],
+        examples: ["moda prompts sync", "moda prompts sync --dry-run"]
+      },
+      {
+        name: "promote",
+        description: "Move a dev/staging/prod label to a prompt version",
+        usage: "moda prompts promote <key> --label=<dev|staging|prod> --version=<version_id>",
+        flags: [
+          { name: "--label=<label>", description: "Release label to move (dev, staging, prod)." },
+          { name: "--version=<id>", description: "Prompt version id to point the label at." }
+        ],
+        examples: ["moda prompts promote support.triage --label=prod --version=pver_abc123"]
+      },
+      {
+        name: "ab",
+        description: "Run a judged prompt A/B replay experiment",
+        usage: "moda prompts ab --baseline=<path> --candidate=<path> --conversations=<ids>",
+        flags: [
+          { name: "--baseline=<path>", description: "Prompt file to treat as the control." },
+          { name: "--candidate=<path>", description: "Prompt file to treat as the variant." },
+          { name: "--conversations=<ids>", description: "Comma-separated conversation ids to replay." }
+        ],
+        examples: [
+          "moda prompts ab --baseline=prompts/agent.prompt.md --candidate=prompts/agent-v2.prompt.md --conversations=conv_1,conv_2"
+        ]
+      },
+      {
+        name: "propose",
+        description: "Revise a prompt from a run's failures",
+        usage: "moda prompts propose [--gate] [--promote-on-win]",
+        flags: [
+          { name: "--gate", description: "Automatically A/B the proposed revision." },
+          { name: "--promote-on-win", description: "Promote the candidate if it wins the gate." }
+        ],
+        examples: ["moda prompts propose --gate --promote-on-win"]
+      }
+    ],
     auth: "api-key",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
-    validateConfigBeforeRun: true,
+    validateConfigBeforeRun: (parsed) => !OFFLINE_PROMPTS_SUBCOMMANDS.has(parsed.positional ?? "status"),
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error"
   }),
@@ -6192,6 +6695,7 @@ var commandRegistry = createCommandRegistry([
       "moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md",
       "moda fix checkout <fix_id>",
       "moda fix submit <fix_id> --pr",
+      'moda fix mark-applied <fix_id> --note="tool description updated in our agent config"',
       'moda fix dismiss <fix_id> --reason="not actionable"'
     ],
     auth: "none",
@@ -6284,7 +6788,13 @@ async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
   if (command === "--help" || command === "-h" || flags.help === "true") {
     const helpTarget = command && command !== "--help" && command !== "-h" ? commandRegistry.find(command) : undefined;
     if (helpTarget) {
-      printCommandHelp(helpTarget);
+      const subcommandName = parsed.positional;
+      const subcommandEntry = subcommandName ? helpTarget.subcommands?.find((entry) => entry.name === subcommandName) : undefined;
+      if (subcommandEntry) {
+        printSubcommandHelp(helpTarget, subcommandEntry);
+      } else {
+        printCommandHelp(helpTarget);
+      }
     } else {
       printHelp();
     }
@@ -6329,7 +6839,8 @@ async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     })
   });
   setActiveContext(context);
-  if (definition.validateConfigBeforeRun) {
+  const needsConfig = typeof definition.validateConfigBeforeRun === "function" ? definition.validateConfigBeforeRun(parsed) : definition.validateConfigBeforeRun;
+  if (needsConfig) {
     try {
       validateConfig();
     } catch (error) {

package/dist/{index-fwxpt51s.js → index-g3gt62rm.js}

@@ -9,7 +9,7 @@ import {
   runPromptSync,
   runSkillSync,
   upsertSkillManifestRecord
-} from "./cli-cjqzrp9k.js";
+} from "./cli-x1a56ws9.js";
 import {
   codingAgentDisplayName,
   describeCodingAgentEvent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-08-17T23:28:03.271Z",
-  "cli_version": "1.27.0",
+  "bundled_at": "2026-08-19T21:29:46.133Z",
+  "cli_version": "1.28.0",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-version: 2.3.0
+version: 2.4.0
 description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — semantic/keyword/hybrid message search, overview KPIs, topic clusters, message context, user frustration detections, tool failures, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, wants to find conversations or tool calls about a topic, or wants to investigate how their AI agent is performing.
 ---
 
@@ -55,9 +55,9 @@ Optional:
 
 - `MODA_BASE_URL` defaults to `https://moda.dev`; override only for
   self-hosted or staging.
-- `MODA_SKILL_VERSION` — export to `2.3.0` so search-adoption telemetry can
+- `MODA_SKILL_VERSION` — export to `2.4.0` so search-adoption telemetry can
   attribute usage to this skill version. Set it once per session:
-  `export MODA_SKILL_VERSION=2.3.0`.
+  `export MODA_SKILL_VERSION=2.4.0`.
 
 ## Setup
 
@@ -106,10 +106,12 @@ Output shape:
 
 Rules and limitations:
 
-- **Requires an existing CLI session.** There is no browserless signup or
-  login: with no stored session it exits `4` (`auth_required`) telling you to
+- **Requires an existing CLI session.** Minting a *new* key is control-plane
+  work: with no stored session it exits `4` (`auth_required`) telling you to
   run `moda auth login` on a machine with a browser first, or to skip
-  provisioning and export `MODA_API_KEY` directly.
+  provisioning and export `MODA_API_KEY` directly. If you already hold a key,
+  you do not need this command at all — `moda auth login --api-key` gets you
+  to an authenticated state with no browser.
 - **Never prompts, even on a TTY.** A single-tenant account auto-selects;
   with multiple tenants you must pass `--tenant-id=<id>` (or set
   `MODA_TENANT_ID`), otherwise it exits `5` (`needs_input`) with per-tenant
@@ -134,13 +136,34 @@ just need credentials.
 
 ```bash
 moda auth login                  # browser PKCE sign-in; stores a moda_ct_ session token
+moda auth login --api-key        # NON-INTERACTIVE: validate MODA_API_KEY and save it
+moda auth login --non-interactive # never open a browser; fail if no key is available
+printf %s "$KEY" | moda auth login --api-key-stdin   # key never touches argv
+moda auth login --api-key=<key>  # inline; WARNS, key is visible in argv + shell history
 moda auth logout                 # revoke the session server-side, then delete it locally
-moda auth status                 # local session state; exit 0 logged in, exit 4 logged out
+moda auth status                 # both credentials; exit 0 if either is usable, else 4
 moda auth status --online        # additionally probe GET /api/cli/context
+moda auth whoami                 # identity from the session, or from the API key
 moda auth token                  # print the raw bearer token + newline, nothing else
 curl -H "Authorization: Bearer $(moda auth token)" https://moda.dev/api/cli/context
 ```
 
+**If you are an agent with `MODA_API_KEY` and no browser, this is the whole
+flow:**
+
+```bash
+moda auth whoami                 # exit 0 + "verified": true means you are authenticated
+```
+
+The API key alone is sufficient for every data command; `moda auth login` is
+only needed for control-plane work (`moda provision`, `moda init`). There are
+two independent credentials and `auth` reports both:
+
+| Credential | Obtained by | Used for |
+| --- | --- | --- |
+| `moda_ct_` session token | `moda auth login` (browser PKCE) | control plane: `provision`, `init`, `auth token` |
+| `moda_sk_` API key | `MODA_API_KEY`, `moda provision`, `moda init` | every data command |
+
 - `moda auth login` opens the browser consent flow at `{MODA_BASE_URL}/auth/cli`
   with a localhost callback (ports 8432-8435, first free). Approving in the
   browser hands the CLI a one-time code that it exchanges for a `moda_ct_...`
@@ -151,13 +174,45 @@ curl -H "Authorization: Bearer $(moda auth token)" https://moda.dev/api/cli/cont
 - `moda auth logout` revokes the stored `moda_ct_` session server-side
   (best-effort) and deletes the local credential; legacy sessions are just
   deleted locally.
+- `moda auth login --api-key` authenticates **without a browser**. Prefer
+  `MODA_API_KEY` (bare `--api-key`) or `--api-key-stdin`; `--api-key=<key>`
+  works but puts the secret in argv and shell history, so it warns. The key is
+  validated against the Data API before anything is written, then saved to
+  `~/.moda/config.json`. A rejected key (401/403) or an unreachable API both
+  fail without persisting. `--non-interactive` is the same path plus a
+  guarantee that no browser opens even when no key is found — it exits with
+  the commands that would mint one.
+- If `MODA_API_KEY` holds a **different** key than the one being saved, the
+  environment still wins afterwards. Login says so instead of reporting a
+  clean success: `"shadowed_by_env": true`, `"effective_credential": "env"`,
+  exit `3`. Unset `MODA_API_KEY` to use the saved credential.
+- `moda auth whoami` reports the browser session when there is one. With no
+  session but a usable API key it reports
+  `{ "credential": "api_key", "apiKeyCredential": { "source": <"env"|"profile"|"config">,
+  "masked": <string>, "verified": <bool> }, "tenant_id": <string|null> }`.
+  `verified: true` means the key was accepted by the API just now. If the API
+  is unreachable the command exits `3` (degraded) with `verified: false`
+  rather than claiming an identity it could not confirm; a rejected key is an
+  error, not a "logged out" state.
 - `moda auth status` reports
-  `{ "loggedIn": <bool>, "profile": <string|null>, "expiresAt": <ISO|null> }`
+  `{ "loggedIn": <bool>, "authenticated": <bool>, "apiKeyCredential": {...},
+  "profile": <string|null>, "expiresAt": <ISO|null> }`
   plus `"user": { "email": <string> }` when the stored session carries an
-  email (PKCE `moda_ct_` sessions do; legacy sessions omit it), and exits `4`
-  when logged out. That exit is an **expected state signal, not
-  an error**: the payload is clean data (no error block, no stderr noise), and
-  no browser is ever opened. With `--online` the payload adds
+  email (PKCE `moda_ct_` sessions do; legacy sessions omit it). `loggedIn` is
+  **browser-session only**; `authenticated` is true when *either* credential is
+  usable, and the exit code follows `authenticated` (`0` usable, `4` neither).
+  `apiKeyCredential` is `{ "present": false }` or
+  `{ "present": true, "source": <"env"|"profile"|"config">, "masked": <string>,
+  "tenantId": <string|null> }` — `source: "env"` tells you a `MODA_API_KEY` is
+  shadowing anything on disk. The raw key is never emitted. Exit `4` is an
+  **expected state signal, not an error**: the payload is clean data (no error
+  block, no stderr noise), and no browser is ever opened.
+  Without `--online` there is no network I/O, so `authenticated` means the
+  credential is **present**, not that it still works, and
+  `apiKeyCredential.verified` is `null`. With `--online` the key is probed too:
+  a rejected key gets `verified: false`, stops counting toward `authenticated`,
+  and exits `4`; an unreachable API leaves it counting, so a blip never kills a
+  good credential. With `--online` the payload adds
   `{ "online": { "reachable": <bool>, "ok": <bool>, "tenantCount": <n> } }`:
   `reachable: true` means any HTTP response arrived (even a 401/500), `ok`
   reflects HTTP success, and `tenantCount` is present only when the response
@@ -621,23 +676,35 @@ replay **gate** that proves it on held-out production evidence. Use this loop
 whenever you are asked to fix a detected Problem, or before hand-editing
 prompt/skill files in a repo that talks to Moda.
 
+Fixes are typed by where the evidence points: `PROMPT` (a managed prompt
+revision — the checkout/verify/submit loop below), `TOOL_SCHEMA` (a proposed
+rewrite of one tool's description), and `SKILL` (a drafted SKILL.md for an
+agent-behavior problem). Tool and skill candidates are not repo files: read
+them from the packet (they are also written locally under
+`.moda/fixes/<SHORTREF>/`), apply them in your own stack, then confirm with
+`moda fix mark-applied` — no GitHub integration required.
+
 The fail-to-pass loop:
 
 ```bash
 moda fixes                                   # ranked queue of fixes with proof
 moda fix <fix_id> --packet                   # moda.fix_packet.v1: cause, target
                                              # file, evidence links, verify cmd,
-                                             # handback + magic word
+                                             # handback + magic word; tool/skill
+                                             # candidates land in .moda/fixes/
 moda fix start <problem_id> --wait           # draft from a Problem and drive
                                              # scope -> propose -> gate
-moda fix checkout <fix_id>                   # write the candidate at its target
-                                             # source path (NEVER runs git)
+moda fix checkout <fix_id>                   # PROMPT fixes: write the candidate
+                                             # at its target source path
+                                             # (NEVER runs git)
 # ...edit the target file...
 moda fix verify <fix_id> --prompt-file=<path>  # re-gate local content on the
-                                               # frozen holdout
+                                               # frozen holdout (PROMPT only)
 # iterate edit -> verify until exit 0, then hand back:
 moda fix submit <fix_id> --pr                # draft PR via the Moda GitHub App
 moda fix submit <fix_id> --local-ref=<branch>  # or record your own branch
+moda fix mark-applied <fix_id> --note="…"    # tool/skill/no-PR path: confirm a
+                                             # candidate you applied yourself
 moda fix dismiss <fix_id> --reason="why"     # reject (feeds problem feedback)
 ```
 
@@ -660,6 +727,15 @@ Rules that keep the proof honest:
 - Fix PRs end with the magic word `Fixes MODA-FIX-<SHORTREF>` in the body —
   Moda-authored PRs carry it automatically; hand-authored PRs must include it
   so the merge confirms the fix and starts production monitoring.
+- `mark-applied` is the confirmation for changes shipped without a PR (tool
+  descriptions, installed skills, hand-applied prompts): it flips the fix to
+  `SHIPPED`, records your `--note`, and starts the same monitoring the merge
+  webhook would. It is idempotent — repeating it is a duplicate no-op.
+- `TOOL_SCHEMA` fixes gate like prompt fixes (both arms pin the same current
+  prompt; the proposed description is the only delta). `SKILL` fixes rest at
+  `PROPOSED` until the skill is registered with the Moda skill harness — an
+  inline drafted SKILL.md cannot enter the gate, so deliver it via the packet
+  and `mark-applied`.
 - The pipeline is advance-on-poll: `--wait` (on `start`, `verify`, or
   `moda fix <fix_id> --wait`) drives it; a fix left `GATING` will not finish
   on its own.
@@ -813,8 +889,10 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda init` | Browser auth + provision API key + install agent rules |
 | `moda provision` | Headless tenant + API key provisioning; single JSON credentials doc on stdout (exit `4` without a session, `5` when `--tenant-id` is needed) |
 | `moda auth login` | Browser PKCE sign-in; stores a revocable `moda_ct_` session token |
+| `moda auth login --api-key` | Non-interactive: validate `MODA_API_KEY` (or `--api-key=<key>`) and save it; never opens a browser |
+| `moda auth whoami` | Authenticated identity from the session, or from the API key when there is no session |
 | `moda auth logout` | Revoke the CLI session server-side, then delete it locally |
-| `moda auth status` | Local auth session state (exit `4` = logged out — expected, not an error) |
+| `moda auth status` | Both credentials; exit `0` if either is usable, `4` if neither (expected, not an error) |
 | `moda auth token` | Print the raw bearer token for `$(moda auth token)` composition |
 | `moda search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
 | `moda overview` | Dashboard KPIs, top clusters, recent activity |
@@ -842,11 +920,12 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |
 | `moda prompts promote <key>` | Move a remote prompt label |
 | `moda fixes` | Ranked queue of Fixes ("a fix with proof"); `--status=S`, `--limit=N`, `--cursor=TOKEN` |
-| `moda fix <fix_id>` | One Fix: status + gate result; `--packet` prints `moda.fix_packet.v1`; `--wait` drives a running pipeline to rest |
+| `moda fix <fix_id>` | One Fix: status + gate result; `--packet` prints `moda.fix_packet.v1` and writes tool/skill candidates under `.moda/fixes/<ref>/`; `--wait` drives a running pipeline to rest |
 | `moda fix start <problem_id>` | Draft a Fix from a Problem (`--type=auto\|prompt`); `--wait` drives scope → propose → gate |
-| `moda fix verify <fix_id>` | Re-gate on the frozen holdout; `--prompt-file=P` gates local content (exit `0` pass / `1` fail with per-case findings / `3` degraded — never a pass) |
-| `moda fix checkout <fix_id>` | Write the candidate at its target source path (never runs git) |
+| `moda fix verify <fix_id>` | Re-gate on the frozen holdout; `--prompt-file=P` gates local content, PROMPT fixes only (exit `0` pass / `1` fail with per-case findings / `3` degraded — never a pass) |
+| `moda fix checkout <fix_id>` | Write the candidate at its target source path (never runs git; PROMPT fixes only) |
 | `moda fix submit <fix_id>` | Deliver: `--pr` opens a draft PR \| `--local-ref=<branch>` records your branch |
+| `moda fix mark-applied <fix_id>` | Confirm a candidate you applied in your own stack (`--note=TEXT`, ≤600 chars); no PR needed — flips to SHIPPED and starts monitoring |
 | `moda fix dismiss <fix_id>` | Reject with `--reason=TEXT` (feeds problem feedback) |
 
 `moda search` flags: `--mode=keyword|semantic|hybrid` (default `hybrid`),