@dench.com/cli 3.6.6-staging.386 → 3.7.0-staging.387

package/lib/api-schemas.ts

@@ -57,6 +57,48 @@ const nativeEmailCreate = z.object({
   requestId: z.string(),
   ...nativeEmailContent,
 });
+const inboxHeader = z.object({
+  messageHandle: z.string(),
+  threadHandle: z.string(),
+  mailboxId: z.string(),
+  from: nativeEmailRecipient,
+  to: z.array(nativeEmailRecipient),
+  subject: z.string(),
+  at: z.number(),
+  dateSource: z.enum(["sentAt", "createdAt"]),
+  direction: z.enum(["inbound", "outbound"]),
+  status: z.string(),
+  hasAttachments: z.boolean(),
+  headersTruncated: z.boolean(),
+});
+const inboxCoverage = z.object({
+  source: z.literal("synced"),
+  scope: z.literal("mailbox_linked_messages"),
+  mailboxId: z.string(),
+  mailboxEmail: z.string(),
+  mailboxStatus: z.string(),
+  ingestionMode: z.string(),
+  phase: z.string(),
+  syncStatus: z.string().nullable(),
+  lastPolledAt: z.number().nullable(),
+  lastBackfillCompletedAt: z.number().nullable(),
+  oldestSeenAt: z.number().nullable(),
+  backfillStatus: z.string().nullable(),
+  backfillCapped: z.boolean(),
+  providerComplete: z.literal(false),
+  privacyLimited: z.boolean(),
+});
+const inboxPaging = {
+  limit: z.coerce.number().int().min(1).max(50).optional(),
+  cursor: z.string().optional(),
+};
+const inboxPage = z.object({
+  page: z.array(inboxHeader),
+  continueCursor: z.string().nullable(),
+  isDone: z.boolean(),
+  coverage: inboxCoverage,
+  order: z.literal("sentAt_desc_then_undated"),
+});
 const nativeEmailReceipt = z
   .object({
     ok: z.boolean(),
@@ -2118,7 +2160,7 @@ const composioToolRun = z.object({
   tool_slug: z
     .string()
     .optional()
-    .describe("Tool slug, e.g. GMAIL_FETCH_EMAILS."),
+    .describe("Tool slug, e.g. SLACK_LIST_CHANNELS."),
   arguments: z
     .record(z.string(), z.unknown())
     .optional()
@@ -3392,8 +3434,34 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
       )
       .optional(),
   }),
+  "email.inbox.search": z.object({
+    ...inboxPaging,
+    mailbox: z.string().optional(),
+    from: z.string().min(1).max(500).optional(),
+    to: z.string().min(1).max(500).optional(),
+    subject: z.string().min(1).max(500).optional(),
+    after: z.coerce
+      .number()
+      .optional()
+      .describe(
+        "Inclusive Unix milliseconds; missing sentAt falls back to createdAt.",
+      ),
+    before: z.coerce
+      .number()
+      .optional()
+      .describe("Exclusive Unix milliseconds."),
+    direction: z.enum(["inbound", "outbound"]).optional(),
+  }),
+  "email.inbox.thread": z.object({ ...inboxPaging, threadHandle: z.string() }),
+  "email.inbox.message": z.object({
+    messageHandle: z.string(),
+    format: z.enum(["text", "html"]).optional(),
+    maxBytes: z.coerce.number().int().min(1).max(100000).optional(),
+  }),
   "email.drafts.create": nativeEmailCreate,
-  "email.native.send": nativeEmailCreate,
+  "email.native.send": nativeEmailCreate.extend({
+    to: z.array(nativeEmailRecipient).min(1),
+  }),
   "email.drafts.get": z.object({ draftId: z.string() }),
   "email.drafts.senders": z.object({ organizationId: z.string().optional() }),
   "email.drafts.update": z.object({
@@ -3536,6 +3604,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
 
   // CRM objects
   "crm.objects.list": noInput,
+  "crm.objects.listCompact": noInput,
   "crm.objects.get": z.object({ name: z.string() }),
   "crm.objects.create": z.object({
     name: z.string().describe("Object name (lowercased, singular)."),
@@ -3631,6 +3700,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
 
   // CRM fields
   "crm.fields.list": z.object({ objectName: z.string() }),
+  "crm.fields.listCompact": z.object({ objectName: z.string() }),
   "crm.fields.create": z.object({
     objectName: z.string(),
     name: z.string(),
@@ -4163,6 +4233,18 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
         "Number field to total per bucket (e.g. Amount grouped by Stage). Exact at any table size.",
       ),
   }),
+  "crm.search.page": z.object({
+    text: z.string().describe("Full-text query over readable entries."),
+    objectName: z.string().optional(),
+    select: z.array(z.string().min(1)).min(1).max(30).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    cursor: z
+      .string()
+      .optional()
+      .describe(
+        "Use the preceding continueCursor, with the same query and projection.",
+      ),
+  }),
   "crm.search": z.object({
     text: z.string().describe("Full-text query."),
     objectName: z.string().optional().describe("Omit to search org-wide."),
@@ -5157,6 +5239,24 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // Workspace orientation
   "workspace.context.sections": z.object({}).passthrough(),
+  "email.inbox.search": inboxPage,
+  "email.inbox.thread": inboxPage,
+  "email.inbox.message": z.object({
+    header: inboxHeader,
+    coverage: inboxCoverage,
+    body: z.object({
+      format: z.enum(["text", "html"]),
+      content: z.string(),
+      truncated: z.boolean(),
+      totalBytes: z.number(),
+    }),
+    recipients: z.object({
+      to: z.array(nativeEmailRecipient),
+      cc: z.array(nativeEmailRecipient),
+      bcc: z.array(nativeEmailRecipient),
+      truncated: z.boolean(),
+    }),
+  }),
   "email.drafts.create": nativeEmailReceipt,
   "email.drafts.get": nativeEmailReceipt,
   "email.drafts.update": nativeEmailReceipt,
@@ -5283,6 +5383,18 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // CRM objects
   "crm.objects.list": z.array(crmObjectDoc),
+  "crm.objects.listCompact": z.array(
+    z.object({
+      _id: z.string(),
+      name: z.string(),
+      displayName: z.string(),
+      description: z.string().optional(),
+      entryCount: z.number().nullable(),
+      countScope: z.enum(["workspace", "private_unknown"]),
+      visibility: z.enum(["workspace", "owner_only", "owner_plus_members"]),
+      archived: z.boolean(),
+    }),
+  ),
   "crm.objects.get": crmObjectDoc.nullable(),
   "crm.objects.create": z.object({ id: z.string() }),
   "crm.objects.update": okResponse,
@@ -5337,6 +5449,20 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // CRM fields
   "crm.fields.list": z.array(crmFieldDoc),
+  "crm.fields.listCompact": z.array(
+    z.object({
+      _id: z.string(),
+      name: z.string(),
+      type: z.string(),
+      required: z.boolean(),
+      readOnly: z.boolean(),
+      defaultValue: z.string().optional(),
+      enumValues: z.array(z.string()).optional(),
+      enumMultiple: z.boolean(),
+      relatedObjectId: z.string().optional(),
+      relationshipType: z.string().optional(),
+    }),
+  ),
   "crm.fields.create": z.object({ id: z.string() }),
   "crm.fields.update": okResponse,
   "crm.fields.delete": okResponse,
@@ -5493,6 +5619,16 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
       sumNumber: z.number().optional(),
     }),
   ),
+  "crm.search.page": z.object({
+    page: z.array(
+      z.object({ _id: z.string(), objectId: z.string(), data: fieldsMap }),
+    ),
+    isDone: z.boolean(),
+    continueCursor: z.string().nullable(),
+    returnedCount: z.number(),
+    selectedFields: z.array(z.string()).nullable(),
+    completeness: z.literal("page"),
+  }),
   "crm.search": z.array(
     z
       .object({
@@ -6217,6 +6353,12 @@ export const convexExtras: Record<string, ConvexExtras> = {
 // ---------------------------------------------------------------------------
 
 export const requestExamples: Record<string, unknown> = {
+  "email.native.send": {
+    requestId: "send-intro-001",
+    to: [{ email: "ada@example.com", name: "Ada" }],
+    subject: "Introduction",
+    textBody: "Hello Ada",
+  },
   "campaigns.accounts.linkedin": {},
   "campaigns.create": {
     name: "Founder outreach",
@@ -6470,11 +6612,11 @@ export const requestExamples: Record<string, unknown> = {
     input_images_base64: ["iVBORw0KGgoAAAANSUhEUg..."],
   },
   "tool.search": {
-    queries: [{ use_case: "fetch the 10 most recent emails" }],
+    queries: [{ use_case: "list Slack channels" }],
   },
   "tool.run": {
-    tool_slug: "GMAIL_FETCH_EMAILS",
-    arguments: { max_results: 10 },
+    tool_slug: "SLACK_LIST_CHANNELS",
+    arguments: { limit: 10 },
   },
   "crm.people.search": {
     titles: ["Head of Sales"],
@@ -8019,18 +8161,18 @@ export const responseExamples: Record<string, unknown> = {
     error: null,
     results: [
       {
-        use_case: "fetch recent emails",
-        primary_tool_slugs: ["GMAIL_FETCH_EMAILS"],
-        toolkits: ["gmail"],
+        use_case: "list Slack channels",
+        primary_tool_slugs: ["SLACK_LIST_CHANNELS"],
+        toolkits: ["slack"],
       },
     ],
     toolkit_connection_statuses: [
-      { toolkit: "gmail", has_active_connection: true },
+      { toolkit: "slack", has_active_connection: true },
     ],
     tool_schemas: {
-      GMAIL_FETCH_EMAILS: {
-        toolkit: "gmail",
-        tool_slug: "GMAIL_FETCH_EMAILS",
+      SLACK_LIST_CHANNELS: {
+        toolkit: "slack",
+        tool_slug: "SLACK_LIST_CHANNELS",
         execution_ref: "eyJzZXNzaW9uIjoi...",
         execution_ref_version: 1,
       },
@@ -8039,11 +8181,11 @@ export const responseExamples: Record<string, unknown> = {
     execution_ref_version: 1,
   },
   "tool.run": {
-    data: { messages: [{ id: "msg01", subject: "Quick intro" }] },
+    data: { channels: [{ id: "C_EXAMPLE", name: "general" }] },
     error: null,
     log_id: "log_exec_01",
     execution_mode: "gateway_tool_router",
-    tool_slug: "GMAIL_FETCH_EMAILS",
+    tool_slug: "SLACK_LIST_CHANNELS",
     tool_router_session_id: "trs_abc123",
   },
   "tool.disconnect": { id: "ca_github01", deleted: true },

package/lib/app-sdk-catalog.generated.ts

@@ -141,6 +141,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"chat.send","group":"chat","summary":"Send a message to an existing chat thread.","cli":"dench chat send","method":"POST","path":"/chat/threads/{threadId}/messages","permission":"ai:chat","pathParams":["threadId"]},
   {"id":"chat.follow","group":"chat","summary":"Follow a live chat response stream.","cli":"dench chat follow","method":"GET","path":"/chat/threads/{threadId}/stream","permission":"ai:chat","pathParams":["threadId"]},
   {"id":"crm.objects.list","group":"crm","summary":"List CRM objects.","cli":"dench crm objects list","method":"GET","path":"/crm/objects","permission":"crm:read","pathParams":[]},
+  {"id":"crm.objects.listCompact","group":"crm","summary":"List names, display labels, visibility and workspace counts without internal state.","cli":"dench crm objects list --compact","method":"GET","path":"/crm/catalog/objects","permission":"crm:read","pathParams":[]},
   {"id":"crm.objects.get","group":"crm","summary":"Get a CRM object.","cli":"dench crm objects get","method":"GET","path":"/crm/objects/{name}","permission":"crm:read","pathParams":["name"]},
   {"id":"crm.objects.create","group":"crm","summary":"Create a CRM object.","cli":"dench crm objects create","method":"POST","path":"/crm/objects","permission":"crm:write","pathParams":[]},
   {"id":"crm.objects.update","group":"crm","summary":"Update a CRM object.","cli":"dench crm objects update","method":"PATCH","path":"/crm/objects/{name}","permission":"crm:write","pathParams":["name"]},
@@ -165,6 +166,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"crm.sidebar.groups.move-item","group":"crm","summary":"Move a sidebar row into a group (groupId set) or back to the top level (groupId null). Open to any member.","cli":"dench crm sidebar group add","method":"POST","path":"/crm/sidebar/groups/move","permission":"crm:write","pathParams":[]},
   {"id":"crm.sidebar.pins.set","group":"crm","summary":"Pin (pinned true) or unpin a Library row — or a whole group — on the home-level Pinned shortcut strip (the \"tab on the left\"). Does not move the row inside Library. Workspace-shared; open to any member.","cli":"dench crm sidebar pin","method":"POST","path":"/crm/sidebar/pins","permission":"crm:write","pathParams":[]},
   {"id":"crm.fields.list","group":"crm","summary":"List fields for a CRM object, including read-only calculation metadata.","cli":"dench crm fields list","method":"GET","path":"/crm/objects/{objectName}/fields","permission":"crm:read","pathParams":["objectName"]},
+  {"id":"crm.fields.listCompact","group":"crm","summary":"List field names, types and effective constraints without indexing or enrichment internals.","cli":"dench crm fields list --compact","method":"GET","path":"/crm/catalog/objects/{objectName}/fields","permission":"crm:read","pathParams":["objectName"]},
   {"id":"crm.fields.create","group":"crm","summary":"Create a CRM field or read-only campaign activity boolean column.","cli":"dench crm fields create","method":"POST","path":"/crm/objects/{objectName}/fields","permission":"crm:write","pathParams":["objectName"]},
   {"id":"crm.fields.update","group":"crm","summary":"Update a CRM field or change/explicitly clear an existing campaign calculation.","cli":"dench crm fields update","method":"PATCH","path":"/crm/objects/{objectName}/fields/{fieldName}","permission":"crm:write","pathParams":["objectName","fieldName"]},
   {"id":"crm.fields.delete","group":"crm","summary":"Delete a CRM field.","cli":"dench crm fields delete","method":"DELETE","path":"/crm/objects/{objectName}/fields/{fieldName}","permission":"crm:write","pathParams":["objectName","fieldName"]},
@@ -237,6 +239,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"crm.sql","group":"crm","summary":"Run CRM SQL-compatible query.","cli":"dench crm sql","method":"POST","path":"/crm/sql","permission":"crm:read","pathParams":[]},
   {"id":"crm.aggregate","group":"crm","summary":"Aggregate CRM entries.","cli":"dench crm aggregate","method":"POST","path":"/crm/aggregate","permission":"crm:read","pathParams":[]},
   {"id":"crm.search","group":"crm","summary":"Search CRM entries.","cli":"dench crm search","method":"GET","path":"/crm/search","permission":"crm:read","pathParams":[]},
+  {"id":"crm.search.page","group":"crm","summary":"Search bounded pages of readable CRM entries, optionally projecting cells. Always follow continueCursor until isDone.","cli":"dench crm search --page","method":"GET","path":"/crm/search/page","permission":"crm:read","pathParams":[]},
   {"id":"crm.statuses.list","group":"crm","summary":"List CRM statuses.","cli":"dench crm statuses list","method":"GET","path":"/crm/objects/{objectName}/statuses","permission":"crm:read","pathParams":["objectName"]},
   {"id":"crm.statuses.set","group":"crm","summary":"Set CRM statuses.","cli":"dench crm statuses set","method":"PUT","path":"/crm/objects/{objectName}/statuses","permission":"crm:write","pathParams":["objectName"]},
   {"id":"crm.batch","group":"crm","summary":"Apply a CRM batch.","cli":"dench crm batch","method":"POST","path":"/crm/batch","permission":"crm:write","pathParams":[]},
@@ -315,6 +318,9 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"email.identity.disable","group":"email","summary":"Soft-disable a sender (or every sender on a domain) for the workspace; sends are blocked until restored.","cli":"dench email identity disable","method":"POST","path":"/email/sending-identities/{identity}/disable","permission":"email:write","pathParams":["identity"]},
   {"id":"email.identity.restore","group":"email","summary":"Restore a previously disabled sender for the workspace.","cli":"dench email identity restore","method":"POST","path":"/email/sending-identities/{identity}/restore","permission":"email:write","pathParams":["identity"]},
   {"id":"email.identity.delete","group":"email","summary":"Permanently delete a sender (or every sender on a domain) from the workspace; re-adding it requires verification from scratch.","cli":"dench email identity delete","method":"DELETE","path":"/email/sending-identities/{identity}","permission":"email:write","pathParams":["identity"]},
+  {"id":"email.inbox.search","group":"email","summary":"Search authorized synced mailbox headers with bounded cursor pagination. isDone covers stored records, not provider completeness.","cli":"dench email inbox search","method":"GET","path":"/email/inbox/search","permission":"email:read","pathParams":[]},
+  {"id":"email.inbox.thread","group":"email","summary":"Read a bounded page of synced headers using an exact thread handle from inbox search; bodies remain on demand.","cli":"dench email inbox thread","method":"GET","path":"/email/inbox/threads/{threadHandle}","permission":"email:read","pathParams":["threadHandle"]},
+  {"id":"email.inbox.message","group":"email","summary":"Read a bounded stored body using an exact message handle from inbox search; rechecks mailbox and record privacy.","cli":"dench email inbox message","method":"GET","path":"/email/inbox/messages/{messageHandle}","permission":"email:read","pathParams":["messageHandle"]},
   {"id":"email.drafts.create","group":"email","summary":"Create an editable Dench email draft and synchronize its selected native mailbox asynchronously. Use a stable requestId for retries.","cli":"dench email draft create","method":"POST","path":"/email/drafts","permission":"email:write","pathParams":[]},
   {"id":"email.drafts.get","group":"email","summary":"Read an email draft, eligible senders and provider sync status.","cli":"dench email draft show","method":"GET","path":"/email/drafts/{draftId}","permission":"email:read","pathParams":["draftId"]},
   {"id":"email.drafts.senders","group":"email","summary":"List native mailboxes this caller may use.","cli":"dench email draft senders","method":"GET","path":"/email/drafts/senders","permission":"email:read","pathParams":[]},
@@ -322,8 +328,8 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"email.drafts.send","group":"email","summary":"Send the current Dench draft revision through its native mailbox. Repeated requests share a durable receipt.","cli":"dench email draft send","method":"POST","path":"/email/drafts/{draftId}/send","permission":"email:write","pathParams":["draftId"]},
   {"id":"email.drafts.upload","group":"email","summary":"Upload attachment bytes authorized against this draft before adding its storage reference.","cli":"dench email draft attach","method":"POST","path":"/email/drafts/{draftId}/attachments","permission":"email:write","pathParams":["draftId"]},
   {"id":"email.drafts.signature","group":"email","summary":"Load the selected mailbox signature for explicit visible insertion.","cli":"dench email draft signature","method":"GET","path":"/email/drafts/{draftId}/signature","permission":"email:read","pathParams":["draftId"]},
-  {"id":"email.native.send","group":"email","summary":"Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request.","cli":"dench email send --mailbox","method":"POST","path":"/email/native/send","permission":"email:write","pathParams":[]},
-  {"id":"email.send","group":"email","summary":"Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId.","cli":"dench email send","method":"POST","path":"/email/send","permission":"email:write","pathParams":[]},
+  {"id":"email.native.send","group":"email","summary":"Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request.","cli":"dench email send [--mailbox <id/email>]","method":"POST","path":"/email/native/send","permission":"email:write","pathParams":[]},
+  {"id":"email.send","group":"email","summary":"Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId.","cli":"dench email send --from <verified-email>","method":"POST","path":"/email/send","permission":"email:write","pathParams":[]},
   {"id":"email.message.get","group":"email","summary":"Read a raw email message's status and open/click counters.","cli":"dench email message status","method":"GET","path":"/email/messages/{messageId}","permission":"email:read","pathParams":["messageId"]},
   {"id":"email.message.list","group":"email","summary":"List recent raw email messages for the workspace.","cli":"dench email message list","method":"GET","path":"/email/messages","permission":"email:read","pathParams":[]},
   {"id":"email.template.create","group":"email","summary":"Create a managed email campaign template.","cli":"dench email template create","method":"POST","path":"/email/templates","permission":"email:write","pathParams":[]},
@@ -459,7 +465,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"agentConfig.user.show","group":"agent-config","summary":"Read USER.md.","cli":"dench user show","method":"GET","path":"/agent-config/user","permission":"agent-config:read","pathParams":[]},
   {"id":"agentConfig.user.edit","group":"agent-config","summary":"Update USER.md.","cli":"dench user edit","method":"PUT","path":"/agent-config/user","permission":"agent-config:write","pathParams":[]},
   {"id":"agentConfig.tools.show","group":"agent-config","summary":"Read tool notes.","cli":"dench tools show","method":"GET","path":"/agent-config/tools","permission":"agent-config:read","pathParams":[]},
-  {"id":"agentConfig.tools.edit","group":"agent-config","summary":"Update tool notes.","cli":"dench tools notes-edit","method":"PUT","path":"/agent-config/tools","permission":"agent-config:write","pathParams":[]},
+  {"id":"agentConfig.tools.edit","group":"agent-config","summary":"Update tool notes.","cli":"dench tools edit","method":"PUT","path":"/agent-config/tools","permission":"agent-config:write","pathParams":[]},
   {"id":"agentConfig.mem.show","group":"agent-config","summary":"Read aggregate memory.","cli":"dench mem show","method":"GET","path":"/agent-config/mem","permission":"agent-config:read","pathParams":[]},
   {"id":"agentConfig.mem.edit","group":"agent-config","summary":"Update aggregate memory.","cli":"dench mem set","method":"PUT","path":"/agent-config/mem","permission":"agent-config:write","pathParams":[]},
   {"id":"agentConfig.bootstrap.show","group":"agent-config","summary":"Read bootstrap state.","cli":"dench bootstrap status","method":"GET","path":"/agent-config/bootstrap","permission":"agent-config:read","pathParams":[]},

package/lib/bundled-references.ts

@@ -0,0 +1,17 @@
+import bundle from "./references.generated.json";
+
+export const referenceRevision = bundle.revision;
+const files: Record<string, { sha256: string; content: string }> = bundle.files;
+export function getBundledReference(path: string): string | undefined {
+  return Object.hasOwn(files, path) ? files[path].content : undefined;
+}
+export function bundledReferenceIndex() {
+  return {
+    revision: referenceRevision,
+    references: Object.entries(files).map(([path, file]) => ({
+      path,
+      sha256: file.sha256,
+      bytes: new TextEncoder().encode(file.content).byteLength,
+    })),
+  };
+}

package/lib/cli-args.ts

@@ -27,7 +27,15 @@
  * the caller adapts.
  */
 
-export class CliArgError extends Error {}
+export class CliArgError extends Error {
+  readonly code = "invalid_arguments";
+}
+
+/** Help is a local operation, even after otherwise valid mutation arguments. */
+export function isHelpRequest(args: readonly string[]): boolean {
+  if (args.includes("--help") || args.includes("-h")) return true;
+  return args[0] === "help" || args[1] === "help";
+}
 
 export function shift(args: string[], expected: string): string {
   const value = args.shift();
@@ -35,10 +43,28 @@ export function shift(args: string[], expected: string): string {
   return value;
 }
 
+/** A standalone short option cannot supply another flag's value. Descending
+ * --sort uses -Field (including single-letter fields); negative numbers remain
+ * ordinary values. Longer dash-prefixed text remains supported. */
+export function missingFlagValue(
+  value: string | undefined,
+  name: string,
+): boolean {
+  return (
+    value === undefined ||
+    value.startsWith("--") ||
+    value === "-h" ||
+    (name !== "--sort" && /^-[a-zA-Z]$/.test(value))
+  );
+}
+
 export function getFlag(args: string[], name: string): string | undefined {
   const idx = args.indexOf(name);
   if (idx === -1) return undefined;
   const value = args[idx + 1];
+  if (missingFlagValue(value, name)) {
+    throw new CliArgError(`${name} needs a value`);
+  }
   args.splice(idx, 2);
   return value;
 }
@@ -141,9 +167,10 @@ export function assertNoUnknownFlags(
   // some shells to terminate option parsing) is allowed.
   for (const token of args) {
     if (token === "--") continue;
-    if (token.startsWith("--")) {
+    if (/^--?[^\d.]/.test(token)) {
+      const path = command.replace(/^dench\s+/, "");
       throw new CliArgError(
-        `Unknown flag for ${command}: ${token}. Run \`dench ${command.split(" ")[0]} help\` for the full flag list.`,
+        `Unknown flag for ${path}: ${token}. Run \`dench ${path} --help\` for usage.`,
       );
     }
   }

package/lib/command-args.ts

@@ -0,0 +1,237 @@
+import { CliArgError, missingFlagValue } from "./cli-args";
+
+type PositionalArity = readonly [min: number, max: number | null];
+
+type CommandArguments = {
+  command: string;
+  values: string[];
+  switches: string[];
+  positionals: PositionalArity;
+  flagPositionals: Record<string, PositionalArity>;
+};
+const spec = (
+  command: string,
+  positionals: PositionalArity,
+  values = "",
+  switches = "",
+  flagPositionals: Record<string, PositionalArity> = {},
+): CommandArguments => ({
+  command,
+  positionals,
+  flagPositionals,
+  values: values.split(" ").filter(Boolean),
+  switches: switches.split(" ").filter(Boolean),
+});
+
+const browserSpec = (
+  verb: string,
+  positionals: PositionalArity,
+  flagPositionals: Record<string, PositionalArity> = {},
+): CommandArguments =>
+  spec(
+    `browser ${verb}`,
+    positionals,
+    "--thread --selector --text --label --value --key --target-id --targetId --pixels --timeout-ms --timeoutMs --x --y --output --url --script",
+    "--full-page",
+    flagPositionals,
+  );
+
+/** CLI spellings for dispatchers that do not reject leftovers themselves.
+ * Positional ranges follow the actual handlers; null deliberately allows free text
+ * or multiple IDs. Flag alternatives cover positional inputs replaced by flags.
+ * Shared by pre-dispatch validation and help; API property names are not flags. */
+export const COMMAND_ARGUMENTS = [
+  spec(
+    "signin",
+    [0, 0],
+    "--kind --name --email --org-name --org --timeout-ms --otp-code",
+    "--new-workspace --no-open",
+  ),
+  spec("logout", [0, 1], "", "--all"),
+  spec("use", [1, 1]),
+  spec("backend set", [1, 1]),
+  spec("backend clear", [0, 0]),
+  ...["install", "uninstall", "refresh"].map((verb) =>
+    spec(
+      `ads ${verb}`,
+      [0, 0],
+      "--target",
+      "--no-open --apply --color --no-color",
+    ),
+  ),
+  spec(
+    "ads payout setup",
+    [0, 0],
+    "--target",
+    "--no-open --apply --color --no-color",
+  ),
+  spec(
+    "ads payout onboard",
+    [0, 0],
+    "--target",
+    "--no-open --apply --color --no-color",
+  ),
+  spec(
+    "ads withdraw",
+    [0, 0],
+    "--amount --idempotency-key --target",
+    "--no-open --apply --color --no-color",
+  ),
+  spec(
+    "chat new",
+    [1, null],
+    "--model --file-context --visibility --title",
+    "--yolo --follow",
+  ),
+  spec("chat send", [2, null], "--model", "--yolo --follow"),
+  spec("chat rename", [2, null], "", "--from-stdin", {
+    "--from-stdin": [0, 0],
+  }),
+  spec("chat delete", [1, null], "--ids", "--yes -y --include-automated", {
+    "--ids": [0, null],
+  }),
+  spec("apps create", [1, 1], "--name --icon --description", "", {
+    "--name": [0, 1],
+  }),
+  spec(
+    "apps publish",
+    [1, 1],
+    "--slug --name --description --icon --visibility --version",
+  ),
+  ...["install", "uninstall", "enable", "disable", "pin", "unpin"].map((verb) =>
+    spec(`apps ${verb}`, [1, 1]),
+  ),
+  spec("apps webhooks register", [2, 2], "", "--rotate"),
+  spec("apps webhooks delete", [2, 2]),
+  spec("apps validate", [1, 1]),
+  spec(
+    "members me",
+    [0, 0],
+    "--name --tagline --timezone --image-url --avatar",
+    "--clear-avatar --auto-timezone",
+  ),
+  spec(
+    "cron create",
+    [1, 1],
+    "--prompt --description --overlap --target --type --at --cron --tz --every --every-ms --connection --event --toolkit --trigger-config --object --where --where-logic",
+    "--disabled --delete-after-run --no-secret --signed",
+  ),
+  spec(
+    "cron update",
+    [1, 1],
+    "--name --prompt --description --overlap --enabled --at --cron --tz --every --every-ms",
+  ),
+  spec("cron run", [1, 1], "", "--wait"),
+  spec("cron secret", [1, 1], "", "--off"),
+  ...["delete", "enable", "disable"].map((verb) =>
+    spec(`cron ${verb}`, [1, 1]),
+  ),
+  spec("files rm", [1, 1], "", "--recursive -r"),
+  spec("files mv", [2, 2]),
+  spec("files write", [1, 1]),
+  spec("stage", [1, 2], "", "--clean"),
+  ...["identity", "organisation", "user", "tools", "mem"].flatMap((group) =>
+    ["edit", "set"].map((verb) =>
+      spec(`${group} ${verb}`, [0, 0], "--content", "--stdin"),
+    ),
+  ),
+  spec("mem append", [1, null]),
+  spec("model default", [0, 1]),
+  spec("model thread", [2, 2]),
+  spec("bootstrap complete", [0, 0]),
+  spec("bootstrap reopen", [0, 0]),
+  spec("bootstrap template", [0, 0], "--content", "--stdin"),
+  spec(
+    "memory save",
+    [2, null],
+    "--kind --tags --sensitivity --scope --visibility",
+  ),
+  spec("project create", [1, 1], "--repo --root"),
+  spec("approval request", [1, 1], "--reason --risk --agent"),
+  spec("approval approve", [1, 1], "--evidence"),
+  spec("approval reject", [1, 1], "--evidence"),
+  spec("billing topup", [1, 1], "--amount", "--no-open", {
+    "--amount": [0, 0],
+  }),
+  spec("upgrade", [0, 0], "--tier --cycle --billing-cycle", "--no-open"),
+  spec("tool run", [1, 1], "--args --account --approval"),
+  spec("tool connect", [1, 1], "--callback-url"),
+  spec("tool disconnect", [1, 1]),
+  spec(
+    "browser session create",
+    [0, 0],
+    "--context-id --contextId --width --height",
+  ),
+  spec("browser session stop", [1, 1]),
+  // Value flags replace the joined positional input. The clickAt handler
+  // instead lets its first/second positionals override --x/--y individually.
+  browserSpec("open", [0, null], { "--url": [0, 0] }),
+  browserSpec("state", [0, 0]),
+  browserSpec("inspect", [0, 0]),
+  browserSpec("navigate", [0, null], { "--url": [0, 0] }),
+  browserSpec("click", [0, 0]),
+  browserSpec("clickAt", [0, 2]),
+  browserSpec("click-at", [0, 2]),
+  browserSpec("fill", [0, 0]),
+  browserSpec("type", [0, null], { "--value": [0, 0] }),
+  browserSpec("key", [0, null], { "--key": [0, 0] }),
+  browserSpec("scroll", [0, 1]),
+  browserSpec("wait", [0, 0]),
+  browserSpec("evaluate", [0, null], { "--script": [0, 0] }),
+  browserSpec("tabs", [0, 0]),
+  browserSpec("newTab", [0, null], { "--url": [0, 0] }),
+  browserSpec("new-tab", [0, null], { "--url": [0, 0] }),
+  ...["activateTab", "activate-tab", "closeTab", "close-tab"].map((verb) =>
+    browserSpec(verb, [0, 1], { "--target-id": [0, 0], "--targetId": [0, 0] }),
+  ),
+  browserSpec("screenshot", [0, 0]),
+  browserSpec("stop", [0, 0]),
+];
+
+export function assertDeclaredCommandFlags(argv: readonly string[]): void {
+  const args = argv.filter((arg) => arg !== "--json");
+  if (["routine", "routines"].includes(args[0])) args[0] = "cron";
+  if (["ad", "adline"].includes(args[0])) args[0] = "ads";
+  if (args[0] === "agent" && ["new", "send"].includes(args[1]))
+    args[0] = "chat";
+  if (args[0] === "crm" && args[1] === "members") args.shift();
+  const contract = COMMAND_ARGUMENTS.find(({ command }) =>
+    command.split(" ").every((part, index) => args[index] === part),
+  );
+  if (!contract) return; // Domain parsers keep their own consumed-argument validation.
+  const positionals: string[] = [];
+  const flags = new Set<string>();
+  for (let i = contract.command.split(" ").length; i < args.length; i++) {
+    const arg = args[i];
+    if (!/^--?[^\d.]/.test(arg)) {
+      positionals.push(arg);
+      continue;
+    }
+    flags.add(arg);
+    if (contract.switches.includes(arg)) continue;
+    if (contract.values.includes(arg)) {
+      const value = args[++i];
+      if (missingFlagValue(value, arg))
+        throw new CliArgError(`Missing value for ${arg}`);
+      continue;
+    }
+    throw new CliArgError(
+      `Unknown flag for ${contract.command}: ${arg}. Run \`dench ${contract.command} --help\` for usage.`,
+    );
+  }
+  const [min, max] =
+    Object.entries(contract.flagPositionals).find(([flag]) =>
+      flags.has(flag),
+    )?.[1] ?? contract.positionals;
+  if (positionals.length < min || (max !== null && positionals.length > max)) {
+    const expected =
+      max === null
+        ? `at least ${min}`
+        : min === max
+          ? String(min)
+          : `${min}–${max}`;
+    throw new CliArgError(
+      `${positionals.length < min ? "Missing" : "Unexpected"} positional argument for ${contract.command}: expected ${expected}, received ${positionals.length}. Run \`dench ${contract.command} --help\` for usage.`,
+    );
+  }
+}