Source Doc Inventory designed
The portal should become readable enough that internal teams do not need to open
GitHub docs for normal onboarding. It should not become a raw mirror of
doc/**. This inventory controls which references get promoted into
portal-native pages and which stay as audit/source links.
Generated Inventory
The portal check now generates two source-doc inventory artifacts:
- Machine-readable JSON
- Reviewable Markdown artifact at
packages/docs/static/portal/source-doc-inventory.md
The inventory is built from each portal page's source_docs frontmatter. It
records which canonical docs are referenced, which portal pages use them, and a
first-pass promotion wave.
Discovery search should build on this inventory. The Search And Discovery plan defines the local index shape for portal pages, source docs, diagrams, and generated references.
Promotion Waves
| Wave | Meaning | Action |
|---|---|---|
| P0 portal-native | Core onboarding sources that internal teams should understand without GitHub access | Create or maintain standalone portal pages |
| P1 deep dive | High-value architecture, security, ops, API, or developer sources | Create focused deep-dive pages under the owning portal family |
| P2 route/link | Useful supporting references | Keep linked from relevant portal pages until reader demand justifies a page |
| Reference only | Prototype, historical, or IA evidence | Keep as source evidence; do not turn into public-facing explanation unless promoted |
P0 Sources Already Being Folded
| Source | Portal-native coverage |
|---|---|
doc/product/PRD.md | Product Strategy, Internal Team Onboarding |
doc/product/UX_Journeys.md | User Interactions, Use AI Cloud |
doc/architecture/Architecture_v1.md | Platform Overview, System Overview |
doc/operations/Production_Platform_Baseline.md | Day-2 Operations, Security & Production Readiness |
doc/Governance_Overview.md | Governance Model |
Next Consolidation Targets
| Track | Source docs | Portal pages to add next |
|---|---|---|
| Product deep dives | Product IA, UX implementation spec, page contracts, competitive matrix | Product IA, launch workflow, billing experience, admin/operator product surface |
| Architecture deep dives | Platform foundation, API route model, domain authoring model, state machines | Control plane, domain boundaries, platform shared services, state/event model |
| Ops/Security deep dives | Production baseline, runbook architecture, security control verification, threat model | Production baseline, security controls, incident model, release evidence model |
| Developer deep dives | App SDK starter pack, manifest guide, external app integration, API auth/access | App SDK onboarding, manifest reference, app promotion, generated API reference |
| Governance deep dives | Contract gates, CI checklist, coding/testing standards, agent model | Change control, Definition of Done, CI gates, agent lanes |
Consolidation Rule
Promote a source doc when a normal internal reader would otherwise need to read the raw GitHub document to understand the product, architecture, operation, or governance model. Keep it as a source link when it is mainly evidence, detailed specification, or implementation reference.