diff --git a/README.md b/README.md
index 561c9b6..b4e3223 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,14 @@ greeting:1-2
Bobbin found a parsed function, with its source range, in the index you just built.
See the [quick start](https://scbrown.github.io/bobbin/getting-started/quick-start.html) for semantic search.
+
+
+This 20-second recording uses a small local Python fixture. Semantic search
+finds the invoice-total function; context returns its source. The optional
+graph store is unavailable, and the recording retains that warning.
+[Read the transcript](docs/demos/terminal/transcript.txt) or
+[reproduce the recording](docs/demos/terminal.md).
+
## On your own code
Run `bobbin init` and `bobbin index` from your repository first.
diff --git a/docs/demos/terminal.md b/docs/demos/terminal.md
new file mode 100644
index 0000000..1686268
--- /dev/null
+++ b/docs/demos/terminal.md
@@ -0,0 +1,32 @@
+# Find code by meaning, then read its context
+
+This recording runs native Bobbin 0.36.1 at commit
+`667a680d393c0d9e5347af7fc9d71472c00a494e` against a local public Python fixture.
+The manifest pins the executable and every input. Semantic search returns
+`calculate_total`; context displays its three source lines. The optional Quipu
+store is unavailable, so its single warning remains visible. This does not
+claim graph ranking occurred.
+
+The two reading holds total 20 seconds. Actual command execution durations
+are recorded separately. The static transcript is an accessible fallback;
+the last SVG frame remains visible when animation is disabled.
+
+The vendored renderer is byte-identical to Tambo's shared recorder at
+`b0765b5d8f16a6a26acb3595552f17826d965b44`,
+SHA-256 `bebbe000565314f18a58731f2a1a4690577db127b3673fa10a45ce74eef0f23c`.
+It refuses possible private paths and credentials rather than filtering output.
+
+## Reproduce
+
+Use Python 3, the recorded Bobbin version and a compatible ONNX runtime.
+Prepare a new, absent workspace with the helper. It creates an isolated HOME
+and index, and indexing may download the embedding model. It does not install
+hooks or connect to a graph.
+
+```sh
+python3 docs/demos/terminal/prepare.py /tmp/bobbin-terminal-demo --tool "$(command -v bobbin)"
+python3 docs/demos/terminal/render.py docs/demos/terminal/demo.tape.json --workspace /tmp/bobbin-terminal-demo --tool bobbin="$(command -v bobbin)" --output /tmp/bobbin-terminal-render
+```
+
+The fixture and model cache stay inside that disposable workspace. No existing
+index or user configuration is read. Use a fresh directory for each capture.
diff --git a/docs/demos/terminal/demo.cast b/docs/demos/terminal/demo.cast
new file mode 100644
index 0000000..bda02fd
--- /dev/null
+++ b/docs/demos/terminal/demo.cast
@@ -0,0 +1,3 @@
+{"version": 2, "width": 65, "height": 14, "title": "Bobbin | find code and assemble context", "env": {"TERM": "dumb"}}
+[0.0, "o", "\u001b[2J\u001b[H$ bobbin search 'calculate invoice total' --mode semantic --limit\r\n 2\r\n\u2713 Found 1 results for: calculate invoice total (semantic)\r\n\r\n1. totals.py:1 (calculate_total)\r\n [totals-example] function python \u00b7 lines 1-3 \u00b7 score 0.6736\r\n"]
+[10.0, "o", "\u001b[2J\u001b[H$ bobbin context 'calculate invoice total' --budget 40\r\n\u2713 Context for: calculate invoice total\r\n 1 files, 1 chunks (3/40 lines)\r\n\r\n--- totals.py [direct, score: 1.0000] ---\r\n calculate_total (function), lines 1-3\r\n def calculate_total(amounts):\r\n \"\"\"Calculate the total amount for an invoice.\"\"\"\r\n return sum(amounts)\r\n\r\n ! PPR enabled but Quipu store unavailable; continuing without \r\ngraph ranking. Use --verbose for details.\r\n"]
diff --git a/docs/demos/terminal/demo.svg b/docs/demos/terminal/demo.svg
new file mode 100644
index 0000000..c0dd030
--- /dev/null
+++ b/docs/demos/terminal/demo.svg
@@ -0,0 +1,34 @@
+
diff --git a/docs/demos/terminal/demo.tape.json b/docs/demos/terminal/demo.tape.json
new file mode 100644
index 0000000..e2e0934
--- /dev/null
+++ b/docs/demos/terminal/demo.tape.json
@@ -0,0 +1,46 @@
+{
+ "title": "Bobbin | find code and assemble context",
+ "description": "Native semantic retrieval and context from a small local Python fixture; optional graph ranking is unavailable.",
+ "width": 1100,
+ "height": 700,
+ "font_size": 24,
+ "line_height": 32,
+ "inputs": [
+ "totals.py"
+ ],
+ "steps": [
+ {
+ "tool": "bobbin",
+ "args": [
+ "search",
+ "calculate invoice total",
+ "--mode",
+ "semantic",
+ "--limit",
+ "2"
+ ],
+ "requires": [
+ "calculate_total",
+ "semantic"
+ ],
+ "hold": 10,
+ "timeout": 120
+ },
+ {
+ "tool": "bobbin",
+ "args": [
+ "context",
+ "calculate invoice total",
+ "--budget",
+ "40"
+ ],
+ "requires": [
+ "calculate_total",
+ "graph ranking"
+ ],
+ "allow_stderr": true,
+ "hold": 10,
+ "timeout": 120
+ }
+ ]
+}
diff --git a/docs/demos/terminal/fixture/totals.py b/docs/demos/terminal/fixture/totals.py
new file mode 100644
index 0000000..0da14c6
--- /dev/null
+++ b/docs/demos/terminal/fixture/totals.py
@@ -0,0 +1,3 @@
+def calculate_total(amounts):
+ """Calculate the total amount for an invoice."""
+ return sum(amounts)
diff --git a/docs/demos/terminal/manifest.json b/docs/demos/terminal/manifest.json
new file mode 100644
index 0000000..effda28
--- /dev/null
+++ b/docs/demos/terminal/manifest.json
@@ -0,0 +1,57 @@
+{
+ "theme": "stack-terminal-24",
+ "versions": {
+ "bobbin": "bobbin 0.36.1 (667a680d393c0d9e5347af7fc9d71472c00a494e)"
+ },
+ "binary_sha256": {
+ "bobbin": "d56bd5e01a82b64269c106f0b68692dc6c225bc12ad9bafb24dce1c61be57937"
+ },
+ "version_args": {
+ "bobbin": [
+ "--version"
+ ]
+ },
+ "inputs_sha256": {
+ "render.py": "bebbe000565314f18a58731f2a1a4690577db127b3673fa10a45ce74eef0f23c",
+ "tape": "e97f346a9ebb25a1ae7f8896e6c51b7e34400558acffce1c23f2e332e62cd3f2",
+ "totals.py": "8b22236231ed7b92250a818a749d26334e3201f87d28a9e6bcdb38ebdec7ea19"
+ },
+ "duration_seconds": 20.0,
+ "timeline": "deliberate reading holds; execution times recorded separately",
+ "frames_checked": 2,
+ "commands": [
+ {
+ "tool": "bobbin",
+ "args": [
+ "search",
+ "calculate invoice total",
+ "--mode",
+ "semantic",
+ "--limit",
+ "2"
+ ],
+ "exit": 0,
+ "seconds": 0.261712,
+ "stdout": "\u2713 Found 1 results for: calculate invoice total (semantic)\n\n1. totals.py:1 (calculate_total)\n [totals-example] function python \u00b7 lines 1-3 \u00b7 score 0.6736\n\n",
+ "stderr": ""
+ },
+ {
+ "tool": "bobbin",
+ "args": [
+ "context",
+ "calculate invoice total",
+ "--budget",
+ "40"
+ ],
+ "exit": 0,
+ "seconds": 0.214701,
+ "stdout": "\u2713 Context for: calculate invoice total\n 1 files, 1 chunks (3/40 lines)\n\n--- totals.py [direct, score: 1.0000] ---\n calculate_total (function), lines 1-3\n def calculate_total(amounts):\n \"\"\"Calculate the total amount for an invoice.\"\"\"\n return sum(amounts)\n\n",
+ "stderr": " ! PPR enabled but Quipu store unavailable; continuing without graph ranking. Use --verbose for details.\n"
+ }
+ ],
+ "sha256": {
+ "demo.svg": "39c22eb226479048e1bc5bc88c1f6e586907fe8ec8f4e3f6c78e5b76cb5152bf",
+ "transcript.txt": "f7fe87d60b1901e95f97761bc49d15b4c1a62d167c112e743e607b7b289955bc",
+ "demo.cast": "d955fc73c73534f684e19471b0995807d6f95f04446cceac9014685d165219fb"
+ }
+}
diff --git a/docs/demos/terminal/prepare.py b/docs/demos/terminal/prepare.py
new file mode 100644
index 0000000..ae2bafe
--- /dev/null
+++ b/docs/demos/terminal/prepare.py
@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Prepare a disposable index and model cache for the terminal recorder."""
+import argparse
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("workspace", type=Path)
+ parser.add_argument("--tool", type=Path, required=True)
+ args = parser.parse_args()
+ tool = args.tool.resolve(strict=True)
+ root = args.workspace.resolve()
+ root.mkdir() # Refuse an existing workspace rather than reuse its state.
+ home = root / ".demo-home"
+ home.mkdir()
+ shutil.copyfile(Path(__file__).parent / "fixture/totals.py", root / "totals.py")
+ (root / ".terminal-demo-sandbox").write_text("disposable terminal fixture\n")
+ env = {
+ "PATH": str(tool.parent) + os.pathsep + os.defpath,
+ "HOME": str(home),
+ "XDG_CONFIG_HOME": str(home / ".config"),
+ "XDG_CACHE_HOME": str(home / ".cache"),
+ "XDG_STATE_HOME": str(home / ".state"),
+ "TMPDIR": str(root),
+ "LANG": "C.UTF-8",
+ "TERM": "dumb",
+ "NO_COLOR": "1",
+ "RUST_LOG": "off",
+ "BOBBIN_GPU": "0",
+ }
+ for command in [
+ ["init", ".", "--quiet"],
+ ["index", ".", "--repo", "totals-example", "--no-quipu-publish", "--skip-calibrate", "--quiet"],
+ ]:
+ subprocess.run([str(tool), *command], cwd=root, env=env, check=True)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/demos/terminal/render.py b/docs/demos/terminal/render.py
new file mode 100644
index 0000000..9afe7fa
--- /dev/null
+++ b/docs/demos/terminal/render.py
@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Record real local CLI output and render a self-contained animated SVG."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import html
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import time
+import shlex
+import textwrap
+import xml.etree.ElementTree as ET
+
+HERE = Path(__file__).resolve().parent
+FORBIDDEN = [
+ r"/(?:home|Users|root|srv|run)/",
+ r"\b[\w.-]+\.(?:lan|svc|internal|local)\b",
+ r"\b(?:\d{1,3}\.){3}\d{1,3}\b",
+ r"\b(?:[0-9a-fA-F]{1,4}:){2,}[0-9a-fA-F:]+\b",
+ r"(?i)\bbearer\s+\S+",
+ r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
+ r"(?i)(?:token|password|secret)\s*[=:]\s*\S+",
+]
+
+
+def check_text(text: str, *, identifiers: bool = True) -> None:
+ """Refuse, never redact a recording into a claimed successful command."""
+ if any(re.search(pattern, text) for pattern in FORBIDDEN):
+ raise ValueError("recording refused: possible private data")
+ if any(ord(char) < 32 and char not in "\n\r\t" for char in text):
+ raise ValueError("recording refused: unsupported terminal control")
+ # Reject crew work-item prefixes while allowing public CLI flag names.
+ if identifiers and re.search(r"\b(?:aegis|na)-[a-z0-9]+(?:\.\d+)*\b", text):
+ raise ValueError("recording refused: possible work item identifier")
+
+
+
+def render_svg(tape: dict, frames: list[dict], duration: float) -> str:
+ width, height = tape["width"], tape["height"]
+ title = html.escape(tape["title"])
+ pieces = [
+ f'')
+ return "\n".join(pieces) + "\n"
+
+
+def digest(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("tape", type=Path)
+ parser.add_argument("--workspace", type=Path, required=True,
+ help="prepared PRIVATE sandbox; commands may write here")
+ parser.add_argument("--tool", action="append", default=[], metavar="NAME=PATH")
+ parser.add_argument("--output", type=Path, required=True)
+ args = parser.parse_args()
+ tape = json.loads(args.tape.read_text())
+ if tape["font_size"] != 24 or not 1 <= len(tape["steps"]) <= 12:
+ raise ValueError("use the shared 24px theme and at most twelve steps")
+ tools = dict(value.split("=", 1) for value in args.tool)
+ binaries = {name: Path(path).resolve(strict=True) for name, path in tools.items()}
+ root = args.workspace.resolve(strict=True)
+ if not (root / ".terminal-demo-sandbox").is_file():
+ raise ValueError("workspace needs an explicit .terminal-demo-sandbox marker")
+ home = root / ".demo-home"
+ home.mkdir(exist_ok=True)
+ # Never inherit endpoints, tokens, user configuration or tool search paths.
+ env = {"PATH": os.pathsep.join(dict.fromkeys(
+ [str(p.parent) for p in binaries.values()] + [os.defpath])),
+ "HOME": str(home), "XDG_CONFIG_HOME": str(home / ".config"),
+ "XDG_CACHE_HOME": str(home / ".cache"),
+ "XDG_STATE_HOME": str(home / ".state"), "TMPDIR": str(root),
+ "LANG": "C.UTF-8", "TERM": "dumb", "NO_COLOR": "1", "RUST_LOG": "off",
+ "BOBBIN_GPU": "0"}
+ binary_hashes = {name: digest(path) for name, path in binaries.items()}
+ version_args = {name: tape.get("version_args", {}).get(name, ["--version"])
+ for name in binaries}
+ versions = {name: subprocess.check_output([str(path), *version_args[name]], env=env,
+ text=True, timeout=10).strip() for name, path in binaries.items()}
+ frames, events, runs, transcript = [], [], [], []
+ elapsed = 0.0
+ for step in tape["steps"]:
+ name = step["tool"]
+ command = "$ " + shlex.join([name, *step["args"]])
+ stdin = None
+ if "stdin" in step:
+ input_path = (root / step["stdin"]).resolve(strict=True)
+ input_path.relative_to(root)
+ stdin = input_path.read_text()
+ command += " < " + shlex.quote(step["stdin"])
+ check_text(command)
+ start = time.monotonic()
+ result = subprocess.run([str(binaries[name]), *step["args"]], cwd=root,
+ env=env, input=stdin, capture_output=True,
+ text=True, timeout=step.get("timeout", 30))
+ seconds = time.monotonic() - start
+ check_text(result.stdout + result.stderr)
+ if result.returncode != step.get("exit", 0):
+ raise RuntimeError("unexpected command exit; no render published")
+ if result.stderr and not step.get("allow_stderr", False):
+ raise RuntimeError("unexpected stderr; no render published")
+ body = result.stdout + result.stderr
+ for required in step.get("requires", []):
+ if required not in body:
+ raise RuntimeError("required output absent; no render published")
+ transcript.extend([command, body.rstrip(), f"[exit {result.returncode}]"])
+ # Page complete output, never ellipsize or silently discard a line.
+ lines = []
+ for line in (command + "\n" + body.rstrip()).splitlines():
+ lines.extend(textwrap.wrap(line, width=65, replace_whitespace=False,
+ drop_whitespace=False) or [""])
+ pages = [lines[i:i + 14] for i in range(0, len(lines), 14)]
+ for page in pages:
+ check_text("\n".join(page))
+ frames.append({"at": elapsed, "lines": page})
+ events.append([elapsed, "o", "\x1b[2J\x1b[H" + "\r\n".join(page) + "\r\n"])
+ elapsed += step.get("hold", 5) / len(pages)
+ runs.append({"tool": name, "args": step["args"], "exit": result.returncode,
+ "seconds": round(seconds, 6), "stdout": result.stdout,
+ "stderr": result.stderr})
+ if not 10 <= elapsed <= 30:
+ raise ValueError("reading timeline must be 10 to 30 seconds")
+ svg = render_svg(tape, frames, elapsed)
+ ET.fromstring(svg)
+ check_text(svg, identifiers=False)
+ cast = {"version": 2, "width": 65, "height": 14, "title": tape["title"],
+ "env": {"TERM": "dumb"}}
+ artifacts = {"demo.svg": svg, "transcript.txt": "\n".join(transcript) + "\n",
+ "demo.cast": json.dumps(cast) + "\n" + "\n".join(
+ json.dumps(event) for event in events) + "\n"}
+ for name, body in artifacts.items():
+ check_text(body, identifiers=name != "demo.svg")
+ inputs = {"render.py": digest(Path(__file__)), "tape": digest(args.tape)}
+ for name in tape.get("inputs", []):
+ path = (root / name).resolve(strict=True)
+ path.relative_to(root)
+ inputs[name] = digest(path)
+ if binary_hashes != {name: digest(path) for name, path in binaries.items()}:
+ raise RuntimeError("tool bytes changed during capture; no render published")
+ manifest = {"theme": "stack-terminal-24", "versions": versions,
+ "binary_sha256": binary_hashes, "version_args": version_args,
+ "inputs_sha256": inputs, "duration_seconds": elapsed,
+ "timeline": "deliberate reading holds; execution times recorded separately",
+ "frames_checked": len(frames), "commands": runs,
+ "sha256": {n: hashlib.sha256(b.encode()).hexdigest()
+ for n, b in artifacts.items()}}
+ args.output.mkdir(parents=True, exist_ok=True)
+ for name, body in artifacts.items():
+ (args.output / name).write_text(body)
+ (args.output / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+ print(json.dumps({"frames_checked": len(frames), "duration": elapsed,
+ "svg_sha256": manifest["sha256"]["demo.svg"]}))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/demos/terminal/transcript.txt b/docs/demos/terminal/transcript.txt
new file mode 100644
index 0000000..76849e0
--- /dev/null
+++ b/docs/demos/terminal/transcript.txt
@@ -0,0 +1,18 @@
+$ bobbin search 'calculate invoice total' --mode semantic --limit 2
+✓ Found 1 results for: calculate invoice total (semantic)
+
+1. totals.py:1 (calculate_total)
+ [totals-example] function python · lines 1-3 · score 0.6736
+[exit 0]
+$ bobbin context 'calculate invoice total' --budget 40
+✓ Context for: calculate invoice total
+ 1 files, 1 chunks (3/40 lines)
+
+--- totals.py [direct, score: 1.0000] ---
+ calculate_total (function), lines 1-3
+ def calculate_total(amounts):
+ """Calculate the total amount for an invoice."""
+ return sum(amounts)
+
+ ! PPR enabled but Quipu store unavailable; continuing without graph ranking. Use --verbose for details.
+[exit 0]
diff --git a/docs/knowledge/repository-knowledge.json b/docs/knowledge/repository-knowledge.json
index 6447afd..6c02953 100644
--- a/docs/knowledge/repository-knowledge.json
+++ b/docs/knowledge/repository-knowledge.json
@@ -109,7 +109,7 @@
"source": "README.md",
"subject": "http://aegis.gastown.local/ontology/doc/bobbin/README.md",
"summary": "Start with installation and the first successful search, then read architecture and contributor guidance.",
- "source_sha256": "53ac24ef95c0f5aa4cfcda826df06732e3f722f912eb5914d3837048dd6659cb",
+ "source_sha256": "883e46dc9528c956edee68abbfd55cb28c6813e5a545ea15e8a29e887814e7ca",
"properties": {
"startHereOrder": "1"
}