Fix docs build: ensure directories exist and generate schemas before docs

[Copilot]

CI build failing on docs generation with ENOENT: no such file or directory when writing category index.mdx files.

Root Cause

build-docs.ts creates category directories only when JSON schemas exist, but writes index.mdx based on zod file presence. When schemas missing → no directory → write fails.

Changes

• packages/spec/scripts/build-docs.ts: Add directory creation before writing index.mdx

  const categoryDir = path.join(DOCS_ROOT, category);
  if (!fs.existsSync(categoryDir)) fs.mkdirSync(categoryDir, { recursive: true });

• apps/docs/package.json: Run gen:schema before gen:docs in build script

  "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && next build"

This ensures the dependency chain executes correctly: gen:schema → gen:docs → next build.

Original prompt

引用: https://github.com/objectstack-ai/spec/actions/runs/21848274390/job/63049058438#step:9:1

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
objectstack-studio	Ready	Preview, Comment	Feb 10, 2026 3:12am
spec	Ready	Preview, Comment	Feb 10, 2026 3:12am

[Copilot]

Pull request overview

Fixes docs CI generation failures by ensuring prerequisites (schema generation + output directories) exist before writing generated MDX, and updates/extends generated reference docs content.

Changes:

• Update docs build pipeline to run gen:schema before gen:docs (then next build).
• Regenerate/reference docs across multiple protocol areas (system/kernel/api/etc.), adding new sections (e.g., Studio, Hub, MCP) and updating nav metadata.
• Add/adjust reference index and meta navigation entries for newly generated docs.

Reviewed changes

