docs(readme): the README reflects the code it documents - #342
Merged
Conversation
A review of the README's flowchart and Architecture section against src/ turned up drift, most of it from the 0.4.x releases. Corrected: - Vocabulary is no longer local-Whisper-only. Since #326/#327 the same shared list is bound as the OpenAI Session's `keywords` field on a keywords-capable model and re-bound on an idle push when it changes, so the flowchart pins it on the Backend Router and names how each backend applies it. The two stale `config.zig` comments that still called it local-only — the `vocabulary` field doc and the generated `config.zon` header line the daemon writes for the user — say the same thing now. - Secure Event Input was absent entirely, while the README claimed every Insertion leaves an Insertion Record. It does not: an Utterance spoken under a held Secure Event Input is withheld from the ring and kept out of the log even under `.log_transcripts` (#286), and the chord never reaches the daemon at all (#245). Documented as its own paragraph. - The status line still read v0.1.2, six releases behind. Filled in: - `api_key.zig`, `secure_input.zig`, `signing_identity.zig` and `broken_pipe.zig` were missing from the module tables — the first three are named concepts in the project vocabulary. - `vocabulary` and `log_transcripts` were missing from a config table that opens with "Every field is optional". - `acceptance/` and `tools/` were missing from Repository Layout, and `--remove-model` from the Model Operation subcommands. Verified against the code rather than assumed: the Coordinator's five phases, the Insert Worker's dictation-then-menu-then-Undo drain order, the ring's N=20, every config default, the key precedence, and every build step and link the README names all match. Documentation only — no behavior change.
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 & why
A review of the README's Mermaid flowchart and Architecture section against
src/turned up drift, most of it from the 0.4.x releases. Two items were factually wrong rather than merely incomplete.Corrected
keywordsfield on a keywords-capable model (session.zig) and re-bound on an idle push when the menu edits it (menu.zig). The flowchart now pins Vocabulary on the Backend Router and each backend node names how it applies it. The two staleconfig.zigcomments that still called it local-only are fixed in the same pass — thevocabularyfield doc, and the generatedconfig.zonheader line the daemon writes into the user's own config file..log_transcripts(Dictation under a held Secure Event Input is a decided, stated posture #286), and while SEI is held the chord never reaches the daemon at all (Surface a held Secure Event Input: the recovery chord silently never arrives #245). Now its own paragraph.v0.1.2— six releases behindbuild.zig.zon.Filled in
api_key.zig,secure_input.zig,signing_identity.zig,broken_pipe.zig— missing from the module tables; the first three are named concepts in CONTEXT.md.vocabularyandlog_transcripts— missing from a config table that opens with "Every field is optional".acceptance/andtools/in Repository Layout;--remove-modelamong the Model Operation subcommands.Type of change
Checklist
nix develop --command zig build testpassesFor the reviewer
Documentation only — no behavior change. The
src/config.zighunks are two comments; one of them is user-facing, since it is emitted into a freshly generatedconfig.zon. No golden test pins that header, and the suite passes.Verified against the code rather than assumed, and left alone because it already matched: the Coordinator's five phases, the Insert Worker's dictation → menu → Undo drain order, the ring's N=20, all ten pre-existing config defaults, the key precedence, and every build step and link the README names.
One thing deliberately not touched:
docs/vocab-biasing-spec.mdstill states the local-only rule in three places. It is a locked spec whose successordocs/openai-biasing-spec.mdalready records that premise as superseded, so amending it looked like it would work against the convention rather than with it. Happy to change that if you'd rather the old spec carry a pointer.