@askthew/mcp-plugin 0.4.10 → 0.4.11

package/README.md

@@ -1,214 +1,78 @@
-# Ask The W Plugin
+# Ask The W MCP Plugin
 
-Connect a local coding agent to Ask The W. The fastest path is free and local-first:
+Cloud-first MCP capture for Claude Code, Codex, and Cursor.
 
 ```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install --host claude_code --free --email you@founder.com
+npx -y --package @askthew/mcp-plugin askthew-mcp install --host claude_code
 ```
 
-This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent list the trail, keep decisions, and get limited local recap and coaching without onboarding into the web app.
+Use `--host codex` or `--host cursor` for the other supported clients.
 
-Founder-friendly promise: install from npm, then ask your coding agent to review the last session. You should see value in under 60 seconds.
-
-This package runs a small MCP server that lets Codex, Claude Code, Cursor, and other MCP-capable tools send compact work-session signals to an Ask The W workspace.
+The installer walks email OTP, stores a device token in `~/.askthew/cloud-token.json`, writes the host MCP config, and adds a marked Ask The W block to `CLAUDE.md` or `AGENTS.md` so future sessions capture automatically.
 
 ## What It Does
 
-- Installs an Ask The W plugin server entry into a supported local client.
-- Preserves existing MCP servers and settings.
-- Adds marked project instructions so future coding-agent sessions know when to send Ask The W updates.
-- Free mode stores full-fidelity signals and decisions locally in SQLite.
-- Paid workspace mode sends a startup heartbeat so Ask The W can show the plugin as installed.
-- Exposes a small MCP surface for capture, signals, decisions, recap, and coaching.
-- Redacts obvious secrets from summaries, evidence excerpts, commands, and metadata before sending.
-- Adds lightweight workspace metadata such as host type, repo name, app path, and server name.
-
-## What It Does Not Do
-
-- It does not send full transcripts by default.
-- It does not send local free-tier content to Ask The W unless you upgrade and run sync upload.
-- It does not expose internal workspace APIs through the plugin.
-- It does not include the Ask The W app, private server code, Supabase code, or internal analytics code.
-
-Ask The W keeps the local plugin focused on the trail your agent can use while it works.
-
-## Free Local Install
-
-```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
-  --host claude_code \
-  --free \
-  --email you@founder.com
-```
-
-Free install is local-first: it generates `~/.askthew/identity.json`, writes MCP config and agent instructions immediately, and never requires an email code before local capture works. The email is an unverified claim used for upgrade onboarding only; data is keyed by the generated install ID, not email alone.
-
-Installer bookkeeping is separate from local capture data: install receipts live under `~/.local/state/askthew/install-receipts.json` by default, or `$XDG_STATE_HOME/askthew/install-receipts.json` when `XDG_STATE_HOME` is set. This lets `uninstall` remove host config and repo instruction blocks even after `~/.askthew` has been wiped.
-
-Telemetry is aggregate-only and opt-out. Ask The W does not receive code, file contents, file paths, file names, command text, summaries, or decision content in free mode telemetry. Aggregate summaries are signed by the local install identity and stored under the generated install ID. Opt out with `--no-telemetry`, `ASKTHEW_TELEMETRY=off`, or `askthew-mcp telemetry opt-out`.
-
-## Refresh vs Uninstall
-
-Use `refresh` when you want the latest installed MCP config and instruction blocks without touching local identity or local data:
-
-```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp refresh --host claude_code
-```
-
-`refresh` preserves `~/.askthew/identity.json` and `~/.askthew/store.sqlite`, reuses any existing email claim silently, rewrites the host MCP config, and rewrites the marked Ask The W blocks in `CLAUDE.md` and `AGENTS.md`. This is the recommended QA update path after a plugin publish.
-
-Use `uninstall` when you want to remove the plugin from a host:
-
-```bash
-npx -y @askthew/mcp-plugin@latest uninstall --host claude_code --keep-local-data --keep-auth
-```
-
-Without `--keep-local-data`, uninstall removes `~/.askthew`; without `--keep-auth`, it removes the local install identity. Uninstall does not clear npm's cache.
+- Runs a local MCP stdio server in one mode: cloud shim.
+- Captures compact signals through `POST /api/v1/agent/signals`.
+- Buffers captures in `~/.askthew/outbox.sqlite` when the network is down.
+- Redacts obvious secrets before queueing and sending.
+- Lists signals and decisions, creates decisions, and calls cloud recap/coach.
+- Exposes `askthew_start_signup` and `askthew_complete_signup` when no token file exists, for manual MCP config users.
 
