quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/budget.js

@@ -0,0 +1,241 @@
+/**
+ * Budget commands: CRUD for quoxflow budget definitions + rolled-up usage.
+ *
+ * quox budget list|get|create|update|delete|usage
+ *
+ * Backend: quoxflow (NOT the auth service, NOT proxied by collector) —
+ * quoxflow/src/api/routes/budgets.ts, mounted at /api/budgets. Org scoping
+ * is via `?org_id=` query param on GETs and an `org_id` body field on
+ * writes — see cli/lib/api/endpoints/budgets.js header for the full
+ * verified org-scoping mechanism (list requires+filters org_id; get/usage
+ * check org_id against the budget's owner when present; update/delete
+ * require it in the body and 403 on mismatch).
+ */
+
+import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const SCOPE_KINDS = ['org', 'objective', 'execution', 'iteration'];
+
+function numOrUndefined(value) {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (Number.isNaN(n)) throw new Error(`Expected a number, got: ${value}`);
+  return n;
+}
+
+export function registerBudgetCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const budget = program
+    .command('budget')
+    .description('Manage quoxflow spend/usage budgets (org, objective, execution, iteration scope)');
+
+  // ── budget list ─────────────────────────────────────────────────────────────
+
+  budget
+    .command('list')
+    .description('List budgets for the active org')
+    .option('--scope <kind>', `filter by scope kind (${SCOPE_KINDS.join('|')})`)
+    .option('--scope-id <id>', 'filter by scope id')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = { org_id: orgId };
+      if (options.scope) query.scope = options.scope;
+      if (options.scopeId) query.scope_id = options.scopeId;
+
+      const data = await client.get(resolveEndpoint('budgets.list').path, {
+        service: resolveEndpoint('budgets.list').service,
+        query,
+      });
+      const budgets = data.data?.budgets || data.budgets || [];
+
+      formatOutput({
+        columns: ['id', 'scope_kind', 'scope_id', 'period_start', 'period_end', 'max_cost_usd_micro', 'max_tokens', 'hard_stop'],
+        headers: ['ID', 'Scope', 'Scope ID', 'Period Start', 'Period End', 'Max Cost (micro-USD)', 'Max Tokens', 'Hard Stop'],
+        rows: budgets,
+      }, { format: program.opts().output, emptyMessage: 'No budgets found.' });
+    });
+
+  // ── budget get ───────────────────────────────────────────────────────────────
+
+  budget
+    .command('get')
+    .description('Show budget details')
+    .argument('<id>', 'budget ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await client.get(resolveEndpoint('budgets.get', { id }).path, {
+        service: resolveEndpoint('budgets.get', { id }).service,
+        query: { org_id: orgId },
+      });
+      const b = data.data?.budget || data.budget || data;
+
+      formatDetail(b, {
+        format: program.opts().output,
+        title: `Budget: ${b.id || id}`,
+      });
+    });
+
+  // ── budget create ────────────────────────────────────────────────────────────
+
+  budget
+    .command('create')
+    .description('Create a budget')
+    .requiredOption('--scope <kind>', `scope kind (${SCOPE_KINDS.join('|')})`)
+    .requiredOption('--scope-id <id>', 'scope id (e.g. org id, objective id, execution id, iteration id)')
+    .requiredOption('--period-start <iso>', 'period start (ISO timestamp)')
+    .requiredOption('--period-end <iso>', 'period end (ISO timestamp)')
+    .option('--max-tokens <n>', 'max total tokens (in + out)')
+    .option('--max-cost-usd-micro <n>', 'max cost in micro-USD (1 USD = 1,000,000)')
+    .option('--max-tool-calls <n>', 'max tool calls')
+    .option('--max-duration-ms <n>', 'max wall-clock duration (ms)')
+    .option('--max-iterations <n>', 'max iterations')
+    .option('--no-hard-stop', 'do not hard-stop execution when exceeded (default: hard-stop enabled)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (!SCOPE_KINDS.includes(options.scope)) {
+        throw new Error(`--scope must be one of: ${SCOPE_KINDS.join(', ')}`);
+      }
+
+      const body = {
+        org_id: orgId,
+        scope_kind: options.scope,
+        scope_id: options.scopeId,
+        period_start: options.periodStart,
+        period_end: options.periodEnd,
+        max_tokens: numOrUndefined(options.maxTokens),
+        max_cost_usd_micro: numOrUndefined(options.maxCostUsdMicro),
+        max_tool_calls: numOrUndefined(options.maxToolCalls),
+        max_duration_ms: numOrUndefined(options.maxDurationMs),
+        max_iterations: numOrUndefined(options.maxIterations),
+        hard_stop: options.hardStop,
+      };
+
+      const data = await client.post(resolveEndpoint('budgets.create').path, {
+        service: resolveEndpoint('budgets.create').service,
+        body,
+      });
+      const b = data.data?.budget || data.budget || data;
+      printSuccess(`Budget created (${b.id}).`);
+      formatDetail(b, { format: program.opts().output });
+    });
+
+  // ── budget update ────────────────────────────────────────────────────────────
+
+  budget
+    .command('update')
+    .description('Update a budget')
+    .argument('<id>', 'budget ID')
+    .option('--period-start <iso>', 'new period start (ISO timestamp)')
+    .option('--period-end <iso>', 'new period end (ISO timestamp)')
+    .option('--max-tokens <n>', 'new max total tokens')
+    .option('--max-cost-usd-micro <n>', 'new max cost in micro-USD')
+    .option('--max-tool-calls <n>', 'new max tool calls')
+    .option('--max-duration-ms <n>', 'new max wall-clock duration (ms)')
+    .option('--max-iterations <n>', 'new max iterations')
+    .option('--hard-stop <bool>', 'set hard_stop (true|false)')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      const patch = { org_id: orgId };
+      if (options.periodStart !== undefined) patch.period_start = options.periodStart;
+      if (options.periodEnd !== undefined) patch.period_end = options.periodEnd;
+      if (options.maxTokens !== undefined) patch.max_tokens = numOrUndefined(options.maxTokens);
+      if (options.maxCostUsdMicro !== undefined) patch.max_cost_usd_micro = numOrUndefined(options.maxCostUsdMicro);
+      if (options.maxToolCalls !== undefined) patch.max_tool_calls = numOrUndefined(options.maxToolCalls);
+      if (options.maxDurationMs !== undefined) patch.max_duration_ms = numOrUndefined(options.maxDurationMs);
+      if (options.maxIterations !== undefined) patch.max_iterations = numOrUndefined(options.maxIterations);
+      if (options.hardStop !== undefined) {
+        if (options.hardStop !== 'true' && options.hardStop !== 'false') {
+          throw new Error('--hard-stop must be "true" or "false".');
+        }
+        patch.hard_stop = options.hardStop === 'true';
+      }
+
+      if (Object.keys(patch).length === 1) {
+        throw new Error('Specify at least one field to update.');
+      }
+
+      const data = await client.patch(resolveEndpoint('budgets.update', { id }).path, {
+        service: resolveEndpoint('budgets.update', { id }).service,
+        body: patch,
+      });
+      const b = data.data?.budget || data.budget || data;
+      printSuccess('Budget updated.');
+      formatDetail(b, { format: program.opts().output });
+    });
+
+  // ── budget delete ────────────────────────────────────────────────────────────
+
+  budget
+    .command('delete')
+    .description('Delete a budget')
+    .argument('<id>', 'budget ID')
+    .option('--force', 'skip confirmation')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (!options.force && !program.opts().yes) {
+        const { default: inquirer } = await import('inquirer');
+        const ans = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirm',
+          message: `Delete budget ${id}? This cannot be undone.`,
+          default: false,
+        }]);
+        if (!ans.confirm) {
+          printInfo('Cancelled.');
+          return;
+        }
+      }
+
+      await client.delete(resolveEndpoint('budgets.delete', { id }).path, {
+        service: resolveEndpoint('budgets.delete', { id }).service,
+        body: { org_id: orgId },
+      });
+      printSuccess('Budget deleted.');
+    });
+
+  // ── budget usage ─────────────────────────────────────────────────────────────
+
+  budget
+    .command('usage')
+    .description('Show rolled-up usage + daily breakdown for a budget')
+    .argument('<id>', 'budget ID')
+    .option('--since <iso>', 'filter usage since this ISO timestamp')
+    .option('--until <iso>', 'filter usage until this ISO timestamp')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = { org_id: orgId };
+      if (options.since) query.since = options.since;
+      if (options.until) query.until = options.until;
+
+      const data = await client.get(resolveEndpoint('budgets.usage', { id }).path, {
+        service: resolveEndpoint('budgets.usage', { id }).service,
+        query,
+      });
+      const payload = data.data || data;
+
+      formatDetail(payload.usage, {
+        format: program.opts().output,
+        title: `Budget Usage: ${id}`,
+      });
+
+      if (program.opts().output !== 'json' && program.opts().output !== 'quiet') {
+        formatOutput({
+          columns: ['date', 'tokens_in', 'tokens_out', 'cost_usd_micro', 'tool_calls', 'duration_ms', 'iteration_count'],
+          headers: ['Date', 'Tokens In', 'Tokens Out', 'Cost (micro-USD)', 'Tool Calls', 'Duration (ms)', 'Iterations'],
+          rows: payload.daily || [],
+        }, { format: program.opts().output, emptyMessage: 'No daily usage recorded.' });
+      }
+    });
+}

