docs: sync submission materials

Co-authored-by: Codex <codex@openai.com>

README.md

@@ -61,6 +61,7 @@ of a continuously refreshed project atlas, and every advisor response is grounde
 - Source code (GitHub): <https://github.com/JacobLinCool/hackathon-advisor>
 - Demo video: <https://youtu.be/Gq-FUiL-ZPw>
 - Social post: <https://x.com/JacobLinCool/status/2066156056724848965>
+- Team HF username: [`JacobLinCool`](https://huggingface.co/JacobLinCool)
 - Submission notes: [`docs/submission-notes.md`](docs/submission-notes.md)
 - Start at the Idea Map, search for a theme, click nearby projects, hover quest badges for evidence, and open the
   advisor when you are ready to test an idea.
@@ -92,11 +93,16 @@ Hackathon Advisor is submitted primarily for the **Thousand Token Wood** track.
 its core form is an AI-native field guide: a living map, an almanac voice, quest evidence, and shareable artifacts that
 make the hackathon field itself explorable.
 
+The demo video is part of that submission evidence. It is built from real app footage of the atlas and advisor flows. Codex helped draft the storyboard, drive the app, capture the screen, generate voice-over, compose the cut, and verify frames and ASR transcripts against the intended narration.
+
 The Space is also targeting the official sponsor and achievement tags shown in the README front matter:
 
 - `sponsor:openbmb`: MiniCPM5-1B is the central planner and quest-classifier base model.
-- `sponsor:openai`: Codex helped implement, debug, document, and prepare the submission; the public Git history uses
-  Codex co-author trailers.
+- `sponsor:openai`: Codex served as the engineering partner across the build. It helped translate the hackathon
+  requirements into implementation slices, inspect and revise the repository, implement the atlas
+  refresh/storage/search paths, add the quest-evidence UI, run tests and browser checks, review deployed Space behavior,
+  prepare commits and deployment updates, produce the demo storyboard/app-footage/voice-over checks, and refine the
+  README narrative. The redacted project-facing Codex session traces are published as a Hugging Face dataset.
 - `sponsor:nvidia`: voice input runs `nvidia/nemotron-speech-streaming-en-0.6b` through NVIDIA NeMo ASR.
 - `sponsor:modal`: Modal is used for development compute, including the quest LoRA training path and remote index-build
   path, and is documented in this README.
@@ -173,9 +179,15 @@ MiniCPM is loaded following the official demo shape (`trust_remote_code=True`, `
 [Codex](https://developers.openai.com/codex) served as the engineering partner for the project. It helped translate the
 hackathon requirements into implementation slices, inspect the existing codebase, build the atlas refresh/storage/cache
 path, add the dashboard search and quest-evidence UI, run local tests and browser checks, review deployed Space behavior,
-prepare commits and deployment updates, and revise the README into a submission narrative. The live app runtime uses the
-models and data listed above; Codex appears in the development record as the assistant that helped design, implement,
-validate, and document the system.
+prepare commits and deployment updates, and revise the README into a submission narrative. This was an evidence loop:
+Codex could read the repository, operate the local or deployed app, inspect the result, and then revise the
+implementation or presentation from what it observed. The live app runtime uses the models and data listed above; Codex
+appears in the development record as the assistant that helped design, implement, validate, and document the system.
+
+The demo video used the same agentic workflow. Codex helped draft the narrated storyboard, drive the live app, capture
+real screen footage, generate voice-over, compose the final video, and check the artifact by reading frames and ASR
+transcripts. That media workflow ran outside Hackathon Advisor's submitted runtime and is not counted in the model
+budget, but it documents how Codex was used to produce and verify submission materials rather than only code changes.
 
 The redacted session-level Codex traces are published as a Hugging Face dataset at
 [`build-small-hackathon/hackathon-advisor-codex-traces`](https://huggingface.co/datasets/build-small-hackathon/hackathon-advisor-codex-traces).
@@ -197,8 +209,9 @@ sponsor awards and the six bonus-quest badges.
 | Sharing is Caring | Real Codex session logs for this project are published on the Hub at [`build-small-hackathon/hackathon-advisor-codex-traces`](https://huggingface.co/datasets/build-small-hackathon/hackathon-advisor-codex-traces); the publisher selects project-relevant sessions, minimizes internal metadata, applies [`openai/privacy-filter`](https://huggingface.co/openai/privacy-filter), and records source hashes for audit. |
 | Field Notes | A build report on the quest-classifier fine-tune is published at [`docs/quest-classification-lora.md`](docs/quest-classification-lora.md), and the app exports session Field Notes as markdown. |
 | Tiny Titan | The largest single model is MiniCPM5-1B at ~1.08B — well under the 4B Tiny Titan ceiling; the full runtime stack totals ≈1.98B, far under the 32B cap. |
+| Best Demo | The YouTube demo and public X post are linked from this README, and a backup MP4 is committed at [`static/assets/hackathon-advisor-demo.mp4`](static/assets/hackathon-advisor-demo.mp4). The video uses real app footage and a Codex-assisted production loop for storyboard, app driving, screen capture, voice-over generation, final composition, and frame/ASR verification. |
 | OpenBMB | MiniCPM5-1B is the central language model for both tool planning and quest classification. |
-| OpenAI Codex | Codex helped implement, debug, document, deploy, and prepare the submission; the public GitHub and Space histories use `Co-authored-by: Codex <codex@openai.com>` trailers. |
+| OpenAI Codex | Codex acted as an engineering partner across implementation, debugging, documentation, deployment review, demo production, and submission preparation. The public GitHub and Space histories use `Co-authored-by: Codex <codex@openai.com>` trailers, and selected project-facing session traces are published after minimization and privacy-filter redaction. |
 | NVIDIA Nemotron | Voice input runs `nvidia/nemotron-speech-streaming-en-0.6b` through NVIDIA NeMo. |
 | Modal | Modal trains the quest-classifier LoRA (`scripts/modal_train_quest_lora.py`), and a Modal remote index-build path is provided; the index shipped in this repo was built locally. |
 | Best Agent | Each turn MiniCPM5 selects one tool; the engine then orchestrates the search → whitespace → score → plan chain over the live project field. |

docs/article.md

@@ -1,4 +1,4 @@
-# Hackathon Advisor: A Living Field Guide for Build Small
+# Hackathon Advisor: A Living Field Guide for Hackathon Builders
 
 Watch the demo video: <https://youtu.be/Gq-FUiL-ZPw>
 
@@ -8,115 +8,59 @@ Space: <https://huggingface.co/spaces/build-small-hackathon/hackathon-advisor>
 
 ## Overview
 
-Hackathon Advisor is a live atlas of the Build Small Hackathon and a small-model originality coach for builders. It
-turns the public `build-small-hackathon` organization into an evidence surface: every public Space contributes to a map
-of the field, a searchable project index, quest-evidence summaries, and an advisor that helps a builder test where a new
-idea may still have room to grow.
+Hackathon Advisor is a live atlas of the Build Small Hackathon and a small-model originality coach for builders. It turns the public `build-small-hackathon` organization into an evidence surface: every public Space contributes to a map of the field, a searchable project index, quest-evidence summaries, and an advisor that helps a builder test where a new idea may still have room to grow.
 
-The project addresses a practical problem in compressed creative work. During a hackathon, builders need to understand
-the surrounding field quickly. They need to know which ideas are crowded, which themes are emerging, which quests a
-project might satisfy, and how a proposal can become more specific before time runs out. Hackathon Advisor makes those
-questions answerable from the public work already being built around them.
+The project addresses a practical problem in compressed creative work. During a hackathon, builders need to understand the surrounding field quickly. They need to know which ideas are crowded, which themes are emerging, which quests a project might satisfy, and how a proposal can become more specific before time runs out. Hackathon Advisor makes those questions answerable from the public work already being built around them.
 
-The motivation starts with the data itself. Build Small already produces a ready-made corpus: public Spaces, READMEs,
-model declarations, app files, tags, and demos. That corpus invites exploration. Once it is made searchable and
-comparable, participants can see what others are building, which methods they are using, and what kinds of results are
-emerging across the community.
+The motivation starts with the data itself. Build Small already produces a ready-made corpus: public Spaces, READMEs, model declarations, app files, tags, and demos. That corpus invites exploration. Once it is made searchable and comparable, participants can see what others are building, which methods they are using, and what kinds of results are emerging across the community.
 
 ## Contribution
 
-The central claim of the project is simple: originality improves when builders can see the field they are entering. The
-app presents that field first. A full-screen Idea Map places projects by embedding similarity, draws nearest-neighbor
-links, and exposes clusters that would be difficult to infer from a feed of individual Spaces. Search and filters make
-the same evidence usable for targeted questions, such as "voice assistants", "local-first", or "quest classifier".
+The central claim of the project is simple: originality improves when builders can see the field they are entering. The app presents that field first. A full-screen Idea Map places projects by embedding similarity, draws nearest-neighbor links, and exposes clusters that would be difficult to infer from a feed of individual Spaces. Search and filters make the same evidence usable for targeted questions, such as "voice assistants", "local-first", or "quest classifier".
 
-This kind of visibility gives an online hackathon some of the generative character of OpenAI's Parameter Golf challenge:
-the event becomes more than a submission queue. It becomes a shared surface where participants can discover adjacent
-work, recognize partial overlap, borrow useful patterns, and extend ideas into new domains. A project similar to one's
-own can become evidence of a nearby direction; a project in another domain can suggest a feature, interface, or
-evaluation strategy that would otherwise remain invisible.
+This kind of visibility gives an online hackathon some of the generative character of OpenAI's [Parameter Golf](https://github.com/openai/parameter-golf) challenge: the event becomes more than a submission queue. It becomes a shared surface where participants can discover adjacent work, recognize partial overlap, borrow useful patterns, and extend ideas into new domains. A project similar to one's own can become evidence of a nearby direction; a project in another domain can suggest a feature, interface, or evaluation strategy that would otherwise remain invisible.
 
-The advisor, called The Unwritten Almanac, uses the same project snapshot to compare a proposed idea against nearby
-work. It cites overlapping projects, identifies whitespace, scores the idea with a deterministic rubric, and drafts a
-build plan. The output is meant to be useful before implementation begins: it helps a builder sharpen the audience,
-choose a tractable scope, and reduce accidental duplication.
+The advisor, called The Unwritten Almanac, uses the same project snapshot to compare a proposed idea against nearby work. It cites overlapping projects, identifies whitespace, scores the idea with a deterministic rubric, and drafts a build plan. The output is meant to be useful before implementation begins: it helps a builder sharpen the audience, choose a tractable scope, and reduce accidental duplication.
 
-The broader value is collective intelligence. When participants can find related work quickly, similar teams can learn
-from each other's approaches and the community can combine ideas while the event is still unfolding. The atlas helps
-good ideas become easier to find, easier to extend, and easier to improve.
+The broader value is collective intelligence. When participants can find related work quickly, similar teams can learn from each other's approaches and the community can combine ideas while the event is still unfolding. The atlas helps good ideas become easier to find, easier to extend, and easier to improve.
 
 ## User Experience
 
-The experience begins with exploration. A builder can search the atlas, inspect a cluster, open a project card, and see
-the evidence behind detected quest matches. The map is intentionally the first surface because it gives the advisor's
-later recommendations visible context.
+The experience begins with exploration. A builder can search the atlas, inspect a cluster, open a project card, and see the evidence behind detected quest matches. The map is intentionally the first surface because it gives the advisor's later recommendations visible context.
 
-When the builder opens The Unwritten Almanac, the app shifts from field reading to idea development. The workspace keeps
-an idea board, profile constraints, score seals, whitespace candidates, and export actions in one place. A session can
-produce field notes, an Almanac chapter, a shareable PNG, a demo bundle, and LoRA training materials. These artifacts
-become reusable records for review and submission.
+When the builder opens The Unwritten Almanac, the app shifts from field reading to idea development. The workspace keeps an idea board, profile constraints, score seals, whitespace candidates, and export actions in one place. A session can produce field notes, an Almanac chapter, a shareable PNG, a demo bundle, and LoRA training materials. These artifacts become reusable records for review and submission.
 
-The "Ask the atlas" drawer adds a second mode of interaction. It lets a builder ask structured questions about the
-current dashboard. Verified repository results appear before the model-written answer, and map actions can highlight or
-filter projects directly. The model's prose is grounded in a compact digest of the verified result.
+The "Ask the atlas" drawer adds a second mode of interaction. It lets a builder ask structured questions about the current dashboard. Verified repository results appear before the model-written answer, and map actions can highlight or filter projects directly. The model's prose is grounded in a compact digest of the verified result.
 
 ## Technical Design
 
-Hackathon Advisor is deployed as a Gradio `gradio.Server`, a FastAPI application with Gradio API endpoints. The visible
-interface is a custom HTML, CSS, and JavaScript frontend served from `static/`; the engine in `hackathon_advisor/`
-remains UI-agnostic.
+Hackathon Advisor is deployed as a Gradio `gradio.Server`, a FastAPI application with Gradio API endpoints. The visible interface is a custom HTML, CSS, and JavaScript frontend served from `static/`; the engine in `hackathon_advisor/` remains UI-agnostic.
 
 The runtime model stack is open-weight and local to the Space:
 
-- Advisor planning: `openbmb/MiniCPM5-1B` with a public advisor LoRA.
-- Quest classification: official Space metadata first, then `openbmb/MiniCPM5-1B` with a public quest-classifier LoRA
-  for evidence not declared by tags.
-- Retrieval: `ggml-org/embeddinggemma-300m-qat-q8_0-GGUF` through llama.cpp.
-- Voice input: `nvidia/nemotron-speech-streaming-en-0.6b` through NVIDIA NeMo ASR.
+- Advisor planning: [`openbmb/MiniCPM5-1B`](https://huggingface.co/openbmb/MiniCPM5-1B) with the public [`build-small-hackathon/hackathon-advisor-minicpm5-lora`](https://huggingface.co/build-small-hackathon/hackathon-advisor-minicpm5-lora) adapter.
+- Quest classification: official Space metadata first, then [`openbmb/MiniCPM5-1B`](https://huggingface.co/openbmb/MiniCPM5-1B) with the public [`build-small-hackathon/hackathon-advisor-quest-minicpm5-lora`](https://huggingface.co/build-small-hackathon/hackathon-advisor-quest-minicpm5-lora) adapter for evidence not declared by tags.
+- Retrieval: [`ggml-org/embeddinggemma-300m-qat-q8_0-GGUF`](https://huggingface.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF) through llama.cpp.
+- Voice input: [`nvidia/nemotron-speech-streaming-en-0.6b`](https://huggingface.co/nvidia/nemotron-speech-streaming-en-0.6b) through NVIDIA NeMo ASR.
 
-The advisor gives the 1B model a narrow, inspectable role. MiniCPM selects one advisor action per turn; Python then
-carries out the deterministic sequence over search, whitespace discovery, scoring, planning, profile constraints, and
-exports. This design keeps the user-facing response tied to retrieved evidence while preserving the small-model
-discipline of the hackathon.
+The advisor gives the 1B model a narrow, inspectable role. MiniCPM selects one advisor action per turn; Python then carries out the deterministic sequence over search, whitespace discovery, scoring, planning, profile constraints, and exports. This design keeps the user-facing response tied to retrieved evidence while preserving the small-model discipline of the hackathon.
 
-The atlas refresh method crawls public Spaces in the hackathon organization, reads each README and declared app file,
-builds a llama.cpp embedding index, resolves official `track:*`, `sponsor:*`, and `achievement:*` tags before invoking
-the quest LoRA for remaining evidence, validates the dashboard payload, and atomically swaps the new snapshot into the
-mounted Space cache. The last validated atlas remains available when a refresh fails, and many inspection routes remain
-usable while heavier models are unloaded.
+The atlas refresh method crawls public Spaces in the hackathon organization, reads each README and declared app file, builds a llama.cpp embedding index, resolves official `track:*`, `sponsor:*`, and `achievement:*` tags before invoking the quest LoRA for remaining evidence, validates the dashboard payload, and atomically swaps the new snapshot into the mounted Space cache. The last validated atlas remains available when a refresh fails, and many inspection routes remain usable while heavier models are unloaded.
 
 ## Validation Challenges
 
-The main engineering challenge was trust. A map is useful only when builders and judges can understand where its signals
-come from. The refresh process therefore preserves project metadata, README evidence, app-file evidence, embedding
-provenance, quest-analysis outputs, and manifest data for each validated snapshot.
+The main engineering challenge was trust. A map is useful only when builders and judges can understand where its signals come from. The refresh process therefore preserves project metadata, README evidence, app-file evidence, embedding provenance, quest-analysis outputs, and manifest data for each validated snapshot.
 
-Quest classification required additional care. Early prompt-only runs could rename quests, emit explanatory prose, or
-misread local-inference criteria. The final classifier is a supervised MiniCPM LoRA trained on real public Spaces, with
-a strict JSON schema and invariant checks behind every refresh. The write-up in
-[`docs/quest-classification-lora.md`](docs/quest-classification-lora.md) describes the dataset and validation path.
+Quest classification required additional care. Early prompt-only runs could rename quests, emit explanatory prose, or misread local-inference criteria. The final classifier is a supervised MiniCPM LoRA trained on real public Spaces, with a strict JSON schema and invariant checks behind every refresh. The write-up in [`docs/quest-classification-lora.md`](docs/quest-classification-lora.md) describes the dataset and validation path.
 
-The runtime also had to separate MiniCPM's PyTorch stack from llama.cpp on systems where OpenMP runtimes conflict. Query
-embedding on macOS runs in a worker subprocess, and dashboard refresh builds the GGUF index in a subprocess before
-returning to MiniCPM quest analysis.
+The runtime also had to separate MiniCPM's PyTorch stack from llama.cpp on systems where OpenMP runtimes conflict. Query embedding on macOS runs in a worker subprocess, and dashboard refresh builds the GGUF index in a subprocess before returning to MiniCPM quest analysis.
 
-## Codex Development Record
+## Codex Development
 
-Codex acted as an engineering collaborator throughout the build. It helped inspect the codebase, turn requirements into
-implementation slices, add the dashboard storage and search paths, build the quest-evidence UI, run tests, review
-deployed Space behavior, prepare the demo materials, and refine the submission documents.
+Codex acted as an engineering collaborator throughout the build. It helped inspect the codebase, turn requirements into implementation slices, add the dashboard storage and search paths, build the quest-evidence UI, run tests, review deployed Space behavior, prepare the demo materials, and refine the submission documents. The workflow was not only "ask for code, receive code"; it became a loop where Codex could read the repository, operate the app, inspect the result, and then revise the implementation or presentation from evidence.
 
-The project also preserves Codex's contribution as evidence. The public Git history includes Codex co-author trailers,
-and redacted Codex session traces are published at
-<https://huggingface.co/datasets/build-small-hackathon/hackathon-advisor-codex-traces>.
+The demo video was part of that loop. I used Codex with the [`studio-demo-video`](https://github.com/JacobLinCool/video-studio-mlx/tree/main/.agents/skills/studio-demo-video) skill to write a narrated storyboard, drive the live app, capture real screen footage, generate a voice-over, compose the final video, and check the result by reading extracted frames and ASR transcripts. That process used Codex's computer-use and vision abilities as practical production tools: it could operate UI surfaces, inspect whether focus rings and captions landed correctly, and verify that the spoken lines matched the intended scenes.
 
-## Fit For Build Small
+The local media backend behind this workflow was my in-progress Swift/MLX project, [Video Studio MLX](https://github.com/JacobLinCool/video-studio-mlx). That workflow points to a related lesson from the build: small local models are not only useful inside the submitted app; they can also support the way an agent builds, documents, and checks the app. I do not count this MLX tooling as part of Hackathon Advisor's hackathon runtime or model budget because it is not built with Gradio. It is still worth mentioning because it shows a possible agentic production path: write the script, use the product, generate narration, edit the video, and verify the artifact with simple visual and speech checks.
 
-Hackathon Advisor fits the Build Small constraints through its model budget and its product form. Every runtime model is
-under 4B parameters, the full stack is far below the 32B cap, and inference runs from open weights inside the Space
-process. MiniCPM is central to the advisor and quest classifier, llama.cpp powers retrieval, Nemotron supports voice
-input, Modal supports development compute, and Codex is part of the documented build record.
-
-The project is submitted for Thousand Token Wood because it makes the hackathon field navigable as an AI-native
-landscape. The atlas, Almanac, quest evidence, and exports give builders a way to see the surrounding work and produce a
-more deliberate idea from that evidence.
+The project also preserves Codex's contribution as evidence. The public Git history includes Codex co-author trailers, and redacted Codex session traces are published at <https://huggingface.co/datasets/build-small-hackathon/hackathon-advisor-codex-traces>.