Contributing to platform docs

Before you open a PR

1. Read the style guide and status vocabulary.
2. Classify the page in docs/access/page-classification.yaml (Public / Partner / Internal / Client-specific).
3. If the page is Public or Partner and should ship externally, add it to public-allowlist.txt and mkdocs.public.yml nav.
4. Never put Internal findings, client names, secret env names, or private infra URLs on allowlisted pages.
5. Update docs/access/page-metadata.yaml (audience, owner role, status, last_verified, repo evidence, review_interval_days).

Local checks

source .venv/bin/activate
./scripts/run_quality_gate.sh          # full gate
./scripts/build_public.sh              # public artifact
./scripts/build_internal.sh            # internal artifact

PR checklist

Use the repository pull-request template (.github/PULL_REQUEST_TEMPLATE.md). Summarise:

• Audience and classification
• Evidence (repo / commit / date) for technical claims
• Security: nothing sensitive on the public allowlist
• Examples validated (JSON / OpenAPI)
• Links and OpenAPI impact
• Verification commands run

Deploy

Deploy public docs only from committed source after review:

./scripts/build_public.sh
npx wrangler@4 pages deploy site-public --project-name=masteryhiveai-platform-docs

Do not deploy site-internal/ to the public Cloudflare project.