@commissionsight/cli 0.1.0 → 0.1.2

package/README.md

@@ -41,7 +41,9 @@ cs upload batch ./statements --workspace "Main Book" --wait --report ./ingest.js
 ## Using this CLI from an AI agent (Claude Code, etc.)
 
 This section is the contract an autonomous agent should rely on. Everything here
-is stable and machine-checkable.
+is stable and machine-checkable. (Running `cs` with **no arguments** prints a
+condensed version of this guidance, so a harness that discovers the binary is
+onboarded immediately.)
 
 ### 1. Discover the surface programmatically — don't guess
 
@@ -49,9 +51,12 @@ is stable and machine-checkable.
 cs schema --json
 ```
 
-Returns the **entire** command/flag tree as JSON: every command, its positional
-args (with `required`/`variadic`), and every option (`type`, `short`, `desc`,
-`choices`, `default`). Parse this instead of memorizing commands. Shape:
+Returns the **entire** command/flag tree as JSON **plus a `conventions` block**
+(the envelope shape, exit-code table, error fields, auth, idempotency, and
+pagination rules) — so a single call fully onboards an agent. It contains every
+command, its positional args (with `required`/`variadic`), and every option
+(`type`, `short`, `desc`, `choices`, `default`). Parse this instead of memorizing
+commands. Shape:
 
 ```json
 {
@@ -90,8 +95,11 @@ safely `JSON.parse(stdout)` without stripping anything.
   ```
 
 `error.code` is a stable slug derived from the API's problem+json body
-(`period_exists`, `already_retracted`, …) or `null`. Branch on `error.code` /
-`error.status`, not on `message` text.
+(`period_exists`, `already_retracted`, …) or `null`. The error object also carries
+a machine-readable **`hint`** (the recovery action, e.g. "re-run with --replace")
+and **`retriable`** (true for rate-limits/timeouts/5xx) — so an agent can recover
+without parsing `message` text. Branch on `error.code` / `error.status` /
+`error.retriable`.
 
 ### 3. Use exit codes for control flow
 

package/dist/output/envelope.d.ts

@@ -13,6 +13,10 @@ export interface ErrEnvelope {
         status: number;
         code: string | null;
         message: string;
+        /** Actionable next step an agent can act on without parsing `message`. */
+        hint?: string;
+        /** True when retrying the same call may succeed (rate limit, timeout, 5xx). */
+        retriable: boolean;
         body?: unknown;
     };
 }
@@ -23,6 +27,14 @@ export declare function ok(data: unknown): OkEnvelope;
  * `type` URI slug, then `title`/`code`. Returns null when nothing usable.
  */
 export declare function deriveCode(body: unknown): string | null;
+/**
+ * Compute an actionable hint + retriability from an API status (+ derived code),
+ * so an agent can recover without parsing the human message.
+ */
+export declare function errorMeta(status: number, code: string | null): {
+    hint?: string;
+    retriable: boolean;
+};
 /** Shape any thrown value into the error envelope. */
 export declare function errEnvelope(err: unknown): ErrEnvelope;
 /** Convenience: the exit code that pairs with a thrown value. */

package/dist/output/envelope.js

@@ -2,7 +2,7 @@
  * The stable JSON envelope (plan §5.1) and the error-shaping helpers.
  * Success → { ok: true, data }. Failure → { ok: false, error }.
  */
-import { ApiError, UsageError, exitCodeFor } from '../errors.js';
+import { ApiError, UsageError, TimeoutError, exitCodeFor } from '../errors.js';
 export function ok(data) {
     return { ok: true, data };
 }
@@ -32,19 +32,62 @@ function slug(s) {
         .replace(/[^a-z0-9]+/g, '_')
         .replace(/^_+|_+$/g, '');
 }
+/**
+ * Compute an actionable hint + retriability from an API status (+ derived code),
+ * so an agent can recover without parsing the human message.
+ */
+export function errorMeta(status, code) {
+    if (status === 409 && code === 'period_exists') {
+        return { hint: 're-run with --replace to overwrite this carrier+period', retriable: false };
+    }
+    if (status === 409 && code === 'already_retracted') {
+        return { hint: 'this carrier+period was already retracted/replaced; no action needed', retriable: false };
+    }
+    if (status === 409)
+        return { hint: 'resource conflict; inspect error.body', retriable: false };
+    if (status === 401 || status === 403) {
+        return { hint: 'authenticate: set COMMISSIONSIGHT_TOKEN or run `cs auth login --token-stdin`', retriable: false };
+    }
+    if (status === 404)
+        return { hint: 'not found; verify the id/ref exists', retriable: false };
+    if (status === 400 || status === 422) {
+        return { hint: 'inputs rejected; read error.body for field-level errors', retriable: false };
+    }
+    if (status === 429)
+        return { hint: 'rate limited; back off and retry', retriable: true };
+    if (status >= 500)
+        return { hint: 'server error; retry shortly', retriable: true };
+    return { retriable: false };
+}
 /** Shape any thrown value into the error envelope. */
 export function errEnvelope(err) {
     if (err instanceof ApiError) {
+        const code = deriveCode(err.body);
+        const { hint, retriable } = errorMeta(err.status, code);
         return {
             ok: false,
             error: {
                 status: err.status,
-                code: deriveCode(err.body),
+                code,
                 message: err.message,
+                ...(hint ? { hint } : {}),
+                retriable,
                 body: err.body,
             },
         };
     }
+    if (err instanceof TimeoutError) {
+        return {
+            ok: false,
+            error: {
+                status: 0,
+                code: 'timeout',
+                message: err.message,
+                hint: 'raise --timeout, or poll again with `cs job wait <jobId>`',
+                retriable: true,
+            },
+        };
+    }
     if (err instanceof UsageError) {
         return {
             ok: false,
@@ -52,6 +95,8 @@ export function errEnvelope(err) {
                 status: 0,
                 code: 'usage_error',
                 message: err.message,
+                hint: 'fix the invocation; run `cs <command> --help` or `cs schema --json`',
+                retriable: false,
                 ...(err.candidates ? { body: { candidates: err.candidates } } : {}),
             },
         };
@@ -60,7 +105,7 @@ export function errEnvelope(err) {
     const code = err instanceof Error && err.name && err.name !== 'Error'
         ? slug(err.name)
         : null;
-    return { ok: false, error: { status: 0, code, message } };
+    return { ok: false, error: { status: 0, code, message, retriable: false } };
 }
 /** Convenience: the exit code that pairs with a thrown value. */
 export { exitCodeFor };

package/dist/output/help.d.ts

@@ -3,5 +3,14 @@
  */
 import type { Cmd } from '../types.js';
 import type { IO } from '../io.js';
-export declare function renderTopHelp(io: IO, table: Cmd[]): void;
+/**
+ * The agent prompt shown when `cs` is run with no args — the first thing an AI
+ * harness (Claude Code, Codex, Copilot, …) sees. Tells it exactly how to drive
+ * the CLI: discover via `cs schema --json`, then parse the --json envelope and
+ * branch on exit codes. Kept plain-text so it is safe to capture/parse.
+ */
+export declare function renderAgentBanner(io: IO): void;
+export declare function renderTopHelp(io: IO, table: Cmd[], opts?: {
+    agent?: boolean;
+}): void;
 export declare function renderCommandHelp(io: IO, cmd: Cmd, table: Cmd[]): void;

package/dist/output/help.js

@@ -7,8 +7,37 @@ function optLine(name, spec) {
     const choices = spec.choices ? ` (${spec.choices.join('|')})` : '';
     return `  ${flag.padEnd(30)}${spec.desc}${choices}`;
 }
-export function renderTopHelp(io, table) {
+/**
+ * The agent prompt shown when `cs` is run with no args — the first thing an AI
+ * harness (Claude Code, Codex, Copilot, …) sees. Tells it exactly how to drive
+ * the CLI: discover via `cs schema --json`, then parse the --json envelope and
+ * branch on exit codes. Kept plain-text so it is safe to capture/parse.
+ */
+export function renderAgentBanner(io) {
+    io.stdout([
+        '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+        'AI agents (Claude Code, Codex, Copilot, Cursor): drive this CLI like so.',
+        '',
+        '1. Discover everything — run:  cs schema --json',
+        '   → the full command/flag tree (every command, arg, option) as JSON.',
+        '2. Add --json to every command. stdout is exactly ONE envelope:',
+        '     success → {"ok":true,"data":…}',
+        '     failure → {"ok":false,"error":{"status","code","message"}}',
+        '   All logs/progress go to stderr, so parse stdout directly.',
+        '3. Branch on exit codes — they are stable:',
+        '     0 ok · 2 usage · 3 auth · 4 not-found · 5 conflict (retry --replace)',
+        '     6 validation · 7 rate-limited · 124 timeout',
+        '4. Auth non-interactively: export COMMISSIONSIGHT_TOKEN, or',
+        '     printf %s "$TOKEN" | cs auth login --token-stdin',
+        '5. Destructive commands need --yes. Uploads are idempotent — safe to retry.',
+        '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+        '',
+    ].join('\n'));
+}
+export function renderTopHelp(io, table, opts = {}) {
     io.stdout(`cs ${cliVersion()} — CommissionSight CLI\n\n`);
+    if (opts.agent)
+        renderAgentBanner(io);
     io.stdout('Usage: cs <command> [subcommand] [args] [flags]\n\n');
     // Group by top-level segment.
     const groups = new Map();

package/dist/output/schema-tree.d.ts

@@ -23,10 +23,28 @@ export interface SchemaCommand {
     }[];
     options: SchemaOption[];
 }
+export interface SchemaConventions {
+    /** The stable output envelope (plan §5.1). */
+    envelope: {
+        success: string;
+        error: string;
+        stdout: string;
+    };
+    /** ApiError.status → exit-code semantics (plan §5.2). */
+    exitCodes: Record<string, string>;
+    /** Fields present on a failure envelope's `error` object. */
+    errorFields: string[];
+    auth: string;
+    idempotency: string;
+    pagination: string;
+}
 export interface SchemaDoc {
     name: string;
     version: string;
+    /** Machine-readable usage contract so one `cs schema --json` call is enough. */
+    conventions: SchemaConventions;
     globalOptions: SchemaOption[];
     commands: SchemaCommand[];
 }
+export declare const CONVENTIONS: SchemaConventions;
 export declare function buildSchema(table: Cmd[], version: string): SchemaDoc;

package/dist/output/schema-tree.js

@@ -1,4 +1,26 @@
 import { GLOBAL_OPTIONS } from '../globals.js';
+export const CONVENTIONS = {
+    envelope: {
+        success: '{"ok":true,"data":<result>}',
+        error: '{"ok":false,"error":{"status":<int>,"code":<string|null>,"message":<string>,"hint":<string?>,"retriable":<bool>,"body":<any?>}}',
+        stdout: 'With --json, stdout carries exactly one envelope; all logs/progress go to stderr.',
+    },
+    exitCodes: {
+        '0': 'success',
+        '1': 'unexpected/internal error (includes a job that finished failed)',
+        '2': 'usage error (bad flags/args)',
+        '3': 'auth error (401/403)',
+        '4': 'not found (404)',
+        '5': 'conflict (409) — e.g. period_exists; retry with --replace',
+        '6': 'validation/unprocessable (400/422)',
+        '7': 'rate limited (429) — retriable',
+        '124': 'timeout (--wait exceeded --timeout) — retriable',
+    },
+    errorFields: ['status', 'code', 'message', 'hint', 'retriable', 'body'],
+    auth: 'Set COMMISSIONSIGHT_TOKEN, or pipe a token via `cs auth login --token-stdin`. --token-file/--token also work; --token is discouraged (shell history).',
+    idempotency: 'cs upload / cs upload batch derive a stable idempotency key per file; re-running is safe and resumable (existing carrier+periods come back as skipped).',
+    pagination: 'List commands accept --limit and --all (auto-paginate); offset endpoints also take --offset, listFiles takes --cursor.',
+};
 function optionToSchema(flag, spec) {
     return {
         flag,
@@ -14,6 +36,7 @@ export function buildSchema(table, version) {
     return {
         name: 'cs',
         version,
+        conventions: CONVENTIONS,
         globalOptions: Object.entries(GLOBAL_OPTIONS).map(([f, s]) => optionToSchema(f, s)),
         commands: table
             .slice()

package/dist/router.js

@@ -96,9 +96,12 @@ export async function run(argv, opts = {}) {
     }
     // No command resolved.
     if (!match) {
-        const wantsHelp = hasFlag(argv, 'help', 'h') || argv.length === 0 || words.length === 0;
-        if (wantsHelp && (argv.length === 0 || hasFlag(argv, 'help', 'h'))) {
-            renderTopHelp(io, table);
+        const noArgs = argv.length === 0;
+        const wantsHelp = hasFlag(argv, 'help', 'h') || noArgs || words.length === 0;
+        if (wantsHelp && (noArgs || hasFlag(argv, 'help', 'h'))) {
+            // No-args invocation leads with the AI-agent prompt (the first touchpoint
+            // for a harness discovering the `cs` binary).
+            renderTopHelp(io, table, { agent: noArgs });
             return EXIT.OK;
         }
         // Unknown command word(s).
@@ -209,13 +212,9 @@ function finishError(io, err, json, quiet) {
         return code;
     }
     io.stderr(`error: ${env.error.message}\n`);
-    // Actionable hints.
-    if (env.error.status === 409 && env.error.code === 'period_exists') {
-        io.stderr('hint: retry with --replace to correct this period atomically\n');
-    }
-    if (env.error.status === 401 || env.error.status === 403) {
-        io.stderr("hint: check your token with 'cs auth status'\n");
-    }
+    // Single source of truth for the actionable hint (also in the JSON envelope).
+    if (env.error.hint)
+        io.stderr(`hint: ${env.error.hint}\n`);
     if (err instanceof UsageError && err.candidates?.length) {
         io.stderr('candidates:\n');
         for (const c of err.candidates)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commissionsight/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Command-line interface for the CommissionSight API — auth, workspaces, and statement uploads for any carrier and period.",
   "keywords": [
     "commissionsight",