@primitivedotdev/sdk 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "./types-9vXGZjPd.js";
 import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
-import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendResult, f as SendThreadInput, h as createPrimitiveClient, l as ReplyInput, n as ForwardInput, p as client, s as PrimitiveClient, u as SendInput } from "./index-K4KbjppU.js";
+import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendResult, f as SendThreadInput, h as createPrimitiveClient, l as ReplyInput, n as ForwardInput, p as client, s as PrimitiveClient, u as SendInput } from "./index-Cts9r1sL.js";
 import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CbEivn3S.js";
 
 //#region src/index.d.ts

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "./received-email-D6tKtWwW.js";
-import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-CLLpjjWy.js";
+import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DH-YKt7a.js";
 import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-zkN4wUTs.js";
 //#region src/index.ts
 const primitive = {

package/dist/oclif/api-command.js

@@ -67,8 +67,22 @@ function extractBodyFields(schema) {
                 kind = "complex";
             }
         }
+        // Pull the first paragraph of the schema description for use
+        // as the CLI flag's --help string. We split on a blank line
+        // (paragraph break) and then collapse any soft line wraps
+        // inside that paragraph to spaces. This avoids the previous
+        // bug where `split("\n")[0]` truncated wrapped prose like
+        //   "Optional override for ... Defaults to\nthe inbound's..."
+        // to "Optional override for ... Defaults to" - a sentence
+        // ending with "to" with nothing after it, which read as
+        // ellipsis truncation in --help. The remaining paragraphs
+        // are intentionally dropped so multi-paragraph schemas don't
+        // blow out the per-flag help block.
         const description = typeof propSchema.description === "string"
-            ? propSchema.description.split("\n")[0].trim()
+            ? propSchema.description
+                .split(/\n\s*\n/)[0]
+                .replace(/\s*\n\s*/g, " ")
+                .trim()
             : "";
         const enumRaw = propSchema.enum;
         const enumValues = kind === "string" && Array.isArray(enumRaw)
@@ -242,6 +256,52 @@ export function formatErrorPayload(payload) {
     }
     return JSON.stringify(payload, null, 2);
 }
+// Pull the top-level error code out of either a server response
+// payload (`{ error: { code: '...' } }` or `{ code: '...' }`) or a
+// thrown Error whose `cause.code` carries the value. Used to drive
+// `--api-key` and similar hints in writeErrorWithHints below.
+// Also exported so individual commands (send, whoami) can branch
+// on auth failures and avoid surfacing misleading "fix this flag"
+// guidance when the real problem is the API key.
+export function extractErrorCode(payload) {
+    if (payload instanceof Error) {
+        const { code } = extractCauseDetails(payload.cause);
+        return code;
+    }
+    if (payload && typeof payload === "object") {
+        const inner = payload.error;
+        if (inner && typeof inner === "object" && typeof inner.code === "string") {
+            return inner.code;
+        }
+        const direct = payload.code;
+        if (typeof direct === "string")
+            return direct;
+    }
+    return undefined;
+}
+// Common-case actionable hints keyed by error code. The full
+// JSON envelope still goes to stderr unchanged for any caller
+// that wants to parse it; the hint is an extra trailing line so
+// a human reading the output sees "what to actually do next."
+// The AGX walkthrough flagged that an `unauthorized` envelope
+// alone left the agent without context for the env var or the
+// `--api-key` flag; this closes that gap without having to
+// special-case every command.
+const ERROR_CODE_HINTS = {
+    unauthorized: "Hint: pass --api-key explicitly, or set PRIMITIVE_API_KEY in your environment. `primitive whoami` is the fastest way to verify a key is live.",
+};
+// Write a server / SDK error to stderr in the canonical envelope
+// shape, plus an actionable hint when the code is one we know how
+// to advise on. Replaces the bare
+// `process.stderr.write(${formatErrorPayload(p)}\n)` dance every
+// command was doing.
+export function writeErrorWithHints(payload) {
+    process.stderr.write(`${formatErrorPayload(payload)}\n`);
+    const code = extractErrorCode(payload);
+    if (code && ERROR_CODE_HINTS[code]) {
+        process.stderr.write(`${ERROR_CODE_HINTS[code]}\n`);
+    }
+}
 // Reserved flag names the body-field expander must never overwrite.
 // `--raw-body` and `--body-file` are the JSON escape hatches.
 // `--api-key`, `--base-url`, `--output` are infra. Path and query
