Sync Contract

The design system treats ~/.copilot as the canonical authoring location for reusable AI agents and skills. Generated docs pages are read-only projections so the AI catalog appears in the same navigation system as engineering, product, and ADR documentation, on the Astro Starlight site at docs-site/.

Local Build Behavior

Local pnpm build runs scripts/sync-ai-catalog.mjs --commit before the Vite build. The script regenerates the AI catalog from ~/.copilot. When ~/.copilot is its own Git repo, the script commits pending ~/.copilot changes with a standard sync message.

CI Behavior

When CI=true or GITHUB_ACTIONS=true, commit mode exits before writing files or running Git. CI can build the design system without attempting to read or mutate user-home AI folders.

Drift Prevention

Agents and skills should be changed in ~/.copilot first. Generated AI pages should not be hand-edited because the next sync will replace them.

Repo Guidance

CLAUDE.md is the repository entry file for AI coding assistants. ai:sync copies it to uppercase AGENTS.md for Codex when the checkout supports a distinct uppercase file; on case-insensitive filesystems where AGENTS.md resolves to lowercase agents.md, the script keeps the larger manual intact because CLAUDE.md already references it.

Source Lint

ai:sync parses Copilot agent and skill frontmatter as real YAML before generating docs pages or syncing skills into Codex. The command fails on malformed frontmatter, missing name, missing description, non-string agent categories, or skill names that do not match their folder names.