@wirecat/drive-cli 0.2.0 → 0.4.0

package/dist/program.js

@@ -2,22 +2,22 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { CliError, createDeadline, createOutputBuffer, createRenderer, processStreams, visibleControls, } from "@wirecat/cli-base";
 import { annotate, describeOptions, flatten, metaOf } from "@wirecat/cli-base/commands";
 import { formatSuggestions, suggest } from "@wirecat/cli-base/completion";
-import { commandWords, liftProfile, parseDuration, refuseCommandName } from "@wirecat/cli-messaging/cli";
+import { commandWords, liftProfile, parseDuration, refuseCommandName } from "@wirecat/cli-core/cli";
 import { Command, Help, InvalidArgumentError, Option } from "commander";
-import { operationOf, validateRequest } from "./api-contract.js";
-import { activeProfile, application, fileId, profileName, readConfig, writeConfig } from "./config.js";
+import { validateRequest } from "./api-contract.js";
+import { installCatalogCommands } from "./catalog-commands.js";
+import { activeProfile, application, checkTextLimit, fileId, pictureSearch, profileName, readConfig, writeConfig, } from "./config.js";
 import { googleError } from "./errors.js";
 import { memoryModel } from "./extraction.js";
-import { googleSource } from "./google.js";
+import { googleSource, MAX_ENTRIES } from "./google.js";
 import { apiMethod, googleApi } from "./google-api.js";
 import { installKnowledgeCommands } from "./knowledge-commands.js";
 import { login } from "./login.js";
-import { FOLDER } from "./model.js";
+import { FOLDER, metadataJson, skipJson } from "./model.js";
 import { checkPolicy, guardedGoogleWrite, methodPolicyKeys } from "./policy.js";
 import { lockProfile } from "./profile-lock.js";
-import { ACCOUNT_FREE_COMMANDS, describeDriveProgram } from "./registry.js";
+import { ACCOUNT_FREE_COMMANDS, commandsDocument, describeDriveProgram, examples } from "./registry.js";
 import { installRemoteCommands } from "./remote-commands.js";
-import { requestSchema } from "./schema.js";
 import { readSnapshot, readState } from "./state.js";
 import { openIndex } from "./store.js";
 import { sync } from "./sync.js";
@@ -39,7 +39,7 @@ export const createProgram = (options = {}) => {
     const env = options.env ?? process.env;
     const streams = options.streams ?? processStreams;
     const program = new Command("drive")
-        .description("Manage Google Drive and Docs, local Markdown, shared knowledge and search")
+        .description("manage Google Drive and Docs, local Markdown, shared knowledge and search")
         .version(VERSION)
         .usage("<profile> [options] <command>")
         .option("--profile <name>", "explicit Google account profile (alternative to the first word)")
@@ -47,8 +47,9 @@ export const createProgram = (options = {}) => {
         .option("--jsonl", "print machine-readable JSON lines")
         .option("--agent-json", "show control and direction characters visibly in machine output")
         .option("--quiet", "suppress optional diagnostics")
+        .option("--debug", "on failure, show the full error record: cause and stack")
         .option("--timeout <duration>", "whole-command deadline, e.g. 30s", (raw) => parseDuration(raw, "--timeout"))
-        .option("--max-output-bytes <n>", "bound buffered result output", offset, 4 * 1024 * 1024)
+        .option("--max-output-bytes <n>", "largest result to print, in bytes; 0 for no limit", offset, 4 * 1024 * 1024)
         .option("--read-only", "refuse local and remote mutations")
         .option("--offline", "answer only operations that use local cached data")
         .option("--dry-run", "validate command/policy and preview without acting")
@@ -69,7 +70,7 @@ export const createProgram = (options = {}) => {
             throw new CliError("validation_error", "choose a profile explicitly: drive <profile> <command> or drive --profile <name> <command>; " +
                 (choices.length
                     ? `configured profiles: ${choices.join(", ")}`
-                    : "no profiles configured; connect with drive personal session start"), { profiles: choices });
+                    : "no profiles configured; connect with drive personal session start"), { reason: "profile.required", profiles: choices });
         }
         return profileName(name);
     };
