Chart VoidKontrol wayfinding and correct current hidraw evidence

CONTEXT.md

@@ -0,0 +1,43 @@
+# VoidKontrol
+
+VoidKontrol manages the verified customization capabilities of a Kreo Swarm 75
+keyboard while preserving its ordinary typing and media controls.
+
+## Language
+
+**Driver-declared capability**:
+A customization advertised by the vendor's software for a keyboard model,
+whose behavior on the connected keyboard has not necessarily been verified.
+_Avoid_: Verified capability, working feature
+
+**Verified capability**:
+A customization whose behavior has been demonstrated on an identified keyboard
+and connection mode, including the readback needed to confirm an update.
+_Avoid_: Driver-declared capability
+
+**Device layer**:
+One of the keyboard's Base, Fn, Fn1, or Fn2 sets of key assignments.
+_Avoid_: Profile
+
+**Macro**:
+A named sequence of key press/release actions and delays assigned to a keyboard
+macro slot, with an execution behavior supported by the device.
+
+**Desired configuration**:
+The settings the user intends the keyboard to use; they may differ from the
+settings currently confirmed on the keyboard.
+_Avoid_: Device readback
+
+**Device readback**:
+Settings obtained from the keyboard and used as evidence of its current state.
+_Avoid_: Desired configuration, successful request
+
+**Configuration backup**:
+A saved, complete configuration read from the keyboard before changes, intended
+to support restoration to that known state.
+_Avoid_: Raw packet recording
+
+**Restore**:
+An explicit operation that reapplies a compatible configuration backup and
+verifies the resulting keyboard state.
+_Avoid_: Factory reset

KREO-SWARM75-LINUX-CONTROL-SPEC.md

@@ -49,11 +49,20 @@ is `1` — but it is not RGB control.
 
 ### Linux access requirement
 
