docs: narrative-voice intros across orchestration + channels + observability

All edits are intro-section rewrites that add a 'why this exists / when
to reach for it' framing in front of the existing reference content.
Every claim verified against source.

mission() — frame as 'state intent first, shape the graph later' with
  the honest current-status callout (compiles to a fixed gather/process/
  deliver stub today, planner config preserved but doesn't yet change
  graph shape at runtime). Verified mission() factory + MissionBuilder
  in src/orchestration/builders/MissionBuilder.ts.

workflow() — frame as the right answer when the steps are known and
  ordered, with cross-references to AgentGraph and mission() for the
  cases workflow() doesn't fit. Verified workflow() factory in
  src/orchestration/builders/WorkflowBuilder.ts.

AgentGraph — frame as full topology control when workflow() is too
  rigid and mission() too far ahead of the planner runtime. Honest
  callout that gmi/extension/subgraph node execution still requires
  the runtime bridge today (compilation is complete, execution is
  partial for those node kinds). Verified AgentGraph class + START/END
  constants + node factory functions.

Channels — frame around 'the agents people actually use don't live in
  one window' and the IChannelAdapter boundary. Twelve in-tree adapters
  plus 37 curated extension packs (37 verified by counting
  packages/agentos-extensions/registry/curated/channels/*/package.json).

Telephony — open with the latency budget reality of phone calls (Twilio
  ~200ms / practical ~400ms ceiling) that drives the pipeline shape.
  Three real providers (Twilio, Telnyx, Plivo) plus a mock for tests.
  Verified IVoiceCallProvider + CallManager.

Observability — open with 'can't operate in production without it,
  cost of bolting it on later is paid in incidents you can't reproduce'.
  Reinforce the opt-in policy and the host-owns-the-SDK model. Verified
  the @opentelemetry/api peer-dep import shape in
  src/evaluation/observability/otel.ts.

Author: jddunn

docs/architecture/AGENT_GRAPH.md

@@ -1,14 +1,10 @@
 # AgentGraph
 
-`AgentGraph` is the lowest-level authoring API in the Unified Orchestration Layer. It exposes explicit node and edge management, supports cycles, subgraph composition, and four edge types including the AgentOS-exclusive discovery and personality edges.
+When `workflow()` is too rigid and `mission()` is too far ahead of where the runtime currently plans, the answer is `AgentGraph` — explicit node and edge construction with cycles, conditional routing, subgraph composition, and the discovery and personality edges that don't exist in any other open agent framework. It compiles to the same [`CompiledExecutionGraph`](https://github.com/framersai/agentos/blob/master/src/orchestration/compiler/CompiledExecutionGraph.ts) IR as the higher-level builders, but it gets you full control over the topology before compilation.
 
-> Current runtime note:
-> `AgentGraph` compilation is complete, but some advanced execution paths are still bridge-dependent today.
-> The base runtime executes `tool`, `router`, `guardrail`, and `human` nodes directly.
-> `gmi`, `extension`, and `subgraph` execution require a higher-level runtime bridge,
-> and discovery/personality edges are still partial unless those integrations are wired.
+**Honest runtime status.** Compilation is complete. Execution is partial: the base runtime executes `tool`, `router`, `guardrail`, and `human` nodes directly. `gmi`, `extension`, and `subgraph` execution still requires a higher-level runtime bridge today, and the discovery and personality edges activate fully only when those integrations are wired. If your graph uses only the four direct-execution node kinds, you're in production-ready territory; if it relies heavily on `gmi` nodes inside cycles, expect to wire the bridge.
 
-Use `AgentGraph` when you need full control: complex conditional routing, agent loops that cycle back, memory-driven state machines, or subgraph composition. For linear pipelines, see [workflow()](./workflow-dsl.md). For goal-driven orchestration, see [mission()](./mission-api.md).
+Use `AgentGraph` when you need cycles, conditional fan-out, memory-driven state machines, or subgraph composition. Use [`workflow()`](./workflow-dsl.md) for linear pipelines. Use [`mission()`](./mission-api.md) when you'd rather declare intent than topology.
 
 ## Quick Start
 

docs/features/CHANNELS.md

@@ -1,31 +1,19 @@
-# Channels — 37-Platform Deployment Guide
+# Channels — multi-platform deployment guide
 
-> Connect your agent to any messaging platform with a unified adapter interface.
+The agents people actually use don't live in one window. A useful research assistant gets pinged on Slack during the workday, on Telegram on the weekend, and over email when someone forwards a thread for it to summarise. Each platform has its own ergonomics, its own rate limits, its own message-shape quirks, its own auth model. The work of integrating each one is real, and writing it once per agent is the thing that stops most projects at "demo on Discord."
 
----
-
-## Table of Contents
+The channel layer is the boundary that makes this someone else's problem. Every external platform sits behind a single [`IChannelAdapter`](https://github.com/framersai/agentos/blob/master/src/channels/IChannelAdapter.ts) interface; your agent code emits and receives `ChannelMessage` objects, and the adapter handles serialization, auth, reconnection, and platform-specific edge cases. Twelve adapters ship in-tree (`src/channels/adapters/`); 37 curated extension packs cover the rest of the messaging, social, and publishing surface. Same shape on either side of the boundary — same `ChannelMessage` envelope, same `ChannelRouter` for routing inbound traffic to the right agent, same code path for sending replies back out.
 
-1. [Overview](#overview)
-2. [All 37 Channels](#all-37-channels)
-3. [Setup Guides](#setup-guides)
-   - [Discord](#discord)
-   - [Slack](#slack)
-   - [Telegram](#telegram)
-   - [Twitter / X](#twitter--x)
-   - [WhatsApp](#whatsapp)
-4. [Custom Channel Adapter](#custom-channel-adapter)
-5. [Message Routing](#message-routing)
-6. [Broadcast to Multiple Channels](#broadcast-to-multiple-channels)
-
----
-
-## Overview
+```
+User (Discord / Telegram / etc.)
+  ↕  platform SDK
+IChannelAdapter
+  ↕  ChannelRouter
+Your Agent (AgentOS)
+```
 
-The AgentOS Channel System normalizes every external messaging platform behind
-a single `IChannelAdapter` interface. Your agent code never speaks platform
-APIs directly — it emits and receives `ChannelMessage` objects, and the adapter
-handles all platform-specific serialization, authentication, and reconnection.
+Channels are registered as `messaging-channel` extensions and managed by the
+`ChannelRouter`, which handles load balancing, health checks, and fallback.
 
 ```
 User (Discord / Telegram / etc.)

docs/features/TELEPHONY_PROVIDERS.md

@@ -1,8 +1,8 @@
 # Telephony Providers
 
-AgentOS supports three telephony providers for outbound and inbound voice calls:
-**Twilio**, **Telnyx**, and **Plivo**. All three implement the same
-`IVoiceCallProvider` interface and are wired through the central `CallManager`.
+A real phone call has stricter latency budgets than any chat surface. Twilio's docs say "audio gaps over 200ms feel unnatural"; in practice anything over 400ms gets users hanging up. The voice path through AgentOS is built around that constraint: the [voice pipeline](./VOICE_PIPELINE.md) runs end-to-end at low enough latency to feel like a conversation, and the telephony layer extends that into the PSTN by speaking the same streaming protocol — incoming caller audio is decoded to Float32 frames for VAD/STT, outbound TTS audio is re-encoded to mu-law on the way back to the phone, all through a full-duplex WebSocket. The provider is interchangeable.
+
+Three providers ship in-tree at [`src/channels/telephony/providers/`](https://github.com/framersai/agentos/tree/master/src/channels/telephony/providers): **Twilio**, **Telnyx**, and **Plivo**. All three implement [`IVoiceCallProvider`](https://github.com/framersai/agentos/blob/master/src/channels/telephony/IVoiceCallProvider.ts) and are wired through the central [`CallManager`](https://github.com/framersai/agentos/blob/master/src/channels/telephony/CallManager.ts) state machine. There's also a mock provider for testing.
 
 ---
 

docs/observability/OBSERVABILITY.md

@@ -1,7 +1,10 @@
 # AgentOS Observability (OpenTelemetry)
 
-> AgentOS provides **opt-in** OpenTelemetry (OTEL) spans, metrics, and log correlation/export hooks.
-> AgentOS itself does **not** start an OTEL SDK. Your host application owns exporters, sampling, and context propagation.
+You can't operate an agent runtime in production without observability, and the cost of bolting it on after the fact is paid in incidents you can't reproduce. AgentOS treats spans, metrics, and log correlation as first-class concerns — but it does not own the OpenTelemetry SDK lifecycle. The SDK is an application-level concern: your host owns exporters, sampling, and context propagation, because the right answer for a CLI process is different from the right answer for a long-running server is different from the right answer for an edge worker.
+
+What AgentOS owns is the *emit side*: opt-in spans around turns and tool-result handling, opt-in counters and histograms for the operations worth measuring, optional trace-correlation in logs and streamed response metadata, and an optional path to export application logs as OTEL `LogRecord`s. All defaults are off. Turning them on is a single config change, and the runtime will surface to whatever exporter your host has wired (OTLP to Honeycomb, Tempo, Jaeger, Grafana Cloud — the runtime doesn't care, because your host SDK is what does the export).
+
+The implementation lives in [`src/evaluation/observability/`](https://github.com/framersai/agentos/tree/master/src/evaluation/observability) and uses [`@opentelemetry/api`](https://www.npmjs.com/package/@opentelemetry/api) directly — never bundled, always peer-dep-style imported, so your host SDK is the one and only OTEL provider in the process.
 
 ---
 

docs/orchestration/MISSION_API.md

@@ -1,10 +1,10 @@
 # mission() API
 
-`mission()` is the goal-first authoring API in the Unified Orchestration Layer. Instead of declaring nodes and edges directly, you describe the mission intent and let the compiler build the execution graph.
+`workflow()` and `AgentGraph` ask you to think in terms of nodes and edges before you've thought in terms of intent. `mission()` lets you state the intent first and shape the graph later. You declare what the mission is supposed to accomplish — the goal template, the input schema, the return schema, the planner hints — and the compiler emits a working execution graph from those declarations. When the shape stabilises through use, you export it via `.toWorkflow()` and pin it as a deterministic [workflow()](./workflow-dsl.md) or [AgentGraph](./agent-graph.md) for production.
 
-Current status: `mission()` compiles to a fixed phase-ordered stub graph (`gather` → `process` → `deliver`) with anchors and mission-level policies applied on top. Planner config is accepted and preserved, but it does not yet change graph shape at runtime.
+**Honest status today.** `mission()` is partly the API you'd expect from the description above and partly a forward-compatible shape for what it will be. The compiler currently emits a fixed phase-ordered stub graph (`gather` → `process` → `deliver`) with the anchors and mission-level policies you declared applied on top. The planner config is accepted and preserved, but does not yet change graph shape at runtime. The exported [`CompiledExecutionGraph`](./workflow-dsl.md) is real and runs through the same orchestration runtime as everything else; it's just not dynamically planned yet. See [`/architecture/runtime-status-matrix`](../architecture/runtime-status-matrix) for the shipped-vs-partial map across the orchestration surface.
 
-Use `mission()` when you want a goal-centric builder API today, when you're prototyping around anchors and policies, or when you want a forward-compatible path to richer planner-backed compilation later. When the steps stabilise, call `.toWorkflow()` to export a fixed `CompiledExecutionGraph` and switch to [workflow()](./workflow-dsl.md) or [AgentGraph](./agent-graph.md) for production.
+Use `mission()` today when you want a goal-centric authoring API, when you're prototyping around anchors and policies, or when you want a forward-compatible authoring path that will pick up dynamic planning when it lands. Use `workflow()` or `AgentGraph` when you need the graph shape pinned and reviewable.
 
 ## Quick Start
 

docs/orchestration/WORKFLOW_DSL.md

@@ -1,8 +1,8 @@
 # workflow() DSL
 
-`workflow()` is the sequential/pipeline authoring API in the Unified Orchestration Layer. It compiles to the same `CompiledExecutionGraph` IR as `AgentGraph` and `mission()`, but enforces that the result is a strict DAG — cycles are detected and rejected at compile time.
+The right way to ship a multi-step agent is rarely the most flexible way. A graph that can loop and replan is great when you don't know what shape the work takes; it's overkill — and harder to operate — when you do know. `workflow()` exists for the second case. You declare the steps in the order they run, the compiler builds the execution graph, and a static cycle check rejects anything that would loop. The output is the same [`CompiledExecutionGraph`](https://github.com/framersai/agentos/blob/master/src/orchestration/compiler/CompiledExecutionGraph.ts) the cyclic builders produce, so you can swap a `workflow()` for an `AgentGraph` later without re-architecting the runtime around it.
 
-Use `workflow()` when your steps are known upfront and execute in a well-defined order. For cyclic agent loops or complex graph structures, see [AgentGraph](./agent-graph.md). For goal-driven orchestration where steps emerge at runtime, see [mission()](./mission-api.md).
+Use `workflow()` when the steps are known and ordered. Use [`AgentGraph`](./AGENT_GRAPH.md) when you need cycles, conditional branches, or fan-out/fan-in patterns the linear `then()` chain can't express. Use [`mission()`](./MISSION_API.md) when you want to declare intent first and let the planner decide the steps.
 
 ## Quick Start