@@ -129,16 +130,14 @@ export const createProgram = (options = {}) => {
             await index.close();
         }
     };
-    const session = program.command("session").description("Google browser sign-in and local account profiles");
-    session
-        .command("start")
-        .description("Approve Google access in your browser; read-only unless --write is requested")
-        .option("--client-file <file>", "use your own Desktop OAuth application JSON instead of WireCat's app")
-        .option("--credential-storage <storage>", "keyring or explicit private-file storage", "keyring")
-        .option("--no-browser", "print the sign-in URL without opening a browser")
-        .option("--write", "request remote Drive/Docs mutation permissions")
-        .option("--activity", "also request Drive Activity history permissions")
-        .option("--apps", "also request the installed Drive applications permission")
+    const session = program.command("session").description("sign in to Google and manage local profiles");
+    examples(session.command("start").description("sign in to Google in the browser; read-only unless you pass --write"), ["drive personal session start", "drive work session start --write --activity"])
+        .option("--client-file <file>", "path to your own Desktop OAuth client JSON, used instead of WireCat's")
+        .option("--credential-storage <storage>", "where the sign-in is kept: keyring, or file for a private file", "keyring")
+        .option("--no-browser", "print the sign-in URL instead of opening a browser")
+        .option("--write", "also ask for permission to change Drive files and Docs")
+        .option("--activity", "also ask for permission to read Drive Activity history")
+        .option("--apps", "also ask for permission to see installed Drive apps")
         .action(async (args) => {
         if (args.credentialStorage !== "keyring" && args.credentialStorage !== "file")
             throw new CliError("validation_error", "credential storage is keyring or file");
@@ -156,35 +155,33 @@ export const createProgram = (options = {}) => {
             showUrl: (url) => streams.diagnostic(`Open Google sign-in: ${url}\n`),
         }));
     });
