Skip to content

docs(readme): the README reflects the code it documents - #342

Merged
dbgeek merged 1 commit into
mainfrom
claude/readme-mermaid-architecture-review-8fc6d1
Aug 2, 2026
Merged

docs(readme): the README reflects the code it documents#342
dbgeek merged 1 commit into
mainfrom
claude/readme-mermaid-architecture-review-8fc6d1

Conversation

@dbgeek

@dbgeek dbgeek commented Aug 2, 2026

Copy link
Copy Markdown
Owner

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

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.
  • vocabulary and log_transcripts — missing from a config table that opens with "Every field is optional".
  • acceptance/ and tools/ in Repository Layout; --remove-model among the Model Operation subcommands.

Type of change

  • Bug fix
  • Documentation
  • Small improvement
  • Larger change (discussed first in issue #___)

Checklist

  • Single, focused concern
  • nix develop --command zig build test passes
  • Uses the project vocabulary from CONTEXT.md
  • Matches the surrounding code style

For the reviewer

Documentation only — no behavior change. The src/config.zig hunks are two comments; one of them is user-facing, since it is emitted into a freshly generated config.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.md still states the local-only rule in three places. It is a locked spec whose successor docs/openai-biasing-spec.md already 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.

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.
@dbgeek
dbgeek merged commit d1f2b6b into main Aug 2, 2026
2 checks passed
@dbgeek
dbgeek deleted the claude/readme-mermaid-architecture-review-8fc6d1 branch August 2, 2026 19:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant