docs(AGENTS.md): Update RTK section and add style system docs
This commit is contained in:
163
AGENTS.md
163
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-instructions v2 -->
|
||||
# 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 <cmd> # 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 <num> # 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 <script> # Compact npm script output
|
||||
rtk npx <cmd> # Compact npx command output
|
||||
rtk prisma # Prisma without ASCII art (88%)
|
||||
```
|
||||
|
||||
### Files & Search (60-75% savings)
|
||||
|
||||
```bash
|
||||
rtk ls <path> # Tree format, compact (65%)
|
||||
rtk read <file> # Code reading with filtering (60%)
|
||||
rtk grep <pattern> # Search grouped by file (75%)
|
||||
rtk find <pattern> # Find grouped by directory (70%)
|
||||
```
|
||||
|
||||
### Analysis & Debug (70-90% savings)
|
||||
|
||||
```bash
|
||||
rtk err <cmd> # Filter errors only from any command
|
||||
rtk log <file> # Deduplicated logs with counts
|
||||
rtk json <file> # JSON structure without values
|
||||
rtk deps # Dependency overview
|
||||
rtk env # Environment variables compact
|
||||
rtk summary <cmd> # Smart summary of command output
|
||||
rtk diff # Ultra-compact diffs
|
||||
```
|
||||
|
||||
### Infrastructure (85% savings)
|
||||
|
||||
```bash
|
||||
rtk docker ps # Compact container list
|
||||
rtk docker images # Compact image list
|
||||
rtk docker logs <c> # Deduplicated logs
|
||||
rtk kubectl get # Compact resource list
|
||||
rtk kubectl logs # Deduplicated pod logs
|
||||
```
|
||||
|
||||
### Network (65-70% savings)
|
||||
|
||||
```bash
|
||||
rtk curl <url> # Compact HTTP responses (70%)
|
||||
rtk wget <url> # Compact download output (65%)
|
||||
```
|
||||
|
||||
### Meta Commands
|
||||
|
||||
```bash
|
||||
rtk gain # View token savings statistics
|
||||
rtk gain --history # View command history with savings
|
||||
rtk discover # Analyze Claude Code sessions for missed RTK usage
|
||||
rtk proxy <cmd> # Run command without filtering (for debugging)
|
||||
rtk init --global # Add RTK to ~/.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
rtk init # Add RTK instructions to CLAUDE.md
|
||||
|
||||
## Token Savings Overview
|
||||
|
||||
| Category | Commands | Typical Savings |
|
||||
|----------|----------|-----------------|
|
||||
| Tests | vitest, playwright, cargo test | 90-99% |
|
||||
| Build | next, tsc, lint, prettier | 70-87% |
|
||||
| Git | status, log, diff, add, commit | 59-80% |
|
||||
| GitHub | gh pr, gh run, gh issue | 26-87% |
|
||||
RTK passes through unchanged if no filter exists, so it's always safe to use.
|
||||
| Package Managers | pnpm, npm, npx | 70-90% |
|
||||
| Files | ls, read, grep, find | 60-75% |
|
||||
| Infrastructure | docker, kubectl | 85% |
|
||||
|
||||
@@ -21,18 +21,18 @@ pkl = "latest"
|
||||
[tasks.compile]
|
||||
description = "Compile (uses BOARD env var)"
|
||||
depends = ["gen-compile-commands"]
|
||||
run = """
|
||||
run = '''
|
||||
source ./boards/$BOARD/board-config.sh
|
||||
arduino-cli compile --fqbn "$FQBN" --libraries ./libraries $LIBS --build-property "compiler.cpp.extra_flags=$OPTS" --warnings default ./boards/$BOARD
|
||||
"""
|
||||
'''
|
||||
|
||||
[tasks.upload]
|
||||
description = "Upload (uses BOARD env var)"
|
||||
depends = ["kill"]
|
||||
run = """
|
||||
run = '''
|
||||
source ./boards/$BOARD/board-config.sh
|
||||
arduino-cli upload --fqbn "$FQBN" --port "$PORT" ./boards/$BOARD
|
||||
"""
|
||||
'''
|
||||
|
||||
[tasks.monitor-raw]
|
||||
depends = ["kill"]
|
||||
|
||||
Reference in New Issue
Block a user