Skip to content

docs: split 593-line README into focused top page + docs/ - #12

Merged
vr000m merged 1 commit into
mainfrom
docs/split-readme
Jun 9, 2026
Merged

docs: split 593-line README into focused top page + docs/#12
vr000m merged 1 commit into
mainfrom
docs/split-readme

Conversation

@vr000m

@vr000m vr000m commented Jun 9, 2026

Copy link
Copy Markdown
Owner

Summary

The README had grown to 593 lines, burying install/run basics under protocol, deployment, integration, and migration detail. This splits it so the top page stays focused on why it exists + install + run, and the deeper material moves to thematic files under docs/.

README keeps: preamble (why it exists), V1 scope, Running the server, Managing agents with just, Choosing a backend and model, and a new Documentation index. 593 → ~190 lines.

Moved verbatim to docs/:

File Content
docs/operations.md Multi-backend operation, per-ASR socket convention, two-agent install, A/B benchmark, checking server health, Whisper hallucination-suppression knobs
docs/integration.md Client usage, Pipecat integration, Reference consumer (Koda)
docs/protocol.md Protocol subset (V1 wire events)
docs/migration.md Upgrading 0.1.x → 0.2.0

Per request, the just operator recipes stay on the top page (promoted to their own ## Managing agents with just); only the per-ASR reference table they cite moved (link repointed).

Verification

  • No content lost: comm diff of original README vs the union of all new files shows only the 12 lines I deliberately changed — 4 re-leveled headings + 8 repointed cross-references. Everything else is byte-identical (extracted with sed, not retyped).
  • All links resolve: a script checks every internal markdown link + heading anchor across the 5 files — README → docs, docs → docs, and same-file anchors all pass.
  • No stale external refs: nothing else in the repo links to the moved README sections.

Docs-only — no code changes.

The README had grown to 593 lines, burying install/run basics under
protocol, deployment, integration, and migration detail. Keep the
preamble, V1 scope, running the server, the `just` operator recipes, and
backend/model selection on the top page; move the rest verbatim into:

- docs/operations.md  — multi-backend op, two-agent install, A/B
  benchmark, health checks, Whisper hallucination knobs
- docs/integration.md — client usage, Pipecat integration, Koda reference
- docs/protocol.md     — V1 wire protocol
- docs/migration.md    — 0.1.x -> 0.2.0 upgrade

Content moved verbatim (comm-verified: only deliberately re-leveled
headings + repointed cross-links differ from the original). A README
Documentation index links the four files; all internal links and anchors
resolve (checked). README 593 -> ~190 lines.
@vr000m
vr000m merged commit 714baa1 into main Jun 9, 2026
4 checks passed
@vr000m
vr000m deleted the docs/split-readme branch June 9, 2026 04:21
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