Documentation Structure

Capell documentation is split by ownership. Source repositories own product and package docs; this repository owns the public docs shell, navigation, generated index pages, and operational notes for publishing.

Use this page when you need to decide where a doc belongs before opening a pull request.

Where docs live

Documentation	Source of truth	Published path
Core CMS concepts, install, admin, frontend, operations, performance, and reference docs	capell-app/capell/docs/**	/core/** and selected top-level routes
Core package docs for core, admin, frontend, installer, and marketplace	capell-app/capell/packages/<package>/README.md and docs/**	/packages/<package>/**
Add-on package docs	capell-app/packages/packages/<package>/README.md and docs/**	/packages/<package>/**
Docs site shell, homepage, package shelf, docs source page, navigation, styles, and sync logic	capell-app/capell-docs	Site-wide

The sync intentionally excludes internal, specs, and superpowers directories from every public docs level. Keep agent plans, implementation notes, and draft specs out of published docs.

Add or change a doc

1. Add product or package docs beside the code they describe.
2. Use README.md for the package landing page and docs/** for deeper guides.
3. Keep package metadata current in capell.json; the package shelf reads product group, tier, runtime contexts, source path, and package name from it.
4. Run the local sync before reviewing navigation or generated pages:

npm run sync:local

For docs-only changes in this repository, run the normal build check:

npm run build

Local sync paths

Local package documentation work expects sibling source checkouts:

Command	Source refreshed
npm run sync:local	Core and package source docs
npm run sync:local:core	../capell-4
npm run sync:local:packages	../capell-4/packages

Generated files under src/content/docs/** can change after a sync. Review those diffs, but make durable source-doc edits in the source repository unless the page is owned by capell-docs.

Publishing model

The docs deploy from GitHub Actions. A push to capell-docs/main builds and deploys the site. Source repositories trigger the same workflow through repository_dispatch when public docs paths change.

The deploy builds static files into dist/, then syncs the finished build to the live docs directory. A failed deploy leaves the previous static site in place until the next successful run.

Docs Source And Sync Detailed source mapping, local sync commands, and public exclusion rules.

Package Shelf Generated package index from manifests and package documentation.

Docs Map Source-owned map of Capell core documentation.