The more specific the requirement, the more likely the assistant is to implement it correctly in one pass. Useful details include:

• User flow: what each page displays and what short press, double press, and long press do for each button.
• State and data: whether the application needs timing, persistence across power loss, networking, recording, or communication with a computer.
• Experience goals: fonts, colors, animation, sound, response time, and error states.
• Constraints: application navigation and controls, permitted dependencies, and Flash/data usage. The baseline test menu is not an application UI option.
• Acceptance criteria: which behaviors require automated tests and which must be observed on real hardware.

When details are omitted, the assistant may choose conservative defaults that do not change the product direction, but it must list those assumptions in the delivery. Decisions involving new wiring, electrical safety, board revisions, or irreversible data formats require confirmation first.

Inspect an example without switching the current working tree:

git branch -r --list 'origin/demo/*'
git diff main...origin/demo/tetris-game -- main components tests
git show origin/demo/tetris-game:main/demo_tetris.c

Start a new application. This repository hosts several independent projects on one baseline: after starting from main, create a feature/* branch and develop the application there — do not develop directly on main. Each project's final branch is feature/* (e.g. feature/my-passport-app), kept separate so main stays a clean upstream baseline and the projects do not entangle.

git switch main
git switch -c feature/my-passport-app

Example branches may change the same menu, configuration, or driver in incompatible ways. Understand the differences before extracting a state model, asset pipeline, or concurrency pattern. Code appearing in an example branch is not automatically part of the current main BSP contract.

The table below describes the application capabilities implemented by the current main branch. It is not a list of everything that might be possible according to the chip datasheet.

All pins, addresses, panel parameters, and button voltage windows are defined only in components/bsp/include/bsp_pins.h. Application code must not duplicate these constants. See the AI Hardware Development Guide for the complete pin map, panel initialization, ADC thresholds, I2C addressing rules, audio clocks, and memory details.

Applications may also use ESP-IDF timers, FreeRTOS tasks, and internal Flash/NVS; the Pomodoro branch contains an NVS example. Wi-Fi and Bluetooth LE remain ESP-IDF application services rather than BSP APIs: their menu pages initialize each stack only while open and release it on exit. demo/claude-buddy-port remains a fuller BLE application architecture reference, not a substitute for measuring the current board's antenna, RF performance, power consumption, and coexistence behavior.

Capabilities outside the current contract

The public firmware contract is limited to the interfaces listed above. Do not infer additional board interfaces from the ESP32-C3 feature list. New hardware interfaces require an explicit BSP definition and on-device acceptance criteria.

components/bsp/include/  Public BSP APIs and bsp_pins.h hardware facts
components/bsp/src/      Display, button, audio, battery, and shared-I2C implementations
main/                    Minimal menu, LVGL UI, and independent hardware demo pages
tests/                   Lightweight logic tests that can run without hardware
tools/                   Shared local/CI validation and firmware verification scripts
docs/                    Project docs, changelog, engineering/contribution rules, and design references
.github/                 GitHub community files, PR template, issue forms, and CI workflows
sdkconfig.defaults       ESP32-C3, USB console, Flash, and LVGL defaults
partitions.csv           Minimal default: NVS, PHY data, and one factory application
dependencies.lock        Reproducible ESP-IDF Managed Component resolution
AGENTS.md                Mandatory AI-agent entry point (paired with AGENTS.zh_CN.md)
CLAUDE.md                Claude Code pointer to AGENTS.md (paired Chinese version)
LICENSE                  Repository license