docs: prepare hackathon submission package

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

.env.example

@@ -0,0 +1,24 @@
+# Local development example. Copy to .env only if your runner loads env files.
+# Do not put secrets in this file.
+
+ADVISOR_CACHE_DIR=.cache/advisor-dashboard
+ADVISOR_MODEL_BACKEND=rules
+ADVISOR_MODEL_ID=openbmb/MiniCPM5-1B
+ADVISOR_ADAPTER_ID=build-small-hackathon/hackathon-advisor-minicpm5-lora
+ADVISOR_ADAPTER_REVISION=25de69bcde397e1bcdd852923b56a42f10222650
+
+ADVISOR_QUEST_ANALYZER_BACKEND=rules
+ADVISOR_QUEST_ADAPTER_ID=build-small-hackathon/hackathon-advisor-quest-minicpm5-lora
+
+ADVISOR_EMBEDDING_MODEL_REPO=ggml-org/embeddinggemma-300m-qat-q8_0-GGUF
+ADVISOR_EMBEDDING_MODEL_FILE=embeddinggemma-300m-qat-Q8_0.gguf
+ADVISOR_EMBEDDING_N_CTX=2048
+
+ADVISOR_ASR_MODEL_ID=nvidia/nemotron-speech-streaming-en-0.6b
+
+# Deployed Space values, shown here for documentation only.
+# ADVISOR_ZERO_GPU=1
+# ADVISOR_ZERO_GPU_DURATION=120
+# ADVISOR_CACHE_DIR=/data/advisor-cache
+# ADVISOR_REFRESH_COMPUTE=cpu
+# ADVISOR_SCHEDULED_REFRESH_COMPUTE=cpu

.gitattributes

@@ -1,3 +1,4 @@
 # Auto detect text files and perform LF normalization
 * text=auto
