@vimoxshah/tokenflow 1.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,207 @@
+# Troubleshooting
+
+Start here:
+
+```bash
+tokenflow doctor      # runtime, paths, store, every adapter's detection status
+npm run validate     # incl. whether the aggregates still agree with the stored records
+```
+
+---
+
+## "No usage sources found"
+
+That is a normal answer, not a failure. Check where your tool actually keeps its logs, then point
+at it:
+
+```yaml
+# ~/.tokenflow/config.yaml
+sources:
+  anthropic:
+    paths: ["/custom/claude/home", "~/.claude-work"]
+  openai:
+    paths: ["/custom/codex/home"]
+```
+
+An adapter is only "available" if the specific directory or file it names exists. `tokenflow
+providers` prints the exact reason for each one.
+
+No supported tool at all? Either `tokenflow import <file>` an export, or `tokenflow demo` to explore.
+
+## "node:sqlite is unavailable"
+
+You are on Node < 22.5. Upgrade Node; the SQLite-backed adapters (`cursor`, and `generic` with
+`--format sqlite`) will start working. Everything else is unaffected.
+
+## Refresh is slow
+
+The first ingest reads everything once; after that it should be seconds. If it stays slow:
+
+- `tokenflow doctor` → is `files tracked` growing every run? A source whose files are rewritten
+  rather than appended can't be resumed, and will be re-read each time.
+- Network drives and FUSE mounts are the usual culprit. The store handles mounts that refuse
+  `rename`/`unlink`, but read throughput is what it is.
+- Cap the work and resume: `tokenflow refresh --budget 30`, repeatedly.
+
+## Refresh hit the time budget
+
+Expected, by design. Progress was saved. Run it again — it continues at the byte offset where it
+stopped:
+
+```bash
+until node bin/tokenflow.js refresh --budget 30 --quiet | grep -q 'budget reached'; do :; done
+```
+
+## The numbers look too high
+
+This is the failure mode worth being suspicious about, and there are three real causes.
+
+**Streaming logs re-report usage.** Both shipped adapters handle it, but a custom adapter probably
+doesn't. Symptom: one day, or one session, dwarfs everything else by 10–100x. Check
+`metadata.token_count_events` / `metadata.usage_segments` in the Data Explorer — a record built
+from hundreds of events is a reconstruction, and if your adapter summed them it inflated them.
+See [creating-provider.md](creating-provider.md#5-watch-for-re-reported-usage).
+
+**Overlay double counting.** If "Include gateway overlay" is on, proxy records are being added to
+client records for the same traffic. Turn it off (it is off by default) — overlay exists for the
+measured *cost*, not for tokens.
+
+**Cache read counted as input.** If your adapter passed a vendor's inclusive `input_tokens`
+straight through, every cached prompt token is counted twice. `input + cache_read` should be the
+prompt side, with no overlap.
+
+Sanity check any suspicious day against the raw source:
+
+```bash
+tokenflow export --csv --from 2026-08-15 --to 2026-08-15
+```
+
+…then compare with whatever independent record you have (a gateway log, a billing page). Two
+sources agreeing is worth more than one source being plausible.
+
+## The numbers look too low
+
+- **Active days** counts days with *measured tokens*. Days where only a no-token source (Cline,
+  Cursor, git) was active are reported separately as "activity-only" — that is why the count can
+  be lower than you expect.
+- Check the **date filter**. `ui.defaultFrom` sets a floor for the default view; the data is still
+  there. Click "Since …" or set an explicit range.
+- Check **Data health → Sources**: each adapter's real coverage window is listed. A source that
+  only started logging in July does not cover March.
+- Many tools prune their own logs (Claude Code defaults to ~30 days). Nothing can recover data the
+  source already deleted.
+
+## Cost shows nothing / "no price"
+
+By design: no rate in the table, no number. See what is missing and fix it:
+
+```bash
+tokenflow pricing
+tokenflow pricing --set "your-model=15,75,1.5,18.75"
+tokenflow refresh --full
+```
+
+Newly released models are the usual case — the built-in table only carries rates that were
+published when it was built (its version is shown in the dashboard footer).
+
+## Cost coverage is under 100%
+
+Expected when some models are priced and others aren't. The Cost page states the covered share and
+lists the unpriced models by volume. The **estimated** total covers only priced requests; the
+**measured** figure, if present, covers only gateway-routed traffic. They are shown separately
+because they measure different things.
+
+## "Data health: Good" instead of "Excellent"
+
+The grade is driven by the share of token fields the *sources* didn't report. A dataset containing
+Cline or Cursor records will never be "Excellent" — those sources report no tokens at all. Check
+**Data health → Field availability** for the per-field breakdown.
+
+## Interface shows "Unknown"
+
+The source record had no surface field. Interface is deliberately never inferred from the model.
+If you know what a client is, say so:
+
+```yaml
+interfaceOverrides:
+  my-custom-client: "API"
+```
+
+## The dashboard is empty but `status` shows data
+
+Almost always the date filter. Click **Since …**, or clear filters via the breadcrumb. The
+breadcrumb above the tabs always lists every active filter.
+
+## "a refresh is already running"
+
+One refresh at a time, so two writers can't interleave into the store. Wait for it, or restart the
+server.
+
+## Aggregates disagree with the records
+
+```bash
+npm run validate     # reports drift between the cube and the stored facts
+tokenflow compact     # rewrites shards without superseded records and rebuilds
+```
+
+This can happen if a process was killed mid-refresh. `compact` is always safe to run.
+
+## Port already in use
+
+```bash
+tokenflow dashboard --port 8080
+```
+
+## `refresh --full` says it is "refusing a full re-ingest"
+
+The command was about to drop stored records belonging to a source whose logs it cannot read
+right now, so it stopped and told you how many and why. This is the guard working, not a
+failure. Usual causes:
+
+- you are running from a different machine, container or sandbox than the one that ingested
+- a source path in `config.yaml` moved (`~/.claude`, `~/.codex`, a Cursor DB)
+- the log directory was pruned or archived
+
+```bash
+tokenflow doctor                       # which paths resolve, which adapters detect
+tokenflow refresh                      # incremental is always safe
+tokenflow restore export.csv --yes     # rebuild from a full export instead
+tokenflow refresh --full --force       # only if you really mean "discard those records"
+```
+
+## I moved to a new machine / the logs are gone
+
+Export on the machine that has the logs, restore on the one that does not. The CSV carries
+counts and identifiers only — prompts, conversations and code stay put.
+
+```bash
+# old machine
+tokenflow export --csv --all
+# new machine
+tokenflow restore tokenflow-usage-2026-08-20.csv --yes
+```
+
+Estimated costs are recomputed with the current price table on restore (`--no-reprice` to
+keep them as exported); measured costs are preserved. Per-record `metadata` is not part of a
+CSV export and is not restored. If the real logs later become reachable again, just
+`refresh` — the restored slice is superseded automatically rather than double counted.
+
+## I want to start over
+
+```bash
+tokenflow reset --yes     # deletes ingested data, keeps config, pricing and mappings
+tokenflow refresh
+```
+
+Or delete the whole thing: `rm -rf ~/.tokenflow`. Nothing lives anywhere else.
+
+## Something is genuinely broken
+
+```bash
+node bin/tokenflow.js doctor
+node bin/tokenflow.js refresh --strict --debug --provider <suspect>
+npm test
+```
+
+`--strict` validates every record as it is written and prints the first failures with the adapter
+that produced them, which is usually enough to localise the problem to one adapter and one field.

package/examples/config.example.yaml

@@ -0,0 +1,92 @@
+# tokenflow — a fully worked configuration
+# Lives at ~/.tokenflow/config.yaml (or $TOKENFLOW_HOME/config.yaml).
+# config.json is also accepted if you prefer JSON.
+
+version: 1
+
+# Dates and hours are resolved in this zone AT INGEST and then stored, so "my
+# peak hour" means your local peak hour. null = this machine's zone.
+timezone: Asia/Kolkata
+
+# Stamped onto every record. Present so a future team deployment can aggregate
+# across machines without a schema change; unused in single-user mode.
+identity:
+  user: vshah
+  machine: my-laptop
+  team: null
+
+# Enabled adapters. An empty list means "everything detected".
+providers:
+  - anthropic
+  - openai
+  - cline
+  - cursor
+  - headroom
+  - git
+
+sources:
+  # Several Claude Code homes is normal — one per account. Listing them here
+  # skips auto-discovery entirely.
+  anthropic:
+    paths:
+      - "~/.claude"
+      - "~/.claude-work"
+
+  # $CODEX_HOME is respected; this overrides it.
+  openai:
+    paths:
+      - "~/.codex"
+
+  # Reports sessions but NO token counts, so every token field is null and the
+  # records are measurement:activity.
+  cline:
+    path: "~/.cline/data/sessions"
+
+  # SQLite; needs Node >= 22.5. Read from a temp snapshot so a live editor is
+  # never disturbed.
+  cursor:
+    db: "~/.cursor/ai-tracking/ai-code-tracking.db"
+
+  # A local gateway. measurement:overlay — excluded from token totals by
+  # default (it would double count the client adapter) but it carries the only
+  # MEASURED cost available anywhere.
+  headroom:
+    path: "~/.headroom"
+
+  # The independent work signal for the Productivity correlations.
+  git:
+    scanRoots:
+      - "~/code"
+      - "~/work"
+    autoFromUsage: true          # also use cwds seen in ingested usage records
+    author: "you@example.com"    # optional: only your own commits
+    since: "2026-01-01"          # optional
+
+store:
+  keepRaw: true                  # false still builds the cube; only the Data
+  rawRetentionDays: null         # Explorer and full CSV export need the shards
+
+analytics:
+  includeOverlaySources: false   # leave false; see the headroom note above
+  minSessionGapMinutes: 30       # only used for sources with no session id
+
+# Prepended to the built-in model -> vendor ruleset, so an internal alias maps
+# to the right vendor instead of falling through to "unknown".
+modelMappings:
+  - match: "^acme-llm-"
+    provider: acme
+    label: "Acme AI"
+  - match: "^internal-glm"
+    provider: zai
+    label: "Z.ai / GLM"
+
+# Interface is never inferred from the model. If you know a client's surface and
+# the source doesn't record one, say so here.
+interfaceOverrides:
+  my-batch-runner: "API"
+  team-slackbot: "Web"
+
+ui:
+  theme: dark
+  defaultRange: all
+  defaultFrom: "2026-03-14"      # floor for the DEFAULT VIEW only

package/examples/demo-data/README.md

@@ -0,0 +1,38 @@
+# Sample data
+
+Two ways to get a populated dashboard without connecting anything real.
+
+## 1. The mock provider (recommended)
+
+```bash
+npm run demo
+```
+
+Deterministic synthetic usage across four providers, three clients and four interfaces, with
+weekday seasonality, a mild upward trend, genuinely idle days and a bimodal daily rhythm — so the
+time-pattern and trend views have something real-shaped to show. Same seed, same output.
+
+Every record carries `metadata.demo = true` and `machine: "demo-machine"`, and the dashboard shows
+a persistent **DEMO DATA** banner while any of it is in scope. Clear it with:
+
+```bash
+tokenflow provider remove mock && tokenflow refresh --full
+```
+
+## 2. The generic importer (exercises a different code path)
+
+`sample-usage.csv` is a tiny hand-written export in the shape a third-party console tends to
+produce. Importing it exercises the mapping layer rather than the generator:
+
+```bash
+tokenflow import examples/demo-data/sample-usage.csv --dry-run    # see the inferred mapping
+tokenflow import examples/demo-data/sample-usage.csv
+```
+
+Things it deliberately contains:
+
+- an **empty** `cached_tokens` cell — must import as `null` (not available), never `0`
+- a model with no configured price (`glm-4.6`) — must import with `estimated_cost: null`
+- a quoted field containing a comma
+- three vendors, so provider classification has something to do
+- a `client` column, so interface classification has a real surface signal

package/examples/demo-data/sample-usage.csv

@@ -0,0 +1,11 @@
+created_at,model,client,surface,prompt_tokens,completion_tokens,cached_tokens,cost_usd,generation_id,project
+2026-08-05T09:12:00Z,claude-3-5-sonnet-20241022,my-runner,api,12400,860,9800,0.0412,gen-0001,billing-service
+2026-08-05T09:31:00Z,claude-3-5-sonnet-20241022,my-runner,api,13100,1240,11200,0.0455,gen-0002,billing-service
+2026-08-05T11:02:00Z,gpt-4o,vscode-ext,vscode,4200,510,0,0.0156,gen-0003,web-app
+2026-08-05T14:45:00Z,deepseek-chat,cli-tool,cli,8800,1900,6400,0.0045,gen-0004,data-pipeline
+2026-08-06T10:05:00Z,gpt-4o,vscode-ext,vscode,5100,720,1200,0.0184,gen-0005,web-app
+2026-08-06T10:40:00Z,glm-4.6,cli-tool,cli,9600,1400,,0.0031,gen-0006,"infra, terraform"
+2026-08-06T16:20:00Z,claude-3-5-sonnet-20241022,my-runner,api,21000,2100,18400,0.0620,gen-0007,billing-service
+2026-08-07T09:00:00Z,deepseek-chat,cli-tool,cli,3300,410,2100,0.0014,gen-0008,data-pipeline
+2026-08-07T13:15:00Z,glm-4.6,cli-tool,cli,15200,2600,,0.0058,gen-0009,web-app
+2026-08-07T20:55:00Z,claude-3-5-sonnet-20241022,my-runner,api,30500,3400,27000,0.0951,gen-0010,billing-service

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@vimoxshah/tokenflow",
+  "version": "1.1.0",
+  "description": "Local-first, provider-agnostic analytics for the AI tokens you actually spend. Zero dependencies, nothing leaves your machine.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "bin": {
+    "tokenflow": "bin/tokenflow.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./sdk": "./src/sdk.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "skills",
+    "examples",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "Refresh & Open Dashboard.command"
+  ],
+  "scripts": {
+    "setup": "node bin/tokenflow.js setup",
+    "dashboard": "node bin/tokenflow.js dashboard",
+    "refresh": "node bin/tokenflow.js refresh",
+    "status": "node bin/tokenflow.js status",
+    "demo": "node bin/tokenflow.js demo",
+    "test": "node --test \"test/**/*.test.js\"",
+    "typecheck": "tsc --noEmit -p jsconfig.json",
+    "typecheck:deps": "npm i --no-save --no-package-lock typescript@5 @types/node@22",
+    "lint": "node scripts/lint.js",
+    "validate": "node scripts/validate-install.js",
+    "start": "node bin/tokenflow.js up",
+    "up": "node bin/tokenflow.js up"
+  },
+  "keywords": [
+    "ai",
+    "tokens",
+    "usage",
+    "analytics",
+    "dashboard",
+    "claude",
+    "claude-code",
+    "openai",
+    "codex",
+    "cursor",
+    "cline",
+    "deepseek",
+    "observability",
+    "local-first",
+    "cost",
+    "llm"
+  ],
+  "dependencies": {},
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vimoxshah/tokenflow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vimoxshah/tokenflow/issues"
+  },
+  "homepage": "https://github.com/vimoxshah/tokenflow#readme",
+  "author": "Vimox Shah"
+}

