Portal Maintenance implemented
The portal is a curated front door. Its maintenance model is now implemented: source links, metadata, synced contract artifacts, and canonical-doc ownership are enforced in normal change flow.
The operating split is deliberate: doc/** is the canonical corpus;
packages/docs/docs/** is the curated portal. The portal should not mirror
every source file.
Required Metadata
Every portal page must declare:
audiencevisibilitystatussource_docsdescription
The docs-portal-check target validates those fields and fails when a
source_docs entry does not resolve to a repo file.
The same check generates a source-doc inventory artifact so the team can see which canonical references are already covered by portal pages and which should be promoted next. See Source Doc Inventory.
Ownership and freshness metadata is also required. See Ownership And Freshness for the review cadence, freshness-risk, owner, and sync-trigger model.
Change Rules
- Product, API, security, ops, or architecture changes update the relevant portal page in the same PR when the user-facing explanation changes.
- Portal pages summarize and route. Detailed specs remain under
doc/**. - Generated artifacts come from committed contracts or code, not hand-edited snapshots.
- Security and production-readiness pages distinguish implemented, report-only, gap, runbook, and evidence states.
- External publication requires visibility review before pages leave the internal track.
Update Triggers
| Change type | Portal expectation |
|---|---|
| User-visible workflow or copy change | Update the affected user-guide or audience page in the same change |
| New admin/operator surface | Add or update the matching team handoff page and route |
| Architecture review or ARB/JAD packet change | Refresh the architecture review pack or linked deep-dive pages |
| Security/readiness posture change | Refresh the security-readiness path and any user/admin wording affected by it |
| Docs hostname/publication-path change | Update portal config, deployment runbook, and portal README together |
| Screenshot-backed flow change | Replace screenshots and rerun make docs-portal-check in the same slice |
Standing Sync Track
Keep a separate Fairway-backed sync track for portal maintenance. That track should stay active even after the first portal build-out is complete and should own canonical-doc hygiene, source-link validation, generated artifact freshness, stale/superseded doc cleanup, and visibility review.
Visual Assets
Mermaid diagrams are preferred for architecture, process, state, and dependency views because they are reviewable text. Use maintained images only when a page needs a real screenshot, a publication-ready visual, or a concept that Mermaid cannot express clearly. See Visual Standards.
Quarterly Review
Once per quarter, review:
- top-level audience paths,
- stale source links,
- status labels,
- public/customer/partner/internal visibility,
- App SDK examples and runnable commands,
- generated API/SDK artifact freshness.
Release Discipline
When a release changes user/admin/operator behavior, the portal should be treated as part of the release closeout, not as a later cleanup item. If the team needs the portal to explain a behavior to product, architecture, security, developers, or operators, that explanation should ship with the behavior or the release should stay visibly incomplete.