[nightshift] doc-drift: documentation vs code inconsistencies

[nightshift-micr]

[nightshift] Doc Drift Analysis

Repository: micr-dev/tokens (slopmeter)

Summary

Analyzed documentation vs actual code for drift and inconsistencies. Found 12 issues across all severity levels.

---

P0 — Critical (Will Mislead Users)

P0-1: Root README omits Gemini CLI entirely

File: README.md, lines 3 and 59–67
Code: packages/cli/src/cli.ts lines 36, 52, 58, 276; packages/cli/src/providers.ts line 57
Details: The root README's one-liner lists providers but omits Gemini CLI. The Options section lists every --provider flag except --gemini. The code fully supports Gemini with --gemini flag, a gemini provider ID, and a dedicated lib/gemini.ts module. The CLI README correctly includes Gemini.
Action: Add "Gemini CLI" to line 3, and add slopmeter --gemini to the Options section.

P0-2: Root README claims LAST 30 DAYS is a top metric — it doesn't exist in code

File: README.md, line 74
Code: packages/cli/src/graph.ts, lines 622–704
Details: The README's "What the image shows" section states the top metrics include LAST 30 DAYS. The code only renders three header metrics: INPUT TOKENS, OUTPUT TOKENS, and TOTAL TOKENS. No "LAST 30 DAYS" metric exists.
Action: Remove the LAST 30 DAYS entry from the "Top metrics per provider" list.

---

P1 — High (Incomplete or Incorrect Information)

P1-1: packages/cli/package.json description omits 4 supported providers

File: packages/cli/package.json, line 3
Details: The description field reads "CLI for generating yearly usage heatmaps for Claude Code, Codex, Cursor, Open Code, and Pi Coding Agent." — missing Gemini CLI, Droid, Hermes Agent, and Helios. Shown on npm when users run npx slopmeter.
Action: Update description to include all 9 providers.

P1-2: Undocumented CURSOR_WEB_BASE_URL environment variable

File: packages/cli/src/lib/cursor.ts, lines 20, 225–228
Details: The code reads CURSOR_WEB_BASE_URL with a default of https://cursor.com. Neither README mentions this variable.
Action: Add CURSOR_WEB_BASE_URL to the Environment knobs section in both READMEs.

P1-3: Undocumented SLOPMETER_WEB_DATA_URL environment variable

File: packages/web/scripts/publish-usage.ts line 66; packages/web/lib/usage.ts line 56
Details: The publish script and web app both read SLOPMETER_WEB_DATA_URL for the hosted usage JSON payload. Completely undocumented.
Action: Add SLOPMETER_WEB_DATA_URL to the README.

P1-4: Root README monorepo layout is incomplete

File: README.md, lines 7–14
Details: The layout diagram shows tooling/ containing only typescript-config/, but tooling/eslint-config/ also exists.
Action: Add eslint-config/ under tooling/ in the layout diagram.

P1-5: Root README --output default description is misleading

File: README.md, line 42; packages/cli/src/cli.ts line 328
Details: README says "Output file (default: ./heatmap-last-year.png)" but the code uses ./heatmap-last-year.${format} where format can be svg/json.
Action: Clarify that the default output filename is ./heatmap-last-year.{format}.

---

P2 — Medium (Minor Inconsistencies)

P2-1: "Environment knobs" section mixes data locations with env vars

File: README.md, line 161
Details: Droid entry is a data location (~/.factory/sessions/**/*.settings.json) placed among actual env vars.
Action: Move the Droid data location to the "Data locations" section.

P2-2: Claude Code .claude-* auto-discovery not documented

File: packages/cli/src/lib/claude-code.ts, lines 80–101, 127
Details: discoverClaudeWorkDirs() auto-discovers ~/.claude-* directories. Neither README mentions this.
Action: Add a note about auto-discovery of ~/.claude-* work directories.

P2-3: CLAUDE_CONFIG_DIR data location notation is misleading

File: README.md, line 179
Details: $CLAUDE_CONFIG_DIR/*/projects notation is confusing — the code reads each comma-separated base directory and looks for a projects subdirectory.
Action: Clarify the notation.

P2-4: JSON_EXPORT_VERSION is a hardcoded date that may drift

File: packages/cli/src/lib/export.ts, line 11
Details: Hardcoded "2026-03-03" doesn't track the npm package version (0.4.1).
Action: Consider deriving from package.json or documenting the update cadence.

---

P3 — Low (Cosmetic)

P3-1: Hardcoded "Claude" provider name in generic heatmap note

File: packages/cli/src/graph.ts, line 844
Details: Note says "Claude started logging..." but the function is used for ALL providers. Currently only Claude sets these, so it's latent.

P3-2: packages/cli/package.json keywords missing newer providers

File: packages/cli/package.json, keywords array
Details: Missing "gemini", "gemini-cli", "droid", "hermes", "helios" keywords. Affects npm discoverability.

---

Summary

Severity	Count
P0	2
P1	5
P2	4
P3	2

Highest-impact items: P0-1 (missing Gemini from root README) and P0-2 (non-existent LAST 30 DAYS metric).