Publish tiny_computer_agent_app.py from marimo

tiny_computer_agent_app.py

@@ -63,7 +63,7 @@ def readme():
 
     > **Status 0.3.0: it drives a real desktop — on Linux and on Windows.** Screen capture,
     > an OCR element index with real coordinates, a real mouse click, and a *verified*
-    > outcome. A run can be saved as a portable *trace*, replayed offline and **scored**, so
+    > outcome. Every capability has a real screenshot in the [capability gallery](#capability-gallery), and a run can be saved as a portable *trace*, replayed offline and **scored**, so
     > "which brain is right, and how often?" is a number in a table.
     > The suite passes on a live Linux desktop and inside a real Windows Server
     > 2022 guest; what is not solved is model reliability — see
@@ -125,7 +125,7 @@ def readme():
     ```bash
     python -m pip install -e ".[desktop,ocr,dev]"
     pytest tests -q
-    # 151 passed, 2 skipped in 18.7s
+    # 162 passed, 2 skipped in 18.7s
     ```
 
     The two skips are the live-desktop tests. Give them a display and they run for real:
@@ -257,7 +257,7 @@ def readme():
       `warning: no text was found on screen, so the index is 96 numbered grid cells and the
       agent is choosing blind` — instead of silently guessing.
 
-    **153 tests pass**, including real OCR over a real image and (opt-in) live-desktop tests
+    **164 tests pass**, including real OCR over a real image and (opt-in) live-desktop tests
     that click a real button.
 
     ## Verified on real Windows
@@ -299,7 +299,7 @@ def readme():
 
     None of the three failures in the first row is a harness defect: two are
     `ModuleNotFoundError: numpy` and the third is the guard bug documented below. With the
-    OCR engine installed, the same suite exits **0**. (Those Windows counts predate `trace.py`; the harness suite has since grown to 153 tests.)
+    OCR engine installed, the same suite exits **0**. (Those Windows counts predate `trace.py`; the harness suite has since grown to 164 tests.)
 
     **The emulated-OCR caveat.** onnxruntime requires AVX2, and QEMU's software emulation of
     AVX2 is roughly two orders of magnitude slower than native. A suite that finishes in 17
@@ -325,7 +325,7 @@ def readme():
 
     ## The test suite, in full
 
-    `pytest tests` collects **153 tests**. 151 run headless — no display, no network, no
+    `pytest tests` collects **164 tests**. 162 run headless — no display, no network, no
     weights. The last 2 are the opt-in live-desktop tests, skipped unless
     `TINY_COMPUTER_AGENT_LIVE_TEST=1`.
 
@@ -343,11 +343,13 @@ def readme():
     | `tests/test_desktop.py` | 10 | display detection, the preflight checks, `doctor` |
     | `tests/test_cli.py` | 10 | the command line: `--doctor`, `--image`, `--live`, argument handling |
     | `tests/test_trace.py` | 28 | traces: a run recorded with no pixels, replayed against another brain, and scored against ground truth |
+    | `tests/test_models.py` | 7 | the model backends: lazy loading, device choice, honest refusals |
+    | `tests/test_api_surface.py` | 4 | the public API is a promise: everything advertised is importable, and nothing public is left out |
     | `tests/test_live_desktop.py` | 2 | **needs a display, opt-in**: OCR finds a real button at the pixels it was drawn at, and a real click makes the app react |
 
     ```bash
-    pytest tests -q                                  # 151 passed, 2 skipped
-    TINY_COMPUTER_AGENT_LIVE_TEST=1 pytest tests -q  # 153 passed, on a desktop
+    pytest tests -q                                  # 162 passed, 2 skipped
+    TINY_COMPUTER_AGENT_LIVE_TEST=1 pytest tests -q  # 164 passed, on a desktop
     ```
 
     ## Install
@@ -356,7 +358,7 @@ def readme():
     pip install -e ".[ocr]"              # labels from pixels (RapidOCR: no system binary)
     pip install -e ".[desktop,ocr]"      # + real capture and real input
     pip install -e ".[vision,ocr]"       # + the tiny model brains
-    pytest                               # 153 tests, no display or network needed
+    pytest                               # 164 tests, no display or network needed
     ```
 
     ## Run it on your machine
@@ -458,6 +460,605 @@ def readme():
     | `desktop.py` | Preflight checks, `doctor`, and `build_agent` in one call |
     | `demo.py` | The synthetic desktop used by tests and `--image example` |
     | `trace.py` | Portable traces: record a run with no pixels, replay it offline, score the choice against ground truth |
+    | `showcase.py` | The capability gallery: one real screenshot per capability, checked against the public API |
+
+    ## Capability gallery
+
+    **68 capabilities, one screenshot each - and every one of the 141 public callables in the package (functions, methods, classes and protocols) appears in at least one of them**, together with 6 of its public constants.
+
+    Nothing here is a mock-up. Each picture is produced by [`showcase.py`](showcase.py): a command or a call is run for real, and its actual output - or the real desktop it acted on - is what you see. The desktop shots are real screen captures on a real X server (Xvfb, 1280x800), including a real mouse click verified by the target application's own reaction.
+
+    > **An honest note on the platform.** These were captured on Linux, because the sandbox that builds this card has no Windows: no KVM, no QEMU and no Windows image. The harness is OS-agnostic (pyautogui uses `SendInput` on Windows, and `GrabScreen` falls back to Pillow's `ImageGrab`), so these are the same code paths - but they are not Windows pixels. The Windows twins are generated by the same script in [`.github/workflows/live-desktop.yml`](.github/workflows/live-desktop.yml).
+
+    Regenerate it with `python showcase.py` (`--list` to see the ids, `--only <id>` for a subset, `--card` to rewrite this section). It runs the calls for real, so a broken capability fails loudly instead of shipping a stale picture.
+
+    | area | capabilities |
+    |---|---:|
+    | Action vocabulary | 3 |
+    | Decisions | 7 |
+    | Execution | 2 |
+    | The loop | 7 |
+    | Safety | 4 |
+    | Screens | 6 |
+    | Perception | 6 |
+    | Preflight | 4 |
+    | Models | 5 |
+    | Traces & scoring | 7 |
+    | Command line | 9 |
+    | Real desktop | 7 |
+    | Extensibility | 1 |
+
+    ---
+
+    ### Action vocabulary
+
+    **The six verbs, and only six**
+
+    *Every action is validated on construction, before anything touches the machine.*
+
+    <img src="gallery/vocab-verbs.png" width="860">
+
+    `shows:` `ACTION_KINDS`, `ACTION_MENU`, `Action`, `Action.describe`, `Action.to_dict`, `parse_action`
+
+    **Malformed actions are refused, not guessed at**
+
+    *An unknown verb or a missing target raises before the machine is touched.*
+
+    <img src="gallery/vocab-refusals.png" width="860">
+
+    `shows:` `ActionError`, `Action`, `parse_action`
+
+    **The contract handed to a model**
+
+    *The prompt-side menu: one JSON object, six shapes, no invented verbs.*
+
+    <img src="gallery/vocab-menu.png" width="860">
+
+    `shows:` `ACTION_MENU`
+
+    ### Decisions
+
+    **A short numbered menu, in reading order**
+
+    *A 256M model cannot emit coordinates; it can pick a number from twelve.*
+
+    <img src="gallery/menu-numbered.png" width="860">
+
+    `shows:` `DecisionMenu`, `DecisionMenu.render`, `MenuItem`, `MenuItem.label`
+
+    **Menu lookup tolerates what models actually send**
+
+    *1, "2", 2.0 and "Save." all resolve; a stray word resolves to nothing.*
+
+    <img src="gallery/menu-lookup.png" width="860">
+
+    `shows:` `DecisionMenu.item`, `DecisionMenu.find`, `DecisionMenu.mentioned_in`
+
+    **Reading a decision out of a small model's reply**
+
+    *The LAST JSON object wins, because a model that echoes its prompt answers last.*
+
+    <img src="gallery/decision-json.png" width="860">
+
+    `shows:` `parse_decision`, `extract_json_object`, `extract_json_objects`, `DecisionMenu`
+
+    **An echoed prompt is refused; a right answer in the wrong field is recovered**
+
+    *Real 256M/0.5B failure modes, both caught: no blind click either way.*
+
+    <img src="gallery/decision-echo-guard.png" width="860">
+
+    `shows:` `parse_decision`, `BrainError`, `DecisionMenu.mentioned_in`
+
+    **A garbled verb with a valid label is still usable**
+
+    *A 256M model really does emit {"kind": "file", "label": "Save"}.*
+
+    <img src="gallery/decision-garbled.png" width="860">
+
+    `shows:` `parse_decision`, `BrainError`
+
+    **MockBrain: replay a fixed script, exactly once**
+
+    *Deterministic and offline - the workhorse for tests, demos and replays.*
+
+    <img src="gallery/brain-mock.png" width="860">
+
+    `shows:` `MockBrain`, `MockBrain.decide`, `MockBrain.remaining`
+
+    **PlannerBrain: no weights, no download, and it gives up honestly**
+
+    *The proof the harness works end to end, and a real fallback when no model is wanted.*
+
+    <img src="gallery/brain-planner.png" width="860">
+
+    `shows:` `PlannerBrain`, `PlannerBrain.decide`, `GoalUnreachable`
+
+    ### Execution
+
+    **Dry run resolves every click to pixels - and touches nothing**
+
+    *The default everywhere: read a whole episode before anything clicks.*
+
+    <img src="gallery/exec-dry-run.png" width="860">
+
+    `shows:` `DryRunExecutor`, `DryRunExecutor.execute`, `resolve_point`, `ActionResult`
+
+    **Real input refuses to guess a pixel for a label it cannot find**
+
+    *This is the gate between a hallucinated label and 'Delete account'.*
+
+    <img src="gallery/exec-refuses-unresolved.png" width="860">
+
+    `shows:` `ActionResult.summary`, `InputUnavailable`, `PyAutoGuiExecutor`, `PyAutoGuiExecutor.execute`
+
+    ### The loop
+
+    **observe -> think -> act -> verify, traced end to end**
+
+    *One call runs a whole episode; every step is kept for audit.*
+
+    <img src="gallery/loop-end-to-end.png" width="860">
+
+    `shows:` `AgentLoop`, `AgentLoop.run`, `Episode`, `Episode.render`, `Episode.to_rows`, `Step`, `Step.line`, `Step.ok`
+
+    **A hard step budget, so a run cannot wander**
+
+    *The budget ends the episode and says so; nothing executes past it.*
+
+    <img src="gallery/loop-budget.png" width="860">
+
+    `shows:` `Policy`, `Policy.step_budget`, `AgentLoop.run`
+
+    **Repeating one action against an unchanged screen is stopped**
+
+    *A stuck agent is not a persistent one - it is stopped and told why.*
+
+    <img src="gallery/loop-no-progress-guard.png" width="860">
+
+    `shows:` `AgentLoop.run`, `Step`, `Step.error`
+
+    **A kill-switch file aborts before the next action**
+
+    *Checked before every single action: create the file, the run stops.*
+
+    <img src="gallery/loop-kill-switch.png" width="860">
+
+    `shows:` `Policy.kill_switch_path`, `Policy.should_stop`, `AgentLoop.run`
+
+    **A dead screen or a broken brain is an episode, not a traceback**
+
+    *Every failure path is recorded as a failed step with a reason.*
+
+    <img src="gallery/loop-survives-failures.png" width="860">
+
+    `shows:` `AgentLoop.run`, `Episode.stop_reason`, `GoalUnreachable`, `BrainError`
+
+    **Success is evidence, not the model's word**
+
+    *Without a verifier, a successful action that removes its own target looks like a failure.*
+
+    <img src="gallery/loop-verifier.png" width="860">
+
+    `shows:` `AgentLoop.run`, `Episode.success`, `Observation.text`
+
+    **Every step can be streamed out as it happens**
+
+    *This is the hook a live console, a progress bar or a websocket uses.*
+
+    <img src="gallery/loop-on-step.png" width="860">
+
+    `shows:` `AgentLoop.run`, `Step.line`, `on_step`
+
+    ### Safety
+
+    **Typing from the deny list never reaches the keyboard**
+
+    *Checked before execution; a refusal ends the episode and clicks nothing.*
+
+    <img src="gallery/safety-deny-text.png" width="860">
+
+    `shows:` `Policy`, `Policy.check`, `PolicyViolation`, `DEFAULT_DENY_TEXT`
+
+    **Clicking a denied widget is refused, however the label is spelled**
+
+    *Terminal, keychain, wallet, password manager, bank - matched on the label.*
+
+    <img src="gallery/safety-deny-label.png" width="860">
+
+    `shows:` `Policy.deny_labels`, `Policy.check`, `Observation.find`
+
+    **Key chords on the deny list are never pressed**
+
+    *ctrl+alt+t, ctrl+alt+delete and ctrl+shift+escape are refused by default.*
+
+    <img src="gallery/safety-deny-keys.png" width="860">
+
+    `shows:` `Policy.deny_keys`, `Policy.check`, `PolicyViolation`
+
+    **A numbered grid cell is a blind click: allowed to plan, refused for real**
+
+    *With real input the blind guess is refused unless you pass --allow-grid.*
+
+    <img src="gallery/safety-blind-grid.png" width="860">
+
+    `shows:` `Policy.allow_grid_clicks`, `Policy.check`, `GridDetector`
+
+    ### Screens
+
+    **A scripted screen, for testing the loop with no display**
+
+    *The final frame repeats forever, so a runaway agent cannot exhaust the script.*
+
+    <img src="gallery/screen-fake.png" width="860">
+
+    `shows:` `FakeScreen`, `FakeScreen.capture`, `Observation`
+
+    **A still image (or a sequence) replayed as a screen**
+
+    *Lets the whole pipeline be exercised with no display, and a failure be replayed.*
+
+    <img src="gallery/screen-image.png" width="860">
+
+    `shows:` `ImageScreen`, `ImageScreen.capture`, `fake_desktop`
+
+    **Real capture: monitors, downscaling, and HiDPI mapping**
+
+    *Frame pixel -> screen pixel is preserved, so a click cannot drift.*
+
+    <img src="gallery/capture-options.png" width="860">
+
+    `shows:` `GrabScreen`, `GrabScreen.capture`, `GrabScreen.map_to_screen`, `ScreenUnavailable`
+
+    **Labels are compared on their alphanumeric core**
+
+    *OCR loses spaces, models add punctuation - so nothing matches by exact string.*
+
+    <img src="gallery/element-matching.png" width="860">
+
+    `shows:` `Element`, `Element.center`, `Element.matches`, `Observation.find`, `normalise_label`
+
+    **The compact text a model is shown**
+
+    *This is the whole world as the brain sees it - capped, and honest when empty.*
+
+    <img src="gallery/observation-summary.png" width="860">
+
+    `shows:` `Observation.summary`
+
+    **The built-in synthetic desktop**
+
+    *Draws a screenshot-like desktop offline - the same image --image example replays.*
+
+    <img src="gallery/fake-desktop.png" width="860">
+
+    `shows:` `fake_desktop`, `write_fake_desktop`, `OcrDetector`
+
+    ### Perception
+
+    **Probing for a detector, and building one by name**
+
+    *The doctor and the CLI both ask this before promising anything.*
+
+    <img src="gallery/detector-available.png" width="860">
+
+    `shows:` `detector_available`, `make_detector`, `DetectorUnavailable`, `Detector`
+
+    **OCR turns a screenshot into labelled, clickable elements**
+
+    *The model never has to guess where anything is: this is the grounding.*
+
+    <img src="gallery/ocr-labels.png" width="860">
+
+    `shows:` `OcrDetector`, `OcrDetector.detect`, `Element`
+
+    **Three knobs keep dialog prose out of the menu**
+
+    *Every extra line of noise is one more chance for a small model to click prose.*
+
+    <img src="gallery/ocr-filters.png" width="860">
+
+    `shows:` `OcrDetector.min_score`, `OcrDetector.max_label_chars`, `OcrDetector.min_label_chars`
+
+    **A numbered grid, for screens with no text at all**
+
+    *An agent with an empty index has no legal moves; a grid always has moves.*
+
+    <img src="gallery/grid-detector.png" width="860">
+
+    `shows:` `GridDetector`, `GridDetector.detect`
+
+    **OCR when there is text, a grid when there is none**
+
+    *The default: useful with nothing installed, better the moment OCR appears.*
+
+    <img src="gallery/auto-detector.png" width="860">
+
+    `shows:` `AutoDetector`, `AutoDetector.detect`
+
+    **IndexedScreen: capture + detect, composed**
+
+    *One capture() call gives the loop an index it can act on.*
+
+    <img src="gallery/indexed-screen.png" width="860">
+
+    `shows:` `IndexedScreen`, `IndexedScreen.capture`, `Observation.summary`
+
+    ### Preflight
+
+    **Is there a desktop session to drive at all?**
+
+    *The first question the CLI and the doctor both ask.*
+
+    <img src="gallery/display-available.png" width="860">
+
+    `shows:` `display_available`
+
+    **Every precondition, one list, each with the fix**
+
+    *Eight checks; a required one that fails is a blocking problem.*
+
+    <img src="gallery/run-checks.png" width="860">
+
+    `shows:` `run_checks`, `Check`, `Check.render`
+
+    **python -m tiny_computer_agent --doctor**
+
+    *The first thing to run on a new machine. Exits non-zero when not ready.*
+
+    <img src="gallery/cli-doctor.png" width="860">
+
+    `shows:` `detector_available`, `display_available`, `doctor`, `report`
+
+    **One call wires screen + detector + brain + executor + policy**
+
+    *Defaults are the safe ones: dry run, a step budget, and a kill-switch file.*
+
+    <img src="gallery/build-agent.png" width="860">
+
+    `shows:` `build_agent`, `Policy`, `AgentLoop`
+
+    ### Models
+
+    **Which model runtime is present, and are the weights cached?**
+
+    *Weights are loaded lazily, so asking is free.*
+
+    <img src="gallery/models-deps.png" width="860">
+
+    `shows:` `model_dependencies`, `model_cached`, `MODEL_BRAINS`, `make_model_brain`, `DEFAULT_TEXT_MODEL`, `DEFAULT_VISION_MODEL`, `BrainError`
+
+    **Device and dtype selection**
+
+    *CUDA if it is there, CPU otherwise; the harness never needs a GPU.*
+
+    <img src="gallery/models-device.png" width="860">
+
+    `shows:` `resolve_device`, `pick_dtype`
+
+    **The prompt a model actually receives - and how it learns from a dead end**
+
+    *Placeholders, not worked examples: a weak model echoes the prompt, and an echo fails validation.*
+
+    <img src="gallery/models-prompt.png" width="860">
+
+    `shows:` `ModelBrain`, `ModelBrain.build_prompt`, `ModelBrain.decide`
+
+    **A second decision is told what already failed**
+
+    *'you already tried this and the screen did NOT change' is the most useful line a small model gets.*
+
+    <img src="gallery/models-prompt-history.png" width="860">
+
+    `shows:` `ModelBrain`, `ModelBrain.build_prompt`, `ModelBrain.history`
+
+    **The two real model backends, and lazy loading**
+
+    *Constructing a brain costs nothing; the weights arrive on the first decide().*
+
+    <img src="gallery/models-swap.png" width="860">
+
+    `shows:` `TextPlannerBrain`, `VLMBrain`, `TextPlannerBrain.unload`, `VLMBrain.unload`, `ModelBrain.loaded`, `make_model_brain`
+
+    ### Traces & scoring
+
+    **A task with one right answer, and the frames to show**
+
+    *Ground truth lives with the task, so a run can be scored at all.*
+
+    <img src="gallery/scenario.png" width="860">
+
+    `shows:` `Scenario`, `Scenario.label`, `Scenario.screen`, `Trace.render`, `run_scenario`
+
+    **An episode becomes a portable, pixel-free trace**
+
+    *JSON, so it diffs in review and replays on a machine with nothing installed.*
+
+    <img src="gallery/trace-record.png" width="860">
+
+    `shows:` `Trace`, `Trace.blocked`, `Trace.choice`, `Trace.decided`, `Trace.decision_step`, `Trace.frames`, `Trace.load`, `Trace.name`, `Trace.record`, `Trace.save`, `Trace.to_dict`, `Trace.to_json`, `TraceStep`, `TraceStep.observation`, `TraceStep.to_dict`
+
+    **Replay a recorded trace against a different brain**
+
+    *The frames are the fixture; the brain is the only variable. Nothing is captured or clicked.*
+
+    <img src="gallery/trace-replay.png" width="860">
+
+    `shows:` `Trace.replay`, `Trace.observations`, `score_trace`
+
+    **Counting how often the choice was right**
+
+    *Scored on normalised text, so OCR spacing is forgiven - the same bargain the index makes.*
+
+    <img src="gallery/score-trace.png" width="860">
+
+    `shows:` `score_trace`, `score`, `score_replay`, `Verdict`, `Verdict.line`
+
+    **Verdicts collected into an accuracy**
+
+    *The number the whole module exists for: which brain is right, and how often.*
+
+    <img src="gallery/scoreboard.png" width="860">
+
+    `shows:` `Scoreboard`, `Scoreboard.accuracy`, `Scoreboard.accuracy_for`, `Scoreboard.add`, `Scoreboard.blocked`, `Scoreboard.brains`, `Scoreboard.by_brain`, `Scoreboard.confusion`, `Scoreboard.earned`, `Scoreboard.render`, `Scoreboard.to_rows`, `Scoreboard.total`
+
+    **Every scenario through every brain, in one table**
+
+    *A fresh brain per task, so state like 'already clicked this' cannot leak between them.*
+
+    <img src="gallery/benchmark.png" width="860">
+
+    `shows:` `benchmark`, `Scoreboard.to_rows`
+
+    **Replay a whole recorded suite against one brain**
+
+    *The literal roadmap step: the frames are fixed, nothing new is captured.*
+
+    <img src="gallery/benchmark-traces.png" width="860">
+
+    `shows:` `benchmark_traces`, `load_traces`, `Trace.save`
+
+    ### Command line
+
+    **--image example  (replay a screenshot, dry run)**
+
+    *No display needed: the whole pipeline over a still image.*
+
+    <img src="gallery/cli-image.png" width="860">
+
+    `shows:` `main`, `build_parser`, `ImageScreen`, `detector_available`
+
+    **--script  (replay a fixed action list instead of a brain)**
+
+    *The script is validated exactly like a model's answer: nothing skips the gates.*
+
+    <img src="gallery/cli-script.png" width="860">
+
+    `shows:` `MockBrain`, `demo_screen`, `parse_action`
+
+    **--verify-text  (the harness decides success, not the brain)**
+
+    *Without it, an action that removes its own target looks like a failure.*
+
+    <img src="gallery/cli-verify-text.png" width="860">
+
+    `shows:` `AgentLoop.run`, `Episode.success`
+
+    **--trace / --expected  (record the run, then score it)**
+
+    *Writes JSON next to the code, and prints the score straight away.*
+
+    <img src="gallery/cli-trace.png" width="860">
+
+    `shows:` `Trace.record`, `Trace.save`, `score_trace`
+
+    **--no-ocr  (index a numbered grid instead)**
+
+    *Useful on a machine with no OCR engine, or for a canvas app.*
+
+    <img src="gallery/cli-detector.png" width="860">
+
+    `shows:` `GridDetector`, `make_detector`, `detector_available`
+
+    **Exit codes: 0 success, 1 failure, 2 bad usage, 3 no screen**
+
+    *A shell can tell 'it worked' from 'it gave up' without parsing any text.*
+
+    <img src="gallery/cli-exit-codes.png" width="860">
+
+    `shows:` `main`
+
+    **The two deliberate acts before the mouse can move**
+
+    *--real-input without the env var, and --brain vlm with no pixels: both refuse.*
+
+    <img src="gallery/cli-refusals.png" width="860">
+
+    `shows:` `main`, `ALLOW_REAL_INPUT_ENV`
+
+    **--live with no display is refused, with the fix**
+
+    *It tells you what to do instead of dying inside an episode.*
+
+    <img src="gallery/cli-live-headless.png" width="860">
+
+    `shows:` `display_available`, `main`
+
+    **--live  (your real screen, dry run)**
+
+    *Real capture, real OCR, a real element index - and not one click.*
+
+    <img src="gallery/cli-live-dry-run.png" width="860">
+
+    `shows:` `GrabScreen`, `IndexedScreen`, `AutoDetector`, `main`
+
+    ### Real desktop
+
+    **GrabScreen: capture a real desktop**
+
+    *1280x800 of a real X server. mss first, Pillow's ImageGrab as the fallback.*
+
+    <img src="gallery/desk-capture.png" width="860">
+
+    `shows:` `GrabScreen`, `GrabScreen.capture`, `ScreenUnavailable`
+
+    **The element index, drawn on the pixels it came from**
+
+    *Every box is a real OCR word with a real screen coordinate: the model picks a label, not a pixel.*
+
+    <img src="gallery/desk-ocr-index.png" width="860">
+
+    `shows:` `OcrDetector`, `OcrDetector.detect`, `IndexedScreen`, `Element.center`
+
+    **A real click, and the window's own reaction**
+
+    *Pixels in, a label chosen, a pixel resolved, a button pressed - and the dialog closed itself.*
+
+    <img src="gallery/desk-click.png" width="860">
+
+    `shows:` `PyAutoGuiExecutor`, `AgentLoop.run`, `Policy.dry_run`, `resolve_point`
+
+    **Success only when the harness can see it**
+
+    *The app changed its own title and wrote a marker file; the verifier saw the change.*
+
+    <img src="gallery/desk-verify.png" width="860">
+
+    `shows:` `AgentLoop.run`, `Episode.success`, `Episode.stop_reason`
+
+    **A screen with no text still has legal moves**
+
+    *OCR finds nothing on a canvas, so the index degrades to numbered cells - and says so.*
+
+    <img src="gallery/desk-grid-fallback.png" width="860">
+
+    `shows:` `AutoDetector`, `GridDetector`, `OcrDetector`
+
+    **The safety gate, on a real button, in a real window**
+
+    *The Terminal button is visible and labelled - and the policy refuses to press it.*
+
+    <img src="gallery/desk-policy-refusal.png" width="860">
+
+    `shows:` `Policy.check`, `Policy.deny_labels`, `PolicyViolation`, `Observation.find`
+
+    **The same click, driven end to end from the CLI**
+
+    *--live --real-input --verify-text Saved: capture, OCR, click, verify, exit code.*
+
+    <img src="gallery/desk-cli-real-input.png" width="860">
+
+    `shows:` `main`, `PyAutoGuiExecutor`, `AgentLoop.run`
+
+    ### Extensibility
+
+    **Every stage is a Protocol: bring your own screen, brain, detector, executor**
+
+    *The loop depends on four one-method contracts, not on the shipped implementations.*
+
+    <img src="gallery/protocols.png" width="860">
+
+    `shows:` `Brain`, `Brain.decide`, `ScreenSource`, `ScreenSource.capture`, `Detector`, `Detector.detect`, `Executor`, `Executor.execute`, `ActionResult`
 
     ## Why a tiny model can do this at all
 
@@ -512,6 +1113,8 @@ def readme():
     - [ ] Make the VLM reliable on a live screen (it echoes the prompt instead of choosing)
     - [ ] Accessibility-tree detector (AT-SPI on Linux, UI Automation on Windows)
     - [x] Score episodes: replay a trace and count how often the choice was right - see [scoring a brain, offline](#scoring-a-brain-offline)
+    - [x] A capability gallery: one real screenshot per capability, generated by `showcase.py`
+    - [ ] A **Windows** run of the gallery: the workflow builds it on `windows-latest`, but it needs a GitHub mirror with Actions enabled - Hugging Face does not run GitHub Actions
     - [ ] marimo console: live screen preview, action log, pause / resume / step
 
     ## License
@@ -653,9 +1256,14 @@ def publish_status(
                 ".gitignore": gitignore_txt,
                 "tiny_computer_agent_app.py": _notebook.read_text(encoding="utf-8"),
             }
-            _folders = ["tiny_computer_agent", "tests"]
+            # the tool that builds the capability gallery, shipped with the card it fills
+            for _tool in ("showcase.py", "showcase_core.py", "showcase_catalog.py"):
+                if (_root / _tool).is_file():
+                    _files[_tool] = (_root / _tool).read_text(encoding="utf-8")
+            _folders = [f for f in ("tiny_computer_agent", "tests", "gallery", "showcase_scenes")
+                        if (_root / f).is_dir()]
             if (_root / ".github").is_dir():
-                _folders.append(".github")          # the CI that tests on real Windows
+                _folders.append(".github")          # the CI that builds the Windows gallery
             _missing = [f for f in ("tiny_computer_agent", "tests") if not (_root / f).is_dir()]
             if _missing:
                 _status = mo.md(f"Nothing to publish: missing {_missing} next to `{_root}`").callout(kind="danger")