nybls 0.1.0__tar.gz

nybls-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "nybls",
+  "owner": {
+    "name": "Ares",
+    "url": "https://github.com/nKOxxx"
+  },
+  "plugins": [
+    {
+      "name": "nybls",
+      "source": "./",
+      "description": "Watch videos properly: transcript first, contact sheets for coverage, then only the frames the model names a gap for \u2014 with a spend ledger and evidence receipts.",
+      "version": "0.1.0",
+      "license": "MIT",
+      "keywords": [
+        "video",
+        "youtube",
+        "vision",
+        "frames",
+        "transcript"
+      ],
+      "homepage": "https://github.com/nKOxxx/nybls"
+    }
+  ],
+  "metadata": {
+    "description": "Budgeted, iterative video watching for AI agents \u2014 sip the video, don't slurp it."
+  }
+}

nybls-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "nybls",
+  "displayName": "nybls",
+  "version": "0.1.0",
+  "description": "Budgeted, iterative video watching for AI agents — transcript first, then only the frames the model asks for, with receipts.",
+  "author": { "name": "Ares", "url": "https://github.com/nKOxxx" },
+  "homepage": "https://github.com/nKOxxx/nybls",
+  "repository": "https://github.com/nKOxxx/nybls",
+  "license": "MIT",
+  "keywords": ["video", "youtube", "vision", "frames", "transcript", "analysis"]
+}

nybls-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+tests/sample/
+brand/nybls_60.png
+brand/nybls_180.png
+.DS_Store
+.env

