chore(agent): add generated guidance source

.gitignore

@@ -8,3 +8,11 @@ result
 .direnv/
 
 **/.claude/settings.local.json
+
+AGENTS.override.md
+
+AGENTS.md
+
+.cargo/
+.cclsp.json
+.mcp.json

AGENTS.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/render-agents. Edit /realm/project/intercept-bounce/CLAUDE.md and included files instead. -->
+
 # Repository Guidelines
 
 ## Project Structure & Module Organization

CLAUDE.md

@@ -0,0 +1,26 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+The runtime crate lives under `src/`, where `main.rs` wires the CLI in `cli.rs` to the filtering core in `filter/`. Shared utilities (`config.rs`, `telemetry.rs`, `logger.rs`) keep side-effects isolated. Integration and property tests sit in `tests/`, with reusable fixtures in `test-helpers/`. Performance work belongs in `benches/`, while `fuzz/` houses `cargo fuzz` targets. Reference material and generated manuals land in `docs/`, and the `xtask/` helper orchestrates doc builds.
+
+## Build, Test, and Development Commands
+- `cargo build --release` compiles the filter binary with production optimizations.
+- `cargo test --all` runs unit, integration, and property suites; mirror CI before opening a PR.
+- `cargo clippy --all-targets -- -D warnings` enforces lint cleanliness; match CI expectations.
+- `cargo fmt --all` or `./dev.sh fmt` keeps formatting consistent; run before committing.
+- `./dev.sh all` chains fmt, clippy, and tests for a quick gate.
+- `cargo run --package xtask --bin xtask -- generate-docs` refreshes the CLI/manpage material in `docs/`.
+- `nix develop` drops you into the flake-provisioned dev shell; use `./dev.sh nix` for a full build.
+
+## Coding Style & Naming Conventions
+Rust code follows standard 4-space indentation and `rustfmt` defaults. Modules, files, and test helpers use `snake_case`; types remain `PascalCase`. Prefer explicit `use crate::...` paths for clarity, and document non-obvious helpers with `///` comments. CI treats clippy warnings as errors, so resolve lints locally.
+
+## Runtime Configuration Tips
+- `--ignore-key <KEY>` lets you exempt specific controls (e.g., `KEY_VOLUMEDOWN` encoder wheels) from debouncing; the flag accepts symbolic names or numeric codes.
+- Keep `--log-bounces` on when developing input pipelines so freshly ignored keys can be verified quickly via the systemd journal.
+
+## Testing Guidelines
+Keep fast checks in `tests/` and push slower fuzz targets under `fuzz/`. Name new integration files `*_tests.rs`; within modules, group cases under `mod tests { ... }`. Run `cargo test --all` before pushing, and refresh relevant property tests when touching timing logic. For fuzzing, seed with `cargo fuzz run fuzz_core_filter` or `fuzz_target_stats` and commit any minimized corpus updates. Benchmarks live in `benches/filter.rs`; use `cargo bench` to validate performance-sensitive changes.
+
+## Commit & Pull Request Guidelines
+History favors concise, imperative subjects (e.g., `Tighten near-miss logging`); include a brief body when context is not obvious. Squash fixups locally so each commit passes `./dev.sh all`. PRs should link issues when applicable, summarize behavioural impact, and cite how you validated the change. Attach log snippets or screenshots for user-visible output shifts, and call out configuration updates in `docs/` or sample pipelines.

flake.nix

@@ -186,8 +186,8 @@
     })
     // {
       nixosModules = {
-        default = import ./nix/modules/intercept-bounce.nix { inherit self; };
-        intercept-bounce = import ./nix/modules/intercept-bounce.nix { inherit self; };
+        default = import ./nix/modules/intercept-bounce.nix {inherit self;};
+        intercept-bounce = import ./nix/modules/intercept-bounce.nix {inherit self;};
       };
     };
 }

nix/modules/intercept-bounce.nix

@@ -1,7 +1,11 @@
-{ self }:
-{ config, lib, pkgs, ... }:
-let
-  inherit (lib)
+{self}: {
+  config,
+  lib,
+  pkgs,
+  ...
+}: let
+  inherit
+    (lib)
     concatMap
     escapeShellArgs
     mkEnableOption
@@ -11,7 +15,7 @@ let
     types
     ;
 
-  packagesForSystem = lib.attrByPath [ pkgs.system ] (self.packages or { }) { };
+  packagesForSystem = lib.attrByPath [pkgs.system] (self.packages or {}) {};
 
   defaultPackage =
     packagesForSystem.intercept-bounce