+static/assets/*.mp4 filter=lfs diff=lfs merge=lfs -text
 static/assets/parchment.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -195,3 +195,7 @@ cython_debug/
 
 # Published LoRA adapter — lives on the Hugging Face Hub, not in git
 artifacts/quest-lora/
+
+# Local demo production workspace. Keep only curated public assets under static/assets/.
+demo-video/
+frames/

README.md

@@ -16,7 +16,21 @@ tags:
   - small-models
   - agent
   - originality
-  - off-the-grid
+  - track:wood
+  - sponsor:openbmb
+  - sponsor:openai
+  - sponsor:nvidia
+  - sponsor:modal
+  - achievement:offgrid
+  - achievement:welltuned
+  - achievement:offbrand
+  - achievement:llama
+  - achievement:sharing
+  - achievement:fieldnotes
+  - tiny-titan
+  - best-demo
+  - best-agent
+  - bonus-quest-champion
 models:
   - openbmb/MiniCPM5-1B
   - build-small-hackathon/hackathon-advisor-minicpm5-lora
@@ -45,8 +59,10 @@ of a continuously refreshed project atlas, and every advisor response is grounde
 - Live app: <https://build-small-hackathon-hackathon-advisor.hf.space>
 - Hugging Face Space: <https://huggingface.co/spaces/build-small-hackathon/hackathon-advisor>
 - Source code (GitHub): <https://github.com/JacobLinCool/hackathon-advisor>
-- Demo video: _TODO — add the hosted demo video URL before submission._
-- Social post: _TODO — add the public X/LinkedIn post URL before submission._
+- Demo video: <https://build-small-hackathon-hackathon-advisor.hf.space/static/assets/hackathon-advisor-demo.mp4>
+- Social post draft: [`docs/social-post.md`](docs/social-post.md) - publish it, then replace this line with the
+  public post URL before the final form submission.
+- 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.
 
@@ -61,6 +77,30 @@ The atlas is the default experience because the map is the evidence. The advisor
 where it uses the same project snapshot to cite overlap, propose whitespace, score the idea, draft a build plan, and
 export the session evidence.
 
+## Hackathon Submission
+
+Hackathon Advisor is submitted primarily for the **Thousand Token Wood** track. The product is useful to builders, but
+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 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: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.
+- `achievement:offgrid`: runtime inference is local to the Space process; no proprietary cloud inference API is called.
+- `achievement:welltuned`: the advisor and quest classifier use published MiniCPM LoRA adapters.
+- `achievement:offbrand`: the app uses a custom `gradio.Server` frontend instead of the stock Gradio interface.
+- `achievement:llama`: retrieval embeddings run through llama.cpp via `llama-cpp-python`.
+- `achievement:sharing`: redacted Codex build traces are published as a Hugging Face dataset.
+- `achievement:fieldnotes`: the repo includes build reports and field-note exports.
+
+Additional prize evidence for Tiny Titan, Best Agent, Best Demo, and Bonus Quest Champion is summarized in
+[`docs/submission-notes.md`](docs/submission-notes.md).
+
 ## What You Can Do
 
 - Explore a full-screen t-SNE atlas of public hackathon Spaces, with KMeans clusters and nearest-neighbor links.

docs/article.md

@@ -0,0 +1,85 @@
+# Hackathon Advisor: A Living Field Guide for Build Small
+
+Demo: <https://build-small-hackathon-hackathon-advisor.hf.space>  
+Demo video: <https://build-small-hackathon-hackathon-advisor.hf.space/static/assets/hackathon-advisor-demo.mp4>  
+Repository: <https://github.com/JacobLinCool/hackathon-advisor>  
+Space: <https://huggingface.co/spaces/build-small-hackathon/hackathon-advisor>
+
+## The Problem
+
+Build Small moves fast. Every builder is trying to make something local, useful, strange, or delightful under a strict
+model budget, but the field changes hour by hour. A good idea can already be crowded. A quiet niche can be invisible.
+Quest and sponsor fit can be buried in READMEs, model cards, and app files. The result is that builders spend too much
+of their scarce time guessing where their project sits.
+
+Hackathon Advisor turns the hackathon itself into the starting point. It is a live atlas of public
+`build-small-hackathon` Spaces and a small-model originality coach that helps a builder ask: what exists, what is nearby,
+what is still unwritten, and how could this idea become a focused submission?
+
+## The Experience
+
+The app opens on the Idea Map, not a chatbot. Each point is a public hackathon Space. Clusters show the shape of the
+field; nearest-neighbor links show which projects echo each other. A builder can search for a theme, filter by quest,
+open a project, and inspect evidence before asking the advisor for help.
+
+The advisor side is called The Unwritten Almanac. It compares an idea against the current project atlas, cites nearby
+projects, proposes whitespace, scores the idea, and drafts a build plan. The workspace can export field notes, an
+Almanac chapter, a page PNG, a demo bundle, and LoRA training materials.
+
+There is also an "Ask the atlas" drawer. It uses the base MiniCPM5-1B model's native tool calling to answer questions
+about the dashboard. Verified tool results render before the prose, and map actions can highlight or filter the atlas.
+
+## The Implementation
+
+The visible Space is a Gradio `gradio.Server`, which is a FastAPI server with Gradio API endpoints. The frontend is a
+custom HTML/CSS/JS interface served from `static/`; the engine in `hackathon_advisor/` stays UI-agnostic.
+
+The runtime model stack is fully open-weight and local to the Space:
+
+- Advisor planning: `openbmb/MiniCPM5-1B` plus a public advisor LoRA.
+- Quest classification: `openbmb/MiniCPM5-1B` plus a public quest-classifier LoRA.
+- 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.
+
+The advisor deliberately keeps the 1B model's job small. MiniCPM chooses one tool call per turn. Python then handles the
+deterministic orchestration: search, whitespace, scoring, planning, profile handling, exports, and response templates.
+This keeps behavior inspectable and avoids asking a tiny model to run an uncontrolled multi-hop ReAct loop.
+
+The atlas refresh path crawls public Spaces in the hackathon organization, reads each README and declared app file,
+rebuilds the llama.cpp embedding index, runs quest analysis, validates the dashboard payload, and swaps the result
+atomically into the mounted Space cache. A failed refresh leaves the last validated dashboard in place.
+
+## What Was Hard
+
+The hardest part was not drawing a map. It was making the map trustworthy enough for judges and builders.
+
+MiniCPM and llama.cpp can clash on OpenMP when loaded into the same hot path, so 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.
+
+Quest classification also needed discipline. A prompt-only classifier would rename quests, emit extra prose, or award
+Off the Grid to projects that used remote inference APIs. We built a supervised dataset from real public Spaces,
+fine-tuned a MiniCPM LoRA, and kept schema validation plus hard invariants in the refresh path.
+
+Finally, the Space needed to be useful even when GPU quota is tight. The atlas, search, exports, cached dashboard, and
+many inspection routes remain available without loading the heavy models.
+
+## How Codex Helped
+
+Codex acted as the engineering partner across the project. It helped inspect the codebase, break the work into
+implementation slices, build the dashboard storage and search paths, add quest evidence UI, write and adjust tests,
+debug deployed Space behavior, prepare commit history, publish redacted build traces, and turn the project into a
+submission-ready story.
+
+The project also uses Codex as evidence. Redacted Codex session traces are published at
+<https://huggingface.co/datasets/build-small-hackathon/hackathon-advisor-codex-traces>, and commits in the public GitHub
+repo include Codex co-author trailers.
+
+## Why It Fits Build Small
+
+Hackathon Advisor is small in the way the hackathon asks for: every model is under 4B, the full stack is far below the
+32B cap, and the runtime uses open weights instead of proprietary inference APIs. It is also complete: a public Space,
+a public repo, a demo video, a model/data trail, a custom interface, and a clear use case.
+
+The project belongs in Thousand Token Wood because it turns a hackathon into a navigable, AI-native landscape. The map,
+Almanac, quest evidence, and exports make the field feel alive while still grounding every suggestion in real public
+projects.

docs/social-post.md

@@ -0,0 +1,47 @@
+# Social Post Draft
+
+Use this after the demo video and Space are public. After posting, replace the README social-post line with the public
+post URL.
+
+## X / Twitter Draft
+
+I built Hackathon Advisor for #BuildSmall: a live atlas of the hackathon field plus a tiny-model originality coach.
+
+Search public Spaces, inspect project clusters, see quest evidence, ask the atlas what exists, then open The Unwritten
+Almanac to test whether your idea still has room to breathe.
+
+Runs local/open-weight:
+- MiniCPM5-1B + LoRA for tool planning
+- MiniCPM5-1B + LoRA for quest classification
+- EmbeddingGemma GGUF via llama.cpp
+- Nemotron Speech ASR via NeMo
+
+Codex helped turn this from a pile of project signals into a deployable Space: code, tests, debug passes, demo prep,
+submission docs, and co-authored commits.
+
+Demo: https://build-small-hackathon-hackathon-advisor.hf.space
+Video: https://build-small-hackathon-hackathon-advisor.hf.space/static/assets/hackathon-advisor-demo.mp4
+GitHub: https://github.com/JacobLinCool/hackathon-advisor
+
+#BuildSmall #Gradio #HuggingFace #OpenAICodex #MiniCPM #Nemotron #Modal
+
+## LinkedIn / Longer Draft
+
+I built Hackathon Advisor for the Build Small Hackathon.
+
+It is a live map of public Build Small Spaces and a small-model originality coach. Builders can search the field, inspect
+project clusters, review quest evidence, chat with the atlas, and open The Unwritten Almanac to compare an idea against
+what already exists.
+
+The runtime stays within the spirit of Build Small: open weights, no proprietary runtime inference API, and every model
+well under the 32B cap. MiniCPM5-1B handles tool planning and quest classification through LoRA adapters, EmbeddingGemma
+GGUF runs through llama.cpp for retrieval, and Nemotron Speech powers voice input through NVIDIA NeMo.
+
+Codex helped throughout the build: implementation planning, code changes, tests, deployed Space checks, demo preparation,
+submission notes, README polish, and commit history with Codex co-author attribution.
+
+Demo: https://build-small-hackathon-hackathon-advisor.hf.space  
+Demo video: https://build-small-hackathon-hackathon-advisor.hf.space/static/assets/hackathon-advisor-demo.mp4  
+GitHub: https://github.com/JacobLinCool/hackathon-advisor
+
+#BuildSmall #Gradio #HuggingFace #OpenAICodex #MiniCPM #Nemotron #Modal

docs/submission-notes.md

@@ -0,0 +1,96 @@
+# Hackathon Submission Notes
+
+Prepared on 2026-06-14 for the Build Small Hackathon submission deadline of 2026-06-15 23:59 UTC.
+
+Official guide: <https://build-small-hackathon-field-guide.hf.space/submit>  
+Live app: <https://build-small-hackathon-hackathon-advisor.hf.space>  
+Space: <https://huggingface.co/spaces/build-small-hackathon/hackathon-advisor>  
+GitHub: <https://github.com/JacobLinCool/hackathon-advisor>  
+Demo video: <https://build-small-hackathon-hackathon-advisor.hf.space/static/assets/hackathon-advisor-demo.mp4>
+
+## Official Checklist
+
+| Requirement | Status | Evidence / action |
+| --- | --- | --- |
+| Stay under 32B | Ready | All runtime models are below 4B; the full stack is documented at `/api/prize-ledger` and in `README.md`. |
+| Ship a Gradio app in the official org | Ready | Public Gradio Space: `build-small-hackathon/hackathon-advisor`; `/health` returns 200. |
+| Record a demo | Ready | Final demo video is committed at `static/assets/hackathon-advisor-demo.mp4` and served by the Space. |
+| Post it | Needs user action | Draft is in `docs/social-post.md`; publish it manually and replace the README draft link with the public post URL. |
+| Mind the GPU limit | Ready | Uses one ZeroGPU Space (`zero-a10g`) for this submission. |
+| Tag README | Ready | README front matter uses official `track:*`, `sponsor:*`, and `achievement:*` tags. |
+| Short write-up of idea and tech | Ready | README plus `docs/article.md` describe the problem, experience, architecture, quests, and Codex usage. |
+
+## Target Track
+
+| Track | Eligible? | Rationale |
+| --- | --- | --- |
+| Backyard AI | Not primary | The app is useful to hackathon builders, but it is not framed around one everyday personal task for a named nearby user. |
+| Thousand Token Wood | Yes | The project is an AI-native field guide: map, almanac, quest evidence, grounded originality coaching, and shareable artifacts. |
+
+README tag: `track:wood`.
+
+## Sponsor Prizes
+
+| Prize | Eligible? | Requirement | Evidence |
+| --- | --- | --- | --- |
+| Best MiniCPM Build | Yes | Build with MiniCPM models. | `openbmb/MiniCPM5-1B` is the advisor planner and quest-classifier base model. |
+| Best Use of Codex | Yes | Codex-attributed commits in connected GitHub repo or Space. | Public GitHub history includes Codex co-author trailers; README explains Codex role; trace dataset is published. |
+| Nemotron Hardware Prize | Yes | Build with Nemotron models. | `/api/transcribe` uses `nvidia/nemotron-speech-streaming-en-0.6b` through NVIDIA NeMo ASR. |
+| Best Use of Modal | Yes | Use Modal for development or runtime and note it in README. | Modal scripts train the quest LoRA and support remote index builds; README notes Modal development compute. |
+
+README tags: `sponsor:openbmb`, `sponsor:openai`, `sponsor:nvidia`, `sponsor:modal`.
+
+## Achievement Tags From The Submit Tool
+
+| Achievement | Eligible? | Evidence |
+| --- | --- | --- |
+| Off the Grid | Yes | Runtime inference uses local open weights on the Space; no proprietary remote inference API is in the runtime path. |
+| Well-Tuned | Yes | Advisor and quest-classifier MiniCPM LoRA adapters are public on Hugging Face. |
+| Off-Brand | Yes | Custom `gradio.Server` frontend in `static/`, not stock Gradio UI. |
+| Llama Champion | Yes | EmbeddingGemma GGUF retrieval runs through llama.cpp via `llama-cpp-python`. |
+| Sharing is Caring | Yes | Redacted Codex traces are published on the Hub, and the app exports shareable notes/PNG/bundles. |
+| Field Notes | Yes | `docs/quest-classification-lora.md`, `docs/blog-quest-lora.md`, `docs/article.md`, and field-note exports document the build. |
+
+README tags: `achievement:offgrid`, `achievement:welltuned`, `achievement:offbrand`, `achievement:llama`,
+`achievement:sharing`, `achievement:fieldnotes`.
+
+## Other Prize Table Fit
+
+| Prize / badge | Eligible? | Status |
+| --- | --- | --- |
+| Tiny Titan | Yes | Largest runtime model is MiniCPM5-1B at about 1.08B, well below 4B. |
+| Best Agent | Yes | MiniCPM selects tools; Python orchestrates search, whitespace, scoring, plans, exports, and atlas actions. |
+| Best Demo | Mostly ready | Demo video is ready; public social post still needs manual publication. |
+| Bonus Quest Champion | Yes | The submission satisfies the six achievement tags and multiple sponsor/extra prize criteria. |
+| Judges' Wildcard | Automatic | No separate entry required. |
+
+## Deployment Verification
+
+- `https://build-small-hackathon-hackathon-advisor.hf.space/health` returned HTTP 200 on 2026-06-14.
+- Space API reports `sdk: gradio`, `private: false`, `runtime.stage: RUNNING`, `hardware.current: zero-a10g`.
+- Runtime endpoint reports `backend: minicpm-transformers`, `model_id: openbmb/MiniCPM5-1B`, and `device: cuda`.
+- Mounted cache/storage is configured at `/data`.
+
+## Repository Hygiene
+
+- GitHub repository is public: <https://github.com/JacobLinCool/hackathon-advisor>.
+- `.env`, `.venv`, `.cache`, build artifacts, `node_modules`, local demo work files, and local frames are ignored.
+- `.env.example` contains safe non-secret defaults.
+- A secret-pattern scan found only placeholder/example strings and test fixtures, not real committed credentials.
+
+## Manual Remaining Step
+
+Publish one social post using `docs/social-post.md`, then update the README `Social post draft` line with the public URL
+before completing the official submission form.
+
+## Submission Form Summary
+
+Hackathon Advisor is a live atlas of the Build Small Hackathon and a small-model originality coach. It crawls public
+Build Small Spaces into a searchable map, shows project clusters and quest evidence, lets builders ask the atlas what
+exists, and opens The Unwritten Almanac to compare a new idea against nearby work, find whitespace, score originality,
+and export shareable field notes.
+
+The runtime is local/open-weight: MiniCPM5-1B plus LoRA for advisor tool planning, MiniCPM5-1B plus LoRA for quest
+classification, EmbeddingGemma GGUF through llama.cpp for retrieval, and Nemotron Speech ASR through NVIDIA NeMo for
+voice input. Every model is under 4B and the full stack is far below the 32B cap. Codex helped build, test, debug,
+document, and prepare the submission, with Codex co-author attribution in the public Git history.

static/assets/hackathon-advisor-demo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4083eab54424addeaaf8452ae9b960b508f79f208207f4d79bd8c7e1f705aac1
+size 31122881