Architecture

Three-repository pipeline

The documentation and governance system spans three repositories, each with a distinct responsibility:

Repository	Role
docs-control	Central governance hub — repository settings, branch protection config, managed files manifest, reusable CI workflows, Antigravity AI workflows, caller workflow templates, agent skills, and downstream dispatch
docs-builder	Docker build image — Astro + Starlight build orchestration, npm dependencies, Puppeteer PDF generation, interactive components
docs-theme	Astro Starlight plugin — shared branding, CSS, fonts, logos, layout components, astro.config.mjs, and content.config.ts

Content repositories only need a docs/ directory. The build container and workflow handle everything else.

Data flow

When a template file or workflow changes in docs-control on main:

1. The dispatch workflow fires and triggers enforcement in every downstream repository
2. The enforcement workflow compares desired state against current state and patches any drift
3. The file sync workflow detects drifted managed files, creates a PR with canonical content, and auto-merges it
4. Reusable Antigravity AI workflows (antigravity-review.yml and antigravity-translate.yml) execute on pull requests across enrolled repositories

Antigravity AI Automation

The fleet incorporates Antigravity (agy) AI automation running on GitHub Actions runners:

Workflow	Purpose	Trigger & Execution
Antigravity Code Review (antigravity-review.yml)	Automated AI pull request code review	Runs on PR creation or update. Uses Gemini 3.6 Flash (High) to audit diffs for security vulnerabilities, hardcoded secrets, PII leakage, and code quality, posting feedback via PR comments.
Antigravity Language Translation (antigravity-translate.yml)	Automated AI documentation translation	Runs on PRs modifying docs/en/**/*.md[x]. Executes the .agents/skills/i18n-translate/SKILL.md skill to update 12 target locales (fr, es, de, pt-br, ja, ko, zh-cn, zh-tw, ar, it, hi, th), update i18n.sourceHash, and auto-commit back to the PR branch.

Token & Credentials Model

Three sets of credentials provide least-privilege separation:

Token / Secret	Permissions / Scope	Used by
REPO_SETTINGS_TOKEN	Administration R/W, Pages R/W, Contents Read, Metadata Read	enforce-repo-settings.yml, dispatch-downstream.yml, update-governed-workflow-pins.yml
REPO_SYNC_TOKEN	Contents R/W, Issues R/W, Pull Requests R/W, Metadata Read	sync-managed-files.yml
ANTIGRAVITY_TOKEN & GCP_PROJECT_ID	Antigravity AI Authentication & GCP Project Access	antigravity-review.yml, antigravity-translate.yml

The enforcement workflow needs admin access to modify branch protection and Pages settings. The sync workflow needs contents and PR access to create branches, commit files, and merge PRs. Antigravity AI workflows use dedicated project credentials to authenticate with Gemini 3.6 Flash.

Self-detection

Docs-control is both the provider and consumer of its own governance config. When enforce-repo-settings.yml runs on docs-control itself (via the push trigger), it detects this by comparing managed_files.source_repo against github.repository. This triggers the self_contexts override in branch protection — docs-control uses workflows directly (for example, Shell Unit Tests), while downstream repositories use caller wrappers (for example, lint / Shell Unit Tests). See the configuration page for details on contexts vs self_contexts.

Repository layout

Directory / File	Purpose
.github/config/repo-settings.json	Central config: repository settings, branch protection, Actions permissions, Pages config, and the managed files manifest
.github/config/downstream-repos.json	Registry of enrolled downstream repositories
.github/config/docs-sites.json	Metadata for each downstream docs site (label, URL, description) used by README templating
.github/workflows/	Reusable workflows: enforcement, file sync, pages deploy, linked-issue check, dispatch, antigravity review, and antigravity translation
.agents/skills/	Agent skills governance: demo-components, i18n-translate
workflows/	Caller templates downstream repositories install into .github/workflows/
docs/	Documentation source (built and deployed via Astro Starlight)
CONTRIBUTING.md	Contributor workflow rules (synced to all downstream repositories)
CLAUDE.md	AI assistant instructions (synced to all downstream repositories)
AGENTS.md	Repository agent instructions and governance policies
README.md.tpl	Template for dynamically generated downstream README files
.pre-commit-config.yaml	Pre-commit hooks configuration (synced to all downstream repositories)
.markdownlint.json	Markdown linter rules
.yamllint.yaml	YAML linter rules