package/scripts/build-dmg.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Package TokenFlow.app into a distributable DMG.
+#
+#   scripts/build-dmg.sh [version]        # → dist/TokenFlow-<version>.dmg
+#
+# Builds the app first (scripts/build-menubar-app.sh), then wraps it in a
+# drag-to-Applications DMG. Requires macOS with hdiutil (built in) and
+# Xcode Command Line Tools for swiftc. The DMG is unsigned — Gatekeeper
+# right-click → Open on first launch, see docs/getting-started.md.
+set -euo pipefail
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+VERSION="${1:-$(node -p "require('$REPO/package.json').version")}"
+DIST="$REPO/dist"
+APP="$DIST/TokenFlow.app"
+DMG="$DIST/TokenFlow-$VERSION.dmg"
+
+"$REPO/scripts/build-menubar-app.sh" "$DIST" "$VERSION" >/dev/null
+echo "built TokenFlow.app"
+
+STAGING="$(mktemp -d)"
+trap 'rm -rf "$STAGING"' EXIT
+
+cp -R "$APP" "$STAGING/"
+ln -s /Applications "$STAGING/Applications"
+
+rm -f "$DMG"
+hdiutil create -volname "TokenFlow $VERSION" \
+  -srcfolder "$STAGING" \
+  -ov -format UDZO \
+  "$DMG" | tail -1
+
+echo "wrote $DMG ($(du -h "$DMG" | cut -f1))"

