@trillioncore/cli 0.22.1 → 0.23.0

package/README.md

@@ -18,7 +18,7 @@ tc login
 ## Quickstart
 
 ```sh
-tc login                       # browser OAuth — opens your default browser, authenticates, and stores sessions
+tc login                       # confirmed device authorization — browser may be on another machine
 tc whoami                      # prints the authenticated user, target source, and organization
 tc agent start --organization TrillionCore --env production --format json  # agent harness preflight + briefing
 tc handover --to Jake --since today       # draft/edit/publish a private Git-based handover to Daily Cortex
@@ -34,36 +34,69 @@ Memory writing contract for agent closeout: write durable interpretation, not ra
 
 Sessions are stored in `~/.trillioncore/config.json` and are scoped by environment, user, and organization. Use `tc logout` to clear them.
 
-## Local agent / ChatGPT usage
+## Latest Fathom action items
 
-If a local ChatGPT, coding agent, or sandbox runs `tc` on your behalf, run it in agent-safe mode:
+Ask naturally through the existing chat command:
 
 ```sh
-TC_AGENT_SAFE=1 tc brief
-TC_AGENT_SAFE=1 tc ask "What changed since yesterday?"
-tc --agent-safe whoami
+tc ask "What were the action items from the last call?"
+tc ask --json "What were the action items from the last Fathom transcript?"
 ```
 
-Agent-safe mode is a local blast-radius guardrail. It only allows read-heavy commands:
+When the deployment feature flag is enabled, the organization is authorized,
+and the request matches a latest-Fathom action-item prompt (currently
+default-off/canary-only), TrillionCore selects the latest completed Fathom
+meeting by meeting start time and returns only action items backed by transcript
+evidence. Unrelated prompts do not activate this workflow. Interactive non-JSON
+terminal queries offer one numbered action-item selection after the read-only
+answer; press Enter to skip it. Non-code or ambiguous items create nothing. An
+accepted selection creates one task bead and starts the configured bead loop;
+follow execution with `tc loop status`. `--json` output and piped input or output
+remain read-only.
 
-- `tc whoami`
-- `tc status`
-- `tc brief`
-- `tc ask ...`
-- `tc search ...`
-- `tc cat ...`
-- `tc ls ...`
-- `tc tree ...`
+## MCP handovers
 
-All other commands are blocked before they run. Ask the human user to run blocked commands manually.
+For hosted agents that support MCP/custom connectors, prefer the Trillioncore MCP connector over local CLI setup:
 
-Agent-safe mode does not grant access by itself. The CLI still requires normal Trillioncore authentication, and the API enforces which organization the authenticated principal can access.
+```text
+https://api.trillioncore.com/mcp
+```
+
+Connect that URL, sign in through Trillioncore, review the requested read/write permissions in your browser, and click **Allow access**. The connector can then read context and create approved handovers or feedback without a static token or local CLI setup. Manage or fully revoke the connection under **Settings → Connected Apps**.
+
+The CLI grant commands remain available for bootstrap and troubleshooting only. Approve a client ID only when you intentionally registered and trust that client:
+
+```sh
+tc mcp grants
+tc mcp approve-write <client-id>
+tc mcp revoke-write <client-id>
+```
+
+`tc mcp revoke-write` removes only write access while preserving the read connection. **Settings → Connected Apps → Revoke access** revokes the entire connection.
+
+If an MCP write tool returns `mcp.write_approval_required`, reconnect the MCP client to repeat browser authorization or use the CLI fallback from a trusted authenticated machine.
+
+Example handover prompt:
+
+```text
+Use Trillioncore MCP to create an end-of-day handover for Jake.
+Ask me for missing notes first.
+Include current state, blockers, and what Jake should do tomorrow.
+Use create_handover only after I confirm the draft.
+```
+
+Pickup prompt:
+
+```text
+Use Trillioncore MCP to list handovers addressed to me.
+Summarize the newest handover and call get_memory if you need full details.
+```
 
 ## Commands
 
 | Command                          | What it does                                                                                                                                                              |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tc login [--organization X]`    | Authenticate via browser. Optionally pre-select an org by name.                                                                                                           |
+| `tc login [--organization X]`    | Authenticate via an explicitly confirmed browser device flow. Optionally pre-select an org by name.                                                                       |
 | `tc logout`                      | Clear stored authentication.                                                                                                                                              |
 | `tc switch [--organization X]`   | Change the default organization used when no per-command target exists.                                                                                                   |
 | `tc whoami [-j]`                 | Show the authenticated user, target source, and organization diagnostics.                                                                                                 |
@@ -123,7 +156,7 @@ The CLI defaults to the production Trillioncore stack. Two environment variables
 | `TC_API_URL` | `https://api.trillioncore.com` | Trillioncore API base URL.                   |
 | `TC_APP_URL` | `https://app.trillioncore.com` | Web app URL used for the browser OAuth flow. |
 
-For self-hosted, staging, or local development, set both before running `tc` — e.g.:
+For self-hosted or staging deployments, both URLs must use HTTPS. Plain HTTP browser authentication is rejected before any authentication network request. The only exception is explicit loopback development on `localhost`, `127.0.0.1`, or `[::1]` — e.g.:
 
 ```sh
 TC_API_URL=http://localhost:3001 TC_APP_URL=http://localhost:3000 tc login
@@ -143,10 +176,12 @@ The CLI tried to refresh your token and couldn't. Re-run `tc login`.
 Likely a stale session in `~/.trillioncore/config.json`. Run `tc logout && tc login`.
 
 **Browser doesn't open during `tc login`**
-The CLI prints a fallback URL to the terminal — copy it into your browser manually. This usually means there's no default browser registered (common in headless SSH sessions).
+The CLI registers a five-minute device request, then prints a URL and a short verification code. Open the URL in any browser, including a browser on another machine when the CLI runs over SSH or on a headless VPS. In the browser, enter the code shown in the terminal, verify the displayed code matches, choose an organization, and click **Authorize this CLI**. Single-organization and `--organization` flows still require this explicit confirmation. `--organization` is only a preselection hint: zero or duplicate case-insensitive matches fail closed and require a manual organization choice. Keep the terminal running until it confirms authentication; transient polling network errors, 429 responses, and server errors retry within the original five-minute deadline, while Ctrl-C remains immediately cancellable.
+
+Treat an unexpected login URL as a phishing attempt. The URL carries a one-way request identifier rather than a token, but it can identify an attacker's waiting CLI. Do not authorize a link you did not initiate, do not share the URL or verification code, and never accept a code supplied by another person. The high-entropy polling verifier and delivered credentials stay out of URLs and logs and are sent only in HTTPS POST bodies (except explicit loopback HTTP during local development). The CLI acknowledges consumption only after its mode-restricted temporary configuration is flushed, atomically renamed, and the containing directory is flushed on POSIX, allowing recovery from a lost polling response or failed local durability step without manual token copying. Never share CLI configuration files or print their contents.
 
-**Want to see what's stored?**
-`cat ~/.trillioncore/config.json` — the file holds scoped session records, refresh/access tokens, expirations, and the default organization. Tokens are sensitive; treat the file accordingly.
+**Need to inspect configuration?**
+Use `tc config list` and `tc status`; do not print `~/.trillioncore/config.json`, because it contains sensitive session credentials.
 
 ## Repository