-## Workspace Install
+## Paid Workspace Install
 
-Create a workspace token in Ask The W at `/decisions/settings/connectors`, then run the installer from your coding agent or terminal. Treat the token like a password; anyone with it can write compact source signals into that workspace.
-
-Use setup tokens promptly. They expire after 24 hours if the connector never sends activity. Once connected, active tokens renew while in use and expire after 90 days without activity. Rotate the token in Ask The W if it is exposed or if the connector reports an expired or revoked token.
-
-Codex:
-
-```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
-  --host codex \
-  --token "<ASKTHEW_INSTALL_TOKEN>" \
-  --api-url "https://app.askthew.com/" \
-  --server-name "askthew"
-```
-
-Claude Code:
+Paid users install from the workspace settings page. The page issues a short-lived paid bind token and shows:
 
 ```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
-  --host claude_code \
-  --token "<ASKTHEW_INSTALL_TOKEN>" \
-  --api-url "https://app.askthew.com/" \
-  --server-name "askthew"
+npx -y --package @askthew/mcp-plugin askthew-mcp install --host claude_code --bind <paid_bind_token>
 ```
 
-Cursor:
-
-```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install \
-  --host cursor \
-  --token "<ASKTHEW_INSTALL_TOKEN>" \
-  --api-url "https://app.askthew.com/" \
-  --server-name "askthew"
-```
-
-After install, restart or reload your coding agent if needed. At the start of every new coding-agent session in this repo, before plan mode or exploration, call `capture_session_signal` with `kind: "setup_complete"` and choose "Always allow" if the host prompts for tool permission. If you realize later that the startup call was missed, send it immediately with `metadata.recovered_missed_startup=true`.
-
-Claude Desktop and Cowork custom connectors use Ask The W's hosted Remote MCP URL instead of this local `npx` installer. In Ask The W, create a Claude Remote URL from the plugin source, then paste it into Claude's custom connector form as the Remote MCP server URL. The URL must be public HTTPS; `localhost`, `127.0.0.1`, LAN IPs, VPN-only hosts, and firewall-blocked servers will fail because Claude connects from Anthropic's cloud. Treat the URL like a password and rotate it if it leaks.
+The CLI exchanges that token for a device token already bound to the workspace. No OTP is needed because the web session proved workspace authority.
 
-The installer also adds safe, marked project instructions to both markdown convention files plus any host-specific rule file:
+## Free To Paid Bind
 
-- Codex: `AGENTS.md`
-- Claude Code: `CLAUDE.md`
-- Cursor: `.cursor/rules/askthew.mdc`
-
-These instructions tell the coding agent to send compact Ask The W updates at the start of every new repo session, after meaningful direction changes, implementation work, verification, long-session checkpoints, and final summaries. Existing instruction files are preserved.
-
-To skip this behavior, pass:
+Users who started free can later run:
 
 ```bash
---no-agent-instructions
+askthew-mcp bind
 ```
 
-## Configuration
-
-The installer writes the MCP server into the host's native MCP configuration so it appears in that host's MCP server list:
+The CLI flushes the outbox first, prints a short display code, opens the browser bind URL, and polls until the workspace confirms the bind. Existing install identity stays stable.
 
-- Codex: `~/.codex/config.toml`
-- Claude Code: `~/.claude.json`, scoped to the current project
-- Cursor: `~/.cursor/mcp.json`
+## Tool Surface
 
-Codex example:
+The v1 MCP tools are:
 
-```toml
-[mcp_servers.askthew]
-command = "npx"
-args = ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"]
-env = { ASKTHEW_INSTALL_TOKEN = "<ASKTHEW_INSTALL_TOKEN>", ASKTHEW_HOST_TYPE = "codex", ASKTHEW_API_URL = "https://app.askthew.com/", ASKTHEW_SERVER_NAME = "askthew" }
-```
+- `capture_session_signal`
+- `list_signals`
+- `create_decision`
+- `list_decisions`
+- `recap`
+- `coach`
+- `askthew_start_signup` and `askthew_complete_signup` when a token file is missing
 
