Content ownership

Clear ownership boundaries keep workflow documentation authoritative in the repositories that define the workflows, while still allowing this portal to present a unified site. Violating these boundaries creates drift: the published site becomes wrong, or workflow repos lose their standalone usefulness.

Golden rules

1. Workflow repos own workflow docs. Policy, procedures, migration guides, and tool integration details for a specific workflow are authored and reviewed in that workflow's Git repository first.
2. The portal owns publication mechanics. Site configuration, navigation between workflows, shared landing pages, and cross-workflow documentation live here.
3. Sync is copy-for-publish, not fork-for-edit. Files under docs-<workflow>/ (except portal-owned framing) are mirrors. Treat edits there as temporary unless they are backported upstream.
4. Common docs live here. Material that applies across workflows — portal architecture, ownership policy, publishing procedures — is authored in docs-common/.

Content map

Location	Authored by	Typical content	Edit here when
docs-common/	Portal maintainers	Portal architecture, ownership, publishing, cross-workflow guides	The change is about the portal or applies to all workflows
docs-superbuild/intro.md	Portal maintainers	Section landing, upstream pointer, navigation context	Framing or onboarding text for the superbuild section
docs-superbuild/*.md (other)	Synced from superbuild-workflow	CMake/Conan policy, governance, migration specs	Never as primary edit — change superbuild-workflow/docs/ first, then sync
docs-<workflow>/ (future)	Mixed: portal intro + synced body	Per-workflow sections	Intro in portal; body in workflow repo

Portal-owned vs synced files

Synced workflow content is copied from an upstream docs/ directory (or configured subset). The sync script preserves portal-owned files:

• intro.md in each docs-<workflow>/ folder is never overwritten by sync
• Files listed in a workflow's preserve manifest (optional, per-workflow) remain portal-owned

All other Markdown files in a workflow section are expected to match upstream after sync. If they differ, assume upstream is correct unless the portal is mid-publish.

Navigation and framing

The portal may legitimately change, without upstream approval:

• Navbar and footer links
• Sidebar structure and category groupings (in sidebars<Workflow>.ts)
• Section intro pages and short contextual notes prepended during sync (if ever automated)
• Cross-links between workflow sections and common docs

The portal must not silently rewrite workflow policy text during sync. Transformation steps belong in explicit, reviewable tooling — not ad hoc edits in mirrored files.

For AI coding agents

When asked to update superbuild workflow policy:

• Direct the change to ai-workflows/superbuild-workflow (local clone: superbuild-workflow/)
• After upstream merge, run sync in this portal and update sidebars if new pages were added

When asked to update how the documentation site works:

• Edit docs-common/ and portal configuration in this repository

When unsure: if the text describes what a workflow requires, it belongs upstream; if it describes how this site publishes workflows, it belongs here.

Anti-patterns

Anti-pattern	Why it fails
Editing synced docs-superbuild/governance.md only in the portal	Next sync overwrites the change; workflow repo consumers never see it
Duplicating full workflow docs into docs-common/	Two sources of truth diverge
Making the portal the only place workflow docs exist	Workflow repos lose submodule/policy value; CI and offline consumers break
Skipping sync after upstream doc merges	Published site lies about current policy