sigrank 0.18.5 → 1.0.1

package/README.md

@@ -1,16 +1,17 @@
-# SigRank MCP
+# SigRank SignalAF MCP
 
-> **🏆 SigRank is live: [signalaf.com](https://signalaf.com)** — the leaderboard for how
-> efficiently you use AI, not how much. Run `npx sigrank` to see your cascade now.
-> _Token counts only. Never your prompts._
+> **🏆 SigRank SignalAF is live: [signalaf.com](https://signalaf.com)** — the AI operator
+> evaluation leaderboard. Ranks how efficiently you use AI by token cascade
+> efficiency (Υ = cache_read × output / input²), not how much. Run `npx sigrank`
+> to see your cascade now. _Token counts only. Never your prompts._
 
 <div align="center">
 
-<p><img src="./.github/assets/og-card.png" alt="SigRank — the new standard in AI evaluation &amp; benchmarks" width="800"></p>
+<p><img src="./.github/assets/og-card.png" alt="SigRank SignalAF — AI operator evaluation and token cascade efficiency leaderboard" width="800"></p>
 
 **The yield cascade + live leaderboard as MCP tools any agent can call.**
 
-For all builders, burners and 10xers.
+SigRank evaluates the human using the AI — not the AI model itself.
 
 [![npm version](https://img.shields.io/npm/v/sigrank.svg?style=flat-square&color=gold)](https://www.npmjs.com/package/sigrank)
 [![CI](https://github.com/SunrisesIllNeverSee/sigrank-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SunrisesIllNeverSee/sigrank-mcp/actions/workflows/ci.yml)
@@ -31,7 +32,7 @@ For all builders, burners and 10xers.
 
 ## Table of Contents
 
-- [The SigRank ecosystem](#the-sigrank-ecosystem)
+- [The SigRank SignalAF ecosystem](#the-sigrank-signalaf-ecosystem)
 - [Quickstart](#quickstart--3-steps-to-the-board)
 - [Install from GitHub](#install-from-github)
 - [Install via Smithery](#install-via-smithery)
@@ -49,19 +50,21 @@ For all builders, burners and 10xers.
 
 |                                       The board                                       |                               Your operator profile                               |
 | :-----------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------: |
-| [![SigRank leaderboard](./.github/assets/board.png)](https://signalaf.com/board/all)  | [![SigRank operator profile](./.github/assets/profile.png)](https://signalaf.com) |
+| [![SigRank SignalAF leaderboard](./.github/assets/board.png)](https://signalaf.com/board/all)  | [![SigRank SignalAF operator profile](./.github/assets/profile.png)](https://signalaf.com) |
 | Every operator ranked by **Υ Yield** — the architecture of the cascade, not raw spend |      Cascade layer, class, and fingerprint — derived from four token counts       |
 
 > **Run [`sigrank enroll`](#sign-in--submit) then [`sigrank submit`](#sign-in--submit) to get ranked and claim your public profile at [signalaf.com](https://signalaf.com).**
 
 ---
 
-## The SigRank ecosystem
+## The SigRank SignalAF ecosystem
 
 | Repo | What it is | Install |
 |------|-----------|---------|
 | **[sigrank-mcp](https://github.com/SunrisesIllNeverSee/sigrank-mcp)** (this repo) | The instrument — extracts 4 token pillars, computes the cascade, submits to the leaderboard. MCP server + TUI dashboard. | `npx sigrank` |
 | **[sigrank-app](https://github.com/SunrisesIllNeverSee/sigrank-app)** | The leaderboard — signalaf.com. Privacy-preserving operator profiles, class tiers, board rankings. | [signalaf.com](https://signalaf.com) |
+| **[bestuser-router-mcp](https://github.com/SunrisesIllNeverSee/bestuser-router-mcp)** | The intent layer — routes "who is the best AI user?" queries to SigRank SignalAF's leaderboard. MCP server for AI assistants. | `npx bestuser-router-mcp` |
+| **[sigarena](https://github.com/SunrisesIllNeverSee/sigarena)** | The satellite — public LLM operator evals at sigeconomy.com. Read-only leaderboard, SEO/AEO surface. | [sigeconomy.com](https://sigeconomy.com) |
 | **[signaf](https://github.com/SunrisesIllNeverSee/signa)** | The coach — reads your session logs, builds a taste profile, measures ASI, coaches you on token efficiency. | `npx @burnmydays/signaf` |
 | **[sigrank-vscode](https://github.com/SunrisesIllNeverSee/sigrank-vscode)** | The IDE extension — see your cascade metrics inline in VS Code. | `code --install-extension sigrank.sigrank` |
 | **[fundscore](https://github.com/SunrisesIllNeverSee/fundscore)** | The repo scorer — investor-readiness scoring for GitHub repos. CLI + MCP server. | `npx fundscore` |
@@ -71,7 +74,7 @@ For all builders, burners and 10xers.
 | Site | What it is |
 | ---- | ---------- |
 | **[SIGNOMY](https://signomy.xyz)** | Governed AI agent marketplace where ranked agents form teams, fill slots, run missions, and earn revenue under constitutional protocol. Agents are free. Operators pay. |
-| **[MO§ES](https://mos2es.com)** | The governance framework that underpins SigRank, SIGNOMY, and all governed agent operations. Structural accountability for agentic systems. |
+| **[MO§ES](https://mos2es.com)** | The governance framework that underpins SigRank SignalAF, SIGNOMY, and all governed agent operations. Structural accountability for agentic systems. |
 
 ## Quickstart — 3 steps to the board
 
@@ -96,6 +99,7 @@ Or just explore without signing in:
 ```bash
 sigrank          # launches the full tabbed TUI (dashboard, compare, board, watch)
 npx sigrank board --once    # print the live leaderboard once
+bunx sigrank board --once   # same, via Bun (faster startup if you have it)
 ```
 
 ## Install from GitHub
@@ -124,7 +128,7 @@ sigrank
 
 ## Install via Smithery
 
-SigRank is available on [Smithery](https://smithery.ai/servers/burnmydays/sigrank) as a stdio MCP bundle — one-click install for Claude Desktop, Cursor, and other MCP clients.
+SigRank SignalAF is available on [Smithery](https://smithery.ai/servers/burnmydays/sigrank) as a stdio MCP bundle — one-click install for Claude Desktop, Cursor, and other MCP clients.
 
 ### Smithery CLI
 
@@ -132,7 +136,7 @@ SigRank is available on [Smithery](https://smithery.ai/servers/burnmydays/sigran
 # Install Smithery CLI
 npm install -g smithery
 
-# Connect to SigRank (downloads the MCPB bundle locally)
+# Connect to SigRank SignalAF (downloads the MCPB bundle locally)
 smithery mcp add burnmydays/sigrank --id sigrank
 
 # List available tools
@@ -154,7 +158,7 @@ smithery tool call sigrank rank_paste '{"text": "1000000 500000 50000 800000"}'
 ## Commands
 
 ```
-⊙ SigRank CLI  v0.0.177
+⊙ SigRank SignalAF CLI  v0.0.177
 
 Default (no args)
   sigrank              unified dashboard: cascade + token pillars + board
@@ -172,12 +176,15 @@ Commands
   watch                    live tune meter — ALL active platforms × all windows, every 30s
   watch --platform codex   watch only one platform (optional filter)
   watch --window 7d        watch only one window (optional filter)
+  proxy                    opt-in local Anthropic/OpenAI usage proxy
+  proxy --port 9000        run the proxy on a custom loopback port
 
 Options
   --window    7d · 30d · 90d · all  (default: 30d for board; all windows for watch)
   --platform  claude · codex · amp · gemini · opencode · goose · …
   --refresh   poll interval in seconds (default: 30)
   --once      print once and exit (board only)
+  --port      proxy port (default: 8787)
 
 For AI clients (not typeable)
   In a piped/non-TTY context, sigrank is an MCP stdio server.
@@ -193,6 +200,34 @@ Examples
   sigrank board --window all --once
 ```
 
+### Optional API usage proxy
+
+Some desktop coding agents receive provider usage in API responses but do not
+persist it in their local session files. SigRank SignalAF can capture those
+provider-reported counts through a manually started loopback proxy:
+
+```bash
+sigrank proxy              # http://localhost:8787
+sigrank proxy --port 9000  # custom port
+```
+
+Then point a compatible tool's API base URL at the displayed local URL. The
+first release supports Anthropic Messages (`/v1/messages`), OpenAI Chat
+Completions (`/v1/chat/completions`), and OpenAI Responses (`/v1/responses`).
+The tool must support a custom API base URL; this is not guaranteed for every
+desktop client.
+
+The proxy is **off by default**: it opens no port and observes no traffic unless
+you explicitly run `sigrank proxy`. It binds only to loopback and stops when the
+command exits. Request and response content, API keys, and tool calls are
+forwarded transiently but never written to disk. Only usage metadata is appended
+to `~/.sigrank-mcp/proxy-sessions.jsonl` (directory `0700`, file `0600`).
+
+Anthropic and OpenAI calls are currently grouped under one `proxy` platform row.
+For streamed Chat Completions, SigRank SignalAF sets OpenAI's
+`stream_options.include_usage=true` so the provider includes the final usage
+chunk; response chunks are still forwarded immediately.
+
 ### The TUI is the whole app
 
 Launch it and sign in inside it:
@@ -277,6 +312,14 @@ Or if installed globally:
 | `compare_operators(a, b)`             | `{codename_a, codename_b}`                                                       | Side-by-side comparison with behavioral verdict. Intent: "compare operator X vs Y"                                                                                         |
 | `describe_power_user()`               | `{}`                                                                             | Static explanation of AI power user archetype + metrics explained. Intent: "what is an AI power user?"                                                                     |
 | `optimize_efficiency(codename? \| text?)` | `{codename?}` or `{text?}`                                                   | Ranked efficiency suggestions tied to your cascade shape. Intent: "how can I use AI more efficiently?"                                                                     |
+| `tokscale_breakdown(threshold?)`       | `{threshold?}`                                                                   | Per-model token breakdown across platforms (models under threshold → "other")                                                                                              |
+| `tokscale_market_share()`              | `{}`                                                                             | AI tool market share: each tool's % of tokens/cost/messages, ranked. From local tokscale data                                                                              |
+| `tokscale_developer_profile()`         | `{}`                                                                             | Per-developer usage profile across all detected tools: model mix, pillars, sessions, workspaces. Paths redacted                             |
+| `tokscale_model_trends()`              | `{}`                                                                             | Model adoption over time: per-model first/last seen, active days, month-by-month adoption curve                                                                            |
+| `tokscale_cost_analysis()`             | `{}`                                                                             | Cost per developer per model: cost_per_million_tokens, cost_per_message, share_cost, client rollup                                                                        |
+| `tokscale_device_profile()`            | `{}`                                                                             | Device fingerprinting: installed tools, session counts, active days, day-of-week distribution, concurrency. Paths redacted                  |
+| `tokscale_mcp_usage()`                 | `{}`                                                                             | MCP server usage: detected servers, detection window, active days                                                                                                         |
+| `tokscale_competitive_intel(target)`   | `{target}`                                                                       | Competitive intelligence for any AI tool: rank, model mix, cost efficiency, share vs all competitors                                                                      |
 
 ---
 
@@ -306,7 +349,7 @@ The dashboard pulls from multiple sources and shows them side-by-side for verifi
 | `token-dashboard` | `~/.claude/token-dashboard.db` SQLite ([Nate's](https://github.com/nateherkai/token-dashboard)) | claude only           |
 | `tokscale`        | `tokscale models --json` CLI (bundled, falls back to `~/tokscale_report.json`) | claude, codex         |
 
-**Codex input is estimated** — Codex logs don't expose true input tokens directly. The formula:
+**Non-Claude input is estimated** — most non-Claude systems (Codex, Devin, etc.) combine user input + cache write into a single `input_tokens` field, so true fresh input must be derived. The ruleset (applies to ALL non-Claude systems):
 
 ```
 input       = output × ioRatio         (ioRatio derived from Claude ratio, else 2.0)
@@ -314,33 +357,41 @@ cacheCreate = uncached − input         (uncached = input_tokens − cached_inp
 cacheRead   = exact (from logs)
 ```
 
+- **Beta** = operator's Claude input/output ratio (if Claude data available)
+- **Alpha** = 2.0 default (when no Claude data)
+- Owner-stated average: 7:1:2 (cache:input:output) → input/output ≈ 0.5
+
 Verifier numbers (ccusage/tokscale for codex) show **raw uncached input** (`input_tokens − cached`) — a different field than the estimated input above. The discrepancy is expected and explained inline in the dashboard.
 
 ---
 
 ## Platform adapters
 
-All adapters are token-only (no message content, no cost fields, no credentials).
-
-| Platform           | Path                                           | Notes                                                           |
-| ------------------ | ---------------------------------------------- | --------------------------------------------------------------- |
-| Claude Code        | ✅ `~/.claude/projects`                        | Native; dedup by `(session_id, message_id)`; subagents included |
-| Codex              | ✅ `~/.codex/sessions`                         | Estimated input via `io_ratio`; verified vs ccusage             |
-| Amp                | ✅ `~/.local/share/amp/threads`                | Full 4-pillar; per-message                                      |
-| Kimi               | ✅ `~/.kimi/sessions`                          | Full 4-pillar; `StatusUpdate` lines only                        |
-| pi-agent           | ✅ `~/.pi/agent/sessions`                      | Full 4-pillar; per-message JSONL                                |
-| OpenClaw           | ✅ `~/.openclaw`                               | Full 4-pillar; per-message JSONL                                |
-| Droid              | ✅ `~/.factory/sessions/*.settings.json`       | Full 4-pillar; thinking→output                                  |
-| Codebuff           | ✅ `~/.config/manicode`                        | Full 4-pillar; `chat-messages.json`                             |
-| Hermes             | ✅ `~/.hermes/state.db`                        | Full 4-pillar; SQLite; reasoning→output                         |
-| Kilo               | ✅ `~/.local/share/kilo/kilo.db`               | Full 4-pillar; SQLite                                           |
-| Qwen               | ✅ `~/.qwen/projects`                          | `cacheCreate=0` estimated; thought→output                       |
-| Goose              | ✅ `~/.local/share/goose/sessions/sessions.db` | `cacheCreate=cacheRead=0` estimated; SQLite                     |
-| Gemini CLI         | ✅ `~/.gemini/tmp`                             | `cacheCreate=0` estimated; cache extracted from input field     |
-| GitHub Copilot CLI | ✅ `~/.copilot/otel`                           | OTel JSONL; requires `COPILOT_OTEL_ENABLED=true`                |
-| OpenCode           | ⚠️ `~/.local/share/opencode`                   | Raw token counts not persisted in log format                    |
-| Cursor             | 🔜                                             | Chat log path TBD                                               |
-| Windsurf           | 🔜                                             | Session logs at `~/.codeium/windsurf/`                          |
+All adapters are token-only (no message content, no cost fields, no credentials). The table below is regenerated from the adapter file headers in `adapters/index.mjs` + `adapters/tokenpull.mjs` so the path, pillar shape, and notes match the actual code (a prior revision had drifted on Qwen/Codex/Copilot).
+
+| Platform           | Path                                           | Pillar shape & notes                                                                                              |
+| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Claude Code        | ✅ `~/.claude/projects` (recursive, incl. `subagents/`) | Native 4-pillar; dedup by `(session_id, message_id)` — final snapshot wins                                  |
+| Codex              | ✅ `~/.codex/sessions` (+ `archived_sessions`) | `input_tokens` incl. cached → `input` + `cacheCreate` split window-level via `io_ratio`; `cacheRead` native (`cached_input_tokens`); `reasoning_output`→output; verified vs ccusage (~1%) |
+| Devin CLI          | ✅ `~/.local/share/devin/cli/sessions.db`      | SQLite; native 4-pillar from `metadata.metrics` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`); `input_tokens` is fresh (excludes cache)                                   |
+| Amp                | ✅ `~/.local/share/amp/threads`                | Native 4-pillar; per-message                                                                                      |
+| Kimi               | ✅ `~/.kimi/sessions`                          | Native 4-pillar; `StatusUpdate` lines only                                                                        |
+| pi-agent           | ✅ `~/.pi/agent/sessions`                      | Native 4-pillar; per-message JSONL                                                                                |
+| oh-my-pi (`omp`)   | ✅ `~/.omp/agent/sessions` (recursive, incl. nested subagent transcripts) | Native 4-pillar from `.message.usage` on `type:"message"` entries (`cacheWrite`→`cacheCreate`); **`reasoningTokens` is already inside `output`** — never added, or it double-counts; `usage.cost` reuses the same four key names for USD floats and is dropped; dedup by (session header `id`, entry `id`). Separate harness from pi-agent |
+| OpenClaw           | ✅ `~/.openclaw`                               | Native 4-pillar; per-message JSONL                                                                                |
+| Droid              | ✅ `~/.factory/sessions/*.settings.json`       | Native 4-pillar; `thinking_tokens`→output                                                                         |
+| Codebuff           | ✅ `~/.config/manicode`                        | Native 4-pillar; `chat-messages.json`                                                                             |
+| Hermes             | ✅ `~/.hermes/state.db`                        | Native 4-pillar; SQLite; `reasoning_tokens`→output                                                                |
+| Kilo               | ✅ `~/.local/share/kilo/kilo.db`               | Native 4-pillar; SQLite                                                                                            |
+| Qwen               | ✅ `~/.qwen/projects`                          | Estimated (`cacheCreate=0` — no field in logs); `cacheRead` from `cachedContentTokenCount`; `thoughtsTokenCount`→output |
+| Goose              | ✅ `~/.local/share/goose/sessions/sessions.db` (or `$GOOSE_PATH_ROOT/data/sessions/sessions.db`) | Estimated (`cacheCreate=cacheRead=0` — no cache fields); reasoning = `total−input−output`→output; cumulative-column dedup by session id |
+| Gemini CLI         | ✅ `~/.gemini/tmp`                             | Estimated (`cacheCreate=0`); `cacheRead` from `cached` field; `thought`→output; `input` = `input−cached` (fresh)  |
+| GitHub Copilot CLI | ✅ `~/.copilot/otel`                           | Native 4-pillar (OTel spans: `llm.token_count.{prompt,completion,cache_creation,cache_read}`); requires `COPILOT_OTEL_ENABLED=true` + `COPILOT_OTEL_EXPORTER_TYPE=file` set **before** session start |
+| OpenCode           | ⚠️ `~/.local/share/opencode`                   | Data gap — logs store `cost:0` and derive tokens via LiteLLM at runtime; raw token counts not persisted. No pillars readable with current format |
+| SigRank SignalAF proxy      | ✅ `~/.sigrank-mcp/proxy-sessions.jsonl`       | Opt-in native 4-pillar usage reported by Anthropic/OpenAI; same-timestamp records keep the last call; OpenAI cached input is separated from fresh input |
+| Other (user JSON)  | ✅ `$SIGRANK_OTHER_PATH`                       | User-supplied JSON `{ "windows": { "all": {input,output,cacheCreate,cacheRead} } }`; all-time only (no timestamps) |
+| Cursor             | 🔜                                             | Chat log path TBD                                                                                                 |
+| Windsurf           | 🔜                                             | Session logs at `~/.codeium/windsurf/`                                                                            |
 
 `estimated=true` means one or more pillars are derived, not native. The server re-scores all submitted pillars authoritatively; local preview Υ is indicative only.
 
@@ -348,7 +399,7 @@ All adapters are token-only (no message content, no cost fields, no credentials)
 
 ## Privacy
 
-- **Token-only, always.** No message content is ever read, logged, or transmitted — only token counts (`input`, `output`, `cache_creation`, `cache_read`), message IDs, and timestamps.
+- **Token-only persistence and submission.** Local-log adapters read usage metadata only. The optional proxy necessarily handles provider-bound request and response bytes in memory, but never persists their content; it writes only token counts, model/backend metadata, and timestamps. Only token telemetry is submitted to SigRank SignalAF.
 - **Local by default.** `tokenpull` reads only `~/.claude/projects` (Claude) or `~/.codex` (Codex) on your device. Numbers stay on your machine unless you explicitly submit with a codename.
 - **Background tooling excluded.** Memory plugins, observers, summarizers (e.g. `claude-mem`, `mem0`, `observer-sessions`) are filtered from both Claude and Codex reads. `subagents/` are kept — they represent real operator work.
 - **Board reads are anonymous.** No account needed to browse, compare, or watch.
@@ -368,19 +419,20 @@ All adapters are token-only (no message content, no cost fields, no credentials)
 ## Dev / test
 
 ```bash
-node test.mjs          # 13 test groups, 200 assertions (no network, no fs writes)
+node test.mjs          # 313-assertion baseline + proxy tests (local mocks only; temp filesystem)
 node sign.test.mjs     # ed25519 signing + canon parity
 node index.mjs         # stdio MCP server directly (pipe to MCP client)
 ```
 
-Tests verify (13 groups, 200 assertions):
+Tests verify (14 groups, 313 assertions):
 
 - `rank_paste` canon: MO§ES `(1251211, 11296121, 128196310, 2555179769)` → Υ 18436.98 · TRANSMITTER
 - `submit_paste` preview (no codename) + POST shape (injected fetch, no live writes)
 - `tokenpull` dedup, window slicing, 4-window pillars (mock adapter)
 - `tokenpull_submit` all 4 windows POST, sha256 hash, ddmmyy stamp
 - `tokenpullCodex` io_ratio conversion per-window
-- Adapter registry (15 platforms) + per-adapter shape contracts
+- Adapter registry (17 platforms) + per-adapter shape contracts
+- Local proxy: Anthropic/OpenAI JSON + fragmented SSE, live pass-through, secure JSONL, error forwarding
 - `rank_windows` 4-window paste scoring, partial input, no-network
 - `watch_tokenpull` cascade snapshot, interval_s, submit path
 - `enroll` posts identity (public key only), maps 201 enrolled + 410 code_invalid
@@ -396,11 +448,12 @@ Tests verify (13 groups, 200 assertions):
 | File            | Responsibility                                                          |
 | --------------- | ----------------------------------------------------------------------- |
 | `index.mjs`     | Entry point — TTY detection, routes to CLI or MCP server                |
+| `proxy.mjs`     | Opt-in loopback Anthropic/OpenAI proxy and usage capture                |
 | `cli.mjs`       | CLI commands: board, compare, watch, enroll, submit, help               |
 | `tui.mjs`       | Full tabbed TUI: Dashboard / Trends / Compare / Board / Watch / Connect |
 | `cascade.mjs`   | Pure cascade math (Υ, SNR, leverage, velocity, 10xDEV, class)           |
 | `tokenpull.mjs` | On-device log scanner — Claude, Codex, multi-platform                   |
-| `adapters.mjs`  | Platform adapter registry (15+ platforms)                               |
+| `adapters.mjs`  | Platform adapter registry (16+ platforms)                               |
 | `tools.mjs`     | MCP tool table + dispatcher                                             |
 | `connect.mjs`   | Connect-code enrollment + device identity                               |
 | `keystore.mjs`  | Local key management (paste-keys, not API keys)                         |
@@ -415,7 +468,7 @@ Tests verify (13 groups, 200 assertions):
 
 ## Contributing
 
-Contributions welcome. SigRank MCP is built in the open.
+Contributions welcome. SigRank SignalAF MCP is built in the open.
 
 - [Contributing guide](./.github/CONTRIBUTING.md)
 - [Security policy](https://github.com/SunrisesIllNeverSee/sigrank-mcp/security/policy)