sc-frederick · Nov 5, 2026 · Nov 5, 2026
diff --git a/README.md b/README.md
@@ -6,7 +6,9 @@ pass or a discipline review. Moke reads source images, follows its review
 instructions, records findings and coverage, and produces an offline HTML report.
 Follow-up requests can deepen the review while retaining earlier issue IDs.
 
-![Moke's desktop workbench with source evidence and findings navigation](docs/screenshots/workbench.png)
+[Watch the narrated demo on YouTube](https://youtu.be/wl8wwq_Tlrw).
+
+![Moke's five-sheet review with 19 findings, coverage gaps, and findings navigation](docs/screenshots/workbench.png)
 
 ## The review workflow
 
@@ -35,14 +37,19 @@ Follow-up requests can deepen the review while retaining earlier issue IDs.
    status and reviewer-verified closure. Export a complete package to preserve
    the source files and execution history as well.
 
+![A saved false-alarm decision beside the source drawing and SAM highlight](docs/screenshots/correction.png)
+
+Revision reviews carry earlier findings into the revised sheets. The demo also
+shows a finding that remained open on a 13-sheet set reviewed on October 31.
+
+![A revision recheck retains an unresolved area discrepancy and the reviewer's decision](docs/screenshots/revision.png)
+
 Drawn-to-schedule count comparisons remain available as specialized checks.
 Reviewers accept their count inputs and coverage before deterministic comparison;
 corrections and revision rechecks retain their history. The
 [two-sheet count demonstration](docs/fixtures/hero-case.md) exercises a supported
 issue, corrected false alarm, unchanged control and revision recheck.
 
-![A count-check revision recheck retains its earlier results](docs/screenshots/revision.png)
-
 A review report states what was actually inspected. Model findings are review
 results, and a finished execution does not provide professional approval.
 Regulatory findings need applicable governing sources; unavailable sources and
@@ -113,7 +120,7 @@ Build installers with `bun run package:desktop`. See [desktop builds and release
 ```sh
 bun run verify          # checks, smoke tests, builds, and Electron end-to-end tests
 bun run test:packaged   # after packaging, repeat the desktop flow against the packaged executable
-bun run test:screenshots
+bun run test:screenshots # offline fixture captures in test-results/
 ```
 
 Tests use real local databases, RPC, PDF workers, and Electron. Hosted-provider
@@ -122,9 +129,10 @@ no paid requests. Headless Linux needs an X display, for example
 `xvfb-run -a bun run verify`. Install Poppler for the optional experiment smoke
 tests; they skip explicitly when `pdftoppm` is unavailable.
 
-Screenshots come from the same Electron workflow using authored synthetic PDFs,
-without inference. [Development and testing](docs/development.md) explains the
-suite layout, screenshot refresh, and toolchain.
+The README screenshots are frames from the narrated demo, showing actual review
+results and saved decisions. The [screenshot source notes](docs/screenshots/README.md)
+record the video and frame timestamps. [Development and testing](docs/development.md)
+explains the suite layout, offline fixture captures, and toolchain.
 
 ## Repository layout
 
@@ -145,8 +153,16 @@ record the Forge design system, its adaptations, and third-party asset attributi
 
 ## Hackathon provenance
 
-The Moke name and review prompts predate this entry. This repository implements
-a fresh application from the project-kit desktop starter, with drawing evidence,
+This entry addresses **Build for Your World**. The application work in this
+repository began on October 27, 2026. The [rules and evidence review](docs/validation/hackathon-readiness.md)
+maps the public repository, Meta model integration, demo, and source attribution
+to the participant guide checked on November 4.
+
+The Moke name, review prompts, and the owner's 2023 Florida Building Code
+plan-review reference predate this entry. The code index tooling and
+`florida-code-additions.md` were added during the hackathon; see the
+[code index provenance](backend/review/code-index/README.md).
+This repository implements a fresh application from the project-kit desktop starter, with drawing evidence,
 corrections, and revision tracking built for the hackathon. It does not reuse the
 earlier Moke application. Pi Durable provides agent execution as an MIT-licensed
 dependency; the new work is the drawing-review application, evidence handling,

diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@ Start with [Moke's README](../README.md) for the product, workflow, and screensh
 
 ## Setup and development
 
-- [Development and testing](development.md): commands, smoke/Electron suites, and screenshot refresh.
+- [Development and testing](development.md): commands, smoke/Electron suites, demo frames, and offline fixture captures.
 - [Inference setup](inference.md): provider keys, canonical routes, and manual API checks.
 - [Cloud reviews](cloud-reviews.md): Push to cloud, operator setup, sandbox lifetimes, and recovery limits.
 - [Model reference](models.md): the Meta catalog and the Baseten hackathon endpoint.
@@ -25,6 +25,9 @@ Start with [Moke's README](../README.md) for the product, workflow, and screensh
 
 ## Validation records
 
+The [hackathon rules and repository evidence](validation/hackathon-readiness.md)
+records the participant guide check and what this repository can verify.
+
 These record specific live runs on the dates they state. They are not benchmarks
 for unseen drawings. Raw request and response receipts stayed in the ignored
 `.local/` directory of the machine that ran them; the `*-result.json` files here

diff --git a/docs/development.md b/docs/development.md
@@ -17,7 +17,7 @@ by `svelte-check --tsgo` for Effect diagnostics.
 | `bun run verify`           | Run checks, smoke tests, builds, and Electron flows                      |
 | `bun run package:desktop`  | Build installers without publishing                                      |
 | `bun run test:packaged`    | Run the desktop flows against exactly one packaged executable            |
-| `bun run test:screenshots` | Refresh the screenshots linked from the README                           |
+| `bun run test:screenshots` | Capture the offline Electron fixture in `test-results/`                  |
 
 Local Electron tests run only on Linux, through `scripts/isolated-desktop.ts`.
 It never uses an existing desktop. It needs unprivileged user namespaces for
@@ -67,16 +67,22 @@ tests use the upstream runner and are not part of this repository's commands.
 
 Run one smoke suite with `bun test ./tests/smoke/review.test.ts`. Electron tests
 need `bun run build` first. The Playwright `desktop` project runs the regular
-suite; the `screenshots` project repeats the review flow and writes documentation
-images. The packaged command requires exactly one application under `release/`,
+suite; the `screenshots` project repeats the review flow and writes offline fixture
+images to test output. The packaged command requires exactly one application under `release/`,
 so remove obsolete build output before repackaging.
 
 Live checks are opt-in and may spend API credits. See [inference setup](inference.md)
 and the [recorded validation](validation/core-validation.md). A passing offline
 suite establishes application behavior with controlled responses, not current
 provider availability or model accuracy.
 
-## Screenshot refresh
+## README screenshots
+
+The README uses frames from the narrated demo. See
+[screenshot sources](screenshots/README.md) for the source video, timestamps, and
+extraction commands. These images show actual model reviews and saved decisions.
+
+## Offline fixture captures
 
 ```sh
 bun run build
@@ -88,15 +94,13 @@ The screenshot run uses the same private Linux display runner as `test:e2e`.
 The Electron flow creates its own two-sheet PDFs and browser profile in a
 temporary data directory.
 It captures the real workbench at 1440 × 1000, a corrected finding, and a
-revision recheck. Screenshots go to `docs/screenshots/`.
+revision recheck. Screenshots go to each test's output directory under
+`test-results/`, leaving the demo frames in `docs/screenshots/` intact.
 No model inspection starts. The test refuses screenshot mode with live inference
 enabled, checks renderer errors, and removes its temporary project after closing.
 
-The captures include the [workbench](screenshots/workbench.png),
-[correction history](screenshots/correction.png), and
-[revision history](screenshots/revision.png).
-
-Inspect the generated PNGs before committing them.
+The captures include `workbench.png`, `correction.png`, and `revision.png` for
+inspecting the offline workflow.
 
 ## Design and experiments
 

diff --git a/docs/screenshots/README.md b/docs/screenshots/README.md
@@ -0,0 +1,40 @@
+# Screenshot sources
+
+The README screenshots are full frames from `moke-demo-voiceover-final.mp4`, the
+local final narrated demo cut rendered on November 4, 2026. They retain the
+recorded app UI, cursor, and footage labels at the video resolution of
+2560 × 1440. The video edit already cropped the window title bar and scaled the
+footage. Frame extraction adds no further cropping or content edits.
+
+[Watch the demo on YouTube](https://youtu.be/wl8wwq_Tlrw).
+
+Source video SHA-256:
+
+```text
+a9fc56262ddd25e83f0aef285f5fd33f95bbe3375d2a0a5840e96d3339afe5cb
+```
+
+| Image                            | Video timestamp | Content                                                                                                                                |
+| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [workbench.png](workbench.png)   | 00:01:32        | Five-sheet civil review with 19 findings, coverage gaps, and findings navigation                                                       |
+| [correction.png](correction.png) | 00:01:48        | Source evidence with a SAM highlight and a saved false-alarm decision explaining that identifying information was removed for the demo |
+| [revision.png](revision.png)     | 00:02:02        | Earlier 13-sheet review showing an unresolved Rev 1 area discrepancy and the saved reviewer decision                                   |
+
+The revision frame retains the video's "Oct 31 footage, 13-sheet set" label.
+It is from a different review than the five-sheet civil example.
+
+## Extract the frames
+
+With FFmpeg installed, run these commands from the repository root. Set
+`MOKE_DEMO_VIDEO` to the local copy of the source video; the video itself is not
+stored in this repository.
+
+```sh
+export MOKE_DEMO_VIDEO=/path/to/moke-demo-voiceover-final.mp4
+ffmpeg -hide_banner -loglevel error -y -ss 92 -i "$MOKE_DEMO_VIDEO" -frames:v 1 -threads 2 docs/screenshots/workbench.png
+ffmpeg -hide_banner -loglevel error -y -ss 108 -i "$MOKE_DEMO_VIDEO" -frames:v 1 -threads 2 docs/screenshots/correction.png
+ffmpeg -hide_banner -loglevel error -y -ss 122 -i "$MOKE_DEMO_VIDEO" -frames:v 1 -threads 2 docs/screenshots/revision.png
+```
+
+`bun run test:screenshots` captures the offline synthetic fixture into
+`test-results/`. It does not replace these demo frames.
diff --git a/docs/screenshots/correction.png b/docs/screenshots/correction.png
diff --git a/docs/screenshots/revision.png b/docs/screenshots/revision.png
diff --git a/docs/screenshots/workbench.png b/docs/screenshots/workbench.png
diff --git a/docs/validation/hackathon-readiness.md b/docs/validation/hackathon-readiness.md
@@ -0,0 +1,29 @@
+# Hackathon rules and repository evidence
+
+Checked November 4, 2026 against the live
+[participant guide](https://cerebralvalley.ai/e/meta-ai-developer-hackathon/details)
+using Browser Control. This records repository evidence and verification limits;
+it does not certify participant eligibility or guarantee a judging outcome.
+
+| Requirement                                             | Repository evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Address a problem statement and incorporate Meta models | Moke addresses Build for Your World through engineering drawing review. [Model routes](../../src/lib/review/models.ts) include Muse Spark, Muse Wonder, Muse Spark Open through Baseten, and Muse Spark 1.3 Contributor through OpenCode Go. [SAM evidence](../experiments/adaptive-meta-review.md) documents segmentation.                                                                                                                                                                                               |
+| Public repository                                       | GitHub reported `sc-frederick/moke-meta-hackathon` as public during this check.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Identify work built during the event                    | The application history starts October 27, 2026 at `0c5e8716c`. The [README](../../README.md#hackathon-provenance), [manifest](../../.project-kit/manifest.json), and [prompt provenance](../../backend/review/prompts/README.md) distinguish the new application from the project-kit starter, earlier Moke prompts, the pre-existing [2023 Florida code reference](../../backend/review/code-index/README.md), and dependencies. The code index tooling and additions were introduced in the October 30 implementation. |
+| Respect code, data, and asset rights                    | The [MIT License](../../LICENSE), [design attribution](../design.md), and [Tabler license](../../src/lib/review/TABLER-LICENSE) document source attribution. The licensed Forge reference pack and local drawing fixture directory are excluded from tracked files. The [demo frames](../screenshots/README.md) retain the recorded footage and its labels. These checks do not independently establish ownership of every dependency or drawing.                                                                         |
+| Three-minute demo showing the new work                  | The local narrated demo cut used for the screenshots is 151.541 seconds. It shows the review results, source evidence, saved decisions, and a labeled earlier revision review. [Frame provenance](../screenshots/README.md) identifies its source and timestamps.                                                                                                                                                                                                                                                         |
+| Baseten hackathon model identifier                      | The configured route uses `meta-models/muse-spark-open-1026`, as the guide requires for the supplied Baseten key. [Recorded validation](baseten-rate-limits.md) documents use of that route.                                                                                                                                                                                                                                                                                                                              |
+
+The open-weight bonus is judged separately and requires the infrastructure
+partner to verify eligible model use. Supporting Muse Spark Open and recording
+past runs are evidence, not a guarantee of bonus eligibility or current credit.
+
+## Submission checks outside this repository
+
+The guide gives a November 4, 2026 deadline of 9:00 PM Eastern Time, requires one
+submission per team, limits teams to four participants, and requires everyone who
+worked on the project to be listed. It also requires the submitted video link to
+be accessible. This repository check does not verify the final platform
+submission, roster, waiver acceptance, participant eligibility, or access to the
+submitted video URL. The local demo duration does not establish that the same cut
+is the one submitted.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "moke-meta-hackathon",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": true,
   "description": "A desktop workbench for evidence-backed engineering drawing review",
   "homepage": "https://github.com/sc-frederick/moke-meta-hackathon",

diff --git a/tests/e2e/review.spec.ts b/tests/e2e/review.spec.ts
@@ -2,7 +2,7 @@ import { expect, test } from "@playwright/test";
 import { electron } from "./isolated-electron.ts";
 import { cp, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { Schema } from "effect";
 import { ResponseReceipt } from "../../backend/inference/response.ts";
@@ -93,9 +93,8 @@ test("desktop proves supported, corrected, unchanged-control, revision, media, a
       }
 
       await page.evaluate(() => document.fonts.ready);
-      await mkdir(resolve("docs/screenshots"), { recursive: true });
       await page.screenshot({
-        path: resolve("docs/screenshots", `${name}.png`),
+        path: test.info().outputPath(`${name}.png`),
         animations: "disabled",
       });
     };