@openwop/spec-artifacts 2.42.6 → 2.42.8

package/api/v2/openapi.yaml

@@ -1,12 +1,15 @@
 openapi: 3.1.0
 info:
   title: OpenWOP v2 API
-  version: 2.42.6
+  version: 2.42.8
   summary: REST surface for declaring, executing, suspending, resuming, and observing multi-step workflows.
-  description: GENERATED by scripts/derive-v2-api.py from api/openapi.yaml and the RFC 0167 children (v2 charter Phase 3,
-    P3-C). Bare origin, unversioned path keys, negotiation by `OpenWOP-Version` + `protocolVersions[]` (RFC 0172 §A). No seam
-    or test-mode operation lives here (RFC 0168 §C.2 — see api/seams-v2.yaml). Every non-standard header is `OpenWOP-<Name>`
-    (RFC 0171 §C.1). Retry timing lives in `Retry-After` only (RFC 0171 §B.2).
+  description: 'The OpenWOP v2 REST API. Paths are unversioned and served at the bare origin; a client selects a version with
+    the `OpenWOP-Version` header from the host''s `protocolVersions[]`. Conformance seams and test-mode operations are not
+    in this document: they are in `api/seams-v2.yaml`. Every non-standard header is named `OpenWOP-<Name>`. Retry timing is
+    carried only in `Retry-After`.
+
+
+    Generated from `api/openapi.yaml` by `scripts/derive-v2-api.py`; do not edit.'
   contact:
     name: openwop spec working group
     url: https://openwop.dev/spec/v1/
@@ -14,11 +17,11 @@ info:
     name: Apache-2.0
     identifier: Apache-2.0
 externalDocs:
-  description: openwop spec v1 corpus
+  description: OpenWOP specification (v1 corpus)
   url: https://openwop.dev/spec/v1/
 servers:
 - url: https://{host}
-  description: openwop-compliant server
+  description: An OpenWOP server.
   variables:
     host:
       default: api.example.com
@@ -33,11 +36,11 @@ tags:
 - name: runs
   description: Run lifecycle — create, read, stream, cancel, fork.
 - name: agents
-  description: Manifest-agent inventory (RFC 0072 §A). Read-only; gated on capabilities.agents.manifestRuntime. Dispatch rides
-    the run surface (WorkflowNode.agent + POST /v1/runs).
+  description: Manifest-agent inventory. Read-only; gated on `capabilities.agents.manifestRuntime`. Dispatch uses the run
+    surface (`WorkflowNode.agent` + `POST /runs`).
 - name: tools
-  description: Portable tool catalog (RFC 0078 §B). Read-only ToolDescriptor projection across tool sources (node-pack / workflow
-    / mcp / connector / host-extension); gated on capabilities.toolCatalog; authorization-scoped per §F-2.
+  description: 'Portable tool catalog: a read-only `ToolDescriptor` projection across tool sources (node-pack, workflow, mcp,
+    connector, host-extension). Gated on `capabilities.toolCatalog`; scoped to the tools the caller is authorized to invoke.'
 - name: hitl
   description: Human-in-the-loop interrupts and approvals.
 - name: artifacts
@@ -45,16 +48,16 @@ tags:
 - name: webhooks
   description: Subscribe to run events via outbound HTTP.
 - name: triggers
-  description: Durable trigger-bridge subscriptions (RFC 0083). RFC 0099 adds the external-event create surface (`POST /v1/trigger-subscriptions`);
+  description: Durable trigger-bridge subscriptions. The external-event create surface (`POST /trigger-subscriptions`) is
     gated on `capabilities.triggerBridge.ingestion.registrationEndpoint`.
 - name: audit
   description: Audit-log integrity verification (gated on the `openwop-audit-log-integrity` profile).
 - name: prompts
-  description: Prompt-template library — list, fetch, render, mutate (RFC 0028; gated on `capabilities.prompts.*`).
+  description: 'Prompt-template library: list, fetch, render, mutate. Gated on `capabilities.prompts.*`.'
 - name: content
-  description: Localized authored content — public delivery + tenant-scoped admin CRUD (RFC 0103; gated on `capabilities.content.supported`).
+  description: 'Localized authored content: public delivery and tenant-scoped admin CRUD. Gated on `capabilities.content.supported`.'
 - name: host
-  description: Host-capability resources — e.g. the RFC 0059 agent workspace file store (gated on `capabilities.workspace.*`).
+  description: Host-capability resources, such as the agent workspace file store (gated on `capabilities.workspace.*`).
 paths:
   /.well-known/openwop:
     get:
@@ -69,11 +72,11 @@ paths:
         required: false
         schema:
           type: string
-        description: 'RFC 0165 §C.2; runs.md §Snapshot. Standard conditional request against any resource that carries an
-          `ETag` — the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot): a matching value
-          MUST yield `304 Not Modified` with no body, and the 304 carries `OpenWOP-Version` like every response (versioning.md
-          §1.4).'
+        description: Conditional request on the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot).
+          A value matching the `ETag` the host sent MUST yield `304 Not Modified` with no body. The 304 carries `OpenWOP-Version`
+          like every response (versioning.md §1.4).
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Capabilities object — see `capabilities.md`.
@@ -85,9 +88,8 @@ paths:
             ETag:
               schema:
                 type: string
-              description: 'capabilities.md §1 (RFC 0165 §C.2). Standard strong validator for the discovery document: a v2
-                host MUST send it and MUST honor `If-None-Match` with `304`; a host that changes semantics without changing
-                the bytes is non-conformant.'
+              description: Strong validator for the discovery document (capabilities.md §1). A v2 host MUST send it and MUST
+                honor `If-None-Match` with `304`. A host that changes semantics without changing the bytes is non-conformant.
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
           content:
@@ -95,7 +97,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Capabilities'
         '304':
-          description: RFC 0165 §C.2 — `If-None-Match` matched the current `ETag`; the body is unchanged.
+          description: '`If-None-Match` matched the current `ETag`; the body is unchanged.'
           headers:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
@@ -136,6 +138,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /workflows/{workflowId}:
     get:
       tags:
@@ -152,6 +155,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/WorkflowId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Workflow definition.
@@ -189,26 +193,18 @@ paths:
           type: string
           enum:
           - enforce
