@scribed/cli 0.1.23 → 0.1.25

package/README.md

@@ -2,6 +2,11 @@
 
 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.
 
+Verified catalog (2026-10-18): **1,102 external tools across 48 categories**;
+581 tools in 28 categories are included in the default core set. Route
+coverage does not imply full UI parity: session-only actions and the remaining
+option audit are tracked in the repository's `output/ui-parity/` reports.
+
 ## Install
 
 Requires Node.js 20 or newer; users do not need Bun.
@@ -41,14 +46,70 @@ Downloads use a new private folder, verify the published SHA256 and exact HTTP d
 
 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
+## Send work from Scribed to a coding project
+
+This local connection is the reverse of MCP access: Scribed sends your requested
+task to a project on your computer and reads the agent's reply. It uses your
+existing coding-agent CLI sign-in, not a hosted “Sign in with Claude/Cursor/Codex”
+integration. No marketplace listing or publisher review is needed for these
+local paths. Your platform's access rules, project trust and normal billing apply.
+Requires a released CLI/API build with local handoff support.
+
+```bash
+scribed login --api-url https://app.scribed.ai
+scribed agents connect codex --project /path/to/project --mode agent
+# Setup prints the connection ID and listener command:
+scribed agents listen --connection <id>
+```
+
+Keep the listener running, then tell Scribed: “Send my Codex project a prompt to
+fix the checkout tests.” Scribed discovers your connected projects, sends the
+requested prompt and can read the reply. Settings → API / CLI / MCP also has a
+project picker, message history, queued-message cancellation and disconnect.
+If several projects match, specify the project name. Project connections are
+private to your account and do not inherit the selected workspace.
+
+| Platform | Local setup | What receives the task |
+| --- | --- | --- |
+| Codex | `scribed agents connect codex --project /path/to/project` | A fresh `codex exec` session in that folder; read-only by default, workspace writes with explicit `--mode agent`. |
+| Cursor | `scribed agents connect cursor --project /path/to/project` | A fresh Cursor CLI planning session. This connector supports plan mode only; it does not enable forced unattended edits. |
+| Claude Code | `scribed agents connect claude-code --project /path/to/project` | A new interactive Claude Code session started with the exact channel commands printed by setup. Plan by default; `--mode agent` retains the session's ordinary permission controls. |
+
+Claude Code Channels is an experimental research preview. Custom channels use
+the documented `--dangerously-load-development-channels server:scribed-channel`
+development option and require local trust; organization policy still applies.
+Keep that interactive session open. The CLI does not change provider permission
+settings or relay approval decisions. `scribed agents channel-setup --connection
+<id>` prints the setup again. Codex/Cursor connections start fresh tasks and do
+not inject into an existing desktop chat or automatically resume one.
+
+Only display metadata goes into the project registration. The canonical project
+path and random listener capability are saved in private files under
+`~/.config/scribed/channels/`; the API stores a capability hash. Every operation
+also requires your current Scribed login and the original account/server.
+The provider process receives task text on standard input, never as a shell
+command; Scribed-specific environment credentials are removed from its environment.
+
+Prompts are limited to 4,000 characters, replies to 8,000. Queued prompts expire
+after 24 hours. Delivery alone does not prove execution or completion. An
+uncertain claim, process result or reply is never automatically executed again.
+Inspect the history and project before sending another task. Disconnect cancels
+queued messages and refuses future claims; already delivered work may continue
+and can be stopped in the coding agent itself. A crashed listener leaves a local
+lock: follow its diagnostic only after checking no listener remains.
+
+## Sign in to Scribed
 
 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               # terminal email/password → bearer session
+scribed login --email-otp --email me@acme.com # request an email sign-in code
+scribed login --phone-otp --phone +14155550123 # request a phone sign-in code
+scribed login --password --two-factor otp # use an existing SMS/email 2FA challenge
+scribed login --password --two-factor backup # use an existing saved backup code
 scribed login --password --email me@acme.com --api-url http://localhost:8081
 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
@@ -64,9 +125,36 @@ The default login registers a public OAuth client, opens Scribed in the browser,
 
 `--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.
 
+Terminal sign-in uses the same authentication transport as the native apps.
+Email/phone code availability is checked before sending; codes and passwords are
+entered privately, never as command flags. If the account requires 2FA, select
+an offered authenticator (`totp`), sent code (`otp`) or saved backup code
+(`backup`); `--two-factor` selects it in advance. The resulting bearer is checked
+against its verified, unexpired session before private local storage. Challenges
+stay in memory. A rejected code offers explicit retry/cancel without resending;
+at the two-factor code prompt, `/switch` selects another available method and
+`/cancel` stops. Returning to the OTP method keeps its already requested code.
+Known expiry, lockout, rate-limit and uncertain network responses stop the flow.
+The phone API intentionally reports incorrect, expired and exhausted attempts
+alike; correcting a code reuses that same attempt and its server-enforced limits.
+Trust-device persistence,
+2FA enrollment/removal and backup-code generation remain in the browser.
+
 ### 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`.
+Run `scribed signup` for the terminal wizard. It uses the same account fields, validation, email verification and mobile verification as the native apps, and stores the resulting bearer session like `login --password`. Terms acceptance is explicit; verification codes must come from the person signing up.
+
+```bash
+scribed signup
+scribed signup --input private-signup.json --json
+scribed signup --resume --email you@example.com --email-code <code> --send-phone-code --json
+scribed signup --resume --email you@example.com --send-phone-code --phone-channel call --json
+scribed signup --resume --email you@example.com --phone-code <code> --json
+```
+
+`--input` accepts the shared `packages/account-signup` `SignUpDraft`, including `password`, `confirmPassword` and explicit `acceptTerms`. Protect that input file; passwords and codes are never saved in CLI configuration or printed. The staged flow reports what remains and resumes verification without creating another account. Phone codes use SMS by default; `--phone-channel call` requests a voice call when sending a code. Supplying `--phone-code` verifies that code without sending another. Use `--resend-email` to request a replacement email code and `--invite-token` to sign up for an existing invitation.
+
+Google/Apple consent stays in the browser: run `scribed login`, choose **Sign up**, complete the wizard, and then authorize the CLI. Browser login never collects signup details in the terminal. Subsequent onboarding tools remain limited by their API authorization; the offline signup lifecycle test does not prove live onboarding apply.
 
 ### Credentials and environment
 
@@ -306,7 +394,11 @@ scribed records view create deals --input view.json | view update <viewId> --inp
 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)
+                                       # CSV / TSV / JSON / XLSX / XLSM / vCard parsed here → objects_record_create per row (--ai: objects_import_suggest_mapping)
+scribed records import contacts contacts.xlsx extra.vcf --dry-run
+scribed records import contacts contacts.xlsx --sheet "Customers" --map "City=address#city"
+                                       # all visible worksheets by default; --sheet repeats to select sheets; --map also accepts address key#part
+                                       # merged columns, synthesized full names, and file + sheet + row diagnostics; 50 MiB per file
 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 →