Copilot reviewed 154 out of 177 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
content/docs/references/system/migration.mdx	Regenerated system migration reference content (schema sections now largely empty).
content/docs/references/system/metrics.mdx	Expanded system metrics intro and regenerated schema headings/usages.
content/docs/references/system/meta.json	Update System reference navigation pages list.
content/docs/references/system/message-queue.mdx	Regenerated message-queue reference content (details removed).
content/docs/references/system/masking.mdx	Regenerated masking reference content (details removed).
content/docs/references/system/license.mdx	Update license reference usage and add LicenseMetricType section.
content/docs/references/system/job.mdx	Regenerated job reference content (details removed).
content/docs/references/system/index.mdx	Add cards for new System schemas and remove obsolete card.
content/docs/references/system/http-server.mdx	Regenerated http-server reference content (details removed).
content/docs/references/system/encryption.mdx	Regenerated encryption reference content (details removed).
content/docs/references/system/core-services.mdx	New System “Core Services” reference page.
content/docs/references/system/compliance.mdx	Regenerated compliance reference content (details removed).
content/docs/references/system/change-management.mdx	Regenerated change-management reference content (details removed).
content/docs/references/system/cache.mdx	Regenerated cache reference content (details removed).
content/docs/references/system/auth-config.mdx	Regenerated auth-config reference content (details removed).
content/docs/references/studio/plugin.mdx	New Studio plugin protocol reference page.
content/docs/references/studio/meta.json	New Studio reference navigation metadata.
content/docs/references/studio/index.mdx	New Studio reference index with cards.
content/docs/references/shared/view.mdx	Regenerated shared view reference content (enum values removed).
content/docs/references/shared/metadata-types.mdx	New shared metadata-types reference page.
content/docs/references/shared/metadata-persistence.mdx	New shared metadata-persistence reference page.
content/docs/references/shared/meta.json	Add shared pages (enums, metadata-*).
content/docs/references/shared/mapping.mdx	Regenerated shared mapping reference content (details removed).
content/docs/references/shared/index.mdx	Add cards for new shared references.
content/docs/references/shared/identifiers.mdx	Regenerated identifiers page (inline descriptions removed).
content/docs/references/shared/http.mdx	Regenerated shared http reference content (details removed).
content/docs/references/shared/enums.mdx	New shared enums reference page.
content/docs/references/security/territory.mdx	Regenerated security territory reference content (details removed).
content/docs/references/security/sharing.mdx	Regenerated sharing reference content (details removed).
content/docs/references/security/rls.mdx	Regenerated RLS reference content (details removed).
content/docs/references/security/policy.mdx	Regenerated policy reference content (details removed).
content/docs/references/security/permission.mdx	Regenerated permission reference content (details removed).
content/docs/references/qa/testing.mdx	Regenerated QA testing reference content (details removed).
content/docs/references/meta.json	Add Studio to top-level references nav.
content/docs/references/kernel/startup-orchestrator.mdx	Regenerated kernel startup-orchestrator reference content (details removed).
content/docs/references/kernel/service-registry.mdx	Regenerated kernel service-registry reference content (details removed).
content/docs/references/kernel/plugin.mdx	Update kernel plugin reference usage and headings.
content/docs/references/kernel/plugin-versioning.mdx	Expand plugin-versioning intro and regenerate sections.
content/docs/references/kernel/plugin-validator.mdx	Regenerated plugin-validator reference content (details removed).
content/docs/references/kernel/plugin-structure.mdx	Regenerated plugin-structure reference content (details removed).
content/docs/references/kernel/plugin-security.mdx	Update plugin-security usage and sections, add new headings.
content/docs/references/kernel/plugin-security-advanced.mdx	Fix source path and regenerate advanced security sections.
content/docs/references/kernel/plugin-runtime.mdx	New kernel plugin-runtime reference page.
content/docs/references/kernel/plugin-registry.mdx	Regenerated plugin-registry reference content (details removed).
content/docs/references/kernel/plugin-lifecycle-events.mdx	Regenerated lifecycle-events reference content (details removed).
content/docs/references/kernel/plugin-lifecycle-advanced.mdx	Regenerated lifecycle-advanced reference content (details removed).
content/docs/references/kernel/plugin-capability.mdx	Regenerated plugin-capability reference content (details removed).
content/docs/references/kernel/permission.mdx	Regenerated kernel permission reference content (details removed).
content/docs/references/kernel/package-registry.mdx	Regenerated package-registry reference content (details removed).
content/docs/references/kernel/meta.json	Update kernel pages ordering and add new entries.
content/docs/references/kernel/manifest.mdx	Regenerated manifest reference content (details removed).
content/docs/references/kernel/index.mdx	Add cards for new kernel reference pages.
content/docs/references/kernel/feature.mdx	Regenerated feature reference content (details removed).
content/docs/references/kernel/context.mdx	Regenerated context reference content (details removed).
content/docs/references/integration/object-storage.mdx	Regenerated integration object-storage reference content (details removed).
content/docs/references/integration/message-queue.mdx	Regenerated integration message-queue reference content (details removed).
content/docs/references/integration/mapping.mdx	Regenerated integration mapping reference content (details removed).
content/docs/references/integration/http.mdx	Regenerated integration http reference content (details removed).
content/docs/references/identity/role.mdx	Regenerated identity role reference content (details removed).
content/docs/references/identity/organization.mdx	Regenerated identity organization reference content (details removed).
content/docs/references/identity/identity.mdx	Regenerated identity identity reference content (details removed).
content/docs/references/hub/tenant.mdx	New Hub tenant protocol reference page.
content/docs/references/hub/registry-config.mdx	New Hub registry-config protocol reference page.
content/docs/references/hub/plugin-security.mdx	New Hub plugin-security protocol reference page.
content/docs/references/hub/plugin-registry.mdx	New Hub plugin-registry protocol reference page.
content/docs/references/hub/meta.json	New Hub reference navigation metadata.
content/docs/references/hub/license.mdx	New Hub license protocol reference page.
content/docs/references/data/search-engine.mdx	Regenerated data search-engine reference content (details removed).
content/docs/references/data/query.mdx	Regenerated data query reference content (details removed).
content/docs/references/data/metrics.mdx	Remove data metrics reference page.
content/docs/references/data/meta.json	Remove metrics from data navigation.
content/docs/references/data/mapping.mdx	Regenerated data mapping reference content (details removed).
content/docs/references/data/hook.mdx	Regenerated data hook reference content (details removed).
content/docs/references/data/filter.mdx	Regenerated data filter reference content (details removed).
content/docs/references/data/external-lookup.mdx	Regenerated external-lookup reference content (details removed).
content/docs/references/data/driver.mdx	Regenerated driver reference content (details removed).
content/docs/references/data/driver-sql.mdx	Regenerated driver-sql reference content (details removed).
content/docs/references/data/document.mdx	Regenerated document reference content (details removed).
content/docs/references/data/datasource.mdx	Regenerated datasource reference content (details removed).
content/docs/references/data/dataset.mdx	Regenerated dataset reference content (details removed).
content/docs/references/data/analytics.mdx	Update analytics usage section and regenerate headings.
content/docs/references/automation/webhook.mdx	Regenerated webhook reference content (details removed).
content/docs/references/automation/trigger-registry.mdx	Update automation trigger-registry usage and regenerate headings.
content/docs/references/automation/sync.mdx	Regenerated sync reference content (details removed).
content/docs/references/automation/state-machine.mdx	Regenerated state-machine reference content (details removed).
content/docs/references/automation/flow.mdx	Regenerated flow reference content (details removed).
content/docs/references/automation/events.mdx	Regenerated events reference content (details removed).
content/docs/references/automation/etl.mdx	Regenerated etl reference content (details removed).
content/docs/references/automation/connector.mdx	Update connector usage and regenerate headings.
content/docs/references/automation/approval.mdx	Regenerated approval reference content (details removed).
content/docs/references/api/view.mdx	Regenerated api view reference content (enum values removed).
content/docs/references/api/versioning.mdx	New API versioning protocol reference page.
content/docs/references/api/storage.mdx	Regenerated api storage reference content (details removed).
content/docs/references/api/router.mdx	Regenerated api router reference content (details removed).
content/docs/references/api/rest-server.mdx	Regenerated rest-server reference content (details removed).
content/docs/references/api/realtime.mdx	Update realtime usage and rename presence sections.
content/docs/references/api/plugin-rest-api.mdx	New API REST plugin protocol reference page.
content/docs/references/api/package-registry.mdx	Regenerated api package-registry reference content (details removed).
content/docs/references/api/odata.mdx	Regenerated odata reference content (details removed).
content/docs/references/api/object.mdx	New API object reference page (currently appears mismapped).
content/docs/references/api/metadata.mdx	Regenerated metadata reference content (details removed).
content/docs/references/api/meta.json	Update API reference nav: add/remove pages.
content/docs/references/api/index.mdx	Add cards for new API reference pages and remove Hub card.
content/docs/references/api/identity.mdx	Regenerated api identity reference content (details removed).
content/docs/references/api/http-cache.mdx	Regenerated http-cache reference content (details removed).
content/docs/references/api/errors.mdx	Regenerated errors reference content (details removed).
content/docs/references/api/endpoint.mdx	Regenerated endpoint reference content (details removed).
content/docs/references/api/dispatcher.mdx	New API dispatcher protocol reference page.
content/docs/references/api/discovery.mdx	Update discovery imports and add ServiceInfo section.
content/docs/references/api/contract.mdx	Regenerated contract reference content (details removed).
content/docs/references/api/connector.mdx	Regenerated connector reference content (enum values removed).
content/docs/references/api/batch.mdx	Regenerated batch reference content (details removed).
content/docs/references/api/auth.mdx	Regenerated auth reference content (details removed).
content/docs/references/api/analytics.mdx	Regenerated analytics API reference content (details removed).
content/docs/references/ai/runtime-ops.mdx	Regenerated ai runtime-ops reference content (details removed).
content/docs/references/ai/plugin-development.mdx	Regenerated plugin-development reference content (details removed).
content/docs/references/ai/meta.json	Add MCP to AI navigation.
content/docs/references/ai/mcp.mdx	New AI MCP protocol reference page.
content/docs/references/ai/index.mdx	Add MCP card to AI index.
content/docs/references/ai/feedback-loop.mdx	Regenerated feedback-loop reference content (details removed).
content/docs/references/ai/agent.mdx	Regenerated ai agent reference content (details removed).
apps/docs/package.json	Ensure schema generation runs before docs generation in build script.

