ashlr-plugin 1.36.4

package/commands/ashlr-spawn.md

@@ -0,0 +1,61 @@
+---
+name: ashlr-spawn
+description: Spawn a named delegation pattern as one or more sub-agents. Patterns defined in _spawn-patterns.json.
+argument-hint: "`<pattern>` [args...]"
+---
+
+Spawn a named delegation pattern using `_spawn-patterns.json`.
+
+## Patterns available
+
+- `triage-issues` — classify open issues by severity / label / age (haiku, batch)
+- `refactor-files` — apply a described refactor across a file list (sonnet, parallel-per-file)
+- `codebase-explain` — explain a codebase area with key files + flow (haiku, tiered)
+- `pr-review-sweep` — review all changed files in a PR (sonnet, parallel-per-file-changed)
+- `parallel-test-fix` — fix failing tests across multiple files (sonnet, parallel-per-file)
+
+## Argument convention
+
+```
+/ashlr-spawn <pattern> [args...]
+```
+
+- First positional token after `/ashlr-spawn` is the **pattern name**.
+- Everything after the pattern name is the **args** string, passed verbatim to the prompt template as `{{args}}`.
+- For file-fanout patterns (`refactor-files`, `parallel-test-fix`), additional tokens that look like file paths (contain `/` or `.`) are collected into `{{files}}`; the remaining tokens form `{{args}}`.
+
+Examples:
+```
+/ashlr-spawn triage-issues
+/ashlr-spawn codebase-explain the genome pipeline
+/ashlr-spawn refactor-files extract pure functions src/utils.ts src/helpers.ts
+/ashlr-spawn pr-review-sweep 123
+/ashlr-spawn parallel-test-fix __tests__/savings-math.test.ts __tests__/stats-sqlite.test.ts
+```
+
+## Steps
+
+1. Parse `$ARGUMENTS`:
+   - Extract the pattern name (first token).
+   - Collect remaining tokens: file-path-like tokens → `{{files}}`; everything else → `{{args}}`.
+
+2. Read `commands/_spawn-patterns.json` (path: `${CLAUDE_PLUGIN_ROOT}/commands/_spawn-patterns.json`). If the file is missing, error: "\_spawn-patterns.json not found — run from the plugin root."
+
+3. Look up the pattern. If not found, print: "Unknown pattern `<name>`. Available: triage-issues, refactor-files, codebase-explain, pr-review-sweep, parallel-test-fix" and stop.
+
+4. Render the `prompt_template` by substituting `{{args}}` and `{{files}}` with the parsed values (empty string if not provided).
+
+5. Apply `fanout_strategy`:
+   - `batch` — spawn **one** Agent with `subagent_type` from the pattern, passing the rendered prompt.
+   - `parallel-per-file` — spawn **one Agent per file** in `{{files}}`, each with the same rendered prompt focused on that single file. Collect results.
+   - `parallel-per-file-changed` — use `git diff --name-only origin/main...HEAD` to get the changed file list, then spawn one Agent per file.
+   - `tiered` — spawn Phase 1 `ashlr:ashlr:explore` agent, then pass its output to Phase 2 `ashlr:ashlr:code` agent for deeper analysis.
+
+6. Wait for all agents to complete.
+
+7. Print a merged report:
+   - Header: `## /ashlr-spawn <pattern> — <N> agent(s) completed`
+   - One section per agent output (for multi-agent fanouts, titled by file name).
+   - Footer: total agents spawned, pattern used, fanout strategy.
+
+If `$ARGUMENTS` is empty, print the patterns list and stop.

package/commands/ashlr-start.md

@@ -0,0 +1,60 @@
+---
+name: ashlr-start
+description: >
+  First-run onboarding wizard for the ashlr-plugin. Guides users through
+  doctor check, permissions, a live read demo, genome initialization, and
+  a quick pro teaser — all in under 60 seconds. Run automatically on the
+  first session; re-run manually any time with /ashlr-start.
+  Use /ashlr-start --reset to re-arm the auto-trigger for the next session.
+---
+
+You are running the ashlr first-run onboarding wizard.
+
+## --reset flag
+
+If the user invoked `/ashlr-start --reset`, run:
+
+```sh
+bun run "${CLAUDE_PLUGIN_ROOT}/scripts/onboarding-wizard.ts" --reset
+```
+
+Show the output and stop. Do not run the full wizard.
+
+## Normal wizard flow
+
+1. Run the wizard script:
+
+```sh
+bun run "${CLAUDE_PLUGIN_ROOT}/scripts/onboarding-wizard.ts" --no-interactive
+```
+
+2. Render its output verbatim in a plain code block.
+
+3. After the block, work through each `[ASHLR_PROMPT: ...]` line that
+   appeared in the output. For each one:
+   - Ask the user the exact question shown in the marker.
+   - Wait for their answer (y/n).
+   - If they answer **yes** (or press Enter, treating blank as yes):
+     - For the permissions prompt: run
+       `bun run "${CLAUDE_PLUGIN_ROOT}/scripts/install-permissions.ts"`
+       and show the output.
+     - For the genome prompt: invoke the `/ashlr-genome-init` skill.
+   - If they answer **no**, acknowledge and move on.
+
+4. If any `[ASHLR_WARN] ...` lines appeared, surface the fix instructions
+   clearly but do not block the wizard.
+
+5. After all prompts are resolved, say:
+   "Wizard complete. Run /ashlr-savings any time to see your running
+   totals, or /ashlr-tour for a deeper walkthrough."
+
+## Rules
+
+- Do not run any destructive operation without the user's explicit
+  confirmation at a `[ASHLR_PROMPT]` step.
+- Do not add narration between wizard sections — the script output is
+  the narrative.
+- If the script exits non-zero, show stderr and tell the user to run
+  `/ashlr-doctor` for a full diagnosis.
+- Do not call any tool not listed above during the wizard.
+- Keep responses concise — the wizard output is the substance.

package/commands/ashlr-status.md

@@ -0,0 +1,64 @@
+---
+name: ashlr-status
+description: Report the ashlr-plugin activation status and MCP server health.
+---
+
+Report the following as a compact status block:
+
+1. **Plugin version** — from `.claude-plugin/plugin.json`
+2. **MCP server reachable** — call `ashlr__savings` and see if it returns; if yes, mark green
+3. **Genome detected** — check for `.ashlrcode/genome/` in `process.cwd()`; report yes/no
+4. **Core library version** — read `~/Desktop/ashlr-core-efficiency/package.json` if accessible
+5. **Session savings** — from `ashlr__savings`
+
+Format:
+
+```
+ashlr-plugin v0.1.0
+  server:  ✓ reachable
+  genome:  ✓ (.ashlrcode/genome found) | ✗ (no genome — run `/genome init`)
+  core:    @ashlr/core-efficiency@0.1.0
+  session: 12 calls, ~8,450 tokens saved
+```
+
+If `$ARGUMENTS` contains `--context`, also run:
+
+```sh
+bun run "${CLAUDE_PLUGIN_ROOT}/scripts/context-status.ts"
+```
+
+If `ASHLR_CONTEXT_DB_DISABLE=1` is set, print `ashlr context-db: disabled (ASHLR_CONTEXT_DB_DISABLE=1)` instead. Append the output under a `## Embedding cache` section after the main status block.
+
+If `$ARGUMENTS` contains `--telemetry` (or is not set — always include this section), append a **Telemetry snapshot** section:
+
+```sh
+bun run "${CLAUDE_PLUGIN_ROOT}/scripts/telemetry-status.ts"
+```
+
+This reports:
+- **LLM provider** — which provider `selectProvider()` would pick right now (anthropic / onnx / local / snipCompact-only). Determined by: `ANTHROPIC_API_KEY` set? → anthropic. ONNX runtime available? → onnx. Else → local or snipCompact.
+- **Embedding cache** — total embeddings in `~/.ashlr/context.db`, hit rate over last 100 calls from `~/.ashlr/embed-calibration.jsonl`.
+- **Genome** — sections present (count files in `.ashlrcode/genome/`), fire-rate (fraction of last 50 `ashlr__grep` calls where `genome_route_taken` was emitted, from `~/.ashlr/session-log.jsonl`).
+- **Block→ashlr ratio (24h)** — blocks emitted vs `tool_called_after_block` events in last 24h from hook-timings.jsonl + session-log.jsonl. Shows conversion rate as %.
+- **Opt-in telemetry** — current mode (off / opt-in) + buffer line count + how to disable.
+
+Format:
+
+```
+## Telemetry snapshot
+  llm-provider:   anthropic (ANTHROPIC_API_KEY set)
+  embed-cache:    847 entries · last-100 hit rate 34%
+  genome:         12 sections · last-50 grep fire-rate 68%
+  block→ashlr:    42 blocks / 31 converted = 74% (24h)
+  opt-in telemetry: OFF (default) · to enable: ASHLR_TELEMETRY=on
+```
+
+When telemetry is ON, show instead:
+
+```
+  opt-in telemetry: ON · buffer: 42 events · to disable: ASHLR_TELEMETRY=off
+```
+
+If any data is unavailable (file absent, DB not initialized), show `—` for that field rather than erroring.
+
+No preamble, no trailing summary.

package/commands/ashlr-team-invite.md

@@ -0,0 +1,47 @@
+---
+name: ashlr-team-invite
+description: Invite someone to your ashlr team by email. Sends a magic-link invite (admin role required).
+---
+
+Invite a new member to the caller's team.
+
+**Usage:** The user invokes this skill with an email, optionally followed by `admin` or `member` (default: `member`):
+
+```
+/ashlr-team-invite alice@example.com
+/ashlr-team-invite bob@example.com admin
+```
+
+Steps:
+
+1. If the first non-flag argument is missing or doesn't look like an email (no `@`), reply:
+
+   > "Usage: `/ashlr-team-invite <email> [admin|member]`"
+
+   and stop.
+
+2. Resolve the API base URL (default `https://api.ashlr.ai`, override with `ASHLR_API_URL`), and the API token:
+
+   ```bash
+   TOKEN="${ASHLR_PRO_TOKEN:-$(cat ~/.ashlr/pro-token 2>/dev/null)}"
+   [ -z "$TOKEN" ] && { echo "Not signed in. Run /ashlr-upgrade first."; exit 1; }
+   ```
+
+3. POST the invite:
+
+   ```bash
+   curl -sS -X POST "${ASHLR_API_URL:-https://api.ashlr.ai}/team/invite" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"email":"<EMAIL>","role":"<ROLE>"}'
+   ```
+
+4. Interpret the response:
+   - HTTP 200 → print `✓ invite sent to <email>. Expires in 7 days.`
+   - HTTP 403 with `{"error":"Admin role required."}` → print `✗ You must be a team admin to invite members.`
+   - HTTP 404 with `{"error":"Not a team member."}` → print `✗ You're not on a team yet. Create one with POST /team/create first.`
+   - Any other error → print the server's `error` field verbatim.
+
+5. Print no preamble. Print no trailing summary. Just the one-line outcome.
+
+No other commands. No branching beyond the four response cases above.

package/commands/ashlr-tier.md

