docs

Install dependencies, synchronize the engine-generated API files, and start the development server:

npm ci
npm run api:sync -- --engine=../skymage
npm run dev

api:sync copies the generated OpenAPI document and Markdown reference from the engine repository. Validate a local engine checkout with:

npm run api:check -- --engine=../skymage
npm run build
npm audit

API documentation automation

The engine's ApiCatalog is the source of truth for runtime query filtering and normalization, public/openapi.json, and docs/api-reference.md. This repository stores synchronized copies for VitePress and the interactive playground.

The Sync Engine API workflow runs when the engine sends an engine-updated repository dispatch, once per day as a fallback, or manually. It reads the deployed public specification from https://skymage.net/openapi.json, validates the result, builds the site, and commits only the generated API artifacts when they changed.

Configure a DOCS_REPO_TOKEN secret in the engine repository with access to dispatch workflows in skymagephp/docs. The docs workflow uses its own GITHUB_TOKEN with contents: write permission to commit synchronized files. If branch protection blocks direct bot pushes, allow GitHub Actions to bypass that rule or replace the commit step with an automated pull request.