docs: README — full spec-set refresh for the in-flight stack

README.md

@@ -1,12 +1,42 @@
 # OVOS Formal Specifications
 
-Formal, implementation-agnostic specifications for the OpenVoiceOS
-voice assistant ecosystem.
+Formal, implementation-agnostic specifications for a **voice
+operating system** — a platform that provides a stable application
+binary interface for voice-interactive applications.
 
-This repository is the **source of truth** for how OVOS components
+This repository is the **source of truth** for how components
 talk to each other and what their data shapes mean. The specs are
 written generically so they can be implemented by any tool, in any
-language, and adopted by voice assistants beyond OVOS.
+language, and adopted beyond their origin project.
+
+### What a voice operating system is
+
+A voice OS is not a voice assistant. A voice assistant is a product
+that answers questions. A voice OS is a **platform**: it defines the
+boundary between user input and computation, arbitrates which
+application handles each utterance, manages conversation state across
+interactions, and provides a stable ABI that arbitrary third-party
+applications run against without knowing anything about each other.
+
+The analogy to a general-purpose OS is direct:
+
+| OS concept | Voice OS equivalent |
+|---|---|
+| Process scheduler | Pipeline plugin ordering (PIPELINE-1 §5–6) |
+| IPC / message passing | The bus and MSG-1 envelope |
+| Shared memory | Session carrier (SESSION-1, SESSION-2) |
+| Process supervision | Handler-lifecycle trio (PIPELINE-1 §8) |
+| Loadable kernel modules | Pipeline plugins, transformer plugins |
+| System call ABI | The `match(utterances, lang, session) → Match` contract |
+
+The consequence is that OVOS is not a chatbot, not an LLM wrapper,
+and not a monolithic product. It is a **runtime**: swap the
+scheduler (pipeline ordering), the NLU engines (pipeline plugins),
+the dialogue policy (converse / context), the output layer (TTS,
+display), or any combination — the ABI stays stable and the rest
+keeps working. A skill written against the intent stack runs on any
+conformant orchestrator, under any pipeline configuration, in any
+language OVOS supports.
 
 > ⚠️ **Draft.** Specs in this repository are at **Draft** status.
 > Implementations are being brought into conformance progressively;
@@ -57,23 +87,41 @@ below). Adoption is voluntary; conformance, once adopted, is not.
 
 ## Specifications
 
+### Intent stack — what a skill defines
+
 | ID | Document | Version | Status |
 |----|----------|---------|--------|
 | OVOS-INTENT-1 | [Sentence Template Grammar](sentence-template-grammar.md) | 2 | Draft |
-| OVOS-INTENT-2 | [Locale Resource Formats](locale-resource-formats.md) | 2 | Draft |
+| OVOS-INTENT-2 | [Locale Resource Formats](locale-resource-formats.md) | 2 | Draft · [v3 in review (PR #4)](https://github.com/OpenVoiceOS/architecture/pull/4) |
 | OVOS-INTENT-3 | [Intent Definition](intent-definition.md) | 1 | Draft |
-| OVOS-MSG-1 | [Bus Message](message-object.md) | 1 | Draft |
+| OVOS-INTENT-4 | [Intent and Entity Registration](intent-registration.md) | 2 | [Draft — in review (PR #9)](https://github.com/OpenVoiceOS/architecture/pull/9) |
+
+### Bus stack — how components talk
+
+| ID | Document | Version | Status |
+|----|----------|---------|--------|
+| OVOS-MSG-1 | [Bus Message](message-object.md) | 2 | Draft |
+| OVOS-SESSION-1 | [Session Carrier Wire Shape](session.md) | 1 | Draft |
+| OVOS-SESSION-2 | [Session Lifecycle and State Ownership](session-lifecycle.md) | 1 | Draft |
+
+### Orchestrator stack — what processes utterances
+
+| ID | Document | Version | Status |
+|----|----------|---------|--------|
+| OVOS-PIPELINE-1 | [Utterance Lifecycle and Pipeline](pipeline.md) | 2 | Draft |
+| OVOS-TRANSFORM-1 | [Transformer Plugins](transformer.md) | 1 | [Draft — in review (PR #20)](https://github.com/OpenVoiceOS/architecture/pull/20) |
+| OVOS-CONTEXT-1 | [Intent Context](intent-context.md) | 1 | [Draft — in review (PR #18)](https://github.com/OpenVoiceOS/architecture/pull/18) |
+| OVOS-CONVERSE-1 | [Active Handlers and Interactive Response](converse.md) | 1 | [Draft — in review (PR #25)](https://github.com/OpenVoiceOS/architecture/pull/25) |
 
 Each spec carries its own scope statement, design rationale, and
-conformance section in its own header. Open the document for the
-full picture — the table above is just an index.
-
-**Reading order.** The intent specs are numbered in dependency
-order: OVOS-INTENT-1 defines the template grammar; OVOS-INTENT-2
-builds on it to define the resource files; OVOS-INTENT-3 builds on
-both to define what an intent is. OVOS-MSG-1 is the bus-layer
-envelope and the routing / session model — independent of the
-intent stack and readable at any point.
+conformance section in its header. Open the document for the full
+picture — the tables above are an index.
+
+**Reading order by role:**
+- *Writing a skill?* INTENT-1 → INTENT-2 → INTENT-3. INTENT-4 only if you need the registration wire format.
+- *Building a pipeline plugin?* PIPELINE-1, then SESSION-1 + SESSION-2, then the role spec (CONVERSE-1, CONTEXT-1, or TRANSFORM-1).
+- *Building an orchestrator?* MSG-1 → SESSION-1 → SESSION-2 → PIPELINE-1, then INTENT-4, CONTEXT-1, CONVERSE-1, TRANSFORM-1.
+- *Surveying the architecture?* [APPENDIX §1](APPENDIX.md) for the three-stack narrative.
 
 For background — design rationale, comparisons with other systems,
 the catalogue of known divergences from current code, and known