docs(protocol): retire runtime-capabilities page — it taught the removed ObjectStackCapabilities schema (#4781) (#4816)

`content/docs/protocol/kernel/runtime-capabilities.mdx` documented
`ObjectStackCapabilities` (data/ui/system subsystem descriptors) end to end,
including two full `const capabilities: ObjectStackCapabilities = {...}`
examples and a `hasCapability()` helper. That schema was removed in #3605:
`import type { ObjectStackCapabilities } from '@objectstack/spec'` is TS2305,
and none of the tabled keys (`queryDistinct`, `queryHaving`, `queryJoins`,
`geoSpatial`, …) exist in any live schema. The page named "AI Agents:
Understanding platform constraints for code generation" as an audience, so it
was teaching a non-existent capability-negotiation surface to code generators.

Delete the page. The live mechanisms are the REST discovery endpoint and the
driver-side `DriverCapabilities` (post-#4634).

The page's trailing "Discovery Endpoint" section was NOT accurate either and is
deliberately not moved verbatim. Checked against the implementation:

  - `ObjectStackProtocolImplementation.getDiscovery()`
    (packages/metadata-protocol/src/protocol.ts) returns
    `{ version, apiName, routes, services, capabilities }` — no `name`, no
    `environment`, no `locale`. The page showed all three on
    `GET /api/v1/discovery`; those fields belong to the *dispatcher*-served
    `/.well-known/objectstack` payload (packages/runtime/src/http-dispatcher.ts
    `getDiscoveryInfo`), which `content/docs/api/index.mdx` already documents
    correctly and separately.
  - The page's sample carried `routes.graphql: "/graphql"`. `ApiRoutesSchema`
    (packages/spec/src/api/discovery.zod.ts) has no `graphql` key and
    `serviceToRouteKey` never maps one — flatly wrong.
  - `version: "1.0.0"` — the REST handler overrides it with
    `config.api.version` (`v1`).

Folded into content/docs/api/index.mdx only the parts that verify:

  - `GET /api/v1` and `GET /api/v1/discovery` are one handler registered at two
    paths (`registerDiscoveryEndpoints`, packages/rest/src/rest-server.ts), and
    the dispatcher cedes `<basePath>/discovery` to REST when mounted
    (ADR-0076 D11) — it owns the route only in REST-less compositions.
  - The `capabilities` map and `transactionalBatch` (#3298 / ADR-0034): true
    iff `POST {basePath}/batch` is mounted AND the engine can honour a
    transaction (protocol derives it from `engine.transaction`, rest-server
    ANDs it with `api.enableBatch`).

Also: meta.json nav entry removed; the two inbound links (automation/index.mdx,
kernel/index.mdx) repointed; scripts/role-word-baseline.json ratcheted down for
the removed file (check-role-word fails on a vanished baselined file).

Docs-only, releases nothing — empty changeset.


Claude-Session: https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ

Co-authored-by: Claude <noreply@anthropic.com>

Author: xuyushun441-sys

.changeset/retire-runtime-capabilities-doc-page.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(protocol): retire `protocol/kernel/runtime-capabilities` — the page taught `ObjectStackCapabilities`, a schema removed in #3605. Docs-only; releases nothing.

content/docs/api/index.mdx

@@ -98,9 +98,14 @@ Schema reference: [API](/docs/references/api)
 
 The discovery endpoint is the entry point for all clients. It returns the API version, available routes, service capabilities, and per-service status.
 
-### `GET /api/v1`
+### `GET /api/v1` (and `GET /api/v1/discovery`)
 
-Returns the full discovery manifest.
+Returns the full discovery manifest. `@objectstack/rest` registers **one handler at both
+paths** — the API base path and `<basePath>/discovery` — so the two are the same document,
+not a redirect and not two shapes. In a REST-less composition the runtime dispatcher
+registers `<basePath>/discovery` as the fallback owner instead, and then serves its own
+`/.well-known/objectstack` payload there (see below); when `@objectstack/rest` is mounted
+the dispatcher cedes the route to it, so a single owner answers it (ADR-0076 D11).
 
 **Response**:
 ```json
@@ -125,7 +130,8 @@ Returns the full discovery manifest.
   "capabilities": {
     "cron": { "enabled": false },
     "automation": { "enabled": false },
-    "search": { "enabled": false }
+    "search": { "enabled": false },
+    "transactionalBatch": { "enabled": true, "description": "Atomic cross-object batch endpoint (POST {basePath}/batch)…" }
   }
 }
 ```
@@ -134,6 +140,15 @@ Disabled/uninstalled route keys (e.g. `auth`, `analytics`, `workflow`) are omitt
 
 `metadata` is reported from whatever implementation fills its slot, so the sample's `available` is the `MetadataPlugin` case (a persisted `sys_metadata` registry). A stack running the kernel's in-memory fallback instead reports `status: "degraded"` with a `message` naming what is missing and what to install. `handlerReady` is `true` either way: `/api/v1/meta` is served by the protocol, so the route is mounted whichever registry sits behind it.
 
+`capabilities` is a flat map of platform feature flags, one entry per well-known
+capability (`comments`, `automation`, `cron`, `search`, `export`, `chunkedUpload`,
+`transactionalBatch`), each derived from what is actually registered — never hardcoded.
+`transactionalBatch` (#3298, ADR-0034) is the one worth negotiating at connect time: it is
+`true` **iff** the atomic cross-object batch route (`POST {basePath}/batch`) is mounted
+*and* the runtime engine can honour a transaction, so a client can decide once whether to
+send an atomic batch or fall back to client-side sequencing, instead of probing for
+`404`/`405`/`501`. See [Data API → batch](/docs/api/data-api).
+
 ### `GET /.well-known/objectstack`
 
 Served by the runtime dispatcher (`@objectstack/runtime`), not `@objectstack/rest` — its body is wrapped as `{ "data": { ... } }` and includes fields (`name`, `environment`, `features`, `locale`) that the `@objectstack/rest`-served `/api/v1` response above does not. The client SDK's `connect()` tries `/api/v1/discovery` first and falls back to this endpoint, unwrapping either `body.data` or the bare `body`.

content/docs/automation/index.mdx

@@ -52,6 +52,6 @@ Rule of thumb: model *state* with workflows, model *steps* with flows, use hooks
 
 ## Related
 
-- **Spec:** [State Machine (Lifecycle)](/docs/protocol/objectql/state-machine), [Runtime Capabilities](/docs/protocol/kernel/runtime-capabilities)
+- **Spec:** [State Machine (Lifecycle)](/docs/protocol/objectql/state-machine), [HTTP API](/docs/protocol/kernel/http-protocol)
 - **Schema reference:** [Automation](/docs/references/automation)
 - **Neighbors:** validation rules that block bad data live in [Data Modeling](/docs/data-modeling/validation); who may trigger an automation is governed by [Permissions & Identity](/docs/permissions); the services hooks call (email, queue, storage…) are documented in [Kernel & Services](/docs/kernel/runtime-services).

content/docs/kernel/index.mdx

@@ -40,6 +40,6 @@ The kernel is ObjectStack's runtime: it loads your metadata artifact, hosts plug
 
 ## Related
 
-- **Spec:** [System Lifecycle](/docs/protocol/kernel/lifecycle), [Runtime Capabilities](/docs/protocol/kernel/runtime-capabilities), [Metadata Service](/docs/protocol/kernel/metadata-service)
+- **Spec:** [System Lifecycle](/docs/protocol/kernel/lifecycle), [Metadata Service](/docs/protocol/kernel/metadata-service)
 - **Schema reference:** [Kernel](/docs/references/kernel), [System](/docs/references/system), [Contracts](/docs/references/contracts)
 - **Neighbors:** building and packaging plugins is covered in [Plugins & Packages](/docs/plugins); running the kernel in production is covered in [Deployment & Operations](/docs/deployment).

content/docs/protocol/kernel/meta.json

@@ -3,7 +3,6 @@
   "pages": [
     "index",
     "lifecycle",
-    "runtime-capabilities",
     "http-protocol",
     "realtime-protocol",
     "error-handling",