@@ -27,6 +27,10 @@ collections.
 
 For architecture boundaries, read [Architecture](architecture).
 
+For provider feature checks, read
+[Capability Planning](architecture/capability-planning). It explains how agent
+and option requirements resolve to a concrete provider surface before execution.
+
 For architectural choices that should not be reversed accidentally, read
 [Decisions](decisions). The most important ones are
 [Provider Surfaces Are First-Class](decisions/provider-surfaces-first-class)
 
@@ -20,6 +20,10 @@ the [Yoke Harness](../concepts/yoke-harness), [Runs And Sessions](../concepts/ru
 [CLI And Run Storage](../reference/cli-and-run-storage) pages into one
 execution path.
 
+Read [Capability Planning](capability-planning) when a change adds or changes
+features that depend on the selected provider surface. It explains how agent
+and option requirements become a surface plan before provider execution starts.
+
 Read [Provider Surfaces](../concepts/provider-surfaces) when runtime behavior
 depends on the exact Claude or Codex entrypoint. That concept page is the
 architecture-facing map for capability planning.
 
@@ -0,0 +1,45 @@
+---
+title: "Capability Planning"
+summary: "Capability planning is the harness step that turns agent and option requirements into a concrete provider surface plan before execution."
+topics: [architecture, runtime]
+sources:
+  - id: capabilities
+    type: file
+    path: src/yoke/capabilities.py
+  - id: surfaces
+    type: file
+    path: src/yoke/surfaces.py
+  - id: models
+    type: file
+    path: src/yoke/models.py
+  - id: options
+    type: file
+    path: src/yoke/options.py
+  - id: capability-tests
+    type: file
+    path: tests/test_capabilities.py
+---
+
+# Capability Planning
+
+Capability planning is the runtime check that decides whether a [Yoke Harness](../concepts/yoke-harness) can perform the requested work on one concrete [Provider Surface](../concepts/provider-surfaces). It gathers feature requirements from the agent and the selected options, resolves or validates the surface, and returns a `Plan` before provider execution starts [@models]. This makes provider differences explicit: a Codex or Claude provider name is not enough to promise streaming, callbacks, goals, workflows, or native collaboration behavior.
+
+## Inputs To The Plan
+
+The feature language lives in `Feature` and `Support`. Features name things Yoke can reason about, such as one-shot runs, sessions, streaming, structured output, models, permissions, request events, goals, interrupts, workflows, native workflows, skills, plugins, MCP, and collaboration-agent tools [@capabilities]. Support values are `native`, `compiled`, `emulated`, `unsupported`, and `unknown` [@capabilities].
+
+The harness builds its required feature set from two places. Agent definitions contribute features for goals, skills, subagents, workflows, and provider options, while run, session, goal-loop, and workflow options contribute runtime requirements such as structured output, event callbacks, sessions, goals, native workflows, or provider-specific permissions [@models] [@options].
+
+## Surface Selection
+
+Yoke keeps a profile for each known provider surface. A profile carries the provider, surface, broad channel, runtime, capability matrix, default status, and whether this package has a runnable adapter for that surface [@capabilities] [@surfaces].
+
+When a harness has an explicit surface, planning validates that surface against the required features and reports missing support instead of silently switching surfaces [@models]. When the surface is omitted, planning can select the best known surface for the required features, optional channel, and runnable constraint [@models] [@surfaces].
+
+Selection ranks candidate profiles by how well they satisfy the required features and by their total capability score [@surfaces]. Tests cover the important behavior: `run_event_callbacks` selects Codex app-server or Claude Python SDK automatically, explicit unsupported Codex surfaces fail before a run starts, native Claude workflow requests can select a non-runnable TypeScript SDK profile unless `runnable=True` is required, and unsupported feature sets raise diagnostics that list considered surfaces [@capability-tests].
+
+## Why It Matters
+
+Planning is the guardrail between product promises and provider mechanics. [Runtime Flow](runtime-flow) explains the execution path, but capability planning is the point where Yoke decides whether that path is allowed for the selected surface.
+
+This is why [Provider Surfaces Are First-Class](../decisions/provider-surfaces-first-class) matters in day-to-day changes. Adding a new option, workflow shape, event callback, permission mode, or provider-native behavior should update the feature requirement and capability matrix together, then add tests that prove the harness selects, validates, or rejects the intended surfaces [@options] [@surfaces] [@capability-tests].
@@ -41,6 +41,8 @@ features, then calls the adapter's `run(...)` method [@models] [@ports]. The
 adapter owns the provider protocol from that point: Claude SDK messages, Codex
 app-server notifications, Codex SDK events, and Codex CLI JSONL output all enter
 Yoke through adapter code rather than through product services [@ports].
+The surface selection and rejection rules for those feature checks are detailed
+in [Capability Planning](capability-planning).
 
 Streaming follows the same boundary. `Harness.stream(...)` creates or resumes a
 session, asks the adapter to stream one turn, and yields normalized events
 
@@ -41,7 +41,7 @@ When no explicit surface is set, `profile_for` uses provider defaults, and `sele
 
 Capabilities are expressed as features with support levels. The `Feature` enum includes one-shot runs, sessions, streaming, structured output, model listing, login, permissions, request events, subagents, skills, plugins, hooks, MCP, goals, interrupts, forks, workflows, native workflows, and experimental APIs [@capabilities].
 
-Each feature has a support value: `native`, `compiled`, `emulated`, `unsupported`, or `unknown` [@capabilities]. Reports can also include notes, lowering descriptions, recipes, and evidence for a feature on a surface [@surfaces].
+Each feature has a support value: `native`, `compiled`, `emulated`, `unsupported`, or `unknown` [@capabilities]. Reports can also include notes, lowering descriptions, recipes, and evidence for a feature on a surface [@surfaces]. The runtime selection rules are covered in [Capability Planning](../architecture/capability-planning).
 
 Feature support also changes how Yoke explains product-facing promises. The README says skills may be native skill roots on the Codex app-server but compiled to files on other surfaces, Codex app-server subagents are compiled into guidance to use native `spawn_agent`, goals are native state only on the Codex app-server, and workflows are portable Yoke constructs across the listed surfaces [@readme]. These are not marketing distinctions; they are the support levels and lowering descriptions that `harness.explain()` exposes through the capability matrix [@surfaces].
 
 
@@ -44,7 +44,7 @@ The constructor accepts compact provider specs such as `codex:app`, then normali
 
 The harness asks the selected provider adapter to execute work. `ProviderAdapter` defines the boundary for readiness checks, login, runs, model listing, workflows, goal loops, session listing, session reads, session starts, sends, streams, goal mutation, interruption, compaction, renaming, tagging, forking, and close operations [@ports].
 
-Before many operations, the harness resolves required features. `run`, `stream`, `start`, `workflow`, `models`, and session-management methods all call capability planning helpers before delegating to an adapter [@models]. This is where the harness connects to [Provider Surfaces](provider-surfaces): the selected surface must support the features implied by the agent and options. See [Workflows](workflows) for the split between portable Yoke orchestration and provider-native workflow artifacts.
+Before many operations, the harness resolves required features. `run`, `stream`, `start`, `workflow`, `models`, and session-management methods all call capability planning helpers before delegating to an adapter [@models]. This is where the harness connects to [Provider Surfaces](provider-surfaces): the selected surface must support the features implied by the agent and options. For the exact selection and validation flow, read [Capability Planning](../architecture/capability-planning). See [Workflows](workflows) for the split between portable Yoke orchestration and provider-native workflow artifacts.
 
 The CLI is one concrete harness caller. It loads a folder collection, creates a harness for the selected provider surface, and stores run or workflow results after execution [@cli]; see [CLI And Run Storage](../reference/cli-and-run-storage) for that shell contract.