docs: README polish + APPENDIX cleanup + GLOSSARY extraction

[JarbasAl]

Summary

The README had grown to document spec internals (per-spec scope paragraphs, the full glossary, compatibility-level exposition, design notes about individual specs). The APPENDIX had become a dumping ground — six overlapping subsections in §5 all restating the same idea, §3 enumerating every pipeline stage, §9 repeating §1/§2/§6/§7 content in five subsections. This PR refocuses the README on the repository itself, lifts the glossary into its own file, and prunes the APPENDIX down to ~590 lines from ~770 without losing substance.

Changes

README (rewritten — 247 → 131 lines)

• New Goals section — interoperability, stability, adoption beyond OVOS.
• Specifications table trimmed to ID / Document / Version / Status — dropped the Scope column (each spec carries its own scope statement in its own header).
• Reading order kept (still useful navigation) but shortened.
• Reference implementation section kept; added note that the bus stack does not yet have a ground-up reference implementation.
• "Contributing" replaces the old "Changing a specification" section; same content, clearer name; adds note that non-normative PRs (APPENDIX / GLOSSARY / README / examples) do not require a version bump.
• Cross-links to APPENDIX.md, GLOSSARY.md, CHANGELOG.md added inline so the lean README still routes readers to context.

Dropped from README:

• "Design notes" bullets — per-spec content, already in each spec's own design rationale and in APPENDIX §4.
• "Planned" section — covered by APPENDIX §7 "Known gaps".
• "Versions" / compatibility-level exposition — moved to APPENDIX §10 (see below).

New file: GLOSSARY.md

• All terms previously inline in the README, with each definition now linking to the spec section that owns it.
• Marked non-normative; the authoritative definition stays in each spec.

APPENDIX cleanup (770 → 590 lines)

• §3 Pipeline section: stopped enumerating every stage (stop, converse, padatious, …) — that detail belongs in a future pipeline spec, not in an out-of-scope appendix note. Kept the broad framing (the pipeline is unspecified, persona realizes the engine-agnostic contract).
• §5 The bus as substrate: compressed six subsections (5.1–5.6) into three (5.1 single-flip routing model, 5.2 no central correlation/state, 5.3 why HiveMind works). Same substance, no repetition; the "what this rules out" warnings folded into §5.1 where they belong with the mechanic, the "what this defers" list moved into §7 known gaps where it was already partially listed.
• §9 Design history: compressed six subsections to three. Dropped 9.2 (overlapped with §1 + §6), 9.4 (already in §2.2), and 9.6 (already in §7).
• New §10 Compatibility levels: the V0/V1/V2 ladder previously in the README, with an honest note that the bus-stack additions complicate the model and a revised compat ladder is TBD.

What didn't change

• No spec content. README, GLOSSARY, APPENDIX are all non-normative, so no Version bumps anywhere.
• All cross-references still resolve (verified — every §X.Y link in the appendix lands on a real section after renumbering).
• Every glossary term still points at the same spec section as before.

Test plan

• Render README, GLOSSARY, APPENDIX on GitHub to confirm markdown is clean
• Click every cross-link in the new GLOSSARY to verify each spec-section link resolves
• Verify the APPENDIX compression didn't lose substance — every dropped paragraph has an equivalent (or shorter, sharper) statement remaining

Why now

The next bus-stack specs (#9 OVOS-INTENT-4, #11 OVOS-PIPELINE-1 draft) each add new rows to the README's specs table and new entries to the appendix. Tidying first lets each subsequent spec just add an ID/Document/Version/Status row and slot APPENDIX additions cleanly, instead of fighting the dumping-ground accretion.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@JarbasAl, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 1 review/hour. Refill in 51 minutes and 2 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0fd57e09-6d29-4935-8d95-e0718573b0fb

📥 Commits

Reviewing files that changed from the base of the PR and between 97d070e and f1758a8.

📒 Files selected for processing (3)

• APPENDIX.md
• GLOSSARY.md
• README.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-polish

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}