-This laptop's kernel does not provide `hidraw` (`modprobe hidraw` reports that
+**Corrected by a read-only recheck on 2026-09-21:** the running kernel
-the module is absent).  A native controller therefore requires a kernel with
+`7.2.6_1` has `CONFIG_HIDRAW=y`, and both Swarm HID interfaces now have hidraw
-`CONFIG_HIDRAW=y` or `CONFIG_HIDRAW=m`, plus a narrow udev rule granting the
+nodes. The earlier `modprobe hidraw` failure did not establish missing
-controller service access to the matching hidraw node.  It must select the
+support: Linux defines `CONFIG_HIDRAW` as a boolean, not a separately loadable
-node that represents interface 1 / usage `0xff00:0x01`.
+module option (`CONFIG_HIDRAW=m` is not valid).
+
+A native controller requires `CONFIG_HIDRAW=y` and a narrow udev policy
+granting its device service access to the matching node. At the recheck,
+interface 1 was `/dev/hidraw5`, owned by `root:root` with mode `0600`; the
+desktop user could neither read nor write it. Node numbers are dynamic and
+must not be hard-coded. Select interface 1 / usage `0xff00:0x01` and validate
+the complete descriptor before enabling control. See the dated
+[device evidence](docs/evidence/2026-09-21-swarm75.md) and
+[Linux HID Kconfig](https://github.com/torvalds/linux/blob/master/drivers/hid/Kconfig).
 
 Do **not** use libusb by detaching or unbinding `hid-generic`: that can take
 the keyboard away from the desktop.  A read-only libusb `GET_REPORT` attempt

README.md

@@ -0,0 +1,33 @@
+# VoidKontrol
+
+VoidKontrol is being planned as a Kreo Swarm 75 keyboard manager for Void Linux,
+with IBM Carbon in the desktop app and native niri and Noctalia integration.
+There is no application implementation or working device-control release yet.
+
+The canonical plan is the Gitea decision map:
+[Find the way to VoidKontrol v1: complete verified Swarm75 control on Void Linux](https://git.bongbetic.com/xavierk/voidkontrol/issues/1).
+Its child issues hold research, unresolved decisions, and hardware prerequisites.
+
+## Confirmed v1 boundary
+
+Start with the verified USB presentation. Target device information, global and
+per-key lighting, four key layers, macros, supported typing and power settings,
+and backup/export/import/restore. Enable each capability only after its behavior
+is verified on the device. Firmware flashing and the factory-reset UI are
+excluded from v1; other connection modes require separate validation.
+
+## Read next
+
+- [Control specification](KREO-SWARM75-LINUX-CONTROL-SPEC.md): transport facts,
+  vendor capability targets, safety invariants, and bring-up gates.
+- [Domain language](CONTEXT.md): distinctions between declared capabilities,
+  verified capabilities, desired settings, and device readback.
+- [Current device evidence](docs/evidence/2026-09-21-swarm75.md): hidraw is
+  enabled, but device-service access and authenticated protocol captures are
+  still needed. No device settings were changed during this recheck.
+- [Issue tracker workflow](docs/agents/issue-tracker.md): how to query the map's
+  frontier, claim a ticket, and record its resolution.
+
+The original specification was corrected to reflect current hidraw evidence;
+its protocol-validation requirements remain in force. Research recommendations
+are not implementation decisions or passed hardware tests.

docs/agents/issue-tracker.md

@@ -6,8 +6,8 @@ Issues and specs for this repo live as Gitea issues. Use the official [`tea`](ht
 
 - **Create an issue**: `tea issues create --title "..." --description "..."`.
 - **Read an issue**: `tea issues <number>`.
-- **List issues**: `tea issues`; use `tea issues --state all` for all states and `tea issues --format json` for machine-readable output.
+- **List issues**: `tea issues`; use `tea issues --state all` for all states and `tea issues --output json` for machine-readable output.
-- **Comment on an issue**: `tea comment issue <number>`.
+- **Comment on an issue**: `tea comments add <number> "<body>"`.
 - **Apply / remove labels**: `tea issues edit <number> --add-labels "..."` / `--remove-labels "..."`.
 - **Close**: `tea issues close <number>`.
 - **Pull requests**: use `tea pulls create`, `tea pulls <number>`, and `tea pulls checkout <number>`.
@@ -25,3 +25,37 @@ Create a Gitea issue.
 ## When a skill says "fetch the relevant ticket"
 
 Run `tea issues <number>`.
+
+## Wayfinding operations
+
+The current project is `xavierk/voidkontrol`, with configured tea login
+`xavierk`. Pass `--login xavierk --repo xavierk/voidkontrol` when repository
+context is unavailable. Use `tea api` for API operations not exposed by a
+dedicated command; read the server's `/swagger.v1.json` for its current schema.
+
+- **Map**: the issue labelled `wayfinder:map`. Start by reading its body.
+- **Children**: Gitea 1.27.1 exposes issue dependencies but no parent/subissue
+  endpoint in this server's schema. Give each child `wayfinder:child-of-<map
+  index>` plus its `wayfinder:research`, `wayfinder:task`,
+  `wayfinder:grilling`, or `wayfinder:prototype` label. Its body ends with a
+  named `Parent map` link. This membership convention does not replace native
+  blocking.
+- **Claim**: assign the driving user before work:
+  `tea issues edit --add-assignees xavierk <index>`. An open issue with an
+  assignee is claimed. If work stops incomplete, leave an evidence/progress
+  comment and release the claim with an API PATCH containing `{"assignees":[]}`.
+- **Blocking**: POST `{"owner":"xavierk","repo":"voidkontrol","index":<blocker>}`
+  to `repos/xavierk/voidkontrol/issues/<blocked>/dependencies` using `tea api`.
+  Create all tickets before adding these relationships. Verify by GET on that
+  endpoint; each returned issue blocks the issue in the URL.
+- **Frontier**: list open issues with the map-membership label, paginate through
+  all results, discard assigned issues, and GET each candidate's dependencies.
+  A candidate is takeable when every dependency is closed. Order by issue
+  creation/index ascending. Use names, with links, when presenting this result.
+- **Resolution**: publish the answer as a comment, link any committed research
+  or prototype asset, close the child, then append one named link and a short
+  gist to the map's `Decisions so far`. Read the latest map before editing so
+  concurrent additions survive. The full decision stays on the child.
+
+Canonical starting map:
+[Find the way to VoidKontrol v1: complete verified Swarm75 control on Void Linux](https://git.bongbetic.com/xavierk/voidkontrol/issues/1).

docs/evidence/2026-09-21-swarm75.md

@@ -0,0 +1,71 @@
+# Swarm75: read-only host and descriptor recheck
+
+Observed on 2026-09-21 during initial VoidKontrol wayfinding. This is discovery
+evidence, not an authenticated control session or a hardware acceptance result.
+
+## Findings
+
+| Observation | Evidence |
+| --- | --- |
+| Host | `/etc/os-release`: Void Linux; `uname -r`: `7.2.6_1`; `getconf GNU_LIBC_VERSION`: `glibc 2.41` |
+| hidraw support | `/boot/config-7.2.6_1`: `CONFIG_HIDRAW=y`, `CONFIG_HID_GENERIC=m`, `CONFIG_USB_HID=m` |
+| Swarm identity | Both relevant sysfs HID devices report `HID_ID=0003:0000258A:0000010C`, `HID_NAME=BY Tech Kreo Swarm` |
+| Input ownership | Both sysfs devices report `DRIVER=hid-generic`; nothing was unbound or grabbed |
+| Interface 0 | Present as `/dev/hidraw4` at observation time |
+| Interface 1 | Present as `/dev/hidraw5` at observation time; sysfs USB interface suffix `:1.1` |
+| Access | Interface 1 node is `root:root`, mode `0600`; desktop-user `test -r` and `test -w` both fail |
+| Vendor usage | Interface 1 descriptor includes vendor application collections with usage page `0xff00`, usage `0x01` |
+| Descriptor | 240 bytes, SHA-256 `04f6ae259d80ba5828ae7f6b81cdcb2d31acf0b20dc93b473561cd8b3c930ab0` |
+
+The node numbers are observations, not persistent identifiers. Discovery must
+reselect and revalidate the matching interface each time.
+
+Parsing the descriptor's report-size and report-count items gives these payload
+sizes (excluding the report ID byte):
+
+| Report ID | Input payload | Feature payload |
+| --- | --- | --- |
+| 1 | 1 byte including padding | — |
+| 2 | 2 bytes | — |
+| 3 | 3 bytes | — |
+| 4 | 15 bytes | — |
+| 5 | — | 5 bytes |
+| 6 | 7 bytes | 519 bytes |
+| 7 | 7 bytes | — |
+
+Report 1 includes three meaningful system-control bits and padding, consistent
+with the original specification's description. The descriptor agrees with the
+declared report-6 transport size; that agreement does not establish authentication,
+command semantics, checksums, firmware identity, or safe persistence behavior.
+
+## Correction to the initial specification
+
+The earlier inference from `modprobe hidraw` was incorrect. Linux declares
+[`CONFIG_HIDRAW` as `bool`](https://github.com/torvalds/linux/blob/master/drivers/hid/Kconfig),
+so `CONFIG_HIDRAW=m` is not an alternative and a missing standalone module is
+not proof that the running kernel lacks hidraw. Current kernel configuration
+and existing nodes directly establish its presence here.
+
+## Reproduction and boundaries
+
+Inspect `/sys/class/hidraw/*/device/uevent` and resolve their symlink targets to
+identify the Swarm interfaces. Read the selected device's `report_descriptor`
+attribute, sum report-size × report-count bits by report ID and main-item type,
+and hash the descriptor with SHA-256. Query node properties with `udevadm info`
+and inspect access without opening the device for control.
+
+Only kernel configuration, sysfs metadata, descriptor bytes, and filesystem
+permissions were read. No feature reports were sent, no normal input events
+were read, no permission rules were installed, and no device settings changed.
+Ordinary typing continuity was not measured by an interactive acceptance test.
+
+## Evidence still required
+
+- Confirm the physical connection and keyboard layout, including special controls.
+- A deliberately scoped official Kontrol authentication and configuration-read
+  capture for this device and transport.
+- Exact framing/authentication/checksum and complete configuration-read coverage.
+- Later, explicit reversible write/readback/persistence/restore verification for
+  every feature advertised as supported.
+
+Tracked by [Obtain authenticated Swarm75 evidence without interrupting normal input](https://git.bongbetic.com/xavierk/voidkontrol/issues/5).