chore: polish FSOC repository for SIH presentation

.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: Build & Test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same ref (saves CI minutes on rapid pushes).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  cpp:
+    name: C++ (build + ctest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Ubuntu's apt cmake can lag the project's cmake_minimum_required (3.24);
+      # the pip wheel is always current and avoids guessing at the runner's
+      # preinstalled version.
+      - name: Install CMake + Ninja
+        run: python3 -m pip install --upgrade cmake ninja
+
+      - name: Install OpenCV (core, imgproc, imgcodecs, dnn)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libopencv-dev
+
+      - name: Configure (debug)
+        run: cmake --preset debug
+
+      - name: Build (debug)
+        run: cmake --build --preset debug
+
+      - name: Test
+        run: ctest --preset debug --output-on-failure
+
+  frontend:
+    name: Frontend (typecheck, lint, build, E2E)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Production build
+        run: npm run build
+
+      # playwright.config.ts uses channel:"chrome" (the system browser, not a
+      # Playwright-managed download) — install it explicitly rather than
+      # assuming it's preinstalled on the runner image.
+      - name: Install Google Chrome
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: stable
+
+      - name: End-to-end tests (Playwright, REPLAY fixtures)
+        run: npx playwright test

CHECKLIST.md

@@ -1,4 +1,8 @@
-# 48-Hour MVP Checklist — C++20
+# FSOC Engineering Checklist — C++20
+
+(Originally the "48-Hour MVP Checklist" for the initial baseline sprint; retitled as
+the project grew through Stage 2-4 AI perception and P0-v2 state estimation. Content
+below is a chronological, `[x]`-per-milestone engineering log, not a to-do list.)
 
 - [x] CMake/C++20 skeleton
 - [x] Frozen coordinate convention

docs/README.md

@@ -0,0 +1,57 @@
+# Documentation Index
+
+A reviewer's map through this repository's docs. Start at the top and go as deep as you
+need — nothing here duplicates another file; each doc is the single canonical source
+for what it covers.
+
+## Start here
+
+| doc | what it's for |
+|---|---|
+| [`SIH_MVP_FREEZE.md`](SIH_MVP_FREEZE.md) | The frozen SIH MVP state: build/test status, measured metrics, safe vs. unsafe claims for a judge presentation, exact demo commands |
+| [`MVP_GOLDEN_DEMO.md`](MVP_GOLDEN_DEMO.md) | The 15-step, fully reproducible judge-session walkthrough |
+| [`RELEASE_NOTES_v2_sih_mvp.md`](RELEASE_NOTES_v2_sih_mvp.md) | Draft GitHub release notes for the `v2_sih_mvp` tag (not yet published) |
+
+## Architecture
+
+| doc | what it's for |
+|---|---|
+| [`19_AI_PERCEPTION_ARCHITECTURE.md`](19_AI_PERCEPTION_ARCHITECTURE.md) | Classical + AI + Safe Hybrid fusion design (ADR-015 through ADR-018) |
+| [`09_FUTURE_ARCHITECTURE.md`](09_FUTURE_ARCHITECTURE.md) | The swappable-interface boundary for a future real-hardware port |
+| [`15_INTERFACE_CONTRACTS.md`](15_INTERFACE_CONTRACTS.md) | Frozen module boundaries and data contracts |
+| [`18_FRONTEND_DATA_CONTRACT.md`](18_FRONTEND_DATA_CONTRACT.md) | The C++ → frontend `DemoSnapshot` transport shape |
+| [`08_TELEMETRY_SCHEMA.md`](08_TELEMETRY_SCHEMA.md) | The 42-column CSV telemetry schema, field by field |
+| [`04_COORDINATES_AND_MATH.md`](04_COORDINATES_AND_MATH.md) | The frozen world/camera/image coordinate conventions |
+
+## Validation
+
+| doc | what it's for |
+|---|---|
+| [`MVP_METRICS.md`](MVP_METRICS.md) | Consolidated real measured numbers across every stage, including the full latency budget |
+| [`MVP_ABLATION.md`](MVP_ABLATION.md) | The clutter false-lock investigation, the state-estimator mitigation, and the A/B/C ablation, all measured |
+| [`21_AI_STAGE4_EVALUATION_PROTOCOL.md`](21_AI_STAGE4_EVALUATION_PROTOCOL.md) | The frozen Classical/AI/Hybrid evaluation protocol |
+| [`16_BASELINE_ACCEPTANCE.md`](16_BASELINE_ACCEPTANCE.md) | The 7 frozen Step-10 baseline acceptance gates |
+| [`07_TEST_AND_VALIDATION_PLAN.md`](07_TEST_AND_VALIDATION_PLAN.md) | The original test/validation strategy |
+
+## Design decisions
+
+| doc | what it's for |
+|---|---|
+| [`../DECISIONS.md`](../DECISIONS.md) | Every architecture decision (ADR-001 through ADR-019) with the evidence behind it |
+
+## Development history
+
+| doc | what it's for |
+|---|---|
+| [`DEVELOPMENT_HISTORY.md`](DEVELOPMENT_HISTORY.md) | The chronological Step 1 → Step 11 build log (moved out of `README.md` to keep the landing page judge-facing) |
+| [`archive/`](archive/) | Superseded, purely historical bookkeeping from the original Python→C++ starter-kit conversion |
+
+## Everything else
+
+`00_PROJECT_BRIEF.md` / `01_PRD.md` / `02_SRS.md` / `03_TECHNICAL_DESIGN.md` /
+`05_48_HOUR_ROADMAP.md` / `06_DEFINITION_OF_DONE.md` / `10_DEMO_AND_JUDGING_STORY.md` /
+`11_RISK_REGISTER.md` / `12_EXPERIMENT_PROTOCOL.md` / `13_GIT_WORKFLOW.md` /
+`14_TASK_BOARD.md` / `16_AI_CODING_GUARDRAILS.md` / `17_CLAUDE_CODE_USAGE.md` /
+`17_DEMO_FREEZE.md` / `20_AI_DATASET_AND_TRAINING.md` / `09_VISUALIZATION.md` — the
+original planning/process docs from each build phase. Still accurate for their scope;
+not duplicated or re-summarized here.

docs/RELEASE_NOTES_v2_sih_mvp.md

@@ -0,0 +1,84 @@
+<!--
+DRAFT release notes for tag v2_sih_mvp (already exists, points to cc8069e on main).
+NOT published. To publish once reviewed:
+
+  gh release create v2_sih_mvp \
+    --title "FSOC SIH 2026 Software MVP V2" \
+    --notes-file docs/RELEASE_NOTES_v2_sih_mvp.md \
+    --target main
+
+(--target is only needed if the tag doesn't already point where you want; it does,
+so this can be omitted. Add --draft to review on GitHub before publishing, or
+--latest to mark it as the repo's "Latest release".)
+-->
+
+## Project identity
+
+FSOC — autonomous closed-loop coarse alignment for mobile Free-Space Optical
+Communication (FSO) terminals. Smart India Hackathon 2026, problem statement SIH26169.
+A deterministic C++20 simulation of the full SEE → ESTIMATE → PREDICT → CORRECT loop:
+synthetic camera → classical + neural (TinyBeaconNet) perception → Safe Hybrid fusion →
+alpha-beta state estimation → PID pan/tilt control.
+
+## Major capabilities
+
+- Closed-loop pan/tilt tracking simulation with a validated PID baseline (`v1_baseline`).
+- Real TinyBeaconNet CNN (27,282 parameters) trained on a seeded synthetic dataset,
+  exported to ONNX, and run natively in C++ via OpenCV-DNN — no Python in the runtime path.
+- Safe Hybrid fusion policy (ADR-018): classical + AI cross-validation with unconditional
+  rejection on disagreement — no confidence overrides.
+- `TargetTracker`: a minimal alpha-beta state estimator with a temporal-consistency gate
+  and a bounded coast/reacquire state machine (ADR-019) — deliberately not a Kalman/UKF.
+- 5 named, deterministic demo presets (`normal`/`noise`/`occlusion`/`clutter`/`reacquisition`).
+- Next.js Mission Control frontend with live (ENGINE) and deterministic-replay (REPLAY)
+  telemetry modes, and a real-time "STATE ESTIMATOR" diagnostic panel.
+- GitHub Actions CI (C++ build+test, frontend typecheck/lint/build/E2E) on every push/PR.
+
+## Verified metrics
+
+All measured by committed, deterministic tools in this repository (`docs/MVP_METRICS.md`,
+`docs/MVP_ABLATION.md`, `docs/SIH_MVP_FREEZE.md`):
+
+- Step-10 baseline acceptance: **7/7 PASS**
+- C++ test suites: **17/17** (100%)
+- Frontend end-to-end tests: **20/20**
+- Severe (>50px) closed-loop outliers: Classical 2,240 → Classical+Tracker 12;
+  Hybrid 1,808 → Hybrid+Tracker 9 (**~99.5% reduction** in both cases)
+- Full-step latency, Hybrid+Tracker, P95: **~1.2 ms** against a 20 ms / 50 Hz budget
+  (development-machine CPU, not a hardware claim)
+- Telemetry: 42-column real CSV export
+
+## Demo commands
+
+```bash
+cmake --preset debug && cmake --build --preset debug && ctest --preset debug
+./build/debug/fsoc_demo normal
+./build/debug/fsoc_demo clutter
+./build/debug/fsoc_demo occlusion
+./build/debug/fsoc_demo reacquisition
+cd frontend && npm install && npm run dev   # http://localhost:4317
+```
+
+Full 15-step judge walkthrough: `docs/MVP_GOLDEN_DEMO.md`.
+
+## Known limitations
+
+- A temporally coherent (smoothly moving) distractor defeats the clutter mitigation
+  completely — a disclosed, currently-unresolved gap.
+- The intrinsic single-frame classical false-positive rate (44.9%) is unchanged;
+  unfixable without modifying the frozen classical detector algorithm.
+- AI-only reacquisition through the fusion policy is not implemented (deliberately
+  deferred, ADR-019).
+- Real coverage cost: the clutter mitigation trades ~20 points of coverage for the
+  outlier reduction above.
+
+## Hardware boundary
+
+Zero physical camera, beacon, servo, or pan/tilt hardware has been used anywhere in
+this project. Every metric above is from the deterministic C++ simulation on a
+development machine. No embedded/flight/hardware real-time performance claim is made.
+
+## Full details
+
+`docs/SIH_MVP_FREEZE.md` is the canonical source for this release's build/test status,
+safe vs. unsafe claims for presentation, and exact reproduction commands.

FILES.txt → docs/archive/FILES.txt

@@ -1,3 +1,7 @@
+# ARCHIVED: a stale, manually-maintained file listing from early in the project. Does
+# not reflect the current repository tree (hundreds of files added since). Kept for
+# history only — use `git ls-files` for a current listing.
+
 .clang-format
 .clang-tidy
 .claude/agents/gnc-geometry-engineer.md

KIT_MANIFEST.md → docs/archive/KIT_MANIFEST.md

@@ -1,3 +1,8 @@
+> **Archived.** Written at the very start of the project (Python→C++ starter-kit
+> conversion); the "63 files" count and asset list are historical, not current. Kept for
+> engineering-history continuity, not as a live reference — see `docs/README.md` for the
+> current documentation index.
+
 # Kit Manifest
 
 This is the C++20 replacement for the original Python FSOC Vibe Coding starter.

MIGRATION_FROM_PYTHON.md → docs/archive/MIGRATION_FROM_PYTHON.md

@@ -1,3 +1,6 @@
+> **Archived.** A one-time bookkeeping note from the original Python→C++20 conversion at
+> the very start of the project. Purely historical.
+
 # Migration From Python Starter
 
 The project has been converted to C++20.

VALIDATION.txt → docs/archive/VALIDATION.txt

@@ -1,3 +1,7 @@
+# ARCHIVED: a manually-appended, Step-1-era validation log. Fully superseded by
+# docs/16_BASELINE_ACCEPTANCE.md, docs/MVP_METRICS.md, and docs/SIH_MVP_FREEZE.md,
+# which are the current, canonical sources for measured results. Kept for history only.
+
 SIH26169 FSOC C++ starter validation
 
 Validated in packaging environment with CMake 3.31 / C++20: