ashlr-plugin 1.36.4

package/docs/benchmarks.md

@@ -0,0 +1,211 @@
+# ashlr-plugin Token-Savings Benchmarks
+
+> **Latest run:** v1.36.0 (`docs/benchmarks-v2.json`)
+> **Headline:** `−57%` cross-language mean on real open-source codebases
+> (TS/vercel-ai `−62%`, Python/pandas `−65%`, Rust/tokio `−44%`)
+>
+> _Prior self-repo figure (`−74%`) is preserved in `docs/benchmarks-v2.json`
+> under `aggregate.overall.mean` but is no longer the headline — it reflects
+> the plugin's own repo which includes large generated JSON and media files._
+
+## How the numbers are produced
+
+`scripts/run-benchmark.ts` measures real byte/token reduction by calling the
+handler functions directly — no MCP layer, no Claude Code in the loop. For
+each tool, we sample representative inputs from a target repo, run them
+through the canonical compression pipeline, and report:
+
+- `rawBytes` / `rawTokens` — what the native tool would have shipped
+- `ashlrBytes` / `ashlrTokens` — what the ashlr handler returned
+- `ratio` — `ashlrBytes / rawBytes` (lower is better)
+
+The output is a stable JSON shape (`docs/benchmarks-v2.json`) that downstream
+tools (dashboard, README badges) can read without re-running the bench.
+
+```bash
+# Run against the current repo
+bun run scripts/run-benchmark.ts
+
+# Run against another repo (must be a git checkout)
+bun run scripts/run-benchmark.ts --repo /path/to/other-repo --out /tmp/other.json
+
+# Dry-run: print results, don't write JSON
+bun run scripts/run-benchmark.ts --dry-run
+```
+
+## What the headline number actually means
+
+`overall.mean = arithmetic mean of all sample ratios across read/grep/edit.`
+
+This is **a specific number for a specific repo and a specific tool mix**.
+It is NOT a marketing estimate; it is what the compression layer measured on
+actual files. Three things shape it:
+
+1. **File mix.** A repo full of large source files (well-suited to read
+   compression) will show higher savings than a repo full of media or
+   generated artifacts. The ashlr-plugin's own repo includes `hero.mp4`,
+   `bench/refs/`, `docs/benchmarks-v2.json` itself (large) — these drag
+   `ashlr__read` mean savings down vs a typical user codebase.
+
+2. **Tool mix.** Read and grep typically save 80-95%. Edit savings depend on
+   *where* the edit lives:
+   - Small edits (≤ 80 chars combined old+new) skip the redirect entirely
+     in real use (Track A `ASHLR_EDIT_MIN_CHARS` guard) — but the bench
+     calls handlers directly and so reports the negative-savings the guard
+     prevents in practice. Treat the edit headline as a ceiling for
+     "redirect-eligible edits," not a typical-user number.
+   - Medium edits (20-200 LOC range) save ~50%.
+   - Large edits (> 200 LOC) save 90%+.
+
+3. **Workload shape.** A user who reads many files but edits few will see
+   higher savings than a user who edits constantly with small touches.
+
+## Per-tool savings (measured 2026-04-26)
+
+| Tool                | Mean savings | Notes |
+|---------------------|--------------|-------|
+| `ashlr__read`       | **−82.1%**  | snipCompact head/tail + LLM summarization for >16KB files |
+| `ashlr__grep`       | **−92.8%**  | Genome-RAG when available; ripgrep-summarize fallback |
+| `ashlr__edit`       | **~0%** raw bench | But hook now skips micro-edits below `ASHLR_EDIT_MIN_CHARS=80`, so real-world is ≥0 |
+| `ashlr__multi_edit` | not in bench | Track B baseline fix (v1.22) — was 5-10× over-credited |
+| `ashlr__websearch`  | not in bench | Estimated 60-80% (per fixture inspection) |
+| `ashlr__task_list`  | not in bench | Estimated 70-85% (per fixture inspection) |
+| `ashlr__notebook_edit` | not in bench | Estimated 65-75% on multi-cell notebooks |
+| `ashlr__write`      | not in bench | Identical to `ashlr__edit` for existing files |
+
+**Future work**: extend `scripts/run-benchmark.ts` to include the new tool
+families using `bench/fixtures/{websearch,tasklist,notebook}-*.{json,ipynb}`
++ a curated multi-repo reference set (Node SDK, Python lib, Rust project).
+
+## Reproducing the numbers
+
+The bench is deterministic given a repo + commit SHA. To verify a number:
+
+```bash
+git checkout <sha>          # the commit you want to reproduce
+bun install
+bun run scripts/run-benchmark.ts --dry-run
+```
+
+The bench seeds its file sampler with the commit SHA (when run in a clean
+checkout) so two people on the same SHA get the same sample set.
+
+## Multi-repo reference set
+
+### Why a multi-repo headline?
+
+The ashlr-plugin's own repo contains `hero.mp4`, large generated JSON
+(`docs/benchmarks-v2.json`), the `.ashlrcode/genome/` knowledge base, and
+`site/tsconfig.tsbuildinfo`. These files make the self-repo benchmark
+non-representative — they inflate `ashlr__read` savings beyond what a typical
+user codebase would see.
+
+### The three reference repos
+
+| Key | Language | Upstream | Sampled commit | Files |
+|-----|----------|----------|----------------|-------|
+| `node-sdk` | TypeScript | [vercel/ai](https://github.com/vercel/ai) | `0498012` | 32 TS files from `packages/ai/src/` |
+| `python-lib` | Python | [pandas-dev/pandas](https://github.com/pandas-dev/pandas) | `be0642f` | 30 Py files from `pandas/core/` |
+| `rust-project` | Rust | [tokio-rs/tokio](https://github.com/tokio-rs/tokio) | `6c03e03` | 31 Rs files from `tokio/src/` |
+
+Each ref directory lives in `bench/refs/<key>/` and is itself a git repo.
+A `.refrev` file records the upstream commit SHA sampled from.
+
+**Why these three?** TypeScript + Python + Rust are the top three languages in
+the ashlr-plugin user base (based on install telemetry). Each project is a
+well-maintained OSS library with realistic file size distributions: small
+utilities, medium modules, and large implementation files. They collectively
+represent agentic AI SDK code, data-science library internals, and systems
+async runtime code — meaningfully different workloads.
+
+### Results (measured 2026-04-26)
+
+| Repo | Overall | Read | Grep | Edit |
+|------|---------|------|------|------|
+| `node-sdk` (TS) | **−61.6%** | −75.3% | −66.1% | ~0%* |
+| `python-lib` (Py) | **−64.9%** | −78.8% | −67.9% | ~0%* |
+| `rust-project` (Rs) | **−43.6%** | −70.0% | −17.2% | ~0%* |
+| **Cross-language mean** | **−57%** | **−75%** | **−50%** | ~0%* |
+
+_*Edit savings at ~0% in the bench reflects the synthetic small-edit overhead
+(see edit caveat above). Real-world medium/large edits save 50-96%._
+
+**Note on grep for Rust:** ripgrep patterns `import`, `TODO`, `class`, and
+`interface` have low match rates in Rust source (Rust uses `use`, `//TODO:`,
+struct/enum, and traits instead). This suppresses the grep headline for the
+rust-project repo. With Rust-idiomatic patterns (`fn `, `use `, `impl `, etc.)
+savings would be comparable to TS/Py. The bench intentionally uses
+language-agnostic patterns to expose this; the genome-RAG path (not measured
+here) adapts to file content automatically.
+
+### How the aggregate is computed
+
+`crossLanguageMean = arithmetic mean of the 3 repo overall.mean values`
+
+The per-repo mean is itself the pooled mean across all individual read/grep/edit
+sample ratios (same as the per-repo bench). See `scripts/benchmark-refs.ts` for
+the exact computation.
+
+### Running the multi-repo bench yourself
+
+```bash
+# Run all three ref repos and merge into docs/benchmarks-v2.json
+bun run scripts/benchmark-refs.ts
+
+# Dry run (no file write)
+bun run scripts/benchmark-refs.ts --dry-run
+
+# Write to a different output path
+bun run scripts/benchmark-refs.ts --out /tmp/my-bench.json
+```
+
+### Extending with your own repo
+
+You can add your own codebase to the reference set:
+
+1. Create a directory under `bench/refs/<your-key>/` and populate it with
+   source files (must be a git checkout — `git init && git add . && git commit`).
+2. Add a `.refrev` file with the upstream commit SHA.
+3. Add your config to the `REFS` array in `scripts/benchmark-refs.ts`.
+
+The bench uses `git ls-files` to enumerate tracked files, so you control
+exactly which files are measured by what you commit to the ref repo.
+
+## Trust pass — what `v1.22` fixed in the math
+
+Per the v1.22 audit (`~/.claude/plans/ultrathink-deploy-agents-to-jazzy-hoare.md`),
+four bugs distorted reported savings prior to this release:
+
+1. **Edit micro-edit penalty.** Sub-80-char edits on >5KB files were
+   redirected through the diff round-trip and produced *negative* savings
+   (~−150% at p90 in `docs/benchmarks-v2.json`). Track A added an
+   `ASHLR_EDIT_MIN_CHARS` guard that passes those through to native Edit.
+
+2. **Multi-edit baseline inflation.** `ashlr__multi_edit` baseline was
+   `original.length + updated.length` per file (full file twice) — the
+   pre-v1.18 formula. Track A aligned it with single-edit:
+   `Σ hunk.search.length + hunk.replace.length`. Removed 5-10× over-credit.
+
+3. **Pricing map.** Default model was `sonnet-4.5` ($3/MTok). Track A
+   added `sonnet-4.6` ($2.5) as new default plus `opus-4.7` ($18 in / $90 out).
+   Opus users were under-priced ~2× before.
+
+4. **`tool_noop` mislabeling.** Low-confidence paths emitted `tool_noop`
+   events even when content WAS shipped. Track A renamed to
+   `tool_low_confidence_shipped` so the savings-accounting signal is
+   accurate. `tool_noop` now reserved for actual zero-bytes-shipped no-ops.
+
+## Telemetry that grounds the bench in real usage
+
+v1.22 Track G adds dashboard sections that show real-world data:
+
+- **"Where savings come from"** — per-mechanism breakdown
+  (snipCompact / LLM-anthropic / LLM-onnx / LLM-local / genome / embed-cache /
+  structured-render).
+- **"Adoption funnel"** — blocks emitted vs blocks → ashlr-call rate (7-day
+  rolling). Run `/ashlr-dashboard` to see it.
+- **`/ashlr-status`** — LLM provider availability + embed-cache hit rate +
+  genome fire-rate + 24h block→ashlr-call ratio.
+
+These are the numbers worth tracking weekly. The bench is a calibration
+tool; the telemetry is the live feedback loop.

package/docs/billing.md

@@ -0,0 +1,185 @@
+# ashlr billing
+
+ashlr uses Stripe for subscription billing. This document covers the tiers,
+the integration architecture, and what happens at each lifecycle event.
+
+## Tiers
+
+| Tier | Price | Features |
+|------|-------|----------|
+| Free | $0 | Full local plugin, 40 MCP tools, 34 slash commands, Codex workflow skills, local genome scribe loop |
+| Pro  | $12/mo or $120/yr | Everything in Free + cloud LLM summarizer, cross-machine stats sync, hosted retrieval, live auto-updating badge |
+| Team | $24/user/mo or $240/user/yr | Everything in Pro + shared team genome sync, team dashboard, priority support (min 3 users) |
+
+Free users who attempt to use gated endpoints receive HTTP 403 with
+`{ "error": "This feature requires a paid plan.", "upgrade_url": "/billing/checkout" }`.
+
+## How users get access
+
+The fastest way to upgrade is `/ashlr-upgrade` — a terminal-native flow that
+takes under 90 seconds without leaving Claude Code. See [upgrade.md](upgrade.md)
+for the full walkthrough.
+
+Users can also sign up and sign in through a passwordless magic-link flow:
+
+1. Visit `/signin` on the site and enter an email address.
+2. The backend creates a user record (if new) and sends a one-time link via
+   [SendGrid](https://sendgrid.com). The link is valid for 15 minutes.
+3. Clicking the link calls `POST /auth/verify`, which issues a permanent API
+   token and stores it in the user's browser (`localStorage`). The token is
+   used as a `Bearer` credential for all subsequent API calls.
+4. To upgrade to Pro or Team, the user visits `/pricing` and completes a
+   Stripe Checkout session. The webhook at `POST /billing/webhook` promotes the
+   user's tier in the database.
+
+**Rate limit:** The `/auth/send` endpoint accepts at most 5 requests per email
+address per hour. The 6th request returns HTTP 429.
+
+**Self-serve:** There is no longer a manual CLI provisioning step for new users.
+The `bun run src/cli/issue-token.ts <email>` CLI is retained for internal use
+and emergency provisioning only.
+
+## Stripe integration
+
+### Products and prices
+
+The `stripe-setup` CLI creates two Stripe products ("ashlr Pro" and "ashlr Team")
+with four prices (monthly and annual for each). IDs are stored in the
+`stripe_products` database table so the runtime never hard-codes them.
+
+To bootstrap a new environment:
+
+```sh
+STRIPE_SECRET_KEY=sk_live_... bun run src/cli/stripe-setup.ts
+```
+
+The script is idempotent — re-running it skips any prices already in the DB.
+
+### Checkout flow
+
+1. Authenticated user POSTs to `POST /billing/checkout` with `{ tier, seats? }`.
+2. Server creates a Stripe Checkout Session and returns `{ url }`.
+3. Client redirects user to `url`.
+4. On success, Stripe redirects to `/billing/return?session={CHECKOUT_SESSION_ID}`
+   and fires a `checkout.session.completed` webhook.
+5. Webhook handler creates the subscription record and upgrades `users.tier`.
+
+### Customer portal
+
+`GET /billing/portal` creates a Stripe Customer Portal session for the
+authenticated user. The portal lets them update their payment method, view
+invoices, change plan, or cancel. Returns `{ url }` for a client-side redirect.
+
+Users without a billing record receive 404.
+
+### Subscription status
+
+`GET /billing/status` returns:
+
+```json
+{
+  "tier": "pro",
+  "seats": 1,
+  "renewsAt": "2026-05-17T00:00:00.000Z",
+  "cancelAt": null
+}
+```
+
+Free users with no subscription record receive `{ "tier": "free", ... }`.
+
+## Webhook events
+
+The webhook endpoint is `POST /billing/webhook`. Register it in the Stripe
+dashboard pointing at `https://api.ashlr.ai/billing/webhook`.
+
+Events handled:
+
+| Event | Action |
+|-------|--------|
+| `checkout.session.completed` | Creates subscription record, sets `users.tier` to the purchased tier |
+| `customer.subscription.updated` | Updates `current_period_end`, `seats`, and `status`; reactivates tier if status returns to `active` |
+| `customer.subscription.deleted` | Sets subscription `status` to `canceled`, downgrades `users.tier` to `free` |
+| `invoice.payment_failed` | Sets subscription `status` to `past_due`; tier remains for the 7-day grace period while Stripe retries |
+
+Webhook idempotency is enforced via the `stripe_events` table. Duplicate
+`event.id` deliveries return 200 immediately without re-processing.
+
+All events are verified via `stripe.webhooks.constructEvent` using the
+`STRIPE_WEBHOOK_SECRET` environment variable. Invalid signatures return 400.
+
+## What happens on cancellation
+
+When a user cancels, Stripe fires `customer.subscription.deleted` at the end
+of the paid period. The webhook handler downgrades `users.tier` to `free`.
+The subscription record is retained for auditing with `status = 'canceled'`.
+
+Users on an annual plan who cancel mid-year retain access until the period end
+(`current_period_end`). Refunds are handled through the Stripe dashboard.
+
+## Dispute policy
+
+Disputes should be handled through the Stripe dashboard. Contact
+support@ashlr.ai for billing questions before initiating a chargeback.
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `STRIPE_SECRET_KEY` | Yes (production) | Stripe secret key (`sk_live_...` or `sk_test_...`) |
+| `STRIPE_WEBHOOK_SECRET` | Yes (production) | Signing secret from Stripe webhook dashboard (`whsec_...`) |
+| `BASE_URL` | No | Base URL for success/return redirects (default: `https://api.ashlr.ai`) |
+| `SITE_URL` | No | Site URL for cancel redirect (default: `https://plugin.ashlr.ai`) |
+| `TESTING` | Tests only | Set to `1` to stub Stripe client; no real API calls are made |
+
+## Database tables
+
+Three tables support billing:
+
+- **`subscriptions`** — one row per Stripe subscription; tracks tier, status,
+  seats, `current_period_end`, and `cancel_at`.
+- **`stripe_events`** — event IDs from processed webhook deliveries; prevents
+  double-processing on Stripe retries.
+- **`stripe_products`** — caches Stripe product and price IDs seeded by the
+  `stripe-setup` CLI; keyed by `pro`, `pro-annual`, `team`, `team-annual`.
+
+The `users` table has a `tier` column (`free` | `pro` | `team`) that is the
+single source of truth for access control checks at request time.
+
+## Audit log and policy packs (team tier)
+
+Both features require the **team** tier or higher. Free and Pro users receive
+HTTP 403 if they attempt to call these endpoints.
+
+### Policy packs
+
+Team admins can upload YAML/JSON allow-deny-confirm rule sets via
+`POST /policy/upload`. The server stores each upload as an immutable versioned
+snapshot. Members fetch the current pack via `GET /policy/current` (cached
+5 minutes via ETag). Admins can roll back to any prior version via
+`POST /policy/rollback`. See `docs/policy-packs.md` for rule syntax and
+examples.
+
+Only users with `org_role = "admin"` can upload or roll back. Members can
+read the current pack. Free and Pro users are rejected at the tier gate before
+org-role checks run.
+
+### Audit log
+
+The `POST /audit/event` endpoint accepts tool-call events from the
+`audit-upload` hook. Events are written to `audit_events` in an append-only
+fashion — no updates or deletes are issued outside of explicit admin purges.
+
+Paths and cwds in event arguments are replaced with a 16-char SHA-256
+fingerprint before storage. File contents are never stored. This satisfies
+GDPR path-data minimisation while preserving correlation for compliance audits.
+
+Org admins can query events with filters (`GET /audit/events`) or export the
+full log as NDJSON (`GET /audit/export`). Non-admin members are blocked at the
+org-role gate with 403.
+
+### Database tables (Phase 4)
+
+- **`policy_packs`** — immutable versioned snapshots; unique on `(org_id, name, version)`.
+- **`policy_current`** — one row per org; points to the active pack.
+- **`audit_events`** — append-only event log; indexed by `(org_id, at)` and `(user_id, at)`.
+- **`users.org_id`** / **`users.org_role`** — org membership and role columns added in Phase 4 migration.

package/docs/cloud-genome.md

@@ -0,0 +1,155 @@
+# Cloud Genome Pipeline
+
+Architecture reference for the server-side genome build, encryption, and client pull pipeline introduced in v1.13.
+
+---
+
+## Overview
+
+```
+User CLI (session start)
+    │
+    │  hooks/session-start.ts
+    │  └─ scripts/genome-cloud-pull.ts
+    │       parse cwd git remote
+    │       canonicalize repo URL
+    │       GET /genome/personal/find?repo_url=<canon>
+    │           ├─ found: download sections
+    │           └─ not found: skip silently
+    │       decrypt sections (user genome key)
+    │       write to ~/.ashlr/genomes/<projectHash>/
+    │       write .ashlr-cloud-genome marker
+    │
+    ▼
+ashlr__grep retrieval chain
+    ├─ 1. local .ashlrcode/genome/     (always wins if present)
+    ├─ 2. ~/.ashlr/genomes/<hash>/     (cloud cache, via findParentGenome)
+    └─ 3. ripgrep full-tree fallback
+```
+
+The cloud genome supplements local genomes — it never replaces them. If `.ashlrcode/genome/` exists in the project, it is used exclusively and the cloud cache is ignored for that session.
+
+---
+
+## File locations
+
+| Path | Purpose |
+|---|---|
+| `~/.ashlr/genomes/<projectHash>/` | Per-project cloud genome cache directory |
+| `~/.ashlr/genomes/<projectHash>/.ashlr-cloud-genome` | Marker file; presence indicates a cloud genome is loaded |
+| `~/.ashlr/genome-key` | Per-user master genome decryption key, mode `0o600`. Fetched once from `GET /user/genome-key` and cached locally. |
+| `~/.ashlr/genome-cloud-pull.log` | Pull log: timestamps, section counts, errors |
+
+`<projectHash>` is a SHA-256 of the canonical repo URL (e.g. `github.com/owner/repo`), truncated to 16 hex chars.
+
+---
+
+## Build pipeline
+
+Source: `server/src/services/genome-build.ts`
+
+```
+POST /genome/build  { userId, owner, repo }
+    │
+    ▼
+buildGenomeFromGitHub(userId, owner, repo)
+    │
+    ├─ tier check: free tier → visibility must be "public"
+    │    live check via api.github.com/repos/<owner>/<repo>
+    │    (server-enforced; client cannot bypass)
+    │
+    ├─ git clone --depth 1  (60s timeout)
+    │
+    ├─ bun run scripts/genome-init.ts --minimal  (120s timeout)
+    │    produces: architecture.md, conventions.md, decisions.md
+    │    + top-level file index
+    │
+    ├─ per-section AES-GCM encrypt
+    │    key: users.genome_encryption_key_encrypted (auto-generated on first build)
+    │
+    └─ upsertSection → genomes table
+         sets build_status = "ready", last_built_at = now()
+```
+
+Rate limit: 5 builds per user per hour (`POST /genome/build`).
+
+---
+
+## Tier gating
+
+| Tier | Repo visibility | Enforcement |
+|---|---|---|
+| Free | Public repos only | Server performs live `api.github.com` check on every build request. `repo_visibility` stored in `genomes` table for audit. |
+| Pro | Public + private | `repo` scope step-up consent required. Server verifies token has `repo` scope before cloning. |
+
+The client cannot fake visibility. The live API check is performed server-side regardless of what the client reports.
+
+---
+
+## Encryption
+
+### Per-user genome key
+
+Each user has a `genome_encryption_key_encrypted` column in the `users` table. This is a random 32-byte key, itself encrypted with the server's `ASHLR_MASTER_KEY`. The key is auto-generated on first private-repo build (or first genome build for Pro users).
+
+`GET /user/genome-key` returns the decrypted key over TLS. The client caches it at `~/.ashlr/genome-key` with mode `0o600`. This file is never included in git history or synced.
+
+### Section encryption
+
+Each genome section is encrypted individually with AES-256-GCM:
+- Random 12-byte IV per section
+- Auth tag appended
+- Implementation: `servers/_genome-crypto.ts`
+
+The server stores ciphertext; plaintext never touches disk on the server after the build completes.
+
+---
+
+## Webhook-driven delta rebuild
+
+Source: `server/src/routes/webhooks.ts`
+
+GitHub push events trigger incremental re-indexing of affected genome sections rather than a full rebuild.
+
+```
+GitHub push event → POST /webhooks/github
+    │
+    ├─ verify HMAC-SHA256 signature (timingSafeEqual)
+    │    header: X-Hub-Signature-256
+    │    secret: GITHUB_WEBHOOK_SECRET
+    │
+    ├─ deduplicate by X-GitHub-Delivery header (idempotency)
+    │
+    ├─ extract changed file paths from commits[].added/modified/removed
+    │
+    ├─ map paths → genome sections (by path prefix)
+    │
+    └─ re-run genome-init --section <name> for each affected section
+         upsertSection → update last_built_at
+```
+
+Signature verification is at `server/src/routes/webhooks.ts:28-35`. Deliveries are stored by delivery ID; a duplicate delivery is acknowledged with 200 and skipped.
+
+To register the webhook on your repo: `github.com/<owner>/<repo>/settings/hooks` → Payload URL: `https://api.ashlr.ai/webhooks/github`, content type: `application/json`, events: `push`.
+
+---
+
+## Kill switch
+
+Set `ASHLR_CLOUD_GENOME_DISABLE=1` in your shell environment (or in `~/.claude/settings.json` under `env`) to disable the cloud genome pull entirely. `ashlr__grep` will skip the `~/.ashlr/genomes/` cache and fall through to ripgrep.
+
+This is useful if you are on a slow connection, working offline, or want to force the local-only code path for testing.
+
+---
+
+## When `ashlr__grep` consults the cloud cache
+
+The retrieval order in `servers/_genome-cache.ts:findParentGenome`:
+
+1. Walk up from `cwd` looking for `.ashlrcode/genome/`. If found, use it — done.
+2. Compute `projectHash` from the git remote of `cwd`.
+3. Check `~/.ashlr/genomes/<projectHash>/.ashlr-cloud-genome` exists.
+4. If yes, load sections from that directory and run TF-IDF retrieval.
+5. If no match or `ASHLR_CLOUD_GENOME_DISABLE=1`, fall through to ripgrep.
+
+The local genome always wins. Cloud is a supplement, not a replacement.

package/docs/competitive-wozcode.md

@@ -0,0 +1,92 @@
+# WozCode Competitive Learnings
+
+> Internal strategy doc — last updated 2026-06-01.
+> Source: public site/repo analysis (minified), benchmark pages, pricing docs.
+> Treat WozCode's self-reported numbers with skepticism (see Caveats).
+
+---
+
+## Summary
+
+WozCode is a closed-source, account-gated Claude Code efficiency plugin (~182 GitHub stars). It competes directly with Ashlr on token reduction. Their headline claim is "80% token reduction," but their own benchmark pages show internally inconsistent numbers. Ashlr's measured, per-tool savings data is a stronger trust signal.
+
+Three technical capabilities are worth adopting or beating. One pricing model (pay-for-performance) is defensible for Ashlr and worth studying. Several growth surfaces (llms.txt, leaderboard, benchmark blog) are low-effort wins.
+
+---
+
+## Capability Comparison
+
+| Capability | WozCode | Ashlr |
+|---|---|---|
+| AST-truncated reads (stub bodies, keep signatures) | Yes — default-on for large files | Not yet |
+| Fuzzy edit matching (Levenshtein + whitespace tolerance) | Yes | Not yet |
+| Post-edit syntax validation loop (Tree-sitter/tsc) | Yes | Not yet |
+| Genome / RAG context retrieval | No | Yes |
+| Per-tool measured savings | No (aggregate self-report) | Yes |
+| Open source + auditable | No (minified, account-gated) | Yes |
+| Opt-in telemetry | No (PostHog on-by-default, hardcoded token) | Yes |
+| Tool breadth | Narrow (deliberate) | 40 tools, 33 commands |
+| `llms.txt` | Yes | No |
+| Public savings leaderboard | Yes (gamified) | No |
+| Multi-surface install (VS Code / Cursor / Windows) | Yes | macOS/Linux primary |
+| Plain-English settings UI (`/woz-settings`) | Yes | Partial (`/ashlr-settings`) |
+| Benchmark blog post | Yes | No |
+
+---
+
+## Prioritized Learnings
+
+### P0 — Product (implement to close capability gap)
+
+**1. AST-truncated reads** (highest per-call token win)
+WozCode stubs out function bodies on large file reads, returning only signatures, types, and exports. This is their biggest single-call saving. For Ashlr: extend `ashlr__read` to detect large files (>N LOC) and emit an AST-truncated view by default, with `bypassSummary:true` to get full content. Tree-sitter or `@ast-grep/napi` are viable. Make it default-on — users should not need to opt in.
+
+**2. Fuzzy edit matching**
+WozCode applies Levenshtein distance + whitespace/unicode normalization before failing an edit. Today Ashlr's `ashlr__edit` fails on whitespace drift, forcing a costly retry round-trip. Adding a fuzzy fallback (with a diff preview so the model can confirm) eliminates that class of second-turn errors entirely.
+
+**3. Post-edit syntax validation loop**
+After each edit, WozCode runs a fast syntax check (Tree-sitter for parse errors, `tsc --noEmit` for TypeScript, file-type-appropriate linter) and feeds failures back in the same turn. This prevents bad edits from reaching a second model round-trip. For Ashlr: add an optional `validate: true` flag to `ashlr__edit` / `ashlr__multi_edit` that runs the cheapest applicable checker and returns inline errors.
+
+### P1 — Positioning + Pricing
+
+**Pay-for-performance pricing model**
+WozCode Enterprise: `$50/seat + 10% of measured savings`. This is actually *more* defensible for Ashlr than for WozCode because Ashlr's savings are **measured per-tool** (not self-reported aggregate). A pay-for-performance tier aligns incentives perfectly and turns Ashlr's measurement advantage into a pricing advantage. Study structure: base seat fee covers fixed costs; the savings share creates a shared-upside relationship.
+
+**Savings cap on free tier**
+WozCode offers a free tier capped at $100/mo in savings rather than feature-gating. This is a better acquisition model than feature-gating: users experience the full product, and heavy users naturally convert. Consider adopting for Ashlr's free tier.
+
+**Lean into WozCode's benchmark inconsistency**
+WozCode's TerminalBench numbers differ across their own pages: 80.2%/69% vs 68%/58% vs "17% on their blog." These are internally inconsistent and unverifiable. Ashlr should publish a transparent, reproducible benchmark methodology with per-tool breakdowns — this is already partially done via `benchmarks.md` / `benchmarks-v2.json`. A short benchmark blog post with methodology and raw data is a credibility differentiator.
+
+### P2 — Growth + DX
+
+**`llms.txt`** — Add `site/public/llms.txt` listing Ashlr's tools, commands, and genome format. WozCode has one; it improves AI-driven discovery and is a 30-minute task.
+
+**Public savings leaderboard** — Opt-in leaderboard showing top savers (anonymized or named). WozCode uses this for social proof. Ashlr already collects savings data; surfacing it publicly turns a telemetry feature into a growth loop.
+
+**Benchmark blog post** — A single authoritative post with methodology, per-tool numbers, and comparison. Addresses the credibility gap vs WozCode's (flawed) benchmarks. Publish to the marketing site; link from README and llms.txt.
+
+**Multi-surface install matrix** — Document and test install on VS Code (with MCP), Cursor, Windows (PowerShell). `docs/install-windows.md` and `docs/install.ps1` already exist — surface them more prominently. WozCode's multi-surface presence expands their addressable audience.
+
+**Plain-English settings** — `/ashlr-settings` should describe each setting in one plain sentence with a concrete example. Reduces friction for non-power users.
+
+---
+
+## Where Ashlr Already Wins
+
+Message these proactively in docs, README, and the benchmark blog:
+
+- **Open source + auditable.** WozCode is minified and requires account creation to inspect behavior. Ashlr is fully open — every tool, hook, and genome interaction is readable.
+- **Measured savings, not self-reported.** Ashlr tracks per-tool token and cost savings with a verifiable methodology. WozCode's numbers are inconsistent across their own pages.
+- **Opt-in telemetry.** WozCode ships PostHog with a hardcoded token, on by default. Ashlr's telemetry is opt-in and documented.
+- **Breadth.** 40 tools, 33 commands, genome RAG, `/ashlr-brief`, `/ashlr-efficient`. WozCode's surface is deliberately narrow.
+- **No account required.** Ashlr installs with one curl command and one slash command. WozCode requires account creation before the plugin is functional.
+
+---
+
+## Caveats
+
+1. **Benchmark numbers are unverifiable.** All WozCode efficiency claims are self-reported. Their own pages show inconsistent figures (TerminalBench: 80.2/69 vs 68/58 vs "17%"). Do not treat these as ground truth.
+2. **Internals are inferred.** The WozCode repo is minified and obfuscated. Technical capabilities above (AST truncation, fuzzy matching, syntax validation) are inferred from public documentation, changelogs, and behavior — not audited source.
+3. **Third-party reputation is thin.** 182 GitHub stars, low HN engagement, no independent benchmark reproductions as of 2026-06-01. This is an opening: Ashlr can establish the credibility standard before WozCode does.
+4. **Competitive landscape moves fast.** Re-verify these findings before any public messaging; capabilities may have changed.