Content Ownership Boundary
📌 Rule of thumb: every piece of documentation has exactly one home. If the same content is maintained by hand in both the starter repository and this site, that is a bug — assign it one home.
The Boundary
Section titled “The Boundary”The starter repository owns adopter-clone content
Section titled “The starter repository owns adopter-clone content”The starter’s docs/ is canonical for everything that ships inside adopter clones so agents and developers have context offline:
- Architecture Decision Records (
/astro/adr/) - Implementation guides, code examples, guides and reference (
/astro/implementation-guides/) - Patterns (
/astro/patterns/) - AI context (
/astro/ai-context/) and prompt libraries (/astro/ai-prompts/) - Development pages (
/astro/development/) and snippets (/astro/snippets/)
Edit these in the starter repository. Their published copies here are written by the pull pipeline and gated against upstream; a local edit is reverted by the next pull and flagged by CI.
This site owns human onboarding
Section titled “This site owns human onboarding”This docs site is canonical for the pages that onboard humans to a product from the web, and for pages about the site itself:
- Getting started: onboarding, launch demo, quick deploy, FAQ, creating your first page, directory structure, included in this template
- The product index and README pages
- This page
- The reference tech stack page — the one page whose stack versions must resolve from
{{versions.*}}placeholders, which only this site can check against the manifest
These have no copy in the starter; edit them here. The two that live inside pulled directories are named in that directory’s exclude list in the product registry.
Product-Owned Content Is Pulled, Never Pushed
Section titled “Product-Owned Content Is Pulled, Never Pushed”Product-owned content is pulled at build time from the product repository — the historical push-based sync (ADR-008) is superseded.
| Content class | Pull mechanism | Enforcement |
|---|---|---|
Version facts ({{versions.*}}) | pnpm run update:versions from the starter’s versions.json public contract | drift:check — the ADR-059 drift gate, hard CI failure |
| Every directory above | pnpm run update:content from the starter’s docs/ | validate:content — byte-for-byte freshness gate, hard CI failure |
Both pipelines write committed output: builds are deterministic, diffs are reviewable, and offline or PR builds fall back to the committed copy. Both gates follow the same philosophy: a gate that cannot check must not pass, and DRIFT_SKIP=1 is the explicit local-only escape hatch.
The pull rewrites links for this site (the starter’s /patterns/foo/ becomes /astro/patterns/foo/, directory remaps and frontmatter slugs are honoured) and fails when an upstream link points at nothing — that would be a broken link here, and the fix belongs upstream. Placeholders resolve against the manifest of the product section a page lives in, so each product’s pages read their own versions.
The pull pipelines are keyed by the product registry (scripts/src/products.ts); the Go starter’s ADRs are pulled the same way, with the title derived from each record’s heading because those files carry no frontmatter.
What This Means in Practice
Section titled “What This Means in Practice”- A typo in an ADR, an implementation guide, a pattern or a prompt? Fix it in the starter. The next pull brings it here; editing the copy in this repo will be reverted by the pipeline and flagged by
validate:content. - A confusing sentence in Quick Deploy or the FAQ? Fix it here.
- Adding a new content class that both repos want? Decide its single home first. If it must appear in both, add it to the pull table — never copy by hand and never push.