# Docs Map

Use this page as the route map. The docs are intentionally small: each page should answer a busy developer's next question without sending them through a chain of fragments.

## Start Here

| Job                              | Read                                                                    |
| -------------------------------- | ----------------------------------------------------------------------- |
| Try Capell quickly               | [Quickstart](getting-started/quickstart.md)                             |
| Pick the right install path      | [Install matrix](getting-started/install-matrix.md)                     |
| Decide whether Capell fits       | [Why Capell](getting-started/why-capell.md)                             |
| See interactive page experiences | [Capell Interactions](getting-started/capell-interactions.md)           |
| Understand the AI-ready path     | [AI-ready Capell](getting-started/ai-ready.md)                          |
| Learn the core concepts in order | [Capell Learn](getting-started/capell-learn.md)                         |
| Install it in a real Laravel app | [Install guide](getting-started/install.md)                             |
| Understand the model             | [How Capell works](getting-started/how-capell-works.md)                 |
| Use the admin panel              | [Admin](admin/index.md)                                                 |
| Work on public rendering         | [Frontend](frontend/index.md)                                           |
| Build or maintain an extension   | [Packages](packages/README.md)                                          |
| Build an extension from scratch  | [Build an extension end to end](packages/build-extension-end-to-end.md) |
| Decide where a feature belongs   | [Host, package, or app code](development/package-boundaries.md)         |
| Work in this repo                | [Development](development/index.md)                                     |
| Debug production behavior        | [Operations](operations/index.md)                                       |
| See a realistic content model    | [Music store CMS example](examples/music-store-cms.md)                  |

## Main Docs

| Page                                 | Covers                                                                                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| [Admin](admin/index.md)              | Filament resources, settings, users, media, recovery shell, dashboard widgets, admin extension points.                                 |
| [Frontend](frontend/index.md)        | Site/page resolution, public HTML safety, media output, render hooks, Tailwind assets, server rules, frontend tests.                   |
| [Packages](packages/README.md)       | Package shape, manifests, service providers, extension points, Actions/Data/settings, admin/frontend contributions, migrations, tests. |
| [Performance](performance/README.md) | Page cache, fragment cache, model URL cache, ETags, critical assets, lazy hydration.                                                   |
| [Operations](operations/index.md)    | Site Health, Lockdown, upgrades, Marketplace connection, install/admin/frontend troubleshooting.                                       |
| [Development](development/index.md)  | Local repo shape, commands, configuration, seeders, diagnostics, settings migrations.                                                  |
| [Reference](reference/index.md)      | Glossary, ERD, credits, package catalogue.                                                                                             |

## Common Decisions

| Question                                                 | Read                                                                       |
| -------------------------------------------------------- | -------------------------------------------------------------------------- |
| Which install path should I use?                         | [Install matrix](getting-started/install-matrix.md)                        |
| Does this belong in the host repo, a package, or an app? | [Host, package, or app code](development/package-boundaries.md)            |
| Which extension point should a package use?              | [Extension point chooser](packages/extension-point-chooser.md)             |
| What exact contract/tag/test should I use?               | [Extension point API reference](packages/extension-point-api-reference.md) |
| Why is my package contribution missing?                  | [Extension troubleshooting](packages/extension-troubleshooting.md)         |
| What can public HTML expose?                             | [Public HTML safety contract](frontend/public-html-safety.md)              |
| How do lazy widgets and fragments work?                  | [Capell Interactions](getting-started/capell-interactions.md)              |
| Which patterns are forbidden?                            | [Do not do this](development/do-not-do-this.md)                            |
| Where should a new doc go?                               | [Docs ownership rules](development/docs-ownership.md)                      |

## URL Preservation

Treat published URLs as durable. When replacing, moving, or rebuilding an old page, keep the new page clean and preserve the old address with a Page URL whose type is **Redirect**. The redirect record owns the legacy source path and points it at the current page URL, so visitors, bookmarks, inbound links, and search engines still reach the right content without keeping a duplicate page around.

Capell also creates automatic redirect Page URLs when a published page URL changes because a slug or parent path changed. Add a manual redirect when you are creating a new page to replace an existing URL, consolidating old content, or importing legacy routes from another CMS.

For the detailed model, read [Page management: URL history and redirects](../packages/core/docs/page-management.md#url-history-and-redirects).

## Host Packages

| Package     | Composer name            | Package doc                                                      |
| ----------- | ------------------------ | ---------------------------------------------------------------- |
| Core        | `capell-app/core`        | [Core overview](../packages/core/docs/overview.md)               |
| Admin       | `capell-app/admin`       | [Admin overview](../packages/admin/docs/overview.md)             |
| Frontend    | `capell-app/frontend`    | [Frontend overview](../packages/frontend/docs/overview.md)       |
| Installer   | `capell-app/installer`   | [Installer overview](../packages/installer/docs/overview.md)     |
| Marketplace | `capell-app/marketplace` | [Marketplace overview](../packages/marketplace/docs/overview.md) |

First-party add-ons live in the sibling `../capell-packages-4` repository for local development. Use [Approved packages](packages/catalog.md) for the current package catalogue.

## Rules For New Docs

- Update an existing page before adding a new file.
- Link every new doc from this page, a section index, a package overview, or another doc.
- Put historical plans outside the public docs tree.
- Do not keep "moved" stubs unless a published URL needs a temporary redirect.
- Keep extension-point examples beside the reader task that needs them.
- Do not document optional packages as built-in host behavior.
- Public frontend docs must preserve the safety rule: anonymous HTML must not expose authoring controls, model IDs, selectors, signed editor URLs, or package internals.