-    session
-        .command("list")
-        .description("Configured account profiles; no credentials are printed")
-        .action(() => output({
+    examples(session.command("list").description("list the configured profiles; credentials are never printed"), [
+        "drive personal session list",
+    ]).action(() => output({
         scope: "all-configured-profiles",
         items: Object.entries(readConfig(env).profiles).map(([name, p]) => ({
             profile: name,
-            selectedFolders: p.roots.length,
+            selected_folders: p.roots.length,
             storage: p.storage,
         })),
     }));
-    session
-        .command("end")
-        .description("Remove this profile's local sign-in; cached data is retained")
-        .action(() => {
+    examples(session.command("end").description("sign this profile out; imported documents stay"), [
+        "drive personal session end",
+    ]).action(() => {
         const name = selected();
         const config = readConfig(env);
         const profile = activeProfile(env, name);
         credentials(env, profile.storage, options.keyring).remove(name);
         // Preserve the principal and roots so reauthorization resumes the same source identities.
         writeConfig(env, config);
-        output({ profile: name, signedOut: true, cachedData: "retained" });
+        output({ profile: name, signed_out: true, cached_data: "retained" });
     });
-    const folders = program.command("folders").description("Select Google folders for local ingestion");
-    folders
+    const folders = program.command("folders").description("choose the Google Drive folders that sync imports");
+    const folderArgument = "folder id or Google Drive URL";
+    examples(folders
         .command("add")
-        .argument("<url-or-id>")
-        .description("Include a folder and its descendants")
-        .action(async (input) => {
+        .argument("<folder>", folderArgument)
+        .description("import a folder and everything under it on the next sync"), ["drive personal folders add FOLDER_ID"]).action(async (input) => {
         const id = fileId(input);
         const config = readConfig(env);
         const name = selected();
@@ -198,15 +195,13 @@ export const createProgram = (options = {}) => {
         writeConfig(env, config);
         output({ id: metadata.id, name: metadata.name, added: true });
     });
-    folders
-        .command("list")
-        .description("Selected folder IDs")
-        .action(() => output({ items: activeProfile(env, selected()).roots.map((id) => ({ id })) }));
-    folders
+    examples(folders.command("list").description("list the folder ids sync imports"), [
+        "drive personal folders list",
+    ]).action(() => output({ items: activeProfile(env, selected()).roots.map((id) => ({ id })) }));
+    examples(folders
         .command("remove")
-        .argument("<url-or-id>")
-        .description("Stop importing a folder; sync removes sources outside the remaining scope")
-        .action((input) => {
+        .argument("<folder>", folderArgument)
+        .description("stop importing a folder; the next sync drops its documents"), ["drive personal folders remove FOLDER_ID"]).action((input) => {
         const id = fileId(input);
         const config = readConfig(env);
         const name = selected();
@@ -216,48 +211,53 @@ export const createProgram = (options = {}) => {
         writeConfig(env, config);
         output({ id, removed: true, next: `run drive ${name} sync to reconcile cached sources` });
     });
-    program
+    examples(program
         .command("sync")
-        .description("Fetch selected sources and resume a durable pending batch")
-        .option("--max <n>", "maximum source operations this run", positive, 200)
-        .option("--rescan", "reconcile selected folders from a fresh change token")
-        .option("--embed", "embed pending shared note chunks using an already-downloaded model")
+        .summary("import what changed in the chosen folders, and finish an unfinished sync")
+        .description("import what changed in the chosen folders, and finish an unfinished sync; " +
+        `one sync reads at most ${MAX_ENTRIES} entries under the chosen folders, and as many changes`), ["drive personal sync", "drive personal sync --rescan --limit 500"])
+        .option("--limit <n>", "how many documents to read from Google in this run", positive, 200)
+        .option("--rescan", "read every chosen folder again instead of only what changed")
+        .option("--embed", "also index pending text for meaning search, with a model already downloaded")
         .action(async (args) => {
         const remote = activeProfile(env, selected()).roots.length ? await source() : undefined;
         const result = await withIndex(async (index) => ({
-            ...(await sync(remote, index, env, selected(), args.max, activeSignal, args.rescan)),
+            ...(await sync(remote, index, env, selected(), args.limit, activeSignal, args.rescan)),
             ...(args.embed ? { embeddings: await index.embed(600) } : {}),
         }));
         output(result);
         if (result.errors.length || result.pending)
             streams.diagnostic(`${result.pending} source operations remain; run drive ${selected()} sync again\n`);
         if (result.errors.length)
-            throw new CliError("provider_error", "sync completed partially; failed operations remain pending");
+            throw new CliError("provider_error", "sync completed partially; failed operations remain pending", {
+                reason: "sync.partial",
+            });
     });
-    program
-        .command("status")
-        .description("Local sync checkpoint, cached sources and pending work")
-        .action(() => {
+    examples(program.command("status").description("show the last sync, imported documents and pending work"), [
+        "drive personal status",
+    ]).action(() => {
         const name = selected();
         const profile = activeProfile(env, name);
         const state = readState(env, name, profile.principal);
         output({
             profile: name,
-            selectedFolders: profile.roots,
+            selected_folders: profile.roots,
             documents: Object.keys(state.documents).length,
             pending: state.pending?.jobs.length ?? 0,
-            skipped: state.skipped,
-            lastSync: state.lastSync ?? null,
+            skipped: state.skipped.map(skipJson),
+            last_sync: state.lastSync ?? null,
             coverage: "Google Docs and Markdown/TXT; native export tab fidelity and assets are not verified",
-            remoteChecked: false,
+            remote_checked: false,
         });
     });
-    const documents = program.command("documents").description("Locally imported sources and exports");
-    documents
-        .command("list")
-        .description("Imported sources with original Google URLs")
-        .option("--tag <tag>", "filter by a local shared tag")
-        .option("--person <reference>", "filter by a linked shared person reference")
+    const documents = program.command("documents").description("read imported documents and Google Docs");
+    const documentArgument = "document id or Google Docs URL";
+    examples(documents.command("list").description("list imported documents with their Google URLs"), [
+        "drive personal documents list",
+        "drive personal documents list --tag budget",
+    ])
+        .option("--tag <tag>", "only documents with this tag")
+        .option("--person <reference>", "only documents linked to this person:<uid> reference")
         .action(async (args) => {
         const profile = activeProfile(env, selected());
         const state = readState(env, selected(), profile.principal);
@@ -274,7 +274,7 @@ export const createProgram = (options = {}) => {
             });
         output({
             items: docs.map((doc) => ({
-                ...doc.metadata,
+                ...metadataJson(doc.metadata),
                 reference: doc.reference,
                 tabs: doc.tabs,
             })),
@@ -285,36 +285,57 @@ export const createProgram = (options = {}) => {
         const profile = activeProfile(env, selected());
         const state = readState(env, selected(), profile.principal);
         if (!state.documents[id])
-            throw new CliError("not_found", "this source is not imported in the selected profile");
+            throw new CliError("not_found", "this source is not imported in the selected profile", {
+                reason: "document.not-imported",
+            });
         const doc = state.documents[id];
         return { id, ref: doc.reference, hash: doc.hash, snapshot: readSnapshot(env, selected(), id) };
     };
-    documents
+    examples(documents
         .command("show")
-        .argument("<url-or-id>")
-        .description("Imported text with tab and source metadata")
-        .action((input) => {
+        .argument("<document>", documentArgument)
+        .description("show an imported document's text, tabs and metadata"), ["drive personal documents show DOC_ID"]).action((input) => {
         const { snapshot } = imported(input);
-        output({ metadata: snapshot.metadata, text: snapshot.text, tabs: snapshot.tabs });
+        output({
+            metadata: metadataJson(snapshot.metadata),
+            text: snapshot.text,
+            tabs: snapshot.tabs,
+            ...(snapshot.notRead ? { not_read: snapshot.notRead } : {}),
+        });
     });
-    documents
+    examples(documents
         .command("export")
-        .argument("<url-or-id>")
-        .requiredOption("--out <file>", "destination Markdown file")
-        .description("Write the native Markdown snapshot; existing files are refused")
+        .argument("<document>", documentArgument)
+        .description("write an imported document to a new Markdown file"), ["drive personal documents export DOC_ID --out notes.md"])
+        .requiredOption("--out <file>", "path of the Markdown file to write; an existing file is refused")
         .action((input, args) => {
         const { id, snapshot } = imported(input);
-        writeFileSync(args.out, snapshot.markdown, { flag: "wx", mode: 0o600 });
+        try {
+            writeFileSync(args.out, snapshot.markdown, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new CliError("validation_error", "the output file already exists; choose another --out", {
+                    reason: "export.exists",
+                    param: "--out",
+                });
+            throw error;
+        }
         output({ id, path: args.out, format: "markdown" });
     });
-    program
+    examples(program
         .command("search")
-        .argument("<query>")
-        .description("Shared keyword and optional semantic search over imported Google sources")
-        .option("--limit <n>", "maximum results", positive, 20)
-        .option("--offset <n>", "results to skip", offset, 0)
-        .option("--exact", "keyword search only, without stemming or meaning")
-        .action(async (query, args) => output(await withIndex((index) => index.search(activeProfile(env, selected()).principal, query, { ...args, exact: args.exact ?? false }))));
+        .argument("<query>", "words to look for")
+        .description("search imported documents by words, and by meaning when indexed"), ["drive personal search budget", `drive personal search "quarterly plan" --exact --limit 5`])
+        .option("--limit <n>", "how many results to return", positive, 20)
+        .option("--offset <n>", "how many results to skip", offset, 0)
+        .option("--exact", "match the words exactly: no word forms, no meaning")
+        .action(async (query, args) => output(await withIndex((index) => index.search(activeProfile(env, selected()).principal, query, {
+        ...args,
+        exact: args.exact ?? false,
+        ...(pictureSearch(env, selected()) ? { pictures: true } : {}),
+    }))));
+    installCatalogCommands(program, { env, selected, output, positive, offset, withIndex });
     installKnowledgeCommands(program, {
         document: imported,
         output,
@@ -324,12 +345,14 @@ export const createProgram = (options = {}) => {
         run: async (input, fn) => {
             const lock = await lockProfile(env, selected());
             try {
-                const { ref } = imported(input);
                 return await withIndex(async (index) => {
                     lock.assertHeld();
                     if (!index.knowledge)
                         throw new CliError("configuration_error", "index has no shared knowledge adapter");
-                    const result = await fn(index.knowledge, activeProfile(env, selected()).principal, ref);
+                    const principal = activeProfile(env, selected()).principal;
+                    const found = await index.catalog?.get(principal, fileId(input));
+                    const ref = found?.ref ?? imported(input).ref;
+                    const result = await fn(index.knowledge, principal, ref);
                     lock.assertHeld();
                     return result;
                 });
@@ -342,7 +365,18 @@ export const createProgram = (options = {}) => {
     installRemoteCommands(program, {
         output,
         positive,
-        readBody: options.readBody ?? ((path) => readFileSync(path, "utf8")),
+        readBody: options.readBody ??
+            ((path) => {
+                try {
+                    return readFileSync(path, "utf8");
+                }
+                catch {
+                    throw new CliError("validation_error", "the request body file could not be read", {
+                        reason: "body.unreadable",
+                        param: "--body-file",
+                    });
+                }
+            }),
         call: async (method, params, body) => {
             const descriptor = apiMethod(method);
             validateRequest(method, params, body);
@@ -350,14 +384,16 @@ export const createProgram = (options = {}) => {
             for (const key of methodPolicyKeys(method))
                 await checkPolicy(env, selected(), key, descriptor.mutates, flags, askOnce);
             if (flags.offline)
-                throw new CliError("permission_error", "this operation needs Google; --offline was requested");
+                throw new CliError("permission_error", "this operation needs Google; --offline was requested", {
+                    reason: "offline.refused",
+                });
             if (flags.dryRun)
                 return {
-                    dryRun: true,
+                    dry_run: true,
                     method,
                     mutates: descriptor.mutates,
                     parameters: params,
-                    bodyProvided: body !== undefined,
+                    body_provided: body !== undefined,
                 };
             const act = async () => {
                 try {
@@ -374,15 +410,17 @@ export const createProgram = (options = {}) => {
             return descriptor.mutates ? guardedGoogleWrite(env, selected(), `api.${method}`, act, flags, askOnce) : act();
         },
     });
-    const config = program
-        .command("config")
-        .description("Shared-style defaults/profile settings; credentials are separate");
-    config.command("show").action(() => output(readConfig(env)));
-    config
-        .command("set")
-        .argument("<key>")
-        .argument("<json-value>")
-        .option("--defaults", "change defaults rather than the selected profile")
+    const config = program.command("config").description("read and change settings; credentials are kept apart");
+    examples(config.command("show").description("show the defaults and every profile's settings"), [
+        "drive personal config show",
+    ]).action(() => output(readConfig(env)));
+    examples(config.command("set").description("set one setting of this profile, or of the defaults"), [
+        "drive personal config set readOnly true",
+        `drive personal config set permissions.files '"readonly"' --defaults`,
+    ])
+        .argument("<key>", "readOnly, maxTextChars, pictureSearch, permissions.<key> or models.<purpose>.<field>")
+        .argument("<json-value>", "the new value, as JSON")
+        .option("--defaults", "change the defaults instead of this profile")
         .action((key, raw, args) => {
         const value = readConfig(env);
         if (args.defaults)
@@ -393,9 +431,9 @@ export const createProgram = (options = {}) => {
         if (!args.defaults)
             value.profiles[selected()] = target;
         const [head, ...parts] = key.split(".");
-        if (!["readOnly", "permissions", "models"].includes(head ?? "") ||
+        if (!["readOnly", "permissions", "models", "maxTextChars", "pictureSearch"].includes(head ?? "") ||
             parts.some((part) => ["__proto__", "prototype", "constructor"].includes(part)))
-            throw new CliError("validation_error", "config set accepts readOnly, permissions or models");
+            throw new CliError("validation_error", "config set accepts readOnly, permissions, models, maxTextChars or pictureSearch");
         let parsed;
         try {
             parsed = JSON.parse(raw);
@@ -403,7 +441,14 @@ export const createProgram = (options = {}) => {
         catch {
             throw new CliError("validation_error", "setting value must be JSON");
         }
-        if (!parts.length)
+        if (head === "pictureSearch") {
+            if (args.defaults || parts.length || typeof parsed !== "boolean")
+                throw new CliError("validation_error", "pictureSearch is true or false, set per profile");
+            target.pictureSearch = parsed;
+        }
+        else if (head === "maxTextChars" && !parts.length)
+            target.maxTextChars = checkTextLimit(parsed);
+        else if (!parts.length)
             Object.assign(target, { [key]: parsed });
         else if (head === "permissions") {
             target.permissions ??= {};
@@ -419,10 +464,10 @@ export const createProgram = (options = {}) => {
         writeConfig(env, value);
         output({ key, updated: true, scope: args.defaults ? "defaults" : selected() });
     });
-    program
-        .command("complete")
-        .description("Shell completion from the shared command registry")
-        .argument("[words...]")
+    examples(program.command("complete").description("print a shell completion script, or complete words"), [
+        "drive complete zsh",
+    ])
+        .argument("[words...]", "a shell name, or after -- the words typed so far")
         .allowUnknownOption()
         .helpOption(false)
         .action(async (words) => {
@@ -435,25 +480,17 @@ export const createProgram = (options = {}) => {
         else
             streams.data(formatSuggestions(suggest({ commands: describeDriveProgram(program), globalOptions: describeOptions(program), words })));
     });
-    program
-        .command("schema")
-        .argument("<method>")
-        .description("Generated request schema and operation contract without Google access")
-        .action((method) => {
-        const operation = operationOf(method);
-        output({
-            operation,
-            requestSchema: requestSchema(method),
-        });
-    });
-    program
+    examples(program
         .command("models")
-        .description("Configure the shared model gateway; keys stay outside config")
-        .command("configure")
-        .option("--purpose <purpose>", "shared model purpose", "memories")
-        .addOption(new Option("--provider <provider>").choices(["openai", "anthropic", "off"]).makeOptionMandatory())
-        .option("--model <model>", "model identifier for the selected provider")
-        .option("--base-url <url>", "optional HTTP/S model endpoint without URL credentials")
+        .description("choose the model that proposes memories; keys stay out of config")
+        .command("set")
+        .description("set the provider and model for one use"), ["drive personal models set --provider openai --model MODEL_ID", "drive personal models set --provider off"])
+        .option("--purpose <purpose>", "what the model is used for", "memories")
+        .addOption(new Option("--provider <provider>", "who runs the model, or off to use none")
+        .choices(["openai", "anthropic", "off"])
+        .makeOptionMandatory())
+        .option("--model <model>", "model id at the provider")
+        .option("--base-url <url>", "HTTP or HTTPS address of the model API, without credentials in it")
         .action((args) => {
         const config = readConfig(env);
         config.defaults ??= {};
@@ -466,34 +503,31 @@ export const createProgram = (options = {}) => {
         writeConfig(env, config);
         output({ purpose: args.purpose, configured: true });
     });
-    const mcp = program.command("mcp").description("Expose guarded commands over MCP stdio");
-    mcp.option("--tools", "list offered tools without starting a server").action(async (args) => {
+    const mcp = examples(program.command("mcp").description("serve drive's commands to an agent over MCP on stdio"), [
+        "drive personal mcp",
+        "drive personal mcp --tools",
+    ]);
+    mcp
+        .option("--tools", "list the tools offered instead of starting the server")
+        .action(async (args) => {
         const { mcpTools, serveMcp } = await import("./mcp.js");
         if (args.tools)
             output({
                 items: mcpTools({ ...options, env }, selected(), policyFlags()).map(({ name, schema, command }) => ({
                     name,
-                    inputSchema: schema,
+                    input_schema: schema,
                     mutates: command.mutates,
                 })),
             });
         else
             await serveMcp({ ...options, env, ...(activeSignal ? { signal: activeSignal } : {}) }, selected(), policyFlags());
     });
-    program
-        .command("commands")
-        .argument("[path...]")
-        .description("Discover the command tree and options as shared registry data")
-        .action((path) => {
-        const commands = describeDriveProgram(program);
-        const found = path.length ? flatten(commands).filter((item) => item.path.join(" ") === path.join(" ")) : commands;
-        if (path.length && !found.length)
-            throw new CliError("not_found", "command path was not found");
-        output({
-            items: found,
-            ...(path.length ? {} : { cli: "drive", commands, globalOptions: describeOptions(program) }),
-        });
-    });
+    examples(program.command("commands").description("print the command tree and its options as data"), [
+        "drive commands --json",
+        "drive commands files copy --json",
+    ])
+        .argument("[path...]", "only this command or group, as words")
+        .action((path) => output(commandsDocument(program, path)));
     for (const info of flatten(describeDriveProgram(program))) {
         let command = program;
         for (const part of info.path)
@@ -507,8 +541,8 @@ export const createProgram = (options = {}) => {
             "documents export",
             "tags add",
             "tags remove",
-            "links add",
-            "links remove",
+            "relationships add",
+            "relationships remove",
             "notes add",
             "notes edit",
             "notes remove",
@@ -517,9 +551,9 @@ export const createProgram = (options = {}) => {
             "memories stale",
             "memories extract",
             "facts add",
-            "facts accept",
-            "people link",
-            "models configure",
+            "facts confirm",
+            "identities link",
+            "models set",
             "config set",
         ];
         const remoteWrites = [
@@ -537,7 +571,8 @@ export const createProgram = (options = {}) => {
         annotate(command, {
             origin: metaOf(command).origin ?? "handwritten",
             mutates: metaOf(command).mutates ?? (localWrites.includes(name) || remoteWrites.includes(name)),
-            local: localWrites.includes(name) && name !== "session start" && name !== "memories extract",
+            local: metaOf(command).local ??
+                (localWrites.includes(name) && name !== "session start" && name !== "memories extract"),
             state: "beta",
         });
     }
@@ -564,18 +599,20 @@ export const createProgram = (options = {}) => {
         if (ACCOUNT_FREE_COMMANDS.has(words))
             return;
         selected();
-        if (["commands", "complete", "schema", "config show", "config set", "session list"].includes(words))
+        if (["commands", "complete", "config show", "config set", "session list"].includes(words))
             return;
         const flags = policyFlags();
         const metadata = metaOf(action);
         const rawMethod = words === "api call" ? action.args[0] : undefined;
-        const method = metadata.operationId ?? rawMethod;
+        const method = metadata.operation_id ?? rawMethod;
         if (rawMethod) {
             const descriptor = apiMethod(rawMethod);
             if (descriptor.mutates && !action.opts().allowWrite)
-                throw new CliError("permission_error", "this method changes Google data; pass --allow-write");
+                throw new CliError("permission_error", "this method changes Google data; pass --allow-write", {
+                    reason: "write.not-allowed",
+                });
             if (descriptor.destructive && !action.opts().allowDelete && !flags.allowDangerous)
-                throw new CliError("permission_error", "this method deletes Google data; pass --allow-delete or --allow-dangerous");
+                throw new CliError("permission_error", "this method deletes Google data; pass --allow-delete or --allow-dangerous", { reason: "delete.not-allowed" });
             if (flags.allowDangerous)
                 action.setOptionValue("allowDelete", true);
         }
@@ -596,12 +633,14 @@ export const createProgram = (options = {}) => {
                     "memories extract",
                     "sync",
                 ].includes(words)))
-            throw new CliError("permission_error", "this command may require network access; --offline was requested");
+            throw new CliError("permission_error", "this command may require network access; --offline was requested", {
+                reason: "offline.refused",
+            });
         if (flags.dryRun &&
             path[0] !== "api" &&
             !["files", "comments", "permissions", "revisions", "shared-drives"].includes(path[0] ?? "") &&
             !["documents get", "documents create", "documents update", "documents history"].includes(words)) {
-            output({ dryRun: true, command: words, mutates, local: metadata.local === true });
+            output({ dry_run: true, command: words, mutates, local: metadata.local === true });
             throw new Preview();
         }
         if (words === "session start")