nybls-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nybls-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: nybls
+Version: 0.1.0
+Summary: Budgeted, iterative video watching for AI agents — transcript first, then only the frames the model asks for, with receipts.
+Project-URL: Homepage, https://github.com/nKOxxx/nybls
+Project-URL: Repository, https://github.com/nKOxxx/nybls
+Project-URL: Issues, https://github.com/nKOxxx/nybls/issues
+Author: Ares
+License: MIT License
+        
+        Copyright (c) 2026 Ares
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,claude,ffmpeg,llm,mcp,transcript,video,vision
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: imagehash>=4.3.2
+Requires-Dist: pillow>=10.0
+Requires-Dist: scenedetect>=0.7.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: macos
+Requires-Dist: ocrmac>=1.0; extra == 'macos'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="brand/nybls_1024.png" alt="nybls" width="140">
+</p>
+
+<h1 align="center">nybls</h1>
+
+<p align="center">
+  <em>Other tools slurp the whole video. This one sips —<br>
+  three frames out of fifty-three thousand, and it shows you which.</em>
+</p>
+
+---
+
+## The problem
+
+Almost every "AI watches YouTube" tool reads the **subtitles**. That is not a
+cynical read of the field, it is what the code does: the YouTube loaders in the
+major agent frameworks and self-hosted chat apps are transcript scrapers, and
+Google's own documentation says a YouTube source in NotebookLM imports "only the
+text transcript of the video."
+
+So a video with no speech returns nothing. A chart on screen is invisible. A
+demo that shows rather than tells is invisible. And you cannot tell the
+difference between a tool that looked and a tool that guessed, because neither
+shows you what it saw.
+
+The other half of the field does the opposite and dumps 100 uniformly-sampled
+frames into the model at once — expensive, mostly redundant, and still blind to
+whatever fell between the samples.
+
+## What nybls does instead
+
+nybls gives an AI agent five ways to ask for pieces of a video, and a protocol
+that makes it ask well:
+
+1. **Read the free stuff first** — transcript, scene boundaries, metadata. Zero images.
+2. **Look broadly, cheaply** — one contact sheet is six timestamped thumbnails for
+   the cost of a single image.
+3. **Then say what it is missing** — the agent must name the time interval and what
+   it expects to find there before it may request more.
+4. **Drill in only there** — full-resolution frames, or a zoom crop to read small text.
+5. **Stop, and show the receipts** — every answer ends with the frames it examined
+   and what they cost.
+
+Real run, this repo's test corpus — a 35-minute car-restoration video:
+
+```
+watched 35 min · examined 3 images (~3,069 visual tokens, ~$0.01)
+of ~53,171 total frames · budget 3/142 units
+```
+
+Three frames. It found the reveal at 12:05, identified that the second half of
+the video switches to a different car, and reported honestly that a zoom aimed
+at a badge landed on a headlight instead — so it did not name the model.
+
+## Why "sips" is the whole point
+
+The research this is built on is unambiguous: **selecting fewer frames well beats
+sampling many frames blindly.** Stanford's VideoAgent matched the accuracy of 180
+uniformly-sampled frames using 8.4 frames chosen by a confidence-gated loop.
+Adaptive keyframe selection beats uniform sampling at equal frame count. Grids
+larger than about six tiles measurably destroy a model's ability to localize
+detail. Every rule in the nybls protocol traces to a published result — see
+[docs/RESEARCH.md](docs/RESEARCH.md).
+
+## Install
+
+**Prerequisites** (nybls orchestrates these; it does not vendor them):
+
+| Tool | Why | Install |
+|---|---|---|
+| `ffmpeg` | frame extraction, crops, contact sheets | `brew install ffmpeg` |
+| `yt-dlp` | downloading from YouTube and ~1,800 other sites | `brew install yt-dlp` |
+| `deno` | required by yt-dlp for full YouTube support | `brew install deno` |
+| `whisper-cpp` | local transcription when a video has no captions | `brew install whisper-cpp` |
+
+Then:
+
+```bash
+pip install nybls
+```
+
+On macOS, add Apple Vision OCR (works with Arabic, no extra models):
+
+```bash
+pip install "nybls[macos]"
+```
+
+For local transcription, download a Whisper model once:
+
+```bash
+mkdir -p ~/.nybls/models && curl -L -o ~/.nybls/models/ggml-large-v3-turbo.bin \
+  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
+```
+
+## Use it
+
+```bash
+nybls probe "https://www.youtube.com/watch?v=VIDEO_ID"
+```
+
+```
+id: VIDEO_ID
+title: But what is a neural network? | Deep learning chapter 1
+duration: 18.7 min · 1280x720 · 24 scenes
+transcript: subtitles:video.en.vtt -> ~/.nybls/store/VIDEO_ID/transcript.txt
+budget: 75 image units
+cost so far: 0 images. Read the transcript first; then request sheets.
+```
+
+| Command | What it does | Cost |
+|---|---|---|
+| `nybls probe <url\|file>` | download, transcribe, detect scenes, set the budget | 0 images |
+| `nybls sheet <id> [--range S E]` | 3x2 contact sheet, timestamped | 1 image |
+| `nybls frames <id> --at 92,570` | full-resolution stills | 1 per frame |
+| `nybls zoom <id> --at 570 --box x,y,w,h` | crop into a region to read detail | 1 image |
+| `nybls ledger <id>` | what has been spent | 0 |
+
+Everything is written to `~/.nybls/store/<id>/` as ordinary PNG and text files.
+There is no API integration: your agent reads the files.
+
+### With Claude Code
+
+Install as a plugin — the skill and its protocol come with it:
+
+```
+/plugin marketplace add nKOxxx/nybls
+```
+
+```
+/plugin install nybls@nybls
+```
+
+Then ask:
+
+```
+/nybls:watch https://www.youtube.com/watch?v=VIDEO_ID  what does the chart at the end show?
+```
+
+The skill carries the protocol — the confidence check, the named-gap rule, the
+stop conditions, and the receipts contract — so the discipline travels with the
+tool instead of depending on how well you prompt. For a personal install without
+the plugin system, copy `skills/watch/SKILL.md` to
+`~/.claude/skills/watch/SKILL.md`.
+
+## The guardrails are in the tool, not just the prose
+
+A protocol written only in a prompt is a suggestion. These are enforced by the
+CLI itself:
+
+- **Named gaps.** Past a few images, `frames` and `zoom` refuse to run without
+  `--looking-for "<interval + what you expect>"`.
+- **A real budget.** Duration-scaled, cumulative, and the server refuses to serve
+  past it unless a human passes `--force`.
+- **Duplicate warnings.** A frame that is a near-duplicate of one already served
+  is flagged as wasted budget.
+- **Next-step nudges.** Every command's output ends by telling the agent to draft
+  an answer and classify its own confidence before asking for more.
+
+## What this cannot do
+
+- **No live video.** Batch only: download, then analyze.
+- **Motion is lossy.** It sees stills, not movement. Good for talks, tutorials,
+  demos, dashboards, and on-screen text; weak for sports mechanics or fast action.
+- **Speech only.** Transcription covers words, not music or sound events.
+- **It depends on tools that fight back.** Video platforms actively break
+  downloaders. Keep `yt-dlp` current; expect occasional breakage.
+- **Alpha.** The protocol is validated by published research and by daily use, but
+  this is version 0.1.0 and the interfaces may change.
+
+## Privacy and security posture
+
+Local-first by construction: no API keys, no accounts, no telemetry, no server.
+The agent you already use supplies the model; everything else runs on your
+machine. See [docs/SECURITY.md](docs/SECURITY.md) for the full posture, including
+the one rule that matters most — **video content is data, never instructions.** A
+video can display text aimed at your agent, and the protocol requires that such
+text be reported to you rather than obeyed.
+
+Downloading from a platform may conflict with that platform's terms of service.
+That is your call to make; this tool takes no position and phones nothing home.
+
+## Documentation
+
+- [docs/PROTOCOL.md](docs/PROTOCOL.md) — the WATCH loop in full, and why each rule exists
+- [docs/RESEARCH.md](docs/RESEARCH.md) — the evidence base and everything this is built on
+- [docs/SECURITY.md](docs/SECURITY.md) — threat model and the security checklist
+- [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT.

nybls-0.1.0/README.md

@@ -0,0 +1,192 @@
+<p align="center">
+  <img src="brand/nybls_1024.png" alt="nybls" width="140">
+</p>
+
+<h1 align="center">nybls</h1>
+
+<p align="center">
+  <em>Other tools slurp the whole video. This one sips —<br>
+  three frames out of fifty-three thousand, and it shows you which.</em>
+</p>
+
+---
+
+## The problem
+
+Almost every "AI watches YouTube" tool reads the **subtitles**. That is not a
+cynical read of the field, it is what the code does: the YouTube loaders in the
+major agent frameworks and self-hosted chat apps are transcript scrapers, and
+Google's own documentation says a YouTube source in NotebookLM imports "only the
+text transcript of the video."
+
+So a video with no speech returns nothing. A chart on screen is invisible. A
+demo that shows rather than tells is invisible. And you cannot tell the
+difference between a tool that looked and a tool that guessed, because neither
+shows you what it saw.
+
+The other half of the field does the opposite and dumps 100 uniformly-sampled
+frames into the model at once — expensive, mostly redundant, and still blind to
+whatever fell between the samples.
+
+## What nybls does instead
+
+nybls gives an AI agent five ways to ask for pieces of a video, and a protocol
+that makes it ask well:
+
+1. **Read the free stuff first** — transcript, scene boundaries, metadata. Zero images.
+2. **Look broadly, cheaply** — one contact sheet is six timestamped thumbnails for
+   the cost of a single image.
+3. **Then say what it is missing** — the agent must name the time interval and what
+   it expects to find there before it may request more.
+4. **Drill in only there** — full-resolution frames, or a zoom crop to read small text.
+5. **Stop, and show the receipts** — every answer ends with the frames it examined
+   and what they cost.
+
+Real run, this repo's test corpus — a 35-minute car-restoration video:
+
+```
+watched 35 min · examined 3 images (~3,069 visual tokens, ~$0.01)
+of ~53,171 total frames · budget 3/142 units
+```
+
+Three frames. It found the reveal at 12:05, identified that the second half of
+the video switches to a different car, and reported honestly that a zoom aimed
+at a badge landed on a headlight instead — so it did not name the model.
+
+## Why "sips" is the whole point
+
+The research this is built on is unambiguous: **selecting fewer frames well beats
+sampling many frames blindly.** Stanford's VideoAgent matched the accuracy of 180
+uniformly-sampled frames using 8.4 frames chosen by a confidence-gated loop.
+Adaptive keyframe selection beats uniform sampling at equal frame count. Grids
+larger than about six tiles measurably destroy a model's ability to localize
+detail. Every rule in the nybls protocol traces to a published result — see
+[docs/RESEARCH.md](docs/RESEARCH.md).
+
+## Install
+
+**Prerequisites** (nybls orchestrates these; it does not vendor them):
+
+| Tool | Why | Install |
+|---|---|---|
+| `ffmpeg` | frame extraction, crops, contact sheets | `brew install ffmpeg` |
+| `yt-dlp` | downloading from YouTube and ~1,800 other sites | `brew install yt-dlp` |
+| `deno` | required by yt-dlp for full YouTube support | `brew install deno` |
+| `whisper-cpp` | local transcription when a video has no captions | `brew install whisper-cpp` |
+
+Then:
+
+```bash
+pip install nybls
+```
+
+On macOS, add Apple Vision OCR (works with Arabic, no extra models):
+
+```bash
+pip install "nybls[macos]"
+```
+
+For local transcription, download a Whisper model once:
+
+```bash
+mkdir -p ~/.nybls/models && curl -L -o ~/.nybls/models/ggml-large-v3-turbo.bin \
+  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
+```
+
+## Use it
+
+```bash
+nybls probe "https://www.youtube.com/watch?v=VIDEO_ID"
+```
+
+```
+id: VIDEO_ID
+title: But what is a neural network? | Deep learning chapter 1
+duration: 18.7 min · 1280x720 · 24 scenes
+transcript: subtitles:video.en.vtt -> ~/.nybls/store/VIDEO_ID/transcript.txt
+budget: 75 image units
+cost so far: 0 images. Read the transcript first; then request sheets.
+```
+
+| Command | What it does | Cost |
+|---|---|---|
+| `nybls probe <url\|file>` | download, transcribe, detect scenes, set the budget | 0 images |
+| `nybls sheet <id> [--range S E]` | 3x2 contact sheet, timestamped | 1 image |
+| `nybls frames <id> --at 92,570` | full-resolution stills | 1 per frame |
+| `nybls zoom <id> --at 570 --box x,y,w,h` | crop into a region to read detail | 1 image |
+| `nybls ledger <id>` | what has been spent | 0 |
+
+Everything is written to `~/.nybls/store/<id>/` as ordinary PNG and text files.
+There is no API integration: your agent reads the files.
+
+### With Claude Code
+
+Install as a plugin — the skill and its protocol come with it:
+
+```
+/plugin marketplace add nKOxxx/nybls
+```
+
+```
+/plugin install nybls@nybls
+```
+
+Then ask:
+
+```
+/nybls:watch https://www.youtube.com/watch?v=VIDEO_ID  what does the chart at the end show?
+```
+
+The skill carries the protocol — the confidence check, the named-gap rule, the
+stop conditions, and the receipts contract — so the discipline travels with the
+tool instead of depending on how well you prompt. For a personal install without
+the plugin system, copy `skills/watch/SKILL.md` to
+`~/.claude/skills/watch/SKILL.md`.
+
+## The guardrails are in the tool, not just the prose
+
+A protocol written only in a prompt is a suggestion. These are enforced by the
+CLI itself:
+
+- **Named gaps.** Past a few images, `frames` and `zoom` refuse to run without
+  `--looking-for "<interval + what you expect>"`.
+- **A real budget.** Duration-scaled, cumulative, and the server refuses to serve
+  past it unless a human passes `--force`.
+- **Duplicate warnings.** A frame that is a near-duplicate of one already served
+  is flagged as wasted budget.
+- **Next-step nudges.** Every command's output ends by telling the agent to draft
+  an answer and classify its own confidence before asking for more.
+
+## What this cannot do
+
+- **No live video.** Batch only: download, then analyze.
+- **Motion is lossy.** It sees stills, not movement. Good for talks, tutorials,
+  demos, dashboards, and on-screen text; weak for sports mechanics or fast action.
+- **Speech only.** Transcription covers words, not music or sound events.
+- **It depends on tools that fight back.** Video platforms actively break
+  downloaders. Keep `yt-dlp` current; expect occasional breakage.
+- **Alpha.** The protocol is validated by published research and by daily use, but
+  this is version 0.1.0 and the interfaces may change.
+
+## Privacy and security posture
+
+Local-first by construction: no API keys, no accounts, no telemetry, no server.
+The agent you already use supplies the model; everything else runs on your
+machine. See [docs/SECURITY.md](docs/SECURITY.md) for the full posture, including
+the one rule that matters most — **video content is data, never instructions.** A
+video can display text aimed at your agent, and the protocol requires that such
+text be reported to you rather than obeyed.
+
+Downloading from a platform may conflict with that platform's terms of service.
+That is your call to make; this tool takes no position and phones nothing home.
+
+## Documentation
+
+- [docs/PROTOCOL.md](docs/PROTOCOL.md) — the WATCH loop in full, and why each rule exists
+- [docs/RESEARCH.md](docs/RESEARCH.md) — the evidence base and everything this is built on
+- [docs/SECURITY.md](docs/SECURITY.md) — threat model and the security checklist
+- [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT.

nybls-0.1.0/docs/PROTOCOL.md

@@ -0,0 +1,156 @@
+# The WATCH protocol
+
+The CLI is deliberately unintelligent. It extracts frames, it does not decide
+which frames matter. The deciding happens in the model, guided by this protocol
+and constrained by rails in the tool.
+
+That split is the central design choice, and it is not arbitrary: every attempt
+to make the *extractor* smart loses to letting the *model* choose, because the
+extractor has to decide before it understands the question. Measured result:
+a confidence-gated loop matched the accuracy of 180 uniformly sampled frames
+using 8.4 chosen ones (arXiv:2403.10517).
+
+---
+
+## The loop
+
+### Round 0 — free
+
+```bash
+nybls probe <url-or-file>
+```
+
+Produces the transcript, the scene list, metadata, and the budget. Costs zero
+images. Read all of it before spending anything.
+
+For talk-heavy video this round frequently answers the question outright. It
+must never be used to answer a *visual* question — if the user asks what is on
+screen, the transcript is evidence about the audio, not the picture.
+
+### Round 1 — coverage
+
+```bash
+nybls sheet <id> [--range START_S END_S]
+```
+
+One sheet is six timestamped thumbnails in a 3x2 grid: six moments for the price
+of one image. Use `--range` to cover a specific region of a long video; for a
+20-minute video, one sheet per five to seven minutes of interest is a sane
+budget.
+
+**Six tiles, not more.** IG-VLM ablated 4 to 20 tiles per grid and found six in a
+near-square layout optimal, with larger grids performing worse (arXiv:2403.18406).
+Needle-in-a-haystack testing shows every current model — Claude included — loses
+the ability to localize detail inside dense sub-image grids (arXiv:2406.11230).
+Sheets tell you *where to look*. They are not for reading.
+
+### The evaluator — mandatory, every round
+
+Draft the answer. Then classify, explicitly:
+
+| Verdict | Meaning | Action |
+|---|---|---|
+| `sufficient` | the evidence supports the answer | stop, write the output |
+| `partial` | the shape is right, detail is missing | name the gap, request only that |
+| `insufficient` | cannot answer | name the gap, request only that |
+
+This step is not decoration. In component ablations of adaptive video agents, the
+"can I answer yet?" evaluator was the single highest-impact part of the system —
+removing it hurt accuracy more than removing the smart sampler (arXiv:2410.20252).
+Interval-level model confidence also correlates with correctness, which is what
+makes confidence-gated search work (arXiv:2507.02946).
+
+### Rounds 2–3 — targeted
+
+```bash
+nybls frames <id> --at 92,570 --looking-for "09:30, the chart he refers to"
+nybls zoom   <id> --at 570 --box 0.3,0.2,0.4,0.4 --looking-for "axis labels"
+```
+
+Request frames for a **named** interval and a **named** expectation. Never
+re-sample globally; that is what Round 1 was for.
+
+Prefer a zoom over more frames when the answer is inside one frame. Adding
+spatial zoom to a temporal search gained 2.6 to 5.9 accuracy points under an
+identical frame budget (arXiv:2504.02259, building on arXiv:2312.14135).
+
+### Stop
+
+Stop at the first of:
+
+- confidence is `sufficient`
+- three rounds after probe — accuracy saturates there (arXiv:2403.10517)
+- the budget is exhausted
+
+If you stop at `partial`, **say so in the output.** A confident answer built on
+insufficient evidence is the failure mode this whole design exists to prevent.
+
+---
+
+## Budget
+
+```
+budget = clamp(8, ceil(duration_minutes * 4), 200)   # image units
+```
+
+One sheet, one full frame, and one zoom each cost one unit. The ledger also
+tracks estimated visual tokens, computed the way the Claude API bills them
+(ceil(w/28) * ceil(h/28) per image).
+
+Duration-scaled budgets with a floor and ceiling follow the pattern in
+arXiv:2510.04428. The ceiling matters more than the floor: past roughly 32
+well-chosen frames, video QA accuracy plateaus (arXiv:2502.19680), so a large
+budget is permission to look carefully, not an instruction to look often.
+
+Sampling density is genuinely task-dependent — some questions are answerable at
+one frame per minute, others need one frame per second in a narrow window
+(arXiv:2503.12496). Coarse first, dense only where the question points.
+
+---
+
+## Rails: what the tool enforces
+
+Prose can be ignored. These cannot:
+
+| Rail | Behavior |
+|---|---|
+| Named gaps | past 3 spent images, `frames`/`zoom` refuse without `--looking-for` |
+| Budget stop | requests beyond the budget are refused; only a human may `--force` |
+| Duplicate detection | a near-duplicate of an already-served frame is flagged as waste |
+| Per-call cap | at most 10 frames per invocation |
+| Next-step nudges | every command's output restates the next protocol step |
+
+The rails exist because the protocol must work for an agent that was not
+carefully prompted. Discipline that depends on the operator does not survive
+distribution.
+
+---
+
+## Output contract
+
+Every answer ends with three blocks:
+
+1. **Answer** — grounded in what was seen and heard, with inline `[mm:ss]` citations.
+2. **Evidence strip** — every image examined, and what it showed.
+3. **Ledger** — verbatim output of `nybls ledger <id>`.
+
+The evidence strip is what separates a claim from an assertion. It is also the
+product's most visible difference: a transcript-only tool cannot produce one.
+
+---
+
+## Worked example
+
+A 35-minute video, question: what happens in it?
+
+| Round | Action | Spend | Outcome |
+|---|---|---|---|
+| 0 | probe, read transcript | 0 | narrative clear; the visual payoff is not |
+| 1 | one whole-video sheet | 1 | six moments; the second half is a *different car* |
+| — | evaluator | — | `partial` — the titular reveal is not in these six |
+| 2 | sheet of the final 5.5 minutes | 1 | not there either; the reveal is earlier |
+| 3 | zoom on a badge | 1 | landed on a headlight — reported honestly, model not named |
+
+Final: 3 images, ~3,069 visual tokens, about one cent, against 53,171 frames.
+The reveal was located at 12:05 by combining a Round 1 thumbnail with a free
+transcript read — not by spending more images.