@@ -0,0 +1,122 @@
+---
+name: ashlr-tier
+description: Three-phase tiered delegation — explore (haiku) → implement (sonnet) → integration-check (haiku). Routes each phase to the right model tier automatically.
+argument-hint: "`<task>`"
+---
+
+Run a task through three model tiers in sequence, each phase feeding the next.
+
+## Usage
+
+```
+/ashlr-tier <task>
+```
+
+## How it works
+
+The phase 2 agent is selected based on the caller's ashlr tier (resolved from `~/.ashlr/pro-token-cache.json`):
+
+| Phase | Free tier | Pro/Team tier | Role |
+|-------|-----------|---------------|------|
+| 1 — Discovery | `ashlr:ashlr:explore` (haiku) | `ashlr:ashlr:explore` (haiku) | Map relevant files, understand current state, surface risks |
+| 2 — Implementation | `ashlr:ashlr:explore` (haiku) | `ashlr:ashlr:code` (sonnet) | Implement the change using Phase 1 findings |
+| 3 — Integration check | `ashlr:ashlr:plan` (haiku) | `ashlr:ashlr:plan` (haiku) | Verify the implementation is consistent, surfaces integration risks |
+
+Free tier defaults to haiku for phase 2 to keep delegation costs predictable; Pro/Team tier upgrades to sonnet for higher implementation quality. Override via `--force-sonnet` (any tier) or `--force-haiku` (any tier) — see args.
+
+## Examples
+
+```
+/ashlr-tier add rate limiting to the HTTP server
+/ashlr-tier refactor the genome pipeline to use streaming
+/ashlr-tier extract the summarization logic into a shared helper
+```
+
+## Steps
+
+1. If `$ARGUMENTS` is empty, print usage and stop.
+
+2. **Detect tier**. Run via Bash:
+   ```
+   bun run ${CLAUDE_PLUGIN_ROOT}/scripts/check-tier.ts
+   ```
+   Capture output as `<tier>` — one of `free`, `pro`, `team`.
+   - If `$ARGUMENTS` contains `--force-sonnet`, set `<tier>` to `pro`.
+   - If `$ARGUMENTS` contains `--force-haiku`, set `<tier>` to `free`.
+   - Strip the `--force-*` flag from the forwarded `<task>` argument.
+
+3. **Phase 1 — Discovery** (spawn `ashlr:ashlr:explore`):
+
+   Prompt:
+   ```
+   Discovery phase for task: <task>
+
+   1. Map all files that will need to change or be understood.
+   2. Identify the entry points, key functions, and data flows involved.
+   3. Surface any gotchas, risks, or constraints the implementer must know.
+   4. List any existing utilities or patterns that should be reused.
+
+   Output the standard explore shape (What / Key files / Flow / Gotchas / Unknowns). Stay under 400 words.
+   ```
+
+   Wait for completion. Capture output as `<phase1_output>`.
+
+4. **Phase 2 — Implementation** — pick subagent based on `<tier>`:
+   - `free` → spawn `ashlr:ashlr:explore` (haiku, lower cost)
+   - `pro` or `team` → spawn `ashlr:ashlr:code` (sonnet, full implementation quality)
+
+   Prompt:
+   ```
+   Implementation phase for task: <task>
+
+   Phase 1 discovery findings:
+   <phase1_output>
+
+   Using the above findings:
+   1. Implement the task.
+   2. Follow existing patterns and reuse utilities identified in Phase 1.
+   3. Handle the risks and constraints called out above.
+   4. Run tests after making changes.
+
+   Report: files changed, summary of changes, test results.
+   ```
+
+   Wait for completion. Capture output as `<phase2_output>`.
+
+5. **Phase 3 — Integration check** (spawn `ashlr:ashlr:plan`):
+
+   Prompt:
+   ```
+   Integration check for task: <task>
+
+   Phase 2 implementation summary:
+   <phase2_output>
+
+   Review the implementation for:
+   1. Interface consistency — are all callers of changed functions still compatible?
+   2. Missing edge cases — what inputs/states weren't tested?
+   3. Integration risks — what other system components could be affected?
+   4. Follow-up tasks needed before this is production-ready.
+
+   Output: verdict (Ready / Needs work / Blocked), top 3 risks with file:line citations, recommended follow-ups.
+   ```
+
+   Wait for completion. Capture output as `<phase3_output>`.
+
+6. Print final report. The Phase 2 header line should reflect the actual model used (sonnet for pro/team, haiku for free):
+
+   ```
+   ## /ashlr-tier — <task> (tier: <tier>)
+
+   ### Phase 1: Discovery (explore / haiku)
+   <phase1_output>
+
+   ### Phase 2: Implementation (<code/sonnet> if pro/team, <explore/haiku> if free)
+   <phase2_output>
+
+   ### Phase 3: Integration check (plan / haiku)
+   <phase3_output>
+
+   ---
+   Verdict: <extracted from phase3>
+   ```

