CLI telemetry and the signup-funnel measurement gap

README.md

@@ -21,7 +21,7 @@
   - MCP servers: [sessions](#sessions-mcp-server-for-agents) · [flows](#flows-mcp-server-for-agents) · [flow-result](#flow-result-mcp-server-hosted-reviewers) · [memory](#memory-mcp-server-for-agents)
   - Importing: [import](#loading-historical-sessions) · [remap](#renamed-repo-directories-kcap-remap)
   - Agents & daemon: [daemon](#daemon) · [agent](#local-agents-kcap-agent) · [repos](#repository-paths)
-  - Account: [projects](#projects) · [profiles](#profiles) · [config](#configuration) · [uninstall](#uninstalling) · [other](#other-commands)
+  - Account: [projects](#projects) · [profiles](#profiles) · [config](#configuration) · [telemetry](#telemetry) · [uninstall](#uninstalling) · [other](#other-commands)
 - [License](#license)
 
 ## Why Capacitor
@@ -178,6 +178,8 @@ If your repo directories have been renamed or deleted on disk, the import prints
 
 Open the server URL in your browser. The dashboard shows repositories, sessions, and agents. It updates in real time as Claude Code sessions are active.
 
+kcap also reports anonymous CLI usage data by default — see [Telemetry](#telemetry) for what's collected and how to opt out.
+
 ### Sessions and Flows MCP servers for agents
 
 The `kcap mcp sessions` stdio server lets coding agents search and recall past Capacitor sessions without leaving the chat. `kcap setup` **registers it (with `kcap-review`) for Claude Code, Codex CLI, Cursor, GitHub Copilot CLI, Gemini CLI, SST OpenCode, Google Antigravity, and AWS Kiro CLI** — no manual `claude mcp add` or TOML/JSON edit. For Claude Code it's carried by the plugin's `.mcp.json`; for Codex CLI, `kcap setup` / `kcap plugin install --codex` write it into `~/.codex/config.toml`; for Cursor, `kcap setup` / `kcap plugin install --cursor` write it into `~/.cursor/mcp.json` (opt out with `--skip-cursor-mcp`); for Copilot, `kcap setup` / `kcap plugin install --copilot` write it into `~/.copilot/mcp-config.json` (opt out with `--skip-copilot-mcp`); for Gemini, `kcap setup` / `kcap plugin install --gemini` write it into the shared `~/.gemini/settings.json` (opt out with `--skip-gemini-mcp`); for OpenCode, into `~/.config/opencode/opencode.json` (opt out with `--skip-opencode-mcp`); for Antigravity, `kcap setup` / `kcap plugin install --antigravity` write it into `~/.gemini/config/mcp_config.json` (opt out with `--skip-antigravity-mcp`); for Kiro, `kcap setup` / `kcap plugin install --kiro` write it into `~/.kiro/settings/mcp.json` (opt out with `--skip-kiro-mcp`). The server is repo-aware: `cd` into a project before spawning your agent and `search_sessions` defaults to that repo's sessions.
@@ -1766,6 +1768,32 @@ Semantics:
 
 After adding a remap, re-run `kcap import --org` (or whichever scope you use). The missing-cwd report at the top of the import will show what's still unresolved. Ephemeral worktree paths under `<project>/.<anything>/worktrees/<slug>` are auto-attributed to `<project>` when it still exists on disk, so deleted-worktree cwds don't need a remap entry.
 
+### Telemetry
+
+kcap reports anonymous usage data so we can see which commands people use and where setup goes wrong. It records **command and flag names, exit codes, durations, MCP tool names, and setup-funnel steps.** It never records argument values, file paths, repo names or URLs, session ids, transcript content, environment variable values, usernames, or email addresses.
+
+What identifies an installation, stated plainly: a random device id generated once and stored on this machine, so events can be tied to one install over time without naming a person. For a hosted `*.kcap.ai` workspace, every event additionally carries that workspace's slug — as an `org` property and an `organization` group — so usage rolls up per workspace; self-hosted installs never send it, and the slug names a workspace, not a user.
+
+The first time you run a reportable command, kcap prints a one-time notice to stderr; it never prints again on that machine.
+
+Turn it off in any of three ways:
+
+```bash
+kcap config set telemetry off   # persisted, machine-wide
+export KCAP_TELEMETRY=0         # this shell only
+export DO_NOT_TRACK=1           # the cross-tool convention, honoured by kcap too
+```
+
+`telemetry` is deliberately machine-wide rather than per-profile: consent is a property of the machine, and having it flip when you switch profiles would be surprising.
+
+Precedence, highest first: `KCAP_TELEMETRY` > `DO_NOT_TRACK` > the persisted `telemetry` setting > on by default. `KCAP_TELEMETRY` wins over `DO_NOT_TRACK` **in both directions** — it's the kcap-specific, deliberate statement, and the only way to opt back in on a machine whose shell profile sets a blanket `DO_NOT_TRACK`:
+
+```bash
+DO_NOT_TRACK=1 KCAP_TELEMETRY=1 kcap status   # reports anyway — the explicit setting wins
+```
+
+`kcap config show` reports the effective state and which setting decided it, e.g. `Telemetry: off (source: DO_NOT_TRACK)`.
+
 ### Uninstalling
 
 To remove kcap from this machine, run: