diff --git a/AGENTS.md b/AGENTS.md index 4e29302..0d04635 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,9 @@ Three board targets share business logic via a common library: All commands run via **mise**: ```bash +# Running multiple tasks - use && to chain them +mise run compile && mise run upload && mise run monitor + # Install all dependencies (shared libs + vendored display libs) mise run install-libs-shared mise run install # install shared + board-specific libs (requires BOARD env) @@ -198,6 +201,14 @@ Use `#pragma once` (not `#ifndef` guards). - Use `millis()` for timing (not `delay()`) - Serial console at 115200 baud for debug commands +### Style System + +The project uses a CSS-like styling system for consistent UI across different display sizes: + +- **Style constants** in each board's `board_config.h`: `STYLE_SPACING_X`, `STYLE_HEADER_HEIGHT`, `STYLE_COLOR_BG`, etc. +- **Font abstraction** via `IDisplayDriver` methods: `setTitleFont()`, `setBodyFont()`, `setLabelFont()`, `setDefaultFont()` +- **Layout helpers** in `KlubhausCore/src/Style.h`: `Layout` and `TileMetrics` structs + ## Testing/Debugging **No unit tests exist** - This is an embedded Arduino sketch. Verify changes by building and deploying to hardware: @@ -226,6 +237,12 @@ mise set BOARD=esp32-32e-4 # compile for ESP32-32E-4" | `TEST:touch X Y release` | Inject synthetic release at raw panel coords (X,Y) | | `TEST:touch clear` | Clear test mode (required between touch sequences) | +**Debug Features** (only when `DEBUG_MODE` is enabled in board-config.sh): + +| Feature | Description | +|---------|-------------| +| Red crosshair | Draws a red crosshair at exact touch coordinates on tap (DEBUG_MODE only) | + Note: The S3 touch panel is rotated 180° relative to the display. Use raw panel coordinates: - Display (100,140) → Raw (700, 340) @@ -253,12 +270,11 @@ The monitor daemon automatically starts after upload and is killed before upload ## Gotchas -1. **secrets.h is gitignored**: Copy from `.example` before building: +1. **secrets.h can be shared**: KlubhausCore/src/secrets.h provides default credentials. Boards with `LOCAL_SECRETS` defined in board-config.sh will use their local `secrets.h` instead. ```bash - cp boards/esp32-32e/secrets.h.example boards/esp32-32e/secrets.h - cp boards/esp32-32e-4/secrets.h.example boards/esp32-32e-4/secrets.h - cp boards/esp32-s3-lcd-43/secrets.h.example boards/esp32-s3-lcd-43/secrets.h + # For boards without local secrets.h, the defaults will be used + # To use board-specific credentials, add -DLOCAL_SECRETS to OPTS in board-config.sh ``` 2. **Display libs are vendored**: Each board uses a different display library. The build system uses `--libraries` to link only the board's vendored lib — never link both TFT_eSPI and LovyanGFX in the same build. @@ -410,143 +426,26 @@ mise run gen-crush-config - Backlight on IO27 (HIGH = on) - Common anode RGB LEDs on IO16, IO17, IO22 (LOW = on) -# RTK (Rust Token Killer) - Token-Optimized Commands +# RTK (Rust Token Killer) -## Golden Rule +RTK filters command output to reduce tokens. It's optional but recommended for saving tokens. -**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use. - -**Important**: Even in command chains with `&&`, use `rtk`: +## Installation Check ```bash -# ❌ Wrong -git add . && git commit -m "msg" && git push - -# ✅ Correct -rtk git add . && rtk git commit -m "msg" && rtk git push +which rtk # Check if installed ``` -## RTK Commands by Workflow - -### Build & Compile (80-90% savings) - +If installed, use it before git commands: ```bash -rtk cargo build # Cargo build output -rtk cargo check # Cargo check output -rtk cargo clippy # Clippy warnings grouped by file (80%) -rtk tsc # TypeScript errors grouped by file/code (83%) -rtk lint # ESLint/Biome violations grouped (84%) -rtk prettier --check # Files needing format only (70%) -rtk next build # Next.js build with route metrics (87%) +rtk git status +rtk git diff +rtk git add . +rtk git commit -m "message" +rtk git push ``` -### Test (90-99% savings) - -```bash -rtk cargo test # Cargo test failures only (90%) -rtk vitest run # Vitest failures only (99.5%) -rtk playwright test # Playwright failures only (94%) -rtk test # Generic test wrapper - failures only -``` - -### Git (59-80% savings) - -```bash -rtk git status # Compact status -rtk git log # Compact log (works with all git flags) -rtk git diff # Compact diff (80%) -rtk git show # Compact show (80%) -rtk git add # Ultra-compact confirmations (59%) -rtk git commit # Ultra-compact confirmations (59%) -rtk git push # Ultra-compact confirmations -rtk git pull # Ultra-compact confirmations -rtk git branch # Compact branch list -rtk git fetch # Compact fetch -rtk git stash # Compact stash -rtk git worktree # Compact worktree -``` - -Note: Git passthrough works for ALL subcommands, even those not explicitly listed. - -### GitHub (26-87% savings) - -```bash -rtk gh pr view # Compact PR view (87%) -rtk gh pr checks # Compact PR checks (79%) -rtk gh run list # Compact workflow runs (82%) -rtk gh issue list # Compact issue list (80%) -rtk gh api # Compact API responses (26%) -``` - -### JavaScript/TypeScript Tooling (70-90% savings) - -```bash -rtk pnpm list # Compact dependency tree (70%) -rtk pnpm outdated # Compact outdated packages (80%) -rtk pnpm install # Compact install output (90%) -rtk npm run