@notis_ai/cli 0.2.18 → 0.2.19

package/src/command-specs/agents.js

@@ -1,7 +1,11 @@
 import { createHash } from 'node:crypto';
-import { basename } from 'node:path';
+import { basename, isAbsolute } from 'node:path';
 
-import { installAgentSetup, shouldInstallLocalAgentSetup } from '../runtime/agent-setup.js';
+import {
+  installAgentSetup,
+  installRecallOnlyAgentHooks,
+  shouldInstallLocalAgentSetup,
+} from '../runtime/agent-setup.js';
 import {
   completePendingTurn,
   freshRecallItems,
@@ -42,7 +46,54 @@ export function installLocalAgentContext(
   });
 }
 
+/**
+ * Recall-only install for a hosted coding agent. The local guard against
+ * hosted environments does not apply: this mode is asked for explicitly, binds
+ * to the session's injected credential instead of a stored profile, and
+ * writes only into the agent's own config folder.
+ */
+export function installRecallOnlyAgentContext(ctx, env = process.env) {
+  const options = ctx.options || {};
+  if (options.memoryHooks === false) {
+    throw usageError('--recall-only installs memory hooks; it cannot be combined with --no-memory-hooks');
+  }
+  if (options.envFile !== undefined && (typeof options.envFile !== 'string' || !isAbsolute(options.envFile))) {
+    throw usageError('--env-file must be an absolute path');
+  }
+  const agents = selectedAgents(options);
+  if (ctx.runtime.credentialKind !== 'env' || !ctx.runtime.jwt) {
+    return agents.map((agent) => ({ agent, status: 'skipped_requires_session_credential' }));
+  }
+  return agents.map((agent) => {
+    const configDir = agent === 'codex' ? env.CODEX_HOME : env.CLAUDE_CONFIG_DIR;
+    if (typeof configDir !== 'string' || !isAbsolute(configDir)) {
+      return { agent, status: 'skipped_requires_agent_config_dir' };
+    }
+    return installRecallOnlyAgentHooks({ agentId: agent, configDir, envFile: options.envFile || null });
+  });
+}
+
 async function agentsInstallHandler(ctx) {
+  if (ctx.options?.recallOnly) {
+    const results = installRecallOnlyAgentContext(ctx);
+    const installed = results.filter((result) => result.mode === 'recall_only'
+      && result.memory_hook?.status !== 'error');
+    const hookErrors = results.filter((result) => result.memory_hook?.status === 'error');
+    return ctx.output.emitSuccess({
+      command: 'agents install',
+      data: { mode: 'recall_only', agents: results },
+      humanSummary: installed.length
+        ? `Installed recall-only Notis memory hooks for ${installed.length} coding agent${installed.length === 1 ? '' : 's'}.`
+        : 'Skipped recall-only coding-agent memory hooks.',
+      warnings: hookErrors.map((result) => result.memory_hook.message),
+      hints: [],
+      renderHuman: () => results.map((result) => (
+        result.mode === 'recall_only'
+          ? `${result.agent}: recall-only memory hook ${result.memory_hook?.status || 'skipped'}`
+          : `${result.agent}: ${result.status}`
+      )).join('\n'),
+    });
+  }
   const results = installLocalAgentContext(ctx);
   const hookErrors = results.filter((result) => result.memory_hook?.status === 'error');
   const configuredCount = results.filter((result) => result.instructions).length;
@@ -132,10 +183,12 @@ export function formatMemoryContext(data, { sessionStart = false } = {}) {
   return lines.join('\n');
 }
 
-function withFreshResults(input, data) {
+function withFreshResults(input, data, home) {
   const results = Array.isArray(data?.results) ? data.results : [];
   const texts = results.map(memoryText);
-  const freshTexts = new Set(freshRecallItems(input, texts.filter(Boolean)));
+  const freshTexts = new Set(home === undefined
+    ? freshRecallItems(input, texts.filter(Boolean))
+    : freshRecallItems(input, texts.filter(Boolean), home));
   const emitted = new Set();
   return {
     ...data,
@@ -148,6 +201,45 @@ function withFreshResults(input, data) {
   };
 }
 
+const WORKER_CONTEXT_PREFIX = 'Current worker context for this turn.';
+const INJECTED_BLOCK_PATTERN = /<(system_instruction|notis_[a-z_]+|delegated_provider|interaction_id|relevant_memory|instructions)>[\s\S]*?<\/\1>/g;
+
+function withoutInjectedBlocks(text) {
+  return text.replace(INJECTED_BLOCK_PATTERN, '\n');
+}
+
+/**
+ * The user's own request inside a delegated Notis turn. A hosted coding agent
+ * receives the Notis contract, earlier history, delivery receipts and a worker
+ * context snapshot in the same message; searching all of that would recall
+ * memories about the contract instead of the request. Each request follows its
+ * `<interaction_id>` tag and ends before the next tag or the worker context.
+ */
+export function delegatedRequestText(prompt) {
+  const text = typeof prompt === 'string' ? prompt : '';
+  const workerAt = text.indexOf(WORKER_CONTEXT_PREFIX);
+  const head = workerAt >= 0 ? text.slice(0, workerAt) : text;
+  const tagPattern = /<interaction_id>[\s\S]*?<\/interaction_id>/g;
+  const tags = [...head.matchAll(tagPattern)];
+  let request = '';
+  if (tags.length) {
+    request = tags.map((tag, index) => {
+      const start = tag.index + tag[0].length;
+      const end = index + 1 < tags.length ? tags[index + 1].index : head.length;
+      return withoutInjectedBlocks(head.slice(start, end)).trim();
+    }).filter(Boolean).join('\n');
+  } else {
+    request = withoutInjectedBlocks(text)
+      .replace(/Current worker context for this turn\.[^\n]*(?:\n\{[^\n]*\})?/g, '\n')
+      .trim();
+  }
+  if (!request) {
+    const goal = /<goal>([\s\S]*?)<\/goal>/.exec(text);
+    request = goal ? goal[1].trim() : '';
+  }
+  return request.replace(/\n{3,}/g, '\n\n').slice(0, 12000);
+}
+
 function memoryStateInput(input, runtime) {
   return {
     ...input,
@@ -166,7 +258,19 @@ export async function agentContextHandler(ctx, {
   // Hook failures are deliberately silent and fail-open. A temporary Notis
   // outage must not prevent the user's Codex or Claude prompt from running.
   try {
-    const input = await readInput();
+    const recallOnly = ctx.options?.recallOnly === true;
+    const stateDir = recallOnly && typeof ctx.options?.stateDir === 'string' && isAbsolute(ctx.options.stateDir)
+      ? ctx.options.stateDir
+      : undefined;
+    if (recallOnly) {
+      // Recall-only hooks never capture, so no turn is held for a Stop hook.
+      rememberPending = () => {};
+      clearPending = () => {};
+    }
+    const rawInput = await readInput();
+    const input = recallOnly && rawInput?.hook_event_name === 'UserPromptSubmit'
+      ? { ...rawInput, prompt: delegatedRequestText(rawInput.prompt) }
+      : rawInput;
     const stateInput = memoryStateInput(input, ctx.runtime);
     const event = input?.hook_event_name;
     if (!['SessionStart', 'UserPromptSubmit'].includes(event)) return 0;
@@ -194,7 +298,7 @@ export async function agentContextHandler(ctx, {
         include_profile: event === 'SessionStart',
       },
     });
-    const data = withFreshResults(stateInput, unwrapToolPayload(result.payload));
+    const data = withFreshResults(stateInput, unwrapToolPayload(result.payload), stateDir);
     const additionalContext = formatMemoryContext(data, { sessionStart: event === 'SessionStart' });
     if (!additionalContext) return 0;
     process.stdout.write(`${JSON.stringify({
@@ -333,13 +437,15 @@ export const agentsCommandSpecs = [
     command_path: ['agents', 'install'],
     summary: 'Install Notis instructions and recall/capture hooks for local Codex and Claude Code.',
     when_to_use:
-      'Run after login to give local coding agents durable Notis CLI guidance, session-start profile context, deduplicated relevant recall, and automatic completed-turn capture. Hosted Notis sandboxes already receive prompt context and are skipped.',
+      'Run after login to give local coding agents durable Notis CLI guidance, session-start profile context, deduplicated relevant recall, and automatic completed-turn capture. Hosted Notis sandboxes are skipped unless --recall-only is given: that mode installs only recall hooks into the hosted agent\'s own config folder, signed in with the session\'s injected credential.',
     args_schema: {
       arguments: [],
       options: [
         { flags: '--codex-only', description: 'Configure only Codex.' },
         { flags: '--claude-only', description: 'Configure only Claude Code.' },
         { flags: '--no-memory-hooks', description: 'Install static instructions and remove Notis recall/capture hooks.' },
+        { flags: '--recall-only', description: 'Hosted coding agents: install only recall hooks (no capture, no instructions) into CODEX_HOME or CLAUDE_CONFIG_DIR, signed in with the injected NOTIS_JWT.' },
+        { flags: '--env-file <path>', description: 'With --recall-only: a shell file each hook sources first to pick up the current injected sign-in.' },
       ],
     },
     examples: [
@@ -347,6 +453,7 @@ export const agentsCommandSpecs = [
       'notis agents install --codex-only',
       'notis agents install --claude-only',
       'notis agents install --no-memory-hooks',
+      'notis agents install --recall-only --codex-only',
     ],
     output_schema: 'Returns each configured agent, instruction file path/status, memory-hook file path/status, and profile binding.',
     mutates: true,
@@ -360,7 +467,13 @@ export const agentsCommandSpecs = [
     command_path: ['agent-context'],
     summary: 'Internal hook adapter that injects relevant Notis memory.',
     when_to_use: 'Called by installed Codex and Claude Code UserPromptSubmit hooks; not intended for direct use.',
-    args_schema: { arguments: [], options: [] },
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--recall-only', description: 'Hosted recall: search only the user request inside a delegated turn and never hold a turn for capture.' },
+        { flags: '--state-dir <dir>', description: 'Folder for per-session recall state instead of the home folder.' },
+      ],
+    },
     examples: [],
     output_schema: 'Emits vendor-compatible hook JSON with additionalContext, or no output when context is unavailable.',
     mutates: false,

package/src/command-specs/auth.js

@@ -108,7 +108,7 @@ export const authCommandSpecs = [
         { flags: '--mode <mode>', description: 'auto (default) hands the browser callback to a background listener when this command cannot wait; browser waits in-process; code shows a one-time code to copy.' },
         { flags: '--paste-code', description: 'Alias for --mode code.' },
         { flags: '--timeout-seconds <n>', description: 'Authorization lifetime in seconds (default 300 while waiting in a terminal; 1800 for detached or code hand-offs).' },
-        { flags: '--scope <scope>', description: 'OAuth permission to request (repeatable).', collect: true },
+        { flags: '--scope <scope>', description: 'OAuth permission to request (repeatable). Default: every permission Notis offers the CLI.', collect: true },
         { flags: '--code <code>', description: 'Redeem the code shown in the browser after a non-interactive login.' },
       ],
     },
@@ -133,9 +133,9 @@ export const authCommandSpecs = [
   },
   {
     command_path: ['logout'],
-    summary: 'Revoke and remove the OAuth credential for one CLI profile.',
+    summary: 'Sign this computer out of one CLI profile: revoke and remove its OAuth credential.',
     when_to_use:
-      'Use this to disconnect a single account. Other profiles keep their credentials unless you pass --all-profiles.',
+      'Use this to disconnect a single account on this computer. Its sign-ins on other computers stay, and other profiles keep their credentials unless you pass --all-profiles.',
     args_schema: {
       arguments: [],
       options: [

package/src/command-specs/diagnostics.js

@@ -4,6 +4,8 @@ import { usageError } from '../runtime/errors.js';
 import {
   COMPOSIO_MULTI_EXECUTE_TOOL,
   fetchToolDiscovery,
+  fetchToolSchema,
+  fetchToolkits,
   healthCheck,
   nextIdempotencyKey,
   runToolCommand,
@@ -37,6 +39,22 @@ function discoveredToolNames(payload) {
   return [...new Set(names.filter(Boolean))];
 }
 
+function isNotisAppSupabase(value) {
+  const upper = String(value || '').toUpperCase();
+  return upper.includes('SUPABASE') && upper.includes('NOTIS_APP') && !upper.includes('WEBSITE');
+}
+
+export function selectSupabaseSqlTool(discoveredNames, toolkits = []) {
+  const discovered = discoveredNames.find((name) => (
+    isNotisAppSupabase(name) && name.toUpperCase().includes('EXECUTE_SQL')
+  ));
+  if (discovered) return discovered;
+  // Semantic search ranks Composio's generic Supabase tools above a connected
+  // custom MCP server, so derive the canonical name from the connected toolkit.
+  const toolkit = toolkits.find((entry) => entry.has_active_connection && isNotisAppSupabase(entry.id));
+  return toolkit ? `${String(toolkit.id).toUpperCase()}_EXECUTE_SQL` : null;
+}
+
 async function discoverSupabaseSqlTool(runtime) {
   const payload = await fetchToolDiscovery(
     runtime,
@@ -44,10 +62,20 @@ async function discoverSupabaseSqlTool(runtime) {
     'query',
   );
   const names = discoveredToolNames(payload);
-  const match = names.find((name) => (
-    name.toUpperCase().includes('SUPABASE')
-    && name.toUpperCase().includes('EXECUTE_SQL')
-  ));
+  let match = selectSupabaseSqlTool(names);
+  if (!match) {
+    const { toolkits } = await fetchToolkits(runtime);
+    const candidate = selectSupabaseSqlTool([], toolkits);
+    if (candidate) {
+      try {
+        await fetchToolSchema(runtime, candidate);
+        match = candidate;
+      } catch (error) {
+        // Only an unknown tool name means the toolkit lacks it; surface outages.
+        if (error?.code !== 'usage_error' || !/not found/.test(error.message)) throw error;
+      }
+    }
+  }
   if (!match) {
     throw usageError('No connected Supabase execute-SQL capability was discovered. Run `notis tools link mcp_supabase_notis_app`.');
   }
@@ -56,7 +84,8 @@ async function discoverSupabaseSqlTool(runtime) {
 
 export function unwrapToolExecutionPayload(payload) {
   return (
-    payload?.data?.results?.[0]?.response?.data
+    payload?.data?.data?.results?.[0]?.response?.data
+    ?? payload?.data?.results?.[0]?.response?.data
     ?? payload?.results?.[0]?.response?.data
     ?? payload?.data?.result
     ?? payload?.result
@@ -72,30 +101,30 @@ function parseJsonCandidate(value) {
     return JSON.parse(trimmed);
   } catch {
     const boundaryEnd = trimmed.lastIndexOf('</untrusted-data');
-    const boundaryStart = boundaryEnd >= 0
-      ? trimmed.lastIndexOf('<untrusted-data', boundaryEnd)
-      : -1;
-    const contentStart = boundaryStart >= 0 ? trimmed.indexOf('>', boundaryStart) + 1 : -1;
-    if (contentStart > 0 && boundaryEnd > contentStart) {
+    const boundaryName = boundaryEnd >= 0
+      ? trimmed.slice(boundaryEnd + 2, trimmed.indexOf('>', boundaryEnd)) : null;
+    const opening = boundaryName ? `<${boundaryName}>` : null;
+    for (let boundaryStart = opening ? trimmed.indexOf(opening) : -1;
+      boundaryStart >= 0 && boundaryStart < boundaryEnd;
+      boundaryStart = trimmed.indexOf(opening, boundaryStart + opening.length)) {
+      const contentStart = boundaryStart + opening.length;
       // Supabase MCP sometimes returns the prose envelope with literal "\\n"
       // separators. Strip those only at the boundary: globally replacing them
       // corrupts valid escaped newlines inside JSON string values.
       const inner = trimmed
         .slice(contentStart, boundaryEnd)
         .trim()
-        .replace(/^(?:\\r?\\n)+/, '')
-        .replace(/(?:\\r?\\n)+$/, '')
+        .replace(/^(?:(?:\\r)?\\n)+/, '')
+        .replace(/(?:(?:\\r)?\\n)+$/, '')
         .trim();
       try {
         return JSON.parse(inner);
-      } catch (error) {
-        const nested = parseJsonCandidate(inner);
-        if (nested !== null) return nested;
-        throw usageError(
-          `Supabase diagnostic rows were not valid JSON: ${error instanceof Error ? error.message : String(error)}; prefix=${JSON.stringify(inner.slice(0, 100))}`,
-        );
+      } catch {
+        // The provider also mentions this marker in its introductory prose.
+        // Try its actual opening, never a nested tool result's different marker.
       }
     }
+    if (boundaryEnd >= 0) throw usageError('Supabase diagnostic rows were not valid JSON.');
     const arrayMatch = trimmed.match(/(\[[\s\S]*\])/);
     if (arrayMatch) {
       try {
@@ -445,7 +474,15 @@ async function debugEntitlementOverrideHandler(ctx) {
   });
 }
 
-function buildTraceCostSql(reference) {
+export function langfuseTraceIdCandidates(reference) {
+  const value = String(reference);
+  const compact = value.replaceAll('-', '').toLowerCase();
+  const providerId = /^[0-9a-f]{32}$/.test(compact) && !/^0+$/.test(compact)
+    ? compact : createHash('sha256').update(value).digest('hex').slice(0, 32);
+  return [...new Set([providerId, value])];
+}
+
+export function buildTraceCostSql(reference) {
   const literal = sqlLiteral(reference);
   return `
 SELECT jsonb_build_object(
@@ -464,6 +501,8 @@ SELECT jsonb_build_object(
 FROM public.interactions AS i
 WHERE i.id::text = ${literal}
    OR to_jsonb(i)->>'trace_id' = ${literal}
+   OR replace(i.id::text, '-', '') = lower(${literal})
+   OR replace(to_jsonb(i)->>'trace_id', '-', '') = lower(${literal})
 ORDER BY i.created_at ASC;`;
 }
 
@@ -579,7 +618,10 @@ async function debugTraceCostHandler(ctx) {
     refund_basis: refundableEstimate === null
       ? 'Requires confirmed Notis bug evidence and an explicit bug-attributable cost. Misunderstandings and service limitations are not goodwill bugs.'
       : 'Capped at the lower of recorded provider cost and the explicitly attributed true-bug amount.',
-    interactions,
+    interactions: interactions.map((item) => ({
+      ...item,
+      langfuse_trace_id_candidates: langfuseTraceIdCandidates(item.trace_id || item.id),
+    })),
     trace_file: traceDiagnostics,
   };
   return ctx.output.emitSuccess({
@@ -606,7 +648,42 @@ async function debugWorkerIdentityHandler(ctx) {
   });
 }
 
+export function buildProcessDiagnosticsSql(reference) {
+  if (typeof reference !== 'string' || !reference.trim() || reference.length > 256) {
+    throw usageError('An interaction id of 1–256 characters is required.');
+  }
+  return `BEGIN READ ONLY; SET LOCAL request.jwt.claim.role='service_role'; SELECT public.notis_process_diagnostics_v1(${sqlLiteral(reference)}) AS diagnostic; COMMIT;`;
+}
+
+async function debugProcessHandler(ctx) {
+  const execution = await executeReadOnlySql(ctx, buildProcessDiagnosticsSql(ctx.args.interactionId), 'process');
+  const raw = execution.rows[0]?.diagnostic;
+  const diagnostic = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  if (!diagnostic || diagnostic.definition_version !== 1 || diagnostic.status) {
+    throw usageError(`Process diagnostics unavailable: ${diagnostic?.status || 'invalid response'}.`);
+  }
+  if (diagnostic.interaction_id !== ctx.args.interactionId) throw usageError('Crossed diagnostic identity.');
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '), data: diagnostic, requestId: execution.requestId,
+    humanSummary: `${diagnostic.user_outcome}; ${diagnostic.handling}; ${diagnostic.reason_code || 'no incident'}.`,
+    meta: { mutating: false, sql_tool: execution.toolName },
+    renderHuman: () => JSON.stringify(diagnostic, null, 2),
+  });
+}
+
 export const diagnosticCommandSpecs = [
+  {
+    command_path: ['debug', 'process'],
+    summary: 'Read receipt-backed process diagnostics for one interaction.',
+    when_to_use: 'Correlate an interaction with Temporal runs, private failure references, delivery and settlement.',
+    args_schema: { arguments: [{ token: '<interaction-id>', key: 'interactionId', description: 'Exact interaction id.' }], options: [] },
+    examples: ['notis debug process interaction_123 --json'],
+    output_schema: 'Versioned, content-free logical outcome, handling, workflow/run and evidence references.',
+    mutates: false, idempotent: true,
+    related_commands: ['notis debug worker-identity', 'notis debug trace-cost <trace-or-interaction>'],
+    backend_call: { type: 'tool-discovery', name: 'Supabase execute SQL capability' },
+    handler: debugProcessHandler,
+  },
   {
     command_path: ['debug', 'user-context'],
     summary: 'Resolve a user’s effective redacted runtime and billing context.',

package/src/command-specs/documents.js

@@ -0,0 +1,158 @@
+import { usageError } from '../runtime/errors.js';
+import { httpRequest } from '../runtime/transport.js';
+import { unifiedDiffSummary, versionName } from './version-history.js';
+
+const documentArgument = { token: '<document-id>', key: 'documentId', description: 'Exact document ID.' };
+const versionOption = { flags: '--version-id <version-id>', description: 'Saved version ID from versions list.' };
+
+async function remote(ctx, operation, { method = 'POST', body, query, humanSummary } = {}) {
+  const suffix = query ? `?${new URLSearchParams(Object.entries(query).filter(([, value]) => value != null))}` : '';
+  const result = await httpRequest({ runtime: ctx.runtime, method, path: `/portal_documents/${operation}${suffix}`, body, spacesProtocol: true });
+  return ctx.output.emitSuccess({ command: ctx.spec.command_path.join(' '), data: result.payload,
+    humanSummary: humanSummary ? humanSummary(result.payload) : JSON.stringify(result.payload, null, 2),
+    meta: { mutating: method !== 'GET', request_id: result.requestId } });
+}
+
+function versionId(options) {
+  if (typeof options.versionId !== 'string' || !options.versionId.trim()) throw usageError('Pass --version-id with a saved version ID from versions list.');
+  return options.versionId;
+}
+
+function limit(value) {
+  if (value === undefined) return undefined;
+  if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 100) throw usageError('Pass --limit as a whole number from 1 to 100.');
+  return Number(value);
+}
+
+function confirmed(options, what) {
+  if (!options.yes) throw usageError(`${what} cannot be undone. Only do it when the user asked, then pass --yes.`);
+}
+
+export const documentsCommandSpecs = [
+  {
+    command_path: ['documents', 'versions', 'list'],
+    summary: 'Read a document’s saved versions, newest first.',
+    when_to_use: 'See when and by whom a document changed, before comparing or restoring a version.',
+    args_schema: { arguments: [documentArgument], options: [
+      { flags: '--before <version-id>', description: 'Read versions older than this version.' },
+      { flags: '--limit <count>', description: 'How many versions to read (1 to 100).' },
+    ] },
+    examples: ['notis documents versions list <document-id>'], mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/versions' },
+    handler(ctx) {
+      return remote(ctx, 'versions', { method: 'GET', query: { document_id: ctx.args.documentId,
+        before: ctx.options.before, limit: limit(ctx.options.limit) } });
+    },
+  },
+  {
+    command_path: ['documents', 'versions', 'read'],
+    summary: 'Read one saved version of a document.',
+    when_to_use: 'See exactly what a saved version said, before comparing or restoring it.',
+    args_schema: { arguments: [documentArgument], options: [versionOption] },
+    examples: ['notis documents versions read <document-id> --version-id <version-id>'],
+    mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/versions/read' },
+    handler(ctx) {
+      return remote(ctx, 'versions/read', { method: 'GET', query: { document_id: ctx.args.documentId, version_id: versionId(ctx.options) } });
+    },
+  },
+  {
+    command_path: ['documents', 'versions', 'diff'],
+    summary: 'Compare two saved versions of a document, or one with the current version.',
+    when_to_use: 'See what changed between versions. Prints the unified diff; pass --json for the full comparison.',
+    args_schema: { arguments: [documentArgument], options: [
+      { flags: '--from <version-id>', description: 'The older saved version.' },
+      { flags: '--to <version-id>', description: 'The newer saved version, or current (default).' },
+    ] },
+    examples: ['notis documents versions diff <document-id> --from <version-id>',
+      'notis documents versions diff <document-id> --from <version-id> --to <version-id> --json'],
+    mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/versions/diff' },
+    handler(ctx) {
+      if (typeof ctx.options.from !== 'string' || !ctx.options.from.trim()) throw usageError('Pass --from with a saved version ID from versions list.');
+      return remote(ctx, 'versions/diff', { method: 'GET', humanSummary: unifiedDiffSummary,
+        query: { document_id: ctx.args.documentId, from: ctx.options.from, to: ctx.options.to || 'current' } });
+    },
+  },
+  {
+    command_path: ['documents', 'versions', 'restore'],
+    summary: 'Bring a document back to a saved version; what it replaces is kept as a version.',
+    when_to_use: 'Undo changes to a document by restoring an earlier version.',
+    args_schema: { arguments: [documentArgument], options: [versionOption,
+      { flags: '--request-id <id>', description: 'Stable restore request ID; reuse on retry.' }] },
+    examples: ['notis documents versions restore <document-id> --version-id <version-id> --request-id undo-edit'],
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/versions/restore' },
+    handler(ctx) {
+      const version = versionId(ctx.options);
+      if (!ctx.options.requestId) throw usageError('Pass a stable --request-id and reuse it on retry.');
+      return remote(ctx, 'versions/restore', { body: { document_id: ctx.args.documentId, version_id: version,
+        request_id: ctx.options.requestId } });
+    },
+  },
+  {
+    command_path: ['documents', 'versions', 'name'],
+    summary: 'Name a saved version of a document, or clear its name.',
+    when_to_use: 'Mark a version worth keeping. Named versions are kept past the usual retention.',
+    args_schema: { arguments: [documentArgument], options: [versionOption,
+      { flags: '--name <name>', description: 'The version name.' },
+      { flags: '--clear', description: 'Remove the version name.' }] },
+    examples: ['notis documents versions name <document-id> --version-id <version-id> --name "Final draft"'],
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/versions/name' },
+    handler(ctx) {
+      return remote(ctx, 'versions/name', { body: { document_id: ctx.args.documentId, version_id: versionId(ctx.options),
+        name: versionName(ctx.options) } });
+    },
+  },
+  {
+    command_path: ['documents', 'versions', 'delete'],
+    summary: 'Delete one saved version of a document for good.',
+    when_to_use: 'Only when the user asked to delete this version. It cannot be restored afterwards.',
+    args_schema: { arguments: [documentArgument], options: [versionOption,
+      { flags: '--yes', description: 'Confirm the user asked to delete this version for good.' }] },
+    examples: ['notis documents versions delete <document-id> --version-id <version-id> --yes'],
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/versions/delete' },
+    handler(ctx) {
+      const version = versionId(ctx.options);
+      confirmed(ctx.options, 'Deleting a saved version');
+      return remote(ctx, 'versions/delete', { body: { document_id: ctx.args.documentId, version_id: version } });
+    },
+  },
+  {
+    command_path: ['documents', 'bin', 'list'],
+    summary: 'List the documents in your Bin.',
+    when_to_use: 'Find a deleted document to bring back, or to remove for good.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis documents bin list'], mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/bin' },
+    handler(ctx) {
+      return remote(ctx, 'bin', { method: 'GET' });
+    },
+  },
+  {
+    command_path: ['documents', 'bin', 'restore'],
+    summary: 'Bring a document back from the Bin.',
+    when_to_use: 'Undo deleting a document.',
+    args_schema: { arguments: [documentArgument], options: [] },
+    examples: ['notis documents bin restore <document-id>'], mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/bin/restore' },
+    handler(ctx) {
+      return remote(ctx, 'bin/restore', { body: { document_id: ctx.args.documentId } });
+    },
+  },
+  {
+    command_path: ['documents', 'bin', 'remove'],
+    summary: 'Remove a document from the Bin for good.',
+    when_to_use: 'Only when the user asked to remove this document for good. It cannot be brought back afterwards.',
+    args_schema: { arguments: [documentArgument], options: [
+      { flags: '--yes', description: 'Confirm the user asked to remove this document for good.' }] },
+    examples: ['notis documents bin remove <document-id> --yes'], mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_documents/bin/remove' },
+    handler(ctx) {
+      confirmed(ctx.options, 'Removing a document from the Bin');
+      return remote(ctx, 'bin/remove', { body: { document_id: ctx.args.documentId } });
+    },
+  },
+];

package/src/command-specs/files.js

@@ -0,0 +1,29 @@
+import { uploadNativeRecordFileWithCliRuntime } from '../runtime/native-record-files.js';
+import { parseJson } from './helpers.js';
+import { usageError } from '../runtime/errors.js';
+
+export const filesCommandSpecs = [{
+  command_path: ['files', 'upload'],
+  summary: 'Upload a local file for one native record you can edit.',
+  when_to_use: 'Save file bytes without a cloud computer; attach the returned file reference through a normal revision-checked row update.',
+  args_schema: { arguments: [{ token: '<file>', key: 'file', description: 'Local regular file up to 8 MB.' }], options: [
+    { flags: '--target <json>', description: 'Exact native target returned by schema discovery.' },
+    { flags: '--record-key <id>', description: 'Stable record key to attach this file to.' },
+    { flags: '--schema-revision <number>', description: 'Current native schema revision.' },
+    { flags: '--request-id <uuid>', description: 'Stable UUID; reuse with identical bytes after an uncertain response.' },
+    { flags: '--name <name>', description: 'Attachment name; defaults to the local basename.' },
+    { flags: '--content-type <mime>', description: 'File MIME type; inferred from known extensions.' },
+  ] },
+  examples: ['notis files upload ./report.html --target \'{"database_id":"<database-id>"}\' --record-key <record-key> --schema-revision 1 --request-id <uuid>'],
+  mutates: true, idempotent: true, require_auth: true,
+  backend_call: { type: 'http', path: '/portal_native_files/upload' },
+  async handler(ctx) {
+    if (!ctx.options.target || ctx.options.schemaRevision === undefined) throw usageError('Pass the discovered native --target and --schema-revision.');
+    const result = await uploadNativeRecordFileWithCliRuntime({ runtime: ctx.runtime, filePath: ctx.args.file,
+      target: parseJson(ctx.options.target, '--target'), recordKey: ctx.options.recordKey,
+      schemaRevision: Number(ctx.options.schemaRevision), requestId: ctx.options.requestId,
+      ...(ctx.options.name ? { name: ctx.options.name } : {}), ...(ctx.options.contentType ? { contentType: ctx.options.contentType } : {}) });
+    return ctx.output.emitSuccess({ command: 'files upload', data: result,
+      humanSummary: 'Uploaded and verified the file. Attach the returned file reference with a revision-checked record update.', meta: { mutating: true } });
+  },
+}];