@ciphrix/cli 0.2.0 → 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
 
@@ -75,6 +76,31 @@ changes show the proposed action and ask for confirmation; automation can opt in
 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
 
 Ciphrix ships an agent skill as well as a CLI. The CLI provides the tools; the skill teaches an agent the
@@ -103,6 +129,12 @@ Run `npx skills update` to update installed skills when a newer version is avail
 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
 
 An agent can translate a request into a Ciphrix command, inspect the structured result, and present the
@@ -146,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. |

package/dist/commands/capabilities.js

@@ -53,6 +53,23 @@ const inputFor = async (spec, args, options) => {
     }
     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) => {
@@ -154,6 +171,12 @@ const run = async (io, options, next, action) => {
         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',

package/dist/commands/capabilityDefinitions.d.ts

@@ -10,6 +10,7 @@ export interface Capability {
     path: string;
     description: string;
     argument?: string;
+    inputAdapter?: 'documentWorkflow';
     fields: Field[];
     next: string;
 }

package/dist/commands/capabilityDefinitions.js

@@ -63,6 +63,59 @@ const filters = () => [
     field('limit', 'limit', 'integer'),
 ];
 export const capabilities = [
+    ...[
+        ['document workflow set', 'Set workflow type in draft.', 'workflowType'],
+        ['document reviewer set', 'Set reviewer; sent requests must be recalled first.', 'user'],
+        ['document reviewer remove', 'Remove the reviewer from a draft.'],
+        ['document approver set', 'Set approver; sent requests must be recalled first.', 'user'],
+        ['document approver remove', 'Remove approver; sent requests must be recalled first.'],
+        [
+            'document review complete',
+            'Record an explicitly authorized review decision; does not send approval.',
+        ],
+        ['document review send-back', 'Record an explicit negative review decision; clears reviewer.'],
+        [
+            'document review cancel',
+            'Recall review request; clears reviewer. Configure and resend separately.',
+        ],
+        [
+            'document approval send',
+            'Send for approval after review; never completes review implicitly.',
+        ],
+        [
+            'document approval send-back',
+            'Record an explicit negative approval decision; clears approver.',
+        ],
+        [
+            'document approval cancel',
+            'Recall approval request; clears approver. Configure and resend separately.',
+        ],
+        [
+            'document approval self-approve',
+            'Explicit self-approval, separate from ordinary approve; no review bypass.',
+        ],
+        [
+            'document workflow return-to-draft',
+            'Return eligible advanced approval-stage document to draft; clears assignments.',
+        ],
+    ].map(([path, description, input]) => ({
+        path: path,
+        description: description,
+        argument: 'document',
+        inputAdapter: 'documentWorkflow',
+        fields: input === 'workflowType'
+            ? [field('type', 'workflowType', 'text', true, 'workflow type: simple or advanced')]
+            : input === 'user'
+                ? [
+                    field('user', 'user', 'text', true, 'exact active user email or User ID; employees may be assigned'),
+                ]
+                : [],
+        next: 'document get',
+    })),
+    spec('user list', 'List active tenant users, including employees; discovery does not change accounts.', undefined, [
+        field('search', 'search', 'text', false, 'optional name/email search, at least three characters'),
+        ...page(),
+    ], 'document reviewer set'),
     spec('access resource list', 'List review inventory resources and owners.', undefined, [
         ...page(),
         field('search'),

package/dist/commands/policyActions.js

@@ -1,10 +1,20 @@
 import { readFile } from 'node:fs/promises';
 import { applyTool } from '../actions.js';
+import { getManifest, resolveBinding } from '../manifest.js';
 import { writeLine, writeTable } from '../io.js';
 import { asRecord, asText, callTool, errorMessage, resolveToolContext } from '../toolSurface.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f-]{27}$/i;
 const num = (value, fallback) => typeof value === 'number' ? String(value) : asText(value, fallback);
 const target = (policy) => UUID.test(policy) ? { policyId: policy } : { name: policy };
+// Retain the original named calls only for older manifests without these bindings.
+const documentWriteName = async (ctx, operation) => {
+    const manifest = await getManifest(ctx);
+    if (manifest.some((tool) => tool.cli?.operation === operation &&
+        JSON.stringify(tool.cli.group) === JSON.stringify(['document']))) {
+        return (await resolveBinding(ctx, ['document'], operation)).name;
+    }
+    return operation === 'submit' ? 'submit_document' : 'approve_document';
+};
 const renderResult = (io, json, result) => {
     if (json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
@@ -77,7 +87,7 @@ export const policySubmitCommand = async (options) => {
     const result = await applyTool({
         ctx,
         io,
-        toolName: 'submit_document',
+        toolName: await documentWriteName(ctx, 'submit'),
         input: target(policy),
         fallback: 'Could not submit the document for review.',
         yes,
@@ -92,7 +102,7 @@ export const policyApproveCommand = async (options) => {
     const result = await applyTool({
         ctx,
         io,
-        toolName: 'approve_document',
+        toolName: await documentWriteName(ctx, 'approve'),
         input: target(policy),
         fallback: 'Could not approve the document.',
         yes,

package/dist/constants.d.ts

@@ -4,4 +4,4 @@
  */
 export declare const CLI_NAME = "ciphrix";
 export declare const CLI_TAGLINE = "Ciphrix compliance platform CLI";
-export declare const CLI_VERSION = "0.2.0";
+export declare const CLI_VERSION = "0.3.0";

package/dist/constants.js

@@ -4,4 +4,4 @@
  */
 export const CLI_NAME = 'ciphrix';
 export const CLI_TAGLINE = 'Ciphrix compliance platform CLI';
-export const CLI_VERSION = '0.2.0';
+export const CLI_VERSION = '0.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciphrix/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official command-line interface for the Ciphrix compliance platform.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/ciphrix/SKILL.md

@@ -83,8 +83,9 @@ Two consequences worth internalising:
   addressed by their human name **or** their stable code (for example `ACME-DOC-A1B2`, `TSQ-001`,
   `ACME-RSK-CQJ4`, `ACME-AST-M5SD`). Ids work but are never required, and you never invent one. Prefer the
   code when a name is ambiguous.
-- **Intents, not steps.** Ask for the outcome; don't orchestrate the underlying calls. One user-facing
-  request may be several platform operations — that composition is the CLI's job, not the user's.
+- **Intents, not hidden decisions.** An agent may coordinate explicitly authorized platform operations
+  for one user request. Each operation remains separate: stop on errors or uncertain outcomes and never
+  infer a formal decision merely because it would let the next step proceed.
 - **Ask only for decisions.** Only actions that change something a person should review stop for
   confirmation — deleting, editing content, linking, or changing a control, clause, test or asset. A
   formal decision is its own verb (`approve`, `submit`, `test run result`) and applies directly. Everything
@@ -140,6 +141,19 @@ are what a check raised. `check disable` silences a check for the tenant — rec
 
 ## Guardrails
 
+**Document workflow.** Configuration, request sending, review completion, ordinary approval and
+self-approval are separate intents. Sending for approval never authorizes completing review first.
+When a recipient setter reports an already-sent request, explain the current stage and offer recall,
+configure and resend, even if the requested recipient is unchanged. Proceed only with authorization;
+recall clears the recipient, so set them again before resending rather than removing an already-cleared
+assignment. Unsent same-recipient selection reports already set. Read again between recovery steps and
+use a separate write key per operation. Employees may be assigned and complete decisions in the app;
+user discovery does not grant tool access. Use exact active User IDs/emails, not People IDs or fuzzy
+name matches. Workflow readiness is business guidance, not permission or proof of notification delivery.
+Before coordinating a document request or recovery, read
+[the workflow guide](references/document-workflows.md) for stage-specific sequencing and result handling;
+use installed help or [the generated reference](references/commands.md) for exact syntax.
+
 **Context and onboarding.** Read the server status and question schema, then save only facts agreed
 with the user. Business and Operating Context are separate. Let the server decide readiness; initial
 setup is optional and journey completion is explicit. A context save never authorizes starting agents,

package/skills/ciphrix/references/commands.md

@@ -34,6 +34,7 @@ Commands:
   risk                   Manage risks
   check                  Monitoring checks
   job                    Check background jobs started by other commands
+  user                   Active tenant-user discovery; no account administration
   access                 Access inventory, reviewed imports and assigned
                          reviewer workflows
   agent                  Agent activity, complete proposals and explicit human
@@ -1143,6 +1144,16 @@ Commands:
   submit [options] <document>    Submit a draft document for review
   approve [options] <document>   Approve a document awaiting approval
   delete [options] <document>    Delete a document
+  workflow                       Configure workflow or explicitly return to
+                                 draft
+  reviewer                       Configure the review recipient; recall sent
+                                 requests first
+  approver                       Configure the approval recipient; recall sent
+                                 requests first
+  review                         Explicit review decisions and request recall;
+                                 send with document submit
+  approval                       Approval requests, explicit decisions and
+                                 recall; ordinary decision with document approve
   help [command]                 display help for command
 ```
 
@@ -1312,6 +1323,379 @@ Options:
 
 **Effect:** Deletes a document; the CLI asks for confirmation when required.
 
+## `ciphrix document workflow`
+
+```text
+Usage: ciphrix document workflow [options] [command]
+
+Configure workflow or explicitly return to draft
+
+Options:
+  -h, --help                            display help for command
+
+Commands:
+  set [options] <document>              Set workflow type in draft.
+  return-to-draft [options] <document>  Return eligible advanced approval-stage
+                                        document to draft; clears assignments.
+  help [command]                        display help for command
+```
+
+## `ciphrix document workflow set`
+
+```text
+Usage: ciphrix document workflow set [options] <document>
+
+Set workflow type in draft.
+
+Options:
+  --type <value>           workflow type: simple or advanced
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document workflow return-to-draft`
+
+```text
+Usage: ciphrix document workflow return-to-draft [options] <document>
+
+Return eligible advanced approval-stage document to draft; clears assignments.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document reviewer`
+
+```text
+Usage: ciphrix document reviewer [options] [command]
+
+Configure the review recipient; recall sent requests first
+
+Options:
+  -h, --help                   display help for command
+
+Commands:
+  set [options] <document>     Set reviewer; sent requests must be recalled
+                               first.
+  remove [options] <document>  Remove the reviewer from a draft.
+  help [command]               display help for command
+```
+
+## `ciphrix document reviewer set`
+
+```text
+Usage: ciphrix document reviewer set [options] <document>
+
+Set reviewer; sent requests must be recalled first.
+
+Options:
+  --user <value>           exact active user email or User ID; employees may be
+                           assigned
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document reviewer remove`
+
+```text
+Usage: ciphrix document reviewer remove [options] <document>
+
+Remove the reviewer from a draft.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document approver`
+
+```text
+Usage: ciphrix document approver [options] [command]
+
+Configure the approval recipient; recall sent requests first
+
+Options:
+  -h, --help                   display help for command
+
+Commands:
+  set [options] <document>     Set approver; sent requests must be recalled
+                               first.
+  remove [options] <document>  Remove approver; sent requests must be recalled
+                               first.
+  help [command]               display help for command
+```
+
+## `ciphrix document approver set`
+
+```text
+Usage: ciphrix document approver set [options] <document>
+
+Set approver; sent requests must be recalled first.
+
+Options:
+  --user <value>           exact active user email or User ID; employees may be
+                           assigned
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document approver remove`
+
+```text
+Usage: ciphrix document approver remove [options] <document>
+
+Remove approver; sent requests must be recalled first.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document review`
+
+```text
+Usage: ciphrix document review [options] [command]
+
+Explicit review decisions and request recall; send with document submit
+
+Options:
+  -h, --help                      display help for command
+
+Commands:
+  complete [options] <document>   Record an explicitly authorized review
+                                  decision; does not send approval.
+  send-back [options] <document>  Record an explicit negative review decision;
+                                  clears reviewer.
+  cancel [options] <document>     Recall review request; clears reviewer.
+                                  Configure and resend separately.
+  help [command]                  display help for command
+```
+
+## `ciphrix document review complete`
+
+```text
+Usage: ciphrix document review complete [options] <document>
+
+Record an explicitly authorized review decision; does not send approval.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document review send-back`
+
+```text
+Usage: ciphrix document review send-back [options] <document>
+
+Record an explicit negative review decision; clears reviewer.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document review cancel`
+
+```text
+Usage: ciphrix document review cancel [options] <document>
+
+Recall review request; clears reviewer. Configure and resend separately.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document approval`
+
+```text
+Usage: ciphrix document approval [options] [command]
+
+Approval requests, explicit decisions and recall; ordinary decision with
+document approve
+
+Options:
+  -h, --help                         display help for command
+
+Commands:
+  send [options] <document>          Send for approval after review; never
+                                     completes review implicitly.
+  send-back [options] <document>     Record an explicit negative approval
+                                     decision; clears approver.
+  cancel [options] <document>        Recall approval request; clears approver.
+                                     Configure and resend separately.
+  self-approve [options] <document>  Explicit self-approval, separate from
+                                     ordinary approve; no review bypass.
+  help [command]                     display help for command
+```
+
+## `ciphrix document approval send`
+
+```text
+Usage: ciphrix document approval send [options] <document>
+
+Send for approval after review; never completes review implicitly.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document approval send-back`
+
+```text
+Usage: ciphrix document approval send-back [options] <document>
+
+Record an explicit negative approval decision; clears approver.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document approval cancel`
+
+```text
+Usage: ciphrix document approval cancel [options] <document>
+
+Recall approval request; clears approver. Configure and resend separately.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
+## `ciphrix document approval self-approve`
+
+```text
+Usage: ciphrix document approval self-approve [options] <document>
+
+Explicit self-approval, separate from ordinary approve; no review bypass.
+
+Options:
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
 ## `ciphrix risk`
 
 ```text
@@ -1701,6 +2085,47 @@ Options:
   -h, --help       display help for command
 ```
 
+## `ciphrix user`
+
+```text
+Usage: ciphrix user [options] [command]
+
+Active tenant-user discovery; no account administration
+
+Options:
+  -h, --help      display help for command
+
+Commands:
+  list [options]  List active tenant users, including employees; discovery does
+                  not change accounts.
+  help [command]  display help for command
+```
+
+## `ciphrix user list`
+
+```text
+Usage: ciphrix user list [options]
+
+List active tenant users, including employees; discovery does not change
+accounts.
+
+Options:
+  --search <value>         optional name/email search, at least three characters
+  --page <value>           page number starting at 1
+  --limit <value>          page size; server limits apply
+  --api-url <url>          override the API base URL
+  --json                   emit one complete result/error envelope
+  --yes                    confirmed writes only: explicitly authorize without
+                           prompting; rejected on reads/immediate writes
+  --idempotency-key <key>  writes only: key for one logical operation; reuse
+                           identical input, at most 256 characters
+  -h, --help               display help for command
+
+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.
+```
+
+**Effect:** Write controls apply only when advertised by the server: reads reject them, immediate writes do not accept --yes, and confirmed writes require valid explicit consent. Inspect uncertain outcomes rather than bypassing them with a new key.
+
 ## `ciphrix access`
 
 ```text

package/skills/ciphrix/references/document-workflows.md

@@ -0,0 +1,62 @@
+# Document workflows
+
+Use this guide when configuring document review/approval, selecting recipients, recovering a sent
+request or interpreting a workflow result. Installed command help is authoritative for exact options;
+the [generated command reference](commands.md) covers the complete command tree.
+
+## Read, configure, send, decide
+
+1. Read the document with `document get --json`. Resolve the intended name, code or ID before writing.
+   Workflow readiness describes business state; the server still decides permissions and validates
+   prerequisites at execution time.
+2. Configure the workflow in draft. Simple supports explicit self-approval; Advanced requires review
+   before approval. An approved document needs a new version before editing.
+3. Assign recipients using exact active User email or User ID. `user list` supports name/email search
+   and pagination; search needs at least three characters. Resolve ambiguous matches with the user.
+   People IDs, fuzzy names and invitation requests are not recipient selectors.
+4. Send review with `document submit`. Completing review is a separate formal human decision; it
+   advances to approval-not-sent without sending approval. A request to send approval does not authorize
+   completing review on the user's behalf.
+5. Explicitly request approval with `document approval send`. Ordinary approval uses `document approve`;
+   `document approval self-approve` is a distinct human decision and never bypasses Advanced review.
+
+Admins and InfoSec leads have tool access. Active employees may receive assignments and complete
+review/approval in the app; listing or assigning a user does not grant them tool access. Decisions
+record the authenticated caller, not an impersonated assignee.
+
+## Recover a sent request
+
+A sent-recipient setter refuses both a different person and the same person. Explain the current
+stage and ask whether the user wants an explicit recall → configure → resend sequence:
+
+| Current request | Recall                     | Configure after recall  | Resend                   |
+| --------------- | -------------------------- | ----------------------- | ------------------------ |
+| Review sent     | `document review cancel`   | `document reviewer set` | `document submit`        |
+| Approval sent   | `document approval cancel` | `document approver set` | `document approval send` |
+
+Recall clears the affected recipient; configure that person again even if unchanged. Removing an
+already-cleared assignment is not a recovery step. In supported unsent states, setting the same
+recipient succeeds without a change.
+
+Read current state between steps. Each step has independent authorization, confirmation where required
+and its own write key. Stop on an error or uncertain result; the sequence is not atomic. Send-back is
+a negative human decision, not a synonym for recall. Return-to-draft is available only in the supported
+Advanced approval-not-sent/rejected stages and clears assignments and decision attribution.
+
+## Confirmation, retries and results
+
+- Configuration, recipient removal, recall and return-to-draft use confirmed writes. New commands in
+  JSON/noninteractive mode require `--yes`; supply it only for an already authorized change.
+- New send/decision commands apply immediately, still require human authorization, and reject `--yes`.
+  Existing `document submit` and `document approve` retain their advertised options and successful JSON;
+  there are no alternate submit/approve spellings. Check each command's help.
+- New write commands accept `--idempotency-key` for one logical operation. Reuse the same key and input
+  for retries. Confirmed replay also requires valid confirmation: a fresh CLI invocation preflights
+  again and can be refused after state changes or expiry. Never use a new key to bypass uncertainty.
+- New commands return full envelopes with `--json`, preserving structured errors, warnings and
+  pagination. Existing submit success reports `data.status: submitted`, not a current raw workflow
+  state. A fresh document read gives current state; a replay returns the original result snapshot.
+- Success records the committed/queued outcome. It is not evidence that an email arrived, a recipient
+  acted, or the document was published. Report these outcomes separately.
+
+For general operating principles, return to [the Ciphrix skill](../SKILL.md).