# Site Discovery

## Package docs status

This page is generated from public package documentation in `capell-4/packages` and the package manifest checked into the source repository.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/site-discovery` |
| Package slug | `site-discovery` |
| Product group | Capell Search & SEO |
| Tier | premium |
| Bundle | `search-seo` |
| Runtime contexts | `admin`, `frontend`, `console` |
| Capell version | `^4.0` |
| Source repository | `capell-app/packages` |
| Source path | `packages/site-discovery` |
| Docs source | `packages/site-discovery/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/4.x/packages/site-discovery/capell.json) |

Site Discovery owns public sitemap and discoverability output for Capell sites.

## At A Glance

- Package: `capell-app/site-discovery`
- Namespace: `Capell\SiteDiscovery\`
- Surfaces: admin actions/tools, frontend sitemap pages, console
- Service providers: `packages/site-discovery/src/Providers/SiteDiscoveryServiceProvider.php`
- Capell dependencies: `capell-app/admin`, `capell-app/core`, `capell-app/frontend`
- Third-party dependencies: `icamys/php-sitemap-generator`

## Why It Helps Your Capell Workflow

- Resolves public discoverable pages and URLs, then exposes HTML and XML sitemap outputs.
- Provides a discovery-output contract so packages can advertise public machine-readable outputs such as `llms.txt` without coupling Site Discovery to consumer packages.
- Provides a URL change notification contract so packages can submit public URL changes to IndexNow-style services without hard-coding providers into sitemap generation.
- Includes an optional IndexNow notifier, disabled by default until `capell-site-discovery.indexnow.enabled` and a key are configured.
- Helps owners and search tools find the pages Capell intends to publish without each package building its own crawler view.
- Gives developers a shared discovery surface that SEO Suite, Blog, Search, and audits can use consistently.

## Best Used With

- [SEO Suite](../seo-suite/README.md)
- [Search](../search/README.md)
- [Blog](../blog/README.md)

## What It Adds

- Public discoverable page and URL APIs.
- HTML sitemap page type and frontend component.
- XML sitemap generation with chunking and incremental state.
- Sitemap admin page, admin actions, and generation tool.
- Lifecycle listeners that regenerate sitemap output when pages or sites change.

## Built With

- [PHP Sitemap Generator](https://github.com/icamys/php-sitemap-generator) - XML sitemap generation.

## Code Map

| Area      | Path                                    | Purpose                                                             |
| --------- | --------------------------------------- | ------------------------------------------------------------------- |
| Actions   | `packages/site-discovery/src/Actions`   | Domain operations. Test these directly where possible.              |
| Data      | `packages/site-discovery/src/Data`      | Structured payloads, form state, view models, and integration data. |
| Enums     | `packages/site-discovery/src/Enums`     | Persisted states and Filament option values.                        |
| Filament  | `packages/site-discovery/src/Filament`  | Admin resources, pages, widgets, and settings UI.                   |
| Livewire  | `packages/site-discovery/src/Livewire`  | Interactive frontend or admin components.                           |
| Providers | `packages/site-discovery/src/Providers` | Registration, extension hooks, routes, migrations, and resources.   |
| Resources | `packages/site-discovery/resources`     | Views, translations, assets, and package resources.                 |
| Tests     | `packages/site-discovery/tests`         | Package-level Pest coverage.                                        |

## Runtime Surface

- Admin: Page and Site `Sitemap` actions, plus the sitemap generation tool.
- Frontend: `/sitemap` HTML sitemap and `/sitemap-xml` XML response.
- Livewire: `Sitemap`, `SitemapTool`.

## Commands

- `capell:xml-sitemap {--site= : Only regenerate sitemaps for this site ID} {--incremental : Skip domains whose pages have not changed since the last run}` (packages/site-discovery/src/Console/Commands/XmlSitemapCommand.php)

## Data And Persistence

- Data objects live in `src/Data/`; use them for payloads, form state, and view models.
- `PagesSitemap` caches serialized page arrays and rebuilds `SitemapPageData` objects when reading from cache. Do not cache the DTO objects directly; stale serialized objects can come back as `__PHP_Incomplete_Class` in host apps.

## Extension Points

- Contracts: `DiscoverableUrlSource`, `DiscoveryOutputSource`, `UrlChangeNotifier`, `Sitemapable`.
- IndexNow: enable `capell-site-discovery.indexnow.enabled` and set `capell-site-discovery.indexnow.key` to submit URL changes through the built-in notifier.
- Listeners: `RegenerateSitemapsOnPageDeleted`, `RegenerateSitemapsOnPageSaved`, `RegenerateSitemapsOnSiteCreated`.
- Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

## Install And Setup

- Install with `composer require capell-app/site-discovery` in the host Capell application.
- The core install flow can create the default Sitemap page when this package is installed before `capell:install`.
- When adding the package to an existing core-only app, create the Sitemap page for each existing site before testing `/sitemap`; the current extension install flow does not backfill existing sites automatically.
- In this repository, verify package changes with `vendor/bin/pest`; do not use `php artisan`.

## Docs

- [docs index](README.md)
- [overview.md](overview.md)
- [screenshots.json](screenshots.json)

## Screenshot Coverage

The package screenshot contract covers the package-added Page and Site sitemap actions, the sitemap generation tool, `/sitemap`, and `/sitemap-xml`. Keep each capture focused on the added surface; avoid broad admin screenshots that hide which control belongs to this package.

Public sitemap screenshots should be checked for authoring or package identifiers. The public output must not expose `capell-site-discovery`, `capell-sitemap`, admin URLs, editor metadata, signed editor links, or unpublished pages.

## Testing

Run package tests from the repository root:

```bash
vendor/bin/pest packages/site-discovery/tests --configuration=phpunit.xml
```

## Maintenance Notes

- Put behaviour changes in `src/Actions/`; UI classes, commands, and controllers should call actions instead of owning domain logic.
- Use package `Data` classes at boundaries instead of passing anonymous arrays between layers.
- Use backed enums for persisted values and enum labels for Filament options.