# Documentation Portal Sync Contract

## Purpose

Keep the Docusaurus portal useful without turning it into a second source of
truth.

The repository has two documentation layers:

1. `doc/**` is the canonical source corpus.
2. `packages/docs/docs/**` is the curated portal layer.

The portal summarizes, routes, and renders. Canonical specs, architecture
records, product decisions, operations runbooks, governance rules, and API/event
contracts remain under `doc/**` and `doc/api/**`.

## When To Update The Portal

Update the relevant portal page in the same change when a canonical doc change
affects:

- user or tenant-admin workflows,
- App SDK or app-developer onboarding,
- API, event, CLI, SDK, auth, idempotency, or error semantics,
- security controls, release gates, production-readiness posture, or gaps,
- operator runbooks, environment promotion, patching, UAT, or incident flow,
- architecture model, domain ownership, shared services, or deployment shape,
- product IA, page families, journey contracts, or customer-facing language.

Do not update the portal for purely internal scratch notes, typo-only edits, or
historical artifacts unless they change a reader-facing interpretation.

## Source-Of-Truth Rules

- API shape: `doc/api/openapi.draft.yaml` and domain OpenAPI fragments.
- Event shape: `doc/api/asyncapi.draft.yaml` and domain AsyncAPI fragments.
- Architecture decisions: `doc/architecture/**`, especially ADRs and
  platform-foundation docs.
- Product and UX decisions: `doc/product/**`.
- Operations and release practices: `doc/operations/**` and
  `doc/governance/**`.
- Curated reader paths: `packages/docs/docs/**`.

If a portal page and a canonical doc disagree, fix the portal summary unless
the canonical doc is explicitly stale or superseded.

## Canonical Doc Creation Gate

Before creating a new canonical doc, search the existing `doc/**` corpus and
prefer one of these outcomes:

1. update the existing source-of-truth doc;
2. add a cross-link or related-doc note to connect the existing design to the
   new work;
3. mark an old doc superseded and point it at the current source;
4. create a new doc only when it has a distinct lifecycle, owner, or artifact
   type.

New docs must identify their backing source docs and avoid introducing a second
model for concepts already covered elsewhere. This is especially important for
platform-wide concepts such as IAM, billing, API keys, product onboarding,
release evidence, App SDK contracts, gateway strategy, and environment
promotion.

## Portal Page Requirements

Every portal page must include frontmatter with:

- `id`
- `slug`
- `title`
- `description`
- `audience`
- `visibility`
- `status`
- `source_docs`

The `visibility` value is the publication track. Allowed tracks are:

- `public` for unauthenticated publication-safe content,
- `customer` for customer-authenticated or review-pack content,
- `partner` for app-developer and integration partner content,
- `internal` for the full internal operating portal,
- `ops` for protected operator/SRE content,
- `governance` for protected review, evidence, and change-control content.

The `source_docs` list must name real repository paths. `make
docs-portal-check` validates this and applies the initial publication safety
guard. Public and customer tracks must not reference scratch files, Fairway
evidence, local-dev docs, incident/evidence files, raw scripts, or other
internal-only sources. Public, customer, and partner pages must not contain
obvious private URLs, local file paths, credential text, raw private-key
markers, or unsupported TODO/TBD claims.

This guard is not a substitute for security, product, governance, or legal
review. It is the minimum deterministic check before any external track is
packaged.

## Visuals And Images

Use Mermaid first for source-controlled diagrams:

- architecture boundaries,
- ownership maps,
- release or sync flows,
- state machines,
- dependency views,
- event or API flow summaries.

Docusaurus supports Mermaid code blocks through `@docusaurus/theme-mermaid` and
`markdown.mermaid: true`. Use the official Docusaurus diagram docs and test
page as examples for supported diagram types and layout options.

Use maintained image assets when Mermaid cannot express the visual well:

- real UI screenshots,
- visual product journeys,
- publication-ready architecture illustrations,
- customer-facing diagrams that need manual layout,
- screenshots or evidence captures.

Store maintained portal images under `packages/docs/static/img/portal/`. Every
image-backed claim still needs source docs. Do not publish sensitive screenshots
to public, customer, or partner tracks without visibility review.

For static diagrams, keep the rendered image and editable source together when
possible. Use PNG for screenshots and publication-safe rendered diagrams. Use
SVG only when it is hand-authored/reviewable and does not carry hidden metadata.
The image is presentation; the canonical explanation remains in `source_docs`.

## Canonical Doc Hygiene

When touching a high-value source doc, prefer adding or preserving:

- title and purpose,
- status or lifecycle marker,
- owner or owning domain when known,
- supersedes / superseded-by markers when applicable,
- related docs,
- clear current-state versus target-state wording.

This metadata does not need to be uniform frontmatter yet. It does need to be
clear enough that portal maintainers and agents can determine whether the doc
is current, historical, internal-only, or publication-safe.

## Standing Sync Track

The Docusaurus portal track in `.fairway/docusaurus-track.yaml` is the execution
queue for portal build-out and sync work. Keep a separate standing sync task or
recurring queue item for:

- source-doc hygiene sweeps,
- portal source-link validation,
- generated contract artifact freshness,
- new canonical-doc-to-portal mapping,
- stale or superseded doc cleanup,
- publication visibility review.

The sync track should be evidence-backed by:

- `make docs-portal-check`,
- `bash scripts/ci/docs_portal_quality_gate.sh` for CI/Fairway evidence,
- Fairway readiness report for the `docusaurus-portal` profile,
- review records from content, architecture, security, frontend, ops, or
  governance as appropriate.

Run the portal quality gate for docs-only architecture changes when the changed
source doc appears in portal `source_docs`, changes API/App SDK interpretation,
changes publication metadata, changes security or production-readiness posture,
or changes a user/developer/operator reader path. Classify failures as
`DOC-FIX-*`, `HARNESS-FIX-*`, `CI-FIX-*`, or publication-blocking governance
findings using `doc/operations/Docs_Portal_Continuous_Quality_Gates_v1.md`.