AGENTS.md

DOX framework

• DOX is highly performant AGENTS.md hierarchy installed here
• Agent must follow DOX instructions across any edits

Core Contract

• AGENTS.md files are binding work contracts for their subtrees
• Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it

Read Before Editing

1. Read the root AGENTS.md
2. Identify every file or folder you expect to touch
3. Walk from the repository root to each target path
4. Read every AGENTS.md found along each route
5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX

Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.

Update After Editing

Every meaningful change requires a DOX pass before the task is done.

Update the closest owning AGENTS.md when a change affects:

• purpose, scope, ownership, or responsibilities
• durable structure, contracts, workflows, or operating rules
• required inputs, outputs, permissions, constraints, side effects, or artifacts
• user preferences about behavior, communication, process, organization, or quality
• AGENTS.md creation, deletion, move, rename, or index contents

Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.

Hierarchy

• Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
• Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
• Each parent explains what its direct children cover and what stays owned by the parent
• The closer a doc is to the work, the more specific and practical it must be

Child Doc Shape

• Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
• Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
• Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists

Default section order:

• Purpose
• Ownership
• Local Contracts
• Work Guidance
• Verification
• Child DOX Index

Style

• Keep docs concise, current, and operational
• Document stable contracts, not diary entries
• Put broad rules in parent docs and concrete details in child docs
• Prefer direct bullets with explicit names
• Do not duplicate rules across many files unless each scope needs a local version
• Delete stale notes instead of explaining history
• Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist

Closeout

1. Re-check changed paths against the DOX chain
2. Update nearest owning docs and any affected parents or children
3. Refresh every affected Child DOX Index
4. Remove stale or contradictory text
5. Run existing verification when relevant
6. Report any docs intentionally left unchanged and why

User Preferences

When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md

• User wants to be very ambitious for this hackathon
• User wants to go deep on manifold research, not just surface-level framing
• User prefers maximizing prize stacking across multiple categories

---

Project: Build Small Hackathon (Gradio)

Purpose

Gradio "Build Small" hackathon project. Build an ambitious HF Space powered by ≤32B models using Gradio, deployed under the hackathon org. Aiming for multiple prize categories.

Concept Direction (current — pivoted)

Activation Brain — A live comparative interpretability visualizer: two Gemma streams drive dual EEGs, baseline-corrected emotion deltas, model-native meters, and a generated comparison analysis panel. The prior 3D brain view was replaced because a single brain was less clear once both models run simultaneously. The user picks between two architecturally identical Gemma-4-12B models — google/gemma-4-12B-it (base) and OBLITERATUS/Gemma-4-12B-OBLITERATED (abliterated/uncensored) — sharing ONE UMAP frame so firing differences are directly comparable (a censored-vs-uncensored interpretability demo).

Pivot history: Started as "Activation Avatars" (Qwen3-4B hidden states → FLUX.2-Klein face + LivePortrait animation). Abandoned because per-token emotion mapping to a human face produced uncanny flicker (timescale/subspace mismatch — a face has affective inertia; fast multi-emotion change reads as noise). A brain/EEG is expected to fire fast across many regions simultaneously, so the pivot dissolved the core problem and deleted the fragile face stack (FLUX, LivePortrait, expression regressor).

Why two Gemmas (not Qwen): Qwen3-4B (36 layers, 2560 dim) is not comparable to Gemma (48 layers, 3840 dim). The two Gemma-4-12B models ARE identical, enabling a valid same-space comparison. Measured signature: abliteration drops the deep-shell (layer 36) activation norm (153.06→146.21) while surface/mid layers are unchanged.

• Goodfire AI's neural geometry research underpins the manifold approach (manifold steering, curved-manifold concepts, SAE limitations).

Hard Constraints

• Model ≤ 32B parameters
• Gradio app on HF Spaces under build-small-hackathon org
• Deadline: June 15, 2026
• Compute: $250 Modal credits + $20 HF credits + 40min/day ZeroGPU
• Submission: Space + demo video + social post
• Unlimited submissions allowed, max 10 ZeroGPU Spaces
• Can submit to both tracks

Models

• google/gemma-4-12B-it (base) — hidden-state source, 48 layers, 3840 dim, arch gemma4_unified, decoder hooks at layers 12/24/36, decoder path model.language_model.layers
• OBLITERATUS/Gemma-4-12B-OBLITERATED (abliterated/uncensored) — architecturally identical twin; shares hooks/dims/tokenizer → valid same-space comparison
• Both 12B (≤32B OK, but Tiny Titan ≤4B forfeited — traded for the censored-vs-uncensored interpretability demo)
• No image model in the hot path (FLUX/LivePortrait removed in the brain pivot)

Prize Targeting Strategy

Target	Prize	Path
🍄 Thousand Token Wood	$4,000 (1st)	Weird + delightful (live brain firing)
Modal	$10,000 credits (1st)	Serve both Gemmas on Modal
Community Choice	$2,000	Viral/shareable
Best Demo	$1,000	Real-time neuron firing + EEG
Judges' Wildcard	$1,000	Censored-vs-uncensored interpretability art
Bonus Quest Champion	$2,000	badges on main project
BFL	$5,000	forfeited (no FLUX in brain pivot)
Tiny Titan	$1,500	forfeited (12B > 4B cap)

Badge Strategy (per project, "single sash")

Main project badge paths (brain pivot):

• ✅ 🎨 Off-Brand — custom 3D-brain + EEG visualization UI (Three.js)
• ✅ 📡 Sharing is Caring — publish per-model brain bundles + neuron clouds on Hub
• ✅ 📓 Field Notes — blog post on manifold research + the abliteration deep-shell finding + the build
• ✅ 🎯 Well-Tuned — fine-tuned Ministral-8B-Instruct LoRA interpreter published as build-small-hackathon/activation-brain-interpreter; it translates hidden-layer-derived telemetry into comparison analysis
• ❌ 🦙 Llama Champion — dropped with Qwen (no 4B model in scope now)
• ❌ 🔌 Off the Grid — conflicts with Modal ($10k prize); 12B is hard to run local anyway

Prior Art & Research

• Milady project (/a0/usr/projects/milady): Activation Avatars — 3 trained adapter checkpoints (CrossAttention, MultiToken), ~2M params each. Maps Qwen3-4B layers 9/18/27 hidden states → FLUX.2-Klein prompt embeddings. 20 emotions. Results: milady-style face images per emotion.
• Goodfire research (May-June 2026): Neural geometry series. Key papers:
  • "The World Inside Neural Networks" — concepts on curved manifolds
  • "Steering Along Manifolds" — manifold steering >> linear steering on Llama 3.1 8B
  • "Geometric Calculator" — general-purpose addition module in layer 18 computing over circular geometry
  • "Can SAEs Capture Neural Geometry?" — SAEs shatter/dilute manifold structure
• Hackathon winners research: One-sentence pitch + instant wow, multi-agent clear roles, optimize experience not model, latency engineering wins, nail deliverables, community likes count

Architecture (deployed)

Public Technical Artifacts

• HF Dataset build-small-hackathon/activation-brain-artifacts publishes the reproducibility bundle: Gemma fingerprint JSONs, 627 affect-labeled probe prompts, manifold plots, manifold_processed.npz, summary report, fingerprinting script, analysis scripts, Modal backend reference code, and interpreter training/serving scripts.

• HF Model build-small-hackathon/activation-brain-interpreter publishes the fine-tuned Mistral-family LoRA interpreter adapter used for generated comparison analysis.

• The raw local manifold_data.pt hidden-state dump remains unpublished intentionally; use processed/public artifacts for submission evidence unless raw activations are explicitly requested.

• Modal gemma-brain app — two classes BaseGemma + OblitGemma (L40S), each loads its model + precomputed brain bundle, streams fire/token/done SSE. Hook path model.language_model.layers, hooks [12,24,36].

• Interpreter activation-brain-interpreter Modal app — serves the published build-small-hackathon/activation-brain-interpreter LoRA adapter on mistralai/Ministral-8B-Instruct-2410; /api/analyze proxies prompt + both responses + baseline-corrected deltas + native meters to generate varied plain-English analysis. Deterministic frontend analysis remains fallback.

• Frontend brain_app.py (Gradio + FastAPI) — per-model same-origin proxy routes /api/{neurons,init,stream}/{model} plus /api/analyze, serves static/brain_engine.js (dual EEG + comparison analysis UI). Dual concurrent mode (no dropdown): one Send opens TWO parallel SSE streams (base + oblit); each drives its own EEG strip (right column), both model responses are shown labeled in chat; the top row places chat/stats beside the live plain-English comparison-analysis card, and the two EEG/model panels sit beneath them; the analysis emphasizes what the divergence means for tone, warmth, caution, uncertainty, and shared-manifold trajectory rather than only listing metric values. Each EEG includes baseline-corrected emotion activation deltas (positive excess over the first 8 fire events of that response, not argmax counts) plus a calibrated baseline-corrected model-native state meter derived from live weights: uniform 0–100 Valence, Activation, Uncertainty, Constraint, activity-gated Conflict, and Warmth. mdLite() renders safe markdown + collapses degenerate loops. /api/stream/{model} uses an immediate SSE heartbeat and non-buffered synchronous upstream streaming so HF/Gradio proxies open the response before Modal emits first tokens.

• Fingerprints built by fingerprint_model.py (model-agnostic; shared UMAP fit on base, transform on oblit) → gemma4_{base,oblit}_{neurons.json,brain_bundle.pt} on Modal volume avatars-cache.

• Note: Gradio mounts gr.HTML asynchronously, so brain_engine.js must poll for #ab-brain before init (boot poller) — otherwise the canvas stays blank.

Key Documents

• BRIEFING.md — Full hackathon rules, prizes, timeline, strategy, badges, sponsor model catalog, winning playbook
• Tracker at /a0/usr/workdir/office-manager/tracker.json

Decision Log

Tracked in BRIEFING.md section 11.

Child DOX Index

No child directories yet. Will be created as project grows (e.g., src/, adapters/, notebooks/).