@scribed/cli 0.1.0 → 0.1.2

package/README.md

@@ -25,6 +25,22 @@ 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.
@@ -163,9 +179,9 @@ scribed logout                         # revoke the session + clear the stored c
 scribed config                         # config path + effective settings
 
 # The full catalog (docs + execution):
-scribed tools list [--category core|all|<slugs>]   # discover tools (name, category, scope)
-scribed tools categories                           # category slugs + core/opt-in
-scribed tools show <name>                          # description + JSON schema
+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
@@ -205,6 +221,10 @@ scribed --upload-api-url https://scribed-api.fly.dev call transcription_upload -
 # 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;
@@ -269,7 +289,7 @@ scribed leads import leads.csv [--map …] [--set …] [--ai] [--dry-run] | lead
 # 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)
-scribed packs uninstall sales --yes    # pack_uninstall (archives the pack's pages + collections; records stay)
+# (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)
@@ -372,7 +392,7 @@ scribed credentials versions <itemId>                           # credentials_it
 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 a write-scoped API key always reach them (and /v1 never replays their answers from its idempotency cache).
+# `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
@@ -443,7 +463,7 @@ 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`. 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.
+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:
 
@@ -481,23 +501,65 @@ The hosted adapter signs each catalog-derived loopback request with a short-live
 
 ## Personal-key HTTP API
 
-Backend scripts that do not need the CLI or MCP can create a read-only or read/write key in **Settings → API keys** and call the same catalog at `https://app.scribed.ai/v1/tools`. Discovery, JSON schemas, validation, execution, and HMAC provenance reuse this package's catalog adapter; there is no parallel REST contract, and personal keys cannot authenticate private `/api/*` routes.
+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 https://app.scribed.ai/v1/tools/objects_records_list \
-  -H "Authorization: Bearer $SCRIBED_API_KEY"          # description + JSON input schema
-
-curl -X POST https://app.scribed.ai/v1/tools/objects_records_list \
+curl -X POST https://app.scribed.ai/v1/tools/workspaces_list \
   -H "Authorization: Bearer $SCRIBED_API_KEY" \
   -H "Content-Type: application/json" \
-  -H "X-Workspace-Id: <workspace uuid>" \
-  --data '{"pack":"sales","key":"contacts"}'
+  --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"
 ```
 
-Contract: the body is the tool's arguments object (validated against the same schema `scribed tools show` prints); success is `200 { tool, result, requestId }`; failures are `{ error: { code, message }, requestId }` (plus `toolStatus` when the upstream tool failed) with codes such as `invalid_api_key` (401), `insufficient_scope` (403), `tool_not_found` (404), `invalid_arguments` (400), `invalid_json` (400), `idempotency_key_required` (400), `idempotency_conflict` (409), `request_too_large` (413 — bodies are capped at 64 MiB, with smaller per-tool decoded file limits), `rate_limit_exceeded` (429 — 120 requests per minute per key), `tool_request_failed` (the upstream tool's own 4xx / 503, sanitized), and `tool_execution_failed` (502). Every response carries `X-Request-Id`. Write tools additionally require an `Idempotency-Key` header (8–200 printable characters; the CLI sends a random UUID) — a replay with the same arguments returns the recorded response with `Idempotency-Replayed: true`. A read-only key sees and may call only read tools. `X-Workspace-Id` scopes workspace-bound tools (400 `invalid_workspace_id` unless a UUID); a key pinned to a workspace always acts there and refuses a different header with 403 `api_key_workspace_mismatch`.
+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
 
@@ -511,8 +573,8 @@ Contract: the body is the tool's arguments object (validated against the same sc
 - 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.
-- `npm pack --dry-run --ignore-scripts` — inspect the publish tarball
-- 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 appears automatically on the CLI, MCP and API-key surfaces.
+- 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