@scribed/cli 0.1.9 → 0.1.11

package/README.md

@@ -50,18 +50,20 @@ scribed login                          # browser OAuth: Google, Apple, password,
 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
+scribed login --api-key <key>          # personal API key (Settings → API keys) for CI/scripts
+scribed login --api-key <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 |
+| `scribed login --api-key <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`.
 
+`--password` requires a Scribed account with an existing password; Google-only and Apple-only accounts use browser sign-in. For API-key login, replace `<key>` with the complete `scribed_api_…` secret. Interactive users should use `scribed login`; personal API keys are for unattended CI and scripts.
+
 ### 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`.
@@ -78,24 +80,31 @@ Credentials live in `${XDG_CONFIG_HOME:-~/.config}/scribed/config.json` (directo
 | `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 |
+| `SCRIBED_NO_UPDATE_NOTIFIER` | `1` or `true` disables terminal update checks and notices |
 
 Never put a token in Cursor/Claude MCP configuration — the stdio process reads the private CLI config itself.
 
+### CLI updates
+
+After a successful interactive command, the CLI checks npm's public `@scribed/cli` latest release at most once every 24 hours and prints one line to stderr when an update is available. The check sends no Scribed credentials or command arguments. It has a 500 ms deadline; offline, malformed, or inaccessible responses stay silent and are also cached for 24 hours. The private cache lives beside the config as `config.json.update-check.json` (or `<SCRIBED_CONFIG_PATH>.update-check.json`).
+
+Checks and notices are disabled for `scribed mcp`, `--json`, CI, and whenever stdout or stderr is redirected. Disable them persistently with `scribed config --no-update-notifier`; re-enable with `scribed config --update-notifier`. `SCRIBED_NO_UPDATE_NOTIFIER=1` disables them for one environment. Notices never install anything. Update a global npm installation with `npm install -g @scribed/cli@latest`, or use the package manager that installed your CLI.
+
 ## Workspaces
 
-Scribed scopes pages, the drive, booking, transcriptions, HR, and notifications to a workspace. Select one once and every command uses it:
+Scribed scopes pages, the drive, booking, transcriptions, HR, and notifications to a workspace. Select one before using workspace tools or setting up a coding agent for workspace work:
 
 ```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 clear                # remove the saved selection
 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.
+Workspace tools require a selected workspace or an explicit `workspaceId` argument when supported. They do not fall back to a workspace from your browser session. Account tools, including personal connected-app and social-account reads, work without a workspace selection. Pass `--workspace <id>` to choose another workspace for one 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:
 
@@ -173,6 +182,20 @@ scribed mcp --categories core,personal-chat,personal-notes,documents,scribed-que
 
 Global flags on every command: `--json`, `--api-url <url>`, `--upload-api-url <url>`, `--workspace <id>`.
 
+### Every tool by area
+
+Every catalog tool also has a named command, generated from the catalog at start-up: `scribed <area> <action>`, where the area is the tool's category (`scribed --help` lists them) and the action is the tool name without its shared prefix. Arguments are `--flags` named after the tool's arguments (`--period-start`), `key=value` pairs, bare values for the required arguments in order, or one JSON object via `--args` / `--input`. String arguments stay strings (`--zip 02134`); other values are read as JSON. `--help` on any action prints its tool, whether it writes, and its arguments.
+
+```bash
+scribed payroll --help                                   # every Payroll action
+scribed payroll run-create 2026-10-01 --note "October"   # = scribed call payroll_run_create periodStart=2026-10-01 note=October
+scribed calendar --help
+scribed news entries-list --limit 5
+scribed hr --help                                        # hand-written shortcuts + the remaining HR tools
+```
+
+Where an area shares its name with a hand-written group (`hr`, `forms`, `bulletins`, `credentials`, `automations`, `notifications`), the tools that group does not already cover are added to it. A new catalog tool appears here automatically.
+
 ```bash
 scribed whoami                         # GET /api/me (or the active API key)
 scribed logout                         # revoke the session + clear the stored credential
@@ -465,7 +488,15 @@ 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:
+Sign in first. For workspace work, select the workspace before previewing setup:
+
+```bash
+scribed login
+scribed workspace list
+scribed workspace use <id>
+```
+
+Setup helpers print configuration by default. Add `--install` after reviewing it:
 
 ```bash
 scribed setup cursor                   # print stdio mcp.json entry
@@ -481,7 +512,7 @@ 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)).
+The stdio entry is `npx -y @scribed/cli@latest mcp`; it reads the CLI credentials and selected workspace. 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, so the corresponding CLI must be installed and available on your terminal's PATH. With a selected 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.
 
@@ -499,6 +530,12 @@ It uses OAuth 2.1 authorization code + S256 PKCE with dynamic client registratio
 
 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.
 
+### Dedicated Claude directory connection
+
+The directory connection uses `https://app.scribed.ai/mcp/claude`, with the same canonical tool definitions, schemas, descriptions and execution code as the CLI and general MCP server. The `claude-directory` profile removes direct payment collection, SAFE countersigning and standalone AI media generation; design workflows remain available. Its default is all supported categories. `?categories=` and account grants can narrow the catalog. See `src/mcp/claude-directory.ts` for the exact exclusions and rationale.
+
+This endpoint has separate `scribed:claude:v2:read` / `scribed:claude:v2:write` permissions and the exact OAuth resource `https://app.scribed.ai/mcp/claude`. Clients discover these at `/.well-known/oauth-protected-resource/mcp/claude`, request the directory scopes explicitly during registration and consent, and retain the same resource for token exchange and refresh. Directory and general scope families cannot be combined or exchanged for each other; connect separately to the general endpoint when that broader catalog is needed. The expanded catalog requires fresh authorization: original `scribed:claude:read` / `scribed:claude:write` access and refresh grants are rejected rather than silently broadened. The dedicated endpoint's availability does not by itself establish directory approval or publication.
+
 ## 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**.