package/commands/ashlr-tour.md

@@ -0,0 +1,60 @@
+---
+name: ashlr-tour
+description: 60-second guided walkthrough of the ashlr-plugin on the current project — proves the value of the tools on real files.
+---
+
+You are giving a first-run tour of the ashlr-plugin. Execute the steps below in order. Each narration must be at most 2 sentences — short, instructional, second-person ("you"). Do not dump raw payloads unless asked: summarize what the user should notice.
+
+### Step 0 — status-line legend
+
+Run `/ashlr-legend` and show the output verbatim in a fenced code block.
+
+Narrate: "This is what every element in your status line means — refer back to it any time."
+
+### Step 1 — current state
+
+Run the `/ashlr-status` skill (or read `~/.ashlr/stats.json` directly). Narrate: what ashlr currently sees (MCP servers active, genome present?, lifetime tokens saved so far). Keep it to one line.
+
+### Step 2 — tree view
+
+Call `ashlr__tree` on the current working directory (`cwd`).
+
+Narrate: "Here is what `ashlr__tree` shows the model instead of dozens of `ls`/`Read` calls — a compressed structural view of your repo."
+
+### Step 3 — read a real file
+
+Pick the largest TypeScript file in `cwd` (ignore `node_modules`, `dist`, `.git`). Call `ashlr__read` on it. After the call, fetch the raw byte count via `wc -c` and compare to the returned payload length.
+
+Narrate: "That file is X bytes on disk; `ashlr__read` returned Y bytes (~Z% of the original) — head + tail preserved, middle snipped."
+
+### Step 4 — show the receipts
+
+Call `ashlr__savings` and display the totals block verbatim in a fenced code block.
+
+Narrate: "Those two calls alone saved roughly N tokens (~$X). Multiply across a working session and it adds up fast."
+
+### Step 5 — three concrete next steps
+
+End the tour with exactly these three bullets:
+
+1. **Try a real question with genome-aware grep:**
+   ```
+   Use ashlr__grep to find "<something real in your repo>"
+   ```
+2. **Unlock deeper savings (-84% on grep) by mapping the genome:**
+   ```
+   /ashlr-genome-init
+   ```
+3. **Install the status-line so savings follow you everywhere:**
+   ```
+   /ashlr-settings set statusLine true
+   ```
+
+Close with one sentence: "That's the tour — run `/ashlr-savings` any time to see running totals, or `/ashlr-legend` to decode the status line."
+
+### Rules
+
+- Do not run tools outside this sequence during the tour.
+- If any step errors (e.g. no TS files in cwd, MCP server down), note it in one line and continue.
+- Never exceed 2 sentences of narration per step.
+- Total narration across all steps: under 60 lines.

package/commands/ashlr-update.md

