docs(api): a developer page for declarative apis: endpoints (ADR-0121)

[os-elon]

Fixes#10215

api is an authorable metadata kind (ApiEndpointSchema, ADR-0121), live from protocol
17, and the only hand-written page that covered it was the normative implementer text in
protocol/kernel/http-protocol.mdx. The page a developer actually clicks —
api/plugin-endpoints.mdx — is a catalog of built-in plugin routes with nothing about
authoring, so the naming collision sent the reader to the wrong page. That mattered more
than usual here: authRequired: false is, in ADR-0121's own words, an anonymous,
internet-reachable execution entry point, and it was undocumented outside the protocol
reference.

What this adds

New content/docs/api/declarative-endpoints.mdx, developer-facing rather than
normative:

• Leads with the channel decision (ADR-0121 D3) — caller inside the platform invokes an
  action, caller outside reaches an apis: endpoint. Plus D5's reassurance: choosing
  wrong costs the URL shape and the policy keys, never the execution semantics.
• The four publish gates, each stated so a developer can match the prose against the
  error publish/validate actually emits, with the real message fragments quoted. Evaluation
  order and the stop-at-first-failure behaviour are stated, because they decide which of
  three problems you are told about.
• authRequired: false gets its own section, not a bullet — what it opens, the D6
  armed-rateLimit obligation (and why enabled defaulting to false makes a budget
  written without it meter nothing), the pre-auth metering order, the bucket key, and two
  things the flag does not buy: it is not a permission grant, and payload authenticity is
  not covered by any key in this vocabulary.
• api is code-only (api 注册表条目声明 allowRuntimeCreate: true,但运行时创建的端点匹配器永远看不见 —— 声明的能力运行时不兑现(真实 boot 实测) #5488) — allowRuntimeCreate: false / allowOrgOverride: false,
  the 403 NOT_CREATABLE before body validation, and why the runtime metadata door was
  never the door that serves.
• A worked example, and what /openapi.json says about the result.

Edits, all inside content/docs/api/:

• index.mdx — a Card, a module-list entry, and the sentence that disambiguates the two
  endpoint pages.
• plugin-endpoints.mdx — one intro sentence saying what the page is not, and one "See
  also" link. No restructuring, no re-titling.
• meta.json — one entry, placed next to plugin-endpoints so the sidebar itself does the
  disambiguating.

protocol/kernel/http-protocol.mdx is not edited — it is cross-linked, including one
note reconciling its five-row gate table with this page's four families (same checks,
different grouping).

Declared deviation: .claude/ is in this diff

A new hand-written page turns check:docs-audit-scope red until the workflow's derived
scope list is regenerated. .claude/workflows/docs-accuracy-audit.js therefore carries the
one line written by node scripts/docs-audit/check-audit-scope.mjs --write, committed
exactly as generated and never hand-edited:

+ "content/docs/api/declarative-endpoints.mdx",

.claude/** is a governed surface (#9866), so this PR is human-merge-only: it stays a
draft, is not enqueued, and has no auto-merge armed. Batch-2 siblings #10213 and #10216
append to the same file; on conflict the remedy is re-running --write on the merged
base, never a hand edit.

No changeset: the diff is documentation plus that generated line, so nothing is published.

A defect the page caught while being written

Both worked examples carry {/* os:check */}, so check:skill-examples type-checks them
against the current spec. It rejected the first draft: target is required on every
ApiEndpoint, including an object_operation, where neither the publish gate nor the
executor reads it. The examples now declare it and the page says so in prose — exactly the
kind of thing a developer discovers as a type error otherwise.

Verification

All local gates green on cd7e5773b, the final commit — re-derived after committing with
node scripts/pm/dispatch-gates.mjs (which named three families the dispatch list did not:
check:doc-formula-expressions, check:pm-governed-merges, check:skill-frame-sync, all
via the .claude/ path):

Gate	Verdict line
check:doc-anchors	252 internal #fragment link(s) across 400 source file(s) all resolve to a real heading
check:doc-authoring	381 files clean — no bare metadata literals
check:docs-audit-scope	scope is in sync with content/docs/: 181 hand-written doc(s)
check:docs-redirects	OK (92 entries …)
check:published-readme-links	152 outbound link(s) across 60 published markdown file(s)
check:role-word	OK, no new occurrences of the reserved word
check:cross-package-test-inputs	OK: 12 package(s) read outside themselves, all declared
check:skill-examples	211 prose examples type-check against @objectstack/spec
check:empty-state	all classified (1 closed, 2 open, 4 output, 9 scope)
check:liveness	every governed-type property … is classified
check:strictness-ledger	61 file(s) across 5 triaged director(ies)
check:variant-docs	18 discriminated union(s) — 8 governed, 10 exempt
check:doc-formula-expressions	22 record-scoped formula example(s) across 407 files / 1417 TS blocks judged clean
check:skill-frame-sync	4 copies of the decision frame are structurally isomorphic
check:pm-governed-merges	--self-test: 81 assertions

Every heavy step ran through scripts/pm/os-verify-lock.sh.

Generated by Claude Code

---

Generated by Claude Code