@@ -21,37 +25,39 @@ let
   cfg = config.services.interceptBounce;
 
   toStr = value:
-    if builtins.isString value then value else builtins.toString value;
+    if builtins.isString value
+    then value
+    else builtins.toString value;
 
   baseArgs =
     []
-    ++ optionals (cfg.debounceTime != null) [ "--debounce-time" cfg.debounceTime ]
+    ++ optionals (cfg.debounceTime != null) ["--debounce-time" cfg.debounceTime]
     ++ optionals (cfg.nearMissThresholdTime != null) [
       "--near-miss-threshold-time"
       cfg.nearMissThresholdTime
     ]
-    ++ optionals (cfg.logInterval != null) [ "--log-interval" cfg.logInterval ]
-    ++ optionals cfg.logAllEvents [ "--log-all-events" ]
-    ++ optionals cfg.logBounces [ "--log-bounces" ]
-    ++ optionals cfg.listDevices [ "--list-devices" ]
-    ++ optionals cfg.statsJson [ "--stats-json" ]
-    ++ optionals cfg.verbose [ "--verbose" ]
+    ++ optionals (cfg.logInterval != null) ["--log-interval" cfg.logInterval]
+    ++ optionals cfg.logAllEvents ["--log-all-events"]
+    ++ optionals cfg.logBounces ["--log-bounces"]
+    ++ optionals cfg.listDevices ["--list-devices"]
+    ++ optionals cfg.statsJson ["--stats-json"]
+    ++ optionals cfg.verbose ["--verbose"]
     ++ optionals (cfg.ringBufferSize != null) [
       "--ring-buffer-size"
-      toStr cfg.ringBufferSize
+      toStr
+      cfg.ringBufferSize
     ]
-    ++ concatMap (key: [ "--debounce-key" key ]) cfg.debounceKeys
-    ++ concatMap (key: [ "--ignore-key" key ]) cfg.ignoreKeys
+    ++ concatMap (key: ["--debounce-key" key]) cfg.debounceKeys
+    ++ concatMap (key: ["--ignore-key" key]) cfg.ignoreKeys
     ++ optionals (cfg.otelEndpoint != null) [
       "--otel-endpoint"
       cfg.otelEndpoint
     ]
     ++ cfg.extraArgs;
 
-  commandList = [ "${cfg.package}/bin/intercept-bounce" ] ++ baseArgs;
+  commandList = ["${cfg.package}/bin/intercept-bounce"] ++ baseArgs;
   commandString = escapeShellArgs commandList;
-in
-{
+in {
   options.services.interceptBounce = {
     enable = mkEnableOption "intercept-bounce CLI integration";
 
@@ -126,13 +132,13 @@ in
 
     debounceKeys = mkOption {
       type = types.listOf types.str;
-      default = [ ];
+      default = [];
       description = "List of keys passed via repeated --debounce-key flags.";
     };
 
     ignoreKeys = mkOption {
       type = types.listOf types.str;
-      default = [ ];
+      default = [];
       description = "List of keys passed via repeated --ignore-key flags.";
     };
 
@@ -144,13 +150,13 @@ in
 
     extraArgs = mkOption {
       type = types.listOf types.str;
-      default = [ ];
+      default = [];
       description = "Arbitrary arguments appended after generated flags.";
     };
 
     command = mkOption {
       type = types.listOf types.str;
-      default = [ ];
+      default = [];
       description = "Resolved intercept-bounce invocation expressed as a list.";
     };
 
@@ -162,7 +168,7 @@ in
   };
 
   config = mkIf cfg.enable {
-    environment.systemPackages = optionals cfg.installSystemPackage [ cfg.package ];
+    environment.systemPackages = optionals cfg.installSystemPackage [cfg.package];
     services.interceptBounce.command = commandList;
     services.interceptBounce.commandString = commandString;
   };

src/filter/stats.rs

@@ -151,11 +151,7 @@ impl TimingHistogram {
 
     /// Calculates the average timing in microseconds. Returns 0 if count is 0.
     pub fn average_us(&self) -> u64 {
-        if self.count > 0 {
-            self.sum_us / self.count
-        } else {
-            0
-        }
+        self.sum_us.checked_div(self.count).unwrap_or(0)
     }
 
     // Add methods like get_buckets(), get_count() if needed externally.