docs: add a terminal hero and a Motion Canvas explainer

.github/workflows/render-hero-tape.yml

@@ -0,0 +1,56 @@
+# Manual re-render of the terminal hero. The committed GIF and WebM are the
+# ones linked from the README. This workflow does not publish them.
+name: Render hero tape
+
+on:
+  workflow_dispatch:
+
+jobs:
+  render:
+    name: Render hero GIF and WebM
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install VHS, ttyd, and ffmpeg
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg fonts-jetbrains-mono
+          curl -fsSL -o /tmp/vhs.tar.gz https://github.com/charmbracelet/vhs/releases/download/v0.12.1/vhs_0.12.1_Linux_x86_64.tar.gz
+          tar -xzf /tmp/vhs.tar.gz -C /tmp
+          sudo install -m 755 /tmp/vhs_0.12.1_Linux_x86_64/vhs /usr/local/bin/vhs
+          curl -fsSL -o /tmp/ttyd https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd.x86_64
+          sudo install -m 755 /tmp/ttyd /usr/local/bin/ttyd
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+
+      - name: Render
+        run: vhs docs/tapes/hero.tape
+
+      - name: Keep the GIF short and small
+        run: |
+          bytes=$(stat -c%s docs/assets/hero.gif)
+          echo "gif bytes: $bytes"
+          test "$bytes" -le 3145728
+          duration=$(ffprobe -v error -show_entries format=duration -of csv=p=0 docs/assets/hero.gif)
+          echo "gif seconds: $duration"
+          awk -v d="$duration" 'BEGIN { exit !(d > 0 && d < 15) }'
+          test -s docs/assets/hero.webm
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hero-terminal
+          path: |
+            docs/assets/hero.gif
+            docs/assets/hero.webm
+          if-no-files-found: error

.gitignore