@@ -266,22 +326,23 @@ const RESERVED_FLAG_NAMES = new Set([
     "output",
 ]);
 function bodyFieldFlag(field) {
-    // Flag descriptions cap at 80 chars so oclif's --help output
-    // stays readable; the schema's full description is also visible
-    // via `primitive list-operations | jq`.
-    const descMax = 80;
-    const trimmedDesc = field.description.length > descMax
-        ? `${field.description.slice(0, descMax - 3)}...`
-        : field.description;
+    // Pass the full first-line description through. oclif's --help
+    // renderer wraps long values across multiple lines on its own,
+    // so a fixed character cap here just produces ellipsis-truncated
+    // sentences ("body_html is required. Th...") that mislead the
+    // reader. extractBodyFields already normalizes by taking only
+    // the first paragraph of the schema description, so multi-
+    // paragraph fields don't blow out the help.
+    //
     // Field-flag UX choice: do NOT mark scalar body fields as
     // required at the oclif level even when the JSON Schema marks
     // them required. Reason: a caller can satisfy the requirement
-    // either via the individual flag OR via --body / --body-file.
+    // either via the individual flag OR via --raw-body / --body-file.
     // Marking the flag required would force the individual-flag
     // form. The runtime body merger validates the final assembled
     // body against the same server-side schema either way.
     const common = {
-        description: trimmedDesc || field.name,
+        description: field.description || field.name,
     };
     if (field.kind === "boolean")
         return Flags.boolean(common);
@@ -460,8 +521,7 @@ export function createOperationCommand(operation) {
                 responseStyle: "fields",
             });
             if (result.error) {
-                const errorPayload = extractErrorPayload(result.error);
-                process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+                writeErrorWithHints(extractErrorPayload(result.error));
                 process.exitCode = 1;
                 return;
             }

package/dist/oclif/commands/emails-latest.js

