From 44d86784acce90188dcd543f33a308c91fafdfee Mon Sep 17 00:00:00 2001 From: Ivan Malison Date: Sun, 19 Jul 2026 23:31:22 -0700 Subject: [PATCH] docs: use AGENTS.md as canonical agent guidance, include from CLAUDE.md Move the repository agent guidance into AGENTS.md so it is picked up by any tool following the AGENTS.md convention, and reduce CLAUDE.md to an `@AGENTS.md` include so Claude Code continues to read the same content. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 69 +------------------------------------------------------ 2 files changed, 69 insertions(+), 68 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..840e0dadb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# AGENTS.md + +This file provides guidance to coding agents (Claude Code, and any tool that reads `AGENTS.md`) when working with code in this repository. + +## What This Project Is + +RMK is a Rust keyboard firmware library targeting embedded microcontrollers (`no_std` by default). It supports USB and BLE keyboards, split keyboards, on-the-fly keymap configuration(Vial), and advanced key behaviors (combos, tap-hold, macros, morse, etc). The repo is a Cargo monorepo with four crates(): + +- **`rmk`** — core firmware logic +- **`rmk-config`** — TOML configuration parsing (for `keyboard.toml`-based users) +- **`rmk-macro`** — procedural macros (`#[rmk_keyboard]`, `#[derive(Event)]`, etc.) +- **`rmk-types`** — shared types (`KeyAction`, `EncoderAction`, etc.) + +Note that there's no `Cargo.toml` in the project root. + +The `examples/` directory shows two usage patterns: `use_config/` (driven by `keyboard.toml`) and `use_rust/` (pure Rust API). +The `docs` directory contains multi-version documentation +The `scripts` directory contains useful scripts for checking/formatting code + +## Commands + +### Testing + +Dev loop — one feature set, from `rmk/` (requires `cargo nextest`): +```bash +cargo nextest run --no-default-features --features=split,vial,storage,async_matrix,_ble +``` + +Run macro tests from `rmk-macro/` (requires `cargo expand`). + +Run format test from root: +```bash +sh scripts/format_all.sh +``` + +Full feature matrix (what CI runs, ~40 s when clean): +```bash +sh scripts/test_all.sh +``` + +### Building examples +Examples target specific MCUs; build from an example directory, e.g.: +```bash +cd examples/use_config/nrf52840_ble +cargo build --release +``` + +## Architecture + +### Basic Data flow +``` +Matrix / InputDevices → Events (pub/sub channels) -> InputProcessors/Keyboard(keyboard.rs) -> KEYBOARD_REPORT_CHANNEL -> HidWriter (USB or BLE) -> Host +``` + +### `keyboard.toml` and compile-time constants + +`keyboard.toml` is parsed by `rmk-config` (`KeyboardTomlConfig`) at two points: by `rmk/build.rs` at build time, and by `rmk-macro` at macro-expansion time. The path defaults to `keyboard.toml` next to `Cargo.toml` and can be overridden with `KEYBOARD_TOML_PATH` in user space's `.cargo/config.toml`. + +Config is loaded in three layers (later overrides earlier): `event_default.toml` → chip-specific default (from `rmk-config/src/default_config/.toml`, selected via `[keyboard].chip`) → user `keyboard.toml`. + +`build.rs` reads only the `[rmk]` and `[event]` sections, then emits `constants.rs` as Rust `const` items. The full `KeyboardTomlConfig` struct in `rmk-config/src/lib.rs` is the authoritative reference for all available fields and their defaults. + +`[event]` tunes per-event pub/sub channel sizes (`channel_size`, `pubs`, `subs`). All event names and their defaults live in `rmk-config/src/default_config/event_default.toml`. + +## Rules + +- Don't use `pub use` for convenient usage **within** the crate +- Don't add a small helper function (≤ 10 lines) that has only one call site — inline it at the call site diff --git a/CLAUDE.md b/CLAUDE.md index c5b81cf52..43c994c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,68 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## What This Project Is - -RMK is a Rust keyboard firmware library targeting embedded microcontrollers (`no_std` by default). It supports USB and BLE keyboards, split keyboards, on-the-fly keymap configuration(Vial), and advanced key behaviors (combos, tap-hold, macros, morse, etc). The repo is a Cargo monorepo with four crates(): - -- **`rmk`** — core firmware logic -- **`rmk-config`** — TOML configuration parsing (for `keyboard.toml`-based users) -- **`rmk-macro`** — procedural macros (`#[rmk_keyboard]`, `#[derive(Event)]`, etc.) -- **`rmk-types`** — shared types (`KeyAction`, `EncoderAction`, etc.) - -Note that there's no `Cargo.toml` in the project root. - -The `examples/` directory shows two usage patterns: `use_config/` (driven by `keyboard.toml`) and `use_rust/` (pure Rust API). -The `docs` directory contains multi-version documentation -The `scripts` directory contains useful scripts for checking/formatting code - -## Commands - -### Testing - -Dev loop — one feature set, from `rmk/` (requires `cargo nextest`): -```bash -cargo nextest run --no-default-features --features=split,vial,storage,async_matrix,_ble -``` - -Run macro tests from `rmk-macro/` (requires `cargo expand`). - -Run format test from root: -```bash -sh scripts/format_all.sh -``` - -Full feature matrix (what CI runs, ~40 s when clean): -```bash -sh scripts/test_all.sh -``` - -### Building examples -Examples target specific MCUs; build from an example directory, e.g.: -```bash -cd examples/use_config/nrf52840_ble -cargo build --release -``` - -## Architecture - -### Basic Data flow -``` -Matrix / InputDevices → Events (pub/sub channels) -> InputProcessors/Keyboard(keyboard.rs) -> KEYBOARD_REPORT_CHANNEL -> HidWriter (USB or BLE) -> Host -``` - -### `keyboard.toml` and compile-time constants - -`keyboard.toml` is parsed by `rmk-config` (`KeyboardTomlConfig`) at two points: by `rmk/build.rs` at build time, and by `rmk-macro` at macro-expansion time. The path defaults to `keyboard.toml` next to `Cargo.toml` and can be overridden with `KEYBOARD_TOML_PATH` in user space's `.cargo/config.toml`. - -Config is loaded in three layers (later overrides earlier): `event_default.toml` → chip-specific default (from `rmk-config/src/default_config/.toml`, selected via `[keyboard].chip`) → user `keyboard.toml`. - -`build.rs` reads only the `[rmk]` and `[event]` sections, then emits `constants.rs` as Rust `const` items. The full `KeyboardTomlConfig` struct in `rmk-config/src/lib.rs` is the authoritative reference for all available fields and their defaults. - -`[event]` tunes per-event pub/sub channel sizes (`channel_size`, `pubs`, `subs`). All event names and their defaults live in `rmk-config/src/default_config/event_default.toml`. - -## Rules - -- Don't use `pub use` for convenient usage **within** the crate -- Don't add a small helper function (≤ 10 lines) that has only one call site — inline it at the call site +@AGENTS.md