@@ -0,0 +1,155 @@
+---
+name: ashlr-update
+description: Update the ashlr-plugin to the latest version from its git remote.
+---
+
+Update the installed plugin in place.
+
+The install location differs by Claude Code version:
+
+- **New layout** (most users): `~/.claude/plugins/cache/<marketplace>/ashlr/<version>/`
+- **Legacy layout**: `~/.claude/plugins/ashlr-plugin/`
+- **Dev install**: `$CLAUDE_PLUGIN_ROOT` (set when running from a local checkout)
+
+Resolve the actual path before doing anything else.
+
+Steps:
+
+1. **Resolve the install path.** Run via Bash, picking the first candidate that
+   is a git checkout:
+
+   ```bash
+   PLUGIN_DIR=""
+   for candidate in \
+     "${CLAUDE_PLUGIN_ROOT:-}" \
+     "$HOME/.claude/plugins/ashlr-plugin" \
+     "$(ls -d $HOME/.claude/plugins/cache/*/ashlr/*/ 2>/dev/null | tail -1)"; do
+     [ -z "$candidate" ] && continue
+     if [ -d "$candidate/.git" ]; then PLUGIN_DIR="$candidate"; break; fi
+   done
+   echo "PLUGIN_DIR=$PLUGIN_DIR"
+   ```
+
+   - If `PLUGIN_DIR` is empty, tell the user: "ashlr-plugin is not installed as
+     a git checkout. Re-run `/plugin marketplace add` (or reinstall from the
+     marketplace) to upgrade, then restart Claude Code." Stop here.
+   - If multiple cache directories exist (old `0.7.0/` plus a newer versioned
+     dir), the `tail -1` picks the most recent lexicographically — which is
+     usually correct. If that turns out wrong, pass the path yourself.
+
+2. **Capture the pre-update SHA:**
+
+   ```bash
+   git -C "$PLUGIN_DIR" rev-parse --short HEAD
+   ```
+
+3. **Pull and reinstall.** Run as a single bash block so the auto-recovery
+   logic stays atomic:
+
+   ```bash
+   git -C "$PLUGIN_DIR" fetch --quiet 2>&1
+   PULL_OUT=$(git -C "$PLUGIN_DIR" pull --ff-only 2>&1)
+   PULL_RC=$?
+
+   if [ $PULL_RC -ne 0 ] && echo "$PULL_OUT" | grep -q "would be overwritten by merge"; then
+     # Conflict shape: "Your local changes to the following files would be
+     # overwritten by merge:" + tab-indented file list + "Please commit ...".
+     # Extract the file list, then split into:
+     #   SAFE   — files that are gitignored at the upstream HEAD post-pull
+     #            (proof the project no longer tracks them — runtime mutations
+     #            are pure cruft, safe to discard)
+     #   UNSAFE — anything else (real source-file conflicts the user must
+     #            resolve themselves)
+     CONFLICTS=$(echo "$PULL_OUT" | awk '/would be overwritten/{flag=1; next} /^Please/{flag=0} flag' | sed 's/^[[:space:]]*//' | sed '/^$/d')
+     UPSTREAM_IGNORE=$(git -C "$PLUGIN_DIR" show "@{u}:.gitignore" 2>/dev/null)
+
+     SAFE=""
+     UNSAFE=""
+     while IFS= read -r f; do
+       [ -z "$f" ] && continue
+       if echo "$UPSTREAM_IGNORE" | grep -qFx "$f"; then
+         SAFE="$SAFE $f"
+       else
+         UNSAFE="$UNSAFE $f"
+       fi
+     done <<< "$CONFLICTS"
+
+     if [ -n "$UNSAFE" ]; then
+       echo "$PULL_OUT"
+       echo ""
+       echo "Files with local changes that aren't safe to auto-discard:"
+       for f in $UNSAFE; do echo "  $f"; done
+       echo ""
+       echo "Resolve manually, then re-run /ashlr-update."
+       exit 1
+     fi
+
+     echo "Auto-resetting runtime-only files (now gitignored upstream):"
+     for f in $SAFE; do echo "  $f"; done
+     git -C "$PLUGIN_DIR" checkout -- $SAFE
+     git -C "$PLUGIN_DIR" pull --ff-only 2>&1 | tail -5
+   elif [ $PULL_RC -ne 0 ]; then
+     echo "$PULL_OUT"
+     exit 1
+   fi
+
+   (cd "$PLUGIN_DIR" && bun install 2>&1 | tail -3)
+
+   # Refresh ~/.ashlr/last-project.json so the next MCP tool call sees the
+   # current project, not whatever stale value the SessionStart hook last
+   # wrote (could be hours/days old, pointing at a different project). Without
+   # this, even a successful pull leaves ashlr__read/grep/edit refusing every
+   # call against the user's actual cwd until they restart Claude Code.
+   if [ -n "${CLAUDE_PROJECT_DIR:-$PWD}" ]; then
+     CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" \
+       bun -e 'import("./hooks/session-start").then(m => m.writeProjectHint())' \
+       --cwd "$PLUGIN_DIR" 2>/dev/null || true
+   fi
+   ```
+
+   Why the auto-recovery: the plugin's own genome subsystem (PostToolUse
+   `genome-auto-propose` + SessionEnd consolidator) appends to runtime files
+   inside the plugin checkout. When the upstream commit moves those files into
+   `.gitignore`, any locally-mutated copy will block `git pull --ff-only` even
+   though the content is throwaway hook output. The whitelist is "in upstream's
+   `.gitignore`" — that's the project's explicit signal that the file is not
+   source content. Anything outside that whitelist still surfaces verbatim, so
+   real conflicts (a user's hand-edits to the plugin code) never get clobbered.
+
+4. **Capture the post-update SHA and the changelog:**
+
+   ```bash
+   git -C "$PLUGIN_DIR" rev-parse --short HEAD
+   git -C "$PLUGIN_DIR" log --oneline HEAD@{1}..HEAD
+   ```
+
+5. **Report:**
+
+   ```
+   ashlr-plugin updated: <old-sha> → <new-sha>
+   Changes:
+     <oneline log, or "already up to date">
+
+   ⚠ MCP servers run from the old code until you reload.
+     Fastest:  run  /reload-plugins
+     Full:     quit Claude Code and start a fresh session
+   ```
+
+   The warning is not optional — in-process MCP servers are long-lived child
+   processes that Claude Code does NOT hot-reload after `git pull`. If the
+   user keeps working without a reload, `ashlr__edit` / `ashlr__grep` / etc.
+   will still be running the previous version's code even though the source
+   on disk has moved forward.
+
+If the SHAs are equal, just print `ashlr-plugin already up to date at <sha>.`
+and skip the restart prompt.
+
+### Note on Claude Code's plugin cache
+
+The cache directory is named after the version at *install* time (e.g.
+`ashlr/0.7.0/`), and that directory name does **not** change when you pull
+newer commits into it via this skill. The path is effectively opaque — treat
+it as the plugin's git checkout, not a version indicator. Claude Code's
+marketplace loader reads `package.json` / `.claude-plugin/plugin.json` inside
+the checkout, so the version it reports will reflect the pulled HEAD, not the
+directory name.

package/commands/ashlr-upgrade.md

@@ -0,0 +1,96 @@
+---
+name: ashlr-upgrade
+description: >
+  Terminal-native free-to-pro upgrade for ashlr. Walks the user from free
+  to Pro or Team in under 90 seconds without leaving the terminal. Primary
+  path: GitHub OAuth sign-in. Fallback: magic-link email. Handles plan
+  selection, Stripe checkout (with 7-day Pro trial on first checkout), and
+  activation polling — all from the CLI.
+---
+
+You are running the ashlr upgrade flow.
+
+## What Pro gives you
+
+**Your team learns together.** Free ashlr builds a genome that lives on your machine and resets when you switch laptops. Pro lifts that genome into a shared encrypted layer so every engineer's discoveries become everyone's — across machines, across teammates, across sessions.
+
+- **Shared team genome** — every `ashlr__grep` hit, every file pattern discovered, every codebase insight lands in an encrypted, versioned store the whole team retrieves from. New engineers onboard into context, not silence.
+- **Weekly team digest** — a summary of what the team learned that week: top genome sections hit, streak rankings, savings milestones. Delivered via `/ashlr-resume`; optional email.
+- **Cross-machine streak and savings sync** — your streak counter, savings ledger, and `/ashlr-dashboard` follow you across machines without manual copy.
+- **Cloud LLM summarizer** — `ashlr__read` and genome summarization run on hosted Haiku. No local Ollama or GPU setup required.
+- **Hosted embedding retrieval** — `ashlr__grep` uses a cloud pgvector index refreshed on every push. Materially better recall on repos with > 5,000 files.
+
+**Pro:** $12/mo or $120/yr — one developer, all cloud features.
+
+**Pro Team:** $24/user/mo (min 3 seats) or $20/user/mo annual — shared encrypted genome, org-wide savings dashboard, policy packs (shipping), SSO.
+
+First checkout includes a **7-day free trial** — no charge until the trial ends, cancel any time. The free tier is never crippled; Pro adds cloud context, it does not remove anything free.
+
+## Invocation
+
+Run the upgrade script:
+
+```sh
+bun run "${CLAUDE_PLUGIN_ROOT}/scripts/upgrade-flow.ts"
+```
+
+Stream its stdout verbatim to the user. Do not add narration between steps —
+the script output is the narrative.
+
+## Sign-in methods
+
+The script will first ask how the user wants to sign in:
+
+1. **Sign in with GitHub** (primary) — opens `https://plugin.ashlr.ai/signin`
+   in the browser. After GitHub OAuth consent (`read:user user:email public_repo`),
+   the CLI receives a token automatically. This also unlocks the repo picker for
+   auto-genome builds on public repos.
+2. **Magic link** (fallback) — sends a one-time sign-in link to the user's email.
+   Use this if the user cannot open a browser or prefers not to connect GitHub.
+
+## Flags
+
+Pass any user-supplied flags through directly. Supported flags:
+
+- `--tier pro|team` — pre-select a tier
+- `--annual` — pre-select annual billing
+- `--email <addr>` — skip the email prompt (magic-link path only)
+- `--no-poll` — skip the activation polling step (useful for testing)
+
+Example with flags:
+
+```sh
+bun run "${CLAUDE_PLUGIN_ROOT}/scripts/upgrade-flow.ts" --tier pro --annual
+```
+
+## Handling [ASHLR_PROMPT: ...] markers
+
+When the script prints a line starting with `[ASHLR_PROMPT: ...]`, pause,
+ask the user exactly the question inside the brackets, collect their input,
+and write it to the script's stdin followed by a newline.
+
+The markers you will encounter:
+
+- `[ASHLR_PROMPT: How would you like to sign in? (1) GitHub  (2) Email magic link]` — ask which method
+- `[ASHLR_PROMPT: Email to sign in?]` — ask for the user's email address (magic-link path)
+- `[ASHLR_PROMPT: Choose a plan (1-4, default 1):]` — ask which plan number
+- `[ASHLR_PROMPT: How many seats (default 3):]` — (Team plans only) ask seat count
+
+## 7-day Pro trial
+
+First-time Pro checkouts include a 7-day free trial — no charge until the
+trial ends. The script surfaces the trial offer automatically. If you see a
+user hesitating, remind them: trial starts immediately, cancel any time before
+day 7, no charge if cancelled.
+
+## Error handling
+
+If the script exits non-zero, show stderr and tell the user to run
+`/ashlr-doctor` for a full diagnosis.
+
+## Rules
+
+- Do not run any destructive operation without the user's explicit confirmation.
+- Do not add narration between wizard sections — the script output is the narrative.
+- Keep responses concise — the upgrade flow output is the substance.
+- If the user is already on Pro or Team, the script will say so and exit — do not re-run it.