# Overview.Admin ## What it does for you SEO Suite adds live page-level SEO checks, stored audit snapshots, metadata and crawler controls, broken-link observations, translation coverage, Search Console rankings, PageSpeed audits, and public AI-discovery output. These features have separate data sources and lifecycles: the Monitoring reports are not all crawlers, and an empty report does not always mean that no problem exists. ## Your screens - **Monitoring > SEO Audit** lists stored page snapshots, including score, issue counts, schema state, and search preview. **Not scanned** means no snapshot has been stored for that page and language. - **Broken links** lists failed outbound URL visits that were reported with a source page. - **Not found** currently groups site-scoped Insights page-view events by full URL. It does not check the response status and is not proof that a URL returned 404. - **AI Discovery** manages page inclusion, summaries, sections, priority, Markdown overrides, and readiness warnings for the public AI-discovery files. - **AEO observations** run in the queue and record bounded evidence from the real public routes. Current-output evidence and signed publish-regeneration evidence are separate states; **Not observed** is not a passing result. - **Translation coverage** compares each page's translations with the languages assigned to its site. - **Search rankings** shows the latest stored Google Search Console query and page metrics. - A page's **SEO settings** tab provides live checks, metadata and previews, canonical and robots controls, AI Discovery fields, and the AI content brief. - The extension's **SEO settings** surface controls audit switches, strict metadata authoring, AI Discovery defaults and crawler policy, and PageSpeed scheduling. All of the Monitoring tables are scoped to sites the current operator can access. Their page permissions are `View:SeoAuditPage`, `View:BrokenLinksPage`, `View:NotFoundUrlsPage`, `View:AiDiscoveryPage`, `View:TranslationCoveragePage`, and `View:SearchRankingsPage`. The manifest declares `Manage:BrokenLinks`, `Manage:NotFoundUrls`, `Manage:AiDiscovery`, and `Manage:SeoSuiteSettings`, but the current table and extension-settings actions do not separately check those permissions. A user who can view the relevant report can currently open the redirect workflow, delete requested-URL events, or change AI Discovery profiles; a user who can reach the Extensions management surface can save SEO Suite settings. Restrict those parent surfaces to operators trusted with the available actions until action-level checks are tightened. ## Install and diagnose it Install the required Admin, AI Orchestrator, Core, Frontend, Insights, and Site Discovery packages first. Run `capell:seo-suite-install` through the application's normal deployment process. It publishes the package migrations, runs all pending application migrations, and seeds the default global AI-crawler rules; it has no package rollback step, so use the same backup and migration controls as any other production database deployment. `capell:seo-suite-setup` only reseeds the default global crawler rules. It does not publish or run migrations. Run `capell:seo-suite-doctor --base-url=https://your-enabled-domain.example` after setup or a web-server change to check package status, route ownership, AI Discovery coverage, crawler output, caching headers, and obvious public-output leaks. The HTTP check only accepts an enabled registered site domain; use `--skip-http` when only the local installation checks are appropriate. The public `.txt` and `.md` routes must reach Laravel. Add explicit web-server exceptions when a generic static-file rule would intercept `/robots.txt`, `/llms.txt`, `/llms-full.txt`, `/index.md`, or page URLs ending in `.md`. Keep the scheduler and a queue worker running for `capell:seo-suite:aeo-observations`. Core builds with correlated publication events (Core commit `d4c5be65c` or its eventual release) can produce signed before/after publish proof. Older released Core builds remain compatible but record current-output audits only, with publish regeneration left **Not observed**. ## Page checks and authoring gates The SEO settings tab computes a live report for the saved page and selected language. Review its metadata, schema, canonical, robots, links, translation coverage, search preview, and Search Console observations before publishing. The separate SEO Audit table reads stored snapshots; the package does not register a command or schedule that refreshes every site's SEO snapshots. Opening the live page report does not itself guarantee that the snapshot table has been refreshed, so treat **Not scanned** or **stale** as missing evidence rather than a clean result. Strict authoring is off by default. When enabled globally or for a page blueprint, its validator runs during page creation and editing, not only at publish time. A blocker prevents the create or save operation; a warning notifies the editor and allows it. The current validator checks only: - whether a meta title is present when that check is not ignored; - whether a meta description is present and inside the configured length range; and - optionally, whether the page title appears in the meta description. The settings screen also exposes modes for social image, canonical, robots, and schema checks, but the current authoring validator does not evaluate those modes. Continue to review those items in the live SEO report and any Publishing Studio report; do not rely on them to block a save. ## Broken links and requested URLs **Broken links** is populated only when Capell receives a failed URL-visit event with a source page ID. It stores the page, target URL, last observed HTTP status, and last checked time, and displays records whose status is 400 or higher. There is no package crawler, scheduled recheck, or automatic resolution. A row changes only when another failure is reported for the same page and target. When URL Manager's Redirects feature is available, **Redirect** opens its create form with the failed target's path, site, language, and a permanent status prefilled. It does not create the redirect. Choose and verify the destination, check for loops or over-broad paths, then save through the Redirects workflow. Despite its label, **Not found** currently includes every recorded Insights page-view URL in the operator's site scope; it does not filter on HTTP status or missing-page metadata. Verify the URL really returns 404 before treating it as a redirect candidate. Its bulk delete action permanently deletes all matching underlying page-view events for the selected full URLs, which changes Insights history and visitor counts. Export or investigate the evidence first, and do not use deletion as a redirect or remediation step. ## Search Console rankings Search rankings are not fetched when the page is opened. Configure a Google service-account credentials file and readonly property access with: - `CAPELL_SEO_TOOLS_SEARCH_CONSOLE_ENABLED=true`; - `CAPELL_SEO_TOOLS_SEARCH_CONSOLE_CREDENTIALS=/secure/path/credentials.json`; and - optionally, `CAPELL_SEO_TOOLS_SEARCH_CONSOLE_PROPERTY_URL` and `CAPELL_SEO_TOOLS_SEARCH_CONSOLE_TIMEOUT`. A configured property URL is used for every site. Without it, each site uses its default, or first, domain URL. Run `capell:seo-suite-sync-search-console`, optionally with `--site=` and `--limit=`, from your own maintenance schedule. SEO Suite does not register this sync with Laravel's scheduler. Each sync requests the 28 days ending yesterday and the preceding 28-day comparison, then stores page and query metrics. Search queries and full URLs are retained in plaintext alongside their hashes, so they can contain personal or confidential terms. Limit ranking access accordingly and avoid sensitive data in public URLs. The Search Console client converts authentication, network, and API failures into empty results, and the command exits successfully when it is unconfigured or when zero rows are returned. An empty Rankings screen therefore does not prove there was no search traffic. Check the credentials file, property selection, service-account access, network access, command output, and stored window dates before accepting an empty result. ## PageSpeed audits Set `CAPELL_SEO_SUITE_PAGESPEED_ENABLED=true` and provide `CAPELL_SEO_SUITE_PAGESPEED_API_KEY`. The page-list actions queue mobile or desktop audits, so a queue worker must be running. Those jobs use the host worker's retry policy; they do not declare package-specific attempts or backoff. Each Google request has a 90-second default timeout and two short HTTP retries. For maintenance runs, use `capell:seo-suite:pagespeed-audit` with optional `--site`, `--language`, `--page`, `--strategy=mobile|desktop|both`, and `--limit` filters. The weekly Monday 06:00 run is registered only when the settings table exists, the API client is enabled with a key, and both **PageSpeed audits** and **Weekly digest** are enabled. Keep Laravel's scheduler running; the task uses one server and prevents overlapping runs. Failures are stored per URL and strategy, and a mixed run is marked as succeeded with errors. The command still exits successfully after API-result failures, so check the saved run/result statuses and failure count rather than the process exit code alone. Digest delivery is attempted only for a run that did not fail completely and uses the configured SEO Suite PageSpeed notification group. ## AI Discovery and public content Site-language AI Discovery controls appear while editing the site's translation. New profiles enable `llms.txt` and page Markdown by default, leave `llms-full.txt` and Markdown content negotiation disabled, include public pages by default, and cache output for one hour. The global default affects profiles when they are first created; it does not rewrite existing site-language choices. Only published, accessible, sitemap-visible pages with an enabled URL can be exposed. Hidden and `noindex` pages are rejected even if their AI profile says **Include**. The AI Discovery table lets trusted operators include or exclude pages, record an exclusion reason, derive a summary from existing page metadata, and preview or override Markdown. **Fill summary** is deterministic and uses existing page data; it does not call an AI provider. The public output can include page titles, summaries, canonical URLs, and rendered portable content. A Markdown override is returned as public content exactly as saved. Never put drafts, personal information, secrets, admin links, signed URLs, or internal notes in an intro, summary, or Markdown override. Preview the public endpoints anonymously after every material configuration change. `llms-full.txt` generation is queued by default. Keep its configured queue worker running. A unique regeneration job tries twice, times out after 120 seconds, and backs off for 5 then 30 seconds. On a cold cache the endpoint returns 503 with `Retry-After: 5` until content exists; while regeneration is queued it can serve the retained stale copy with `X-Generation-State: queued`. Disable queued generation only if the application is prepared to build the full response synchronously. AI crawler presets are applied when rules are seeded during install, site creation, or `capell:seo-suite-setup`. Saving a different crawler-policy setting does not update existing rows by itself. Rerunning setup updates matching seeded rows and re-enables them, so it can overwrite manual changes for the same provider, user agent, and path. Review the global and site-specific rule precedence, then request `/robots.txt` to confirm the deployed result. ## AI generation and data handling The read-only **AI content brief** sends the saved page's extracted content, metadata, SEO report, site, and language context to the configured AI provider and stores the prompt context, response, model, token counts, and provider metadata in encrypted AI generation history. It does not write its suggestions back to the page. The action itself does not check `Use:AiCreator`, so page edit access must be limited to people trusted to send page content to the provider. The separate **AI Creator** action on page and site records requires the AI Orchestrator feature to be enabled and the user to have `Use:AiCreator`. It rate-limits generation, stores the site's tone, industry, audience, brand notes, the user's intent, and proposed layout in creator context/session records, and submits only the current user's reviewed session for the current site. Those context and session fields are not encrypted by SEO Suite. Do not enter personal data, credentials, unpublished commercial information, or other secrets in AI prompts or brand notes, and review every generated layout before submitting it. ## Retention and recovery Keep Laravel's scheduler running for the daily `capell:seo-suite:prune` task. It removes AI Discovery snapshots, SEO snapshots, completed PageSpeed runs and their results, and Search Console URL/query metrics older than 365 days by default. It does not prune AI Creator contexts, sessions, generation history, broken-link rows, or the Insights events shown on Not found. Use `capell:seo-suite:refresh-ai-discovery-markdown --limit=` when Diagnostics reports included profiles with no stored generated Markdown. It processes profiles whose generated content or generation timestamp is missing; it is not a general age-based refresh. After recovery, rerun the doctor command and verify the public output and response headers from the real site domain.