Commander1024
901afbe754
- Add measured F.Fab bounds and USB mouth markers - Add guarded preservation and regression validation - Refresh review exports and remove draft presentation labels
Developer documentation
This directory collects implementation contracts, research, design decisions, regression procedures, and historical acceptance evidence. It is not the operator manual: start with the project README for user documentation, the command reference for commands, and the security operations checklist for safe operation. Wiring and electrical tests remain beside the user documentation because hardware safety and bring-up need that context.
Firmware contracts and evidence
-
Flash partition layout: storage allocation, reserved partitions, and update boundaries.
-
Roadmap and acceptance record: completed phases, retained scope, historical evidence, and limits of acceptance.
-
Web administration contracts: contributor-facing API, ownership, lifecycle, and recovery details.
-
User/administration regression procedures: reusable checks, including historical baselines explicitly marked as superseded.
-
HTTPS idle cleanup: HTTPD owner, SDK, and lifecycle contract.
-
Web admission diagnostics: instrumentation and interpretation limits.
-
Web throughput diagnostics: counters, capture procedures, and evidence limits.
-
Display design references: Phase 7 display mockup and Phase 7C icon mockup, not promises of current UI appearance.
Source code is authoritative for current behavior. A checklist is not a test result; host doubles do not prove target timing, flash durability, power-loss recovery, or physical electrical safety. Preserve dates, revisions, workload details, and explicit limitations when recording new evidence. Overall user acceptance does not establish that every proposed regression procedure was executed.
Markdown links are document-relative. Unless explicitly stated otherwise, source, build, and test paths in code spans and commands are repository-root-relative. Hardware notes identify retained artifact paths and any different command directory.
Tests and asset provenance stay with their artifacts
Test fixtures, scripts, and contextual READMEs remain under tests. Examples include the HTTPD idle suite, admission diagnostics suite, web administration suite, and browser UI suite. Read each suite's scope, prerequisites, and execution instructions rather than assuming a single host-test command. These links are navigation, not claims that tests ran during documentation cleanup.
Web asset provenance and generation policy remains with the web assets. Do not hand-edit generated embedded assets or regenerate them as a side effect of documentation changes; preserve upstream licenses and attribution.
Hardware research and design notes
The contextual PCB README stays with the editable KiCad project, CAD, libraries, exports, and scripts. The board remains a draft, not fabrication-ready. Development notes preserve the hardware-relative substructure:
- Adafruit MAX3243 research
- Button selection and evidence
- DE-9 mechanical research
- Module footprint notes
- RS-232 reference footprint notes
- PCB draft design and release gates
- Routing validation and historical evidence
Original reference/provenance READMEs remain beside their sources: Adafruit Eagle reference and DE-9 CAD reference. Relocation does not change licenses, validate provisional male-module assumptions, or qualify the board for manufacture. Do not casually rerun destructive generators; use the retained hardware README and each script's documented safeguards.
Security maintenance and evidence
Contributor maintenance includes reviewing relevant ESP-IDF, wolfSSL/wolfSSH, and bundled web-library upstream release/security notes, especially before an update. A relevant issue needs a separate upgrade/mitigation decision and scoped validation; this is not an ongoing CVE audit or a claim that the firmware is vulnerability-free. Dependency patches, crypto upgrades, secure boot, encrypted NVS, and eFuse changes are outside the accepted lightweight operating-checklist scope, not implicit work items or properties of a deployed device. See the Phase 9 record.
The original security checklist's commands and limits were source-reviewed against
application sources and the command reference at f40c09c. That provenance is not
a new build, device test, security audit, or verification of flash/eFuse settings;
verify current implementation when behavior changes. Keep the operator checklist
focused on actionable use and recovery rather than contributor dependency work.
Never put passwords, cookies, tickets, Wi-Fi secrets, private keys, or verifier
material in routine logs, documentation captures, or status output.