chore: checkpoint before lint autofix

documentation/agents/README.md

@@ -0,0 +1,20 @@
+# Agent Documentation
+
+Store long-form guidance for coding agents here.
+
+## Suggested Files
+
+- `documentation/agents/architecture.md`: subsystem boundaries, data flow, invariants.
+- `documentation/agents/build-and-test.md`: canonical commands, fast checks, CI mapping.
+- `documentation/agents/style-and-lint.md`: formatting policy, lint severity, suppression rules.
+- `documentation/agents/refactor-playbook.md`: safe refactor steps, rollout strategy, risk controls.
+- `documentation/agents/frontend_requirements_context.md`: requirements-first UI context, size budgets, and migration constraints.
+- `documentation/agents/module-notes/<module>.md`: module-level constraints and edge cases.
+
+## Writing Rules
+
+- Keep files operational and concrete.
+- Prefer checklists and explicit commands.
+- Record known pitfalls and non-obvious invariants.
+- Link back from `AGENTS.md` only to docs that are actively maintained.
+- When frontend payload/routes/contracts change, refresh the snapshot with `build-scripts/ui_footprint_snapshot.sh` and update `frontend_requirements_context.md`.

documentation/agents/frontend_requirements_context.md

@@ -0,0 +1,201 @@
+# Frontend Requirements Context (Living)
+
+Status: Active  
+Last reviewed: 2026-02-12  
+Review scope: `components/wifi-manager/webapp`, `components/wifi-manager/http_server_handlers.c`, `components/wifi-manager/wifi_manager_http_server.c`, `spiffs_src/CMakeLists.txt`
+
+## Purpose
+
+This document captures reverse-engineered **product requirements** for the embedded web UI, with measurable constraints.  
+It is intentionally not an implementation walkthrough.
+
+Use this as session handoff context for UI refactoring and footprint control.
+
+## Snapshot Findings (Current State)
+
+### 1. What actually ships to firmware
+
+SPIFFS packaging currently copies only:
+
+- `components/wifi-manager/webapp/dist/*.gz`
+- `components/wifi-manager/webapp/dist/*.png`
+
+Evidence: `spiffs_src/CMakeLists.txt`.
+
+Current shipped web payload:
+
+- Total shipped bytes: `219741` (`~214.6 KiB`, `~0.21 MiB`)
+- Largest asset: `dist/js/node_vendors.bundle.js.gz` (`166729` bytes)
+
+### 2. What looks large but is not currently shipped
+
+- `dist/` total is about `4.5M`, dominated by source maps (`*.map`).
+- Source maps are large in repo artifacts, but not copied to SPIFFS by current packaging.
+
+### 3. Major technical debt signal
+
+- UI source references many legacy endpoints (`/status.zzz`, `/messages.zzz`, `/commands.zzz`, etc.).
+- Active server registration in `wifi_manager_http_server.c` is centered on `/data.bin` + static handlers; many legacy handlers are commented out.
+
+This indicates API/contract drift and unclear migration state.
+
+### 4. Modularity and proto usage signal
+
+- Main UI logic is largely monolithic in `src/js/custom.ts` (~2.5k LOC).
+- `index.ts` imports generated protobuf bundle (`configuration_pb.js`) up front.
+- `dist/js/index.bundle.js` includes many generated proto message definitions, not only request/response minimum set.
+
+Implication: upfront JS parse/execute and bundle weight are likely higher than needed.
+
+## Reverse-Engineered Product Requirements
+
+These are the requirements we should preserve while refactoring.
+
+### RQ-UI-001 Captive Portal Bootstrap
+
+The UI must reliably open and render from AP/captive-portal entry points with no manual URL knowledge.
+
+Acceptance:
+
+- Landing page reachable from captive portal probes.
+- First meaningful controls visible without requiring cloud services.
+
+### RQ-UI-002 Network Onboarding and Recovery
+
+Users must be able to scan APs, join/disconnect Wi-Fi, and understand current link mode (Wi-Fi vs Ethernet) with clear status.
+
+Acceptance:
+
+- Scan, connect, disconnect workflows remain available and understandable.
+- Connection state transitions are visible and unambiguous.
+
+### RQ-UI-003 Runtime Observability
+
+Users must see operational status and logs needed for diagnosis (network, playback, OTA progress, errors).
+
+Acceptance:
+
+- Status view remains available in normal and recovery mode.
+- Error and warning paths are visible in UI without dev tools.
+
+### RQ-UI-004 Safe Configuration Editing
+
+Users must be able to view/edit/apply configuration with guardrails (validation feedback, clear commit/apply behavior).
+
+Acceptance:
+
+- Config edit path supports both selective and global update actions.
+- Validation errors are explicit before/after submit.
+
+### RQ-UI-005 OTA Operations
+
+Users must be able to trigger firmware update by URL or upload, with progress and failure feedback.
+
+Acceptance:
+
+- OTA action always yields deterministic status progression or explicit terminal error.
+- Recovery path remains accessible if normal OTA path fails.
+
+### RQ-UI-006 Advanced Control Access
+
+Power-user controls (commands/NVS/diagnostics) must exist but should not degrade common-task UX.
+
+Acceptance:
+
+- Advanced functions remain accessible.
+- Main tasks are not blocked by advanced UI complexity.
+
+### RQ-UI-007 Backward Compatibility Envelope
+
+The UI must support currently deployed firmware API variants during migration (legacy and protobuf-era endpoints), with explicit deprecation strategy.
+
+Acceptance:
+
+- Contract compatibility matrix is documented and tested.
+- Legacy paths have clear sunset criteria.
+
+### RQ-UI-008 Embedded Footprint Discipline
+
+Web assets must stay within explicit firmware budget and be measurable in CI.
+
+Acceptance:
+
+- Shipping budget exists and is enforced.
+- Size regressions fail checks unless explicitly approved.
+
+## Non-Functional Budgets (Proposed)
+
+These are targets, not yet enforced:
+
+- `NB-001` Shipped web payload (`*.gz` + `*.png` in `dist/`) <= `180 KiB` target, `220 KiB` hard cap.
+- `NB-002` Main JS gzip <= `120 KiB` target.
+- `NB-003` Vendor JS gzip <= `120 KiB` target.
+- `NB-004` No runtime dependency on external CDNs for critical UI function.
+- `NB-005` One canonical API transport for new features (`/data.bin` protobuf), with compatibility shim for legacy endpoints during migration only.
+
+## UX + Footprint Improvement Directions
+
+Prioritized by impact/risk.
+
+### P1 Contract Unification (High impact, medium risk)
+
+- Define one frontend API client contract around protobuf request/response.
+- Treat legacy `.zzz` paths as compatibility layer, not primary path.
+- Add explicit compatibility table (firmware version -> supported endpoints).
+
+### P2 Modularization by Capability (High impact, medium risk)
+
+- Split monolithic UI logic into capability modules:
+  - onboarding
+  - status/logs
+  - config editor
+  - OTA
+  - advanced
+- Lazy-load non-critical modules (advanced, release browser, heavy editors).
+
+Expected result: lower startup JS cost and clearer ownership boundaries.
+
+### P3 Proto Surface Minimization (High impact, medium risk)
+
+- Stop importing broad generated config surface on initial load.
+- Create thin protobuf DTO layer for startup-critical flows.
+- Load heavy schema modules only when entering related screens.
+
+### P4 UI Responsiveness and Clarity (Medium impact, low risk)
+
+- Replace mixed polling patterns with a single scheduler and explicit backoff policy.
+- Standardize in-progress/error/success state rendering across all actions.
+- Reduce ambiguous icon-only cues with text fallback in constrained/offline contexts.
+
+### P5 Build Output Hygiene (Medium impact, low risk)
+
+- Keep generating sourcemaps for dev/debug if needed, but separate from shipping artifact workflow.
+- Enforce shipped-size budget on what SPIFFS actually receives, not raw `dist/`.
+
+## Living Maintenance Protocol
+
+This file must be updated when any of the following changes:
+
+- web routes/endpoints
+- protobuf request/response schema used by UI
+- shipped asset packaging rules
+- significant UI feature flow
+
+Required update steps:
+
+1. Run `build-scripts/ui_footprint_snapshot.sh`.
+2. Update Snapshot Findings and budget deltas in this file.
+3. Update compatibility notes if API contract changed.
+4. Add an entry to Decision Log.
+
+## Decision Log
+
+| Date | Decision | Why | Follow-up |
+|------|----------|-----|-----------|
+| 2026-02-12 | Treat this file as requirements-first context, not implementation notes | Reduce drift and speed up session handoffs | Add CI size gate and API contract checks |
+
+## Open Questions
+
+- Are legacy `.zzz` endpoints still required for deployed firmware versions, and for which versions exactly?
+- Is the intended long-term model pure protobuf over `/data.bin` for all dynamic data?
+- What startup latency target is acceptable on AP-mode captive portal connections?