Auto-organize documentation by zod source files

[Copilot]

Documentation was generated flat within category roots (88 files in /ai/), making navigation difficult. Now automatically organizes into subfolders matching source .zod.ts files.

Implementation

• Auto-detection: Scans src/{category}/*.zod.ts files to build schema → zodFile mapping
• Removes hardcoded subcategories: Replaced 74-line SUB_CATEGORIES config with dynamic ZOD_FILE_TITLES lookup
• Clean rebuild: Purges old flat structure before generation to prevent stale files
• Complete coverage: All 49 zod files mapped to human-readable titles

Structure Change

Before:

/content/docs/references/ai/
  Agent.mdx
  CostEntry.mdx
  ModelRegistry.mdx
  ... (88 files)

After:

/content/docs/references/ai/
  agent/           (Agents)
    Agent.mdx
    AIKnowledge.mdx
  cost/            (Cost Management)
    CostEntry.mdx
    BudgetLimit.mdx
  model-registry/  (Model Registry)
    ModelRegistry.mdx
  ... (8 folders)

Applies to all categories: data (12 folders), ui (7 folders), system (19 folders), ai (8 folders), api (1 folder).

Files Modified

• packages/spec/scripts/build-docs.ts - Rewritten to scan zod files instead of using hardcoded mappings

Original prompt

生成官网文档的时候要不要再按每一个zod文件分子文件夹？

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
spec	Error		Jan 23, 2026 4:13pm

[Copilot]

Pull request overview

This PR restructures the reference documentation so that content is organized by underlying .zod.ts source files rather than flat category directories, improving navigation and alignment with the metamodel. It updates category meta.json files and per-subfolder meta.json titles to reflect the new structure and removes now-obsolete pages and groupings.

Changes:

• Reworked meta.json navigation for data, system, ai, and api references to point to subfolders that mirror Zod schema groupings.
• Added new meta.json files for each new subfolder (e.g., data/object, system/manifest, ai/agent, api/contract) with human-readable titles.
• Removed obsolete high-level groupings and old MDX pages that no longer correspond 1:1 to the current Zod schema layout.

Reviewed changes

Copilot reviewed 55 out of 393 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
content/docs/references/system/organization/meta.json	Adds title metadata for the new organization system subfolder.
content/docs/references/system/meta.json	Updates system reference root pages to list schema-aligned subfolders (api, audit, auth, datasource, etc.).
content/docs/references/system/manifest/meta.json	Introduces a Manifest section title for the manifest-related docs.
content/docs/references/system/license/meta.json	Introduces a Licenses section title for license-related system docs.
content/docs/references/system/job/meta.json	Introduces a Jobs section title for job-related system docs.
content/docs/references/system/integration/meta.json	Removes the old Integration grouping meta; now handled via schema-aligned folders.
content/docs/references/system/identity/meta.json	Renames the identity section title from “Identity & Auth” to “Identity” to separate identity from auth.
content/docs/references/system/identity/AuthProvider.mdx	Deletes an obsolete AuthProvider schema doc that no longer matches the new organization.
content/docs/references/system/identity/AuthProtocol.mdx	Deletes an obsolete AuthProtocol schema doc replaced by new structure.
content/docs/references/system/i18n/meta.json	Removes the old Internationalization grouping in favor of new schema-based layout.
content/docs/references/system/geo/meta.json	Removes the old Territory & Geo grouping; territory is now covered via dedicated entries.
content/docs/references/system/events/meta.json	Adds an Events section title for event-related system docs.
content/docs/references/system/driver/meta.json	Adds a Drivers section title for driver-related system docs.
content/docs/references/system/discovery/meta.json	Adds a Service Discovery section title for discovery-related docs.
content/docs/references/system/datasource/meta.json	Adds a Datasources section title for datasource-related docs.
content/docs/references/system/config/meta.json	Removes the old Configuration grouping meta.
content/docs/references/system/auth/meta.json	Adds an Authentication section title separating auth from identity.
content/docs/references/system/audit/meta.json	Simplifies the audit section title from “Audit & Compliance” to “Audit”.
content/docs/references/system/api/meta.json	Adds an api system subfolder title for API-related system configuration/docs.
content/docs/references/system/AuthenticationProvider.mdx	Deletes an obsolete AuthenticationProvider doc consolidated into new structure.
content/docs/references/system/AuthenticationConfig.mdx	Deletes an obsolete AuthenticationConfig doc consolidated into new structure.
content/docs/references/meta.json	Registers api as a top-level reference category alongside data/ui/system/ai.
content/docs/references/data/workflow/meta.json	Adds a Workflows section title for workflow-related data schemas.
content/docs/references/data/validation/meta.json	Adds a Validation section title for validation-related data schemas.
content/docs/references/data/types/meta.json	Removes the old “Types & Definitions” grouping meta.
content/docs/references/data/types/FieldMapping.mdx	Deletes an obsolete FieldMapping doc; mapping docs are now organized under the new mapping structure.
content/docs/references/data/trigger/meta.json	Adds a Triggers section title for trigger-related data schemas.
content/docs/references/data/sharing/meta.json	Adds a Sharing Rules section title for data sharing schemas.
content/docs/references/data/security/meta.json	Removes the old “Security & Access” grouping meta.
content/docs/references/data/query/meta.json	Adds a Queries section title for query-related data schemas.
content/docs/references/data/permission/meta.json	Adds a Permissions section title for permission-related data schemas.
content/docs/references/data/object/meta.json	Adds an Objects section title for object-level data schemas.
content/docs/references/data/meta.json	Replaces conceptual data groupings with schema-aligned pages (dataset, field, filter, etc.).
content/docs/references/data/mapping/meta.json	Adds a Mappings section title for mapping-related data schemas.
content/docs/references/data/logic/meta.json	Removes the old “Logic & Validation” grouping meta.
content/docs/references/data/flow/meta.json	Adds a Flows section title for flow-related data schemas.
content/docs/references/data/filter/meta.json	Adds a Filters section title for filter-related data schemas.
content/docs/references/data/field/meta.json	Adds a Fields section title for field-related data schemas.
content/docs/references/data/dataset/meta.json	Adds a Datasets section title for dataset-related data schemas.
content/docs/references/data/core/meta.json	Removes the old “Core Entities” grouping meta.
content/docs/references/data/automation/meta.json	Removes the old Automation grouping meta.
content/docs/references/data/analytics/meta.json	Removes the old Analytics (Data) grouping meta.
content/docs/references/api/requests/meta.json	Removes the old Request Payloads grouping meta.
content/docs/references/api/meta.json	Updates API reference root to a single contract page reflecting the new structure.
content/docs/references/api/envelopes/meta.json	Removes the old Response Envelopes grouping meta.
content/docs/references/api/contract/meta.json	Adds an API Contracts section title for contract-related API schemas.
content/docs/references/ai/workflow-automation/meta.json	Adds a Workflow Automation section title for AI workflow automation schemas.
content/docs/references/ai/rag-pipeline/meta.json	Adds a RAG Pipelines section title for retrieval-augmented generation pipelines.
content/docs/references/ai/predictive/meta.json	Adds a Predictive Models section title for predictive AI schemas.
content/docs/references/ai/nlq/meta.json	Adds a Natural Language Query section title for NLQ-related schemas.
content/docs/references/ai/model-registry/meta.json	Adds a Model Registry section title for model registry schemas.
content/docs/references/ai/meta.json	Adds explicit AI subpages (agent, conversation, cost, etc.) for schema-aligned navigation.
content/docs/references/ai/cost/meta.json	Adds a Cost Management section title for AI cost-related schemas.
content/docs/references/ai/conversation/meta.json	Adds a Conversations section title for conversation-related AI schemas.
content/docs/references/ai/agent/meta.json	Adds an Agents section title for agent-related AI schemas.

[Copilot]

The title uses the mixed-case form "Api" while other references (for example "title": "API Protocol" and "title": "API Contracts") use the all-caps acronym; for consistency and clarity, this should be updated to "API".

Suggested change

	"title": "Api"
	"title": "API"