docs(getting-started): quick-reference 计数改 (N of M schemas),并把真实参考目录纳入门 (#6530) (#7302)

按 maintainer 2026-08-08 的 Option C 裁决实施。

原来的 `(N schemas)` 是**自指**的:N 只与它自己下面那张表比对,与
content/docs/references/{category}/ 的真实面之间没有任何门在看。#6530 实测出
`## Data Protocol (17 schemas)` 之上是一个发布 29(今日 30)个 schema 页的目录,
其中 13 个页在整张页面上没有任何一行 —— 而门一直是绿的,并且永远会是绿的。

13 个标题一律改为 `(N of M schemas)`:N 仍是本表行数,M 是该分类目录实际发布的
参考页数(`.mdx` 去掉 index.mdx)。表继续保持策展子集 —— 一个把 30 个 data 页
全镜像过来的 quick reference 就不 quick 了 —— 但措辞不再读作总数,且 N < M 这个
正常状态从此有门在看。

今日 main 上全部 13 个 M 重新实测(未复用 08-08 的表):只有 data 动了,29 → 30,
因为 e2798fa(#6345 / PR #6910)在 08-09 新增了 driver-turso.mdx。这正是这道门
值得有的证据 —— 两天,一格漂移,原来的自指门看不见。

跨切规则(裁决要求随行):

- 每一行都必须有链接。Shared 的 `Connector Auth` 原来是**裸名无链接**,现在指向
  /docs/references/integration/connector —— 那个文件在 src/shared/,但
  `@objectstack/spec/shared` 并不发布它,它经 `@objectstack/spec/integration`
  到达消费者,build-docs.ts 的 `integration:` 注释与 scripts/lib/root-index.ts
  都写明了这一点(后者还把 `shared/connector-auth.zod.ts` 这类行点名为缺陷类)。
  Key Schemas 一并从未发布的 ConnectorAuthConfig 改为已发布的 ConnectorInstanceAuth。
- 三行指向 references/ 之外的行统一带 `↗` 标记(UI 的 Widget Contract、Kernel 的
  Events、Shared 的 Connector Auth)。标记就是 N 与 M 的对账口:带标记的行算进 N,
  但不是 M 里的那些页。门双向校验 —— 未标记的行必须指向本小节自己的分类目录下
  一个真实存在、且不与别行重复的页;指向别处的行必须带标记;带标记却指回自己
  目录的行也红,否则标记会悄悄从覆盖率里减掉一页。
- 分类级策展写在页面上而不是留作默认:新增 `## Categories Without a Section`
  一节,写明 references/studio/(3 页)与 references/contracts/(0 页,只剩一个
  meta.json)为何没有小节;门同样读这张表,任何分类目录必须要么有小节、要么在
  这里被声明,不能两者都是、也不能两者都不是。

门的自测从 9 例扩到 22 例。第 3 例是反空转的那一例:页面内部自洽、只有目录不符,
删掉 M 断言后它实测归零(4 条断言全红),即 #6530 记录的"永远绿"状态。第 18/20 例
对分类级覆盖扫描做同样的反向验证。

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

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

Author: os-project-manager

content/docs/getting-started/quick-reference.mdx

@@ -12,7 +12,18 @@ Fast lookup for the ObjectStack protocols organized by category.
 Click on any protocol name to view its complete API reference.
 </Callout>
 
-## Data Protocol (17 schemas)
+**Reading the counts.** Every heading below says `(N of M schemas)`. **N** is how many
+protocols this table lists; **M** is how many reference pages the matching
+`content/docs/references/<category>/` directory publishes. These tables are a *curated*
+fast lookup, not a mirror of the reference tree — `N < M` is normal and intended. Both
+numbers are checked by `pnpm check:quick-reference-counts`, so a category that gains or
+loses a page shows up here instead of drifting unnoticed. A row marked ↗ links outside
+its category's reference tree: it is one of the N rows, but it is not one of the M pages.
+Categories that have no section here at all are named under
+[Categories Without a Section](#categories-without-a-section) — that curation is stated,
+not left implicit.
+
+## Data Protocol (17 of 30 schemas)
 
 Core business logic and data modeling schemas.
 
@@ -36,7 +47,7 @@ Core business logic and data modeling schemas.
 | **[Postgres Driver](/docs/references/data/driver-postgres)** | `driver/postgres.zod.ts` | PostgresConfig | PostgreSQL configuration |
 | **[Mongo Driver](/docs/references/data/driver-mongo)** | `driver/mongo.zod.ts` | MongoConfig | MongoDB configuration |
 
-## UI Protocol (11 schemas)
+## UI Protocol (11 of 16 schemas)
 
 Presentation layer - views, forms, dashboards, and themes.
 
@@ -52,9 +63,9 @@ Presentation layer - views, forms, dashboards, and themes.
 | **[Component](/docs/references/ui/component)** | `component.zod.ts` | PageComponent variants | Reusable UI components |
 | **[Chart](/docs/references/ui/chart)** | `chart.zod.ts` | Chart, ChartType | Chart definitions |
 | **[Theme](/docs/references/ui/theme)** | `theme.zod.ts` | Theme, ColorPalette | Theming and branding |
-| **[Widget Contract](/docs/protocol/objectui/widget-contract)** | `widget.zod.ts` | FieldWidgetProps | Props a custom field widget receives |
+| **[Widget Contract](/docs/protocol/objectui/widget-contract)** ↗ | `widget.zod.ts` | FieldWidgetProps | Props a custom field widget receives — the contract is documented with ObjectUI, outside `references/ui/` |
 
-## Kernel Protocol (17 schemas)
+## Kernel Protocol (17 of 31 schemas)
 
 Plugin architecture, manifests, and kernel runtime.
 
@@ -74,11 +85,11 @@ Plugin architecture, manifests, and kernel runtime.
 | **[Plugin Versioning](/docs/references/kernel/plugin-versioning)** | `plugin-versioning.zod.ts` | PluginCompatibilityMatrix, DeprecationNotice | Version compatibility |
 | **[Service Registry](/docs/references/kernel/service-registry)** | `service-registry.zod.ts` | ServiceRegistryConfig, ServiceMetadata | Service discovery |
 | **[Startup Orchestrator](/docs/references/kernel/startup-orchestrator)** | `startup-orchestrator.zod.ts` | StartupOptions, StartupOrchestrationResult | System startup |
-| **[Events](/docs/kernel/events)** | `events.zod.ts` | Event, EventBusConfig | System event bus |
+| **[Events](/docs/kernel/events)** ↗ | `events.zod.ts` | Event, EventBusConfig | System event bus — the hand-written guide, outside `references/kernel/` (which splits the same surface across six `events-*` pages) |
 | **[Metadata Loader](/docs/references/kernel/metadata-loader)** | `metadata-loader.zod.ts` | MetadataLoaderContract | Metadata loading |
 | **[Package Registry](/docs/references/kernel/package-registry)** | `package-registry.zod.ts` | InstalledPackage, InstallPackageRequest | Package resolution |
 
-## System Protocol (18 schemas)
+## System Protocol (18 of 37 schemas)
 
 Runtime environment, logging, jobs, caching, and observability.
 
@@ -103,7 +114,7 @@ Runtime environment, logging, jobs, caching, and observability.
 | **[Translation](/docs/references/system/translation)** | `translation.zod.ts` | Translation | i18n support |
 | **[Worker](/docs/references/system/worker)** | `worker.zod.ts` | Worker | Background workers |
 
-## AI Protocol (11 schemas)
+## AI Protocol (11 of 11 schemas)
 
 AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking.
 
@@ -121,7 +132,7 @@ AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking
 | **[Usage](/docs/references/ai/usage)** | `usage.zod.ts` | AIUsageRecord, TokenUsage | AI usage and cost tracking |
 | **[Solution Blueprint](/docs/references/ai/solution-blueprint)** | `solution-blueprint.zod.ts` | BlueprintObject, BlueprintApp | Blueprint format for AI app generation |
 
-## API Protocol (17 schemas)
+## API Protocol (17 of 28 schemas)
 
 REST/GraphQL endpoints, real-time subscriptions, and discovery.
 
@@ -145,7 +156,7 @@ REST/GraphQL endpoints, real-time subscriptions, and discovery.
 | **[Metadata](/docs/references/api/metadata)** | `metadata.zod.ts` | Metadata | API metadata endpoints |
 | **[Storage](/docs/references/api/storage)** | `storage.zod.ts` | Storage | API storage operations |
 
-## Automation Protocol (4 schemas)
+## Automation Protocol (4 of 13 schemas)
 
 Flows, state machines, approvals, and integrations.
 
@@ -156,7 +167,7 @@ Flows, state machines, approvals, and integrations.
 | **[State Machine](/docs/references/automation/state-machine)** | `state-machine.zod.ts` | StateMachine | State machine definitions |
 | **[Webhook](/docs/references/automation/webhook)** | `webhook.zod.ts` | Webhook | Outbound webhooks |
 
-## Security Protocol (3 schemas)
+## Security Protocol (3 of 5 schemas)
 
 Access control, permissions, and row-level security.
 
@@ -166,7 +177,7 @@ Access control, permissions, and row-level security.
 | **[RLS](/docs/references/security/rls)** | `rls.zod.ts` | RowLevelSecurityPolicy | Row-level security filters |
 | **[Sharing](/docs/references/security/sharing)** | `sharing.zod.ts` | SharingRule | Record sharing rules |
 
-## Identity Protocol (4 schemas)
+## Identity Protocol (4 of 5 schemas)
 
 User identity, organizations, and position management.
 
@@ -177,7 +188,7 @@ User identity, organizations, and position management.
 | **[Position](/docs/references/identity/position)** | `position.zod.ts` | Position | Permission-set distribution (岗位, ADR-0090) |
 | **[SCIM](/docs/references/identity/scim)** | `scim.zod.ts` | SCIMUser, SCIMGroup | SCIM 2.0 provisioning |
 
-## Cloud Protocol (3 schemas)
+## Cloud Protocol (3 of 11 schemas)
 
 Environments, marketplace, licensing, and multi-tenancy.
 
@@ -187,7 +198,7 @@ Environments, marketplace, licensing, and multi-tenancy.
 | **[Marketplace](/docs/references/cloud/marketplace)** | `marketplace.zod.ts` | MarketplaceListing, PackageSubmission | Plugin marketplace |
 | **[Tenant](/docs/references/cloud/tenant)** | `tenant.zod.ts` | Tenant | Multi-tenancy isolation |
 
-## Integration Protocol (1 schema)
+## Integration Protocol (1 of 1 schema)
 
 External system connectors — one protocol (ADR-0097): a connector entry is
 either a catalog descriptor or a provider-bound instance that a generic
@@ -200,7 +211,7 @@ from the provider itself, not from hand-written spec files.
 |:---------|:-----------|:------------|:--------|
 | **[Connector](/docs/references/integration/connector)** | `connector.zod.ts` | Connector | The connector protocol — auth, sync, webhooks, rate limiting |
 
-## Shared Protocol (5 schemas)
+## Shared Protocol (5 of 8 schemas)
 
 Common utilities used across all protocols.
 
@@ -210,16 +221,28 @@ Common utilities used across all protocols.
 | **[HTTP](/docs/references/shared/http)** | `http.zod.ts` | HttpRequest, HttpMethod, CorsConfig | HTTP utilities |
 | **[Identifiers](/docs/references/shared/identifiers)** | `identifiers.zod.ts` | SystemIdentifier, SnakeCaseIdentifier | Standard ID patterns |
 | **[Mapping](/docs/references/shared/mapping)** | `mapping.zod.ts` | FieldMapping | Field mapping utilities |
-| **Connector Auth** | `connector-auth.zod.ts` | ConnectorAuthConfig | Connector auth patterns |
+| **[Connector Auth](/docs/references/integration/connector)** ↗ | `connector-auth.zod.ts` | ConnectorInstanceAuth | Declarative connector auth (ADR-0097). The file sits in `src/shared/` but `@objectstack/spec/shared` does not publish it — it reaches consumers through `@objectstack/spec/integration`, so it is documented on the Connector page |
 
-## QA Protocol (1 schema)
+## QA Protocol (1 of 1 schema)
 
 Testing and quality assurance.
 
 | Protocol | Source File | Key Schemas | Purpose |
 |:---------|:-----------|:------------|:--------|
 | **[Testing](/docs/references/qa/testing)** | `testing.zod.ts` | TestSuite | Declarative test definitions |
 
+## Categories Without a Section
+
+`content/docs/references/` holds two more category directories that deliberately get no
+section above. Curation happens at the category level as well as inside each table, and
+this is where it is stated. The same gate reads this table, so a new category directory —
+or a page landing in one of these — goes red until this page is updated.
+
+| Category directory | Pages | Why it has no section |
+|:---|---:|:---|
+| [`studio`](/docs/references/studio) | 3 | Designer-facing metadata (`flow-builder`, `object-designer`, `plugin`) — Studio's own authoring surfaces, not protocols an app declares. Reach them from the [reference index](/docs/references). |
+| `contracts` | 0 | Publishes no reference page at all; the directory holds only a `meta.json` left over from an earlier layout. There is nothing to link. |
+
 ---
 
 ## Common Patterns