Imported from zeitlinger/keyboard (AGENTS.md). Install upstream with npx skills add zeitlinger/keyboard. Copyright stays with the author.

AGENTS.md

This file provides agent guidance for working in this repository.

Project Overview

Custom keyboard layout generator for the Hands Down Vibranium layout on a Ferris Sweep (34-key split keyboard). A Kotlin program reads the layout definition from README.md markdown tables and generates QMK firmware C code.

Build & Flash

mise run generate    # Compile Kotlin and generate QMK files (mvn compile exec:java)
mise run flash       # Generate + flash firmware via QMK (avrdude-split-left)

Tools are managed by mise (Java, Maven, Python, jq, uv). Run mise install if needed.

Architecture

The README.md is the source of truth for the keyboard layout. The generator parses its markdown tables (layout, options, symbols, magic keys, adaptives, chords) and produces QMK C code.

Generator (Kotlin, src/main/kotlin/)

• generateKeyboard.kt - Entry point (main()), core data types (Layer, Key, KeyPosition, LayerOption, etc.)
• read.kt - Parses markdown tables into layer data structures
• generate.kt - Produces QMK C layer definitions from parsed layers
• combos.kt - Generates combo definitions (combos.def)
• chords.kt - Generates chord mode C code
• translate.kt - Translates markdown symbols to QMK keycodes using the Symbols table
• modifiers.kt - Home row mod logic
• options.kt - Parses the LayerOptions table
• hand.kt - Left/right hand position logic
• analyze.kt - Layout statistics
• version.kt - Git version embedding

Generated QMK output (qmk/)

• generated.c - Main generated file (layers, magic keys, chords, custom keycodes)
• combos.def - Generated combo definitions
• keymap.c - Hand-written QMK entry point that includes generated.c
• casemodes.c/h - Hand-written X-Case implementation
• layout.h - Hand-written layout helpers

The generator runs twice: once to qmk/ (with placeholder version) and once to target/qmk/ (with git version). Only target/qmk/ should be used for actual firmware builds. Generation itself does not require a clean git working tree. mise run flash checks for uncommitted changes immediately before flashing.

Do NOT edit qmk/generated.c or qmk/combos.def directly. These are committed for reference only. The real sources are:

• README.md - layout tables, adaptives, magic keys, chords (source of truth)
• src/main/resources/generated.c - C template with ${...} placeholders filled by the generator

Workflow

1. Edit layout tables in README.md (layers, combos, chords, magic keys, adaptives, symbols, options)
2. Run mise run generate to regenerate qmk/generated.c and qmk/combos.def
3. Run mise run flash to build and flash

When editing files in src/main/resources/ (C templates): commit first, then run mise run generate, then amend the commit to include the regenerated qmk/ output.

Agent Knowledge

Consult agents/README.md before working on layout ergonomics, motion analysis, or adaptives. Load only the files relevant to the current task.

Key Concepts

• Layers: Base, Left, Right, Nav, FnSym, Num, etc. - defined in Layout and Options tables
• Combos: Two keys pressed together produce a different output (marked with 💎 in layout)
• Chords: Two-letter sequences that expand to common words (Chord Table in README)
• Magic keys: Context-sensitive keys that output different characters based on the previous keypress
• Adaptives: Regular keys that output a different character when typed after a specific key (e.g. h after n -> g, giving "ng" without a combo). To find new candidates: agents/suggest-adaptives.md. To make a combo key (like "qu") participate in adaptives, add it to the Symbols table with custom: (e.g. | "qu" | custom:ADPT_QU |) and add its default SEND_STRING handler in qmk/keymap.c (see N_T/ING pattern).
• Dead keys: Modifier keys (dead1/dead2/dead3) used for layer switching
• X-Case: Automatic case conversion modes (camelCase, snake_case, etc.)