@ciphrix/cli 0.1.0 → 0.2.0

package/dist/commands/framework.js

@@ -1,4 +1,4 @@
-import { writeLine, writeNextHint, writeTable } from '../io.js';
+import { writeLine, writeNextHint, writePageFooter, writeTable } from '../io.js';
 import { asRecord, callTool, errorMessage, resolveToolContext, asText } from '../toolSurface.js';
 const text = (value, fallback = '-') => typeof value === 'string' ? value : typeof value === 'number' ? String(value) : fallback;
 export const frameworkListCommand = async ({ io, apiUrl, json = false, credentialStore, }) => {
@@ -34,7 +34,8 @@ export const frameworkListCommand = async ({ io, apiUrl, json = false, credentia
         writeLine(io.stdout, `${io.theme.dim(`Available to add (${available.length}):`)}`);
         for (const framework of available) {
             const record = asRecord(framework);
-            writeLine(io.stdout, `  ${text(record.frameworkName ?? record.name)}`);
+            const code = asText(record.frameworkCode ?? record.code);
+            writeLine(io.stdout, `  ${code ? `${code} — ` : ''}${text(record.frameworkName ?? record.name)}`);
         }
     }
 };
@@ -118,11 +119,15 @@ export const clauseItemsCommand = async ({ io, framework, clause, apiUrl, json =
         return [text(record.name, text(record.id)), text(record.itemType ?? record.type)];
     }));
 };