package/lib/commands/build.js

@@ -0,0 +1,170 @@
+/**
+ * Build commands — DEVSUITE-BUILD step 4 (`quox build`).
+ *
+ * The governed superset of the thin local `quox-build` client: dispatches a
+ * PRE-REGISTERED target on a dev server through the collector's dev-build
+ * control plane (oracle-signed envelope over Bastion to the host-side
+ * quoxagent dev.build executor), reads live executor state, and reads the
+ * durable receipts mirror. The local `quox-build` spool client and the
+ * Terminal 9 daemon are untouched and keep working; this group is how any
+ * authenticated session drives builds on ANY registered dev server.
+ *
+ * `quox build <target> --host <hostId>` dispatches. Named subcommands
+ * (status/targets/history/latest) win over a target of the same name — a
+ * target literally called "status" must be dispatched via
+ * `quox build dispatch status --host …`.
+ */
+
+import { formatDetail, formatOutput, printSuccess, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerBuildCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const build = program
+    .command('build')
+    .description('QuoxBuild: dispatch and inspect governed builds on dev servers');
+
+  // Commander (non-positional mode) lets the PARENT consume an option it
+  // declares even when the token appears after a subcommand name, so the
+  // bare-target sugar's group-level --host/--stream/--phase/--msg would
+  // otherwise swallow the flags out from under every verb (found live on
+  // the first proof drive). Every verb therefore falls back to the group's
+  // own parsed opts.
+  const groupOpt = (options, key) => options[key] ?? build.opts()[key];
+
+  // An org with exactly one dev server needs no --host: use it and say so. With several, name them;
+  // with none, say so (proof cases code/reach-build-status / -targets exited 1 on a one-server org).
+  async function resolveHost(options) {
+    const given = groupOpt(options, 'host');
+    if (given) return given;
+    const listEp = resolveEndpoint('v1.dev.servers.list');
+    const list = await client.get(listEp.path, { service: listEp.service });
+    const ids = (Array.isArray(list?.servers) ? list.servers : []).map((s) => s.host_id).filter(Boolean);
+    if (ids.length === 1) {
+      printWarning(`No --host given; using the only dev server: ${ids[0]}`);
+      return ids[0];
+    }
+    if (ids.length === 0) throw new Error('No dev server is registered for this org (register one with `quox dev enable <hostId>`).');
+    throw new Error(`--host <hostId> is required: this org has ${ids.length} dev servers (${ids.join(', ')}).`);
+  }
+
+  async function dispatch(target, options) {
+    auth.requireAuth();
+    options = {
+      host: await resolveHost(options),
+      stream: groupOpt(options, 'stream'),
+      phase: groupOpt(options, 'phase'),
+      msg: groupOpt(options, 'msg'),
+    };
+    if (!options.host) {
+      throw new Error('--host <hostId> is required (the dev server that runs the build)');
+    }
+    const body = { target };
+    const stream = options.stream || process.env.QUOX_STREAM;
+    const phase = options.phase || process.env.QUOX_PHASE;
+    if (stream) body.stream = stream;
+    if (phase) body.phase = phase;
+    if (options.msg) body.msg = options.msg;
+
+    const endpoint = resolveEndpoint('v1.dev.build.dispatch', { hostId: options.host });
+    const data = await client.post(endpoint.path, { service: endpoint.service, body });
+    formatDetail(data, { format: program.opts().output, title: `Build dispatched on ${options.host}` });
+    if (data && data.dispatched) {
+      printSuccess(`${(data.targets || [target]).join(', ')} queued on ${options.host} (coalesces within the queue window).`);
+      printWarning('Queued is not built: check `quox build status --host ' + options.host + '` and the receipt before claiming green.');
+    }
+  }
+
+  build
+    .command('dispatch')
+    .description('Queue a build of a pre-registered target on a dev server')
+    .argument('<target>', 'pre-registered target name on that host')
+    .option('--host <hostId>', 'dev server host_id')
+    .option('--stream <code>', 'roadmap stream code for the receipt (default: $QUOX_STREAM)')
+    .option('--phase <phase>', 'stream phase for the receipt (default: $QUOX_PHASE)')
+    .option('--msg <text>', 'what changed')
+    .action(dispatch);
+
+  build
+    .command('status')
+    .description('Live executor state on a dev server: readiness, prereqs, building-now, last outcomes')
+    .option('--host <hostId>', 'dev server host_id')
+    .action(async (options) => {
+      auth.requireAuth();
+      const host = await resolveHost(options);
+      const endpoint = resolveEndpoint('v1.dev.build.status', { hostId: host });
+      const data = await client.get(endpoint.path, { service: endpoint.service });
+      formatDetail(data, { format: program.opts().output, title: `Build status: ${host}` });
+    });
+
+  build
+    .command('targets')
+    .description("List a dev server's pre-registered build targets")
+    .option('--host <hostId>', 'dev server host_id')
+    .action(async (options) => {
+      auth.requireAuth();
+      const host = await resolveHost(options);
+      const endpoint = resolveEndpoint('v1.dev.build.targets', { hostId: host });
+      const data = await client.get(endpoint.path, { service: endpoint.service });
+      formatOutput(data.targets || [], {
+        format: program.opts().output,
+        columns: ['name', 'description', 'steps', 'verify_count'],
+        emptyMessage: 'No pre-registered targets on this host.',
+      });
+    });
+
+  build
+    .command('history')
+    .description('Durable build receipts (the witnessed mirror), newest first')
+    .option('--host <hostname>', 'filter to one host (receipt hostname)')
+    .option('--target <name>', 'filter to one target')
+    .option('--result <r>', 'filter by result (ok, FAIL, UNVERIFIED, INTERRUPTED)')
+    .option('--limit <n>', 'max rows (default 20)', (v) => parseInt(v, 10), 20)
+    .action(async (options) => {
+      auth.requireAuth();
+      const endpoint = resolveEndpoint('v1.build.receipts.list');
+      const params = new URLSearchParams();
+      const host = groupOpt(options, 'host');
+      if (host) params.set('host', host);
+      if (options.target) params.set('target', options.target);
+      if (options.result) params.set('result', options.result);
+      params.set('limit', String(options.limit));
+      const data = await client.get(`${endpoint.path}?${params}`, { service: endpoint.service });
+      formatOutput(data.receipts || [], {
+        format: program.opts().output,
+        columns: ['created_at', 'result', 'target', 'host', 'terminal', 'stream', 'phase', 'duration_seconds'],
+        emptyMessage: 'No build receipts recorded yet.',
+      });
+    });
+
+  build
+    .command('latest')
+    .description('Latest receipt per target (the build-status board)')
+    .action(async () => {
+      auth.requireAuth();
+      const endpoint = resolveEndpoint('v1.build.status.list');
+      const data = await client.get(endpoint.path, { service: endpoint.service });
+      formatOutput(data.targets || [], {
+        format: program.opts().output,
+        columns: ['target', 'result', 'host', 'created_at', 'duration_seconds'],
+        emptyMessage: 'No build receipts recorded yet.',
+      });
+    });
+
+  // Bare `quox build <target> --host …` sugar: dispatch without typing the
+  // verb, matching the muscle memory of the local quox-build client.
+  build
+    .argument('[target]', 'pre-registered target name (shorthand for `quox build dispatch <target>`)')
+    .option('--host <hostId>', 'dev server host_id')
+    .option('--stream <code>', 'roadmap stream code (default: $QUOX_STREAM)')
+    .option('--phase <phase>', 'stream phase (default: $QUOX_PHASE)')
+    .option('--msg <text>', 'what changed')
+    .action(async (target, options) => {
+      if (!target) {
+        build.help();
+        return;
+      }
+      await dispatch(target, options);
+    });
+}

