docs(cli): update docs for refactored command surface

Author: flamehaven01

CHANGELOG.md

@@ -49,6 +49,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added an agent workflow guide covering JSON-first review, cleanup, health,
   and MCP-assisted usage patterns.
 
+**Local impact and opt-in telemetry**
+
+- Added repo-local impact tracking commands:
+  - `slop-detector impact enable`
+  - `slop-detector impact`
+  - `slop-detector impact disable`
+- Impact snapshots are stored in gitignored `.slop-detector/impact.json` and
+  summarize trend deltas across repeated runs.
+- Added telemetry control commands:
+  - `slop-detector telemetry status`
+  - `slop-detector telemetry enable`
+  - `slop-detector telemetry disable`
+  - `slop-detector telemetry inspect --example`
+- Added anonymized telemetry payload construction and local queueing.
+- Added inspect-first telemetry mode:
+  - `AI_SLOP_DETECTOR_TELEMETRY=inspect`
+  - prints a real payload without queueing or sending it
+
 ### Changed
 
 - Adaptive suggestions stay conservative and evidence-backed:
@@ -61,6 +79,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   adaptive preview, and explicit merge as distinct flows.
 - npm wrapper documentation now states explicitly that Node is a transport
   surface over the Python core, not a second implementation.
+- Impact and telemetry surfaces are kept out of the scoring path:
+  scoring remains deterministic, while adoption observability is opt-in and
+  separately controlled.
 
 ---
 

README.md

@@ -27,6 +27,7 @@ File-level evidence. Machine-readable output. No LLM in the scoring path.
 - Previous stable tag: `v3.8.0`
 - `v3.8.0` establishes the canonical `scan / review / pulse / sweep` CLI surface and hardens dogfood operation paths used by `health` and `audit`.
 - `v3.8.1` adds confidence-ranked cleanup plans, manifest hygiene, and opt-in layered architecture review.
+- Unreleased work adds repo-local impact tracking and default-off telemetry controls.
 
 ---
 
@@ -127,6 +128,14 @@ import type { ReviewOutput, ScanOutput } from "ai-slop-detector/types"
 # Programmatic Node API
 import { scanProject, reviewChanges, computeHealth, runCleanupFamily } from "ai-slop-detector"
 
+# Local impact story
+slop-detector impact enable .
+slop-detector impact .
+
+# Telemetry controls (default: off)
+slop-detector telemetry status
+slop-detector telemetry inspect --example
+
 # Local wrapper development
 cd npm-wrapper
 node ./bin/ai-slop-detector.js --version
@@ -213,6 +222,14 @@ slop-detector mcp
 slop-mcp
 ```
 
+Adoption and observability surfaces are intentionally separate from scoring:
+
+- `slop-detector impact` tracks local, gitignored repository progress in
+  `.slop-detector/impact.json`
+- `slop-detector telemetry` stays default-off and only builds anonymized
+  payloads; `AI_SLOP_DETECTOR_TELEMETRY=inspect` prints a real payload without
+  queueing it
+
 ---
 
 ## Scope And Boundaries

docs/CLI_USAGE.md

@@ -312,6 +312,37 @@ slop-detector --export-history history.jsonl
 slop-detector mycode.py --no-history
 ```
 
+## Local Impact & Telemetry
+
+```bash
+# Enable repo-local impact tracking (.slop-detector/impact.json)
+slop-detector impact enable .
+
+# Show local impact summary
+slop-detector impact .
+slop-detector impact --json
+
+# Telemetry stays off by default
+slop-detector telemetry status
+
+# Inspect an example anonymized payload
+slop-detector telemetry inspect --example
+
+# Inspect a live payload without queueing it
+AI_SLOP_DETECTOR_TELEMETRY=inspect slop-detector review . --format json
+
+# Opt in to local telemetry queueing
+slop-detector telemetry enable
+slop-detector telemetry disable
+```
+
+Contracts:
+
+- `impact` is repository-local and gitignored
+- telemetry is default-off
+- telemetry payloads are anonymized and keyed by `project_id`, not path names
+- inspect mode prints a real payload without appending to the telemetry queue
+
 ---
 
 ## CI/CD Integration