-export const clauseAvailableItemsCommand = async ({ io, framework, clause, itemType, apiUrl, json = false, credentialStore, search, }) => {
+export const clauseAvailableItemsCommand = async ({ io, framework, clause, itemType, apiUrl, json = false, credentialStore, search, page, limit, }) => {
     const ctx = await resolveToolContext(apiUrl, credentialStore);
     const input = { framework, clause, itemType };
     if (search)
         input.search = search;
+    if (page)
+        input.page = page;
+    if (limit)
+        input.limit = limit;
     const envelope = await callTool(ctx, 'list_clause_items_available', input);
     if (envelope.status !== 'ok')
         throw new Error(errorMessage(envelope, 'Could not read available items.'));
@@ -130,13 +135,24 @@ export const clauseAvailableItemsCommand = async ({ io, framework, clause, itemT
         writeLine(io.stdout, JSON.stringify(envelope.data, null, 2));
         return;
     }
-    const items = asRecord(envelope.data).items;
+    const data = asRecord(envelope.data);
+    const items = data.items;
     const list = Array.isArray(items) ? items : [];
     writeLine(io.stdout, `${io.theme.bold(`Available ${itemType}s`)} ${io.theme.dim(`(${list.length})`)}`);
     for (const item of list) {
         const record = asRecord(item);
         writeLine(io.stdout, `  ${text(record.name, text(record.id))}`);
     }
+    const total = typeof data.total === 'number' ? data.total : list.length;
+    const currentPage = typeof data.page === 'number' ? data.page : 1;
+    const pageSize = typeof data.limit === 'number' ? data.limit : 25;
+    writePageFooter(io, {
+        shown: list.length,
+        total,
+        page: currentPage,
+        limit: pageSize,
+        hasMore: data.hasMore === true || currentPage * pageSize < total,
+    });
 };
 export const clauseUpdateCommand = async ({ io, framework, clause, changes, apiUrl, json = false, yes = false, credentialStore, }) => {
     const { applyTool } = await import('../actions.js');

package/dist/commands/policy.js

@@ -20,7 +20,7 @@ export const policyListCommand = async ({ io, apiUrl, json = false, name, status
     if (envelope.status !== 'ok')
         throw new Error(errorMessage(envelope, 'Could not list documents.'));
     if (json) {
-        writeLine(io.stdout, JSON.stringify(envelope, null, 2));
+        writeLine(io.stdout, JSON.stringify(envelope.data, null, 2));
         return;
     }
     const data = asRecord(envelope.data);

package/dist/commands/test.d.ts

@@ -29,8 +29,8 @@ export declare const testRunCreateCommand: ({ io, name, apiUrl, json, credential
     runAt?: string | undefined;
 }) => Promise<void>;
 export declare const testRunResultCommand: ({ io, name, runId, apiUrl, json, credentialStore, status, note, }: TestReadOptions & {
-    status: string;
-    note?: string | undefined;
+    status?: string | undefined;
+    note?: string | null | undefined;
 }) => Promise<void>;
 export declare const testRunDeleteCommand: ({ io, name, runId, apiUrl, json, yes, confirm, credentialStore, }: TestActionOptions) => Promise<void>;
 export interface TestAttachOptions extends TestReadOptions {
@@ -41,9 +41,11 @@ export interface TestAttachOptions extends TestReadOptions {
     unlink?: boolean | undefined;
 }
 export declare const testAttachCommand: ({ io, name, runId, apiUrl, json, credentialStore, itemType, itemId, uploadIds, file, unlink, }: TestAttachOptions) => Promise<void>;
-export declare const testAvailableItemsCommand: ({ io, name, runId, itemType, apiUrl, json, credentialStore, search, }: TestReadOptions & {
+export declare const testAvailableItemsCommand: ({ io, name, runId, itemType, apiUrl, json, credentialStore, search, page, limit, }: TestReadOptions & {
     itemType: string;
     search?: string | undefined;
+    page?: number | undefined;
+    limit?: number | undefined;
 }) => Promise<void>;
 export declare const testLinksCommand: ({ io, name, apiUrl, json, credentialStore, }: TestReadOptions) => Promise<void>;
 export declare const testUpdateCommand: ({ io, name, apiUrl, json, yes, confirm, credentialStore, changes, }: TestReadOptions & {

package/dist/commands/test.js

@@ -113,6 +113,12 @@ const renderRuns = (io, runs, assurance) => {
             assuranceLabel(assurance[text(record.id)]),
         ];
     }));
+    for (const run of runs) {
+        const record = asRecord(run);
+        if (typeof record.note === 'string' && record.note.trim() !== '') {
+            writeLine(io.stdout, `Note (${text(record.id)}): ${record.note}`);
+        }
+    }
 };
 const assuranceLabel = (assessment) => assessmentLabel(assessment);
 export const testItemsCommand = async ({ io, name, runId, apiUrl, json = false, credentialStore, }) => {
@@ -162,11 +168,15 @@ export const testRunCreateCommand = async ({ io, name, apiUrl, json = false, cre
         writeLine(io.stdout, `${io.theme.green('✓')} run created: ${text(asRecord(result.data).runId)}`);
 };
 export const testRunResultCommand = async ({ io, name, runId, apiUrl, json = false, credentialStore, status, note, }) => {
+    if (status === undefined && note === undefined)
+        throw new Error('Provide --status, --note or --clear-note.');
     const ctx = await resolveToolContext(apiUrl, credentialStore);
-    const input = { name, status };
+    const input = { name };
+    if (status !== undefined)
+        input.status = status;
     if (runId)
         input.runId = runId;
-    if (note)
+    if (note !== undefined)
         input.note = note;
     const result = await applyTool({
         ctx,
@@ -180,7 +190,12 @@ export const testRunResultCommand = async ({ io, name, runId, apiUrl, json = fal
     if (json)
         writeLine(io.stdout, JSON.stringify(result.data, null, 2));
     else
-        writeLine(io.stdout, `${io.theme.green('✓')} run result: ${status}`);
+        writeLine(io.stdout, status === undefined
+            ? 'Run note updated; result unchanged.'
+            : `${io.theme.green('✓')} run result: ${status}`);
+    const jobId = asText(asRecord(result.meta).aiTaskId);
+    if (!json && jobId)
+        writeNextHint(io, `ciphrix job status ${jobId}`);
 };
 export const testRunDeleteCommand = async ({ io, name, runId, apiUrl, json = false, yes = false, confirm, credentialStore, }) => {
     if (!runId)
@@ -235,13 +250,17 @@ export const testAttachCommand = async ({ io, name, runId, apiUrl, json = false,
     const job = asText(data.aiTaskId);
     writeLine(io.stdout, `${io.theme.green('✓')} ${unlink ? 'unlinked' : 'linked'} ${resolvedItemType} on run ${text(data.runId)}${job ? io.theme.dim(` · job ${job}`) : ''}`);
 };
-export const testAvailableItemsCommand = async ({ io, name, runId, itemType, apiUrl, json = false, credentialStore, search, }) => {
+export const testAvailableItemsCommand = async ({ io, name, runId, itemType, apiUrl, json = false, credentialStore, search, page, limit, }) => {
     const ctx = await resolveToolContext(apiUrl, credentialStore);
     const input = { name, itemType };
     if (runId)
         input.runId = runId;
     if (search)
         input.search = search;
+    if (page)
+        input.page = page;
+    if (limit)
+        input.limit = limit;
     const envelope = await callTool(ctx, 'list_test_items_available', input);
     if (envelope.status !== 'ok')
         throw new Error(errorMessage(envelope, 'Could not read available items.'));
@@ -264,6 +283,16 @@ export const testAvailableItemsCommand = async ({ io, name, runId, itemType, api
             text(record.status),
         ];
     }));
+    const total = typeof data.total === 'number' ? data.total : items.length;
+    const currentPage = typeof data.page === 'number' ? data.page : 1;
+    const pageSize = typeof data.limit === 'number' ? data.limit : 25;
+    writePageFooter(io, {
+        shown: items.length,
+        total,
+        page: currentPage,
+        limit: pageSize,
+        hasMore: data.hasMore === true || currentPage * pageSize < total,
+    });
 };
 export const testLinksCommand = async ({ io, name, apiUrl, json = false, credentialStore, }) => {
     const ctx = await resolveToolContext(apiUrl, credentialStore);

package/dist/commands/vendor.d.ts

@@ -22,10 +22,13 @@ export declare const vendorListCommand: ({ io, apiUrl, json, credentialStore, na
     limit?: number | undefined;
 }) => Promise<void>;
 export declare const vendorGetCommand: ({ io, name, apiUrl, json, credentialStore, }: VendorReadOptions) => Promise<void>;
-export declare const vendorCreateCommand: ({ io, apiUrl, json, credentialStore, name, category, criticality, description, }: VendorCommonOptions & {
+export declare const vendorCreateCommand: ({ io, apiUrl, json, credentialStore, name, category, subcategory, criticality, dataSensitivity, serviceAvailability, description, }: VendorCommonOptions & {
     name: string;
     category?: string | undefined;
+    subcategory?: string | undefined;
     criticality?: string | undefined;
+    dataSensitivity?: string | undefined;
+    serviceAvailability?: string | undefined;
     description?: string | undefined;
 }) => Promise<void>;
 export interface VendorUpdateOptions extends VendorReadOptions {

package/dist/commands/vendor.js

@@ -78,13 +78,19 @@ export const vendorGetCommand = async ({ io, name, apiUrl, json = false, credent
         writeLine(io.stdout, `  ${io.theme.dim(`${label}:`)} ${text(value)}`);
     }
 };
-export const vendorCreateCommand = async ({ io, apiUrl, json = false, credentialStore, name, category, criticality, description, }) => {
+export const vendorCreateCommand = async ({ io, apiUrl, json = false, credentialStore, name, category, subcategory, criticality, dataSensitivity, serviceAvailability, description, }) => {
     const ctx = await resolveToolContext(apiUrl, credentialStore);
     const input = { name };
     if (category)
         input.category = category;
+    if (subcategory)
+        input.subcategory = subcategory;
     if (criticality)
         input.criticality = criticality;
+    if (dataSensitivity)
+        input.dataSensitivity = dataSensitivity;
+    if (serviceAvailability)
+        input.serviceAvailability = serviceAvailability;
     if (description)
         input.description = description;
     const result = await applyTool({

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.1.0";
+export declare const CLI_VERSION = "0.2.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.1.0';
+export const CLI_VERSION = '0.2.0';

package/dist/manifest.d.ts

@@ -0,0 +1,19 @@
+import type { ToolContext } from './toolSurface.js';
+export interface ToolDescriptor {
+    name: string;
+    version: number;
+    description: string;
+    effect: 'read' | 'write' | 'destructive';
+    confirmation: 'none' | 'preflight_confirm';
+    inputSchema: Record<string, unknown>;
+    cli?: {
+        group: string[];
+        operation: string;
+    };
+    limits?: Record<string, unknown>;
+}
+export declare class ManifestError extends Error {
+}
+export declare const getManifest: (ctx: ToolContext) => Promise<ToolDescriptor[]>;
+export declare const getTool: (ctx: ToolContext, name: string) => Promise<ToolDescriptor>;
+export declare const resolveBinding: (ctx: ToolContext, group: string[], operation: string) => Promise<ToolDescriptor>;

package/dist/manifest.js

@@ -0,0 +1,93 @@
+export class ManifestError extends Error {
+}
+const cache = new WeakMap();
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+const checkSchema = (value, depth = 0, budget = { properties: 0 }) => {
+    if (depth > 32)
+        throw new ManifestError('Tool schema exceeds the supported nesting limit.');
+    if (Array.isArray(value)) {
+        for (const child of value)
+            checkSchema(child, depth + 1, budget);
+    }
+    else if (value && typeof value === 'object') {
+        const schema = record(value);
+        budget.properties += Object.keys(record(schema.properties)).length;
+        if (budget.properties > 1000)
+            throw new ManifestError('Tool schema exceeds the supported property limit.');
+        for (const child of Object.values(schema))
+            checkSchema(child, depth + 1, budget);
+    }
+};
+export const getManifest = (ctx) => {
+    const previous = cache.get(ctx);
+    if (previous?.baseUrl === ctx.baseUrl && previous.token === ctx.token)
+        return previous.manifest;
+    const loaded = (async () => {
+        const body = record(await ctx.client.request('/tools/v1', { token: ctx.token }));
+        if (body.manifestVersion !== 1 ||
+            body.apiVersion !== 'v1' ||
+            !Array.isArray(body.tools) ||
+            body.tools.length > 1024) {
+            throw new ManifestError('Unsupported tool manifest. Update the client or contact your administrator.');
+        }
+        const names = new Set();
+        const bindings = new Set();
+        return body.tools.map((value) => {
+            const tool = record(value);
+            if (typeof tool.name !== 'string' ||
+                !/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/.test(tool.name) ||
+                !Number.isInteger(tool.version) ||
+                Number(tool.version) < 1 ||
+                !['read', 'write', 'destructive'].includes(String(tool.effect)) ||
+                !['none', 'preflight_confirm'].includes(String(tool.confirmation)) ||
+                typeof tool.description !== 'string' ||
+                !tool.inputSchema ||
+                typeof tool.inputSchema !== 'object' ||
+                Array.isArray(tool.inputSchema) ||
+                names.has(tool.name))
+                throw new ManifestError('Invalid or unsupported tool descriptor.');
+            names.add(tool.name);
+            checkSchema(tool.inputSchema);
+            if (tool.cli !== undefined) {
+                const binding = record(tool.cli);
+                const segment = (part) => typeof part === 'string' &&
+                    part.length <= 64 &&
+                    /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(part);
+                if (!Array.isArray(binding.group) ||
+                    binding.group.length < 1 ||
+                    binding.group.length > 6 ||
+                    !binding.group.every(segment) ||
+                    !segment(binding.operation))
+                    throw new ManifestError('Invalid command binding.');
+                const key = JSON.stringify([binding.group, binding.operation]);
+                if (tool.version === 1 && bindings.has(key))
+                    throw new ManifestError('Ambiguous command binding in tool manifest.');
+                if (tool.version === 1)
+                    bindings.add(key);
+            }
+            return tool;
+        });
+    })();
+    cache.set(ctx, { baseUrl: ctx.baseUrl, token: ctx.token, manifest: loaded });
+    return loaded;
+};
+export const getTool = async (ctx, name) => {
+    const tool = (await getManifest(ctx)).find((candidate) => candidate.name === name);
+    if (!tool)
+        throw new ManifestError('This operation is not available in the current tool manifest.');
+    if (tool.version !== 1)
+        throw new ManifestError('This operation version is not supported. Update the CLI.');
+    if (tool.effect === 'destructive')
+        throw new ManifestError('This operation is not available through tools.');
+    return tool;
+};
+export const resolveBinding = async (ctx, group, operation) => {
+    const matches = (await getManifest(ctx)).filter((candidate) => candidate.cli?.operation === operation &&
+        JSON.stringify(candidate.cli.group) === JSON.stringify(group));
+    const tool = matches.find((candidate) => candidate.version === 1) ?? matches[0];
+    if (!tool)
+        throw new ManifestError('This command is not supported by the current tool manifest. Update the server or check available capabilities.');
+    return getTool(ctx, tool.name);
+};

package/dist/toolSurface.js

@@ -1,6 +1,7 @@
 import { createApiClient } from './api.js';
 import { resolveApiBaseUrl } from './config.js';
 import { createCredentialStore } from './credentials.js';
+import { getTool } from './manifest.js';
 export const asRecord = (value) => value && typeof value === 'object' ? value : {};
 export const asText = (value, fallback = '') => typeof value === 'string' ? value : fallback;
 /**
@@ -35,7 +36,15 @@ export const resolveToolContext = async (apiUrl, store) => {
     return { baseUrl, client: createApiClient(baseUrl), token: credential.token };
 };
 export const callTool = async (ctx, toolName, input, options = {}) => {
-    const body = { input };
+    const tool = await getTool(ctx, toolName);
+    if (tool.effect !== 'read' && !options.idempotencyKey) {
+        throw new Error(`Refusing to call the write tool '${toolName}' without an idempotency key. Use applyTool.`);
+    }
+    if (options.idempotencyKey !== undefined &&
+        (!options.idempotencyKey.trim() || options.idempotencyKey.length > 256)) {
+        throw new Error('The idempotency key must contain 1 to 256 characters.');
+    }
+    const body = { input, version: tool.version };
     if (options.confirmationToken)
         body.confirmationToken = options.confirmationToken;
     if (options.idempotencyKey)

package/dist/upload.d.ts

@@ -1,16 +1,26 @@
+import { type ToolDescriptor } from './manifest.js';
 import { type ToolContext } from './toolSurface.js';
-/** Maximum evidence file size read and staged by the CLI (50 MiB). */
+/** Maximum evidence file size read and staged by the CLI (25 MiB, matching the tool surface). */
 export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
 export interface UploadLimits {
     maxUploadBytes?: number;
     timeoutMs?: number;
     maxResponseBytes?: number;
 }
+export declare class FileInputError extends Error {
+}
+export declare const readUploadFile: (filePath: string, maxBytes: number) => Promise<Buffer>;
 /**
  * Stages a local file through the `upload_file` tool and returns its upload id, ready to be attached
  * to a target (a test run, a risk, a vendor). The file is sent as multipart to the tool surface with
  * the bearer credential, so no cookie or CSRF token is involved.
  */
+export declare const stageLocalFile: (ctx: ToolContext, filePath: string, purpose: string, limits?: UploadLimits, descriptor?: ToolDescriptor, idempotencyKey?: string) => Promise<{
+    id: string;
+    filename: string;
+    size: number;
+    envelope: Record<string, unknown>;
+}>;
 export declare const uploadLocalFile: (ctx: ToolContext, filePath: string, purpose: string, limits?: UploadLimits) => Promise<{
     id: string;
     filename: string;

package/dist/upload.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { getTool, ManifestError } from './manifest.js';
 import { constants } from 'node:fs';
 import { lstat, open } from 'node:fs/promises';
 import { basename } from 'node:path';
@@ -19,15 +20,17 @@ const MIME_TYPES = {
     '.xls': 'application/vnd.ms-excel',
     '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
 };
-/** Maximum evidence file size read and staged by the CLI (50 MiB). */
-export const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
-const readUploadFile = async (filePath, maxBytes) => {
+/** Maximum evidence file size read and staged by the CLI (25 MiB, matching the tool surface). */
+export const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+export class FileInputError extends Error {
+}
+export const readUploadFile = async (filePath, maxBytes) => {
     const initialStat = await lstat(filePath);
     if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
-        throw new Error('Upload path must be a regular file, not a symlink or special file.');
+        throw new FileInputError('Upload path must be a regular file, not a symlink or special file.');
     }
     if (initialStat.size > maxBytes) {
-        throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+        throw new FileInputError(`Upload exceeds the ${maxBytes}-byte file size limit.`);
     }
     const noFollow = constants.O_NOFOLLOW ?? 0;
     const file = await open(filePath, constants.O_RDONLY | noFollow);
@@ -36,24 +39,24 @@ const readUploadFile = async (filePath, maxBytes) => {
         if (!openedStat.isFile() ||
             openedStat.dev !== initialStat.dev ||
             openedStat.ino !== initialStat.ino) {
-            throw new Error('Upload path changed while it was being opened. Please retry.');
+            throw new FileInputError('Upload path changed while it was being opened. Please retry.');
         }
         if (openedStat.size > maxBytes) {
-            throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+            throw new FileInputError(`Upload exceeds the ${maxBytes}-byte file size limit.`);
         }
         const chunks = [];
         let total = 0;
         while (true) {
             const remaining = maxBytes + 1 - total;
             if (remaining <= 0)
-                throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+                throw new FileInputError(`Upload exceeds the ${maxBytes}-byte file size limit.`);
             const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
             const { bytesRead } = await file.read(chunk, 0, chunk.length, null);
             if (bytesRead === 0)
                 break;
             total += bytesRead;
             if (total > maxBytes)
-                throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+                throw new FileInputError(`Upload exceeds the ${maxBytes}-byte file size limit.`);
             chunks.push(chunk.subarray(0, bytesRead));
         }
         return Buffer.concat(chunks, total);
@@ -72,16 +75,26 @@ const contentTypeFor = (filename) => {
  * to a target (a test run, a risk, a vendor). The file is sent as multipart to the tool surface with
  * the bearer credential, so no cookie or CSRF token is involved.
  */
-export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
+export const stageLocalFile = async (ctx, filePath, purpose, limits = {}, descriptor, idempotencyKey = randomUUID()) => {
+    const tool = descriptor ?? (await getTool(ctx, 'upload_file'));
+    if (tool.effect !== 'write' || tool.confirmation !== 'none') {
+        throw new ManifestError('The server does not support immediate file staging.');
+    }
+    const properties = asRecord(tool.inputSchema.properties);
+    const purposes = asRecord(properties.purpose).enum;
+    if (!Array.isArray(purposes) || !purposes.includes(purpose))
+        throw new Error('Unsupported upload purpose.');
+    if (!idempotencyKey.trim() || idempotencyKey.length > 256)
+        throw new Error('The idempotency key must contain 1 to 256 characters.');
     const filename = basename(filePath);
     const contents = await readUploadFile(filePath, limits.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES);
     const form = new FormData();
     form.append('purpose', purpose);
     form.append('file', new Blob([new Uint8Array(contents)], { type: contentTypeFor(filename) }), filename);
     return withRequestTimeout(limits.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, async (signal) => {
-        const response = await fetchWithoutRedirects(`${ctx.baseUrl}/tools/v1/upload_file`, {
+        const response = await fetchWithoutRedirects(`${ctx.baseUrl}/tools/v1/${encodeURIComponent(tool.name)}`, {
             method: 'POST',
-            headers: { authorization: `Bearer ${ctx.token}`, 'idempotency-key': randomUUID() },
+            headers: { authorization: `Bearer ${ctx.token}`, 'idempotency-key': idempotencyKey },
             body: form,
             signal,
         });
@@ -100,7 +113,9 @@ export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
             const message = typeof asRecord(envelope.error).message === 'string'
                 ? asRecord(envelope.error).message
                 : `Upload failed with status ${response.status}`;
-            throw new ApiError(message, response.status);
+            throw new ApiError(message, response.status, typeof asRecord(envelope.error).code === 'string'
+                ? String(asRecord(envelope.error).code)
+                : undefined, asRecord(envelope.error).details, envelope);
         }
         const payload = asRecord(envelope.data);
         const id = typeof payload.uploadId === 'string' ? payload.uploadId : null;
@@ -108,8 +123,13 @@ export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
             throw new ApiError('Upload did not return an id', 502);
         return {
             id,
+            envelope,
             filename: typeof payload.filename === 'string' ? payload.filename : filename,
             size: typeof payload.size === 'number' ? payload.size : contents.length,
         };
     });
 };
+export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
+    const { id, filename, size } = await stageLocalFile(ctx, filePath, purpose, limits);
+    return { id, filename, size };
+};

package/package.json

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

package/skills/ciphrix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ciphrix
-description: Operate a Ciphrix compliance programme with the `ciphrix` CLI. Use when an agent needs to understand or change a tenant's business context, documents, frameworks, controls, tests and evidence, risks, vendors, assets, monitoring checks, or background jobs.
+description: Operate a Ciphrix compliance programme with the `ciphrix` CLI. Use for onboarding and organizational context, documents, frameworks, controls, tests and evidence, access reviews and imports, agent findings, assigned tasks, risks, vendors, assets, monitoring checks, or background jobs.
 ---
 
 # Ciphrix
@@ -140,6 +140,31 @@ are what a check raised. `check disable` silences a check for the tenant — rec
 
 ## Guardrails
 
+**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,
+initializing a framework or completing onboarding. Replayed packs are snapshots: read status again for
+current readiness.
+
+**Access reviews and proposals.** Inventory is not a review decision. Inspect proposal rows, matches,
+source evidence and current revisions before selecting a merge. Never manufacture person-match or
+visual-evidence confirmation. Keep/revoke decisions, reviewer-task completion and campaign ending are
+distinct human intents. A revoke decision is a removal request, not provider-side revocation. Agent
+findings/options and AI assessments are advisory; inspect the complete current proposal and exact
+declared option before any explicit decision. Assigned-task discovery grants no completion authority.
+
+**Writes and uncertainty.** Discover capabilities through the server, use the exact reviewed inputs,
+and treat confirmation as explicit delegated consent, not an obstacle to automate around. Retain one
+idempotency key per logical operation; never retry unknown outcomes with a new key. The CLI performs no
+automatic write retries and does not promise confirmed recovery across invocations or expired tokens.
+Inspect state/jobs when uncertain. Batch results can partially apply; preserve and report failures.
+Advisory assessments never authorize a formal passing result.
+
+**Files.** Stage and process only the files the user selected. General processing may update context
+or create vendor records; staging alone does not authorize that processing. Imports are proposed work,
+not merged inventory. Temporary evidence/export references expire; do not forward credentials to them,
+claim bytes were downloaded when only a reference was returned, or treat a replayed URL as renewed.
+
 - Work only in the tenant and API environment the authenticated user selected. Never discover or switch
   tenants, endpoints or credential stores by guessing.
 - Do not expose access tokens, stored credentials or sensitive response data in prose, logs or commands.