package/scripts/build-menubar-app.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Build TokenFlow.app — TokenFlow's native macOS menu bar application.
+#
+#   scripts/build-menubar-app.sh [output-dir]
+#
+# Compiles menubar/TokenFlow/main.swift with swiftc (Xcode Command Line Tools)
+# into a minimal .app bundle, embedding the absolute paths of this clone's
+# node binary and CLI so the app can drive refresh/watch actions.
+set -euo pipefail
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+SRC="$REPO/menubar/TokenFlow/main.swift"
+OUT_DIR="${1:-$REPO/dist}"
+APP="$OUT_DIR/TokenFlow.app"
+# App version: first argument, else package.json version. Embedded into the
+# bundle's Info.plist so release CI can verify tag ↔ bundle consistency.
+VERSION="${2:-$(node -p "require('$REPO/package.json').version")}"
+
+command -v swiftc >/dev/null 2>&1 || {
+  echo "error: swiftc not found — install Xcode Command Line Tools:" >&2
+  echo "  xcode-select --install" >&2
+  exit 1
+}
+
+NODE_BIN="$(command -v node)"
+CLI_JS="$REPO/bin/tokenflow.js"
+[ -f "$CLI_JS" ] || { echo "error: $CLI_JS missing" >&2; exit 1; }
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+mkdir -p "$APP/Contents/MacOS"
+mkdir -p "$APP/Contents/Resources"
+cp "$REPO/menubar/TokenFlow/AppIcon.icns" "$APP/Contents/Resources/AppIcon.icns"
+
+cat > "$APP/Contents/Info.plist" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleName</key>                 <string>TokenFlow</string>
+    <key>CFBundleDisplayName</key>          <string>TokenFlow</string>
+    <key>CFBundleIdentifier</key>           <string>app.tokenflow.bar</string>
+    <key>CFBundleVersion</key>              <string>$VERSION</string>
+    <key>CFBundleShortVersionString</key>   <string>$VERSION</string>
+    <key>CFBundlePackageType</key>          <string>APPL</string>
+    <key>CFBundleExecutable</key>           <string>TokenFlow</string>
+    <key>CFBundleIconFile</key>             <string>AppIcon</string>
+    <key>LSMinimumSystemVersion</key>       <string>13.0</string>
+    <key>LSUIElement</key>                  <true/>
+    <key>NSHighResolutionCapable</key>      <true/>
+    <key>NSHumanReadableCopyright</key>     <string>MIT — local-first, nothing leaves your machine.</string>
+    <key>TokenFlowNodePath</key>            <string>$NODE_BIN</string>
+    <key>TokenFlowCLIPath</key>             <string>$CLI_JS</string>
+</dict>
+</plist>
+PLIST
+
+echo "compiling with $(swiftc --version | head -1)"
+swiftc -O -swift-version 5 \
+  -o "$APP/Contents/MacOS/TokenFlow" \
+  "$SRC" 2>&1 | head -40
+
+codesign --force --sign - "$APP" >/dev/null 2>&1 || true
+
+SIZE=$(du -h "$APP" | cut -f1 | tr -d ' ')
+echo "built: $APP ($SIZE)"

