Add Claude Code config and AI-readiness docs#85
Closed
Olson3R wants to merge 17 commits into
Closed
Conversation
Introduces CLAUDE.md and docs/ARCHITECTURE.md so an agent landing in the repo can orient quickly on the build flow, the worker boundary, and the three-file rendering pipeline. Adds a .claude/ config bundle with a permissions allowlist, a PostToolUse hook that runs dprint on edited files, and two subagents (geometry-change, parts-contributor) tailored to the recurring shapes of work in this codebase. Wires up `npm test` to `bun test` to match the existing bun:test imports. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
# Conflicts: # package.json
`npm run check` reports ~50 errors that the project treats as known and accepted — most are in Viewer3D.svelte, App.svelte, VisualEditor2.svelte, plus "Cannot find module target/..." errors for build artifacts that require optional toolchains (Java/Leiningen for keyholes). The CI workflow runs `bun src/scripts/check.ts`, which filters those out via an explicit exclude list. Update CLAUDE.md and the two subagent definitions to recommend the CI script so future agents don't chase phantom errors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add Claude Code config and AI-readiness docs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Cosmos previously baked QWERTY into letterForKeycap() and FLIPPED_KEY, so every keycap legend and ZMK/QMK keycode came out QWERTY. This adds a layout dimension to the cosmos config (proto field 33, persisted in the URL) and wires it through the alpha-letter generation path so swapping the layout updates both the on-keycap legends and the firmware export. - src/lib/layouts/ exposes 5 layouts as a const-keyed registry with per-layout right-row letters and split-half flip maps. DEFAULT_LAYOUT preserves QWERTY back-compat for older shared configs. - letterForKeycap, cosmosFingers, keycapInfo, and flippedKey accept an optional layout (default: QWERTY); mirrorCluster threads the keyboard's layout in via its callers (config.cosmos, toCode, HandFitView, VisualEditor2). - Editor adds a Layout field after Keycaps. Switching layout calls applyLayoutToKeys, which uses alphaColumns() to update only the alpha block; number/F/punctuation rows stay layout-independent. - Firmware exporters need no changes: ZMK/QMK already key off keycap.letter, which is now layout-aware end-to-end. Tests cover all five layouts plus flip behavior. CI svelte-check (bun src/scripts/check.ts) clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lock in the contract that the layout dimension flows from cosmos config through key letters to firmware keycodes: - Round-trip every LAYOUT_IDS value through encode → serialize → decode and verify the layout survives. - Verify a legacy URL (encoded before this feature) still decodes as QWERTY for back-compat. - Build a default Cosmos config and confirm applyLayoutToKeys updates alpha-block letters per layout while leaving the number row untouched. - Confirm ZMK and QMK keycode() emit per-letter codes, and that the rightmost-of-center home-row position emits a different keycode under each layout (h/h/m/d/y across QWERTY/Colemak/Colemak-DH/Dvorak/Workman). The keycode() helpers in zmk.ts and qmk.ts are now exported so the end-to-end tests can verify the firmware contract directly without needing a full FullGeometry stack. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 1 (in this PR), Phase 2 (Miryoku bundle), and Phase 3 (general layer editor) — written down so future contributors and agents can pick up the plan without re-deriving the design discussion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add keyboard layout selector (Phase 1: letter-swap layouts)
Ships Miryoku as a togglable keymap preset that materializes 7 layers (BASE/NAV/MOUSE/MEDIA/NUM/SYM/FUN) in ZMK and QMK output. Orthogonal to the Phase 1 letter-swap layout — the BASE layer's alpha slots resolve to whatever letter the active layout puts on each physical key, so Miryoku × Colemak-DH works without per-layout copies. The slot picker lives in the firmware download dialog with smart auto-suggestions and per-slot localStorage-backed override inputs. <36-key boards see the checkbox disabled. New `KeyAction` union (kp/mt/lt/osm/osl/ trans/none) covers what ZMK and QMK both support natively; tap-dance, combos, and the BUTTON layer are deferred to Phase 3. 70 tests pass (was 48); see docs/PHASE_2_TESTING.md for the manual testing checklist. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The keymap preset only affects firmware output, so it now lives next to the other firmware settings rather than the geometry editor. Replaced the on/off checkbox with a Select dropdown (Default / Miryoku, with Miryoku greyed out below 36 keys) so Phase 3 can extend it with a Custom option without changing the data shape. Slot picker still appears below the selector when Miryoku is chosen. Drops the standalone PHASE_2_TESTING.md — the testing checklist now lives in the PR description. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Caught while reviewing the actual generated cosmotyl QMK download. Three real bugs and one UX problem: 1. Punctuation legends produced invalid keycodes. When a slot's __ALPHA__ placeholder resolved to ;, /, [, etc., qmkEmit emitted KC_; (won't compile) and zmkEmit emitted &kp ; (won't parse). Both now consult a CHARS-style lookup matching the regular generators (KC_SCLN, &kp SEMI). 2. The QMK Miryoku branch dropped all the Cosmos runtime boilerplate — no rgblight include, no RELAY pin defines, no keyboard_post_init_user or housekeeping_task_user, no OLED handlers. The keyboard's split-side power gating, LED, console debug, and OLED logo were all broken. Refactored generateKeymap so the boilerplate is shared between the Miryoku and default branches; only the keymaps[] body differs. 3. ZMK Miryoku BASE didn't inject &studio_unlock at the bootmagic positions when ZMK Studio was enabled — users couldn't unlock Studio via the bootmagic key. UX: the slot picker now uses matrix coordinates (row,col — same format shown on the keyboard view) instead of opaque ZMK position numbers. Each card stacks slot id / keycap legend / matrix coord, mirroring the physical keyboard layout. ?mode=test surfaces a "Fill test matrix" button so the firmware path can be exercised without flashing peaMK. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous synthetic matrix used [i % 7, floor(i/7)] which produced col values up to 7 — outside Cosmos QMK's matrix bounds (rows 0-13, cols 0-6 in split-rows mode). The resulting via.json had labels like "0,7" that wouldn't fit its declared matrix dims. Now left/unibody keys land in rows 0-6 and right-side keys in rows 7-13, both halves using cols 0-6 — same shape peaMK reports on real hardware. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
End-user-facing reference covering: - Layouts vs. keymaps (orthogonal axes) - Default single-layer keymap (pros/cons, when to pick it) - Miryoku — origin/history (manna-harbour 2020), philosophy, all 7 layers, home-row mod placement, pros/cons, who it's for - Other layered keymaps under consideration for Phase 3 (Seniply, Sturdy, Callum mods, Sweep) with one-line distinguishing traits - How keymap presets are stored, picked, and emitted in Cosmos Cross-linked from LAYOUT_PHASES.md so designers find the user docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Moved KEYMAP_STRUCTURES.md from the design-docs area to docs/docs/ keymap-structures.md so the public mkdocs site picks it up — it now renders on the user-facing docs site at /docs/keymap-structures/ and auto-includes in the awesome-pages nav. Removed LAYOUT_PHASES.md and all references to it. The phase plan was internal scaffolding for delivery; the public doc covers what users actually need to know. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous KEYMAP_STRUCTURES.md mixed keymap structure (Default vs Miryoku) with layout (QWERTY vs Colemak) — confusing two orthogonal concerns. Split into two reference-style docs: - docs/layouts.md — alphabet layouts (QWERTY, Colemak, Colemak-DH, Dvorak, Workman). For each: designer/year/origin, alpha-block diagram, diff from prior layout, OS support and behavior notes. Closes with picker table and a section on OS-vs-keyboard-side translation. - docs/keymap-structures.md — keymap structures (Default, Miryoku). Reference tables instead of editorial pros/cons. Includes Miryoku's layer index, mod placement, slot model, output shape per firmware, storage details, compatibility matrix, and Phase 3 candidate list. Both auto-include in awesome-pages "Docs" nav. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Speculative content about Phase 3 presets doesn't belong in user-facing reference docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 2: Miryoku keymap preset
Contributor
Author
|
Closing — this PR was originally for the Claude Code init work and used main:main, which got polluted as Phase 1 and Phase 2 landed on the fork's main. The actual phased work is in #87 (Phase 1, merged) and #88 (Phase 2, open). The Claude-init content is internal to my fork and isn't intended for upstream. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds opt-in tooling and docs aimed at making the repo easier to navigate — for both new human contributors and AI assistants like Claude Code, Cursor, etc.
CLAUDE.mdat the repo root: a one-page orientation covering the Bun-vs-Node toolchain split, themake quickstartflow, the worker boundary, the three-file rendering pipeline (geometry.ts→cachedGeometry.ts→model.ts), and common gotchas (target/is generated,pro/is gitignored,src/lib/opencv*.jsis generated by Vite plugins, etc.). Designed for any LLM-based assistant but named for Claude Code's convention. Other tools that read root-level instruction files (Cursor, Aider) will pick it up too.docs/ARCHITECTURE.md: deeper reference with the high-level diagram (main thread ↔ comlink ↔ web worker, build-timemodel_genpipeline →target/artifacts), per-route notes, and the protobuf-driven config flow. Useful regardless of whether anyone is using AI tooling..claude/directory: Claude Code-specific config — a permissions allowlist for routine commands (make build,npm run check,git status/diff/log, etc.), aPostToolUsehook that runsdprinton edited files (matching the existinglint-stagedsetup), and two subagents (geometry-change,parts-contributor) tailored to recurring shapes of work in this repo. Entirely opt-in; ignored by other tooling.package.json: adds"test": "bun test"so the existingbun:testfiles (config.test.ts,tuple.test.ts, the newcheck.test.tsandfirmwareHelpers.test.ts) are runnable via the standardnpm testinvocation. No new test runner introduced.If any of these aren't a fit, happy to drop them —
docs/ARCHITECTURE.mdand thenpm testwiring are the universally-useful pieces; the rest is happy to live only in forks.Test plan
npm test→ 20/20 pass (aftermake build)bun src/scripts/check.ts→ cleandprint checkon the new files → clean.claude/directory belongs in the upstream repo🤖 Generated with Claude Code