# 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:

```bash
npm run sync:local
```

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

```bash
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](https://docs.capell.app/docs-source/)
  [Package Shelf](https://docs.capell.app/packages/)
  [Docs Map](https://docs.capell.app/core/docs-map/)