# Overview

Status: **Available, no schema impact** · Kind: **package** · Tier: **premium** · Bundle: **search-seo** · Contexts: **admin, frontend, console** · Product group: **Capell Search & SEO**

Site Discovery resolves public Capell URLs and exposes them through HTML sitemap rendering and XML sitemap generation.

## What This Package Adds

- Discoverable URL data and source contracts.
- Discovery output data and source contracts for public machine-readable outputs such as `llms.txt`.
- URL change notification contracts for IndexNow-style submission services.
- Optional built-in IndexNow notifier, disabled until configured with an IndexNow key.
- HTML sitemap page renderables and Livewire components.
- XML sitemap generation with chunking and incremental state tracking.
- Site and Page admin actions for sitemap access/generation.
- Lifecycle listeners that regenerate sitemap output when pages or sites change.

## Install And Demo Setup

Install the package in a host Capell app:

```bash
composer require capell-app/site-discovery
```

No package-owned migrations are declared. Seed at least one site, language, homepage, and child page before capturing sitemap screenshots.

The default Capell install flow can create the Sitemap page when Site Discovery is present during install. If the package is added to an existing core-only app, create the Sitemap page for each existing site before capturing or testing `/sitemap`; the current extension install flow does not backfill that page automatically.

## Admin Surfaces

- Page resource header action: `Sitemap`.
- Site resource header action: `Sitemap`.
- Site resource record action: `Sitemap`.
- Sitemap generation Livewire tool.

The package does not register a standalone Filament resource or navigation page.

## Frontend Surfaces

- HTML sitemap renderable page and `Sitemap` Livewire component.
- `/sitemap` HTML sitemap page.
- `/sitemap-xml` XML sitemap endpoint backed by files generated by the `capell:xml-sitemap` command.
- Public URL discovery used by downstream SEO and AI-discovery packages.

## Screenshot Plan

- `page-sitemap-action.png`: Page resource `Sitemap` action.
- `site-sitemap-action.png`: Site resource row action dropdown with `Sitemap`.
- `sitemap-generation-tool.png`: dashboard tools dropdown with `Update sitemaps`.
- `html-sitemap-page.png`: public `/sitemap` output.
- `xml-sitemap-output.png`: `/sitemap-xml` output after `capell:xml-sitemap`.

Captured files live in the host app under `public/docs/screenshots/packages/site-discovery`.

## Public Safety Notes

Public sitemap output should include only discoverable public URLs and labels. It must not expose unpublished pages, draft workspace URLs, admin URLs, model IDs, authoring metadata, or package-identifying CSS/component aliases.

The screenshot pass checked `/sitemap` and `/sitemap-xml` for `admin`, `filament`, `editor`, `signed`, `capell-site-discovery`, and `capell-sitemap`. The public HTML sitemap still uses the public Livewire runtime because the page is rendered by the package Livewire component; that runtime is not an authoring surface.

## Findings From The Demo Pass

- `PagesSitemap` stores plain array payloads in cache and rebuilds `SitemapPageData` objects on read. This avoids cached `__PHP_Incomplete_Class` values breaking `/sitemap`.
- Public sitemap Blade classes and the registered page component alias avoid package-identifying `capell-site-discovery` and `capell-sitemap` strings.
- The generated XML route is `/sitemap-xml`, not `/sitemap.xml`.
- Feature gap: add a post-install setup action that backfills Sitemap pages for existing sites when the package is installed after the core app.

## Verification

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