@ciphrix/cli 0.1.1 → 0.3.0

package/README.md

@@ -60,8 +60,9 @@ ciphrix test run result "MFA enforced" \
   --note "Rolled out organisation-wide"
 ```
 
-Add `--json` to any command for stable machine-readable output. Commands that perform consequential
-changes show the proposed action and ask for confirmation; automation can opt in with `--yes`.
+Add `--json` for machine-readable output. Confirmed changes show a proposal and ask for consent;
+automation must explicitly opt in with `--yes`. New immediate decision/send commands apply directly
+and reject `--yes`; check command help rather than adding the flag to every write.
 
 ## One interface for compliance work
 
@@ -72,8 +73,33 @@ changes show the proposed action and ask for confirmation; automation can opt in
 - **Manage operational registers** — work with assets, vendors, risks, treatments, ownership, and files.
 - **Operate monitoring** — inspect checks, resources, runs, findings, integrations, and background jobs.
 
-Names and stable Ciphrix codes are accepted throughout, so neither people nor agents need to work with
-opaque database identifiers.
+Established record commands accept names and stable Ciphrix codes where advertised. Access inventory,
+review tasks and proposals require the exact IDs returned by their read commands; never guess identifiers.
+
+### Document review and approval
+
+Configure Simple or Advanced workflows, assign active users, and explicitly send, recall or decide
+review/approval requests. Admins and InfoSec leads operate these commands; employees can receive
+assignments and complete decisions in the app.
+
+```bash
+# Read state before configuring an existing draft
+ciphrix document get "Access Control Policy" --json
+ciphrix document workflow set "Access Control Policy" --type advanced
+ciphrix user list --search "reviewer@example.com" --json
+ciphrix document reviewer set "Access Control Policy" --user "reviewer@example.com"
+ciphrix document approver set "Access Control Policy" --user "approver@example.com"
+
+# Send only when authorized; review completion is a separate human decision
+ciphrix document submit "Access Control Policy"
+```
+
+After the reviewer completes review in the app (or an authorized caller explicitly records that
+decision), request approval separately with `document approval send`. Ordinary approval remains
+`document approve`; self-approval is a distinct explicit decision, not a review bypass.
+
+See the [document workflow guide](skills/ciphrix/references/document-workflows.md) for recovery,
+confirmation/retry boundaries and result interpretation. Use installed `--help` for exact options.
 
 ## Built for agent workspaces
 
@@ -99,7 +125,15 @@ The skill works with compatible agent harnesses including Codex, Claude Code, Cu
 is also included in the npm package at [`skills/ciphrix/SKILL.md`](skills/ciphrix/SKILL.md). Installing
 the npm package never modifies an agent's configuration directories.
 
-Run `npx skills update` to update installed skills when a newer version is available.
+Run `npx skills update` to update installed skills when a newer version is available. Keep the skill
+aligned with your installed CLI version; its generated command reference and local help describe the
+available grammar. Server capability discovery remains authoritative for which operations you can use.
+
+For document workflows, assignment and request sending are separate from formal review and approval
+decisions. An agent may coordinate an authorized recall/configure/resend request, but must ask before
+making a formal decision. A sent request must be recalled before changing its recipient, even when
+selecting the same person. Recall clears that assignment. Active employees may be assigned and finish
+their decisions in the app; tool access remains restricted to admins and InfoSec leads.
 
 ### Ask in natural language, operate through the CLI
 
@@ -144,6 +178,7 @@ one command. Installed help is authoritative. The complete generated reference i
 | `ciphrix login` · `logout`                         | Authorize this device or revoke its session.                                   |
 | `ciphrix context get` · `status` · `set` · `reset` | Read and maintain Business and Operating Context.                              |
 | `ciphrix document …`                               | Browse, read, create, edit, version, submit, approve, and delete documents.    |
+| `ciphrix user list`                                | Discover active users by name/email or paginated listing for assignment.       |
 | `ciphrix test …`                                   | Inspect tests, links, runs and evidence; attach items and record results.      |
 | `ciphrix framework …`                              | Browse applied frameworks and work with clauses and mappings.                  |
 | `ciphrix control …`                                | Inspect controls, ownership, applicability, design requirements, and mappings. |
@@ -155,6 +190,47 @@ one command. Installed help is authoritative. The complete generated reference i
 
 </details>
 
+### Context, reviews and agent-assisted work
+
+The onboarding group reads separate Business and Operating Context, saves agreed questionnaire answers,
+and offers explicit optional setup and completion. Business Context readiness is decided by the server;
+Operating Context and optional setup do not block journey completion. Saving context never automatically
+starts agents or completes the journey. Local `--help` works offline; `onboarding --help-onboarding`
+returns authenticated server guidance and the current status pack.
+
+The access group separates inventory, reviewed import proposals, assigned reviewer decisions and campaign
+results. A revoke decision records a removal request, not provider-side revocation. Recording decisions,
+completing a reviewer task, and ending a campaign are separate operations. Imports merge only explicitly
+selected reviewed rows; inspect per-row failures even when some rows applied.
+
+Agent findings and advisory test/control assessments do not make formal human decisions. Assigned-task
+discovery does not complete work. File staging and processing are explicit, separate operations; processing
+may update context or create vendors. Evidence/CSV commands return expiring signed references without
+automatically downloading files. Use each command's help for the exact inputs, next reads and effects.
+
+### Manifest compatibility, JSON and retries
+
+The CLI discovers allowed tools and their effects from the authenticated server manifest. New command
+groups require server-declared command bindings. An unavailable binding is reported as unsupported;
+the CLI never guesses a different endpoint or interprets the manifest as authorization. Existing
+commands keep their successful JSON formats. New capability commands emit complete success/error
+envelopes with `--json`, preserving warnings, pagination, truncation and structured error details.
+Failures and partially applied mutations return a nonzero exit status.
+
+Confirmed writes require explicit consent. New commands in JSON/non-interactive mode require `--yes`
+for confirmed operations; immediate writes do not accept that flag. Write controls are rejected for
+reads. The optional `--idempotency-key` names one logical write: reuse identical input for a retry,
+never a new key to bypass an unknown outcome. There are no automatic write retries. Confirmed replay
+also needs a valid confirmation token; a fresh invocation re-preflights and may be blocked by changed
+state or expiry. The CLI does not save confirmation tokens or promise recovery across invocations.
+Inspect current records/jobs when uncertain. Replayed status packs and signed URLs are original
+snapshots, not refreshed state or renewed downloads.
+
+Mutation JSON files must be regular files, at most 1 MiB, containing an explicitly selected array.
+Use clear flags or JSON null where supported, not the string `"null"`. Do not infer confirmations
+from suggested matches. New repeated flags collect separate values; existing command conventions remain
+compatible. See the generated command reference for all options and nested payload details.
+
 ## Safe by default
 
 - Credentials use the operating system keychain by default and are isolated by API environment.

package/dist/actions.d.ts

@@ -8,6 +8,8 @@ export interface ApplyOptions {
     fallback: string;
     yes?: boolean | undefined;
     confirm?: ((question: string) => Promise<boolean>) | undefined;
+    idempotencyKey?: string | undefined;
+    quiet?: boolean | undefined;
 }
 /**
  * Runs a tool, handling the two-step confirm contract when the tool requires it.
@@ -16,4 +18,4 @@ export interface ApplyOptions {
  * - Tools that require confirmation: the first call is a preflight (summary + token), the user is asked
  *   once, then the change is applied with the token and an idempotency key.
  */
-export declare const applyTool: ({ ctx, io, toolName, input, fallback, yes, confirm, }: ApplyOptions) => Promise<Record<string, unknown> | null>;
+export declare const applyTool: ({ ctx, io, toolName, input, fallback, yes, confirm, idempotencyKey: suppliedKey, quiet, }: ApplyOptions) => Promise<Record<string, unknown> | null>;

package/dist/actions.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { promptConfirm, writeLine } from './io.js';
+import { ApiError } from './api.js';
+import { getTool } from './manifest.js';
 import { asRecord, asText, callTool, errorMessage } from './toolSurface.js';
 /**
  * Runs a tool, handling the two-step confirm contract when the tool requires it.
@@ -8,23 +10,30 @@ import { asRecord, asText, callTool, errorMessage } from './toolSurface.js';
  * - Tools that require confirmation: the first call is a preflight (summary + token), the user is asked
  *   once, then the change is applied with the token and an idempotency key.
  */
-export const applyTool = async ({ ctx, io, toolName, input, fallback, yes = false, confirm, }) => {
+export const applyTool = async ({ ctx, io, toolName, input, fallback, yes = false, confirm, idempotencyKey: suppliedKey, quiet = false, }) => {
     const ask = confirm ?? ((question) => promptConfirm(io, question));
-    const idempotencyKey = randomUUID();
+    const idempotencyKey = suppliedKey ?? randomUUID();
+    const tool = await getTool(ctx, toolName);
+    if (tool.effect !== 'write')
+        throw new Error('Expected a write operation.');
     const first = await callTool(ctx, toolName, input, { idempotencyKey });
     if (first.status !== 'ok')
-        throw new Error(errorMessage(first, fallback));
+        throw new ApiError(errorMessage(first, fallback), 400, asText(asRecord(first.error).code), asRecord(first.error).details, first);
     const confirmation = asRecord(asRecord(first.meta).confirmation);
     const token = asText(confirmation.token);
-    if (!token)
+    if (tool.confirmation === 'none')
         return first;
-    writeLine(io.stdout, asText(confirmation.summary, 'Apply this change?'));
+    if (!token)
+        throw new Error('The server did not return the required confirmation token. No change was applied.');
+    if (!quiet)
+        writeLine(io.stdout, asText(confirmation.summary, 'Apply this change?'));
     if (!yes && !(await ask('Apply this change?'))) {
-        writeLine(io.stdout, 'Cancelled.');
+        if (!quiet)
+            writeLine(io.stdout, 'Cancelled.');
         return null;
     }
     const result = await callTool(ctx, toolName, input, { confirmationToken: token, idempotencyKey });
     if (result.status !== 'ok')
-        throw new Error(errorMessage(result, fallback));
+        throw new ApiError(errorMessage(result, fallback), 400, asText(asRecord(result.error).code), asRecord(result.error).details, result);
     return result;
 };

package/dist/api.d.ts

@@ -1,7 +1,9 @@
 export declare class ApiError extends Error {
     readonly status: number;
     readonly code: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
+    readonly details: unknown;
+    readonly envelope: unknown;
+    constructor(message: string, status: number, code?: string | undefined, details?: unknown, envelope?: unknown);
 }
 export interface RequestOptions {
     method?: string;

package/dist/api.js

@@ -1,11 +1,15 @@
 export class ApiError extends Error {
     status;
     code;
-    constructor(message, status, code = undefined) {
+    details;
+    envelope;
+    constructor(message, status, code = undefined, details = undefined, envelope = undefined) {
         super(message);
         this.name = 'ApiError';
         this.status = status;
         this.code = code;
+        this.details = details;
+        this.envelope = envelope;
     }
 }
 /** Default time allowed for an API request, including reading its response body. */
@@ -104,7 +108,7 @@ const errorPayload = (data) => {
             : typeof nested?.code === 'string'
                 ? nested.code
                 : undefined;
-    const details = Array.isArray(nested?.details) ? nested?.details : [];
+    const details = nested?.details;
     return { message, code, details };
 };
 /**
@@ -172,7 +176,7 @@ export const createApiClient = (baseUrl, limits = {}) => ({
             }
             if (!response.ok) {
                 const { message, code, details } = errorPayload(data);
-                throw new ApiError(withDetails(message || `Request failed with status ${response.status}`, code, details), response.status, code);
+                throw new ApiError(withDetails(message || `Request failed with status ${response.status}`, code, Array.isArray(details) ? details : []), response.status, code, details, data);
             }
             return data;
         });

package/dist/cli.js

@@ -1,4 +1,6 @@
 import { Command, CommanderError } from 'commander';
+import { registerCapabilities, RenderedCommandError } from './commands/capabilities.js';
+import { asRecord } from './toolSurface.js';
 import { formatBanner } from './banner.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
@@ -247,7 +249,9 @@ export const createProgram = (io = createDefaultIO()) => {
             json: readBooleanOption(options, 'json'),
         });
     });
-    const testRun = test.command('run').description('Create, result and delete runs');
+    const testRun = test
+        .command('run')
+        .description('Run lifecycle, human results/notes, linked evidence references and advisory assessments');
     testRun
         .command('create <name>')
         .description('Create a new pending run')
@@ -266,17 +270,21 @@ export const createProgram = (io = createDefaultIO()) => {
     testRun
         .command('result <name>')
         .description('Record a run result: passing | failing | skipped | pending (reopen)')
-        .requiredOption('--status <status>', 'passing | failing | skipped | pending')
+        .option('--status <status>', 'human-decided result: passing | failing | skipped | pending; omit for note-only changes')
         .option('--note <text>', 'note for the run')
+        .option('--clear-note', 'clear the note without changing the result; conflicts with --note')
         .option('--run <id>', 'a specific run')
         .option('--api-url <url>', 'override the API base URL for this command')
         .option('--json', 'output raw JSON')
         .action(async (name, options) => {
+        if (readBooleanOption(options, 'clearNote') &&
+            readStringOption(options, 'note') !== undefined)
+            throw new Error('--clear-note conflicts with --note.');
         await testRunResultCommand({
             io,
             name,
-            status: readStringOption(options, 'status') ?? '',
-            note: readStringOption(options, 'note'),
+            status: readStringOption(options, 'status'),
+            note: readBooleanOption(options, 'clearNote') ? null : readStringOption(options, 'note'),
             runId: readStringOption(options, 'run'),
             apiUrl: readStringOption(options, 'apiUrl'),
             json: readBooleanOption(options, 'json'),
@@ -848,10 +856,11 @@ export const createProgram = (io = createDefaultIO()) => {
     });
     const control = program
         .command('control')
-        .description('Controls: status, applicability, owner and design requirements');
+        .description('Controls: status, applicability, ownership, design requirements and advisory assessments');
     control
         .command('list')
         .description('List controls with their status, applicability and owner')
+        .option('--framework <code>', 'filter by catalogue framework code; repeat for multiple values', (value, previous = []) => [...previous, value])
         .option('--search <text>', 'filter by name or code')
         .option('--domain <value>', 'filter by control domain')
         .option('--status <csv>', 'filter by status')
@@ -864,6 +873,9 @@ export const createProgram = (io = createDefaultIO()) => {
         .action(async (options) => {
         await controlListCommand({
             io,
+            framework: Array.isArray(asRecord(options).framework)
+                ? asRecord(options).framework
+                : undefined,
             search: readStringOption(options, 'search'),
             domain: readStringOption(options, 'domain'),
             status: readStringOption(options, 'status'),
@@ -1567,6 +1579,7 @@ export const createProgram = (io = createDefaultIO()) => {
             json: readBooleanOption(options, 'json'),
         });
     });
+    registerCapabilities(program, io);
     // A bare `ciphrix` shows the banner and help; commands never print the banner.
     program.action(() => {
         writeBlock(io.stdout, `${formatBanner(io.theme)}\n\n`);
@@ -1590,6 +1603,8 @@ export const main = async (argv = process.argv, io = createDefaultIO()) => {
         return 0;
     }
     catch (error) {
+        if (error instanceof RenderedCommandError)
+            return 1;
         if (error instanceof CommanderError) {
             return error.exitCode;
         }

package/dist/commands/capabilities.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { type CliIO } from '../io.js';
+import { type ToolContext } from '../toolSurface.js';
+export declare class RenderedCommandError extends Error {
+}
+export declare const registerCapabilities: (program: Command, io: CliIO, context?: (apiUrl?: string) => Promise<ToolContext>) => void;

package/dist/commands/capabilities.js

@@ -0,0 +1,311 @@
+import { Command, Option } from 'commander';
+import { applyTool } from '../actions.js';
+import { ApiError } from '../api.js';
+import { promptConfirm, writeLine } from '../io.js';
+import { ManifestError, resolveBinding } from '../manifest.js';
+import { asRecord, callTool, resolveToolContext } from '../toolSurface.js';
+import { FileInputError, readUploadFile, stageLocalFile } from '../upload.js';
+import { capabilities, onboardingOperations, } from './capabilityDefinitions.js';
+export class RenderedCommandError extends Error {
+}
+class InputError extends Error {
+}
+const retryHelp = 'Writes use one idempotency key per operation. Reuse that key/input for retries; never bypass an unknown outcome with a new key. Confirmed calls also require valid confirmation: a fresh invocation re-preflights and may be blocked by changed state or expiry. Inspect current state/jobs when uncertain. Replayed status packs and signed URLs are snapshots, not refreshed reads.';
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new InputError('Expected strict JSON. Quote string values as JSON strings.');
+    }
+};
+const inputFor = async (spec, args, options) => {
+    const input = {};
+    for (const [index, name] of (spec.argument?.split(' ') ?? []).entries())
+        input[name] = args[index];
+    for (const field of spec.fields) {
+        const value = options[field.flag.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())];
+        if (value === undefined)
+            continue;
+        if (Object.hasOwn(input, field.field))
+            throw new InputError(`Conflicting options for ${field.field}.`);
+        let parsed = value;
+        if (field.kind === 'clear')
+            parsed = null;
+        if (field.kind === 'integer') {
+            if (typeof value !== 'string' || !/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+                throw new InputError(`--${field.flag} requires a nonnegative integer.`);
+            parsed = Number(value);
+        }
+        if (field.kind === 'json') {
+            if (typeof value !== 'string')
+                throw new InputError('Expected a JSON argument.');
+            parsed = parseJson(value);
+        }
+        if (field.kind === 'file') {
+            if (typeof value !== 'string')
+                throw new InputError('Expected a regular file path.');
+            parsed = parseJson((await readUploadFile(value, 1024 * 1024)).toString('utf8'));
+            if (!Array.isArray(parsed))
+                throw new InputError(`--${field.flag} requires a JSON array.`);
+        }
+        input[field.field] = parsed;
+    }
+    if (spec.path === 'access entry bulk-update')
+        input.operation = 'update';
+    if (spec.inputAdapter === 'documentWorkflow') {
+        const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        const document = typeof input.document === 'string' ? input.document : '';
+        if (!document.trim())
+            throw new InputError('Provide a document name, code or ID.');
+        delete input.document;
+        input[uuid.test(document) ? 'policyId' : 'name'] = document;
+        if (input.user !== undefined) {
+            const user = typeof input.user === 'string' ? input.user : '';
+            if (uuid.test(user))
+                input.user = { id: user };
+            else if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(user))
+                input.user = { email: user };
+            else
+                throw new InputError('--user requires an exact email or User ID.');
+        }
+    }
+    return input;
+};
+const partialFailure = (value, depth = 0) => {
+    if (depth > 32 || !value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return value.some((item) => partialFailure(item, depth + 1));
+    const record = asRecord(value);
+    if (['failures', 'failed', 'unmerged'].some((key) => Array.isArray(record[key]) && record[key].length > 0))
+        return true;
+    return Object.values(record).some((child) => partialFailure(child, depth + 1));
+};
+const execute = async (ctx, tool, input, io, options) => {
+    if (tool.effect === 'read') {
+        if (options.yes || options.idempotencyKey !== undefined)
+            throw new InputError('Write controls do not apply to a read operation.');
+        return callTool(ctx, tool.name, input);
+    }
+    if (tool.confirmation === 'none' && options.yes)
+        throw new InputError('This write applies immediately and does not accept --yes.');
+    if (tool.confirmation !== 'none' && !options.yes && (options.json || !io.stdout.isTTY))
+        throw new InputError('This confirmed write requires --yes in JSON or non-interactive mode. No change was applied.');
+    return applyTool({
+        ctx,
+        io,
+        quiet: options.json === true,
+        toolName: tool.name,
+        input,
+        fallback: 'The operation could not be completed.',
+        yes: options.yes === true,
+        ...(typeof options.idempotencyKey === 'string' && { idempotencyKey: options.idempotencyKey }),
+        confirm: (question) => promptConfirm(io, question),
+    });
+};
+const render = (io, json, envelope, next) => {
+    if (json)
+        writeLine(io.stdout, JSON.stringify(envelope));
+    else {
+        writeLine(io.stdout, JSON.stringify(envelope.data ?? envelope, null, 2));
+        if (Array.isArray(envelope.warnings))
+            for (const warning of envelope.warnings)
+                writeLine(io.stdout, `warning: ${String(warning)}`);
+        if (asRecord(envelope.meta).truncated)
+            writeLine(io.stdout, 'Results are truncated; inspect continuation details.');
+        if (next)
+            writeLine(io.stdout, `next: ciphrix ${next} --help`);
+    }
+};
+const run = async (io, options, next, action) => {
+    let failed;
+    let applying = false;
+    try {
+        const key = options.idempotencyKey;
+        if (key !== undefined && (typeof key !== 'string' || !key.trim() || key.length > 256)) {
+            throw new InputError('The idempotency key must contain 1 to 256 characters.');
+        }
+        const envelope = await action(() => {
+            applying = true;
+        });
+        if (!envelope) {
+            if (options.json)
+                writeLine(io.stdout, JSON.stringify({ status: 'cancelled' }));
+            return;
+        }
+        render(io, options.json === true, envelope, next);
+        failed = envelope.status !== 'ok' || (applying && partialFailure(envelope.data));
+        if (failed && !options.json)
+            writeLine(io.stderr, 'The operation failed or partially applied. Inspect the returned outcomes before taking further action.');
+    }
+    catch (error) {
+        const envelope = error instanceof ApiError && asRecord(error.envelope).status === 'error'
+            ? asRecord(error.envelope)
+            : {
+                status: 'error',
+                error: {
+                    code: error instanceof InputError || error instanceof FileInputError
+                        ? 'invalid_input'
+                        : error instanceof ManifestError
+                            ? 'unsupported_capability'
+                            : error instanceof ApiError
+                                ? (error.code ?? 'http_error')
+                                : 'transport_error',
+                    message: error instanceof InputError ||
+                        error instanceof FileInputError ||
+                        error instanceof ApiError ||
+                        error instanceof ManifestError
+                        ? error.message
+                        : 'The request could not be completed. Check capabilities and inspect state before retrying a write.',
+                    ...(error instanceof ApiError && {
+                        httpStatus: error.status,
+                        ...(error.details !== undefined && { details: error.details }),
+                    }),
+                },
+            };
+        render(options.json ? io : { ...io, stdout: io.stderr }, options.json === true, envelope, '');
+        failed = true;
+    }
+    if (failed)
+        throw new RenderedCommandError();
+};
+const groupDescriptions = {
+    user: 'Active tenant-user discovery; no account administration',
+    'document workflow': 'Configure workflow or explicitly return to draft',
+    'document reviewer': 'Configure the review recipient; recall sent requests first',
+    'document approver': 'Configure the approval recipient; recall sent requests first',
+    'document review': 'Explicit review decisions and request recall; send with document submit',
+    'document approval': 'Approval requests, explicit decisions and recall; ordinary decision with document approve',
+    access: 'Access inventory, reviewed imports and assigned reviewer workflows',
+    'access resource': 'Resources, owners and asset relationships',
+    'access entry': 'Revisioned access inventory; inventory edits are not review decisions',
+    'access import': 'Your import proposals, selected-row merges and explicit discard',
+    'access review': 'Review campaigns, assigned decisions, completion and frozen outcomes',
+    agent: 'Agent activity, complete proposals and explicit human decisions',
+    'agent run': 'Grouped agent activity; findings are not completed assessments',
+    'agent action': 'Findings, reviewed proposals and declared approve/reject/choose options',
+    task: 'Your assigned stored work; discovery never completes tasks',
+    file: 'Owned local-file staging and explicit processing; no automatic downloads',
+};
+const parent = (program, path) => {
+    let current = program;
+    const traversed = [];
+    for (const segment of path) {
+        traversed.push(segment);
+        current =
+            current.commands.find((command) => command.name() === segment) ??
+                current
+                    .command(segment)
+                    .description(groupDescriptions[traversed.join(' ')] ?? `${segment} capabilities`);
+    }
+    return current;
+};
+const common = (command) => {
+    command
+        .option('--api-url <url>', 'override the API base URL')
+        .option('--json', 'emit one complete result/error envelope')
+        .option('--yes', 'confirmed writes only: explicitly authorize without prompting; rejected on reads/immediate writes')
+        .option('--idempotency-key <key>', 'writes only: key for one logical operation; reuse identical input, at most 256 characters')
+        .addHelpText('after', `\n${retryHelp}\n`);
+};
+const addField = (command, field) => {
+    const flag = `--${field.flag}${['boolean', 'clear'].includes(field.kind) ? '' : ' <value>'}`;
+    const option = new Option(flag, field.help);
+    if (field.required)
+        option.makeOptionMandatory();
+    if (field.kind === 'repeat')
+        option.argParser((value, previous = []) => [...previous, value]);
+    command.addOption(option);
+};
+export const registerCapabilities = (program, io, context = resolveToolContext) => {
+    for (const spec of capabilities) {
+        const segments = spec.path.split(' ');
+        const operation = segments.pop();
+        const command = parent(program, segments)
+            .command(operation +
+            (spec.argument
+                ? ` ${spec.argument
+                    .split(' ')
+                    .map((name) => `<${name}>`)
+                    .join(' ')}`
+                : ''))
+            .description(spec.description);
+        for (const field of spec.fields)
+            addField(command, field);
+        if (spec.path === 'access entry bulk-update')
+            command.addHelpText('after', '\nRows: [{accessId, expectedRevision}]. Only update is exposed. field selects identity, personId, role or status; value is a JSON string, or null to clear personId. Each row can fail independently.\n');
+        if (spec.path === 'access import merge')
+            command.addHelpText('after', '\nRows require proposal_row_id. Optional reviewed corrections: resource_id, resource_name, website, identity, role, person_id, resource_owner_person_id, confirm_person_match, confirm_visual_evidence, expected_revision, access_id. Preserve snake_case. Never infer match/evidence confirmations or merge all rows implicitly. Read the proposal before selecting rows.\n');
+        if (spec.path === 'access review decide')
+            command.addHelpText('after', '\nItems: [{accessId, expectedRevision, decision, comment?}]. decision is keep or revoke; comment may be null. Revoke records a removal request, not provider revocation. Complete the assigned task separately after all decisions.\n');
+        common(command);
+        command.action(async (...values) => {
+            const options = asRecord(values[values.length - 2]);
+            await run(io, options, spec.next, async (write) => {
+                const input = await inputFor(spec, values.slice(0, -2), options);
+                const ctx = await context(typeof options.apiUrl === 'string' ? options.apiUrl : undefined);
+                const tool = await resolveBinding(ctx, segments, operation);
+                if (tool.effect === 'write')
+                    write();
+                if (spec.path === 'file stage') {
+                    if (tool.effect !== 'write' || tool.confirmation !== 'none' || options.yes)
+                        throw new InputError('Staging requires an immediate write capability and does not accept --yes.');
+                    const advertised = Number(tool.limits?.maxFileBytes);
+                    const staged = await stageLocalFile(ctx, String(input.path), String(input.purpose), {
+                        maxUploadBytes: Number.isSafeInteger(advertised) && advertised > 0
+                            ? Math.min(advertised, 25 * 1024 * 1024)
+                            : 25 * 1024 * 1024,
+                    }, tool, typeof options.idempotencyKey === 'string' ? options.idempotencyKey : undefined);
+                    return staged.envelope;
+                }
+                return execute(ctx, tool, input, io, options);
+            });
+        });
+    }
+    const onboarding = program
+        .command('onboarding')
+        .description('Learn organizational context, inspect optional setup and explicitly complete the journey. Operating Context does not block completion.');
+    for (const [operation, description] of onboardingOperations)
+        onboarding.option(`--${operation}${['get-context', 'set-context', 'init-framework'].includes(operation) ? ' <value>' : ''}`, description);
+    onboarding
+        .option('--question <id>', 'questionId from the selected schema')
+        .option('--value <json>', 'strict JSON answer, including quoted JSON strings')
+        .option('--additional-context <text>', 'answer explanation; explanation-only answers are supported');
+    common(onboarding);
+    onboarding.action(async (options) => {
+        await run(io, options, 'onboarding --status', async (write) => {
+            const selected = onboardingOperations.filter(([operation]) => options[operation.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())] !== undefined);
+            if (selected.length !== 1)
+                throw new InputError('Select exactly one onboarding operation; use --help for syntax.');
+            const operation = selected[0][0];
+            const input = {};
+            if (operation === 'get-context' || operation === 'set-context')
+                input.store = options[operation === 'get-context' ? 'getContext' : 'setContext'];
+            if (operation === 'set-context') {
+                if (typeof options.question !== 'string' ||
+                    (options.value === undefined && options.additionalContext === undefined))
+                    throw new InputError('Set context requires --question and --value and/or --additional-context.');
+                input.questionId = options.question;
+                if (options.value !== undefined) {
+                    if (typeof options.value !== 'string')
+                        throw new InputError('Expected a JSON answer.');
+                    input.value = parseJson(options.value);
+                }
+                if (options.additionalContext !== undefined)
+                    input.additionalContext = options.additionalContext;
+            }
+            else if (options.question !== undefined ||
+                options.value !== undefined ||
+                options.additionalContext !== undefined)
+                throw new InputError('Answer options require --set-context.');
+            if (operation === 'init-framework')
+                input.frameworkCode = options.initFramework;
+            const ctx = await context(typeof options.apiUrl === 'string' ? options.apiUrl : undefined);
+            const tool = await resolveBinding(ctx, ['onboarding'], operation === 'help-onboarding' ? 'help' : operation);
+            if (tool.effect === 'write')
+                write();
+            return execute(ctx, tool, input, io, options);
+        });
+    });
+};

package/dist/commands/capabilityDefinitions.d.ts

@@ -0,0 +1,18 @@
+export type FieldKind = 'text' | 'integer' | 'boolean' | 'repeat' | 'json' | 'file' | 'clear';
+export interface Field {
+    flag: string;
+    field: string;
+    help: string;
+    kind: FieldKind;
+    required: boolean;
+}
+export interface Capability {
+    path: string;
+    description: string;
+    argument?: string;
+    inputAdapter?: 'documentWorkflow';
+    fields: Field[];
+    next: string;
+}
+export declare const capabilities: Capability[];
+export declare const onboardingOperations: readonly [readonly ["status", "read current journey and separate context readiness"], readonly ["help-onboarding", "read authenticated server help, all options and current status"], readonly ["get-context", "read business/operating schema and answers"], readonly ["set-context", "save one agreed business/operating answer without completing the journey"], readonly ["run-vendor-agent", "start vendor discovery; may create vendors; requires Business Context 100%"], readonly ["run-risk-agent", "start initial risk generation; requires Business Context 100%"], readonly ["init-framework", "initialize a selected framework; may consume quota and notify administrators"], readonly ["complete", "explicitly complete with Business Context 100%; operating/setup remain optional"]];