@commissionsight/cli 0.1.0 → 0.1.1

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
 

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/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).

package/package.json

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