docs(spec): drop stale GraphQL references and stale header provenance (#11346)

`GraphQL` was retired as a product surface (packages/spec/src/api/ has zero
GraphQL sources, the /graphql dispatcher route was removed, and `graphql`
was never actually a CoreServiceName). Two places in the package still
asserted otherwise:

- CATEGORY_BLURBS.api in build-docs.ts read "REST/GraphQL contracts, ..."
  — drop /GraphQL and regenerate content/docs/references/index.mdx (the
  only file that blurb feeds — no hand-edit).
- packages/spec/llms.txt (hand-kept, ships in the npm tarball) listed an
  IGraphQLService contract row. Deleted it — IGraphQLService is declared
  nowhere in packages/**/src, and unlike the neighbouring IUIService
  DEPRECATED row it has no replacement to point readers at.

Also drops llms.txt's hand-typed `Schema Count` / `Last Updated` header
lines rather than refreshing them: measured against the current tree,
packages/spec now publishes 1,585 schemas across 418 test files — an
order of magnitude past the stale claim — and this file has no generator
to keep a refreshed number honest past the next PR that touches the
package.

Fixes #10834
Fixes #10833


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

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

Author: os-sam

.changeset/docs-graphql-stale-references.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/spec": patch
+---
+
+**Docs:** removes stale GraphQL references and stale hand-typed header provenance from generated and hand-kept protocol docs (#10834, #10833).
+
+GraphQL was retired as a product surface some time ago: `packages/spec/src/api/` has zero GraphQL sources, the `/graphql` HTTP route was removed from the dispatcher (out of the product plan, #2462 follow-on), and `graphql` was never actually a `CoreServiceName` — it only ever existed as a stray entry in this table and in metadata-protocol's discovery table (see the comment above `SERVICE_PROVIDER_TABLE` in `core-services.zod.ts`). Two places in the package still asserted otherwise:
+
+- The generated `content/docs/references/index.mdx` API Protocol blurb read "REST/GraphQL contracts, …". The source is `CATEGORY_BLURBS.api` in `packages/spec/scripts/build-docs.ts`; fixed there and regenerated with `gen:docs` — no hand-edit to the generated `.mdx`.
+- The hand-kept `packages/spec/llms.txt` (no generator; ships in the npm tarball per `files`) listed an `IGraphQLService` contract (execute, subscribe) under Service Contracts. `IGraphQLService` is declared nowhere in `packages/**/src` — verified before removal. Deleted the row rather than marking it `**DEPRECATED**` like the neighbouring `IUIService` row: that precedent fits a contract that has a replacement to point readers at; GraphQL has none — it's out of the product plan, not superseded by another contract — so a deprecation note would invent a migration path that doesn't exist.
+
+Also dropped this file's hand-typed `Schema Count` / `Last Updated` header lines (`171 Zod schemas, 191 test files, 5,157 tests`, `2026-02-12`) rather than refreshing them. Measured against the current tree: `packages/spec` now publishes 1,585 schemas (per the freshly generated `content/docs/references/index.mdx` root index) across 418 `*.test.ts` files — both roughly an order of magnitude past what the header claimed. Since this file has no generator (confirmed by the filer) and nothing re-verifies these numbers on change, a refreshed count would start drifting again on the very next PR that touches the package; removing the assertion is more honest than restating a number this file has no mechanism to keep true. Whether `llms.txt` should be generated at all is a larger follow-up left to the PM, not decided here.
+
+Graded rather than skipped: `llms.txt` ships in the `@objectstack/spec` npm tarball (`files`, enforced by `check:published-files`), so this prose change reaches consumers the same way the precedent in #10669 (`skill.tools` docblock) did.

content/docs/references/index.mdx

@@ -20,7 +20,7 @@ counts are sums of the rows they head. Regenerate with
 | Module | Pages | Schemas | Description |
 | :--- | ---: | ---: | :--- |
 | [AI Protocol](/docs/references/ai) | 11 | 66 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. |
-| [API Protocol](/docs/references/api) | 29 | 417 | REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery. |
+| [API Protocol](/docs/references/api) | 29 | 417 | REST contracts, endpoints, routing, realtime, batch, discovery. |
 | [Automation Protocol](/docs/references/automation) | 13 | 68 | Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records. |
 | [Cloud Protocol](/docs/references/cloud) | 11 | 94 | Environments, packages and versions, marketplace, developer portal, tenancy. |
 | [Data Protocol](/docs/references/data) | 29 | 166 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
@@ -63,7 +63,7 @@ Agents, tools, skills, RAG and knowledge sources, model registry, conversations.
 
 **Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **29 pages, 417 schemas**
 
-REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery.
+REST contracts, endpoints, routing, realtime, batch, discovery.
 
 | File | Schemas |
 | :--- | :--- |

packages/spec/llms.txt

@@ -2,8 +2,6 @@
 
 > **SYSTEM NOTE**: This file provides a high-level summary of the ObjectStack Protocol to help LLMs understand the codebase structure and intent.
 > **Version**: 3.0.0
-> **Schema Count**: 171 Zod schemas, 191 test files, 5,157 tests
-> **Last Updated**: 2026-02-12
 
 ## 1. Architecture Overview (The "Three-Layer Model")
 
@@ -168,7 +166,6 @@ function registerObject(rawConfig: unknown) {
 | `IAuthService` | authenticate, authorize, validateToken |
 | `IAutomationService` | executeFlow, triggerWorkflow |
 | `IUIService` | **DEPRECATED** — use IMetadataService.getView(), .listViews(), .getEffective('view', name, { userId }) |
-| `IGraphQLService` | execute, subscribe |
 
 ---
 

packages/spec/scripts/build-docs.ts

@@ -621,7 +621,7 @@ const ROOT_INDEX_INTRO =
  */
 const CATEGORY_BLURBS: Record<string, string> = {
   ai: 'Agents, tools, skills, RAG and knowledge sources, model registry, conversations.',
-  api: 'REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery.',
+  api: 'REST contracts, endpoints, routing, realtime, batch, discovery.',
   automation: 'Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records.',
   cloud: 'Environments, packages and versions, marketplace, developer portal, tenancy.',
   data: 'Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer.',