@@ -0,0 +1,118 @@
+import { Command, Flags } from "@oclif/core";
+import { listEmails } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
+// `primitive emails:latest` is the agent-grade shortcut for "show me
+// the most recent inbound emails as something I can read at a glance."
+// `emails:list-emails` returns the full JSON envelope which is great
+// for piping but blows out the screen for a quick triage. The AGX
+// walkthrough flagged that an agent doing inbox triage had no compact
+// view to reach for; `latest` is that view.
+//
+// Output is a fixed-width text table: short-id, received timestamp,
+// from address, to address, and subject. Subject is truncated for
+// display only; the underlying JSON is unchanged. For machine-readable
+// output, callers should use `emails:list-emails` and pipe to jq.
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+// Truncation widths chosen so a row fits in ~140 columns total. Long
+// values wrap to "..." rather than blowing out terminal layout.
+const SUBJECT_DISPLAY_WIDTH = 50;
+const ADDRESS_DISPLAY_WIDTH = 32;
+const ID_DISPLAY_WIDTH = 8;
+const RECEIVED_DISPLAY_WIDTH = 19;
+// Truncate to width with right-padding; values longer than width are
+// cut to width-3 with a "..." suffix so the output is exactly `width`
+// chars (3 of which are the ellipsis). Display-only; never mutates
+// the underlying value the caller passed in.
+//
+// Width-exact output matters here: formatRow relies on each column
+// being exactly its declared width so columns line up across rows.
+// An overflowing truncate would shift every later column to the
+// right whenever truncation fired (e.g. a row with both addresses
+// truncated would push SUBJECT 4 chars off).
+export function truncate(value, width) {
+    if (value.length <= width)
+        return value.padEnd(width);
+    return `${value.slice(0, width - 3)}...`;
+}
+// Compact ISO timestamp for display: `YYYY-MM-DD HH:MM:SS` in UTC.
+// The full ISO string with milliseconds and `T`/`Z` markers is too
+// dense to scan at a glance; this is the same shape git log uses.
+export function formatReceivedAt(value) {
+    if (!value)
+        return "-".padEnd(RECEIVED_DISPLAY_WIDTH);
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return value.padEnd(RECEIVED_DISPLAY_WIDTH);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+export function formatRow(email) {
+    const id = truncate(email.id.slice(0, ID_DISPLAY_WIDTH), ID_DISPLAY_WIDTH);
+    const received = formatReceivedAt(email.received_at);
+    const from = truncate(email.sender ?? "", ADDRESS_DISPLAY_WIDTH);
+    const to = truncate(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH);
+    const subject = (email.subject ?? "").replace(/\s+/g, " ");
+    const subjectCol = truncate(subject, SUBJECT_DISPLAY_WIDTH);
+    return `${id}  ${received}  ${from}  ${to}  ${subjectCol}`;
+}
+class EmailsLatestCommand extends Command {
+    static description = `Print the N most recent inbound emails as a one-line-per-row text table. Designed for quick triage and visual scanning. For programmatic access, use \`primitive emails:list-emails\` (full JSON envelope, cursor pagination, filters).
+
+  The displayed id is the first ${ID_DISPLAY_WIDTH} characters of the email's UUID; pass the full UUID (from \`emails:list-emails\` or \`emails:get-email\`) to operations that need it.`;
+    static summary = "Show the most recent inbound emails as a compact table";
+    static examples = [
+        "<%= config.bin %> emails:latest",
+        "<%= config.bin %> emails:latest --limit 25",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "base-url": Flags.string({
+            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
+            env: "PRIMITIVE_API_URL",
+        }),
+        limit: Flags.integer({
+            description: `Number of rows to print (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}).`,
+            default: DEFAULT_LIMIT,
+            // oclif validates min/max at parse time and emits a consistent
+            // out-of-range error before run() is reached, so no manual
+            // bounds check is needed here.
+            min: 1,
+            max: MAX_LIMIT,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EmailsLatestCommand);
+        const apiClient = new PrimitiveApiClient({
+            apiKey: flags["api-key"],
+            baseUrl: flags["base-url"],
+        });
+        const result = await listEmails({
+            client: apiClient.client,
+            query: { limit: flags.limit },
+            responseStyle: "fields",
+        });
+        if (result.error) {
+            writeErrorWithHints(extractErrorPayload(result.error));
+            process.exitCode = 1;
+            return;
+        }
+        const envelope = result.data;
+        const rows = envelope?.data ?? [];
+        if (rows.length === 0) {
+            process.stderr.write("No inbound emails yet. Send an email to one of your verified domains to populate this list.\n");
+            return;
+        }
+        // Header on stderr so the table itself stays grep-friendly.
+        const header = `${"ID".padEnd(ID_DISPLAY_WIDTH)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
+        process.stderr.write(`${header}\n`);
+        for (const row of rows) {
+            this.log(formatRow(row));
+        }
+    }
+}
+export default EmailsLatestCommand;

package/dist/oclif/commands/send.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { listDomains, sendEmail } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, formatErrorPayload } from "../api-command.js";
+import { extractErrorCode, extractErrorPayload, formatErrorPayload, writeErrorWithHints, } from "../api-command.js";
 // `primitive send` is the agent-grade shortcut for the most common
 // case: send a fresh outbound email. It wraps `sending:send-email`
 // with two ergonomic defaults that the underlying operation can't
@@ -30,7 +30,15 @@ import { extractErrorPayload, formatErrorPayload } from "../api-command.js";
 // pattern-matching from there lands in the happy path. We just
 // don't need swaks's `--server` / `--auth-*` flags because the
 // HTTPS API key is the auth and the server is implicit.
-const SUBJECT_MAX_LENGTH = 70;
+// 200 chars is a generous cap that almost never trips on natural
+// first-line subjects (a sentence is typically <120 chars). The
+// previous 70-char limit was tight enough that legitimate one-line
+// bodies routinely produced ellipsis-truncated subjects in inbox
+// listings, e.g. `"this is the simplest possible send: agent typed
+// two flags and hit\\n e..."` from the AGX walkthrough. Real spam
+// scoring engines don't penalize subjects under ~200 chars, so 200
+// is both more useful and still well under the practical wire limit.
+const SUBJECT_MAX_LENGTH = 200;
 function deriveSubject(body) {
     for (const line of body.split("\n")) {
         const trimmed = line.trim();
@@ -52,6 +60,20 @@ async function pickDefaultFromAddress(apiClient) {
     });
     if (result.error) {
         const errorPayload = extractErrorPayload(result.error);
+        // If the underlying failure is an auth problem, don't pretend
+        // --from will fix it: the actual sendEmail call would 401 too.
+        // Surface the auth hint via writeErrorWithHints and bail with
+        // a focused message instead of the verbose "underlying error"
+        // wrapping.
+        if (extractErrorCode(errorPayload) === "unauthorized") {
+            writeErrorWithHints(errorPayload);
+            // exit: 1 to match the run() unauthorized path (which uses
+            // `process.exitCode = 1`). oclif's CLIError defaults to 2,
+            // so without this override the same "unauthorized" condition
+            // exits 2 when surfaced from listDomains and 1 when surfaced
+            // from sendEmail, breaking callers that branch on exit code.
+            throw new Errors.CLIError("Cannot send: API key is missing or invalid (see hint above).", { exit: 1 });
+        }
         throw new Errors.CLIError(`Could not look up your verified domains to default --from. Pass --from explicitly. Underlying error: ${formatErrorPayload(errorPayload)}`);
     }
     const envelope = result.data;
@@ -147,8 +169,7 @@ class SendCommand extends Command {
             responseStyle: "fields",
         });
         if (result.error) {
-            const errorPayload = extractErrorPayload(result.error);
-            process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+            writeErrorWithHints(extractErrorPayload(result.error));
             process.exitCode = 1;
             return;
         }

package/dist/oclif/commands/whoami.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { getAccount } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, formatErrorPayload } from "../api-command.js";
+import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
 // `primitive whoami` is the credentials smoke-test the AGX
 // walkthrough kept asking for. Before this command, a user with a
 // suspect API key had no fast way to verify "is my key live and
@@ -40,8 +40,7 @@ class WhoamiCommand extends Command {
             responseStyle: "fields",
         });
         if (result.error) {
-            const errorPayload = extractErrorPayload(result.error);
-            process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+            writeErrorWithHints(extractErrorPayload(result.error));
             process.exitCode = 1;
             return;
         }

package/dist/oclif/index.js

@@ -1,16 +1,73 @@
-import { Args, Command } from "@oclif/core";
+import { Args, Command, Errors } from "@oclif/core";
 import { operationManifest, } from "../openapi/index.js";
 import { createOperationCommand } from "./api-command.js";
+import EmailsLatestCommand from "./commands/emails-latest.js";
 import SendCommand from "./commands/send.js";
 import WhoamiCommand from "./commands/whoami.js";
 import { renderFishCompletion } from "./fish-completion.js";
 class ListOperationsCommand extends Command {
-    static description = "List all generated API operations";
-    static summary = "List all generated API operations";
+    static description = "List all generated API operations as JSON. Useful for piping to `jq` to discover available commands, their request/response schemas, and per-field descriptions. For inspecting a single operation in detail, prefer `primitive describe <command>`.";
+    static summary = "List all generated API operations (JSON)";
     async run() {
         this.log(JSON.stringify(operationManifest, null, 2));
     }
 }
+// Looks up an operation manifest entry by its `<topic>:<command>` id
+// (e.g. `emails:get-email`). On miss, returns up to 5 closest
+// candidates by substring match so the caller can render a
+// "did you mean" hint. Pure function: no oclif config dependency,
+// so it's also unit-testable in isolation.
+export function lookupOperation(id) {
+    const trimmed = id.trim();
+    const sep = trimmed.indexOf(":");
+    const tag = sep === -1 ? "" : trimmed.slice(0, sep);
+    const cmd = sep === -1 ? trimmed : trimmed.slice(sep + 1);
+    const match = operationManifest.find((op) => op.command === cmd && op.tagCommand === tag) ?? null;
+    if (match)
+        return { match, candidates: [] };
+    const candidates = operationManifest
+        .filter((op) => op.command.includes(cmd) || op.tagCommand.includes(tag))
+        .slice(0, 5)
+        .map((op) => op.tagCommand ? `${op.tagCommand}:${op.command}` : op.command);
+    return { match: null, candidates };
+}
+// `primitive describe <command>` is the operation-detail inspector
+// the AGX walkthrough kept wanting. The information is already in
+// the operation manifest emitted by `list-operations`, but agents
+// don't intuitively reach for `list-operations | jq '.[] | select(...)'`
+// when they want to know "what does the from_email field on this
+// response actually mean." A direct command is more discoverable.
+//
+// Lookup is by the colon-joined command id (e.g. `emails:get-email`,
+// `sending:send-email`, `account:get-account`). For top-level
+// generated commands (without a topic), pass the bare command id.
+class DescribeCommand extends Command {
+    static args = {
+        command: Args.string({
+            description: "Command id to describe, in `<topic>:<command>` form (e.g. `emails:get-email`). Run `primitive list-operations | jq -r '.[] | \"\\(.tagCommand):\\(.command)\"'` to enumerate.",
+            required: true,
+        }),
+    };
+    static description = `Print the full operation manifest entry for a single API command, including the path, request schema, response schema, and per-field descriptions sourced from the OpenAPI spec.
+
+  Useful for clarifying response field meanings (e.g. on inbound EmailDetail, which of \`sender\`, \`from_email\`, \`from_header\`, and \`smtp_mail_from\` to read), confirming required body fields, or checking a path's parameter shape before composing a request.`;
+    static summary = "Describe a single API operation in detail";
+    static examples = [
+        "<%= config.bin %> describe emails:get-email",
+        "<%= config.bin %> describe sending:send-email",
+    ];
+    async run() {
+        const { args } = await this.parse(DescribeCommand);
+        const { match, candidates } = lookupOperation(args.command);
+        if (!match) {
+            const hint = candidates.length > 0
+                ? `Did you mean: ${candidates.join(", ")}?`
+                : "Run `primitive list-operations` to enumerate.";
+            throw new Errors.CLIError(`Unknown operation \`${args.command.trim()}\`. ${hint}`, { exit: 1 });
+        }
+        this.log(JSON.stringify(match, null, 2));
+    }
+}
 class CompletionCommand extends Command {
     static args = {
         shell: Args.string({
@@ -40,6 +97,11 @@ const generatedCommands = Object.fromEntries(operationManifest.map((operation) =
 export const COMMANDS = {
     completion: CompletionCommand,
     "list-operations": ListOperationsCommand,
+    // `describe` prints a single operation's full manifest entry
+    // (path, request schema, response schema, per-field descriptions).
+    // The same data is in `list-operations` but agents don't reach for
+    // `list-operations | jq` when they want to clarify a field meaning.
+    describe: DescribeCommand,
     // `send` is the agent-grade shortcut for sending:send-email with
     // sensible defaults (auto from-address, auto subject). The full
     // operation stays available under sending:send-email for callers
@@ -50,5 +112,9 @@ export const COMMANDS = {
     // wanting this before risking a real call against a possibly-
     // bad key.
     whoami: WhoamiCommand,
+    // `emails:latest` is the inbox-triage shortcut: the most recent N
+    // inbound emails as a compact text table. emails:list-emails stays
+    // available for the full JSON envelope + cursor pagination.
+    "emails:latest": EmailsLatestCommand,
     ...generatedCommands,
 };