@@ -27,6 +27,11 @@ grammars/*.wasm
 .agents/
 .tmp-research-repos/
 docs/visuals.md
+
+# Motion Canvas explainer dependencies and local renders
+media/explainer/node_modules/
+media/explainer/output/
+media/explainer/dist/
 .repolore/
 .opencode/
 CODEBASE_MAP.md

.npmignore

@@ -1,2 +1,7 @@
 docs/TODO.md
 docs/visuals.md
+media/
+docs/tapes/
+docs/assets/*.gif
+docs/assets/*.webm
+docs/assets/*.svg

README.md

@@ -92,6 +92,14 @@ The `codebase-context-review` CLI creates a bounded context packet from a commit
 2. **Understand the repository.** The agent can request a compact codebase map with structure, patterns, and representative files.
 3. **Find the code for the task.** Search returns ranked files and symbols; the agent reads the selected files before editing.
 
+```mermaid
+flowchart TD
+  indexLocal["Index locally"] --> repoMap["Map: structure, patterns, representative files"]
+  repoMap --> searchCode["search_codebase"]
+  searchCode --> ranked["Ranked files and symbols"]
+  searchCode --> beforeEdit["Edit intent: what to read before changing code"]
+```
+
 The same information is available from the terminal. Run these commands from your project root. The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. Once it is ready, inspect the map and search for the code you need:
 
 ```bash
@@ -112,6 +120,10 @@ One stdio server can route across several repositories. Supply `project` in tool
 
 ## See it
 
+This recording is `map`, then `search --intent edit`, on the fixture in `tests/fixtures/codebases/eval-controlled`. The index was built off-camera with `reindex --no-embeddings`, and the screen is cleared before the search so the preflight stays in view. In this take the preflight says the match is low confidence and not ready to edit. A [WebM copy](https://github.com/PatrickSys/codebase-context/blob/master/docs/assets/hero.webm) is the same take.
+
+![map, then search, paused on the edit preflight for the eval-controlled fixture](./docs/assets/hero.gif)
+
 These are real CLI results from the open-source `angular-spotify` repository.
 
 **Patterns and representative files**
@@ -132,6 +144,8 @@ More examples are available in the [CLI gallery](./docs/cli.md) and [walkthrough
 
 Code and indexes stay on the machine with the default local embedding provider. Docker, a GPU, and an API key are not required.
 
+![code never leaves the machine: the default local path keeps the repository and index on this machine. Cloud embeddings are optional and send chunks to that provider.](./docs/assets/code-stays-local.svg)
+
 Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index. The provider, model, project root, and local HTTP port can be changed through environment variables or the project config; see the [capabilities reference](./docs/capabilities.md).
 
 This is the privacy boundary of Codebase Context itself. Your AI client may send search results or file contents to the model provider configured in that client. Codebase Context does not control that connection. If you commit and push `.codebase-context/memory.json`, the recorded project memory also travels with the repository.

docs/tapes/hero.tape

@@ -0,0 +1,47 @@
+# Hero recording: map, then search --intent edit, then a pause on the preflight.
+# Render from the repository root after `pnpm build`:
+#   vhs docs/tapes/hero.tape
+# The hidden setup builds a model-free index. It is not part of the GIF.
+# Keep the visible GIF under 15 seconds and under 3 MB.
+# GitHub Actions workflow: render-hero-tape (manual).
+
+Output docs/assets/hero.gif
+Output docs/assets/hero.webm
+
+Require node
+Require ffmpeg
+
+Set FontFamily "JetBrains Mono"
+Set FontSize 16
+Set Columns 96
+Set Rows 36
+Set Padding 18
+Set TypingSpeed 12ms
+Set Framerate 12
+Set Theme "Catppuccin Mocha"
+
+Env CODEBASE_CONTEXT_ASCII "1"
+Env CODEBASE_ROOT "tests/fixtures/codebases/eval-controlled"
+
+Hide
+Type "export PS1='$ '"
+Enter
+Type "clear"
+Enter
+Type "node dist/index.js reindex --no-embeddings"
+Enter
+Wait+Screen /Indexed/
+Type "clear"
+Enter
+Sleep 200ms
+Show
+
+Type "node dist/index.js map"
+Enter
+Sleep 2.2s
+Type "clear"
+Enter
+Sleep 250ms
+Type "node dist/index.js search --query 'auth headers' --intent edit --limit 3"
+Enter
+Sleep 5s

media/PROMPTS.md

@@ -0,0 +1,125 @@
+# Prompts
+
+Ready to paste. The words in the next section are copied from the README and the benchmark. Keep them as written.
+
+The README hero is the recorded terminal GIF at `docs/assets/hero.gif` (WebM: `docs/assets/hero.webm`). It is one take of `map`, then `search --intent edit`, on `tests/fixtures/codebases/eval-controlled`. In that take the preflight says the match is low confidence and not ready to edit. Do not ask a model to draw a fake terminal result.
+
+Agent: cursor-cloud/cbc-visuals
+
+## Words to copy
+
+```text
+Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns.
+
+Search, examples and project memory run locally by default.
+
+search_codebase ranks files and symbols for the task instead of returning an unstructured dump.
+
+get_team_patterns shows the approaches used in the repository and points to representative files.
+
+Index locally. Codebase Context scans the project, builds a keyword index, and creates local semantic embeddings.
+
+The search result shows ranked files, relevant project patterns, and what the agent should read before it changes code.
+
+Code and indexes stay on the machine with the default local embedding provider. Docker, a GPU, and an API key are not required.
+
+Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index.
+
+claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context
+
+The existing benchmark reports 25.7% expected-file recovery versus jCodeMunch's 27.1% in a fixed retrieval comparison; it does not establish a winner or coding quality.
+```
+
+Leave the benchmark sentence out unless the picture needs a number. If a number appears, use that whole sentence. Do not add a speed, token, or coding-quality claim.
+
+## README still
+
+Use this when a still image is wanted beside the recorded GIF. The GIF remains the hero.
+
+### Claude
+
+```text
+Draw a wide SVG, about 1600 by 640, for the Codebase Context README. Dark background, plain rectangles and one accent color, no photos, no logos, no fake screenshots, no charts.
+
+Use only these sentences, copied as written:
+
+Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns.
+
+Search, examples and project memory run locally by default.
+
+Do not add metrics. Do not draw a terminal. The real demo is a separate GIF.
+```
+
+### Image model
+
+```text
+Wide dark banner, 1600x640, flat geometric shapes, cream text, one amber accent, no people, no stock photos, no UI chrome, no terminal, no numbers. Headline copied exactly: "Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns." Second line copied exactly: "Search, examples and project memory run locally by default."
+```
+
+### Video model
+
+```text
+10 second silent motion graphic, 1600x640, plain rectangles and text on a dark field. No stock footage, no people, no fake product UI. Show this sentence for the first half, copied exactly: "Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns." Then this sentence, copied exactly: "Search, examples and project memory run locally by default." No other claims.
+```
+
+## LinkedIn card
+
+1200 by 627. Same limits: no fake terminal, no invented numbers.
+
+### Claude
+
+```text
+Make a 1200 by 627 SVG card for a LinkedIn post about Codebase Context. Flat shapes, dark background, cream type, one accent. No people, no stock photos, no screenshots, no charts.
+
+Copy these lines exactly:
+
+Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns.
+
+Search, examples and project memory run locally by default.
+
+Code and indexes stay on the machine with the default local embedding provider.
+
+If you mention a measurement, use this whole sentence and no other number: "The existing benchmark reports 25.7% expected-file recovery versus jCodeMunch's 27.1% in a fixed retrieval comparison; it does not establish a winner or coding quality."
+```
+
+### Image model
+
+```text
+LinkedIn card, 1200x627, flat dark layout, three short text blocks, no photographs, no faces, no fake dashboard. Text must be copied exactly and remain readable: "Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns." "Search, examples and project memory run locally by default." "Code and indexes stay on the machine with the default local embedding provider." No extra slogans and no numbers.
+```
+
+### Video model
+
+```text
+15 second silent LinkedIn video, 1200x627, plain shapes and text only. No stock clips, no people, no screen recording. Three beats, each a sentence copied exactly: "Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns." Then "Search, examples and project memory run locally by default." Then "Code and indexes stay on the machine with the default local embedding provider." End there. No winner, speed, or token claim.
+```
+
+## Reddit-safe diagram
+
+A diagram, not an ad. No hype, no fake before/after, no cropped benchmark.
+
+### Claude
+
+```text
+Draw an SVG diagram a Reddit reader can check against the README. White background, sketch-style boxes and arrows, black stroke, no photos, no fake terminal, no trophy, no "10x".
+
+Title, copied in meaning from the README privacy section: code stays on the machine with the default local provider.
+
+Three boxes in a row: Repository, Local index, Results. A dashed box under them: "Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index."
+
+Footer, copied exactly: "Docker, a GPU, and an API key are not required."
+
+Do not include the 25.7% figure. The diagram is about where code goes, not about retrieval score.
+```
+
+### Image model
+
+```text
+Clean diagram on white, hand-drawn boxes, 1200x700, black ink, light blue and green fills, one dashed red box. No people, no logos, no screenshots, no numbers. Title: "Code and indexes stay on the machine with the default local embedding provider." Three boxes: Repository, Local index, Results. Dashed box: "Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index." Footer: "Docker, a GPU, and an API key are not required." All of those sentences must be spelled as written.
+```
+
+### Video model
+
+```text
+12 second silent diagram video, white background, sketch boxes drawing themselves, no stock footage, no voiceover, no numbers. Start with three boxes labeled Repository, Local index, and Results, and the sentence "Code and indexes stay on the machine with the default local embedding provider." Then draw a dashed box with the sentence "Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index." End on "Docker, a GPU, and an API key are not required." Do not add a comparison or a winner.
+```