Comments suppressed due to low confidence (1)

content/docs/references/system/auth-config.mdx:1

• The regenerated reference page now contains only headings with no schema details (e.g., properties/allowed values) under ## AuthConfig and subsequent sections. If this is unintended, it likely indicates the docs generator stopped rendering schema metadata (tables/lists). Consider restoring the schema detail rendering (properties/enum values/union options) so these reference pages remain useful.

---

[Copilot]

The TypeScript example imports the same identifiers as both value imports and type-only imports, which will fail to compile when copied (duplicate import names). Prefer importing only the Zod schemas as values (for .parse) and either (a) omit the type-only import, or (b) import types under different names, or (c) document types via z.infer<typeof HistogramBucketConfig> / exported ...Schema + ... type conventions.

Suggested change

import type { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, MetricsConfig, ServiceLevelIndicator, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system';

[Copilot]

This page is labeled as api/object (Source: packages/spec/src/api/object.zod.ts), but the usage + section refer to VersioningConfig. This looks like a doc generator mapping bug (wrong exported symbol picked for the file). The generated page should reference schemas from object.zod.ts (and the H2 section names should match those schemas), or the file should be renamed/moved to the correct topic.

[Copilot]

The page frontmatter/title says 'Core Services' but the H1 says 'Service Registry Protocol'. This is confusing in navigation/search. Recommend aligning the H1 with the page title (e.g., 'Core Services Protocol') or renaming the page/title if the intent is specifically the service registry.

Suggested change

	# Service Registry Protocol
	# Core Services Protocol

[Copilot]

Acronyms like MCP are typically capitalized in titles/descriptions. Consider changing title/description to MCP to match the protocol name and the content ('Model Context Protocol').

Suggested change

	title: Mcp
	description: Mcp protocol schemas
	title: MCP
	description: MCP protocol schemas