ashlr-plugin 1.36.4

package/docs/deploy.md

@@ -0,0 +1,325 @@
+# Deploy Guide
+
+This document covers end-to-end deployment of the ashlr site (Vercel) and API server (Railway), DNS configuration, smoke testing, rollback procedures, and expected costs.
+
+---
+
+## Table of Contents
+
+1. [Vercel — site deployment](#1-vercel--site-deployment)
+2. [Fly.io — API server deployment](#2-flyio--api-server-deployment)
+3. [DNS configuration](#3-dns-configuration)
+4. [Smoke test](#4-smoke-test)
+5. [Rollback procedures](#5-rollback-procedures)
+6. [Cost expectations](#6-cost-expectations)
+
+---
+
+## Signing up — email setup (SendGrid)
+
+ashlr uses [SendGrid](https://sendgrid.com) to send magic-link sign-in emails from
+`noreply@ashlr.ai`. Before users can self-serve sign up, a domain-verified
+sender must be configured:
+
+1. Create a SendGrid account at https://sendgrid.com and add your sending domain
+   (e.g. `ashlr.ai`). Follow their
+   [domain verification guide](https://docs.sendgrid.com/ui/sending-email/sender-verification)
+   to add the required DNS records (SPF, DKIM, DMARC).
+2. Once the domain is verified, create an API key in the SendGrid dashboard
+   (Developers > API Keys). Scope it to "Sending access" only.
+3. Store the key as a Railway variable alongside your other server variables
+   (Project > ashlr-plugin-api > Variables, or via CLI):
+   ```
+   railway variables --service ashlr-plugin-api --set SENDGRID_API_KEY=SG...
+   ```
+4. Set the `FRONTEND_URL` variable to your site origin so magic-link URLs point
+   to the right place (default: `https://plugin.ashlr.ai`):
+   ```
+   railway variables --service ashlr-plugin-api --set FRONTEND_URL=https://plugin.ashlr.ai
+   ```
+
+**Dev / test mode:** If `SENDGRID_API_KEY` is unset, or if `TESTING=1`, no email
+is sent. The magic token is printed to stderr instead — safe for local
+development and CI.
+
+---
+
+## Stripe webhook setup
+
+After deploying the API server, register the billing webhook in the Stripe dashboard:
+
+1. Go to Stripe Dashboard > Developers > Webhooks > Add endpoint.
+2. Set the endpoint URL to `https://api.ashlr.ai/billing/webhook`.
+3. Select the following events to listen for:
+   - `checkout.session.completed`
+   - `customer.subscription.updated`
+   - `customer.subscription.deleted`
+   - `invoice.payment_failed`
+4. After saving, reveal the signing secret (`whsec_...`) and store it as a Railway variable:
+
+```sh
+railway variables --service ashlr-plugin-api --set STRIPE_WEBHOOK_SECRET=whsec_...
+railway variables --service ashlr-plugin-api --set STRIPE_SECRET_KEY=sk_live_...
+```
+
+5. Bootstrap Stripe products and prices (run once per environment):
+
+```sh
+railway run --service ashlr-plugin-api -- bun run src/cli/stripe-setup.ts
+```
+
+The setup script is idempotent — re-running it is safe.
+
+---
+
+## 1. Vercel — site deployment
+
+The `site/` Next.js app is deployed to Vercel via `.github/workflows/deploy-site.yml`. Pushes to `main` that touch `site/**` trigger a production deploy. Pull requests get a preview URL posted as a comment.
+
+### Step 1 — Create the Vercel project
+
+1. Go to [vercel.com](https://vercel.com) and sign in.
+2. Click **Add New Project**, select your GitHub repo (`ashlrai/ashlr-plugin`).
+3. Set the **Root Directory** to `site`.
+4. Set the **Framework Preset** to `Next.js`.
+5. Leave build/output settings at defaults — the workflow runs `bun run build` itself.
+6. Click **Deploy** once to initialize the project (this first deploy can be ignored).
+
+### Step 2 — Grab the three required tokens
+
+All three values are on the project settings page in Vercel.
+
+| Secret | Where to find it |
+|--------|-----------------|
+| `VERCEL_TOKEN` | Account Settings > Tokens > Create (scope: Full Account) |
+| `VERCEL_ORG_ID` | Project Settings > General > Team ID (shown at page top) |
+| `VERCEL_PROJECT_ID` | Project Settings > General > Project ID |
+
+### Step 3 — Add secrets to GitHub
+
+In the GitHub repo, go to **Settings > Secrets and variables > Actions**, then add:
+
+- `VERCEL_TOKEN`
+- `VERCEL_ORG_ID`
+- `VERCEL_PROJECT_ID`
+
+### Step 4 — Verify
+
+Push any change under `site/` to `main`. The **Deploy site to Vercel** workflow should appear under Actions, run `bun run build`, then deploy. The Vercel dashboard shows the new deployment within ~2 minutes.
+
+For pull requests, the workflow posts a preview URL comment. No additional configuration needed.
+
+---
+
+## 2. Railway — API server deployment
+
+The `server/` Hono/Bun app is deployed to Railway via `.github/workflows/deploy-server.yml`. Pushes to `main` that touch `server/**` run tests first, then deploy. Build is driven by `server/Dockerfile` (referenced from `server/railway.json`).
+
+### Step 1 — Install Railway CLI and log in
+
+```bash
+brew install railway          # macOS
+# or: curl -fsSL https://railway.com/install.sh | sh
+railway login
+```
+
+### Step 2 — Create the project (first time only)
+
+```bash
+cd server
+railway init --name ashlr-plugin-api
+```
+
+This creates a Railway project in your default workspace. After init:
+
+```bash
+# Add a service inside the project (named to match the workflow)
+railway add --service ashlr-plugin-api
+
+# Link this directory to the new project so `railway up` knows where to deploy
+railway link
+```
+
+Railway auto-detects the `Dockerfile` and `railway.json` in `server/`. The `healthcheckPath` is `/readyz` (matches `server/src/routes/health.ts`).
+
+### Step 3 — Set environment variables
+
+The server needs ~20 variables — see [`docs/operations.md`](./operations.md) for the full list. Set them via either:
+
+```bash
+# Per-key
+railway variables --service ashlr-plugin-api --set ASHLR_MASTER_KEY=...
+
+# Or paste a .env in the Railway dashboard:
+#   Project > ashlr-plugin-api > Variables > Raw editor
+```
+
+The minimum to boot a healthy instance: `ASHLR_MASTER_KEY`, `NODE_ENV=production`, `FRONTEND_URL`, plus whichever feature secrets you need (Stripe / SendGrid / GitHub OAuth / xAI).
+
+`PORT` is provided by Railway automatically — don't set it.
+
+### Step 4 — Get the deploy token
+
+```bash
+# Project-scoped token (recommended): only deploys to this project, can't access others.
+# Create one in the Railway dashboard:
+#   Account > Tokens > New Token > scope: Project: ashlr-plugin-api
+```
+
+Copy the printed value. This is your `RAILWAY_TOKEN`.
+
+### Step 5 — Add the secret to GitHub
+
+In GitHub repo > **Settings > Secrets and variables > Actions**, add:
+
+- `RAILWAY_TOKEN`
+
+### Step 6 — Push and verify
+
+Push any change under `server/` to `main`. The **Deploy server to Railway** workflow runs `bun test` first — if any test fails, the deploy is aborted. On success, `railway up --service ashlr-plugin-api --detach` builds and deploys remotely.
+
+Verify with:
+
+```bash
+curl https://api.ashlr.ai/
+# Expected: {"ok":true,"service":"ashlr-server","phase":1}
+```
+
+---
+
+## 3. DNS configuration
+
+### plugin.ashlr.ai — Vercel
+
+Add a CNAME record in your DNS provider:
+
+```
+Type:  CNAME
+Name:  plugin
+Value: cname.vercel-dns.com
+TTL:   3600
+```
+
+Then in Vercel > Project Settings > Domains, add `plugin.ashlr.ai`. Vercel provisions a TLS certificate automatically via Let's Encrypt within ~2 minutes.
+
+### api.ashlr.ai — Railway
+
+Railway provisions a default `<service>-production-<id>.up.railway.app` domain. Get it with:
+
+```bash
+railway domain --service ashlr-plugin-api
+```
+
+In the Railway dashboard → ashlr-plugin-api → Settings → Networking → **Custom Domain**, add `api.ashlr.ai`. Railway shows you the exact CNAME target to use; it usually looks like `<id>.up.railway.app`.
+
+Add a CNAME record in your DNS provider:
+
+```
+Type:  CNAME
+Name:  api
+Value: <target shown in Railway dashboard>
+TTL:   3600
+```
+
+Railway issues the TLS certificate automatically via Let's Encrypt within ~2 minutes.
+
+---
+
+## 4. Smoke test
+
+After every deploy, run the smoke test script to verify both services are healthy:
+
+```bash
+# Install endpoint only (no token required)
+./scripts/deploy-smoke.sh
+
+# Full test including badge and stats endpoints
+ASHLR_TOKEN=<provisioned_token> ./scripts/deploy-smoke.sh
+
+# Override URLs for staging
+SITE_URL=https://preview.plugin.ashlr.ai \
+API_URL=https://staging-api.ashlr.ai \
+ASHLR_TOKEN=<token> \
+./scripts/deploy-smoke.sh
+```
+
+The script exits with code `0` on full pass, `1` if any check fails. It is safe to run repeatedly. Checks performed:
+
+- `GET /` on site — 200
+- `GET /robots.txt` — 200
+- `GET /sitemap.xml` — 200
+- `GET /` on API — `{ok: true}` JSON
+- `POST /stats/sync` — 200 (authenticated)
+- `GET /stats/aggregate` — user_id present (authenticated)
+- `GET /u/:userId/badge.svg` — SVG content with metric text
+
+To provision a token for testing:
+
+```bash
+cd server && bun run issue-token
+```
+
+---
+
+## 5. Rollback procedures
+
+### Vercel rollback
+
+The Vercel dashboard keeps every deployment permanently. To roll back:
+
+1. Go to the project > **Deployments**.
+2. Find the last known-good deployment.
+3. Click the three-dot menu > **Promote to Production**.
+
+Takes effect within 30 seconds globally.
+
+Alternatively, revert the offending commit and push — the workflow redeploys automatically.
+
+### Railway rollback
+
+Railway keeps every previous deployment. Roll back instantly from the dashboard:
+
+1. Go to the project > **ashlr-plugin-api** > **Deployments**.
+2. Find the last known-good deployment.
+3. Click the three-dot menu > **Redeploy**.
+
+Or via CLI:
+
+```bash
+# List recent deployments
+railway status --service ashlr-plugin-api
+
+# Redeploy the most recent successful deployment (rollback if HEAD is broken)
+railway redeploy --service ashlr-plugin-api
+```
+
+Or revert the commit and push — the workflow redeploys the server automatically.
+
+To monitor a rollback:
+
+```bash
+railway logs --service ashlr-plugin-api
+```
+
+---
+
+## 6. Cost expectations
+
+Cost figures below are derived from the Phase 1 architecture (Railway for compute, Neon serverless Postgres, Cloudflare R2/S3 for storage, Upstash Redis for rate limits).
+
+| Component | 100 MAU | 1,000 MAU | 10,000 MAU |
+|-----------|---------|-----------|------------|
+| Vercel (site hosting) | Free tier | Free tier | ~$20/mo (Pro) |
+| Railway compute (ashlr-plugin-api, sleeps when idle) | ~$5/mo | ~$10/mo | ~$30/mo |
+| Postgres (Neon serverless) | ~$0.50/mo | ~$5/mo | ~$30/mo |
+| S3 / R2 (stats backups, genome bodies) | ~$0.10/mo | ~$1/mo | ~$8/mo |
+| Redis (Upstash, rate limits + cache) | $0 (free tier) | $20/mo (fixed) | $50/mo |
+| Cloud LLM inference (Haiku, summarization) | ~$0.20/mo | ~$2/mo | ~$20/mo |
+| Bandwidth + misc | ~$0.20/mo | ~$2/mo | ~$15/mo |
+| **Total** | **~$4/mo** | **~$38/mo** | **~$173/mo** |
+
+**At 1K MAU**, total infra is approximately **$38/month**. The MIT free tier carries no marginal cost per user for the open-source plugin itself; backend costs arise only from the Pro stats-sync and hosted badge features.
+
+**At 10K MAU**, the architecture remains defensible. Beyond that, add Postgres read replicas and consider sharding by organization. See `docs/pro-backend-architecture.md` for the full cost model and scaling decision points.
+
+**Fly.io specifics**: the `ashlr-api` app is configured with `auto_stop_machines = "stop"` and `min_machines_running = 0`. It scales to zero when idle, meaning zero compute cost at 0 requests. The first request cold-starts in ~500ms (Bun is fast). For production traffic, set `min_machines_running = 1` to eliminate cold starts at the cost of ~$3/mo for the always-on machine.

package/docs/email-templates.md

@@ -0,0 +1,113 @@
+# ashlr email templates
+
+React-email templates for all transactional emails sent by the ashlr backend.
+
+## Preview server
+
+Start a local preview server on port 3333:
+
+```
+bun run server/src/emails/preview.ts
+```
+
+Then open http://localhost:3333 to browse all templates. Each template is rendered with realistic sample data. The preview server does not require `SENDGRID_API_KEY`.
+
+Individual template URLs:
+
+| Template | URL |
+|---|---|
+| magic-link | http://localhost:3333/preview/magic-link |
+| welcome | http://localhost:3333/preview/welcome |
+| payment-success | http://localhost:3333/preview/payment-success |
+| payment-failed | http://localhost:3333/preview/payment-failed |
+| subscription-canceled | http://localhost:3333/preview/subscription-canceled |
+| daily-cap-reached | http://localhost:3333/preview/daily-cap-reached |
+
+Or via the npm script alias:
+
+```
+cd server && bun run email:preview
+```
+
+## Templates
+
+### magic-link
+
+**Subject:** Your ashlr sign-in link  
+**Trigger:** `POST /auth/send`  
+**Props:** `{ email: string, link: string }`
+
+Sign-in magic link. Greets the user by the local part of their email address, provides a prominent CTA button, includes the raw link in plain text below the button for accessibility, and notes the 15-minute expiration. Security notice at the bottom.
+
+### welcome
+
+**Subject:** Welcome to ashlr · your first steps  
+**Trigger:** `checkout.session.completed` (sent alongside payment-success)  
+**Props:** `{ email: string }`
+
+Onboarding email. Three numbered steps: run `/ashlr-tour`, set up `ASHLR_PRO_TOKEN`, open `/ashlr-dashboard`. Links to docs, GitHub, and pricing.
+
+### payment-success
+
+**Subject:** ashlr Pro — you're in  
+**Trigger:** `checkout.session.completed`  
+**Props:** `{ email: string, amount: number, tier: string, renewsOn: string }`
+
+Subscription confirmation. Receipt table with plan, amount charged (formatted as `$X.XX`), and renewal date. Links to dashboard and billing portal.
+
+### payment-failed
+
+**Subject:** ashlr Pro — payment failed, we'll retry  
+**Trigger:** `invoice.payment_failed`  
+**Props:** `{ email: string, gracePeriodEnd: string }`
+
+Payment failure notice. Explains the 7-day grace period, shows the exact date access expires if unresolved, provides a CTA to update the payment method in the Stripe billing portal.
+
+### subscription-canceled
+
+**Subject:** ashlr Pro — your subscription has ended  
+**Trigger:** `customer.subscription.deleted`  
+**Props:** `{ email: string }`
+
+Cancellation confirmation. Clearly states that local-first features (genome init, token savings, slash commands, full CLI) remain free forever. Lists the Pro-only features that have been disabled: genome sync across machines and cloud LLM summarization. CTA to resubscribe.
+
+### daily-cap-reached
+
+**Subject:** ashlr Pro — daily LLM cap reached  
+**Trigger:** first `POST /llm/summarize` that returns 429 for a given user on a given UTC day  
+**Props:** `{ email: string }`
+
+Throttled notification (once per user per day via `daily_cap_notifications` table). Shows the 1,000-call / $1.00 cap, the midnight UTC reset time, and a link to Enterprise pricing for higher limits. Local features are explicitly noted as unaffected.
+
+## Design system
+
+| Token | Value |
+|---|---|
+| Paper (background) | `#F3EADB` |
+| Ink (text) | `#121212` |
+| Accent (CTA, links) | `#8B2E1A` |
+| Muted (secondary text) | `#6B5B4E` |
+| Border | `#D9CEBD` |
+
+Fonts: Fraunces italic (headings, loaded via Google Fonts woff2), IBM Plex Sans (body). Web-safe fallbacks: Georgia, Helvetica, Arial.
+
+Container: 600px centered, white background, 8px border-radius, parchment outer background. Mobile-responsive via `maxWidth: 600px`.
+
+## Sending integration
+
+All sends go through `server/src/lib/email.ts`:
+
+```ts
+await sendEmail("magic-link", { to: email, data: { email, link } });
+```
+
+The function renders the React template to HTML + plain text, then calls SendGrid. If `SENDGRID_API_KEY` is unset or `TESTING=1`, it logs the rendered output to stderr instead.
+
+## Email client compatibility notes
+
+- **Gmail**: strips `<style>` blocks in `<head>`. All styles are inline via react-email's built-in inline style props, so Gmail renders correctly.
+- **Outlook (Windows)**: does not support border-radius, box-shadow, or `display: inline-block` on buttons reliably. The CTA button degrades to a plain rectangular block — still functional. The plain-text link below the button ensures access regardless.
+- **Outlook (Windows)**: does not render SVG in `<img>` tags. The logo SVG is embedded inline (not via `<img src="...svg">`), which renders correctly in Gmail and Apple Mail. In Outlook on Windows the inline SVG is ignored; the `aria-label="ashlr"` on the SVG provides accessible fallback text.
+- **Apple Mail**: full support for inline SVG, web fonts, and CSS. All templates render as designed.
+- **Dark mode**: templates use a white card on parchment background. Email clients that invert colors in dark mode (Apple Mail, some Android clients) may adjust the outer background; the inner card remains readable due to explicit background-color declarations on all sections.
+- **Plain-text fallback**: every template exports a `plainText()` function. The SendGrid send includes both `html` and `text` fields, so clients that strip HTML receive the plain-text version.

package/docs/embed-tuning.md

@@ -0,0 +1,103 @@
+# Embedding Cache Threshold Tuning
+
+The ashlr grep cache uses cosine similarity to decide whether a cached result
+is close enough to the current query to be reused. The default threshold is
+`0.68`. This document explains how to tune it for your actual usage patterns.
+
+## Background
+
+Every grep routed through `ashlr__grep` logs a calibration record to
+`~/.ashlr/embed-calibration.jsonl`:
+
+```jsonl
+{"ts":"2026-04-25T10:00:00Z","queryHashHex":"a1b2c3d4","topSimilarity":0.82,"hit":true,"contentLength":1400,"threshold":0.68}
+{"ts":"2026-04-25T10:00:01Z","queryHashHex":"e5f6a7b8","topSimilarity":0.61,"hit":false,"contentLength":0,"threshold":0.68}
+```
+
+- `hit: true` — the cached result was served (cosine similarity >= threshold).
+- `hit: false` — the cache was skipped; a fresh ripgrep ran instead.
+- `topSimilarity` — the best cosine score found in the embedding index.
+
+After a few hundred grep operations you have enough data to tune the threshold.
+
+## Running the tuner
+
+```sh
+# Report only (no changes written):
+bun run scripts/embed-tune.ts
+
+# Custom input file:
+bun run scripts/embed-tune.ts --input ~/.ashlr/embed-calibration.jsonl
+
+# Weight precision 2× over recall (penalise false positives harder):
+bun run scripts/embed-tune.ts --weight precision=2
+
+# Write recommendation to ~/.ashlr/config.json:
+bun run scripts/embed-tune.ts --apply
+```
+
+Sample output:
+
+```
+ashlr embed-tune report
+──────────────────────────────────────────────────
+  entries analysed : 312
+  beta weight      : 1 (F1 score)
+
+  current threshold  0.68  →  precision 0.74  recall 0.83  F1 0.78
+  recommended        0.71  →  precision 0.81  recall 0.79  F1 0.80
+
+  Set via: ASHLR_EMBED_THRESHOLD=0.71
+  Or run with --apply to persist to ~/.ashlr/config.json
+```
+
+## How it works
+
+The tuner sweeps thresholds from `0.50` to `0.95` in `0.01` steps. At each
+step it computes:
+
+| Metric    | Definition |
+|-----------|------------|
+| precision | % of cache hits that were genuine (hit=true in calibration data) |
+| recall    | % of all genuine hits that would still be served from cache |
+| F1        | harmonic mean of precision and recall |
+
+The threshold that maximises F1 (or F-beta with `--weight`) is recommended.
+
+### Weighted F-beta
+
+Pass `--weight precision=2` to use F2, which weights recall twice as much as
+precision — useful if you want maximum cache utilisation and can tolerate some
+irrelevant results. Pass `--weight precision=0.5` (i.e. F0.5) to prioritise
+precision — useful if false positives cause visible quality regressions.
+
+## Applying the result
+
+With `--apply`, the tuner writes `embedThreshold` to `~/.ashlr/config.json`:
+
+```json
+{
+  "embedThreshold": 0.71
+}
+```
+
+Then prints: **"Restart Claude Code to apply."**
+
+The MCP server reads this value on startup. The `ASHLR_EMBED_THRESHOLD`
+environment variable takes precedence over `config.json` when both are set.
+
+## Minimum corpus size
+
+The embedding cache is skipped entirely when the BM25 corpus has fewer than
+50 documents (`BM25_CORPUS_MIN`). Below this size, IDF weights are noisy and
+cosine similarity scores are unreliable regardless of threshold. Let the corpus
+grow before tuning.
+
+## When to re-tune
+
+- After onboarding a new large project (corpus distribution shifts).
+- If you change the embedding model (`ASHLR_EMBED_MODEL`).
+- If you notice grep results that look stale or irrelevant.
+
+A rule of thumb: re-tune after every ~500 grep operations, or whenever
+`embed-calibration.jsonl` grows by more than 200 lines since the last run.

package/docs/genome.md

@@ -0,0 +1,120 @@
+# Genome Auto-Refresh
+
+The genome (`.ashlrcode/genome/`) is the RAG index that powers `ashlr__grep`. Without
+updates it drifts from the codebase as you edit files — causing grep to silently fall
+back to ripgrep, which is slower and larger.
+
+The auto-refresh pipeline (v1.23 Track HH) keeps the genome current without
+requiring manual intervention.
+
+---
+
+## How the refresh cycle works
+
+```
+User edits file
+      │
+      ▼
+PostToolUse hook: posttooluse-genome-refresh.ts
+  ├─ Extract file path from Edit/Write/MultiEdit/NotebookEdit payload
+  ├─ Append absolute path to ~/.ashlr/pending-genome-refresh.txt (deduped)
+  └─ Exit 0 immediately (never blocks)
+
+      │  (multiple edits accumulate, file is appended to)
+      │
+      ▼ (session ends)
+
+SessionEnd hook: session-end-consolidate.ts
+  ├─ 1. genome-auto-consolidate.ts  — merges proposals.jsonl
+  ├─ 2. genome-cloud-push.ts        — pushes to team cloud (if configured)
+  ├─ 3. genome-refresh-worker.ts    — incremental refresh ← NEW
+  └─ 4. telemetry-flush.ts          — opt-in telemetry
+```
+
+### Debounce
+
+The worker checks the mtime of `pending-genome-refresh.txt`. If it was written within
+the last 2 seconds, processing is deferred (another edit may be in flight). This
+prevents partial refreshes during rapid multi-file sessions. At session end the file is
+always old enough to pass the debounce check.
+
+### Incremental vs. full
+
+**Incremental (default):** For each pending file, `_genome-live.refreshGenomeAfterEdit`
+is called. It:
+- Finds genome sections that reference the file (by filename or path)
+- Verbatim sections: patches literal content in-place
+- Summarized sections: invalidates (deletes) them so the propose queue regenerates
+
+No LLM calls. Cost is proportional to the number of sections referencing the file.
+
+**Full rebuild (`--full`):** Re-runs `genome-init.ts --force --minimal` for each
+affected genome root. Rebuilds from scratch. No LLM summarization unless Ollama is
+running. Use explicitly for schema upgrades or large structural refactors.
+
+---
+
+## Stale detection
+
+When `ashlr__grep` finds a genome but gets zero matching sections, it:
+1. Increments an in-session fallback counter
+2. Emits a `genome_stale_detected` telemetry event (pattern + fallback count)
+3. After **3 fallbacks in the same session**, surfaces a one-time nudge:
+
+```
+[ashlr] genome may be stale (3 grep queries fell through to ripgrep).
+Run `bun run scripts/genome-refresh-worker.ts` to refresh, or
+`bun run scripts/genome-refresh-worker.ts --full` for a complete rebuild.
+```
+
+This fires once per session so it doesn't spam repeated queries.
+
+---
+
+## File locations
+
+| Path | Purpose |
+|---|---|
+| `~/.ashlr/pending-genome-refresh.txt` | Pending edit paths (one per line, deduped) |
+| `hooks/posttooluse-genome-refresh.ts` | PostToolUse hook — records paths |
+| `scripts/genome-refresh-worker.ts` | Worker — incremental refresh + `--full` mode |
+
+---
+
+## Manual refresh
+
+```bash
+# Incremental: refresh only files edited since last refresh
+bun run scripts/genome-refresh-worker.ts
+
+# Dry run: see what would be refreshed
+bun run scripts/genome-refresh-worker.ts --dry-run
+
+# Full rebuild (no LLM unless Ollama is running)
+bun run scripts/genome-refresh-worker.ts --full
+
+# Full rebuild, dry run
+bun run scripts/genome-refresh-worker.ts --full --dry-run
+```
+
+---
+
+## Kill switch
+
+Set `ASHLR_GENOME_AUTO=0` to disable all genome automation (refresh, proposals,
+consolidation). The pending file will still accumulate but nothing processes it.
+
+---
+
+## Gotchas
+
+- **Pending file is cumulative.** If you kill Claude mid-session, the pending file
+  persists across the next session start and is processed at the next session end.
+- **Sections not referencing the file by name are not invalidated.** If your genome
+  section uses a generic title (e.g. "Overview") with no mention of the filename in
+  content/tags/summary, the refresh will miss it. Use descriptive section titles.
+- **`--full` on large repos is slow.** It re-scans the entire project. Run it manually
+  only when structural reorganization makes incremental refresh insufficient.
+- **No LLM in the auto path.** The incremental worker never calls an LLM. The only
+  LLM-touching path is `genome-init --summarize` (Ollama, opt-in), which is only
+  reachable via `--full`.