-Claude Code and Cursor use an MCP JSON entry like this:
-
-```json
-{
-  "mcpServers": {
-    "askthew": {
-      "command": "npx",
-      "args": ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
-      "env": {
-        "ASKTHEW_INSTALL_TOKEN": "<ASKTHEW_INSTALL_TOKEN>",
-        "ASKTHEW_HOST_TYPE": "codex",
-        "ASKTHEW_API_URL": "https://app.askthew.com/",
-        "ASKTHEW_SERVER_NAME": "askthew"
-      }
-    }
-  }
-}
-```
+`get_decision` and `promote_signal_to_decision` are intentionally not exposed in v1. Use `list_decisions` and `create_decision` with `sourceSignalIds`.
 
-Optional environment variables:
-
-- `ASKTHEW_CLIENT_ID`
-- `ASKTHEW_CLIENT_LABEL`
-
-## Tool Contract
-
-The session-signal tool remains the main automatic capture path.
-
-```json
-{
-  "name": "capture_session_signal",
-  "input": {
-    "sessionId": "string",
-    "sequence": "number",
-    "kind": "setup_complete | session_checkpoint | direction_change | implementation_update | verification_result | final_summary",
-    "summary": "string",
-    "evidence": [{ "role": "user | assistant | system", "excerpt": "string" }],
-    "filesTouched": ["string"],
-    "commandsRun": ["string"],
-    "metadata": {},
-    "echo": "summary | full"
-  }
-}
-```
+## Local Files
 
-Use compact summaries and short evidence excerpts. Do not send full transcripts. By default, write tools return compact responses; use `echo: "full"` only when you need the larger payload for debugging.
+- `~/.askthew/cloud-token.json` - bearer token, install id, tier, and API URL; mode `0600`
+- `~/.askthew/install.json` - install diagnostics
+- `~/.askthew/outbox.sqlite` - pending capture buffer
 
-The plugin exposes a small public tool surface:
-
-| Tool | Purpose |
-|---|---|
-| `capture_session_signal`, `list_signals` | Capture and list the local signal trail. |
-| `list_decisions`, `get_decision`, `create_decision`, `promote_signal_to_decision` | Keep the decisions worth remembering. |
-| `recap`, `coach` | Get up to three local recaps and three coaching nudges. After that, the plugin returns `Limit reached. Upgrade to the paid plan.` |
-
-Free PLG helpers:
+## CLI
 
 ```bash
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install-hook --pre-commit
-npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp digest --weekly
+askthew-mcp                 # stdio MCP server
+askthew-mcp install --host claude_code
+askthew-mcp install --host claude_code --bind <paid_bind_token>
+askthew-mcp bind
+askthew-mcp token rotate
+askthew-mcp token revoke
+askthew-mcp export
+askthew-mcp delete-me --confirm
 ```
 
-The hook prompts when staged files recently had implementation signals but no linked decision. The weekly digest writes `~/Documents/askthew-digest-YYYY-WW.md`.
-
-Decision writes are text-only and are recorded with the local trail.
-
-## Troubleshooting
-
-- Empty `list_mcp_resources` or `list_mcp_resource_templates` results are normal. This connector is tool-driven.
-- If Ask The W shows "Waiting for install", restart or reload your coding agent.
-- If Ask The W shows "Installed", restart or reload your coding agent if it was already open. At the start of the next repo session, the coding agent should call `capture_session_signal` with `kind: "setup_complete"` before plan mode; choose "Always allow" if it asks for tool permission.
-- For Claude Desktop or Cowork, set `capture_session_signal` to "Always allow" in connector Tool permissions when that panel is available, or choose "Allow always" on the first tool prompt.
-- If a token fails, check whether the error says missing, malformed, expired, or revoked. Copy the full token if it is malformed; rotate it in Ask The W and rerun the installer if it expired or was revoked.
+`token revoke` revokes only the current token. Install-level revocation is handled by the workspace web endpoint or `delete-me`.
 
 ## Development
 

package/dist/cli.d.ts

@@ -1,8 +1,2 @@
 #!/usr/bin/env node
-import { tryRegisterFreeInstall } from "./lib/free-install-registration.js";
-type AuthCommandDeps = {
-    log?: (message: string) => void;
-    registerFreeInstall?: typeof tryRegisterFreeInstall;
-};
-export declare function runAuthCommand(argv: string[], deps?: AuthCommandDeps): Promise<void>;
 export {};