Kleidos Documentation Index#
Navigation map for all documentation under docs/. Each entry links to a real
file; every document in this tree appears exactly once.
Security#
Entry point: security/README.md — user-facing overview
plus auditor navigation to all security controls.
| Document | Description |
|---|---|
security/README.md |
Security overview: plain-language summary + controls-at-a-glance table |
security/threat-model.md |
Asset inventory, trust boundaries, in-scope threat taxonomy (T1–T17), out-of-scope clarifications |
security/vault-encryption.md |
AES-256-CBC envelope design, PBKDF2 key derivation, HKDF device binding, encrypt-then-MAC, sub-key labels, anti-rollback counters |
security/ble.md |
NimBLE SM configuration, LE Secure Connections, Numeric Comparison, RPA privacy, filter-accept-list, CVE-2025-62235 re-pair confirmation |
security/wifi.md |
WPA3-SAE SoftAP, AES-CCMP pairwise cipher, PMF, transition-disable, per-session random AP password |
security/wifi-admin-portal.md |
Session token generation, constant-time comparison, rate limiting, idle timeout, authenticated OTA route |
security/pin-and-bruteforce.md |
Timing Arc UX, NVS-persisted failure counter, BM8563 RTC lockout expiry, escalating lockout thresholds, vault wipe |
security/ota-and-boot.md |
esp_ota_ops app update flow, rollback guard, signed firmware images, BLE-before-WiFi teardown ordering |
security/key-material-and-logging.md |
mbedtls_platform_zeroize() and psa_destroy_key() call sites, HW-SHA/I2S race fix, credential exclusion from log paths |
security/flash-and-production.md |
Secure Boot v2 (RSA-3072), Flash Encryption, NVS encryption, JTAG disable, _secure env, secure_upload_guard.py |
security/audit-log.md |
Structured on-device event log: unlock, BLE session, admin portal, OTA, lockout, vault-wipe events; retention and read-out policy |
security/cve-register.md |
Tracked CVE entries against direct and transitive dependencies; mitigated/not-applicable status for each |
security/audit-dossier.md |
Auditor control matrix: evidence artifacts, test results, and residual-risk acceptances mapped to each threat ID |
security/checklist.md |
Release-preparation and security-review checklist with mechanically verifiable assertions |
security/template.mdis an internal authoring template and is not listed as a user document.
QA / Testing#
Entry point: testing/README.md — index of hardware QA
runbooks and the pytest system.
| Document | Description |
|---|---|
testing/README.md |
Testing directory overview and quick navigation |
testing/qa-system.md |
qa/ pytest system: single entry-point for serial, BLE, WiFi, and video HIL tests |
testing/ble-hid-hardware-qa.md |
Two-device BLE security, HID typing, reconnect, timeout, and stress testing runbook |
testing/hal-smoke-qa.md |
On-device HAL/diagnostic smoke tests |
testing/serial-debug-commands.md |
Every serial command exposed by *_debug builds: navigation, FSM, vault, BLE, WiFi, display, power |
testing/video-qa-capture.md |
Recording device UI in motion over WiFi (VIDEO serial commands and the qa/ video test) |
QA_CHECKLIST.md |
Manual QA test checklist for release verification |
Build & Variants#
| Document | Description |
|---|---|
building.md |
PlatformIO setup, build environments, flash procedures, CI/CD, mbedTLS 4 native install |
variants.md |
Supported hardware variants, capabilities, practical limits, and build target reference |
ota-updates.md |
Firmware update procedures, rollback protection, and browser-based flashing via ESP Web Tools |
device-identifiers.md |
Stable device-to-identifier map independent of the OS-assigned serial port node |
Architecture & Platform#
| Document | Description |
|---|---|
architecture.md |
System architecture, FSM design, module relationships, and data flow |
platform-abstraction.md |
RTOS/logging/platform facade rules, catalog of current facades, and future abstraction candidates |
Guides & Reference#
| Document | Description |
|---|---|
user-guide.md |
End-user manual: setup, daily use, credential management, troubleshooting |
developer-guide.md |
Guide for building, testing, and contributing to the Kleidos firmware |
api-reference.md |
Admin portal REST API served over WiFi AP at http://192.168.4.1 |
code-style-guide.md |
Kleidos C++ code style, naming conventions, and static analysis rules |
UI Library#
Entry point: ui/README.md — conceptual and architectural guide
for the in-house immediate-mode renderer.
| Document | Description |
|---|---|
ui/README.md |
UI library overview: render model, backend summary, host-test seam |
ui/architecture.md |
Render pipeline: Canvas → RasterCanvas → display:: → shadow framebuffer; dirty regions; AA path |
ui/tokens.md |
Design-token reference: color roles, spacing/radius scales, font roles, PPI-aware resolution, Mono1 collapse rules |
ui/layout.md |
LayoutContext, DeviceProfile, responsive breakpoints, flex/box helpers, per-geometry component queries |
ui/components.md |
Component catalog: every src/ui/components/ component, widgets, and the popup system |
ui/input.md |
2-/3-button, keyboard, and touch input model; house interaction convention; screen ownership of interaction |
ui/fonts.md |
AA atlas, size ladder, per-device subset, UTF-8→Latin-1 fold, 5 supported languages, atlas regeneration |
Design & Hardware#
| Document | Description |
|---|---|
brand-logos.md |
Embedded service-logo atlas pipeline, source policy, atlas generation, and verification |
design/font-integration.md |
Firmware typography policy: font roles, AA atlas integration, per-device subset strategy |
design/ui-iteration-handoff.md |
Design iteration notes and handoff record from mockup to firmware |
design/device-mechanics-cad.md |
Official CAD references, dimensions, and mechanical specs for device frames and onboarding animations |
design/mockups_v2/README.md |
Mockups V2 scope, device families, typography targets, and SVG reference files |
hardware/introspection/README.md |
HAL register-introspection engine: console command surface, critical-write gate, curated accessors, and one register-map page per chip |
hardware/introspection/bm8563-rtc.md |
BM8563 / PCF8563 battery-backed RTC backend (ClockTrust::Backed): register map, curated accessors, RTC-alarm deep-sleep wake |
hardware/introspection/rtc-internal.md |
ESP32 internal-RTC (volatile) backend for the no-I2C-RTC boards: ClockTrust model, tamper detection, fail-closed monotonic-countdown lockout, hard limits |
hardware/devices/README.md |
Per-device hardware index: specs, display, buttons, peripherals, chip info, pin maps |
hardware/devices/m5sticks3.md |
M5StickC Plus S3 (StickS3) — primary target; ESP32-S3, 135×240 TFT |
hardware/devices/cardputer-adv.md |
M5Cardputer ADV — ESP32-S3, QWERTY keyboard, 240×135 |
hardware/devices/tdeck.md |
LilyGo T-Deck Plus — ESP32-S3, 320×240, QWERTY + trackball + touch |
hardware/devices/cores3-se.md |
M5Stack CoreS3 SE — ESP32-S3, 320×240 |
hardware/devices/m5stickc-plus2.md |
M5StickC Plus2 — classic ESP32, 135×240 TFT |
hardware/devices/m5stack-gray.md |
M5Stack Gray — classic ESP32, 320×240 |
hardware/devices/core2-v13.md |
M5Stack Core2 v1.3 — classic ESP32, 320×240 |
hardware/devices/m5stickc-plus1.md |
M5StickC Plus 1.1 — classic ESP32, 4 MB flash, no OTA |
hardware/devices/m5core-ink.md |
M5Stack CoreInk — classic ESP32, e-paper, 4 MB flash, no OTA |
hardware/cad-sources/README.md |
CAD working area: official CAD, schematics, photos, and derived measurements for all devices |
hardware/cad-sources/_shared/schema.md |
Canonical measurements.json schema for device bounding boxes and dimensions |
hardware/cad-sources/_shared/photos/README.md |
Reference photos used for visual validation of SVG mockups |
Architectural Decisions#
Entry point: architectural_decisions/README.md
— index of all ADRs with status.
| Document | Description |
|---|---|
architectural_decisions/README.md |
ADR index, record structure, and how to read and update decisions |
architectural_decisions/0001-i18n-packed-string-pool.md |
Packed tail-merged i18n string pool instead of a pointer table (Accepted 2026-06) |
architectural_decisions/0002-vault-envelope-context-binding.md |
Vault envelope context binding and freshness anti-rollback (Accepted 2026-06) |