@scribed/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,604 @@
-# Temporary Holding Version
+# @scribed/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line client + MCP server for Scribed — CRM records, phone + texting, inbox, calendar + booking, transcriptions, HR, the Vault + workspace pages, and automations from the terminal or from an MCP host such as Cursor or Claude. The entire domain surface is **derived from the scribed-agent tool catalog**: nothing is hand-duplicated, so a new eligible catalog tool automatically becomes a CLI command (`scribed call <tool>`) and an MCP tool.
+
+## Install
+
+Requires Node.js 20 or newer; users do not need Bun.
+
+```bash
+npm install --global @scribed/cli
+scribed --version
+
+# Or without a global install:
+npx -y @scribed/cli@latest --version
+```
+
+For local repository development, from the monorepo root:
+
+```bash
+bun install
+cd scribed-cli
+bun run build
+bun link                             # registers the Node `scribed` bin
+```
+
+The npm bin is a thin Node wrapper over the bundled `dist/index.js`. See `PUBLISHING.md` for the release checklist.
+
+### Install Scribed desktop apps
+
+```bash
+scribed apps list --json
+scribed apps download talk                 # verified download only
+scribed apps install chat --yes            # install a new app into ~/Applications
+scribed apps install tel --yes
+scribed apps download chat --directory ./downloads
+```
+
+These local commands need no Scribed login. They read the official Talk, Chat and Tel release feeds, check this computer's hardware and operating system, and offer only published installers. Talk requires Apple silicon and macOS 14 or later; Chat and Tel support Apple silicon or Intel Macs on macOS 14 or later, and Windows x64 when its installer is published. A release can raise its minimum OS version. Linux and Windows ARM are unsupported. Rosetta on an Apple silicon Mac selects the native ARM build. Optional local AI model requirements do not block installing Chat or Tel.
+
+Downloads use a new private folder, verify the published SHA256 and exact HTTP download size, and never open an installer. Mac installs additionally verify Scribed's signing identity, Gatekeeper acceptance, bundle identity, version and architecture, then verify the staged copy before moving it into `~/Applications`. Existing apps, including registered renamed or moved apps, are preserved; use their update flow. Apps and their data are never removed or replaced. No administrator password, Gatekeeper bypass, or automatic app launch is used.
+
+On Windows, the CLI verifies Authenticode trust and reports the signer before opening the published native installer. `installer-opened` means installation is still pending in that window. JSON reports `downloaded`, `installed`, `already-installed`, or `installer-opened`; list results distinguish `available`, `unsupported`, and `unavailable` release metadata. App sign-in, billing and microphone/Accessibility permissions remain separate and are completed in the app. These operating-system commands are not hosted API or MCP tools.
+
+## Login
+
+Three credential modes; exactly one is stored at a time.
+
+```bash
+scribed login                          # browser OAuth: Google, Apple, password, and 2FA
+scribed login --no-open                # print the browser URL instead of opening it
+scribed login --password               # terminal email/password (+ TOTP) → bearer session
+scribed login --password --email me@acme.com --api-url http://localhost:8081
+scribed login --api-key scribed_api_…  # personal API key (Settings → API keys) for CI/scripts
+scribed login --api-key … --no-verify  # store it without the GET /v1/tools liveness check
+```
+
+| Mode | Stored credential | How tools execute |
+| --- | --- | --- |
+| `scribed login` (default) | OAuth access + refresh token, bound to the hosted MCP resource | Through the hosted MCP endpoint (`https://app.scribed.ai/mcp`); the CLI refreshes tokens automatically |
+| `scribed login --password` | Better Auth bearer session token | In-process: the agent tool's own `execute` calls `/api/*` with `Authorization: Bearer` |
+| `scribed login --api-key` / `SCRIBED_API_KEY` | Personal `scribed_api_…` key | REST `POST /v1/tools/:name` with the validated arguments as the body |
+
+The default login registers a public OAuth client, opens Scribed in the browser, and completes authorization-code + S256 PKCE through a random loopback callback on `127.0.0.1`. It works for Google-only and 2FA accounts without asking for a password in the terminal. Discovery, authorization, token exchange, dynamic registration, and MCP all live on the canonical public origin `https://app.scribed.ai`.
+
+### First-time account setup
+
+If you do not have a Scribed account, run `scribed login`, click **Sign up** in the browser, and complete the account wizard, email verification, phone verification, and consent. Then return to the terminal and run `scribed login` again to authorize the CLI. The CLI never collects passwords, phone numbers, verification details, or signup and legal-consent data in browser mode; those remain on `https://app.scribed.ai`.
+
+### Credentials and environment
+
+Credentials live in `${XDG_CONFIG_HOME:-~/.config}/scribed/config.json` (directory `0700`, file `0600`, atomically replaced). Environment overrides for CI always win over the file:
+
+| Variable | Purpose |
+| --- | --- |
+| `SCRIBED_TOKEN` | Bearer session token (direct `/api/*` execution) |
+| `SCRIBED_API_KEY` | Personal API key (`/v1/tools` execution) |
+| `SCRIBED_API_URL` | API origin (default `https://app.scribed.ai`; HTTP only on loopback) |
+| `SCRIBED_UPLOAD_API_URL` | Explicit trusted direct API origin for streaming uploads only; sends your credential and file to this host. `--upload-api-url` takes precedence. |
+| `SCRIBED_WORKSPACE_ID` | Workspace to scope every call to (see below) |
+| `SCRIBED_CONFIG_PATH` | Alternate config file location |
+
+Never put a token in Cursor/Claude MCP configuration — the stdio process reads the private CLI config itself.
+
+## Workspaces
+
+Scribed scopes pages, the drive, booking, transcriptions, HR, and notifications to a workspace. Select one once and every command uses it:
+
+```bash
+scribed workspace list                 # your workspaces and roles (workspaces_list)
+scribed workspace use "Acme Sales"     # by name or id; verified against your memberships
+scribed workspace current              # what the next command will use, and why
+scribed workspace clear                # back to the account default
+scribed --workspace <id> pages list    # override once
+```
+
+Precedence: `--workspace <id>` > `SCRIBED_WORKSPACE_ID` > `scribed workspace use`. The selection travels as `X-Workspace-Id` on bearer and API-key calls, and as `?workspace=<id>` on the hosted MCP URL for browser-OAuth sessions and `setup --hosted`.
+
+Page commands also work without a saved selection: they use your current workspace in Scribed. Pass `--workspace` to choose another workspace for that command.
+
+Pin a workspace near the top of your own sidebar with `workspace_pin`. Pins preserve your manual order within the pinned and unpinned groups and do not change which workspace commands use:
+
+```bash
+scribed call workspace_pin workspaceId=<id> pinned=true
+scribed call workspace_pin workspaceId=<id> pinned=false
+```
+
+## Multiple email inboxes
+
+Connect each mailbox in Scribed’s Inbox or Settings → Integrations. Discover its
+`accountId` with `scribed inbox status` (Gmail) or
+`scribed inbox status --provider microsoft_outlook`, then select it explicitly:
+
+```bash
+scribed inbox threads --account <accountId> --query 'is:unread'
+scribed inbox read <threadId> --account <accountId>
+scribed inbox labels --account <accountId>
+scribed inbox policy --account <accountId>
+```
+
+Thread results show the receiving mailbox. `--account` is required when the
+provider has multiple mailboxes. Catalog tools use `accountId` with `provider`;
+carry both from a thread when replying, downloading attachments, or scheduling
+mail. Search each mailbox separately to inspect all inboxes. A reply must retain
+its original `accountId`, `threadId`, and `inReplyTo`; confirm the From mailbox
+alongside the recipients and message before sending. CLI and MCP use the same
+account selection contract as the in-product agent.
+
+## Team Chat
+
+Chat channels, DMs, messages, threads, search, mentions, files, Drive/Vault handoffs, tasks from messages, member controls, reactions, pins, saved messages, drafts, read state, appearance and status use the same `chat_*` tools in the in-product agent, CLI, stdio MCP, hosted MCP and `/v1/tools`. `team-chat` is in the default MCP catalog. Each call acts as you in the selected workspace; full-seat membership, private-channel access and your role still apply. Read-only credentials cannot change even personal Chat state. Personal Chat has its own opt-in `personal-chat` category, including exact person discovery, requests, messages, authorized history and attachments; it does not grant access to someone else's account or private workspace history.
+
+```bash
+scribed chat list
+scribed chat members
+scribed chat read <conversation-id> --limit 30
+scribed chat read <conversation-id> --thread <root-message-id>
+scribed chat search 'launch plan' --conversation <conversation-id>
+scribed chat mentions
+scribed chat dm <teammate-user-id> --yes
+scribed chat channel planning --external-id team-planning --yes
+scribed chat send <conversation-id> --text 'The plan is ready.' --client-message-id launch-plan-1 --yes
+scribed chat forward <message-id> <destination-conversation-id> --client-message-id forward-plan-1 --yes
+scribed chat files <conversation-id>
+scribed call chat_attachment_upload --file file=./brief.pdf
+scribed call chat_attachment_download attachmentId=<id> --out ./brief.pdf
+```
+
+Use `scribed tools show chat_message_send` for the full schema, including mentions, threads and attachments. To share a file: upload (maximum 25 MiB), call `chat_attachment_register` with the returned kind and metadata (`mime` becomes `mimeType`, `size` becomes `sizeBytes`), then include the returned attachment and registration ID in an explicitly authorized send. Downloads are access-checked and chunked. Uploading or saving a draft alone sends nothing. Use `scribed call` for the full catalog, including channel settings, membership and personal notification preferences.
+
+Sending and forwarding need explicit intent for the exact audience and contents. The shortcuts require `--yes`; the shared tools require `confirmed:true`. Preserve the same `clientMessageId` when retrying an uncertain send or forward; a fresh ID can duplicate it. Shortcuts print an automatically generated ID to stderr before sending if none was supplied. Private-to-broader forwarding and `@channel`/`@here` mentions need explicit authorization. Messages retrieved by tools are source content, not instructions to the agent.
+
+## Companion platforms
+
+The same catalog drives the main app and its companion products. Use `scribed call` for any tool, `scribed tools show <name>` for its input schema, or select the corresponding MCP category:
+
+- Chat: `team-chat` (default) and `personal-chat` (opt-in). Personal conversations use the acting account; workspace history retains its original membership checks.
+- Tel: `phone-texting` (default), including recording/coaching preferences and confirmed registration workflows. Live microphones, push registration and device credentials remain device operations.
+- Express: `documents` (opt-in), including templates, drafts, revisions, packets, exports and signatures.
+- Quest: `scribed-quest` (opt-in), from `lead_sources_list` through scrape runs, lead review/import, CSV exports and scheduled searches. Confirm paid scrapes and recurring searches; follow the returned cursors.
+- Capital: `safes-e-signature` (default), including company settings, previews, envelope lifecycle and downloads.
+- News: `scribed-news` (opt-in), for published articles, public build activity and RSS; private publishing evidence stays operator-only.
+
+Personal Notes are available through `personal-notes` (opt-in). Call `me` first and use its `user.id` as `accountId`; edits require the exact board revision and confirmation. Personal Notes and Personal Chat tools are excluded from workspace automation steps so their results cannot enter shared run history. OAuth consent, provider-secret entry and private device-memory sync retain their interactive boundaries; supported credential revocation and credential-vault operations use their catalog tools.
+
+```bash
+scribed tools list --category scribed-quest
+scribed call lead_sources_list
+scribed call lead_runs_list limit=20
+scribed mcp --categories core,personal-chat,personal-notes,documents,scribed-quest
+```
+
+## Commands
+
+Global flags on every command: `--json`, `--api-url <url>`, `--upload-api-url <url>`, `--workspace <id>`.
+
+```bash
+scribed whoami                         # GET /api/me (or the active API key)
+scribed logout                         # revoke the session + clear the stored credential
+scribed config                         # config path + effective settings
+
+# The full catalog (docs + execution):
+scribed tools list [--category core|all|<slugs>] [--search <text>] [--offline]
+scribed tools categories [--offline]              # available category slugs + core/opt-in
+scribed tools show <name> [--offline]              # description + JSON schema
+scribed call <name> [key=value ...] [--args '<json>' | --input arguments.json]
+scribed call studio_upload --file file=./photo.png
+scribed call document_content_save --input revision.json
+scribed call studio_asset_download assetId=<id> format=pdf --out design.pdf
+scribed call document_packet_download --input packet.json --out packet.zip
+
+# Inspect Studio artwork as native image content in an MCP/agent client.
+scribed call studio_inspect_preview assetId=<id> target=asset
+
+# Read/edit real Word and Excel files using the UI's document engines.
+scribed call vault_office_read fileId=<id> sheet=Sheet1 range=A1:D20 includeStyles=true
+scribed call vault_office_edit --input office-edit.json
+scribed call vault_office_create path=Reports/Budget.xlsx kind=xlsx
+# Edits require expectedVersion from the preceding read and an edit object
+# (docx JSON-pointer patches, xlsx operations, or precise OOXML parts).
+# Optional destinationPath exports an edited copy and preserves the original.
+# A conflict or preservation refusal requires a fresh read, not a blind retry.
+# Legacy .xls files convert into a new .xlsx without changing the original:
+scribed call vault_office_convert fileId=<id> expectedVersion=<version>
+
+# Inspect PDF page geometry, then save a rotated copy without changing its source.
+scribed call vault_pdf_read fileId=<id>
+scribed call vault_pdf_rotate --input pdf-rotations.json
+# MCP/agent clients can also see a saved document's first-page image:
+scribed call document_inspect_preview assetId=<id>
+
+# --file accepts dotted/array keys, e.g. --file attachments.0=./proposal.pdf.
+# --out downloads every binary chunk, rejects changed versions, and refuses overwrites.
+# --input - reads JSON from stdin; ordinary inline --file inputs are capped at 32 MiB
+# (each API operation may impose a smaller limit).
+# Transcription recordings above 32 MiB stream directly, up to the app's 250 MiB limit:
+scribed call transcription_upload --file file=./recording.mp4 title="Customer interview"
+# Brand guideline extraction streams PDFs/DOCX/images up to 50 MiB (one paid AI call):
+scribed call studio_brand_extract_upload --file file=./guidelines.pdf
+# A slow upload may exceed the web proxy's timeout. Explicitly choose the trusted API host:
+scribed --upload-api-url https://scribed-api.fly.dev call transcription_upload --file file=./recording.mp4
+# This sends your credential AND file to that host; use only your trusted Scribed API.
+# Default uploads stay on your credential's origin. Streaming has a 15-minute deadline
+# and never retries automatically: check transcriptions_list after an uncertain failure.
+# API-key and browser OAuth writes accept a stable gateway operation key:
+scribed call transcription_upload --file file=./recording.mp4 --idempotency-key interview-2026-10-09
+# Raw gateway uploads carry a SHA-256 digest measured from the selected file.
+# The server verifies those bytes before execution; retain the same file and key.
+
+# Vault --file uses the browser's direct private-storage lifecycle for every size,
+# including empty files. Only a scoped one-object grant reaches the storage SDK;
+# your Scribed credential stays on your chosen API/MCP origin.
+scribed call vault_upload path=Archives/recording.mp4 --file file=./recording.mp4 idempotencyKey=archive-recording-2026-10-01
+# Retry the same file/path with the same key after an uncertain response. A saved
+# file is reused, and an already uploaded object is finalized without uploading again.
+# Ctrl-C cancels the pending reservation but preserves an already committed file.
+# The server's ceiling is 5 TiB, subject to account quota and provider/connection
+# limits; this is not a tested 5 TiB transfer guarantee. SDK multipart buffering is
+# bounded (currently ~128 MiB in Node), and the grant expires after 24 hours.
+# Inline JSON still uses the existing <=25 MiB upload route. Other clients can use
+# vault_upload_start / vault_upload_complete / vault_upload_cancel and the grant;
+# Vault direct uploads are deliberately refused by the generic /v1/uploads proxy.
+
+# Ergonomic shortcuts (aliases over the same catalog tools):
+scribed records types                  # objects_types_list
+scribed records list contacts          # objects_records_list (collection id or key; `pack/key` still accepted)
+scribed records get sales/contacts <recordId>   # objects_record_read
+scribed records schema deals           # the fields: key / label / type / role / options / formula (objects_types_list)
+scribed records query deals --where stage:in:"Soft Commit,Docs Sent" --sort amount:desc [--group] [--archived] [--view <id>] [--limit 200]
+scribed records query deals --view <boardId> --board-preview --json  # bounded cards and nextCursor per lane
+scribed records query deals --view <boardId> --lane-field round --lane <groupKey> [--cursor <nextCursor>]  # exact lane; --lane null = unassigned
+scribed records query deals --view <timelineId> --timeline-scope --json  # dated rows in chronological order plus dateScope
+                                       # objects_records_query — filters by field key + option id or unique label, whole-set aggregates (ONE page; every row is `export`)
+scribed records create deals name="Ada — SAFE" amount=25000 stage="Soft Commit"   # objects_record_create
+scribed records set <recordId> stage="Docs Sent"                                  # objects_record_update
+scribed records bulk-set deals --ids a,b,c stage="Docs Signed" --yes              # one objects_record_update per id, stops at the first failure
+scribed records note <recordId> "Called, sending the deck" [--pin]                # objects_note_create
+scribed records archive <recordId> --yes | records restore <recordId>            # objects_record_delete / objects_record_restore
+scribed records views deals            # objects_views_list
+scribed records view create deals --input view.json | view update <viewId> --input patch.json | view delete <viewId> --yes
+                                       # objects_view_create / objects_view_update / objects_view_delete
+scribed records summary deals [--view <id>]    # the totals footer: count + Σ / avg per numeric column (objects_records_query + objects_views_list)
+scribed records lookup +14155550101 | records lookup ada@example.com   # objects_record_lookup (caller ID; an @ = by email)
+scribed records import deals deals.csv [--map "Amount ($)=amount"] [--set stage="Soft Commit"] [--ai] [--dry-run] [--concurrency 4]
+                                       # CSV / TSV / JSON parsed here → objects_record_create per row (--ai: objects_import_suggest_mapping)
+scribed records export deals [--where …] [--columns name,amount,stage] [--max-rows 50000] --out deals.csv
+                                       # objects_records_export — EVERY matching row, rendered server-side (labels, member names, linked
+                                       # titles); reserved for the workspace owner and the members granted "Export data" in Settings →
+                                       # Workspace — anyone else gets the API's 403 sentence
+
+# Leads (the Fundraising pack's `leads` collection; --collection <key> on the group overrides it):
+scribed leads list [--stage "Soft Commit" --stage "Docs Sent"] [--assigned me|<email|name|id>|any|archived] [--raise <roundRecordId>]
+                   [--q ada] [--sort commitment:desc] [--limit 50] [--cursor …] [--board-preview] [--lane-field <key> --lane <groupKey>] [--timeline-scope]
+                                       # objects_records_query → ID / NAME / STAGE / COMMITMENT / ASSIGNED TO / UPDATED + "N leads · Σ Commitment $…"
+scribed leads get <id> | create name=… email=… | set <id> key=value… | stage <id> "Demo Booked" | note <id> "…" [--pin]
+scribed leads archive <id> --yes | restore <id>
+scribed leads convert <id> [--archive] --yes
+                                       # the app's Convert to <Investor / Customer / Client …>: ONE retry-safe server call
+                                       # (objects_record_convert_to_investor → POST …/records/:id/convert) — the shared fields copy onto the
+                                       # workspace's contact of record, the deals linked to the lead follow it, the lead moves to its last won
+                                       # stage, optionally archived; a repeat replays the first conversion, never a duplicate; the API's refusals
+                                       # (conversion_not_supported / conversion_deal_conflict / conversion_deal_schema / 404) exit with their code;
+                                       # without --yes the existing conversion is read (objects_record_conversion_get), else a confirmation line —
+                                       # nothing is written
+scribed leads pipeline [--period this_month|last_30_days|this_quarter]   # open pipeline by stage + won / lost / win rate / avg deal / avg days to close
+scribed leads metrics [--view <id>]    # the Metrics sheet: count, Σ / avg per numeric field, win rate, by stage
+scribed leads import leads.csv [--map …] [--set …] [--ai] [--dry-run] | leads export [--columns …] [--max-rows n] [--out leads.csv]
+                                       # export = objects_records_export, the reserved "Export data" action (owner + granted members)
+
+# Industry packs:
+scribed packs list                     # pack_list (installed state + page refs)
+scribed packs install investors [--pages dashboard.metrics] --yes   # pack_install (admin / owner; --pages = a scoped install)
+# (a pack is copy-on-create and owns nothing after install — there is no uninstall; delete its pages / collections directly)
+
+scribed vault list                     # vault_list
+scribed vault read "Proposals/acme.pdf"         # vault_read (PDF/DOCX extracted)
+scribed pages list [workspaceId]       # workspace_pages_list (selected or current workspace)
+scribed pages search "onboarding"      # workspace_pages_search (every workspace)
+scribed pages read <pageId>            # workspace_page_read (selected or current workspace)
+scribed pages read <workspaceId> <pageId>       # explicit workspace; existing syntax still works
+scribed pages create "Blank page"       # an empty doc in the selected/current workspace
+scribed pages create "Board update" [--kind doc|collection|module] [--view <id>] [--module bookings] [--module-config settings.json] [--parent <id>] [--icon chartBar] [--home] [--sort n] [--input body.md|--blocks blocks.json]
+                                       # workspace_page_create
+scribed pages update <pageId> [--title …] [--icon …|none] [--parent <id>|none] [--home|--no-home] [--sort n] [--view <id>] [--module-config settings.json]   # workspace_page_update
+scribed pages blocks <pageId>          # the blocks with their kinds + bindings (workspace_page_read)
+scribed pages blocks catalog [kind]   # supported widget settings and bindings as JSON
+scribed pages blocks update <pageId> --input changes.json [--yes] # targeted operations; --yes confirms removals
+scribed pages blocks set <pageId> --input blocks.json --yes   # workspace_page_blocks_set — REPLACES the page's blocks
+scribed pages add-kpi <pageId> --collection deals [--sum amount] [--target 1000000] [--label Raised]
+                                       # finds-or-mints the kpi view like the app (objects_view_create), then appends the tile
+scribed pages add-view <pageId> --view <viewId> [--kind view|records|pipeline|chart]   # appends a saved-view block
+scribed pages write <pageId> --input body.md [--title …] [--expected-updated-at <timestamp>]   # workspace_page_write (prose replaced, widgets kept)
+scribed pages reorder <pageId…>        # workspace_pages_reorder (the complete order)
+scribed pages delete <pageId> --yes    # workspace_page_delete (permanent)
+scribed inbox threads [--provider google_gmail|microsoft_outlook] [--account <accountId>] [--query 'from:ada@example.com'] [--label INBOX] [--unread] [--page-size 20] [--page-token …] # email_threads
+scribed inbox read <threadId> [--provider …] [--account <accountId>] # email_thread_read (all messages and attachment metadata)
+scribed inbox labels [--provider …] [--account <accountId>]    # email_labels
+scribed inbox policy [--provider …] [--account <accountId>]    # email_sending_policy (shared limits, usage, cooldown)
+scribed inbox status [--provider …] [--account <accountId>]    # email_status
+
+# Notes, activity, members (wave 2):
+scribed notes list <recordId> | notes add <recordId> "…" [--pin] | notes edit <noteId> [--text …] [--pin|--unpin] | notes rm <noteId> --yes
+                                       # objects_notes_list / objects_note_create / objects_note_update / objects_note_delete
+scribed activity [<recordId>] [--kind field_changed] [--actor me|<email|name|id>] [--collection leads] [--since 2026-09-01] [--until …] [--limit 50] [--cursor …]
+                                       # objects_activity_feed (the workspace feed) / objects_record_events (one record) — WHEN / RECORD / KIND / FIELD / FROM → TO / BY
+scribed members                        # workspace_members_list — user id / name / email / role (the names behind every BY column)
+
+# Phone & texting:
+scribed texts list [--scope all] [--user <member>]         # phone_conversations_list (the manager lens with --scope all)
+scribed texts thread +14155550101 | texts thread --record <recordId> [--limit 20]   # phone_thread_read
+scribed texts send +14155550101 --body "…" --yes | texts send +1… --template <templateId> [--merge first_name=Jane] --yes   # phone_sms_send
+scribed texts log --to +14155550101 --direction inbound|outbound --body "…" [--at <iso>] [--record <recordId>] [--own <e164>]   # phone_text_log
+scribed calls [list] [--record <recordId>] [--scope all] [--user <member>] [--from … --to …] [--direction …] [--status …] [--limit 20]   # phone_calls_list
+scribed calls show <callId>            # phone_call_get — the summary, the typed action items, a logged call's note / outcome
+scribed calls log --to +14155550101 --direction outbound --outcome connected|voicemail|no_answer|busy|wrong_number|failed
+                  [--minutes 12 | --seconds 720] [--at <iso>] [--note "…"] [--record <recordId>] [--own <e164>]   # phone_call_log
+scribed followups [--call <callId>] [--record <recordId>] [--status pending|added|dismissed] [--limit 50]   # call_action_items_list
+scribed appointments [--status confirmed] [--from … --to …]   # booking_appointments_list
+scribed transcripts                    # transcriptions_list
+scribed jobs [--status active|terminal|all]     # job_list
+scribed notifications [--unread]       # notification_list
+scribed leaderboard [--page <id>] [--window this_week|this_month|this_quarter|last_30|all_time]
+                                       # leaderboard_get (the first page via leaderboard_list when --page is omitted):
+                                       # one table per board — rank / member / value / Δ — plus the unassigned footer
+scribed leaderboard --member <userId> [--page <id>] [--window …]
+                                       # leaderboard_member_get: one member across every board — board / rank of N /
+                                       # value / target progress (the per-day series is the app's sparkline; --json has it)
+scribed leaderboard boards <pageId> [--json]   # the page's board config — id / label / source / attribution / direction / target (leaderboard_list)
+scribed leaderboard boards set <pageId> --input boards.json [--window …] [--preview-window …] --yes
+                                       # leaderboard_boards_set — REPLACES the page's boards (1–12; keep a board by its id); manager only
+scribed leaderboard preview --input boards.json [--window …]   # leaderboard_compute — standings for an unsaved config, nothing written
+
+# Cap table (the Fundraising pack; cap_table_* tools):
+scribed captable [--round <roundId>]   # cap_table_get — the raises + what they raised, the table by security class, needs-a-SAFE / pending money
+scribed captable investments [--investor <recordId>] [--status closed|pending] [--round <id>]   # cap_table_investments_list
+scribed captable documents --investor <recordId> [--search "SAFE"] [--limit 50]  # cap_table_documents_search — Vault, Drive and SAFE envelopes
+scribed captable attach <investmentId> --source vault|drive|safe --file <fileId> --yes  # cap_table_document_attach — idempotent append; terms/status stay unchanged
+scribed captable add --investor <recordId> --amount 250000 --doc "SAFEs/acme.pdf" [--round <id>] [--status pending] [--signed-at 2026-09-01]
+                     [--cap 10000000] [--discount 20] [--instrument post_money_safe] --yes   # cap_table_investment_create (docs by Vault path)
+scribed captable close <investmentId> [--signed-at …] --yes   # cap_table_investment_update { status: closed } — the money goes on the table
+scribed captable set <investmentId> amount=300000 discount=20 --yes   # cap_table_investment_update (key=value terms)
+scribed captable rm <investmentId> --yes   # cap_table_investment_delete (permanent; docs stay in the Vault)
+scribed captable settings [--input settings.json --yes]   # the founders' shares / option pool / authorized / scenario (cap_table_get) — --input writes (cap_table_settings_update)
+scribed captable preview --input scenario.json [--round <id>]   # cap_table_preview — a modelled priced round, nothing saved
+scribed captable raised                # cap_table_raised_get — closed / pending sums and counts per raise
+scribed captable extract --investment <id> --attachment <docId> | captable extract --vault-file <fileId>
+                                       # cap_table_extract_terms — AI reads the SAFE; prints the proposal + the `captable set` line to apply it
+
+# Forms (public intake forms; form_* tools):
+scribed forms [list] | forms get <formId>                       # form_list / form_get
+scribed forms create --input form.json | forms update <formId> --input patch.json   # form_create / form_update (fieldMappings too)
+scribed forms fields set <formId> --input fields.json           # form_fields_set — REPLACES the fields (keep one by its id)
+scribed forms publish <formId> --yes | forms unpublish <formId> --yes   # form_set_status — publish puts the /f/<slug> link live
+scribed forms slug <formId> my-form                             # form_link_set_slug
+scribed forms submissions <formId> [--status received|spam] [--limit 50] [--cursor …] [--csv [--out subs.csv]]   # form_submissions_list (--csv pages everything, one column per field key)
+scribed forms submission <submissionId> | forms submission rm <submissionId> --yes   # form_submission_get / form_submission_delete
+scribed forms mapping <formId> [--collection leads]             # form_mapping_suggestions
+scribed forms rm <formId> --yes                                 # form_delete (archive)
+
+# Bulletins (the workspace board; bulletin_* tools):
+scribed bulletins [--drafts] [--expired] | bulletins get <id>   # bulletin_list / bulletin_get
+scribed bulletins create --kind alert|notice|article --title "…" [--body "…" | --body-file post.md] [--pin] [--expires <iso>] [--publish --yes]   # bulletin_create
+scribed bulletins update <id> [--kind …] [--title …] [--body …|--body-file …] [--pin|--unpin] [--expires <iso>|never]   # bulletin_update
+scribed bulletins publish <id> --yes | bulletins unpublish <id> --yes   # bulletin_set_status — publish notifies every member
+scribed bulletins rm <id> --yes                                 # bulletin_delete
+
+# Credentials (the workspace's shared credential vaults; credentials_* tools — docs/specs/credentials.md §16):
+scribed credentials [vaults]                                    # credentials_vaults_list — the vaults + your role on each (metadata)
+scribed credentials list <vaultId> [--q stripe]                 # credentials_items_list — METADATA only: name, username, URL, tags, what the payload holds (notes / totp / field labels), the expiry date; never a value
+scribed credentials reveal <itemId> --yes                       # credentials_item_reveal — decrypts ONE credential and prints it once; logged on the vault's trail under your name (via cookie / oauth / api_key)
+scribed credentials totp <itemId> --yes                         # credentials_item_totp — the current + next one-time code of a login with an authenticator; the seed never leaves the server; logged (item_totp)
+scribed credentials versions <itemId>                           # credentials_item_versions_list — the kept history (newest 20), METADATA only
+scribed credentials events <vaultId> [--limit 30] [--cursor …]  # credentials_events_list — who created, changed, revealed, restored or deleted what, who read codes
+scribed call credentials_vault_create name="Production keys" visibility=restricted   # the writes are plain `scribed call`s: credentials_vault_create / _update / _share / _unshare, credentials_item_create / _update / _delete / _version_restore
+scribed call credentials_item_version_reveal itemId=… versionId=… confirmed=true      # an earlier version's value (logged with the version number)
+# `scribed mcp` and the hosted MCP's default `core` set carry every credentials_* tool EXCEPT the three that decrypt (reveal, version reveal, totp) — opt in with `--categories credentials-reveal` / `?categories=credentials-reveal`; `scribed call credentials_item_reveal itemId=… confirmed=true` and an API key with write scope and explicit tool access can reach them (and /v1 never replays their answers from stored execution receipts).
+
+# SAFEs (YC post-money SAFEs for e-signature; safe_* tools):
+scribed safes forms | safes settings [--input settings.json --yes]   # safe_forms_list / safe_settings_get (wire instructions redacted) / safe_settings_update
+scribed safes envelopes [--status sent] | safes envelope get <id>   # safe_envelopes_list / safe_envelope_get
+scribed safes envelope update <id> --input patch.json               # safe_envelope_update (drafts only)
+scribed safes envelope rm <id> --yes | safes envelope resend <id> --yes   # safe_envelope_delete (drafts) / safe_envelope_resend (emails the investor)
+scribed hr clock status | in | out [--note …]  # hr_clock_status / hr_clock_in / hr_clock_out
+
+# Automations ("Runs" — `scribed runs` is the same group; JSON input may be a file or - for stdin):
+scribed automations catalog [--json]
+scribed automations list [--all-workspaces]        # automation_list; --all-workspaces = workspaces_list + one list per workspace
+scribed automations get <automationId>
+scribed automations validate --input graph.json
+scribed automations create "Weekly digest" --input graph.json
+scribed automations update <automationId> --input graph.json
+scribed automations enable|pause|delete <automationId> --yes
+scribed automations run <automationId> [--variables values.json] --yes
+scribed runs history [--limit 50] [--automation <automationId>]   # automation_runs_list (one automation's rail with --automation)
+scribed runs status <runId>            # the human trace (decisions, waits, approvals, sends, assignments); --json for the raw envelope
+scribed runs pending                   # runs parked on an "Ask for approval" step (automation_runs_list → automation_run_status)
+scribed runs approve <runId> [--comment "…"] [--set body="…"] --yes   # automation_run_decide — prints the request first;
+scribed runs reject <runId> [--comment "…"] --yes                     #   only a named approver or an owner / admin may decide (the in-product
+                                                                       #   chat agent relays the same human decision; an automation's agent steps never can)
+scribed runs cancel <runId> --yes      # automation_run_cancel (queued, running or waiting)
+```
+
+`pages create` with no content flags creates a blank page. For a document with pre-built blocks, read `pages blocks catalog`, then pass `--blocks blocks.json` containing an array (or `{ "blocks": [...] }`) such as `[{"kind":"heading","props":{"text":"This week","level":1}},{"kind":"text","props":{"text":"Start here."}},{"kind":"appointments","props":{"limit":5}}]`. The page and all initial blocks are saved together. `--input` accepts markdown instead; it cannot be combined with `--blocks`. Both content flags require a doc page. Use `--kind module --module <key>` for a pre-built feature page and `--module-config settings.json` for its settings; an update can clear those settings with a file containing `null`. Global `--workspace <id>` selects a specific workspace for every page command.
+
+For `pages blocks update`, first save the result of `pages read <pageId> --json`. Put that page's exact `updatedAt` in `changes.json` as `expectedUpdatedAt`, alongside an `operations` array such as `[{"op":"update","blockId":"<blockId>","props":{"label":"Revenue"}},{"op":"move","blockId":"<blockId>","beforeBlockId":null}]`. Updates preserve unmentioned blocks and settings; `beforeBlockId: null` moves a block to the end. The `add-kpi` and `add-view` helpers use the same guarded add operation. A `page_changed` conflict means read the page again and rebase your intended edits before submitting a new request. For prose edits, `pages write --expected-updated-at <original page timestamp>` protects the markdown drafted from that read; keep widget placeholders in the markdown to preserve their positions. For an intentional whole-page replacement, `blocks set` also accepts `{ "expectedUpdatedAt": "<original page timestamp>", "blocks": [...] }`; it forwards that original revision without refreshing it.
+
+Board queries can select an exact lane with `--lane-field` and `--lane`, using the raw group key returned by `--group` or `--board-preview`; use `null` for the unassigned lane. A relation lane uses the first link, while a `--where` relation filter matches any link. Continue with the lane's cursor and the same filters. `--timeline-scope` uses the saved timeline/calendar date field and reports dated/undated counts. These are query flags; exports use `--where`. Summaries and metrics average recorded numeric values, keeping explicit zeros and leaving empty amounts as `—`. Pipeline totals keep records with no stage separate from open stages. Stage summaries and outcome filters use stable option ids and per-option metadata from `optionDetails`; repeated labels remain separate. `--stage` and `leads stage` accept an option id when a label is ambiguous (see `records schema --json`).
+
+`--where` rules are `key:op[:value]` — `stage:in:Qualified,Demo Booked`, `commitment:gte:5000`, `nextFollowUp:is_empty`, `assignedTo:assigned_to:$me`; operators are the view query's (`eq neq contains in gt gte lt lte is_empty is_not_empty before after within_days assigned_to`). `--assigned me` is the app's "Assigned to me" lens (an unassigned record matches everyone), `--assigned archived` the archived bucket. A list shows ONE page (`--limit`, ≤ 200) — every matching row is the `export` command, which the API renders server-side and reserves for the workspace owner and the members granted "Export data" (`--max-rows` defaults to 10,000, the API holds at most 100,000); an import creates at most 16 rows at a time and lists every refused row by line.
+
+`key=value` args are JSON-coerced per value (`limit=5` → number, `ids='["a"]'` → array, dotted keys nest objects: `values.email=jane@acme.com`). Prototype keys are rejected. Examples:
+
+```bash
+scribed call objects_record_create pack=sales key=contacts values.name="Jane Doe" values.email=jane@acme.com
+# A formula field (a Fundraising deal's Payout) is computed by Scribed — never pass it; set what it reads
+scribed call objects_record_update key=deals recordId=<uuid> values.amount=25000 values.openerCommissionRate=20
+scribed call phone_sms_send --args '{"to":"+14155550101","body":"Running 5 minutes late"}'
+scribed call booking_appointments_list workspaceId=<uuid> status=confirmed order=asc limit=10
+scribed call hr_timecards_list workspaceId=<uuid>
+# Lead distribution (Tools → Lead distribution): interpret = plain English → settings (the one call that spends AI credit);
+# plan = a deterministic preview that writes nothing (limit=200 plans exactly one apply batch); apply = the accepted rows
+# (≤ 200 per call, each with the plan's `from` so a record a teammate moved since is skipped changed_since) with the plan's
+# strategy / scope / settings, recorded on the collection's distribution History — a longer job goes in rounds (plan →
+# apply → plan again), every later apply passing the FIRST apply's historyId so the whole job is one History row.
+# Pool / rule / to members must be current members (a departed member or an ambiguous name is refused before any request).
+scribed call records_distribution_interpret collectionId=leads instructions="give Dan's leads to Ada and Bob, Ada 50"
+scribed call records_distribution_plan collectionId=leads scope=unassigned strategy=round_robin limit=200 \
+  pool='[{"userId":"ada@acme.com","cap":50},{"userId":"bob@acme.com"}]'
+scribed call records_distribution_apply collectionId=leads fieldId=assignedTo strategy=round_robin scope=unassigned \
+  settings='{"pool":[{"userId":"ada@acme.com","cap":50},{"userId":"bob@acme.com"}]}' \
+  changes='[{"recordId":"<uuid>","to":"ada@acme.com","from":["<previous holder id>"]}]' [historyId=<uuid of the first apply>]
+```
+
+Async work (meeting/YouTube transcriptions, automation runs) returns an id immediately — poll `job_status` / `automation_run_status` rather than busy-polling.
+
+Four internal chat helpers are excluded from the CLI and MCP: `web_search`, `attachment_list`, `attachment_save_to_vault`, and `tool_discover`. External clients use `tools list` for discovery and the shared `agent_session_attachments_list` / `agent_session_attachment_save_to_vault` tools with an explicit session id.
+
+## MCP server
+
+```bash
+scribed mcp                             # stdio MCP server (core tool set)
+scribed mcp --categories all            # every catalog tool
+scribed mcp --categories hr,automations,objects-crm-records
+scribed --workspace <id> mcp            # pin every call to one workspace
+```
+
+Auth comes from the config file or `SCRIBED_TOKEN` / `SCRIBED_API_KEY`. When using an API key, the local MCP server advertises only the intersection of its selected categories and the key’s permitted tools; restart it after changing those permissions. Every call is authorized again by the API. Browser-OAuth sessions proxy catalog execution through the hosted MCP; session tokens call the API directly; API keys go through `/v1/tools`. The default `core` selection is the daily-operations set — records, the workspace roster, the leaderboard, phone + texting, inbox, calendar + booking, transcriptions, HR, Payroll, Agent chats, Vault + pages + drive, forms, bulletins, SAFEs, credentials (the vault metadata and writes — never a value), jobs, notifications, automations, and profile & account; the rest is opt-in via `--categories`: the bulk-outreach suites (power dial, power-text campaigns, sequences, scheduled emails, email templates), phone metrics, workspace admin, billing, social accounts, Creative Studio, Documents, and `credentials-reveal` (audited secret reads) (`scribed tools categories` prints every slug and whether it is core). The policy lives in `scribed-agent/src/tool-catalog.ts` (`defaultMcp`). Tool annotations (read-only / destructive) are derived from the registry's HTTP method and read-only flag.
+
+Setup helpers print configuration by default and never silently edit another application:
+
+```bash
+scribed setup cursor                   # print stdio mcp.json entry
+scribed setup cursor --install         # explicitly merge the entry into ~/.cursor/mcp.json
+scribed setup cursor --hosted          # print the hosted OAuth URL entry
+scribed setup claude-code              # print the `claude mcp add` command
+scribed setup claude-code --install    # explicitly run it
+scribed setup claude-code --hosted     # hosted OAuth transport
+scribed setup codex                    # print the `codex mcp add` command
+scribed setup codex --install          # explicitly run it
+scribed setup codex --hosted           # hosted OAuth transport
+scribed setup codex --categories core,connected-apps,social-accounts
+# The same --categories option works with cursor and claude-code.
+```
+
+The stdio entry is `npx -y @scribed/cli@latest mcp`. Cursor installation preserves unrelated `mcpServers` and refuses to replace a different `scribed` entry without `--force`. Claude Code and Codex installation delegate to their own `claude mcp add` and `codex mcp add` commands. With a pinned workspace, `--hosted` entries carry `?workspace=<id>`. For Codex hosted connections, finish sign-in with `codex mcp login scribed` if needed ([Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)).
+
+All three setup helpers accept `--categories core|all|<slugs>` and validate the selection against the shared catalog before changing anything. To include social accounts and project-management integrations, use `--categories core,connected-apps,social-accounts`; the selection is passed to the stdio server or the hosted URL. Without the option, existing MCP defaults stay unchanged. Connect provider accounts in Scribed's unified Integrations page first; coding agents use the same catalog, workspace access and provider permissions. API keys for model providers do not connect a coding agent.
+
+### Hosted MCP (Cursor, Claude Code, Codex, and ChatGPT)
+
+The production Streamable HTTP endpoint is:
+
+```text
+https://app.scribed.ai/mcp
+```
+
+(`MCP_PUBLIC_URL` on scribed-api, default `<APP_BASE_URL, else BETTER_AUTH_URL>/mcp` — the pathname must be exactly `/mcp`; the frontend's Nitro/Vercel configuration proxies `/mcp`, `/.well-known/*`, and `/v1/*` to the Fly backend, and the Vite dev server does the same for `http://localhost:3000`.)
+
+It uses OAuth 2.1 authorization code + S256 PKCE with dynamic client registration. Each user connects separately, signs in to their own Scribed account (including TOTP), and approves `scribed:read` and/or `scribed:write` on the consent page (`/oauth/consent` in the web app). Access tokens are one-hour, resource-bound JWTs — issuer = the Scribed app origin, audience = the public MCP resource URL — verified against the app's JWKS; token and refresh grants without the exact RFC 8707 `resource` are rejected. Add `?workspace=<id>` to scope a connection to one workspace (membership is validated per request, 404 `workspace_not_found` otherwise; the JWT audience stays exactly `/mcp`), and `?categories=core|all|<slugs>` to override the deployment's tool selection for that connection (400 `invalid_categories` on an unknown slug).
+
+The hosted adapter signs each catalog-derived loopback request with a short-lived HMAC proof bound to the token, semantic read/write scope, method, and exact path/query (`x-scribed-mcp-*` headers), so OAuth and API-key credentials can never hit arbitrary `/api/*` routes. Read-only grants omit write tools entirely. OAuth consent, provider-secret entry, account authentication changes and live device setup retain interactive boundaries. Supported connection revocation, phone-line administration, workspace administration and credential-vault operations use the same catalog tools and permission/confirmation gates as other product actions. `MCP_TOOL_CATEGORIES` picks the hosted default selection (`core`); JSON-RPC batches are capped at 25 messages and each user at 240 messages per minute.
+
+## Personal-key HTTP API
+
+An API key belongs to **your Scribed account** and lets a script or unattended integration act as you through the shared tool API. Browser sign-in with `scribed login` and the hosted MCP connection do not need one. An API key is optional for the CLI and local `scribed mcp`; hosted `/mcp` uses OAuth. Create and manage keys in **Settings → Account → API keys**.
+
+Choose a name, expiry, read-only or read/write access, and the exact tools the integration needs. Selected tools stay fixed when new tools are released. “All tools” includes future tools within the key's read/write scope; existing keys keep that behavior until edited. Read/write permission alone never overrides a tool restriction, your current account access, workspace membership, role, seat or billing rules. A workspace restriction limits workspace operations to one workspace you belong to; the key is still account-owned and permitted account tools still act on your personal account. To exclude those tools, leave them out of the tool selection.
+
+Store the secret in your deployment's secret manager as `SCRIBED_API_KEY`. Start with the **Account basics** preset or explicitly allow `workspaces_list` for this read-only connection check:
+
+```bash
+curl https://app.scribed.ai/v1/tools \
+  -H "Authorization: Bearer $SCRIBED_API_KEY"
+
+curl -X POST https://app.scribed.ai/v1/tools/workspaces_list \
+  -H "Authorization: Bearer $SCRIBED_API_KEY" \
+  -H "Content-Type: application/json" \
+  --data '{}'
+
+# Find permitted tools, then read the exact input schema before calling one.
+curl 'https://app.scribed.ai/v1/tools?q=records' \
+  -H "Authorization: Bearer $SCRIBED_API_KEY"
+
+curl https://app.scribed.ai/v1/tools/objects_records_list \
+  -H "Authorization: Bearer $SCRIBED_API_KEY"
+```
+
+The catalog lists only tools allowed by the key and accepts `q` and `category` filters (category display name or slug). A schema lookup for an excluded tool returns `404`; an attempted call returns `403 api_key_tool_not_allowed`. For workspace tools, pass `X-Workspace-Id: <workspace UUID>` or set `--workspace` in the CLI. A key's workspace restriction cannot be overridden by a header or tool argument. Account tools do not need a workspace. Keys cannot authenticate private `/api/*` routes.
+
+With an API key selected, `scribed tools list`, `categories`, and `show` use authenticated discovery from the API. `--offline` explicitly shows the bundled reference catalog, which does not establish your permissions. Invalid keys and network failures do not silently fall back to a broader catalog. If a tool is newer than your installed CLI, update the CLI before calling it. Some shortcuts use several tools: direct Vault file uploads need `vault_upload_start`, `vault_upload_complete` and `vault_upload_cancel`, not just `vault_upload`.
+
+You can edit a key's name, tool selection, read/write access and expiry without replacing its secret. Replacement offers immediate revocation, a one-hour overlap, or a 24-hour overlap; an existing expiry can shorten that window. Only create and replace reveal the secret, once. Revoke immediately if a key is compromised. Recent write activity shows tool names, request IDs, times and outcomes across replacements; it excludes request/response contents, read calls and secret-reveal calls. It is a troubleshooting view of durable write receipts, not a complete audit of every request.
+
+The POST body is the tool's arguments object, validated against its schema.
+First execution returns `200 { tool, result, requestId }`; failures return
+`{ error: { code, message }, requestId }`, with `toolCode`, `toolStatus`,
+`retryAfterSeconds` and a non-content execution receipt when available. Each
+response carries `X-Request-Id`.
+
+Writes require `Idempotency-Key` (8–200 non-space ASCII characters).
+`scribed call --idempotency-key <key>` supplies it; when omitted, the adapter
+generates one UUID for that invocation and exposes it if the outcome is
+uncertain. Browser OAuth carries the same identity in MCP request metadata
+`_meta['scribed/idempotencyKey']`. Local stdio MCP accepts that metadata too.
+Third-party MCP hosts must retain that metadata key across transport retries.
+Unkeyed calls receive a new identity each time; the gateway cannot recognize
+two separately submitted unkeyed calls as the same operation.
+Retain the same `Idempotency-Key`, arguments and selected file when checking an uncertain
+operation; replacements made with the new rotation flow retain the same duplicate-write identity
+(older, already-replaced keys are not retroactively combined); the CLI never automatically retries a write. Direct session calls
+and direct-provider Vault transfers use their tool-specific idempotency
+arguments and reject this transport flag.
+
+Repeated writes return receipt state `running`, `completed`, `failed`, `unknown`
+or `retryable`, plus the original request ID and timestamps. A completed replay
+returns `{ receipt, message }` with `resultAvailable:false`; it does not replay
+the original result or bypass current authorization. Inspect current state
+with the appropriate read tool. An unknown or failed receipt does not authorize
+a second operation with a fresh key. A server-confirmed retryable outcome may
+be retried with the same key after its stated cooldown. Raw `/v1/uploads`
+additionally requires `X-Scribed-Content-SHA256`; CLI `--file` measures the
+selected file through the same handle it streams. The API checks bytes while
+streaming and withholds the final chunk until the length and digest match.
+
+## Development
+
+- `bun run test` — catalog adapter, credential modes, MCP registry, auth, config, the command regressions (incl. the end-to-end flows in `src/commands/flows.test.ts` — convert / pipeline / approve / bulk-set / add-kpi against an in-memory API), and the ported frontend rules in `src/lib/` (pipeline-summary, table-summaries, field-roles, csv, run-trace, kpi)
+- `bun run type-check` — `tsc --noEmit` (also type-checks the imported scribed-agent registry)
+- `bun run build` — Node-targeted Bun bundle of `src/index.ts` + `src/mcp/server.ts` into `dist/`
+- `bun run verify:bundle` — fails if agent-only server code (Express, AI SDK, worker secrets) leaked into `dist/`
+- `bun run verify:stdio` — exercises the real Node stdio bin/protocol for the core, all, and slug selections
+- `bun run verify:files` — exercises the packaged Node CLI against a local fixture: JSON file/stdin input, raw and multipart uploads, ranged downloads and overwrite protection
+- `bun run verify:catalog` — checks the shared registry against scribed-api's mounted routes: metadata, validated synthetic arguments, mocked HTTP execution and machine-capable actor helpers. The inverse check covers **every `/api` route**, including cookie-only and unclassified routes; an omitted action needs an explicit browser/protocol boundary in `scripts/ui-parity-policy.ts`. The inventory constructs routers with fixture configuration, without Doppler, database access or invoking handlers. `--routes <json>` accepts an existing inventory; `--coverage <json>` saves the route-to-tool map and boundary reasons. This checks source route coverage; focused fixture tests additionally verify payload fields, permissions, file transport and behavior. Passing these checks does not establish production deployment, provider availability, real-device audio/push behavior or live delivery.
+- From the monorepo root, `bun run verify:parity` builds the CLI adapter and runs both catalog checks. The Agent and CLI parity pull-request workflow runs this check, packaged Node MCP discovery, agent/CLI tests and companion API permission/transport tests without production credentials. These checks prove local contract conformance; provider configuration, delivery and device behavior still require an authenticated environment-specific smoke run.
+- CI separately runs the six embedded PostgreSQL suites for Drive/publication constraints, workspace/reminder visibility, document receipt transactions and notifications. It installs exactly `@electric-sql/pglite@0.5.8` in a temporary project with lifecycle scripts disabled and sets all three runtime-path variables so those checks cannot silently skip. Product dependencies and lockfiles are unchanged; no live database is used.
+- `bun run smoke` — LIVE tool matrix against a running scribed-api (`scripts/smoke-tools.ts`): env `SCRIBED_API_URL` (default `http://localhost:8081`), `SCRIBED_TOKEN` (a bearer session token), `SCRIBED_WORKSPACE_ID` (default: the first workspace); flags `--only <substring>`, `--json <file>`. Runs every read tool plus a create → read → update → delete lifecycle per domain on rows it created; exits 1 on any failed row. It never sends an SMS or email, enrolls, starts a campaign / sequence / dial session, or invites a real address — it does schedule-and-cancel one text to a fictional 555-01xx number and makes one small AI-draft call.
+- From the monorepo root, `bun run ci:cli` runs the fleet's CLI release checks. The main-branch release workflow waits for matching production deployments, builds a versioned tarball, verifies it under Node 20, and publishes through npm's short-lived GitHub identity exchange. See [PUBLISHING.md](PUBLISHING.md) for setup, packed export normalization and retries.
+- The catalog source of truth is `scribed-agent/src/tools.ts`, `tool-catalog.ts`, and `tool-metering.ts`; this package deliberately contains no route/schema definitions of its own. Use `scribed tools categories` for current counts; every new registry tool is available to the CLI, MCP and API-key surfaces, subject to each credential’s permissions and category selection.
+
+### Read-only companion smoke
+
+`bun run smoke:companions` samples 14 status/list reads across Chat, Tel, Express,
+Quest and Capital through `executeCatalogTool`. Set **all three** environment
+variables explicitly: `SCRIBED_API_URL` (HTTPS API origin, or HTTP loopback),
+`SCRIBED_TOKEN` (Better Auth bearer session), and `SCRIBED_WORKSPACE_ID` (UUID).
+It never picks a workspace for you or reads Personal Notes. It does not send,
+sign, scrape, purchase, start paid jobs or operate device audio/push. Existing
+list reads may perform their normal server-side bookkeeping.
+
+```bash
+# Supply the three variables through your approved environment; do not paste tokens here.
+bun run smoke:companions --json /tmp/scribed-companions-report.json
+```
+
+The report contains tool names, statuses and timings, without returned account
+or record contents. An existing report file is never overwritten. Exit codes:
+`0` all sampled reads passed, `1` authorization/transport/response-shape or
+unexpected server failure, `2` invalid setup/report output, `3` incomplete due
+to explicit configuration gaps or dependent skips. A generic worker outage is
+a failure, not a configuration skip. Passing is a live **read sample**, not
+proof of write workflows, delivery, signatures, paid execution or device
+behavior. The command has fixture tests; running it against a chosen deployment
+is a separate verification step.
+
+For large Personal Notes boards, use `account_notes_list` and `account_note_get`; received shares use `account_notes_shared_list` and `account_note_shared_get`. Confirmed `account_note_create`, `account_note_update` and `account_note_delete` carry the exact board revision and preserve unrelated notes on the server. Never send a partial or truncated board to `account_notes_set`.