@echomem/mcp 1.4.7 → 1.4.9

package/README.md

@@ -35,19 +35,28 @@ legacy EchoMem-synthesized recall answer.
 ## Quick start (recommended)
 
 ```bash
-# One command: install the CLI, detect your editor, write MCP config, log in via the browser.
-npm i -g @echomem/mcp@latest && echomem-mcp setup
+# One command, everything: download the bridge + HUD, configure every coding agent you have
+# installed (Codex, Claude Code, Claude Desktop, Cursor, Windsurf…), log in, and launch the HUD.
+npm i -g @echomem/mcp@latest && echomem-mcp init
 ```
 
-This keeps `echomem-mcp` available for later commands like `status`, `update`, `unlock`, and
-playground setup. `setup` detects the client (Cursor / Windsurf / Claude Desktop), writes its MCP
-config (with **no secret** in it — credentials live in `~/.echomem/credentials.json`, mode 0600),
-then opens the browser to approve the device and, for encrypted accounts, unlock the vault. Reload
-your editor and you're done.
+A global install (not `npx`) is recommended because it wires each editor to a **stable** path: a bare
+`npx` run resolves the bridge into a throwaway `_npx/<hash>` cache dir that npm later garbage-collects,
+which would break the MCP server after the fact (`setup` now refuses to pin such a path and falls back
+to the global install, but installing globally avoids the issue entirely). The context HUD's
+launch-at-login also runs from the installed path. `init` is the flagship one-liner — it wraps `setup --all --with-hud`: it writes each
+installed agent's MCP config (with **no secret** in it — credentials live in
+`~/.echomem/credentials.json`, mode 0600), adds the EchoMem memory guidance to their global
+`AGENTS.md` / `CLAUDE.md`, opens the browser to approve the device (and unlock the vault for
+encrypted accounts), then launches the context HUD. Reload your editors and you're done.
+
+Prefer to keep it minimal? `echomem-mcp setup` configures only the auto-detected editor and skips the
+HUD; the granular commands below still work.
 
 | Command | What it does |
 |---|---|
-| `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and run setup in one explicit step |
+| `npm i -g @echomem/mcp@latest && echomem-mcp init` | **Everything in one command** — all installed agents + HUD + login |
+| `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and configure just the detected editor |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
 | `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config without opening the browser or changing credentials |
@@ -90,6 +99,23 @@ because exact context composition and provider eviction are not observable.
 MCP fallback: agents can call `echo_context_health` to get the same score as markdown in-chat. This
 is on-demand; the passive HUD remains a separate local process.
 
+## Agent Doctor — local workspace forensics (new in 1.4.9)
+
+`echomem-mcp init` / `setup` now ends with an **Agent Doctor report**: a local scan of your
+Codex and Claude Code session logs that shows what your AI coding actually cost and where the
+context went dirty — rendered as an interactive 3D "repo city" plus a full forensic breakdown.
+
+- **Unified cost ledger.** Every provider request is priced individually from official API list
+  rates (model, cache write/read, long-context premiums, intro-pricing windows), so the headline
+  TOTAL SPENT, per-repo costs, per-model costs, and cost components all come from one path and
+  reconcile exactly. It is an **API-equivalent estimate of volume, not a bill you paid**.
+- **Fail-closed validation.** The report refuses to render unless every ledger reconciles
+  (tokens, costs, canonical waste analysis). Stale or preview data can never appear as your data.
+- **Wasteful-context analysis.** Canonical context windows label input tokens useful vs wasteful
+  (re-reads of unchanged files, re-finding, dead work) and project the waste over your billed input.
+- **Fully local, zero upload.** The scan reads local JSONL logs only: no transcripts are uploaded
+  and no LLM calls are made to build the report.
+
 ### Manual / headless (SSH, containers, CI)
 
 No browser? Provide secrets directly — this is the documented headless path:
@@ -118,7 +144,7 @@ npm test   # crypto compat + encrypted-local integration tests
 
 ### Add to your IDE (Cursor or Windsurf)
 
-> Prefer `npm i -g @echomem/mcp@latest && echomem-mcp setup` above — it writes these files for you and keeps secrets out of
+> Prefer `npm i -g @echomem/mcp@latest && echomem-mcp init` above — it writes these files for you and keeps secrets out of
 > the client config. The manual steps below are the fallback.
 
 #### For Cursor

package/assets/canonical-scorer/README.md

@@ -0,0 +1,18 @@
+# Vendored Context Golden Standard
+
+Copied from `/Users/erikhein/Desktop/Programming/iditor/context-golden-standard` on 2026-07-09:
+
+- `ErikMachine-Context_Golden_Standard/tools/golden_anchors.mjs`
+- `ErikMachine-Context_Golden_Standard/tools/optimizable_detail.mjs`
+- `tools/analyze-10-problems.mjs`
+- `tools/build-session-waste-dashboard.mjs`
+
+The scoring and allocation rules are unchanged. Local adaptations are limited
+to runner boundaries: `GOLDEN_JSON_ONLY=1` skips HTML/SVG rendering when the MCP
+setup scan needs JSON data only. Claude Code does not run through these vendored
+scripts; it uses a native JSONL/requestId/toolUseResult ledger in
+`src/context-analysis/claude-native-canonical.ts` and is merged with the Codex
+report at the workspace-report boundary.
+
+`src/context-analysis/vendored-canonical.ts` runs these files and adapts their
+JSON output to the setup-page report contract.