Source Of Truth Model designed
GPUaaS should not publish the entire doc/ tree directly into Docusaurus. The
portal is a curated reader path. The canonical corpus remains under doc/**.
Two-Layer Model
| Layer | Path | Role |
|---|---|---|
| Canonical corpus | doc/**, doc/api/** | Contracts, specs, architecture records, runbooks, governance, product decisions, evidence. |
| Curated portal | packages/docs/docs/** | Audience-first summaries, paths, navigation, generated artifact links, and publication tracks. |
The portal may quote small facts, summarize decisions, and route readers. It must not become a parallel spec set.
Use Source Doc Inventory to decide which canonical references should be promoted into portal-native pages and which should remain source links only.
Use the platform-foundation source-of-truth map as the cleanup gate before broad portal edits. It classifies current authority, migration-state material, future-state material, superseded docs, and historical references so portal pages do not need to reconcile contradictory source docs inline.
Change Flow
When canonical docs change, update the portal in the same work item if the change affects a reader-facing journey, API/API consumer behavior, security posture, operator practice, product IA, or architecture model.
When portal pages change, make sure each page still lists the canonical
source_docs that justify the summary.
Before a portal page uses a migration-state, future-state, superseded, or historical source doc, the page must explicitly label that source status and link the current authority alongside it.
What Gets Published Later
The first portal is internal. Future public, customer, and partner tracks should
filter from curated portal pages, not raw doc/** files. This keeps sensitive
runbooks, internal evidence, and work-in-progress architecture out of external
builds unless explicitly reviewed.
Standing Sync Work
Portal sync is a standing track, not a one-time setup. It owns:
- source-link validation,
- canonical doc hygiene,
- generated OpenAPI and AsyncAPI artifact freshness,
- stale or superseded doc cleanup,
- visibility review before external publication,
- portal page updates when high-value source docs change.
Visuals
Use Visual Standards when a portal page
needs a diagram or image. Mermaid is preferred for reviewable architecture and
process diagrams; maintained images belong under packages/docs/static/img/.