package/lib/commands/calendar.js

@@ -0,0 +1,216 @@
+/**
+ * Calendar-Q commands: connected calendars, agenda, coverage, manual sync,
+ * and (L2-C2) proposing/reconciling/reviewing approved event creation.
+ *
+ * There is deliberately NO `calendar create` command: creating an event
+ * always requires a human approval, resolved through the Approvals inbox
+ * (`quox inbox`) — not a second CLI doorway around that gate. `calendar
+ * propose` only ever builds the proposal (no external effect); an agent or a
+ * human approver is what actually triggers calendar_event_create, and that
+ * call is unconditionally gated by withApprovalGate regardless of caller.
+ */
+
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+function isJsonOutput(program) {
+  return program.opts().output === 'json';
+}
+
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function registerCalendarCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const calendar = program
+    .command('calendar')
+    .description('Calendar-Q: connected calendars, agenda, coverage, sync');
+
+  // ── status ───────────────────────────────────────────────────────────
+
+  calendar
+    .command('status')
+    .description('Show connected Calendar-Q connections and their sync watermark')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('calendarq.status');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJsonOutput(program)) return printJson(data);
+      formatOutput({
+        columns: ['connectionId', 'provider', 'resourceId', 'status', 'latestWatermarkTs'],
+        headers: ['ID', 'Provider', 'Resource', 'Status', 'Watermark'],
+        rows: data.connections || [],
+      }, { format: program.opts().output });
+      printSuccess(`${data.connectionsCount ?? 0} connection(s), ${data.layerCount ?? 0} layer(s).`);
+    });
+
+  // ── layers ───────────────────────────────────────────────────────────
+
+  calendar
+    .command('layers')
+    .description('List Calendar-Q layers')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('calendarq.layers');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJsonOutput(program)) return printJson(data);
+      formatOutput({
+        columns: ['layerId', 'kind', 'displayName', 'visible', 'scope'],
+        headers: ['Layer', 'Kind', 'Name', 'Visible', 'Scope'],
+        rows: data.layers || [],
+      }, { format: program.opts().output });
+    });
+
+  // ── agenda ───────────────────────────────────────────────────────────
+
+  calendar
+    .command('agenda')
+    .description("Show a connection's agenda: occurrences plus coverage state")
+    .requiredOption('--connection <id>', 'Calendar-Q connection ID')
+    .option('--layers <csv>', 'comma-separated layer ids to restrict to')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = { connectionId: options.connection };
+      if (options.layers) query.layerIds = options.layers;
+      const ep = resolveEndpoint('calendarq.agenda');
+      const data = await client.get(ep.path, { service: ep.service, query });
+      if (isJsonOutput(program)) return printJson(data);
+      const coverage = data.coverage || {};
+      console.log(`Coverage: ${coverage.state} (watermark ${coverage.watermarkTs ?? 'n/a'}, window ${coverage.windowStartLocalDate} to ${coverage.windowEndLocalDateExclusive})`);
+      const occurrences = data.occurrences || [];
+      if (occurrences.length === 0) {
+        console.log('No occurrences in this window.');
+        return;
+      }
+      for (const occ of occurrences) console.log(occ.spokenForm);
+    });
+
+  // ── coverage ─────────────────────────────────────────────────────────
+
+  calendar
+    .command('coverage')
+    .description('Show just the coverage/freshness state for a connection')
+    .requiredOption('--connection <id>', 'Calendar-Q connection ID')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('calendarq.coverage');
+      const data = await client.get(ep.path, { service: ep.service, query: { connectionId: options.connection } });
+      if (isJsonOutput(program)) return printJson(data);
+      formatDetail(data.coverage || {}, { format: program.opts().output, title: 'Calendar-Q Coverage' });
+    });
+
+  // ── sync ─────────────────────────────────────────────────────────────
+
+  calendar
+    .command('sync')
+    .description('Trigger a manual sync for a connection (respects retired/backoff eligibility)')
+    .requiredOption('--connection <id>', 'Calendar-Q connection ID')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('calendarq.sync');
+      // A full-window provider fetch can run long; give it the same generous
+      // ceiling `quox mail sync` uses.
+      const data = await client.post(ep.path, { service: ep.service, body: { connectionId: options.connection }, timeout: 240000 });
+      if (isJsonOutput(program)) return printJson(data);
+      const result = data.result || {};
+      if (result.skipped) {
+        printSuccess(`Sync skipped for ${options.connection}: ${result.skipped}.`);
+        return;
+      }
+      if (result.failed) {
+        console.error(`Sync failed for ${options.connection}: ${result.error}`);
+        return;
+      }
+      const stats = result.stats || {};
+      printSuccess(`Synced ${options.connection}. ${stats.inserted ?? 0} occurrence(s), ${stats.omitted ?? 0} omitted, ${stats.changed ?? 0} changed.`);
+    });
+
+  // ── propose ──────────────────────────────────────────────────────────
+
+  calendar
+    .command('propose')
+    .description('Propose creating a single, non-recurring event (no external effect — nothing is created yet)')
+    .requiredOption('--connection <id>', 'Calendar-Q connection ID')
+    .requiredOption('--title <title>', 'Event title')
+    .requiredOption('--timezone <tz>', 'IANA timezone')
+    .option('--start <iso>', 'Start time, ISO 8601 (omit for --all-day)')
+    .option('--end <iso>', 'End time, ISO 8601, must be after --start (omit for --all-day)')
+    .option('--all-day', 'Create a single-day all-day event')
+    .option('--date <date>', "'YYYY-MM-DD', required with --all-day")
+    .option('--attendees <csv>', 'comma-separated attendee emails')
+    .option('--notify <policy>', "'none' or 'attendees'", 'none')
+    .option('--visibility <visibility>', "'default', 'private', or 'busy-only'", 'default')
+    .option('--description <text>', 'Event description')
+    .action(async (options) => {
+      auth.requireAuth();
+      const body = {
+        connectionId: options.connection,
+        title: options.title,
+        timezone: options.timezone,
+        notifyPolicy: options.notify,
+        visibility: options.visibility,
+      };
+      if (options.allDay) {
+        body.allDay = true;
+        body.dateOnly = options.date;
+      } else {
+        body.startTs = options.start ? Date.parse(options.start) : undefined;
+        body.endTs = options.end ? Date.parse(options.end) : undefined;
+      }
+      if (options.attendees) body.attendees = options.attendees.split(',').map((e) => ({ email: e.trim() })).filter((a) => a.email);
+      if (options.description) body.description = options.description;
+
+      const ep = resolveEndpoint('calendarq.propose');
+      const data = await client.post(ep.path, { service: ep.service, body });
+      if (isJsonOutput(program)) return printJson(data);
+      const p = data.proposal;
+      console.log(`Proposed "${p.title}" (proposalId ${p.proposalId}).`);
+      if ((data.overlaps || []).length > 0) {
+        console.log(`Disclosed conflicts: ${data.overlaps.map((o) => o.title).join(', ')}`);
+      } else {
+        console.log('No conflicts found against the latest synced calendar data.');
+      }
+      printSuccess('Nothing has been created yet. Approve via the Approvals inbox to actually create this event.');
+    });
+
+  // ── receipts ─────────────────────────────────────────────────────────
+
+  calendar
+    .command('receipts')
+    .description('Show Calendar-Q write-path receipts (newest first), each with its full state timeline')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('calendarq.receipts');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJsonOutput(program)) return printJson(data);
+      const receipts = data.receipts || [];
+      if (receipts.length === 0) {
+        console.log('No receipts yet.');
+        return;
+      }
+      formatOutput({
+        columns: ['createdAt', 'kind', 'operationState', 'opId'],
+        headers: ['When', 'Kind', 'State', 'Operation'],
+        rows: receipts,
+      }, { format: program.opts().output });
+    });
+
+  // ── reconcile ────────────────────────────────────────────────────────
+
+  calendar
+    .command('reconcile <opId>')
+    .description("Resolve an 'attempted' or 'outcome_unknown' create against provider evidence (read-only — never creates/updates/deletes)")
+    .action(async (opId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('calendarq.reconcile', { opId });
+      const data = await client.post(ep.path, { service: ep.service, body: {} });
+      if (isJsonOutput(program)) return printJson(data);
+      if (data.pending) {
+        console.log(`Still unresolved: ${data.error}. Try again later${data.nextEligibleAt ? ` (not before ${new Date(data.nextEligibleAt).toISOString()})` : ''}.`);
+        return;
+      }
+      printSuccess(`Reconciled ${opId}: ${data.outcome}${data.reason ? ` (${data.reason})` : ''}.`);
+    });
+}

