feat: add telemetry adoption funnel

README.md

@@ -117,11 +117,13 @@ Telemetry is disabled unless you explicitly enable it.
 madar telemetry status
 madar telemetry enable
 madar telemetry disable
+madar telemetry clear
+madar telemetry report
 
 MADAR_ENABLE_TELEMETRY=1 madar generate .
 ```
 
-The current telemetry model is local-first and source-safe. It records coarse success events for `install`, `generate`, `pack`, and `compare`, plus version, OS, optional install target, and optional repo-size bucket. It does **not** record prompt text, answer text, source paths, or source content. Full controls: [`docs/telemetry.md`](https://github.com/mohanagy/madar/blob/main/docs/telemetry.md).
+The current telemetry model is local-first and source-safe. It records coarse funnel events for `install`, `generate`, `pack`, `prompt`, MCP `context_pack`, `doctor`, `status`, and `compare`, plus command stage, version, OS, Node major version, and optional coarse buckets such as agent target, repo size, graph size, SPI enabled, failure bucket, and status bucket. It does **not** record prompt text, answer text, source paths, source content, or repository names. Full controls: [`docs/telemetry.md`](https://github.com/mohanagy/madar/blob/main/docs/telemetry.md).
 
 ---
 

docs/reference/cli-and-mcp.md

@@ -96,6 +96,8 @@ madar compare "How does auth work?" --exec '...' --yes
 madar compare "How does auth work?" --baseline-mode pack_only --exec '...' --yes
 madar telemetry enable
 madar telemetry status
+madar telemetry clear
+madar telemetry report
 madar time-travel main HEAD --view risk
 madar federate frontend/graph.json backend/graph.json
 madar --help

docs/telemetry.md

@@ -10,8 +10,13 @@ Telemetry is **disabled by default**. No event is recorded unless you explicitly
 madar telemetry status
 madar telemetry enable
 madar telemetry disable
+madar telemetry clear
+madar telemetry report [spool.json ...]
 ```
 
+- `madar telemetry clear` deletes the local bounded event spool but keeps your persisted opt-in preference unchanged.
+- `madar telemetry report [spool.json ...]` prints a local anonymized funnel summary from the current spool plus any extra spool files you pass in.
+
 Environment overrides:
 
 - `MADAR_ENABLE_TELEMETRY=1` — enable telemetry for the current command without changing the persisted preference.
@@ -21,21 +26,23 @@ Environment overrides:
 
 ## What is collected
 
-The current implementation records only these coarse success events:
-
-- `install_success`
-- `generate_success`
-- `pack_success`
-- `compare_success`
-
-Each stored event can include:
+Each stored event includes these core fields:
 
-- `event`
+- `command`
+- `stage`
 - `recorded_at`
 - `version`
 - `os`
-- `install_platform` (only for install flows)
-- `repo_size_bucket` (only for repo-scoped flows such as `generate`, `pack`, and `compare`)
+- `node_major`
+
+Optional coarse fields are added only when they help explain adoption drop-off without revealing source-sensitive data:
+
+- `agent_target` — install target such as `claude`, `cursor`, `copilot`, `gemini`, `aider`, `codex`, or `opencode`
+- `repo_size_bucket` — coarse file-count bucket
+- `graph_size_bucket` — coarse node-count bucket
+- `spi_enabled` — whether `madar generate` ran with `--use-spi`
+- `failure_bucket` — coarse actionable category such as `usage_error`, `invalid_params`, `missing_graph`, `stale_graph`, `stale_context`, `tool_profile`, `unsupported_corpus`, `install_error`, or `unknown`
+- `status_bucket` — coarse doctor/status outcome (`healthy` or `attention_needed`)
 
 `repo_size_bucket` is intentionally coarse:
 
@@ -45,6 +52,26 @@ Each stored event can include:
 - `500-999`
 - `1000+`
 
+`graph_size_bucket` is intentionally coarse:
+
+- `1-99`
+- `100-499`
+- `500-999`
+- `1000-4999`
+- `5000+`
+
+## Current tracked command surfaces
+
+When telemetry is enabled, Madar records source-safe funnel stages for:
+
+- install flows (`madar install --platform ...`, `madar <agent> install`)
+- `madar generate` (`started`, `succeeded`, `failed`)
+- `madar pack` (`succeeded`, `failed`)
+- `madar prompt` (`succeeded`, `failed`)
+- MCP `context_pack` (`succeeded`, `failed`)
+- `madar doctor` and `madar status` (`succeeded`, `failed`, plus `status_bucket`)
+- `madar compare` (`succeeded`, `failed`)
+
 ## What is excluded
 
 Madar does **not** record:
@@ -53,6 +80,7 @@ Madar does **not** record:
 - answer text
 - source paths
 - source content
+- repository name
 - raw snippets
 - full file counts
 - graph contents
@@ -62,16 +90,6 @@ Madar does **not** record:
 This release stores telemetry locally only:
 
 - persisted opt-in preference under the platform config directory
-- bounded event spool under the platform cache directory
+- bounded event spool under the platform cache directory (`schema_version: 2`)
 
 There is **no cloud upload by default** in this implementation. The goal of this issue is to define the opt-in event model, controls, and source-safe field contract without introducing mandatory network traffic.
-
-## Current tracked command surfaces
-
-When telemetry is enabled, Madar records a coarse success event after these CLI flows complete successfully:
-
-- `madar install --platform <platform>`
-- `madar <agent> install`
-- `madar generate`
-- `madar pack`
-- `madar compare`