git-stunts · flyingrobots · Feb 15, 2026 · Feb 15, 2026 · Feb 15, 2026 · Feb 15, 2026
diff --git a/Dockerfile b/Dockerfile
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1 @@
+docker/Dockerfile.node22-slim
diff --git a/FIXUPS.md b/FIXUPS.md
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![npm version](https://badge.fury.io/js/%40git-stunts%2Fgit-warp.svg)](https://www.npmjs.com/package/@git-stunts/git-warp)
 
 <p align="center">
-  <img src="hero.gif" alt="git-warp CLI demo" width="600">
+  <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
 ## The Core Idea

diff --git a/bin/cli/shared.js b/bin/cli/shared.js
@@ -180,7 +180,7 @@ export async function readCheckpointDate(persistence, checkpointSha) {
 export function createHookInstaller() {
   const __filename = new URL(import.meta.url).pathname;
   const __dirname = path.dirname(__filename);
-  const templateDir = path.resolve(__dirname, '..', '..', 'src', 'hooks');
+  const templateDir = path.resolve(__dirname, '..', '..', 'scripts', 'hooks');
   const { version } = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', 'package.json'), 'utf8'));
   return new HookInstaller({
     fs: /** @type {*} */ (fs), // TODO(ts-cleanup): narrow port type

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -2,14 +2,14 @@ services:
   test:
     build:
       context: ..
-      dockerfile: git-warp/Dockerfile
+      dockerfile: git-warp/docker/Dockerfile.node22-slim
     environment:
       - GIT_STUNTS_DOCKER=1
 
   benchmark:
     build:
       context: ..
-      dockerfile: git-warp/Dockerfile
+      dockerfile: git-warp/docker/Dockerfile.benchmark
     volumes:
       - ./benchmarks:/app/benchmarks
     environment:

diff --git a/Dockerfile.benchmark → docker/Dockerfile.benchmark b/Dockerfile.benchmark → docker/Dockerfile.benchmark
diff --git a/docker/Dockerfile.node22-slim b/docker/Dockerfile.node22-slim
@@ -0,0 +1,26 @@
+FROM node:22-slim
+RUN apt-get update && apt-get install -y \
+    bats \
+    git \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+# Copy git-warp
+COPY git-warp/package*.json ./
+COPY git-warp/scripts ./scripts
+COPY git-warp/patches ./patches
+RUN npm install
+COPY git-warp .
+RUN git init -q \
+  && git config user.email "container@git-warp.local" \
+  && git config user.name "Git Warp Container" \
+  && git add -A \
+  && git commit --allow-empty -m "seed git-warp" >/dev/null
+RUN printf '%s\n' '#!/usr/bin/env bash' 'exec node /app/bin/warp-graph.js "$@"' > /usr/local/bin/warp-graph
+RUN chmod +x /usr/local/bin/warp-graph \
+  && install -m 0755 /app/bin/git-warp /usr/local/bin/git-warp
+ENV GIT_STUNTS_DOCKER=1
+# Default to tests, but can be overridden for benchmark
+CMD ["npm", "test"]
diff --git a/TYPESCRIPT_ZERO.md → docs/TYPESCRIPT_ZERO.md b/TYPESCRIPT_ZERO.md → docs/TYPESCRIPT_ZERO.md
diff --git a/hero.gif → docs/images/hero.gif b/hero.gif → docs/images/hero.gif
diff --git a/hero.tape → docs/images/hero.tape b/hero.tape → docs/images/hero.tape
@@ -1,7 +1,7 @@
 # hero.tape — git-warp hero GIF for README
 # Record: vhs hero.tape
 
-Output hero.gif
+Output docs/images/hero.gif
 
 Set Shell "bash"
 Set FontSize 16

diff --git a/examples/WALKTHROUGH.md b/examples/WALKTHROUGH.md
@@ -174,7 +174,7 @@ See that tree hash? `4b825dc642cb6eb9a060e54bf8d69288fbee4904` is the **empty tr
 Still in the container, run:
 
 ```bash
-node /app/examples/explore.js
+node /app/examples/scripts/explore.js
 ```
 
 Or from your host machine:
@@ -413,7 +413,7 @@ This removes the container and volumes. Run `demo:setup` again anytime to start
 - Read the [ARCHITECTURE.md](../ARCHITECTURE.md) for a technical deep-dive into index sharding and hexagonal design
 - Check out the [README.md](../README.md) for the full API reference
 - Look at the source in `src/domain/services/TraversalService.js` to see how algorithms are implemented
-- Explore [examples/explore.js](./explore.js) to understand the event projection pattern
+- Explore [examples/scripts/explore.js](./scripts/explore.js) to understand the event projection pattern
 - Try building your own event-sourced application!
 
 ---
@@ -456,11 +456,11 @@ npm run demo:setup
 
 For the curious, here's what happens behind the scenes:
 
-1. **`npm run demo:setup`** runs `docker compose up -d` in the `examples/` directory, then executes `setup.js` inside the container.
+1. **`npm run demo:setup`** runs `docker compose up -d` in the `examples/` directory, then executes `scripts/setup.js` inside the container.
 
-2. **`setup.js`** initializes a git repo at `/demo`, creates a chain of event commits using `graph.createNode()`, branches off at `OrderPlaced` to create an alternate timeline, and builds the bitmap index.
+2. **`scripts/setup.js`** initializes a git repo at `/demo`, creates a chain of event commits using `graph.createNode()`, branches off at `OrderPlaced` to create an alternate timeline, and builds the bitmap index.
 
-3. **`explore.js`** loads the index, then demonstrates:
+3. **`scripts/explore.js`** loads the index, then demonstrates:
    - `graph.traversal.ancestors()` for event replay
    - Event projection (reducer pattern)
    - `graph.traversal.descendants()` for branch comparison

diff --git a/examples/html/event-sourcing.html b/examples/html/event-sourcing.html
@@ -39,14 +39,14 @@
       <div class="menu-panel-content">
       <div class="menu-title">Examples</div>
       <div class="menu-links">
-        <a href="setup.html">setup.js</a>
-        <a href="explore.html">explore.js</a>
-        <a href="multi-writer.html">multi-writer.js</a>
-        <a href="event-sourcing.html">event-sourcing.js</a>
-        <a href="lagrangian-path.html">lagrangian-path.js</a>
-        <a href="traversal-benchmark.html">traversal-benchmark.js</a>
-        <a href="streaming-benchmark.html">streaming-benchmark.js</a>
-        <a href="inspect-index.html">inspect-index.js</a>
+        <a href="setup.html">scripts/setup.js</a>
+        <a href="explore.html">scripts/explore.js</a>
+        <a href="multi-writer.html">scripts/multi-writer.js</a>
+        <a href="event-sourcing.html">scripts/event-sourcing.js</a>
+        <a href="lagrangian-path.html">scripts/lagrangian-path.js</a>
+        <a href="traversal-benchmark.html">scripts/traversal-benchmark.js</a>
+        <a href="streaming-benchmark.html">scripts/streaming-benchmark.js</a>
+        <a href="inspect-index.html">scripts/inspect-index.js</a>
       </div>
       <div class="menu-section">
         <label class="theme-label" for="theme-select">Theme</label>
@@ -84,7 +84,7 @@ <h1 class="hero-title">event-sourcing.js: Conceptual Map</h1>
     </div>
     <div class="hero-meta">
       <strong>Run it</strong>
-      <p>node event-sourcing.js</p>
+      <p>node scripts/event-sourcing.js</p>
       <p>Prints the conceptual explanation to the console.</p>
     </div>
   </header>
@@ -94,7 +94,7 @@ <h1 class="hero-title">event-sourcing.js: Conceptual Map</h1>
     <section class="section-block">
       <h2 class="section-title">Setup</h2>
       <p class="section-body">Treat every patch as a business event and use materialize as the projection step that builds the current domain state.</p>
-      <p class="section-body">Run it with <code>node event-sourcing.js</code> to write the event log and project it.</p>
+      <p class="section-body">Run it with <code>node scripts/event-sourcing.js</code> to write the event log and project it.</p>
     </section>
 
     <section class="graph-grid">

diff --git a/examples/html/explore.html b/examples/html/explore.html
@@ -39,14 +39,14 @@
       <div class="menu-panel-content">
       <div class="menu-title">Examples</div>
       <div class="menu-links">
-        <a href="setup.html">setup.js</a>
-        <a href="explore.html">explore.js</a>
-        <a href="multi-writer.html">multi-writer.js</a>
-        <a href="event-sourcing.html">event-sourcing.js</a>
-        <a href="lagrangian-path.html">lagrangian-path.js</a>
-        <a href="traversal-benchmark.html">traversal-benchmark.js</a>
-        <a href="streaming-benchmark.html">streaming-benchmark.js</a>
-        <a href="inspect-index.html">inspect-index.js</a>
+        <a href="setup.html">scripts/setup.js</a>
+        <a href="explore.html">scripts/explore.js</a>
+        <a href="multi-writer.html">scripts/multi-writer.js</a>
+        <a href="event-sourcing.html">scripts/event-sourcing.js</a>
+        <a href="lagrangian-path.html">scripts/lagrangian-path.js</a>
+        <a href="traversal-benchmark.html">scripts/traversal-benchmark.js</a>
+        <a href="streaming-benchmark.html">scripts/streaming-benchmark.js</a>
+        <a href="inspect-index.html">scripts/inspect-index.js</a>
       </div>
       <div class="menu-section">
         <label class="theme-label" for="theme-select">Theme</label>
@@ -84,7 +84,7 @@ <h1 class="hero-title">explore.js: Query the Materialized Graph</h1>
     </div>
     <div class="hero-meta">
       <strong>Run it</strong>
-      <p>node explore.js</p>
+      <p>node scripts/explore.js</p>
       <p>Requires setup.js to have created the demo graph.</p>
     </div>
   </header>
@@ -94,7 +94,7 @@ <h1 class="hero-title">explore.js: Query the Materialized Graph</h1>
     <section class="section-block">
       <h2 class="section-title">Setup</h2>
       <p class="section-body">This example re-opens the graph created in setup.js in read-only mode and demonstrates how to query nodes, properties, and neighbors.</p>
-      <p class="section-body">Run it with <code>node explore.js</code> after setup.js has created the graph.</p>
+      <p class="section-body">Run it with <code>node scripts/explore.js</code> after setup.js has created the graph.</p>
     </section>
 
     <section class="graph-grid">

diff --git a/examples/html/inspect-index.html b/examples/html/inspect-index.html
@@ -39,14 +39,14 @@
       <div class="menu-panel-content">
       <div class="menu-title">Examples</div>
       <div class="menu-links">
-        <a href="setup.html">setup.js</a>
-        <a href="explore.html">explore.js</a>
-        <a href="multi-writer.html">multi-writer.js</a>
-        <a href="event-sourcing.html">event-sourcing.js</a>
-        <a href="lagrangian-path.html">lagrangian-path.js</a>
-        <a href="traversal-benchmark.html">traversal-benchmark.js</a>
-        <a href="streaming-benchmark.html">streaming-benchmark.js</a>
-        <a href="inspect-index.html">inspect-index.js</a>
+        <a href="setup.html">scripts/setup.js</a>
+        <a href="explore.html">scripts/explore.js</a>
+        <a href="multi-writer.html">scripts/multi-writer.js</a>
+        <a href="event-sourcing.html">scripts/event-sourcing.js</a>
+        <a href="lagrangian-path.html">scripts/lagrangian-path.js</a>
+        <a href="traversal-benchmark.html">scripts/traversal-benchmark.js</a>
+        <a href="streaming-benchmark.html">scripts/streaming-benchmark.js</a>
+        <a href="inspect-index.html">scripts/inspect-index.js</a>
       </div>
       <div class="menu-section">
         <label class="theme-label" for="theme-select">Theme</label>
@@ -84,7 +84,7 @@ <h1 class="hero-title">inspect-index.js: Checkpoint Anatomy</h1>
     </div>
     <div class="hero-meta">
       <strong>Run it</strong>
-      <p>CREATE_CHECKPOINT=1 node inspect-index.js</p>
+      <p>CREATE_CHECKPOINT=1 node scripts/inspect-index.js</p>
       <p>Creates a checkpoint if one does not exist.</p>
     </div>
   </header>
@@ -94,7 +94,7 @@ <h1 class="hero-title">inspect-index.js: Checkpoint Anatomy</h1>
     <section class="section-block">
       <h2 class="section-title">Setup</h2>
       <p class="section-body">Inspect checkpoints and the serialized blobs that let materialize resume without replaying every patch.</p>
-      <p class="section-body">Run it with <code>node inspect-index.js</code> to build and decode a checkpoint.</p>
+      <p class="section-body">Run it with <code>node scripts/inspect-index.js</code> to build and decode a checkpoint.</p>
     </section>
 
     <section class="graph-grid">

diff --git a/examples/html/lagrangian-path.html b/examples/html/lagrangian-path.html
@@ -39,14 +39,14 @@
       <div class="menu-panel-content">
       <div class="menu-title">Examples</div>
       <div class="menu-links">
-        <a href="setup.html">setup.js</a>
-        <a href="explore.html">explore.js</a>
-        <a href="multi-writer.html">multi-writer.js</a>
-        <a href="event-sourcing.html">event-sourcing.js</a>
-        <a href="lagrangian-path.html">lagrangian-path.js</a>
-        <a href="traversal-benchmark.html">traversal-benchmark.js</a>
-        <a href="streaming-benchmark.html">streaming-benchmark.js</a>
-        <a href="inspect-index.html">inspect-index.js</a>
+        <a href="setup.html">scripts/setup.js</a>
+        <a href="explore.html">scripts/explore.js</a>
+        <a href="multi-writer.html">scripts/multi-writer.js</a>
+        <a href="event-sourcing.html">scripts/event-sourcing.js</a>
+        <a href="lagrangian-path.html">scripts/lagrangian-path.js</a>
+        <a href="traversal-benchmark.html">scripts/traversal-benchmark.js</a>
+        <a href="streaming-benchmark.html">scripts/streaming-benchmark.js</a>
+        <a href="inspect-index.html">scripts/inspect-index.js</a>
       </div>
       <div class="menu-section">
         <label class="theme-label" for="theme-select">Theme</label>
@@ -84,7 +84,7 @@ <h1 class="hero-title">lagrangian-path.js: Weighted Shortest Path</h1>
     </div>
     <div class="hero-meta">
       <strong>Run it</strong>
-      <p>node lagrangian-path.js</p>
+      <p>node scripts/lagrangian-path.js</p>
       <p>Demonstrates resource-aware routing over WARP state.</p>
     </div>
   </header>
@@ -94,7 +94,7 @@ <h1 class="hero-title">lagrangian-path.js: Weighted Shortest Path</h1>
     <section class="section-block">
       <h2 class="section-title">Setup</h2>
       <p class="section-body">Build a weighted graph and run shortest-path searches. Edge properties become costs, so traversal optimizes for resources.</p>
-      <p class="section-body">Run it with <code>node lagrangian-path.js</code> to build the graph and compute paths.</p>
+      <p class="section-body">Run it with <code>node scripts/lagrangian-path.js</code> to build the graph and compute paths.</p>
     </section>
 
     <section class="graph-grid">