Choose a task below. User guides explain observable behavior; developer references define implementation and validation contracts. Follow links as needed rather than reading the entire directory.
- First setup and daily use
- Hardware and installation prerequisites
- Build, test, and USB installation
- Troubleshooting, USB commands, recovery
- Firmware updates (OTA), screenshots
- Brew by weight, presets
- Tare and retare, cup protection
- Fast and slow shots, scale-loss backup
- Alerts, shot history, activation history
- Home Assistant integration
- Generic webhooks
| Group | Reference |
|---|---|
| Physical switch | Paddle / momentary |
| Machine integration | La Marzocco Linea Micra |
| Without a scale / rinse | No-scale BBW / quick rinse |
| Scale and cup | Scales / Bluetooth on/off / cup detection / tare |
| Network | Wi-Fi / access point / device name |
| Energy | Power management |
| Interface | Theme / shot card colors |
| Reset | Factory reset / firmware mode |
Start with Contributing and the applicable AGENTS.md.
Temporary working files live in Git-ignored temp/ inside the local project.
Development plans live in Git-ignored docs/plans/, and audits in Git-ignored
docs/audits/. Each plan or audit is its own progress record and session handoff.
Their contents are not onboarding or background context: read them only when the
user explicitly requests reading or working with a plan or audit, or when they
are referenced within two levels from that requested record. See the
record access rule.
See the shared format and recovery procedure.
All three directories belong to the local project and remain accessible from
the IDE; see local storage and Git.
Use documentation maintenance to
identify which guides to update when settings, scripts, or behavior change.
The map below identifies the smallest relevant sources and tests.
./scripts/dev context <area> lists focused paths, not file contents; supported
areas are safety, control, machine, scale, ble, network, ota, persistence, web,
build, and tests. There is no docs area.
File names in the table are relative to this directory unless a source path or root policy is named. Commands are starting points, not substitutes for the risk gate in VALIDATION.md.
| Need | Documentation | Editable sources | Tests | Command |
|---|---|---|---|---|
| Safety and relay | PROJECT_CHARTER.md, HARDWARE.md, MANUAL_TEST_PLAN.md |
src/OpenBrewByWeightSafety.h, src/OpenBrewByWeightMachineRelay.h, src/OpenBrewByWeightHardware* |
safety_external_host_test.cpp, main host scenarios |
./scripts/dev validate --risk R3 |
| Control/brew | ARCHITECTURE.md, STATE_MACHINES.md, feature docs |
src/OpenBrewByWeightBrew*, src/OpenBrewByWeightDomain.h |
open_brew_by_weight_host_test.cpp |
./scripts/dev test normal |
| Machine inputs | HARDWARE.md, settings/paddle.md, settings/momentary.md |
src/OpenBrewByWeightMachine* |
momentary_machine_host_test.cpp, main host tests |
./scripts/dev validate --risk R3 |
| Scale sensing | ARCHITECTURE.md, CONCURRENCY.md |
src/OpenBrewByWeightScale* |
main host tests | ./scripts/dev test normal |
| BLE protocols | library README, CONCURRENCY.md |
libraries/EspressoScaleBLE/src/, src/OpenBrewByWeightScaleWorker.cpp |
library tests, main host BLE-scan cases | ./scripts/dev test ble |
| Network/Webhooks | feature docs, RESOURCE_OWNERSHIP.md |
src/OpenBrewByWeightNetwork*, src/OpenBrewByWeightWebhook* |
webhook_error_host_test.cpp, Web contract tests |
./scripts/dev validate --risk R2 |
| Integration API | INTEGRATION_API.md |
network/webhook sources | shared JSON fixtures and integration tests | ./scripts/dev validate --risk R3 |
| Firmware OTA | features/ota.md, features/ota-image-identity.md, EMERGENCY_RECOVERY.md |
scripts/internal/ota-idf, src/ShotStopperOta* |
OTA host, CLI, and Web resilience tests | ./scripts/dev test ota |
| Persistence | ARCHITECTURE.md, settings docs |
src/OpenBrewByWeightPersist*, durable stores/logs |
persistence_host_test.cpp |
./scripts/dev test normal |
| Web UI | SCREENSHOTS.md, feature/settings docs |
src/web/ |
Web asset/contract tests | ./scripts/dev test web |
| Build and partitions | BUILD.md, SCRIPTS.md, STATIC_ANALYSIS.md |
idf/, build scripts |
profile, architecture, and size checks | ./scripts/dev profiles |
| Hardware/machine build profiles | BUILD_PROFILES.md |
config/hardware/, config/machines/, profile resolver |
profile contract tests | ./scripts/dev test tooling |
| Scheduling/resources | SCHEDULABILITY.md, P2_RESOURCE_BUDGETS.md, P2_TARGET_TRACE.md |
task/owner/watchdog headers | TSAN and resource-owner tests | ./scripts/dev test tsan |
| Developer tooling | AI_WORKFLOW.md, root VALIDATION.md |
scripts/, .github/ |
dev contract and risk golden tests | ./scripts/dev test tooling |
- Canonical firmware:
src/; Web source:src/web/; BLE library:libraries/EspressoScaleBLE/; ESP-IDF integration:idf/. - Generated:
src/OpenBrewByWeightVersion.h,src/OpenBrewByWeightWebAssetsGzip.h, build trees, reports, andartifacts/. - Local plans:
docs/plans/; local audits:docs/audits/. Both are retained locally, excluded from Git, and serve as their own session handoffs. - Local temporary working files:
temp/, inside the project and excluded from Git. Keep task-specific files accessible from the IDE; Git exclusion does not mean storing files outside the project. - Vendored/dependency output:
idf/managed_components/andnode_modules/. Do not review or load these trees unless dependency provenance itself is the task. Lockfiles and IDF configuration remain visible and reviewable. - Current safety authority is the charter, validation policy, architecture documents, and manual test plan.