-        description: When set, server cross-host claim system rejects duplicate `(tenantId, scopeId)` pairs with `409 Conflict`.
+        description: When set, the host's cross-host claim system rejects a duplicate `(tenantId, scopeId)` pair with `409
+          Conflict`.
       - in: header
         name: OpenWOP-Force-Engine-Version
         schema:
           type: integer
           minimum: 0
-        description: '**Test-keys-only.** When set, the server emits events for this run AS IF it
-
-          were running the specified engine version (must be within the server''s
-
-          advertised `Capabilities.testing.forceEngineVersionRange`). Used by the
-
-          conformance suite to verify version-negotiation fold-best-effort tolerance
-
-          across the spec''s forward-compat matrix. Servers MUST reject on production
-
-          API keys with `403 force_engine_version_forbidden`. Closes F5.
-
-          '
+        description: Test keys only. The server emits this run's events as if it ran the given engine version, which must
+          be within `Capabilities.testing.forceEngineVersionRange`. Servers MUST reject it on production API keys with `403
+          force_engine_version_forbidden`.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -228,10 +224,10 @@ paths:
                     $ref: ../../schemas/v2/residency.schema.json
                   tenantId:
                     type: string
-                    description: Tenant scoping. Server typically defaults from API key.
+                    description: Tenant scope. A host typically derives it from the API key.
                   scopeId:
                     type: string
-                    description: Opaque correlation ID for `X-Dedup` semantics.
+                    description: Opaque correlation ID for `OpenWOP-Dedup`.
                   callbackUrl:
                     type: string
                     format: uri
@@ -240,29 +236,18 @@ paths:
                     type: string
                     enum:
                     - eval
-                    description: 'RFC 0081 §B. When `eval`, this run is an eval-suite projection
-
-                      (not a workflow run): the host runs the `evalSuiteRef` against
-
-                      `agentId`, emits the content-free `eval.*` family, and terminates
-
-                      with an `EvalSummary` readable via `GET /v1/runs/{runId}/eval-summary`.
-
-                      Capability-gated on `capabilities.agents.evalSuite.supported`; a
-
-                      host that omits it rejects `mode: "eval"` with 501. Omit for a
-
-                      normal workflow run.
-
-                      '
+                    description: 'Set to `eval` to run an eval-suite projection instead of a workflow run: the host runs the
+                      `evalSuiteRef` against `agentId`, emits the content-free `eval.*` family, and terminates with an `EvalSummary`
+                      readable at `GET /runs/{runId}/eval-summary`. Gated on `capabilities.agents.evalSuite.supported`; a
+                      host that omits it rejects `mode: "eval"` with 501. Omit for a normal workflow run.'
                   evalSuiteRef:
                     type: string
                     minLength: 1
-                    description: RFC 0081 — URI of the `AgentEvalSuite` to run. Required when mode is `eval`.
+                    description: URI of the `AgentEvalSuite` to run. Required when mode is `eval`.
                   agentId:
                     type: string
                     minLength: 1
-                    description: RFC 0081 — the manifest agent the eval suite targets. Required when mode is `eval`.
+                    description: The manifest agent the eval suite targets. Required when mode is `eval`.
                 if:
                   properties:
                     mode:
@@ -319,7 +304,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '409':
-          description: '`X-Dedup` collision OR concurrent `Idempotency-Key` collision.'
+          description: An `OpenWOP-Dedup` collision, or a concurrent `Idempotency-Key` collision.
           headers:
             Retry-After:
               schema:
@@ -337,11 +322,13 @@ paths:
       tags:
       - runs
       operationId: listRuns
-      summary: The caller's runs, newest first, cursor-paginated (RFC 0182)
-      description: 'Tenant-scoped by construction: only runs whose tenant segment is the caller''s, every runId bound (identity.md
-        §5). Gated on the `runList` family — 404 not_found when unadvertised. `limit` is honoured up to `runList.maxPageSize`;
-        `cursor` is opaque and a cursor the host did not mint is 400 validation_error; `workflowId` and `status` are exact-match
-        filters when `runList.filters` names them (an unadvertised filter is ignored).'
+      summary: List the caller's runs, newest first
+      description: 'Lists only runs whose tenant segment is the caller''s; every `runId` is tenant-bound (identity.md §5).
+        The list is cursor-paginated. Gated on the `runList` family: a host that does not advertise it answers `404 not_found`.
+
+
+        `limit` is honoured up to `runList.maxPageSize`. `cursor` is opaque; a cursor the host did not mint is `400 validation_error`.
+        `workflowId` and `status` are exact-match filters when `runList.filters` names them; an unadvertised filter is ignored.'
       parameters:
       - name: limit
         in: query
@@ -349,7 +336,7 @@ paths:
         schema:
           type: integer
           minimum: 1
-        description: Page size; clamped to runList.maxPageSize.
+        description: Page size; clamped to `runList.maxPageSize`.
       - name: cursor
         in: query
         required: false
@@ -357,13 +344,13 @@ paths:
           type: string
           minLength: 1
           maxLength: 2048
-        description: Opaque cursor from a previous page's nextCursor.
+        description: Opaque cursor from a previous page's `nextCursor`.
       - name: workflowId
         in: query
         required: false
         schema:
           $ref: ../../schemas/v2/ids.schema.json#/$defs/workflowId
-        description: Exact-match filter (when advertised in runList.filters).
+        description: Exact-match filter, when advertised in `runList.filters`.
       - name: status
         in: query
         required: false
@@ -380,8 +367,9 @@ paths:
           - failed
           - cancelling
           - cancelled
-        description: Exact-match filter (when advertised in runList.filters).
+        description: Exact-match filter, when advertised in `runList.filters`.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: One page of the caller's runs.
@@ -425,11 +413,11 @@ paths:
         required: false
         schema:
           type: string
-        description: 'RFC 0165 §C.2; runs.md §Snapshot. Standard conditional request against any resource that carries an
-          `ETag` — the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot): a matching value
-          MUST yield `304 Not Modified` with no body, and the 304 carries `OpenWOP-Version` like every response (versioning.md
-          §1.4).'
+        description: Conditional request on the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot).
+          A value matching the `ETag` the host sent MUST yield `304 Not Modified` with no body. The 304 carries `OpenWOP-Version`
+          like every response (versioning.md §1.4).
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Projected run state.
@@ -437,13 +425,8 @@ paths:
             ETag:
               schema:
                 type: string
-              description: 'RFC 0115. Strong validator derived from the run''s latest
-
-                persisted event-log sequence number; changes on every
-
-                observable state transition, stable while none occurs.
-
-                '
+              description: Strong validator derived from the run's latest persisted event-log sequence number. It changes
+                on every observable state transition and is stable while none occurs.
             Content-Encoding:
               required: false
               schema:
@@ -452,13 +435,8 @@ paths:
                 - gzip
                 - br
                 - zstd
-              description: 'RFC 0115. Present only when the host negotiated compression
-
-                from `Accept-Encoding`; pairs with `Vary: Accept-Encoding`.
-
-                The decoded body is byte-identical to the identity body.
-
-                '
+              description: 'Present only when the host negotiated compression from `Accept-Encoding`; pairs with `Vary: Accept-Encoding`.
+                The decoded body is byte-identical to the identity body.'
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
           content:
@@ -466,7 +444,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/RunSnapshot'
         '304':
-          description: RFC 0115. Not Modified — `If-None-Match` matched the current `ETag`. Empty body.
+          description: 'Not Modified: `If-None-Match` matched the current `ETag`. Empty body.'
           headers:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
@@ -497,32 +475,24 @@ paths:
           type: string
           pattern: ^(values|(updates|messages|debug)(,(updates|messages|debug))*)$
           default: updates
-        description: RFC 0171 §E.1 — the closed set and its comma-separated combinations; `values` never combines.
+        description: A stream mode from the closed set, or a comma-separated combination of them. `values` never combines.
       - in: query
         name: bufferMs
         schema:
           type: integer
           minimum: 0
           maximum: 5000
-        description: 'Optional batching hint per S3 closure. When set, the server
-
-          accumulates events for up to N ms (or until a forced-flush
-
-          trigger fires — terminal events, suspensions, connection close)
-
-          and emits a single SSE event with `event: batch` and `data:` as
-
-          a JSON array of `RunEventDoc`. Range 0..5000; `0` = no buffering.
-
-          See `stream-modes.md` §Aggregation hint.
-
-          '
+        description: 'Optional batching hint. When set, the server accumulates events for up to N ms, or until a forced-flush
+          trigger fires (terminal events, suspensions, connection close), and emits a single SSE event with `event: batch`
+          and `data:` as a JSON array of `RunEventDoc`. Range 0..5000; `0` means no buffering. See `stream-modes.md` §Aggregation
+          hint.'
       - in: header
         name: Last-Event-ID
         schema:
           type: string
         description: Resume from sequence after this ID.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: SSE stream. Auto-closes on terminal event. Keep-alive comments every 30s.
@@ -569,8 +539,8 @@ paths:
         schema:
           type: integer
           minimum: 0
-        description: RFC 0171 §E.2 — return events with `sequence > afterSequence`; omission means from the first event (sequence
-          0). `lastSequence` and `since` are gone.
+        description: Return events with `sequence > afterSequence`. Omitted, the poll starts from the first event (sequence
+          0).
       - in: query
         name: timeout
         schema:
@@ -580,9 +550,10 @@ paths:
           default: 30
         description: Seconds to wait for new events. Max 60.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
-          description: Events since `lastSequence`.
+          description: Events after `afterSequence`.
           content:
             application/json:
               schema:
@@ -604,8 +575,7 @@ paths:
                   lastSequence:
                     type: integer
                     minimum: -1
-                    description: The highest sequence in the log at the time of the response (one meaning); -1 when the log
-                      is empty.
+                    description: The highest sequence in the log at the time of the response; -1 when the log is empty.
                   status:
                     type: string
                   isTerminal:
@@ -636,6 +606,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         content:
           application/json:
@@ -672,7 +643,7 @@ paths:
     post:
       tags:
       - runs
-      summary: Record a non-blocking quality annotation on a run (RFC 0056).
+      summary: Record a non-blocking quality annotation on a run.
       operationId: createAnnotation
       security:
       - ApiKeyAuth:
@@ -685,6 +656,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -710,7 +682,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Host does not advertise capabilities.feedback.supported (RFC 0056).
+          description: Host does not advertise `capabilities.feedback.supported`.
           content:
             application/json:
               schema:
@@ -721,7 +693,7 @@ paths:
     get:
       tags:
       - runs
-      summary: List the annotations recorded on a run (RFC 0056).
+      summary: List the annotations recorded on a run.
       operationId: listAnnotations
       security:
       - ApiKeyAuth:
@@ -733,6 +705,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Annotations for the run (tenant-scoped).
@@ -758,7 +731,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Host does not advertise capabilities.feedback.supported (RFC 0056).
+          description: Host does not advertise `capabilities.feedback.supported`.
           content:
             application/json:
               schema:
@@ -770,20 +743,11 @@ paths:
     post:
       tags:
       - triggers
-      summary: Register an external-event trigger subscription (RFC 0099).
-      description: 'Creates an external-event (`webhook`/`email`/`form`) TriggerSubscription
-
-        bound to a workflow, with a dedup config and a source-authenticity
-
-        verification policy (RFC 0099 §F.2). The `workflowId` MUST resolve under
-
-        the caller''s RFC 0048 owner triple. The response carries the created
-
-        TriggerSubscription plus a source-specific `binding`; the binding
-
-        secret/URL is returned ONCE and is not re-fetchable in cleartext.
-
-        '
+      summary: Register an external-event trigger subscription.
+      description: Creates an external-event (`webhook`/`email`/`form`) TriggerSubscription bound to a workflow, with a dedup
+        config and a source-authenticity verification policy. The `workflowId` MUST resolve under the caller's owner triple.
+        The response carries the created TriggerSubscription plus a source-specific `binding`; the binding secret or URL is
+        returned once and cannot be re-fetched in cleartext.
       operationId: createTriggerSubscription
       security:
       - ApiKeyAuth:
@@ -795,6 +759,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -817,15 +782,9 @@ paths:
                     $ref: ../../schemas/v2/trigger-subscription.schema.json
                   binding:
                     type: object
-                    description: 'Source-specific binding the caller needs to wire the external
-
-                      source. For `webhook`: `{ ingestUrl, secretFingerprint }`; for
-
-                      `email`: `{ ingestAddress }`; for `form`: `{ ingestUrl }`. The
-
-                      secret is returned once at creation (SR-1).
-
-                      '
+                    description: 'Source-specific binding the caller needs to wire the external source. For `webhook`: `{
+                      ingestUrl, secretFingerprint }`; for `email`: `{ ingestAddress }`; for `form`: `{ ingestUrl }`. The
+                      secret is returned once, at creation (SR-1).'
                     additionalProperties: true
                     properties:
                       ingestUrl:
@@ -846,7 +805,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '501':
-          description: Host does not advertise capabilities.triggerBridge.ingestion.registrationEndpoint (RFC 0099).
+          description: Host does not advertise `capabilities.triggerBridge.ingestion.registrationEndpoint`.
           content:
             application/json:
               schema:
@@ -859,32 +818,19 @@ paths:
       tags:
       - content
       security: []
-      summary: Deliver a published content page resolved for the negotiated locale (RFC 0103 §D).
-      description: 'Resolves the published page `slug` for the locale negotiated from
-
-        `Accept-Language` (i18n.md fallback: q-value order → language family →
-
-        `content.baseLocale`), applies the per-section field merge
-
-        (`localized-content.md` §C), and returns the already-merged sections in
-
-        render order. Sets `Content-Language` to the locale used,
+      summary: Deliver a published content page resolved for the negotiated locale.
+      description: 'Returns the published page `slug` for the locale negotiated from `Accept-Language`, with its sections
+        already merged, in render order. Locale fallback follows i18n.md: q-value order, then language family, then `content.baseLocale`.
+        Sections are merged field by field (`localized-content.md` §C).
 
-        `Vary: Accept-Language, Accept-Encoding`, and
 
-        `Cache-Control: public, max-age=300, stale-while-revalidate=3600`.
+        The response sets `Content-Language` to the locale used, `Vary: Accept-Language, Accept-Encoding`, and `Cache-Control:
+        public, max-age=300, stale-while-revalidate=3600`. Only `status: "published"` content is served.
 
-        Serves `status: "published"` content only. Tenant is host-resolved
 
-        (`localized-content.md` §F): credential-derived when authenticated,
-
-        host-defined (e.g. domain) when anonymous. A `slug` absent for the
-
-        resolved tenant returns the same `404` as a nonexistent slug (no
-
-        cross-tenant enumeration).
-
-        '
+        The tenant is host-resolved (`localized-content.md` §F): from the credential when authenticated, host-defined (for
+        example by domain) when anonymous. A `slug` absent for the resolved tenant returns the same `404` as a nonexistent
+        slug, so tenants cannot be enumerated.'
       operationId: getContentPage
       parameters:
       - name: slug
@@ -899,8 +845,10 @@ paths:
         required: false
         schema:
           type: string
-        description: BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT 400.
+        description: BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT produce
+          a 400.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The resolved, published page for the negotiated locale.
@@ -918,7 +866,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Host does not advertise capabilities.content.supported (RFC 0103).
+          description: Host does not advertise `capabilities.content.supported`.
           content:
             application/json:
               schema:
@@ -929,28 +877,15 @@ paths:
     delete:
       tags:
       - content
-      summary: Delete a content page (RFC 0103 §D, admin).
-      description: '`localized-content.md` §D lists `DELETE …/content/pages/{pageId}` among
-
-        the admin CRUD operations: tenant-scoped, requires `content.write`, and
-
-        removes the page with its sections and every locale overlay. The path
-
-        segment is the page''s **`pageId`**, not its slug. It shares this path
-
-        item with public delivery, which addresses the same segment by `slug`,
+      summary: Delete a content page (admin).
+      description: 'Deletes a page with its sections and every locale overlay: the `DELETE …/content/pages/{pageId}` admin
+        operation of `localized-content.md` §D. Tenant-scoped; requires `content.write`.
 
-        because OpenAPI 3.1 treats two templates that differ only in the
 
-        parameter name as identical and forbids them; the parameter keeps
-
-        delivery''s name for that reason alone. A `pageId` absent for the
-
-        caller''s tenant returns the same `404` as a nonexistent one
-
-        (`localized-content.md` §F, no cross-tenant enumeration).
-
-        '
+        The path segment is the page''s `pageId`, not its slug. The operation shares this path item with public delivery,
+        which addresses the same segment by `slug`, and OpenAPI 3.1 forbids two templates that differ only in parameter name,
+        so the parameter keeps delivery''s name. A `pageId` absent for the caller''s tenant returns the same `404` as a nonexistent
+        one (`localized-content.md` §F), so tenants cannot be enumerated.'
       operationId: deleteContentPage
       security:
       - ApiKeyAuth:
@@ -966,8 +901,10 @@ paths:
         schema:
           type: string
           minLength: 1
-        description: For this operation, the page's `pageId` (§D). See the operation description for why the name is shared.
+        description: For this operation, the page's `pageId`, not its slug; the operation description explains the shared
+          name.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '204':
           description: The page, its sections and its locale overlays were deleted.
@@ -984,12 +921,8 @@ paths:
     get:
       tags:
       - content
-      summary: List content pages for the caller's tenant (RFC 0103 §D, admin).
-      description: 'Tenant-scoped admin listing of pages (draft + published). Requires a
-
-        principal with `content.read` scope.
-
-        '
+      summary: List content pages for the caller's tenant (admin).
+      description: Tenant-scoped admin listing of pages, draft and published. Requires a principal with `content.read` scope.
       operationId: listContentPages
       security:
       - ApiKeyAuth:
@@ -1015,7 +948,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '501':
-          description: Host does not advertise capabilities.content.supported (RFC 0103).
+          description: Host does not advertise `capabilities.content.supported`.
           content:
             application/json:
               schema:
@@ -1025,10 +958,11 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     post:
       tags:
       - content
-      summary: Create a content page (RFC 0103 §D, admin).
+      summary: Create a content page (admin).
       description: Tenant-scoped page creation. Requires `content.write` scope.
       operationId: createContentPage
       security:
@@ -1055,7 +989,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: Invalid request (e.g. baseLocale in supportedLocales, or a malformed locale/slug).
+          description: Invalid request (for example `baseLocale` in `supportedLocales`, or a malformed locale or slug).
           content:
             application/json:
               schema:
@@ -1069,18 +1003,14 @@ paths:
           $ref: '#/components/responses/Forbidden'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /content/pages/{pageId}/sections/{sectionId}:
     put:
       tags:
       - content
-      summary: Upsert a section's base or per-locale fields (RFC 0103 §D, admin).
-      description: 'Locale-targeted write: `locale == content.baseLocale` upserts the
-
-        section''s base `data`; any other (case-canonical BCP 47 subset, RFC 0206) locale upserts
-
-        `localizations[locale]`. Tenant-scoped; requires `content.write`.
-
-        '
+      summary: Upsert a section's base or per-locale fields (admin).
+      description: Locale-targeted write. `locale == content.baseLocale` upserts the section's base `data`; any other locale
+        (case-canonical BCP 47 subset) upserts `localizations[locale]`. Tenant-scoped; requires `content.write`.
       operationId: putContentSection
       security:
       - ApiKeyAuth:
@@ -1103,6 +1033,7 @@ paths:
           type: string
           minLength: 1
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1117,7 +1048,7 @@ paths:
                 locale:
                   type: string
                   pattern: ^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$
-                  description: Target locale; baseLocale upserts `data`, else `localizations[locale]`.
+                  description: Target locale. `baseLocale` upserts `data`; any other locale upserts `localizations[locale]`.
                 data:
                   type: object
                   additionalProperties: true
@@ -1133,7 +1064,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: Invalid request (e.g. baseLocale in supportedLocales, or a malformed locale/slug).
+          description: Invalid request (for example `baseLocale` in `supportedLocales`, or a malformed locale or slug).
           content:
             application/json:
               schema:
@@ -1151,7 +1082,7 @@ paths:
     get:
       tags:
       - content
-      summary: Read the tenant's content language settings (RFC 0103 §B, admin).
+      summary: Read the tenant's content language settings (admin).
       description: Tenant-scoped read of `{ baseLocale, supportedLocales, autoTranslateOnPublish }`. Requires `content.read`.
       operationId: getContentSettings
       security:
@@ -1176,7 +1107,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '501':
-          description: Host does not advertise capabilities.content.supported (RFC 0103).
+          description: Host does not advertise `capabilities.content.supported`.
           content:
             application/json:
               schema:
@@ -1186,15 +1117,13 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     put:
       tags:
       - content
-      summary: Update the tenant's content language settings (RFC 0103 §B, admin).
-      description: 'Tenant-scoped settings update. The invariant `baseLocale ∉
-
-        supportedLocales` MUST hold (else `400`). Requires `content.write`.
-
-        '
+      summary: Update the tenant's content language settings (admin).
+      description: Tenant-scoped settings update. The invariant `baseLocale ∉ supportedLocales` MUST hold, else `400`. Requires
+        `content.write`.
       operationId: putContentSettings
       security:
       - ApiKeyAuth:
@@ -1220,7 +1149,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: Invalid request (e.g. baseLocale in supportedLocales, or a malformed locale/slug).
+          description: Invalid request (for example `baseLocale` in `supportedLocales`, or a malformed locale or slug).
           content:
             application/json:
               schema:
@@ -1234,26 +1163,16 @@ paths:
           $ref: '#/components/responses/Forbidden'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /runs:bulk-cancel:
     post:
       tags:
       - runs
       summary: Cancel a set of in-flight runs in a single request.
-      description: 'Per `spec/v1/rest-endpoints.md` §"POST /v1/runs:bulk-cancel". Accepts
-
-        a non-empty array of runIds and processes each cancellation
-
-        independently. Returns `200` with a per-id results array even when
-
-        some individual cancellations fail; the top-level operation succeeds
-
-        when the request reached the host, regardless of per-id outcomes.
-
-        Hosts enforce a host-defined cap on the array length (RECOMMENDED
-
-        100); over-cap requests return `400 validation_error`.
-
-        '
+      description: 'Accepts a non-empty array of runIds and cancels each one independently. Returns `200` with a per-id results
+        array even when some cancellations fail: the operation succeeds when the request reached the host, whatever the per-id
+        outcomes. Hosts enforce a host-defined cap on the array length (RECOMMENDED 100); an over-cap request returns `400
+        validation_error`.'
       operationId: bulkCancelRuns
       security:
       - ApiKeyAuth:
@@ -1265,6 +1184,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1345,6 +1265,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1357,15 +1278,9 @@ paths:
                 fromSeq:
                   type: integer
                   minimum: 0
-                  description: 'Inclusive — events `< fromSeq` are fixed history; `>= fromSeq` are re-executed.
-
-                    Required for `branch` (the branch point). Optional for `replay`; when omitted,
-
-                    defaults to `0` (full re-execution from source-run start) per `replay.md`
-
-                    §"Replay-mode defaults".
-
-                    '
+                  description: 'Inclusive: events `< fromSeq` are fixed history and events `>= fromSeq` are re-executed. Required
+                    for `branch` (the branch point). Optional for `replay`, where it defaults to `0`, full re-execution from
+                    the start of the source run (`replay.md` §"Replay-mode defaults").'
                 mode:
                   type: string
                   enum:
@@ -1373,7 +1288,7 @@ paths:
                   - branch
                 runOptionsOverlay:
                   type: object
-                  description: For `branch` mode only — caller-supplied `RunOptions` to overlay.
+                  description: '`branch` mode only: caller-supplied `RunOptions` to overlay.'
               additionalProperties: false
       responses:
         '201':
@@ -1409,7 +1324,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: Invalid `fromSeq`, `replay` with non-empty `runOptionsOverlay`, etc.
+          description: Invalid `fromSeq`, `replay` with a non-empty `runOptionsOverlay`, and similar.
           content:
             application/json:
               schema:
@@ -1424,7 +1339,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '422':
-          description: '`fromSeq` references a sequence number that doesn''t exist in the source run''s event log.'
+          description: '`fromSeq` names a sequence number that does not exist in the source run''s event log.'
           content:
             application/json:
               schema:
@@ -1436,19 +1351,10 @@ paths:
     get:
       tags:
       - runs
-      summary: 'RFC 0040 §C — return the run''s immediate parent in the cross-host
-
-        composition chain. Capability-gated on
-
-        `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`;
-
-        hosts that don''t advertise return 404 not_found. Clients walk the full
-
-        chain by following `parent.wellKnownUrl` per response, one hop at a
-
-        time.
-
-        '
+      summary: Read a run's parent in the cross-host composition chain
+      description: 'Returns the run''s immediate parent in the cross-host composition chain. Gated on `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported:
+        true`; a host that does not advertise it returns 404 not_found. Clients walk the full chain one hop at a time by following
+        `parent.wellKnownUrl` in each response.'
       operationId: getRunAncestry
       security:
       - ApiKeyAuth:
@@ -1460,11 +1366,10 @@ paths:
       parameters:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
-          description: 'Run''s immediate parent (or `parent: null` for top-level runs).
-
-            '
+          description: 'The run''s immediate parent (`parent: null` for a top-level run).'
           content:
             application/json:
               schema:
@@ -1477,15 +1382,8 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '404':
-          description: 'Either the run doesn''t exist, OR the host doesn''t advertise
-
-            `crossHostCausation.ancestryEndpointSupported: true` and treats
-
-            the endpoint as absent. Clients can disambiguate by inspecting
-
-            the host''s discovery doc.
-
-            '
+          description: 'The run does not exist, or the host does not advertise `crossHostCausation.ancestryEndpointSupported:
+            true` and treats the endpoint as absent. Clients can tell the two apart from the host''s discovery document.'
           content:
             application/json:
               schema:
@@ -1497,35 +1395,18 @@ paths:
     get:
       tags:
       - agents
-      summary: 'RFC 0072 §A — list the manifest agents this host has installed into its
-
-        AgentRegistry (RFC 0070). Capability-gated on
-
-        `capabilities.agents.manifestRuntime.supported: true`; hosts that don''t
-
-        advertise it return 404. Read-only projection — never carries the
-
-        system-prompt body, resolved handoff schemas, or credential material (SR-1).
-
-        Dispatch is not a bespoke endpoint: a manifest agent is invoked as a run
-
-        whose node pins it via `WorkflowNode.agent` + `POST /v1/runs` (RFC 0072 §B).
-
-        RFC 0074 — the result is scoped to the authenticated principal''s owner
-
-        triple (RFC 0048). When `capabilities.agents.manifestRuntime.installScope`
-
-        is `''tenant''`, only the agents available to the caller''s tenant·workspace
-
-        are returned (an agent another workspace installed is absent, never
-
-        disclosed); when `''host''` (default) the inventory is host-global as in
-
-        RFC 0072. A `''tenant''`-scoped host MUST reject unauthenticated/unscoped
-
-        requests per its standard auth contract rather than fall back to a global list.
-
-        '
+      summary: List installed manifest agents
+      description: 'Lists the manifest agents installed in this host''s AgentRegistry. Gated on `capabilities.agents.manifestRuntime.supported:
+        true`; a host that does not advertise it returns 404. The projection is read-only and never carries the system-prompt
+        body, resolved handoff schemas, or credential material (SR-1). There is no dispatch endpoint: a manifest agent is
+        invoked as a run whose node pins it with `WorkflowNode.agent` + `POST /runs`.
+
+
+        The result is scoped to the authenticated principal''s owner triple. When `capabilities.agents.manifestRuntime.installScope`
+        is `''tenant''`, only the agents available to the caller''s tenant and workspace are returned; an agent another workspace
+        installed is absent, never disclosed. When it is `''host''` (the default), the inventory is host-global. A `''tenant''`-scoped
+        host MUST reject unauthenticated or unscoped requests under its standard auth contract rather than fall back to a
+        global list.'
       operationId: listAgents
       security:
       - ApiKeyAuth:
@@ -1536,9 +1417,9 @@ paths:
         - runs:read
       responses:
         '200':
-          description: 'Installed manifest agents (agentId-sorted). RFC 0202: when the host advertises `a2a.agentCards`, an
-            entry the host routes a workflow to carries `a2aTenant`, the opaque A2A `tenant` value of that agent''s card (interop.md
-            §Per-agent cards).'
+          description: Installed manifest agents, sorted by `agentId`. When the host advertises `a2a.agentCards`, an entry
+            the host routes a workflow to carries `a2aTenant`, the opaque A2A `tenant` value of that agent's card (interop.md
+            §Per-agent cards).
           content:
             application/json:
               schema:
@@ -1551,11 +1432,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '404':
-          description: 'Host does not advertise `capabilities.agents.manifestRuntime` and
-
-            treats the endpoint as absent.
-
-            '
+          description: Host does not advertise `capabilities.agents.manifestRuntime` and treats the endpoint as absent.
           content:
             application/json:
               schema:
@@ -1565,25 +1442,16 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /agents/{agentId}:
     get:
       tags:
       - agents
-      summary: 'RFC 0072 §A — return one installed manifest agent''s inventory entry, or
-
-        404 when no such agent is installed (or the host doesn''t advertise
-
-        `capabilities.agents.manifestRuntime`). RFC 0074 — resolved within the
-
-        authenticated principal''s owner triple (RFC 0048): on an
-
-        `installScope: ''tenant''` host an agent the caller''s workspace has not
-
-        approved 404s identically to "not installed", so the surface never
-
-        discloses another tenant''s inventory.
-
-        '
+      summary: Read one installed manifest agent
+      description: 'Returns one installed manifest agent''s inventory entry, or 404 when no such agent is installed or the
+        host does not advertise `capabilities.agents.manifestRuntime`. The lookup is resolved within the authenticated principal''s
+        owner triple: on an `installScope: ''tenant''` host, an agent the caller''s workspace has not approved returns the
+        same 404 as "not installed", so another tenant''s inventory is never disclosed.'
       operationId: getAgent
       security:
       - ApiKeyAuth:
@@ -1599,21 +1467,14 @@ paths:
         schema:
           type: string
           pattern: ^(?!roster$|org-chart$).+$
-        description: 'The manifest agentId. MUST NOT be the reserved literals `roster` or
-
-          `org-chart` — those name the sibling collection routes
-
-          (`/v1/agents/roster`, `/v1/agents/org-chart`), so excluding them here
-
-          keeps `/v1/agents/{agentId}` unambiguous against them.
-
-          '
+        description: The manifest agentId. MUST NOT be the reserved literals `roster` or `org-chart`, which name the sibling
+          collection routes (`/agents/roster`, `/agents/org-chart`), so `/agents/{agentId}` stays unambiguous.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
-          description: 'The agent''s inventory entry. RFC 0202: when the host advertises `a2a.agentCards`, an entry the host
-            routes a workflow to carries `a2aTenant`, the opaque A2A `tenant` value of that agent''s card (interop.md §Per-agent
-            cards).'
+          description: The agent's inventory entry. When the host advertises `a2a.agentCards`, an entry the host routes a
+            workflow to carries `a2aTenant`, the opaque A2A `tenant` value of that agent's card (interop.md §Per-agent cards).
           content:
             application/json:
               schema:
@@ -1638,21 +1499,11 @@ paths:
     get:
       tags:
       - agents
-      summary: 'RFC 0082 §C/§E — list the deployment records (per-(agentId, version)) for
-
-        a manifest agent: the lifecycle `state`, the named `channels`, the canary
-
-        share, the rollback pointer, and the last-transition provenance. Read-only,
-
-        content-free of any manifest body or credential (SR-1). Capability-gated on
-
-        `capabilities.agents.deployment.supported: true`; hosts that don''t advertise
-
-        it return 404. Tenant-scoped to the caller''s owner triple (RFC 0048/0074)
-
-        when `installScope: ''tenant''`.
-
-        '
+      summary: List an agent's deployment records
+      description: 'Lists the deployment records, one per `(agentId, version)`, for a manifest agent: the lifecycle `state`,
+        the named `channels`, the canary share, the rollback pointer, and the last-transition provenance. Read-only and content-free
+        of any manifest body or credential (SR-1). Gated on `capabilities.agents.deployment.supported: true`; a host that
+        does not advertise it returns 404. Tenant-scoped to the caller''s owner triple when `installScope: ''tenant''`.'
       operationId: listAgentDeployments
       security:
       - ApiKeyAuth:
@@ -1668,18 +1519,11 @@ paths:
         schema:
           type: string
           pattern: ^(?!roster$|org-chart$).+$
-        description: 'The manifest agentId. MUST NOT be the reserved literals `roster` or
-
-          `org-chart` — those name the sibling collection routes
-
-          (`/v1/agents/roster/{rosterId}`, `/v1/agents/org-chart/{departmentId}`),
-
-          so excluding them here keeps `/v1/agents/{agentId}/deployments`
-
-          unambiguous against them.
-
-          '
+        description: The manifest agentId. MUST NOT be the reserved literals `roster` or `org-chart`, which name the sibling
+          collection routes (`/agents/roster/{rosterId}`, `/agents/org-chart/{departmentId}`), so `/agents/{agentId}/deployments`
+          stays unambiguous.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The agent's deployment records (version-sorted).
@@ -1708,21 +1552,12 @@ paths:
     post:
       tags:
       - agents
-      summary: 'RFC 0082 §E — request a deployment state transition (promote / pause /
-
-        deprecate / rollback / adjust-canary). The host MUST authorize fail-closed
-
-        against the RFC 0049 `deploy:*` scope (absent/unseeded role denies), run any
-
-        configured RFC 0051 approvalGate, and — when the gate carries `requiredEval`
-
-        — verify the referenced RFC 0081 eval run is terminal and `EvalSummary.passed`
-
-        BEFORE emitting `deployment.promoted`. On success returns the updated
-
-        deployment record and emits the matching content-free `deployment.*` event.
-
-        '
+      summary: Request a deployment state transition
+      description: 'Requests a transition: promote, pause, deprecate, rollback, or adjust-canary. The host MUST authorize
+        fail-closed against the `deploy:*` scope (an absent or unseeded role denies), run any configured approvalGate, and,
+        when the gate carries `requiredEval`, verify that the referenced eval run is terminal and `EvalSummary.passed` before
+        emitting `deployment.promoted`. On success it returns the updated deployment record and emits the matching content-free
+        `deployment.*` event.'
       operationId: transitionAgentDeployment
       security:
       - ApiKeyAuth:
@@ -1740,6 +1575,7 @@ paths:
         description: The manifest agentId.
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1757,13 +1593,8 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: 'Validation error, or a transition that the host''s advertised
-
-            `states`/`canary` cannot satisfy, or `no_active_deployment` when a
-
-            referenced channel resolves to no active version.
-
-            '
+          description: A validation error; a transition the host's advertised `states`/`canary` cannot satisfy; or `no_active_deployment`
+            when a referenced channel resolves to no active version.
           content:
             application/json:
               schema:
@@ -1774,13 +1605,8 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthenticated'
         '403':
-          description: 'Fail-closed authorization denial (the principal lacks the required
-
-            `deploy:*` scope — RFC 0049), or `eval_gate_unmet` when a `requiredEval`
-
-            gate''s referenced eval run is not terminal-and-passed (RFC 0081).
-
-            '
+          description: Fail-closed authorization denial (the principal lacks the required `deploy:*` scope), or `eval_gate_unmet`
+            when a `requiredEval` gate's referenced eval run is not terminal and passed.
           content:
             application/json:
               schema:
@@ -1801,19 +1627,11 @@ paths:
     get:
       tags:
       - agents
-      summary: 'RFC 0086 §B — list the standing agent roster (named "digital-twin
-
-        employee" instances + their workflow portfolios) visible to the
-
-        caller. Capability-gated on `capabilities.agents.roster.supported:
-
-        true`; hosts that don''t advertise it return 404. Tenant-scoped per
-
-        RFC 0074 — on an `installScope: ''tenant''` host only the caller''s
-
-        owner-triple entries are returned. Read-only; content-free (SR-1).
-
-        '
+      summary: List the standing agent roster
+      description: 'Lists the standing agent roster visible to the caller: named "digital-twin employee" instances and their
+        workflow portfolios. Gated on `capabilities.agents.roster.supported: true`; a host that does not advertise it returns
+        404. Tenant-scoped: on an `installScope: ''tenant''` host only the caller''s owner-triple entries are returned. Read-only;
+        content-free (SR-1).'
       operationId: listAgentRoster
       security:
       - ApiKeyAuth:
@@ -1847,21 +1665,15 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /agents/roster/{rosterId}:
     get:
       tags:
       - agents
-      summary: 'RFC 0086 §B — return one standing roster entry, or 404 when no such
-
-        entry exists, the host doesn''t advertise `capabilities.agents.roster`,
-
-        or (on an `installScope: ''tenant''` host) the entry is outside the
-
-        caller''s owner triple — a cross-tenant entry 404s identically to
-
-        "not found", never disclosing another tenant''s roster.
-
-        '
+      summary: Read one standing roster entry
+      description: 'Returns one standing roster entry, or 404 when no such entry exists, the host does not advertise `capabilities.agents.roster`,
+        or (on an `installScope: ''tenant''` host) the entry is outside the caller''s owner triple. A cross-tenant entry returns
+        the same 404 as "not found", so another tenant''s roster is never disclosed.'
       operationId: getAgentRosterEntry
       security:
       - ApiKeyAuth:
@@ -1878,6 +1690,7 @@ paths:
           type: string
         description: The standing instance id (a `host:<id>` AgentRef agentId).
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The roster entry.
@@ -1905,17 +1718,10 @@ paths:
     get:
       tags:
       - agents
-      summary: 'RFC 0087 §C — return the caller''s agent org-chart (departments + roles
-
-        + `reportsTo` edges over roster members). Capability-gated on
-
-        `capabilities.agents.orgChart.supported: true`; hosts that don''t
-
-        advertise it return 404. Tenant-scoped per RFC 0074. DESCRIPTIVE only:
-
-        an org edge confers no authority (§B `org-position-no-authority-escalation`).
-
-        '
+      summary: Read the caller's agent org chart
+      description: 'Returns the caller''s agent org chart: departments, roles, and `reportsTo` edges over roster members.
+        Gated on `capabilities.agents.orgChart.supported: true`; a host that does not advertise it returns 404. Tenant-scoped.
+        The chart is descriptive only: an org edge confers no authority (`org-position-no-authority-escalation`).'
       operationId: getAgentOrgChart
       security:
       - ApiKeyAuth:
@@ -1949,21 +1755,15 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /agents/org-chart/{departmentId}:
     get:
       tags:
       - agents
-      summary: 'RFC 0087 §D — one department''s subtree + responsibility roll-up (the
-
-        union of its members'' RFC 0086 portfolios). `?recursive=false` narrows
-
-        the roll-up to direct members without changing the response shape.
-
-        404 when the department is unknown, cross-tenant, or the host doesn''t
-
-        advertise `capabilities.agents.orgChart`. The roll-up grants nothing (§B).
-
-        '
+      summary: Read one department's subtree and responsibility roll-up
+      description: Returns one department's subtree and responsibility roll-up (the union of its members' portfolios). `?recursive=false`
+        narrows the roll-up to direct members without changing the response shape. Returns 404 when the department is unknown
+        or cross-tenant, or the host does not advertise `capabilities.agents.orgChart`. The roll-up grants nothing.
       operationId: getAgentOrgChartDepartment
       security:
       - ApiKeyAuth:
@@ -1978,7 +1778,7 @@ paths:
         required: true
         schema:
           type: string
-        description: The department id to root the subtree + roll-up at.
+        description: The department id to root the subtree and roll-up at.
       - in: query
         name: recursive
         required: false
@@ -1987,6 +1787,7 @@ paths:
           default: true
         description: When `false`, the roll-up scopes to direct members only.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The department subtree + responsibility roll-up.
@@ -2014,23 +1815,11 @@ paths:
     get:
       tags:
       - tools
-      summary: 'RFC 0078 §B — list the portable `ToolDescriptor`s visible to the caller
-
-        across every tool source (node-pack / workflow / mcp / connector /
-
-        host-extension). Capability-gated on
-
-        `capabilities.toolCatalog.supported: true`; hosts that don''t advertise
-
-        it return 404. §F-2 — the projection is authorization-scoped: a
-
-        principal sees only the tools it may invoke, and a second principal MUST
-
-        NOT see another principal''s tools (non-disclosure). Read-only; each
-
-        descriptor is content-free of any credential material (SR-1).
-
-        '
+      summary: List the tools the caller may invoke
+      description: 'Lists the portable `ToolDescriptor`s visible to the caller across every tool source (node-pack, workflow,
+        mcp, connector, host-extension). Gated on `capabilities.toolCatalog.supported: true`; a host that does not advertise
+        it returns 404. The projection is authorization-scoped: a principal sees only the tools it may invoke, and a second
+        principal MUST NOT see another principal''s tools. Read-only; no descriptor carries credential material (SR-1).'
       operationId: listTools
       security:
       - ApiKeyAuth:
@@ -2049,13 +1838,12 @@ paths:
           - standard
           - compact
           default: standard
-        description: 'RFC 0112. `compact` returns the `{ tools: CompactToolDescriptor[] }` projection — heavy descriptor fields
-          omitted and `inputSchema` bounded to the compact structural subset — when the host advertises `capabilities.toolCatalog.compactView:
-          true`. Defaults to `standard`; a host that does not advertise `compactView` treats `view=compact` as any unknown
-          query param and returns the standard view.
-
-          '
+        description: '`compact` returns the `{ tools: CompactToolDescriptor[] }` projection (heavy descriptor fields omitted,
+          `inputSchema` bounded to the compact structural subset) when the host advertises `capabilities.toolCatalog.compactView:
+          true`. Defaults to `standard`. A host that does not advertise `compactView` treats `view=compact` like any unknown
+          query parameter and returns the standard view.'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: 'The caller''s authorized tool catalog (standard array, or the compact `{ tools: [] }` projection when
@@ -2095,15 +1883,10 @@ paths:
     get:
       tags:
       - tools
-      summary: 'RFC 0078 §B — return one `ToolDescriptor` by its stable `toolId`, or 404
-
-        when no such tool exists, the caller isn''t authorized for it (§F-2
-
-        non-disclosure — a cross-principal tool 404s identically to "not
-
-        found"), or the host doesn''t advertise `capabilities.toolCatalog`.
-
-        '
+      summary: Read one tool descriptor
+      description: Returns one `ToolDescriptor` by its stable `toolId`, or 404 when no such tool exists, the caller is not
+        authorized for it, or the host does not advertise `capabilities.toolCatalog`. A tool the caller may not see returns
+        the same 404 as "not found".
       operationId: getTool
       security:
       - ApiKeyAuth:
@@ -2128,12 +1911,11 @@ paths:
           - standard
           - compact
           default: standard
-        description: 'RFC 0112. `compact` returns one `CompactToolDescriptor` (heavy fields omitted; `inputSchema` bounded
-          to the compact structural subset) when the host advertises `capabilities.toolCatalog.compactView: true`. Defaults
-          to `standard`; a host that does not advertise `compactView` treats `view=compact` as any unknown query param.
-
-          '
+        description: '`compact` returns one `CompactToolDescriptor` (heavy fields omitted, `inputSchema` bounded to the compact
+          structural subset) when the host advertises `capabilities.toolCatalog.compactView: true`. Defaults to `standard`.
+          A host that does not advertise `compactView` treats `view=compact` like any unknown query parameter.'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The tool descriptor (standard, or one `CompactToolDescriptor` when `view=compact`).
@@ -2163,23 +1945,12 @@ paths:
     get:
       tags:
       - runs
-      summary: 'RFC 0081 §C — return the `EvalSummary` scorecard for a terminal eval run
-
-        (a run started with `mode: "eval"`): aggregate + per-task scores, cost,
-
-        latency, schema-validity, and redaction-safe safety findings, plus the
-
-        suite provenance and (regression mode) the score delta vs a baseline.
-
-        Content-free of task output / rubric prose / credentials (SR-1; the
-
-        `eval-summary-no-content-leak` invariant). Capability-gated on
-
-        `capabilities.agents.evalSuite.supported: true`; hosts that don''t advertise
-
-        it return 404. 409 when the run is not yet terminal.
-
-        '
+      summary: Read the scorecard of a terminal eval run
+      description: 'Returns the `EvalSummary` scorecard for a terminal eval run (one started with `mode: "eval"`): aggregate
+        and per-task scores, cost, latency, schema validity, redaction-safe safety findings, the suite provenance, and, in
+        regression mode, the score delta against a baseline. It carries no task output, rubric prose, or credentials (SR-1;
+        `eval-summary-no-content-leak`). Gated on `capabilities.agents.evalSuite.supported: true`; a host that does not advertise
+        it returns 404. Returns 409 while the run is not yet terminal.'
       operationId: getEvalSummary
       security:
       - ApiKeyAuth:
@@ -2191,6 +1962,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The eval run's scorecard.
@@ -2206,11 +1978,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '404':
-          description: 'No such run, the run is not an eval run, or the host doesn''t advertise
-
-            `capabilities.agents.evalSuite`.
-
-            '
+          description: No such run, the run is not an eval run, or the host does not advertise `capabilities.agents.evalSuite`.
           content:
             application/json:
               schema:
@@ -2231,17 +1999,10 @@ paths:
     get:
       tags:
       - runs
-      summary: 'RFC 0054 — return a deterministic, replay-aware structured diff of
-
-        two runs (typically a run and its RFC 0011 fork): `divergedAtSeq` +
-
-        ordered `eventDiffs[]` + `stateDiff`. The diff is a pure function of
-
-        the two event logs (see `replay.md` determinism contract). Requires
-
-        `runs:read` on BOTH runs. Hosts that don''t implement it return 404.
-
-        '
+      summary: Diff two runs
+      description: 'Returns a deterministic, replay-aware structured diff of two runs, typically a run and its fork: `divergedAtSeq`,
+        ordered `eventDiffs[]`, and `stateDiff`. The diff is a pure function of the two event logs (see the `replay.md` determinism
+        contract). Requires `runs:read` on both runs. A host that does not implement it returns 404.'
       operationId: diffRun
       security:
       - ApiKeyAuth:
@@ -2259,13 +2020,11 @@ paths:
         schema:
           type: string
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
-          description: 'Structured diff of the two runs. `divergedAtSeq: null` + empty
-
-            `eventDiffs` when the logs are identical.
-
-            '
+          description: 'Structured diff of the two runs. `divergedAtSeq: null` and an empty `eventDiffs` when the logs are
+            identical.'
           content:
             application/json:
               schema:
@@ -2285,13 +2044,8 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthenticated'
         '403':
-          description: 'Caller lacks `runs:read` on `{runId}` and/or on `against`
-
-            (`forbidden`); composes with RFC 0048 cross-workspace
-
+          description: The caller lacks `runs:read` on `{runId}` or on `against` (`forbidden`); composes with cross-workspace
             isolation.
-
-            '
           content:
             application/json:
               schema:
@@ -2300,11 +2054,8 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '404':
-          description: 'Either run doesn''t exist, OR the host doesn''t implement the diff
-
-            endpoint and treats the path as absent.
-
-            '
+          description: Either run does not exist, or the host does not implement the diff endpoint and treats the path as
+            absent.
           content:
             application/json:
               schema:
@@ -2316,12 +2067,9 @@ paths:
     post:
       tags:
       - runs
-      summary: Administratively pause an in-flight run (RFC Track 13).
-      description: 'Operator-driven pause distinct from cancel (terminal) and HITL suspend (workflow-driven).
-
-        Emits a `run.paused` event when the pause takes effect; exit only via `:resume` or `:cancel`.
-
-        '
+      summary: Administratively pause an in-flight run.
+      description: An operator-driven pause, distinct from cancel (terminal) and from a HITL suspend (workflow-driven). Emits
+        a `run.paused` event when the pause takes effect. The run leaves `paused` only through `:resume` or `:cancel`.
       operationId: pauseRun
       security:
       - ApiKeyAuth:
@@ -2334,6 +2082,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         content:
           application/json:
@@ -2349,15 +2098,12 @@ paths:
                   - immediate
                   - drain-current-node
                   default: drain-current-node
-                  description: '`immediate` snapshots between events; `drain-current-node` lets the running node
-
-                    reach a terminal before transitioning to `paused`.
-
-                    '
+                  description: '`immediate` snapshots between events; `drain-current-node` lets the running node reach a terminal
+                    state before the run transitions to `paused`.'
               additionalProperties: false
       responses:
         '202':
-          description: Pause requested; transition emits `run.paused` when complete.
+          description: Pause requested; the transition emits `run.paused` when complete.
           content:
             application/json:
               schema:
@@ -2397,10 +2143,8 @@ paths:
     post:
       tags:
       - runs
-      summary: Resume a paused run (RFC Track 13).
-      description: 'Reverses a prior `:pause`. Run transitions from `paused` to `running` and emits `run.resumed`.
-
-        '
+      summary: Resume a paused run.
+      description: 'Reverses a prior `:pause`: the run transitions from `paused` to `running` and emits `run.resumed`.'
       operationId: resumeRun
       security:
       - ApiKeyAuth:
@@ -2413,6 +2157,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         content:
           application/json:
@@ -2483,6 +2228,7 @@ paths:
           minLength: 1
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2528,7 +2274,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '409':
-          description: Concurrent resolve — only one wins.
+          description: Concurrent resolve; only one wins.
           content:
             application/json:
               schema:
@@ -2537,7 +2283,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '422':
-          description: Run was cancelled while interrupt was pending.
+          description: The run was cancelled while the interrupt was pending.
           content:
             application/json:
               schema:
@@ -2581,6 +2327,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     post:
       tags:
       - hitl
@@ -2590,6 +2337,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2642,11 +2390,12 @@ paths:
           type: string
           minLength: 1
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
-          description: Artifact payload. Under `application/json` the shape is implementation-defined; under `application/a2a+json`
-            (RFC 0205 §A, negotiated by `Accept`; a host SHOULD offer it) it is an A2A `Artifact` whose `artifactId` equals
-            the path segment, and a `url` Part in it MUST NOT resolve beyond the caller's `artifacts:read` authorization.
+          description: Artifact payload. Under `application/json` the shape is implementation-defined. Under `application/a2a+json`
+            (negotiated by `Accept`; a host SHOULD offer it) it is an A2A `Artifact` whose `artifactId` equals the path segment,
+            and a `url` Part in it MUST NOT resolve beyond the caller's `artifacts:read` authorization.
           content:
             application/json:
               schema:
@@ -2680,6 +2429,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2700,11 +2450,9 @@ paths:
                   description: Event types to subscribe to (see `run-event.schema.json` enum).
                 secret:
                   type: string
-                  description: 'Server signs payloads with this secret using HMAC-SHA256. REQUIRED in the Standard Webhooks
-                    form `whsec_<base64>` (24–64 decoded bytes) when `signatureAlgorithms` lists `standard-webhooks-1` (RFC
-                    0201 §B.6); never echoed in any response.
-
-                    '
+                  description: The host signs payloads with this secret using HMAC-SHA256. REQUIRED in the Standard Webhooks
+                    form `whsec_<base64>` (24–64 decoded bytes) when `signatureAlgorithms` lists `standard-webhooks-1`. Never
+                    echoed in any response. When omitted, the host generates one and returns it once in the `201` (RFC 0221).
                 tags:
                   type: array
                   items:
@@ -2721,13 +2469,14 @@ paths:
                     enum:
                     - v1
                     - standard-webhooks-1
-                  description: 'RFC 0201 §B — the per-subscription opt-in. Absent means `["v1"]`, today''s behaviour byte
-                    for byte. When present it MUST contain `v1`, MUST NOT repeat a value, and every value MUST be listed in
-                    the host''s `webhooks.signatureAlgorithms`; otherwise `400 validation_error`. Listing `standard-webhooks-1`
-                    opts the subscription into the Standard Webhooks 1.0.0 companion scheme, which runs endpoint verification
-                    before the `201` (`400 webhook_endpoint_unverified` when the endpoint does not echo the challenge).
+                  description: 'The per-subscription signature opt-in. Absent means `["v1"]`. When present it MUST contain
+                    `v1`, MUST NOT repeat a value, and every value MUST be listed in the host''s `webhooks.signatureAlgorithms`;
+                    otherwise `400 validation_error`.
 
-                    '
+
+                    Listing `standard-webhooks-1` opts the subscription into the Standard Webhooks 1.0.0 companion scheme,
+                    which runs endpoint verification before the `201` (`400 webhook_endpoint_unverified` when the endpoint
+                    does not echo the challenge).'
               additionalProperties: false
       responses:
         '201':
@@ -2745,17 +2494,19 @@ paths:
                     type: array
                     items:
                       type: string
-                    description: RFC 0201 §B.7 — the list the dispatcher will apply; present whenever the request carried
-                      `signatureAlgorithms`.
+                    description: The list the dispatcher will apply; present whenever the request carried `signatureAlgorithms`.
+                  secret:
+                    type: string
+                    minLength: 1
+                    description: 'Present only when the request omitted `secret`: the secret the host generated, returned
+                      this once. A supplied secret is never echoed.'
           headers:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: '`validation_error` (malformed body, or an invalid `signatureAlgorithms` / `secret` opt-in, RFC 0201
-            §B), `webhook_url_rejected` (egress), or `webhook_endpoint_unverified` (RFC 0201 §D — an opted-in endpoint did
-            not echo the verification challenge; no subscription is persisted).
-
-            '
+          description: '`validation_error` (malformed body, or an invalid `signatureAlgorithms` or `secret` opt-in), `webhook_url_rejected`
+            (egress), or `webhook_endpoint_unverified` (an opted-in endpoint did not echo the verification challenge; no subscription
+            is persisted).'
           content:
             application/json:
               schema:
@@ -2786,12 +2537,10 @@ paths:
         required: true
         schema:
           $ref: ../../schemas/v2/ids.schema.json#/$defs/subscriptionId
-        description: 'Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5, RFC 0187 §A.1), one path
-
-          segment: `~`-projected (RFC 0184) or percent-encoded.
-
-          '
+        description: 'Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5), carried as one path segment: `~`-projected or
+          percent-encoded.'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '204':
           description: Unregistered.
@@ -2809,13 +2558,15 @@ paths:
       tags:
       - webhooks
       operationId: rotateWebhookSecret
-      summary: Rotate a Standard Webhooks subscription's secret with an overlap (RFC 0201 §E)
-      description: 'Gated on `webhooks.secretRotation`: a host that does not advertise it MUST answer `404 not_found`. Only
-        for a subscription that opted into `standard-webhooks-1`; any other subscription gets `400 validation_error` (its
-        single `v1` signature cannot overlap). Tenant checks are exactly those of `unregisterWebhook`: `403 id_tenant_mismatch`
+      summary: Rotate a Standard Webhooks subscription's secret with an overlap
+      description: 'Rotates the secret of a subscription that opted into `standard-webhooks-1`. Gated on `webhooks.secretRotation`:
+        a host that does not advertise it MUST answer `404 not_found`. Any other subscription gets `400 validation_error`,
+        because its single `v1` signature cannot overlap. Tenant checks are those of `unregisterWebhook`: `403 id_tenant_mismatch`
         when the id''s tenant segment is not the caller''s, checked before the lookup (`identity.md` §5); `404` when unknown.
+
+
         For `overlapSeconds` after `rotatedAt`, `webhook-signature` carries one entry under the new secret and one under the
-        previous one, and `OpenWOP-Signature` stays on the previous secret; at `previousSecretExpiresAt` only the new secret
+        previous one, and `OpenWOP-Signature` stays on the previous secret. At `previousSecretExpiresAt` only the new secret
         signs. A second rotation inside an overlap retires the oldest secret immediately. Rotation does not re-verify the
         endpoint. The response carries no secret.'
       parameters:
@@ -2824,10 +2575,11 @@ paths:
         required: true
         schema:
           $ref: ../../schemas/v2/ids.schema.json#/$defs/subscriptionId
-        description: 'Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5, RFC 0187 §A.1), one path segment: `~`-projected
-          (RFC 0184) or percent-encoded.'
+        description: 'Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5), carried as one path segment: `~`-projected or
+          percent-encoded.'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2841,7 +2593,7 @@ paths:
                 secret:
                   type: string
                   pattern: ^whsec_[A-Za-z0-9+/]+={0,2}$
-                  description: The new secret, `whsec_<base64>` decoding to 24–64 bytes (RFC 0201 §B.6).
+                  description: 'The new secret: `whsec_<base64>`, decoding to 24–64 bytes.'
       responses:
         '200':
           description: Rotated. No secret is returned.
@@ -2884,25 +2636,11 @@ paths:
       tags:
       - audit
       summary: Verify the audit-log hash chain over [fromSeq, toSeq].
-      description: 'Per `spec/v1/auth-profiles.md` §`openwop-audit-log-integrity` §4. The
-
-        verifier re-walks audit-log entries in the requested range,
-
-        re-computes each entry''s `prevHash` from the canonical RFC 8785 JCS
-
-        serialization of the prior entry, verifies signed checkpoints
-
-        against the host''s advertised `auditLogIntegrity.checkpointPublicKey`,
-
-        and returns `chainValid` + an enumeration of any anomalies.
-
-        Hosts MUST require the `audit:read` scope. Hosts that do NOT
-
-        advertise the `openwop-audit-log-integrity` profile MAY omit this
-
-        endpoint entirely (clients SHOULD pre-flight via `/.well-known/openwop`).
-
-        '
+      description: Re-walks the audit-log entries in the requested range, recomputes each entry's `prevHash` from the canonical
+        RFC 8785 JCS serialization of the prior entry, verifies signed checkpoints against the host's advertised `auditLogIntegrity.checkpointPublicKey`,
+        and returns `chainValid` with any anomalies. Hosts MUST require the `audit:read` scope. Hosts that do not advertise
+        the `openwop-audit-log-integrity` profile MAY omit this endpoint entirely; clients SHOULD check `/.well-known/openwop`
+        first. See `spec/v1/auth-profiles.md` §`openwop-audit-log-integrity` §4.
       operationId: verifyAuditLog
       security:
       - ApiKeyAuth:
@@ -2927,6 +2665,7 @@ paths:
           minimum: 0
         description: Last audit-log sequence to include (inclusive). MUST be >= fromSeq.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Verification result.
@@ -2980,13 +2719,8 @@ paths:
         name: tag
         schema:
           type: string
-        description: 'Filter to templates whose `tags[]` contains this exact tag.
-
-          Hosts MAY accept the parameter multiple times; the semantic
-
-          when repeated is AND (every named tag must be present).
-
-          '
+        description: Filter to templates whose `tags[]` contains this exact tag. Hosts MAY accept the parameter more than
+          once; repeated values combine with AND (every named tag must be present).
       - in: query
         name: modelClass
         schema:
@@ -3015,6 +2749,7 @@ paths:
           default: 50
         description: Maximum entries per page.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Paginated list of templates.
@@ -3040,8 +2775,8 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '501':
-          description: Host does not advertise capabilities.prompts.endpointsSupported. (RFC 0028 §A — supported gates Phase
-            A node-execution composition; endpointsSupported gates this REST surface independently.)
+          description: Host does not advertise `capabilities.prompts.endpointsSupported`. (`supported` gates node-execution
+            composition; `endpointsSupported` gates this REST surface independently.)
           content:
             application/json:
               schema:
@@ -3064,6 +2799,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -3096,7 +2832,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '501':
-          description: Host does not advertise capabilities.prompts.mutableLibrary.
+          description: Host does not advertise `capabilities.prompts.mutableLibrary`.
           content:
             application/json:
               schema:
@@ -3112,7 +2848,7 @@ paths:
       schema:
         type: string
         pattern: ^[a-z0-9][a-z0-9._-]{0,127}$
-      description: PromptTemplate.templateId per RFC 0027.
+      description: '`PromptTemplate.templateId`.'
     - in: query
       name: version
       schema:
@@ -3124,13 +2860,8 @@ paths:
       schema:
         type: string
         pattern: ^[a-z0-9][a-z0-9._-]{0,127}$
-      description: 'Disambiguate when multiple installed packs ship the same
-
-        templateId. Hosts MUST return `prompt_ref_ambiguous` if
-
-        ambiguous and libraryId is omitted.
-
-        '
+      description: Disambiguates when several installed packs ship the same templateId. Hosts MUST return `prompt_ref_ambiguous`
+        when the reference is ambiguous and libraryId is omitted.
     get:
       tags:
       - prompts
@@ -3167,7 +2898,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: '`prompt_ref_ambiguous` when libraryId disambiguation is required.'
+          description: '`prompt_ref_ambiguous` when `libraryId` disambiguation is required.'
           content:
             application/json:
               schema:
@@ -3189,8 +2920,8 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '501':
-          description: Host does not advertise capabilities.prompts.endpointsSupported. (RFC 0028 §A — supported gates Phase
-            A node-execution composition; endpointsSupported gates this REST surface independently.)
+          description: Host does not advertise `capabilities.prompts.endpointsSupported`. (`supported` gates node-execution
+            composition; `endpointsSupported` gates this REST surface independently.)
           content:
             application/json:
               schema:
@@ -3200,6 +2931,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     put:
       tags:
       - prompts
@@ -3215,6 +2947,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -3263,7 +2996,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '501':
-          description: Host does not advertise capabilities.prompts.mutableLibrary.
+          description: Host does not advertise `capabilities.prompts.mutableLibrary`.
           content:
             application/json:
               schema:
@@ -3310,7 +3043,7 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '501':
-          description: Host does not advertise capabilities.prompts.mutableLibrary.
+          description: Host does not advertise `capabilities.prompts.mutableLibrary`.
           content:
             application/json:
               schema:
@@ -3320,30 +3053,17 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /prompts:render:
     post:
       tags:
       - prompts
       summary: Render a prompt template with supplied variable bindings.
-      description: 'Returns the composed body + sha256 hash + per-variable hashes.
-
-        The response''s `hash` MUST equal the `hash` that a matching
-
-        `prompt.composed` event would carry at dispatch time for the
-
-        same `(ref, variables, contentTrust)` inputs (RFC 0028 §A
-
-        deterministic-render invariant; RFC 0027 §F replay invariant).
-
-        Does NOT dispatch an LLM call. Secret-source variable values
-
-        MUST be supplied as `[REDACTED:<credentialRef>]` markers; the
-
-        host resolves the plaintext internally and never echoes it in
-
-        the `composed` response field per SR-1.
-
-        '
+      description: Returns the composed body, its sha256 hash, and per-variable hashes. Does not dispatch an LLM call. The
+        response's `hash` MUST equal the `hash` a matching `prompt.composed` event would carry at dispatch time for the same
+        `(ref, variables, contentTrust)` inputs, so rendering is deterministic and replay-safe. Secret-source variable values
+        MUST be supplied as `[REDACTED:<credentialRef>]` markers; the host resolves the plaintext internally and never echoes
+        it in the `composed` response field (SR-1).
       operationId: renderPromptTemplate
       security:
       - ApiKeyAuth:
@@ -3366,24 +3086,15 @@ paths:
                   $ref: ../../schemas/v2/prompt-ref.schema.json
                 variables:
                   type: object
-                  description: 'Variable bindings keyed by `PromptVariable.name`.
-
-                    Secret-source bindings carry `[REDACTED:<credentialRef>]`
-
+                  description: Variable bindings keyed by `PromptVariable.name`. Secret-source bindings carry `[REDACTED:<credentialRef>]`
                     markers; the host resolves the real value internally.
-
-                    '
                   additionalProperties: true
                 contentTrust:
                   type: string
                   enum:
                   - trusted
                   - untrusted
-                  description: 'Aggregate trust marker for the supplied bindings,
-
-                    propagated through composition per RFC 0027 §E.
-
-                    '
+                  description: Aggregate trust marker for the supplied bindings, propagated through composition.
       responses:
         '200':
           description: Composed result.
@@ -3420,13 +3131,8 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '400':
-          description: '`prompt_variable_unresolved` (required variable missing),
-
-            `prompt_variable_type_mismatch` (bound type vs. declared type),
-
-            or `prompt_ref_invalid` (malformed PromptRef).
-
-            '
+          description: '`prompt_variable_unresolved` (a required variable is missing), `prompt_variable_type_mismatch` (bound
+            type differs from declared type), or `prompt_ref_invalid` (malformed PromptRef).'
           content:
             application/json:
               schema:
@@ -3448,8 +3154,8 @@ paths:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
         '501':
-          description: Host does not advertise capabilities.prompts.endpointsSupported. (RFC 0028 §A — supported gates Phase
-            A node-execution composition; endpointsSupported gates this REST surface independently.)
+          description: Host does not advertise `capabilities.prompts.endpointsSupported`. (`supported` gates node-execution
+            composition; `endpointsSupported` gates this REST surface independently.)
           content:
             application/json:
               schema:
@@ -3459,14 +3165,15 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /host/effect-seams:
     get:
       tags:
       - host
       operationId: getEffectSeamManifest
-      summary: The host-declared effect-seam manifest (RFC 0173 §C)
-      description: Every outbound effect seam replay suppression covers. A seam omitted here is invisible to the suite; the
-        RFC 0140 R5 audit is the control.
+      summary: Read the host's effect-seam manifest
+      description: Lists every outbound effect seam that replay suppression covers. A seam omitted here is invisible to the
+        conformance suite; an audit of the host's seams is the control.
       responses:
         '200':
           description: The manifest.
@@ -3481,6 +3188,7 @@ paths:
           $ref: '#/components/responses/Unauthenticated'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3495,9 +3203,8 @@ paths:
       tags:
       - runs
       operationId: getRunCompensation
-      summary: Compensation plan and attempts for a run (RFC 0173 §C.1)
-      description: The read projection that makes compensation a core obligation with a deployed-wire witness (RFC 0151 G9
-        / RFC 0173 §B).
+      summary: Read a run's compensation plan and attempts
+      description: The run's compensation plan and every attempt, as a read projection.
       responses:
         '200':
           description: The projection.
@@ -3512,6 +3219,7 @@ paths:
           $ref: '#/components/responses/NotFound'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3526,8 +3234,8 @@ paths:
       tags:
       - runs
       operationId: getRunEffects
-      summary: The Layer-2 effect ledger for a run (RFC 0173 §C.2)
-      description: Business-identity keyed effect records; the witness for the Layer-2 effect-identity obligation.
+      summary: Read a run's Layer-2 effect ledger
+      description: Effect records keyed by business identity; the witness for the Layer-2 effect-identity obligation.
       responses:
         '200':
           description: The ledger projection.
@@ -3542,6 +3250,7 @@ paths:
           $ref: '#/components/responses/NotFound'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3554,20 +3263,22 @@ paths:
       tags:
       - webhooks
       operationId: listWebhookDeadLetters
-      summary: A subscription's dead-lettered deliveries (RFC 0188 §A.1)
-      description: 'The read that makes `webhooks.md` §Durability observable. A delivery whose retries are exhausted, or a
-        `payload_unprojectable` delivery dead-lettered on its first attempt, appears here until `retentionDays` elapse. Gated
-        on the `webhooks.deadLetter` facet: a host that does not advertise it answers `404 not_found`. **Content-free (RFC
-        0188 §B.1):** the record NAMES a delivery and never carries the delivered bytes, the request headers, or the subscription
-        secret — a dead-letter read is a diagnostic surface, not a payload-replay surface.'
+      summary: List a subscription's dead-lettered deliveries
+      description: 'Lists deliveries that were dead-lettered, making `webhooks.md` §Durability observable. A delivery whose
+        retries are exhausted, or a `payload_unprojectable` delivery dead-lettered on its first attempt, appears here until
+        `retentionDays` elapse. Gated on the `webhooks.deadLetter` facet: a host that does not advertise it answers `404 not_found`.
+
+
+        The record is content-free: it names a delivery and never carries the delivered bytes, the request headers, or the
+        subscription secret.'
       parameters:
       - name: webhookId
         in: path
         required: true
         schema:
           $ref: ../../schemas/v2/ids.schema.json#/$defs/subscriptionId
-        description: The subscription, tenant-bound (`identity.md` §5, RFC 0187 §A.1) and carried as ONE path segment — `~`-projected
-          per RFC 0184, or percent-encoded.
+        description: 'The subscription, tenant-bound (`identity.md` §5) and carried as one path segment: `~`-projected or
+          percent-encoded.'
       - name: limit
         in: query
         required: false
@@ -3585,6 +3296,7 @@ paths:
         description: Opaque cursor from a previous page's `nextCursor`. A cursor minted for another subscription MUST be refused
           `400 validation_error`.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: One page of dead-lettered deliveries, newest first.
@@ -3615,12 +3327,12 @@ paths:
       tags:
       - host
       operationId: streamHostEvents
-      summary: Host-scoped events (heartbeat.*) as SSE (RFC 0171 §E.1)
-      description: The documented default hostEvents address; a host MAY declare another under `heartbeat.deliveryChannel`.
-        Content-free of run data.
+      summary: Stream host-scoped events (`heartbeat.*`) as SSE
+      description: The default `hostEvents` address; a host MAY declare another under `heartbeat.deliveryChannel`. Carries
+        no run data.
       responses:
         '200':
-          description: text/event-stream of hostEvents messages.
+          description: '`text/event-stream` of `hostEvents` messages.'
           content:
             text/event-stream:
               schema:
@@ -3632,6 +3344,7 @@ paths:
           $ref: '#/components/responses/Unauthenticated'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3645,28 +3358,14 @@ components:
       type: http
       scheme: bearer
       bearerFormat: API key
-      description: 'openwop API key. Format implementation-defined; reference impl uses `hk_`/`hk_test_` prefixes.
-
-        Each key carries one or more scopes from the canonical vocabulary
-
-        (`manifest:read`, `runs:create`, `runs:read`, `runs:cancel`,
-
-        `artifacts:read`, `webhooks:manage`, `approvals:respond`, `audit:read`).
-
-        See `auth.md`.
-
-        '
+      description: OpenWOP API key. The format is implementation-defined; the reference implementation uses `hk_`/`hk_test_`
+        prefixes. Each key carries one or more scopes from the canonical vocabulary (`manifest:read`, `runs:create`, `runs:read`,
+        `runs:cancel`, `artifacts:read`, `webhooks:manage`, `approvals:respond`, `audit:read`). Scope matching is in `spec/v2/core/identity.md`
+        §2.1.
     OAuth2:
       type: oauth2
-      description: 'RFC 0200 §F. OAuth 2.0 lanes — v1 `openwop-auth-oauth2-client-credentials`,
-
-        v2 `auth.lanes[].lane: "oauth2"`. Discovery is RFC 9728 Protected Resource
-
-        Metadata at the path-inserted well-known URI (`identity.md` §2.5).
-
-        Placeholder URLs.
-
-        '
+      description: 'The OAuth 2.0 lane (`auth.lanes[].lane: "oauth2"`). Discovery is RFC 9728 Protected Resource Metadata
+        at the path-inserted well-known URI (`identity.md` §2.5). The URLs are placeholders.'
       flows:
         clientCredentials:
           tokenUrl: https://issuer.example/oauth2/token
@@ -3718,26 +3417,14 @@ components:
     OpenIdConnect:
       type: openIdConnect
       openIdConnectUrl: https://issuer.example/.well-known/openid-configuration
-      description: 'RFC 0200 §F. v1 `openwop-auth-oidc-user-bearer` / v2 `auth.lanes[].lane: "oidc"`.
-
-        An ID token MAY be the bearer only when its `aud` equals the host''s configured
-
-        audience (`identity.md` §2.1); any other `aud` is `audience_mismatch`.
-
-        Placeholder URL.
-
-        '
+      description: 'The OpenID Connect lane (`auth.lanes[].lane: "oidc"`). An ID token MAY be the bearer only when its `aud`
+        equals the host''s configured audience (`identity.md` §2.1); any other `aud` is `audience_mismatch`. The URL is a
+        placeholder.'
     MutualTLS:
       type: mutualTLS
-      description: 'RFC 0200 §F. v1 `openwop-auth-mtls` / v2 `auth.lanes[].lane: "mtls"`. In OpenWOP
-
-        mTLS is required *in addition to* a bearer, never instead of one, so it appears
-
-        in no canonical requirement below: a host that requires it adds `MutualTLS: []`
-
-        inside each requirement object (AND).
-
-        '
+      description: 'The mTLS lane (`auth.lanes[].lane: "mtls"`). mTLS is required *in addition to* a bearer, never instead
+        of one, so it appears in no canonical requirement below. A host that requires it adds `MutualTLS: []` inside each
+        requirement object (AND).'
   parameters:
     WorkflowId:
       in: path
@@ -3751,11 +3438,8 @@ components:
       required: true
       schema:
         $ref: ../../schemas/v2/ids.schema.json#/$defs/runId
-      description: 'Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5). The `/` is part of the
-
-        identifier and MUST be percent-encoded as `%2F` in the path segment.
-
-        '
+      description: Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5). The `/` is part of the identifier and MUST be percent-encoded
+        as `%2F` in the path segment.
     IdempotencyKey:
       in: header
       name: Idempotency-Key
@@ -3763,15 +3447,8 @@ components:
       schema:
         type: string
         maxLength: 255
-      description: 'Per-mutation idempotency token (see `idempotency.md` Layer 1).
-
-        Server caches `(tenantId, endpoint, key)` → response for ≥24h.
-
-        Duplicate requests return the cached response with header
-
-        `OpenWOP-Idempotent-Replay: true`.
-
-        '
+      description: 'Per-mutation idempotency token (`idempotency.md` Layer 1). The server caches `(tenantId, endpoint, key)`
+        → response for ≥24h. A duplicate request returns the cached response with `OpenWOP-Idempotent-Replay: true`.'
     OpenWOPVersion:
       name: OpenWOP-Version
       in: header
@@ -3779,14 +3456,23 @@ components:
       schema:
         type: string
         pattern: ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
-      description: RFC 0172 §A.3 — selects a listed major.minor; absent ⇒ the host's `preferredVersion`; unlisted ⇒ 406 protocol_version_unsupported.
+      description: Selects one of the host's listed major.minor versions. Absent, `/.well-known/openwop` uses `preferredVersion`
+        and every other unversioned path is v2; an unlisted value is 406 protocol_version_unsupported.
+    OpenWOPClientVersion:
+      name: OpenWOP-Client-Version
+      in: header
+      required: false
+      schema:
+        type: string
+      description: The protocol version the client implements (versioning.md §1.5). Compared with `minClientVersion` on major.minor.
+        A malformed value is treated as absent and MUST NOT produce a 400. Never selects a contract.
   responses:
     Unauthenticated:
       description: Missing or invalid credential.
       headers:
         WWW-Authenticate:
-          description: RFC 0200 §B — `Bearer` challenge; `resource_metadata` and `error="invalid_token"` on a host with an
-            oauth2/oidc lane. Never on a non-disclosure 404.
+          description: A `Bearer` challenge. On a host with an oauth2 or oidc lane it carries `resource_metadata` and `error="invalid_token"`.
+            Never sent on a non-disclosure 404.
           schema:
             type: string
       content:
@@ -3797,8 +3483,8 @@ components:
       description: Credential valid but lacks required scope or fails resource binding.
       headers:
         WWW-Authenticate:
-          description: RFC 0200 §B — `error="insufficient_scope"` with every required `scope` on a scope refusal; absent on
-            a resource-binding 403.
+          description: On a scope refusal, `error="insufficient_scope"` with every required `scope`. Absent on a resource-binding
+            403.
           schema:
             type: string
       content:
@@ -3836,15 +3522,13 @@ components:
       $ref: ../../schemas/v2/run-snapshot.schema.json
     RunClaimConflict:
       $ref: ../../schemas/v2/error-envelope.schema.json
-      description: RFC 0171 §B.1 — the former one-member enum `RunClaimConflict` is the generated error envelope (`error`
-        carries the code).
+      description: '`RunClaimConflict` is the canonical error envelope; `error` carries the code.'
     UnsupportedStreamMode:
       $ref: ../../schemas/v2/error-envelope.schema.json
-      description: RFC 0171 §B.1 — the former one-member enum `UnsupportedStreamMode` is the generated error envelope (`error`
-        carries the code).
+      description: '`UnsupportedStreamMode` is the canonical error envelope; `error` carries the code.'
   headers:
     OpenWOPVersion:
       schema:
         type: string
-      description: RFC 0172 §A.4 — the contract that produced this response; MUST equal the one used.
+      description: The contract that produced this response. It MUST equal the one used.
       required: true