Repository navigation
docs: the order of work, and why the server is Linux-only - #3
Merged
Merged
Conversation
Two questions kept being answered from scratch, so both are written down. The first is what to do when a change is not a one-liner. The new-feature skill is the order rather than a style guide: work out which half it belongs to, and notice that most features are a table in actions.go and no APK at all; read the docs that apply; and verify in three passes that cost more as they go. The emulator pass is the one that was missing. There is an AVD for it, and a crash found there costs a minute where the same crash found in a headset costs somebody's afternoon. What the emulator cannot answer is written beside it, so it does not become false confidence: Horizon OS's windows, a controller ray, and everything angular that docs/readability.md measured. That last pass belongs to the person wearing the thing, and their judgement outranks a derivation. Two facts about running both devices are recorded because they cost time here: with a headset and an emulator attached at once every bare adb command fails, including make apk and make dev, and a copy signed with another key has to be uninstalled before a debug build will install. The second question is Windows, which will be asked by somebody eventually. The server cross-compiles with four errors, and fixing them would produce a binary that answers discovery, accepts a TLS connection, and opens no shell: creack/pty's Windows file is a stub returning ErrUnsupported. Worse, ConPTY has no foreground process group, so TIOCGPGRP — the read that the whole context bar stands on — has nothing to port to. docs/windows.md records what was checked and how, what a port must solve in what order, and which item on that list is a security regression rather than a missing feature: the config holding the transcription key is 0600 here and an ACL question there. It also says what is untouched, that the client does not change by a line, and that WSL2 is the answer available today for most people who would ask. Commits also stop carrying an attribution trailer. Claude is in this repository's contributors, which is where that belongs; repeating it on every message is noise in a log that is public and read for its reasoning.
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
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.
What
Two documents and the notes that point at them.
.claude/skills/new-feature/SKILL.md— the order of work for anythingbigger than a one-liner: scope it to the right half, research, build, verify,
document, commit, release.
docs/windows.md— what a Windows port of the server would have to solve,written from a cross-compile rather than from memory.
CLAUDE.mdandREADME.md— short notes so both are found by theperson who needs them.
Why
Both questions were being answered from scratch each time.
The verification order in particular had a hole: client changes went straight to
a headset. The emulator pass in the middle is cheap, and the cost of skipping it
is somebody's afternoon rather than a minute.
Windows will be asked about eventually. The dangerous half of the answer is that
the cross-compile is nearly fine — four errors — so the obvious move is to
silence them, which yields a binary that answers discovery, accepts a TLS
connection, and opens no shell at all.
How
linuxtermAVD, thenthe headset with the user. What the emulator cannot answer is listed beside
it — Horizon OS windows, controller ray, readability through the lenses — so
the cheap pass does not turn into false confidence.
every bare adb command including
make apkandmake dev, and a copy signedwith another key must be uninstalled first.
docs/windows.mdseparates what was checked against this tree (the four builderrors, the
creack/ptystub, the missing foreground process group, whichfiles hold what) from what is still assumption (whether ConPTY suffices for a
full-screen TUI, current WSL2 networking). It flags the config-file ACL as a
security regression rather than a missing feature, and says
GOOS=windowsmaynot join the release matrix until a session opens on real hardware.
CLAUDE.md.Testing
Documentation only — no code changes, nothing to run. The Windows claims were
produced by
GOOS=windows GOARCH=amd64 go build .inserver/and by readingcreack/ptyv1.1.24 in the module cache; both are quoted in the document withthe commands that produced them.