ashlr-plugin 1.36.4 → 1.37.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Open-source Claude Code plugin — 40 token-efficient MCP tools, 34 slash commands, GitHub OAuth sign-in, auto-genome from public repos, cloud-genome pull, per-session accounting, animated status line. MIT, opt-in telemetry.",
-    "version": "1.36.4"
+    "version": "1.37.1"
   },
   "plugins": [
     {
@@ -15,8 +15,8 @@
         "source": "url",
         "url": "https://github.com/ashlrai/ashlr-plugin.git"
       },
-      "description": "Token-efficient MCP tools for Claude Code — open-source WOZCODE alternative. Mean -57% savings overall on real codebases.",
-      "version": "1.36.4",
+      "description": "Token-efficient MCP tools for Claude Code, open-source WOZCODE alternative. Measured per-call savings: reads about -75%, greps about -50% (not end-to-end).",
+      "version": "1.37.1",
       "author": {
         "name": "Mason Wyatt",
         "url": "https://github.com/ashlrai"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ashlr",
-  "version": "1.36.4",
+  "version": "1.37.1",
   "description": "Open-source Claude Code plugin — 40 MCP tools and 34 slash commands, hybrid LLM summarization (Anthropic Haiku 4.5 default + ONNX offline + local opt-in), GitHub OAuth sign-in, auto-genome from public repos, cloud-genome pull on session start, PreToolUse redirect hooks (ASHLR_HOOK_MODE), unified $/MTok pricing (ASHLR_PRICING_MODEL), per-session token accounting, opt-in telemetry, animated status line, shareable SVG savings badge. MIT.",
   "author": {
     "name": "Mason Wyatt",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ashlr",
-  "version": "1.36.4",
+  "version": "1.37.1",
   "description": "Multi-host AI coding efficiency layer for Codex and Claude Code: 40 MCP tools, Codex skills, nudge-first hooks, genome memory, and token savings accounting.",
   "author": {
     "name": "Mason Wyatt",

package/README.md

@@ -1,7 +1,9 @@
 # ashlr-plugin
 
-> **Cut Codex and Claude Code token usage by −57% on real codebases.**
-> _TS −62% · Python −65% · Rust −44%_ — measured on `vercel/ai`, `pandas`, and `tokio`.
+**Same agent. Fewer tokens.**
+
+> **Fewer tokens per tool call in Codex and Claude Code: reads about −75%, greps about −27% on vercel/ai, pandas and tokio (per-call benchmark, not end to end).**
+> _TS −60% · Python −63% · Rust −55%_ — measured on `vercel/ai`, `pandas`, and `tokio`.
 > 95% CI reported by the benchmark runner. Reproduce with `bun run scripts/run-benchmark.ts --compare`. ([full methodology](docs/benchmarks.md))
 
 40 MCP tools that replace high-volume `Read` / `Grep` / `Edit` / `Bash` workflows with versions that return **less** without losing what matters. Claude Code gets automatic PreToolUse redirects (`ASHLR_HOOK_MODE=redirect`); Codex gets first-class plugin packaging, MCP, skills, and nudge-first hooks.
@@ -24,7 +26,7 @@ The npm package exposes `ashlr-plugin` for CLI workflows and `ashlr-mcp` for MCP
 
 **Landing page:** [plugin.ashlr.ai](https://plugin.ashlr.ai/) · **Docs:** [plugin.ashlr.ai/docs](https://plugin.ashlr.ai/docs) · **Core library:** [`@ashlr/core-efficiency`](https://github.com/ashlrai/ashlr-core-efficiency) · **License:** MIT
 
-> **Open-source and honestly benchmarked.** The −57% headline is reproducible on your own code with `bun run scripts/run-benchmark.ts --compare` ([methodology](docs/benchmarks.md)). Every ashlr savings figure includes a 95% CI. Telemetry is off by default. Compare against closed, self-benchmarked alternatives with `/ashlr-benchmark --compare`.
+> **Open-source and honestly benchmarked.** The per-call figures are reproducible on your own code with `bun run scripts/run-benchmark.ts --compare` ([methodology](docs/benchmarks.md)). Every ashlr savings figure includes a 95% CI. Telemetry is off by default. Compare against closed, self-benchmarked alternatives with `/ashlr-benchmark --compare`.
 
 [![CI (Linux · macOS · Windows)](https://github.com/ashlrai/ashlr-plugin/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/ashlrai/ashlr-plugin/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush)
 
@@ -32,7 +34,20 @@ The npm package exposes `ashlr-plugin` for CLI workflows and `ashlr-mcp` for MCP
 
 ---
 
-## What's new in v1.36
+## What's new in v1.37
+
+- **Tools act on your project** — MCP tools resolve relative paths and default folders against the folder the host launched them in, not the plugin's install folder. Phantom fleet worktrees are no longer refused.
+- **Faster hooks** — each SessionStart and PostToolUse event starts one `node` launcher instead of one per hook (CPU per native Edit 712 → 319 ms in a Linux container), and SessionStart exits in about 0.6 s instead of 2.1 s.
+- **Claude Code hooks detected correctly** — hooks under Claude Code no longer run in Codex nudge mode.
+- **Works without Bun on PATH** — the npm bins start under node and find or explain Bun instead of failing with `env: 'bun'`.
+- **Readable grep fallback** — `ashlr__grep` without a genome returns plain `path:line:text` matches, says when ripgrep stopped early, and is benchmarked against plain `rg -n` (about −27% per call).
+- **Shorter edit replies** — exact, unique `ashlr__edit` matches return the header only.
+- **New host ids** — `ASHLR_MCP_HOST=gemini-cli` and `cursor`.
+
+See the [CHANGELOG](CHANGELOG.md) for the full list.
+
+<details>
+<summary>v1.36 highlights</summary>
 
 - **Codex-native plugin packaging** — `.codex-plugin/plugin.json`, `.mcp.json`, Codex workflow skills, Codex explorer/worker agent guidance, and portable Codex hooks ship in the same package as the Claude Code plugin.
 - **Reliable Codex MCP launch** — `ashlr-mcp` starts the router directly with `ASHLR_MCP_HOST=codex-cli`, workspace-aware `cwd` behavior, and `ASHLR_ALLOW_PROJECT_PATHS` support for non-plugin launch directories.
@@ -44,6 +59,8 @@ The npm package exposes `ashlr-plugin` for CLI workflows and `ashlr-mcp` for MCP
 - **API-measured savings mode** — when `ANTHROPIC_API_KEY` is set, token counts upgrade from `(est.)` to `(API-measured)` once ≥10 calls have been verified via the Anthropic API. Fire-and-forget; SHA-256 cached; never blocks a tool call.
 - **Benchmark transparency** — `scripts/run-benchmark.ts` now reports a 95% bootstrap confidence interval alongside the headline. New flags: `--compare` (A/B table), `--validate-tokenizer` (API spot-check of the chars/4 heuristic). See [benchmark methodology](docs/benchmarks.md).
 
+</details>
+
 <details>
 <summary>v1.33 highlights</summary>
 
@@ -53,7 +70,7 @@ The npm package exposes `ashlr-plugin` for CLI workflows and `ashlr-mcp` for MCP
 - **Orchestration retry + handoff budget** — per-node retry-with-backoff; HANDOFF_PAYLOAD capped at 8KB.
 - **Orchestration central quota accounting** — `orchestration_usage` table for Team-tier soft-throttle.
 - **Bun ≥ 1.3 prereq surfaced** + wizard restart enforcement — closes 2 fatal first-touch cliffs.
-- **Orchestrator overhead bench** — measured ~5-30ms/node, 2.8× parallel speedup vs sequential.
+- **Orchestrator overhead bench** — per-node overhead and parallel speedup are measured by the orchestrator bench; no figure is published here until it is reproducible from this repo.
 - **Pre-existing tsc errors fixed** + permanent dashboard date-drift fix via clock injection.
 
 </details>
@@ -64,13 +81,13 @@ The npm package exposes `ashlr-plugin` for CLI workflows and `ashlr-mcp` for MCP
 <summary>v1.32 highlights</summary>
 
 - **`/ashlr-orchestrate`** — multi-agent task graphs with parallel execution, dry-run renderer, and tier-gated subprocess wiring.
-- **`/ashlr-orchestrate-status`** — inspect past orchestration runs with per-node telemetry and 2.8× measured parallel speedup.
+- **`/ashlr-orchestrate-status`** — inspect past orchestration runs with per-node telemetry.
 - **Live genome** — PR-aware + commit-aware sections via git post-commit hook and GitHub webhook delta sync.
 - **AI-Native discoveries** — LLM synthesizes `discovery` sections from your commit history automatically.
 - **Predictive prefetch** *(Pro/Team)* — background warm-cache on every `ashlr__read` cuts repeat-hit latency.
 - **PR + issue retrieval** — `ashlr__grep --include-prs --include-issues --since-days` pulls live GitHub context.
 - **Freshness badges** in genome retrieval surface staleness so you trust the answer.
-- **Cross-language bench:** TS −61.3% · Python −63.1% · Rust −46.8% (cross-language headline `-57.1%` holds).
+- **Cross-language bench (per-call, not end to end):** TS −61.3% · Python −63.1% · Rust −46.8%, about −57% averaged across tool calls. This is not a measured reduction in total session cost.
 - **Founder WAD-D dashboard** at `/admin/wad-d` — daily-active records + segment breakdown + discovery propagation.
 
 </details>
@@ -270,6 +287,22 @@ cd ~/.claude/plugins/cache/ashlr-marketplace/ashlr && bun install
 
 ---
 
+## Provider base URLs
+
+The plugin's own provider calls (the summarizer and token-count calls to Anthropic, the genome reachability probes for Anthropic and OpenAI, and the Ollama checks in `/ashlr-ollama-setup` and `genome-init`) read the usual environment variables and keep their old defaults when none is set:
+
+| Variable | Default | Form |
+|---|---|---|
+| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | root, without `/v1` |
+| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | includes `/v1` |
+| `OLLAMA_HOST` | `http://localhost:11434` | `host`, `host:port`, `:port` or a full URL |
+
+Trailing slashes are trimmed. Pointing these at a gateway such as a LiteLLM proxy or a Phantom proxy is therefore possible, because the plugin just sends its requests to whatever URL you set. Only the URL handling is covered by tests here; the plugin has not been tested against any specific gateway, and what a gateway does with your keys and requests is documented by that gateway. Not covered: the Ollama probe in the session greeting and the optional `ASHLR_EMBED_URL` embedding endpoint, which keep their own settings.
+
+`/ashlr-doctor` also lists whether the optional Phantom CLI is installed and which version. It runs only `phantom --version` and never reads or reveals secret values. To run tools with Phantom placeholder keys and base URLs, start them with `phantom exec -- <cmd>`.
+
+Running the doctor and benchmark scripts under Phantom is supported only through `phantom exec`, for example `phantom exec -- bun run scripts/doctor.ts` or `phantom exec -- bun run scripts/run-benchmark.ts --validate-tokenizer`. Inside such a session the doctor's `phantom exec` line reports the proxy port, which provider keys hold `phm_` placeholders and which base URLs point at the local proxy (with the session token redacted). It warns when a key is a `phm_` placeholder outside a session, when a placeholder's base URL does not point at the proxy, or when a key is a `phm:` reference. The plugin never resolves `phm:` references, never runs `phantom reveal` and never prints key values; `run-benchmark --validate-tokenizer` skips the API sample when the key would not work from that process. Detection uses variable names, the `phm` prefixes and the base URL host and port only; it has not been tested against a live Phantom session here.
+
 ## Commands
 
 | Command | Description |
@@ -281,7 +314,7 @@ cd ~/.claude/plugins/cache/ashlr-marketplace/ashlr && bun install
 | `/ashlr-doctor` | 11-check diagnostic — deps, MCP reachability, hooks, settings |
 | `/ashlr-tour` | 60-second guided walkthrough on your current project |
 | `/ashlr-benchmark` | Token-savings benchmark against your current project |
-| `/ashlr-genome-init` | Initialize `.ashlrcode/genome/` for the −84% grep path |
+| `/ashlr-genome-init` | Initialize `.ashlrcode/genome/` for the genome-backed grep path |
 | `/ashlr-ollama-setup` | Diagnose Ollama for `--summarize`; pull recommended 3B model |
 | `/ashlr-settings` | View or change plugin toggles |
 | `/ashlr-update` | `git pull` + `bun install` + report what changed |
@@ -306,6 +339,14 @@ See [plugin.ashlr.ai/docs/contributing/architecture](https://plugin.ashlr.ai/doc
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.
 
+## Part of the Ashlr ecosystem
+
+The Ashlr plugin is one of the open-source tools from [Ashlr](https://ashlr.ai), a forward-deployed engineering company. Its siblings: [Lexicon](https://github.com/ashlrai/lexicon), [Locus](https://github.com/ashlrai/locus), [Phantom Secrets](https://github.com/ashlrai/phantom-secrets), [Ashlr Stack](https://github.com/ashlrai/ashlr-stack), [Ashlr Markdown](https://github.com/ashlrai/ashlr-md).
+
+## Contributing
+
+Issues and PRs are welcome. Look for [`good first issue`](https://github.com/ashlrai/ashlr-plugin/labels/good%20first%20issue) to get started, and read [CONTRIBUTING.md](CONTRIBUTING.md). Report security problems privately per [SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT — [LICENSE](./LICENSE).

package/commands/ashlr-doctor.md

@@ -25,6 +25,35 @@ Steps:
 
 4. If the script itself exits non-zero (couldn't find the plugin root at all), print the stderr and stop — nothing else will work until that's resolved.
 
+## Companions
+
+The **companions** section lists the other Ashlr tools on this machine:
+phantom (`phm`), phantom-secrets (`phantom`), locus, lexicon, ashlr-md
+(`mdopener-mcp`) and ashlr-stack (`stack`). Each is asked for
+`--ashlr-handshake --json` with a 2 second timeout and an environment of only
+PATH, HOME, USER, locale and TMPDIR, so no token reaches it.
+
+- `✓ locus  0.5.1 ready [capabilities]`: answered and healthy.
+- `· name  0.6.0 health: degraded`, `installed, too old for --ashlr-handshake`,
+  `installed, handshake unreadable or timed out`, or `not installed`: shown
+  with a one-line `fix:` hint. All probes run in parallel, so the section
+  takes about 2 seconds at most.
+- When locus, lexicon or ashlr-md reports health other than `ok` and lists
+  the `doctor-fix` capability, its hint is `run locus doctor --fix`,
+  `run lexicon doctor --fix` or `run mdopener-mcp doctor --fix` (a dry run;
+  `--apply` makes the repairs). The hint keys on the capability only, never on the
+  version, and a healthy companion gets nothing extra. Same rule as
+  `stack doctor --ecosystem`.
+
+These lines are informational: they never count as warnings or failures and
+never change the exit code. `bun run scripts/doctor.ts --json` prints the whole
+report as JSON, with a `companions` array of
+`{ name, command, state, version, capabilities, health, fix, next_steps }`
+where `state` is `ready`, `degraded`, `outdated` (printed no JSON),
+`unknown` (timed out, or printed JSON that is not a v1 handshake) or
+`missing`, `health` is the handshake's `health.status` (null without one),
+and `next_steps` lists capability-gated commands (empty when there are none).
+
 ## Cloud check
 
 The report includes a **cloud** section that pings `GET /healthz` on the

package/commands/ashlr-status.md

@@ -16,7 +16,7 @@ Format:
 ```
 ashlr-plugin v0.1.0
   server:  ✓ reachable
-  genome:  ✓ (.ashlrcode/genome found) | ✗ (no genome — run `/genome init`)
+  genome:  ✓ (.ashlrcode/genome found) | ✗ (no genome — run `/ashlr-genome-init`)
   core:    @ashlr/core-efficiency@0.1.0
   session: 12 calls, ~8,450 tokens saved
 ```

package/docs/PHANTOM-USAGE.md

@@ -0,0 +1,58 @@
+# Using ashlr-plugin with Phantom
+
+This page covers running the plugin under Phantom Secrets (`phantom exec`, `phm_` placeholders) and in front of a model gateway such as LiteLLM. For the full provider and gateway rules see [llm-providers.md](llm-providers.md) and [embeddings-gateway.md](embeddings-gateway.md).
+
+## Running under `phantom exec`
+
+Start the agent, or a plugin script, as `phantom exec -- <cmd>`, for example `phantom exec -- claude`. Phantom then does three things:
+- It gives the child fresh `phm_` session placeholders instead of real keys, for example in `ANTHROPIC_API_KEY` and `OPENAI_API_KEY`.
+- It points `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` at a local proxy: `http://127.0.0.1:<port>/<route>/_phantom/<token>/`.
+- It sets `PHANTOM_PROXY_PORT`, `PHANTOM_PROXY_TOKEN` and `PHANTOM_SESSION_KEYS`.
+
+The plugin sends the placeholder unchanged, and the proxy swaps in the real key on the way out. The proxy URL is loopback http, so it passes the plugin's base URL rules.
+
+How the plugin behaves in a session:
+- **Detection by name and prefix only.** `servers/_phantom-exec.ts` detects a session from variable names, the `phm_` and `phm:` prefixes, and the base URL host and port. It never reads or prints a key, and it redacts the proxy token from any URL it reports.
+- **The doctor reports the session.** `/ashlr-doctor` shows a `phantom exec` line and warns, without values, about two cases: a `phm_` placeholder outside a session, and a placeholder whose base URL does not point at the session's proxy.
+- **The benchmark skips unusable keys.** `run-benchmark --validate-tokenizer` skips its API sample when the key would not work, and says why.
+- **`phm:` references are never resolved.** A `phm:` reference in a key variable is not resolved and is never sent. Run under `phantom exec` so the variable holds a placeholder instead.
+- Do not use `phantom reveal` to put a real key into the environment for the plugin.
+
+## Settings that exist
+
+| Variable | Default | What it is |
+|---|---|---|
+| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | Anthropic root, without `/v1` |
+| `ANTHROPIC_API_KEY` | unset | Anthropic key, or a `phm_` placeholder under `phantom exec` |
+| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible root, with `/v1` |
+| `OPENAI_API_KEY` | unset | OpenAI key, or a `phm_` placeholder |
+| `OLLAMA_HOST` | `http://localhost:11434` | Ollama: `host`, `host:port`, `:port` or a full URL; keyless |
+| `ASHLR_LLM_URL` | `http://127.0.0.1:1234/v1` | Local OpenAI-compatible server for summarization, orient and genome merging |
+| `ASHLR_LLM_KEY` | `local-llm` | Bearer for `ASHLR_LLM_URL` |
+| `ASHLR_LLM_MODEL` | `qwen/qwen3-coder-30b@8bit` | Model name for `ASHLR_LLM_URL` |
+| `ASHLR_API_URL` | `https://api.ashlr.ai` | Ashlr cloud API (Pro) |
+| `ASHLR_PRO_TOKEN` | unset | Ashlr Pro token |
+| `ASHLR_EMBED_URL`, `ASHLR_EMBED_FORMAT=openai`, `ASHLR_EMBED_KEY`, `ASHLR_EMBED_MODEL` | Ollama format | Opt-in OpenAI-compatible embeddings ([embeddings-gateway.md](embeddings-gateway.md)) |
+| `ASHLR_GATEWAY_STRICT=1`, `ASHLR_GATEWAY_HOSTS` | off | Strict allowlist for any call that carries a key |
+
+The base rules apply to calls that carry a key, even without strict mode:
+- `https`, or plain `http` only to `127.0.0.1` or `[::1]`. The name `localhost` does not count.
+- No credentials in the URL.
+- No redirects followed.
+
+A refused URL makes no request, and the refusal names only the scheme, host and port.
+
+## LiteLLM
+
+If a LiteLLM proxy sits between the plugin and the providers, use LiteLLM 1.83.0 or newer, never 1.82.7 or 1.82.8.
+
+- **Why 1.83.0:** `litellm` 1.82.7 and 1.82.8 on PyPI were compromised releases that carried credential-stealing code (GHSA-5mg7-485q-xm76, March 2026). 1.83.0, published to PyPI on 2026-03-31, was the first clean release, built by LiteLLM's rebuilt release pipeline ([LiteLLM security update](https://docs.litellm.ai/blog/security-update-march-2026)).
+- **Use a current release, not just 1.83.0.** Later advisories were fixed in later releases (for example GHSA-3cv6-jpf6-8222). On 2026-10-19 the current PyPI release was 1.106.0. Check LiteLLM's security advisories before you pick or upgrade a version.
+- **Install it verifiably.** Use a hash-pinned install (`pip install --require-hashes -r requirements.txt`) or the official `ghcr.io/berriai/litellm` image, checked with `cosign verify` as LiteLLM's README shows. Run it in a container that does not mount your home directory or dotfiles.
+- Keep the provider keys on the LiteLLM side. Give the agent only the proxy URL and, if the proxy needs one, a proxy key that is separate from the provider keys.
+
+To route the plugin's local-provider calls through LiteLLM, set `ASHLR_LLM_URL=http://127.0.0.1:4000/v1` (LiteLLM's default port) and `ASHLR_LLM_KEY` to the proxy key. For a remote LiteLLM, use `https://` and, with `ASHLR_GATEWAY_STRICT=1`, list its exact `host:port` in `ASHLR_GATEWAY_HOSTS`.
+
+## What is tested
+
+Session detection, the doctor line, the benchmark skip and the URL rules are covered by tests against local stub servers (`__tests__/phantom-exec.test.ts`, `__tests__/doctor-phantom.test.ts`, `__tests__/gateway-target.test.ts`). The plugin has not been tested against a live Phantom session or a live LiteLLM proxy here.

package/docs/architecture.md

@@ -12,7 +12,7 @@ ashlr-plugin is a multi-host plugin for Codex and Claude Code that wraps file, s
 
 Two value propositions:
 
-**Token efficiency.** `ashlr__read`, `ashlr__grep`, and `ashlr__edit` replace the built-in `Read`, `Grep`, and `Edit` tools. Large file reads are snip-compacted or LLM-summarized; grep calls route through a per-project genome index (RAG) when one exists, cutting tokens by ~84% on warm queries; edits send only diffs, not full file contents.
+**Token efficiency.** `ashlr__read`, `ashlr__grep`, and `ashlr__edit` replace the built-in `Read`, `Grep`, and `Edit` tools. Large file reads are snip-compacted or LLM-summarized; grep calls route through a per-project genome index (RAG) when one exists, cutting tokens on warm queries (not covered by the published benchmark); edits send only diffs, not full file contents.
 
 **Observability.** Every tool call is accounted in `~/.ashlr/stats.json` (per-session + lifetime counters) and appended to `~/.ashlr/session-log.jsonl`. Claude Code surfaces savings in the status line; Codex surfaces them through MCP tools, CLI commands, and skills. The genome scribe loop extracts architectural knowledge from tool results into `.ashlrcode/genome/`, which feeds back into future grep routing.
 
@@ -206,7 +206,7 @@ SessionEnd
     └──► hooks/session-end-stats-gc.ts     (drop session bucket, append summary to log)
 ```
 
-PreToolUse hooks are matcher-filtered — Claude Code only fires them for the named tool. PostToolUse has a pipe-separated matcher covering both native tools and the ashlr MCP variants (canonical prefix `mcp__plugin_ashlr_ashlr__ashlr__*` as of v1.13 router consolidation; all matchers in `hooks/hooks.json` renamed to this form in v1.18 after legacy `mcp__ashlr-efficiency__*` / `mcp__ashlr-multi-edit__*` stopped matching post-router-migration).
+PreToolUse hooks are matcher-filtered — Claude Code only fires them for the named tool. SessionStart and PostToolUse each have one entry that runs `scripts/hook-bootstrap.mjs --group`: a single node launcher starts every hook for the event as its own `bun` process, in parallel, and merges their output. In PostToolUse a `--match` before a hook keeps that hook's own tool filter, and the entry's matcher is the union of them. PostToolUse has a pipe-separated matcher covering both native tools and the ashlr MCP variants (canonical prefix `mcp__plugin_ashlr_ashlr__ashlr__*` as of v1.13 router consolidation; all matchers in `hooks/hooks.json` renamed to this form in v1.18 after legacy `mcp__ashlr-efficiency__*` / `mcp__ashlr-multi-edit__*` stopped matching post-router-migration).
 
 ---
 
@@ -301,7 +301,7 @@ Source: `servers/_summarize.ts`.
 
 **When it fires.** Each tool that handles large output (read, grep, edit, bash, sql, diff) checks if the raw result exceeds ~2KB. If so it calls `summarize(content, toolName)`.
 
-**Local-first.** Default endpoint is `http://localhost:1234/v1` (LM Studio). Override via `ASHLR_LLM_URL` + `ASHLR_LLM_KEY` for cloud. Cloud only fires when explicitly set; the plugin has no account requirement and telemetry is off by default.
+**Local-first.** Default endpoint is `http://127.0.0.1:1234/v1` (LM Studio). Override via `ASHLR_LLM_URL` + `ASHLR_LLM_KEY` for cloud. Cloud only fires when explicitly set; the plugin has no account requirement and telemetry is off by default.
 
 **Cache.** SHA-256 of the input is used as cache key. Cache files live at `~/.ashlr/summary-cache/<hash>.txt` with a 1-hour TTL. A cache hit costs zero tokens.
 
@@ -375,7 +375,7 @@ Version bumping is manual: edit `plugin.json:version` and `CHANGELOG.md` before
 
 These are the non-obvious decisions baked into the codebase.
 
-**Local-first LLM, opt-in telemetry.** The summarization helper calls `localhost:1234` by default. No summarization payload leaves the machine unless the user explicitly sets `ASHLR_LLM_URL`; telemetry is off by default and has to be enabled separately.
+**Local-first LLM, opt-in telemetry.** The summarization helper calls `127.0.0.1:1234` by default. No summarization payload leaves the machine unless the user explicitly sets `ASHLR_LLM_URL`; telemetry is off by default and has to be enabled separately.
 
 **Atomic stats writes.** A two-layer write protocol (in-process Promise chain + `O_EXCL` lockfile + `rename`) ensures that N concurrent MCP servers and hooks never corrupt `stats.json`. Any approach that just does `JSON.parse` → mutate → `writeFile` will lose updates under load. The lockfile spin is capped at 200ms; if it can't acquire, it skips the write rather than blocking the tool call.
 
@@ -391,7 +391,7 @@ These are the non-obvious decisions baked into the codebase.
 
 ## Supported Platforms
 
-ashlr-plugin is tested in CI on three operating systems via a matrix strategy in `.github/workflows/ci.yml`. The `typecheck`, `test`, and `smoke` jobs all run on every OS on every push.
+ashlr-plugin is tested in CI on three operating systems in `.github/workflows/ci.yml`. Typecheck, unit tests and smoke run on Linux for every PR and on macOS and Windows for every push to main, the weekly schedule, and PRs labelled `ci:full-os`.
 
 | Platform | Runner | Status |
 |---|---|---|

package/docs/ashlr-handshake.md

@@ -0,0 +1,36 @@
+# Ashlr companion handshake (v1)
+
+`ashlr-plugin --ashlr-handshake` prints one JSON object and exits 0. `phm companions`,
+`phm doctor` or an agent can call it instead of parsing `--help`. The same
+contract is implemented by `stack --ashlr-handshake` (ashlr-stack) and
+`locus --ashlr-handshake`.
+
+```json
+{
+  "kind": "ashlr.handshake",
+  "schema_version": 1,
+  "name": "ashlr-plugin",
+  "command": "ashlr-plugin",
+  "version": "1.37.1",
+  "protocols": { "ashlr.handshake": 1, "phantom.agent.preflight": 1 },
+  "capabilities": ["token-efficient-tools", "mcp-server", "claude-code-plugin", "codex-install", "savings-stats", "agent-preflight", "doctor"],
+  "health": { "status": "ok", "checks": [{ "id": "bun-on-path", "status": "ok" }, { "id": "phantom-on-path", "status": "absent" }] },
+  "edits": ["~/.ashlr/", "~/.claude/settings.json", "~/.codex/config.toml"],
+  "receipts": []
+}
+```
+
+Rules every implementation follows:
+
+- **Fast and local:** no network, no vault or keychain, and no secret values or project contents in the output.
+- **Stable shape:** `kind` and `schema_version` identify the contract. New fields may be added in v1; renames or removals bump `schema_version`.
+- **Ids:** `capabilities` and check `id`s are kebab-case. `protocols` maps a protocol name to the version spoken.
+- **Health:** `health.status` is `ok`, `degraded` (works, something it relies on is missing) or `unknown`. A check status is `ok`, `missing` (counts against health) or `absent` (informational, such as phantom not installed when ASHLR_PHANTOM_PREFLIGHT is off).
+- **Edits:** paths the CLI may write. `~/` is the home directory; other paths are relative to the project.
+- **Receipts:** receipt kinds the CLI emits (none yet; reserved for receipt.v1).
+
+The npm launcher (`scripts/ashlr-plugin.mjs`, plain node) answers before it looks for bun, so a machine without bun gets `bun-on-path: missing` and `degraded` instead of an error.
+
+## Consumers
+
+`ashlr doctor` reads companions through this handshake (see commands/ashlr-doctor.md, "Companions"), as does `stack doctor --ecosystem`.

package/docs/assets/og.svg

@@ -32,7 +32,7 @@
 
   <!-- Sub -->
   <text x="80" y="490" font-family="IBM Plex Sans, sans-serif" font-size="24" fill="#121212" opacity="0.8" font-weight="400">Open-source Codex + Claude Code plugin — token-efficient Read, Grep, Edit.</text>
-  <text x="80" y="524" font-family="IBM Plex Sans, sans-serif" font-size="24" fill="#121212" opacity="0.55">Mean −57% savings across reference repos.</text>
+  <text x="80" y="524" font-family="IBM Plex Sans, sans-serif" font-size="24" fill="#121212" opacity="0.55">Per-call: reads about −75%, greps about −50%.</text>
 
   <!-- Bottom strip: install commands -->
   <line x1="80" y1="570" x2="1120" y2="570" stroke="#121212" stroke-opacity="0.15" stroke-width="1" />