package/lib/commands/capabilities.js

@@ -0,0 +1,34 @@
+/**
+ * quox capabilities [name]
+ *
+ * What this Quox can do for your org right now (QUOXON E1): ready, needs setup,
+ * not available, planned, each with the server's honest reason and setup hint.
+ * Backend: collector GET /api/v1/capabilities (org from your token; 30 s cache).
+ * Same renderer as the terminal's /capabilities, so the two never disagree.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { capabilityLines, findCapability, offerFor } from '../quoxon/capabilities.js';
+
+export function registerCapabilitiesCommands(program, ctx) {
+  const { client, auth } = ctx;
+  program
+    .command('capabilities [name]')
+    .description('What this Quox can do for your org: ready, needs setup, not available, planned')
+    .action(async (name) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.capabilities');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      const res = { ok: Array.isArray(data?.capabilities), capabilities: data?.capabilities, error: 'unexpected response' };
+      if (name) {
+        const c = findCapability(name, res);
+        if (!c) { console.log(`Nothing called "${name}". quox capabilities lists them.`); process.exitCode = 1; return; }
+        console.log(`${c.name}: ${c.intent}`);
+        console.log(`Proof: ${c.evidence || 'not stated'}`);
+        console.log(offerFor(c.id, res) || `✔ ${c.name} is ready here.`);
+        return;
+      }
+      for (const [t] of capabilityLines(res)) console.log(t);
+    });
+}