package/scripts/lint.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * A dependency-free linter for this project's own invariants.
+ *
+ * It is deliberately small and opinionated: it checks the things that would
+ * actually break the product (a syntax error, a `|| 0` on a token field, an
+ * `innerHTML` built from data, an unguarded localStorage call) rather than
+ * re-litigating formatting.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+const problems = [];
+const warnings = [];
+
+function walk(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (e.name.endsWith('.js')) out.push(p);
+  }
+  return out;
+}
+
+const files = [
+  ...walk(path.join(ROOT, 'src')),
+  ...walk(path.join(ROOT, 'bin')),
+  ...walk(path.join(ROOT, 'scripts')),
+  ...walk(path.join(ROOT, 'test')),
+];
+
+const TOKEN_FIELDS = /(input_tokens|output_tokens|cache_read_tokens|cache_write_tokens|cache_refresh_tokens|reasoning_tokens)/;
+
+const SELF = path.relative(ROOT, url.fileURLToPath(import.meta.url));
+
+for (const f of files) {
+  const rel = path.relative(ROOT, f);
+  const src = fs.readFileSync(f, 'utf8');
+  // The linter's own rule patterns would otherwise trip its own rules.
+  const isSelf = rel === SELF || rel.endsWith('scripts/lint.js');
+
+  // 1. it must parse
+  try {
+    execFileSync(process.execPath, ['--check', f], { stdio: 'pipe' });
+  } catch (err) {
+    problems.push(`${rel}: syntax error\n${String(err.stderr || err.message).split('\n').slice(0, 4).join('\n')}`);
+    continue;
+  }
+
+  const lines = src.split('\n');
+  lines.forEach((line, i) => {
+    const at = `${rel}:${i + 1}`;
+    if (isSelf && i > 30) return;
+    if (/\t/.test(line)) problems.push(`${at}: tab character`);
+    if (/[ \t]+$/.test(line)) problems.push(`${at}: trailing whitespace`);
+
+    // 2. the null contract: a token field must never be coerced to 0
+    if (TOKEN_FIELDS.test(line) && /\|\|\s*0\b/.test(line) && !/^\s*\*/.test(line)) {
+      problems.push(`${at}: "|| 0" on a token field — a missing value must stay null`);
+    }
+
+    // 3. untrusted labels must never be concatenated into HTML
+    if (/\.innerHTML\s*(\+?=)/.test(line) && /[`+]/.test(line.split('innerHTML')[1] || '')) {
+      if (!/html:/.test(line)) problems.push(`${at}: innerHTML built from an expression — use textContent`);
+    }
+
+    // 4. browser storage must be guarded, because a snapshot may run from file://
+    if (/localStorage|sessionStorage/.test(line) && !/^\s*(\/\/|\*)/.test(line)) {
+      const window = lines.slice(Math.max(0, i - 6), i + 6).join('\n');
+      if (!/try\s*\{/.test(window)) problems.push(`${at}: unguarded ${/local/.test(line) ? 'localStorage' : 'sessionStorage'} — wrap in try/catch`);
+    }
+
+    // 5. no stray debugging
+    if (/\bdebugger\b/.test(line)) problems.push(`${at}: stray debugger statement`);
+    if (/console\.(log|debug)\(/.test(line) && rel.startsWith('src/') && !rel.startsWith('src/ui/')) {
+      warnings.push(`${at}: console.${/debug/.test(line) ? 'debug' : 'log'} in library code`);
+    }
+
+    // 6. an empty catch should say why it is empty
+    if (/catch\s*(\([^)]*\))?\s*\{\s*\}\s*$/.test(line)) {
+      problems.push(`${at}: silent empty catch — add a comment explaining what is being ignored`);
+    }
+  });
+
+  if (!src.endsWith('\n')) problems.push(`${rel}: missing trailing newline`);
+  if (src.includes('\r\n')) problems.push(`${rel}: CRLF line endings`);
+}
+
+// 7. every provider directory must export a valid provider
+const provDir = path.join(ROOT, 'src', 'providers');
+for (const d of fs.readdirSync(provDir)) {
+  const idx = path.join(provDir, d, 'index.js');
+  if (!fs.existsSync(idx)) problems.push(`src/providers/${d}: missing index.js`);
+}
+
+const ok = problems.length === 0;
+if (warnings.length) {
+  console.log(`\n${warnings.length} warning(s):`);
+  for (const w of warnings.slice(0, 30)) console.log(`  ! ${w}`);
+}
+if (!ok) {
+  console.error(`\n${problems.length} problem(s):`);
+  for (const p of problems.slice(0, 60)) console.error(`  ✗ ${p}`);
+  if (problems.length > 60) console.error(`  … and ${problems.length - 60} more`);
+  process.exit(1);
+}
+console.log(`\n✓ lint clean — ${files.length} files checked`);