ashlr-plugin 1.36.4

package/docs/github-oauth-onboarding.md

@@ -0,0 +1,127 @@
+# GitHub OAuth Onboarding
+
+Complete walkthrough: sign in with GitHub, pick a repo, and have a cloud genome ready before your first grep.
+
+---
+
+## Prerequisites
+
+- ashlr-plugin installed and active (`/ashlr-status` shows green)
+- Claude Code running (any plan)
+- A GitHub account with at least one public repo
+
+---
+
+## Step 1 — Start the upgrade flow
+
+Inside Claude Code, run:
+
+```
+/ashlr-upgrade
+```
+
+The script will ask how you want to sign in. Choose option 1: **Sign in with GitHub**.
+
+Alternatively, visit `https://plugin.ashlr.ai/signin` directly in your browser.
+
+---
+
+## Step 2 — Click "Sign in with GitHub"
+
+Your browser opens `https://plugin.ashlr.ai/signin`. Click the "Sign in with GitHub" button. You will be redirected to GitHub's OAuth consent screen.
+
+---
+
+## Step 3 — Authorize the GitHub scopes
+
+GitHub will ask you to authorize three scopes:
+
+| Scope | Why it's needed |
+|---|---|
+| `read:user` | Read your GitHub username and profile |
+| `user:email` | Read your primary email address for account creation |
+| `public_repo` | List your public repos in the repo picker; clone public repos for genome builds |
+
+Click **Authorize**. These are the minimum scopes required. Private-repo access (`repo` scope) is a separate step-up consent — it is never requested without an explicit prompt.
+
+---
+
+## Step 4 — CLI receives token automatically
+
+After you authorize, GitHub redirects back to `plugin.ashlr.ai/auth/github/callback`. The server:
+
+1. Exchanges the code for a GitHub access token.
+2. Encrypts the token with AES-256-GCM and stores it server-side.
+3. Writes a session record that your CLI is polling.
+
+Your terminal (which has been polling `/auth/status?session=<sid>` in the background) will print a confirmation and continue to the next step automatically. You do not need to copy or paste anything.
+
+---
+
+## Step 5 — Pick a public repo in the repo picker
+
+Your browser lands on the repo picker at `plugin.ashlr.ai/repos`. It shows your public GitHub repos. Click a repo to trigger a genome build.
+
+The genome build runs in the background on the server:
+
+- `git clone --depth 1` of the repo (60s timeout)
+- `genome-init --minimal` to extract architecture, conventions, and key paths (120s timeout)
+- Sections are encrypted per-user with AES-GCM and stored
+
+Small repos (< 1k files): 5–10 seconds. Large repos: up to 2 minutes. You can close the browser tab — the build continues server-side.
+
+---
+
+## Step 6 — Cloud genome is consulted automatically
+
+On your next session start in a project whose git remote matches the repo you picked, `hooks/session-start.ts` runs `scripts/genome-cloud-pull.ts` which:
+
+1. Reads the git remote of your current `cwd`.
+2. Canonicalizes the repo URL and calls `GET /genome/personal/find?repo_url=<canon>`.
+3. Downloads encrypted sections to `~/.ashlr/genomes/<projectHash>/`.
+4. Writes a `.ashlr-cloud-genome` marker file.
+
+From that point on, `ashlr__grep` checks the cloud genome cache automatically — no flags, no config. Local `.ashlrcode/genome/` always takes precedence if it exists.
+
+---
+
+## Troubleshooting
+
+### Token not saved / CLI not receiving the callback
+
+- Make sure the browser tab stayed open through the OAuth flow.
+- Check that `BASE_URL` on the server matches the URL your CLI is hitting.
+- Run `/ashlr-doctor` — it checks auth connectivity.
+- Try `/ashlr-upgrade` again; the polling session is single-use but a new one is issued each run.
+
+### Genome build failed
+
+- Check build status at `plugin.ashlr.ai/repos` — each repo shows a status badge.
+- Common causes: repo too large (> 50k files), clone timeout, missing default branch.
+- Open an issue with the repo URL (public repos only) at `github.com/ashlrai/ashlr-plugin`.
+
+### Private repo access
+
+Private repos require the Pro tier. After upgrading, `/ashlr-upgrade` will offer a `repo` scope step-up consent screen. This is a separate OAuth authorization — you will see a new GitHub consent page listing the additional `repo` scope. See [docs/cloud-genome.md](cloud-genome.md) for how tier gating works server-side.
+
+### Revoking access
+
+To revoke ashlr's GitHub access: visit `github.com/settings/applications`, find "ashlr", click Revoke. Your stored token will be invalidated on GitHub's side; the encrypted copy on the server will fail to authenticate on next use and be cleared.
+
+---
+
+## Security note
+
+GitHub access tokens are encrypted at rest using AES-256-GCM with a server-managed master key (`ASHLR_MASTER_KEY`). Tokens are never returned to the browser. OAuth state tokens are HMAC-signed with a 10-minute TTL and use constant-time comparison to prevent timing attacks. Scopes are limited to the minimum required; `repo` (private access) requires explicit additional consent.
+
+See [SECURITY.md](../SECURITY.md#github-oauth-security-v113) for the full security model.
+
+---
+
+## Kill switches
+
+| Method | Effect |
+|---|---|
+| `ASHLR_CLOUD_GENOME_DISABLE=1` | Disables cloud genome pull on session start. `ashlr__grep` will not consult `~/.ashlr/genomes/`. |
+| Delete `~/.ashlr/genomes/` | Removes all locally cached cloud genome sections. They will re-download on next session start if the server still has a build. |
+| Revoke on GitHub | Invalidates the access token. Genome builds for private repos will fail until re-authorized. |

package/docs/hero-video-script.md

@@ -0,0 +1,129 @@
+# Hero video script — ashlr v1.4.0
+
+Shooter's brief. 30 seconds. No narration. Terminal + browser + minimal type captions.
+Aspect ratio 16:9. Export at 1080p minimum.
+
+---
+
+## Shot list
+
+### 0:00 – 0:05 | Terminal — savings command
+
+**Setup:** Clean terminal, dark background, JetBrains Mono or similar. No clutter in prompt.
+
+**Action:**
+```
+$ /ashlr-savings
+```
+Output renders smoothly — the ASCII dashboard animates in, showing per-tool rows, the 7-day sparkline, session total, lifetime total.
+
+**Caption (lower-left, monospaced, small):**
+```
+/ashlr-savings
+```
+
+**Notes:** Use a session with real numbers. Session total should be at least 40K tokens for visual impact. Record at 1x speed; do not speed up. Let the render finish before cut.
+
+---
+
+### 0:05 – 0:10 | Terminal — status line
+
+**Setup:** Same terminal session. Scroll past the dashboard output or open a new pane showing the status line in the Claude Code footer.
+
+**Action:** Status line is visible and animating:
+```
+ashlr · 7d ▁▂▃▅▇█ · session ↑+100K · lifetime +4.3M
+```
+The gradient shimmer sweeps left to right. The `↑` activity indicator is lit (fire a tool call to trigger it if needed).
+
+**Caption:**
+```
+live session counter · 7-day sparkline
+```
+
+**Notes:** Record at real speed; the animation cycle is 120 ms per frame. The gradient sweep should be visible. If the terminal is too narrow to show the full line, widen it before recording.
+
+---
+
+### 0:10 – 0:15 | Terminal — edit with live counter
+
+**Setup:** Same terminal. Open a source file in Claude Code or simulate an `ashlr__edit` call.
+
+**Action:** Run an edit on a medium-sized file (200+ char search string). As the edit completes, the status line counter ticks up visibly — the `↑` indicator appears and the session number increments.
+
+**Caption:**
+```
+counter updates within ~550ms of each tool call
+```
+
+**Notes:** The increment should be visible on screen — choose a file where the edit saves at least 500 tokens. The key visual is the `↑` appearing and the number changing.
+
+---
+
+### 0:15 – 0:20 | Terminal — dashboard
+
+**Setup:** New terminal frame or continuation.
+
+**Action:**
+```
+$ /ashlr-dashboard
+```
+The full ASCII dashboard renders: wordmark banner, three CountUp tiles (session / lifetime / best day), per-tool horizontal bar chart, 7-day and 30-day sparklines, projected annual line in Fraunces italic (simulated in terminal with the actual output).
+
+**Caption:**
+```
+/ashlr-dashboard
+```
+
+**Notes:** Use `--watch` mode if the recording is long enough (it redraws every 1.5s). Otherwise a static render is fine. Ensure the bar chart has at least 3 tools with visible bars.
+
+---
+
+### 0:20 – 0:25 | Browser — landing page
+
+**Setup:** Browser, clean tab, navigate to `plugin.ashlr.ai`. No bookmarks bar visible. Window at 1280x800 minimum.
+
+**Action:** The landing page loads. Scroll slowly past:
+1. Hero with the `−57%` number
+2. The before/after bytes comparison animation (let it play)
+3. The animated SVG terminal mock in the hero
+
+**Caption:**
+```
+plugin.ashlr.ai
+```
+
+**Notes:** Let the before/after animation complete at least once. Do not scroll faster than the animations. The parchment grain texture and the stamp rotate-in on the final percentage are the key visual moments.
+
+---
+
+### 0:25 – 0:30 | Browser + terminal — install + tagline
+
+**Setup:** Split or sequence: browser showing `plugin.ashlr.ai/benchmarks` with the −57% bar chart, then cut to terminal.
+
+**Browser action (0:25 – 0:27):**
+Navigate to `plugin.ashlr.ai/benchmarks`. The −57% cross-language bar is visible. Pause 2 seconds.
+
+**Terminal action (0:27 – 0:30):**
+```
+$ curl -fsSL https://plugin.ashlr.ai/install.sh | bash
+```
+Installation output begins to scroll.
+
+**Caption (centered, Fraunces, large, fades in over install output):**
+```
+ship less context.
+```
+
+**Notes:** The tagline card should appear as the install command fires — the juxtaposition of "running the thing" with the headline is the intended close. Fade to black on the tagline, not on the terminal output.
+
+---
+
+## General notes
+
+- **No narration.** Captions only. Keep them in JetBrains Mono at 11–13px equivalent in the video.
+- **Music:** Optional ambient/lo-fi. If used: −18 LUFS integrated, fade out before final tagline card.
+- **Color:** Parchment palette — `#F3EADB` background, `#8B2E1A` accent. Terminal can be dark.
+- **Transitions:** Cut only. No dissolves, no wipes.
+- **Duration:** 30 seconds hard. Do not pad.
+- **Export:** H.264, 1080p, 60fps. Separate 4K master if available.