docs: split APPENDIX.md into topic-specific files under appendix/

[JarbasAl]

Summary

Split the monolithic APPENDIX.md (1563 lines) into 7 topic-specific files under appendix/, retaining section numbering for stable cross-references. APPENDIX.md is now an index with a preamble and table of contents.

File	Section	Topic
appendix/overview.md	§1	About the OVOS specifications
appendix/comparisons.md	§2	Comparison with other voice-assistant systems
appendix/patterns.md	§3	Architectural patterns
appendix/rationale.md	§4	Design rationale, per specification
appendix/divergences.md	§5	Where the specs differ from current OVOS code
appendix/reference.md	§6	Implementer reference tables
appendix/gaps.md	§7	Known gaps and planned work

Cross-reference impact

• README.md — 3 references updated to point to the correct sub-file or the index
• AGENTS.md, TODO.md — updated (local files, not in repo)
• No spec files reference APPENDIX directly, so no spec edits were needed

Non-normative

Per the contributing rules, this touches only non-normative material and does not require a version bump.

Summary by CodeRabbit

• Documentation
  • Reorganized and expanded the OVOS specification appendix across multiple topic-specific files.
  • Added new appendix sections covering architectural patterns, design rationale, implementation reference, known gaps, comparisons with other voice assistants, and specification divergences.
  • Updated navigation links in README to reference the new appendix structure.

[coderabbitai]

Warning

Review limit reached

@JarbasAl, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 36 seconds. Learn how PR review limits work.

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

⌛ How to resolve this issue?

After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ba66cd86-6e9d-4df5-b9da-99e31b9f569d

📥 Commits

Reviewing files that changed from the base of the PR and between dd32cc9 and c7315b1.

📒 Files selected for processing (9)

• APPENDIX.md
• README.md
• appendix/comparisons.md
• appendix/divergences.md
• appendix/gaps.md
• appendix/overview.md
• appendix/patterns.md
• appendix/rationale.md
• appendix/reference.md

📝 Walkthrough

Walkthrough

This PR restructures the OVOS architecture documentation by splitting a large monolithic appendix into seven focused topic-specific Markdown files. The APPENDIX.md index and README.md are updated to guide navigation through the new appendix directory structure. The changes establish comprehensive documentation covering specification overview, architectural patterns, spec-to-code divergences, design rationale, system comparisons, implementer reference, and known gaps.

Changes

Appendix Reorganization and Expansion

Layer / File(s)	Summary
Index and Navigation Updates APPENDIX.md, README.md	APPENDIX.md expands the normative spec list and introduces a mapping table explaining the appendix is now distributed across topic-specific files. README.md updates links to point to appendix/overview.md §1 and clarifies that APPENDIX.md and appendix/ can be browsed together; contribution guidance now includes both APPENDIX.md and the appendix/ directory when describing non-normative-change exceptions.
Spec Overview and Foundational Concepts appendix/overview.md	Introduces the OVOS "voice operating system" concept, formalization status of the specification set, and the three-stack dependency structure (intent, bus, orchestrator). Defines specification versioning with compatibility ladders for the intent stack and independent versioning for bus/orchestrator stacks. Documents reference tooling ecosystem including ovos-spec-tools, ovos-bus-client, ovos-core, and ovos-localize localization workflow.
Architectural Patterns and Bus Substrate appendix/patterns.md	Formalizes the bus-as-substrate model with single-flip routing and absence of central correlation/state tracking. Specifies layer-2 peer routing composition via session-based destinations and preference/policy split inheritance. Documents the pipeline-plugin model refinement, dispatch polymorphism via <skill_id>:<intent_name>, and the universal ovos.utterance.handled end-marker. Outlines three interoperability adapter injection points (pipeline plugins, transformer chains, bus-boundary) with per-protocol integration notes for Wyoming, OpenAI-compatible APIs, MCP/tool protocols, hassil/HA intents, MQTT-based stacks, and A2A.
Spec-to-Code Divergences and Migration appendix/divergences.md	Catalogs known divergences between formal specs and current OVOS code across envelope semantics, session/context serialization, and pipeline conventions. Prescribes topic/function renames affecting ovos.intent.* namespace and utterance handling topics; specifies which ovos-core session sync topics should be removed. Details message shape changes for keyword/template registration, dispatch payloads, and handler-lifecycle payloads. Enumerates architectural divergences including Match.updated_session mutation rules, ovos.utterance.handled coverage, context key scoping/ownership, and skill self-identification requirements. Lists new spec-introduced topics and provides predecessor-to-replacement topic mapping tables with out-of-scope legacy context/activity topics.
Design Rationale and System Comparisons appendix/rationale.md, appendix/comparisons.md	rationale.md explains design reasoning across intent grammar/resources, bus message envelope semantics, session carrier design, intent registration broadcast, pipeline lifecycle/dispatch ordering, intent context scoping/mutation, transformer plugin architecture, and STOP-1 pre-emption cascade. comparisons.md positions OVOS architecturally relative to Home Assistant/Rhasspy (shared grammar lineage vs differences in matching/templating/pipeline), Rasa (context-aware matching), Amazon ASK/Alexa SKD and Google Dialogflow (entity systems and orchestration), with summary of where OVOS leads, follows, and deliberately differs.
Implementer Reference and Known Gaps appendix/reference.md, appendix/gaps.md	reference.md provides cross-spec topic-name conventions explaining the four-way "intent" namespace collision; consolidated session-field cheat-sheet with empty-array omission semantics; component-identity stamp-rule cheat-sheet for reserved context keys; and introspection surface documentation for pull-query/scatter-response patterns with shared behavioral rules. gaps.md lists deferred specification areas including plugin behavioral specs, unclaimed session preference fields, ASR text normalization, planned conformance corpora/worked examples, conversation-level evaluation infrastructure, OVOS-INTENT-2 ↔ hassil translation tool, and i18n corpus scaling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• OpenVoiceOS/architecture#14: Introduces the appendix split and divergences documentation for PIPELINE-1/intent specs with prescribed renames and architectural changes that this PR expands and reorganizes.

Poem

A rabbit hops through spec-filled pages, 🐰
Reorganizing ancient appendix sages,
Seven topics bloom in folders neat,
Navigation maps now make review complete!
The architecture dance, at last, takes shape. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: splitting a monolithic APPENDIX.md into multiple topic-specific files under a new appendix/ directory.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/appendix-split

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@appendix/gaps.md`:
- Around line 1-3: The file begins with an opening YAML frontmatter delimiter
'---' but has no closing delimiter; either remove the leading '---' entirely if
no frontmatter is intended, or add a matching closing '---' after the
frontmatter block (i.e., close the YAML block) so Markdown pipelines don't
misinterpret the rest of the content; locate the top of the file where the lone
'---' appears and apply one of these two fixes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4adf8214-f9af-4431-be41-e02c2eb12031

📥 Commits

Reviewing files that changed from the base of the PR and between 7dba0e5 and dd32cc9.

📒 Files selected for processing (9)

• APPENDIX.md
• README.md
• appendix/comparisons.md
• appendix/divergences.md
• appendix/gaps.md
• appendix/overview.md
• appendix/patterns.md
• appendix/rationale.md
• appendix/reference.md