SEO Suite — Improvement & Growth Plan

Package: capell-app/seo-suite · Kind: package · Tier: premium · Product group: Capell Search & SEO · Bundle: search-seo · Status: Draft

1. Snapshot

SEO Suite is the premium search/SEO package for the Capell CMS. It bolts metadata panels, schema.org structured data, broken-link tracking, Google Search Console insights, PageSpeed audits, AI-assisted content/metadata generation (via Prism), and an “AI Discovery” surface (llms.txt, llms-full.txt, per-page Markdown, AI-crawler robots.txt) onto core pages and sites. Domain logic is correctly concentrated in ~90 Actions under src/Actions, with admin pages/widgets/extenders delegating to them, Data objects at boundaries, and public Blade/controllers driven by view composers and cached responses.

Surfaces: admin, frontend, console (manifest surfaces).
Key Actions: BuildPageSeoReportAction, CalculateSeoScoreAction, SuggestInternalLinksAction, BuildSeoSuiteDoctorReportAction, GenerateLlmsTxtAction, BuildRobotsTxtAction, RunPageSpeedAuditAction, SyncSearchConsoleInsightsAction, ResolvePageStructuredDataAction, SchemaGraphAction.
Models/tables (13 required): broken_links, page_seo_snapshots, page_speed_audit_runs, page_speed_audit_results, search_console_url_metrics, search_console_query_metrics, ai_generation_histories, ai_creator_contexts, ai_creator_sessions, ai_discovery_site_profiles, ai_discovery_page_profiles, ai_discovery_crawler_rules, ai_discovery_snapshots.
Dependencies — requires: capell-app/admin, capell-app/frontend, capell-app/insights, capell-app/site-discovery, plus prism-php/prism ^0.100. supports: capell-app/blog, capell-app/publishing-studio, capell-app/url-manager. conflicts: none.
Marketplace summary: “Ship search-ready pages by default: live SEO scoring, schema.org structured data, broken-link and redirect management, Google Search Console insights, and first-class AI-discovery output (llms.txt, page Markdown, AI-crawler controls) — all inside the Capell page editor.”
Screenshots in manifest: 14 runner-backed light/dark admin PNGs are promoted from docs/screenshots/: page SEO panel, SEO audit, Search Console insights, broken links, AI Creator action, sitemap, and translation coverage.

2. Improvements (existing functionality)

Done/Shipped: the full SeoCheckKeyEnum set is wired into page reports. BuildPageSeoReportAction::enabledChecks() now covers all 15 enum cases and addTechnicalIssues() emits canonical, schema, image-alt, internal-link, broken-link, redirect, social-image, translation, sitemap, llms.txt, and Search Console issues or passed checks. Evidence: BuildPageSeoReportActionTest asserts every SEO check key is accounted for in report issues or passed checks, and translation labels/messages exist for every wired check. src/Actions/BuildPageSeoReportAction.php, src/Enums/SeoCheckKeyEnum.php, resources/lang/en/generic.php, tests/Integration/Actions/BuildPageSeoReportActionTest.php. Effort: L
Done/Shipped: SeoSuiteHealthCheck performs real keyed diagnostics. The manifest health keys now route to targeted diagnostics: page reports and broken links check storage plus service bindings, schema graph checks service bindings plus template registry, and AI Discovery checks storage, routes, services, and crawler policy. Evidence: SeoSuiteHealthCheckTest maps all four manifest keys and verifies unknown keys return no diagnostics. src/Health/SeoSuiteHealthCheck.php, tests/Feature/Health/SeoSuiteHealthCheckTest.php. Effort: M
Weight the SEO score instead of flat severity penalties. CalculateSeoScoreAction is 100 − Σ severity penalty (Critical 25 / Warning 10 / Notice 3). A page missing only canonical scores identically to one missing alt text; there is no per-check weight or category breakdown. Introduce check-category weights and return a structured breakdown (on-page / technical / structured-data / links) so the widget can show sub-scores. src/Actions/CalculateSeoScoreAction.php, src/Enums/SeoIssueSeverityEnum.php. Effort: M
Done/Shipped: public-output leak scanning covers Capell authoring/admin markers. PublicOutputLeakScanner now detects bounded admin/Filament URLs, authoring routes, Livewire internals, editor metadata keys, structured model/page/field identifiers, permission markers, and draft/unpublished flags while avoiding ordinary prose false positives. Evidence: unit coverage for marker detection/redaction/false positives plus doctor command coverage for generated output leak labels. src/Support/PublicOutputLeakScanner.php, tests/Unit/Support/PublicOutputLeakScannerTest.php, tests/Feature/Console/SeoSuiteDoctorCommandTest.php. Effort: M
Upgrade internal-link suggestions beyond ≥4-char token overlap. SuggestInternalLinksAction tokenises titles/content and scores by literal token intersection, capped at 5. The package already ships an AI/embedding stack (Prism, AiTokenCounter) yet links ignore it. Offer an optional embedding/semantic-similarity strategy and surface anchor-text suggestions, not just target pages. src/Actions/SuggestInternalLinksAction.php, src/Support/InternalLinks/InternalLinkCandidateRepository.php. Effort: L
Make defaultPageSpeedDigestRecipients() query-efficient. It calls $userModel::query()->get() and filters every user in PHP via hasRole/isGlobalAdmin. On a large user table this loads the whole table into memory each schedule resolve. Push the role filter into the query (whereHas('roles', …) / role scope). src/Providers/SeoSuiteServiceProvider.php (L849-868). Effort: S
Persist AI cost, not just tokens. RecordAiGenerationAction stores prompt_tokens/completion_tokens/total_tokens/duration but no monetary cost and no model-price table; PrismProvider::chat() logs token metrics at debug only. Buyers expect a spend dashboard. Add a cost column/derivation and roll it into AiUsageWidget. src/Actions/Ai/RecordAiGenerationAction.php, src/Support/PrismProvider.php. Effort: M
Scope the AI circuit breaker per provider/site. PrismProvider uses a single global cache key ai_circuit_breaker_state; one site’s provider outage trips AI generation for every site and provider. Key it by provider (and optionally site). src/Support/PrismProvider.php (CIRCUIT_BREAKER_KEY). Effort: S
Index the duplicate-title check. BuildPageSeoReportAction::duplicateTitleExists() runs whereHas('translations', … where 'meta->title' = ?), a JSON-path scan per audited page with no supporting index. At scale this is slow and runs inside the synchronous report. Consider a generated/indexed title column or a cached title set. src/Actions/BuildPageSeoReportAction.php. Effort: M
Surface crawler-preview reports in the admin UI. Both docs/overview.md (“Remaining Roadmap”) and the action BuildCrawlerPreviewReportAction exist, but the README still lists “Wire crawler-preview reports into the admin diagnostics UI” as outstanding — the report has no admin page/tab. src/Actions/BuildCrawlerPreviewReportAction.php, src/Filament/Pages/. Effort: M
Shipped 2026-06-08: consume media alt text in image schema. BuildPageImageSchemaAction now falls back to media alt metadata for the ImageObject description when no explicit image description exists, so Media AI-generated alt text and Media Library metadata feed SEO structured output. capell.json now declares media-library / media-ai supports plus seo-suite-media-metadata. src/Actions/BuildPageImageSchemaAction.php, tests/Unit/Actions/BuildPageImageSchemaActionTest.php. Effort: S

3. Missing Features (gaps)

On-page content analysis (H1 presence/uniqueness, heading order, word count, keyword in title/URL/first paragraph, keyword density, readability). Absent entirely — the audit never inspects rendered body content. Ties to capability seo-suite / seo-suite-structured-data-audit adjacency. Table-stakes (core Yoast/RankMath feature).
Focus-keyword workflow. There is a NormalizeTargetKeywordsAction and keyword plumbing into prompts, but no per-page “focus keyword + scored analysis” loop that the audit grades against. Table-stakes.
OG/Twitter card validation + live preview correctness. BuildSocialMetaAction/SocialMetaData build tags and the report has a socialPreview, but socialPreview.imageUrl is hard-coded null in BuildPageSeoReportAction, and there is no validation (missing OG image, wrong dimensions, missing twitter:card). Table-stakes.
Redirect manager UI. CreateRedirectForBrokenLinkAction and BuildRedirectOpportunityReportAction exist, but there is no first-class redirect CRUD/import surface (regex/410/bulk) — redirect creation is only a reaction to broken links. Table-stakes for an “SEO suite.”
XML sitemap ownership clarity / sitemap index + image/video/news sitemaps. Sitemaps are delegated to capell-app/site-discovery; SEO Suite only reports parity. Buyers expect the SEO product to own sitemap segmentation, priority, and submission. Differentiator if pulled in, otherwise document the boundary loudly.
AI-answer / GEO visibility tracking. The package writes llms.txt and AI-crawler rules but never measures whether the site is cited by ChatGPT/Perplexity/AI Overviews. Given the AI Discovery investment this is the natural premium differentiator.
Search Console: query→page opportunity surfacing (CTR/position striking-distance). Metrics are imported (search_console_query_metrics) and there are movement/decline actions, but no “position 11-20 striking-distance” or “high-impressions/low-CTR” opportunity report tied to the page editor. Differentiator.
Bulk metadata editing / CSV export-import of titles & descriptions. AI suggests them one page at a time; there is no grid bulk-edit or import. Table-stakes at premium tier.
User-level authorization for AI generation. AiCreatorPolicy only answers “is the feature enabled for this site” — there is no per-user gate on who may spend AI budget. Table-stakes (cost-control / security).
Scheduled site-wide re-crawl / broken-link sweep. Broken links are recorded reactively via UrlVisitFailed; there is no scheduled crawler that proactively re-checks known URLs. Table-stakes.

4. Issues / Risks

Done/Shipped: AI Discovery public-output safety is covered for anonymous and non-admin users. GenerateLlmsTxtActionTest now reuses PublicOutputLeakScanner for the existing anonymous output test and adds signed-in non-admin coverage for /llms.txt, /index.md, and /robots.txt, asserting generated content contains no admin/editor leak labels. Broader leak scanner strengthening remains a separate Now row. tests/Integration/AiDiscovery/GenerateLlmsTxtActionTest.php, src/Support/PublicOutputLeakScanner.php.
Done/Shipped: manifest cache-safety metadata now reflects generated AI Discovery output. capell.json declares cacheable: true, variesBy: ["site", "locale"], and invalidation sources for Page, AiDiscoverySiteProfile, AiDiscoveryPageProfile, and AiDiscoveryCrawlerRule saves/deletes, matching the cached llms.txt/Markdown/robots output contract. capell.json (performance.cacheSafety), src/Http/Controllers/*, src/Providers/SeoSuiteServiceProvider.php.
frontendRenderBudgetMs: 20 is at risk for schema rendering. WebsiteSchemaComposer/SchemaComponentComposer run during frontend render and call SiteMetaSchemaAction/PageMetaSchemaAction/BreadcrumbsSchemaAction synchronously; BuildPageImageSchemaAction triggers loadMissing(['image','media']) via registerFrontendContextHydration. With multiple schema components on a page, hitting a 20 ms budget without view caching is optimistic. Add a render benchmark/guard. src/View/Composers/, src/Actions/SiteMetaSchemaAction.php, capell.json (performance).
Done/Shipped: manifest settings, permissions, PageSpeed, and shipped admin surfaces are declared. capell.json lists AIOrchestratorSettings and SeoSuiteSettings, page/settings/AI permissions, Search Rankings and Translation Coverage admin-page contributions, AI Discovery routes, supported Blog/Publishing Studio/URL Manager integrations, and PageSpeed audit/digest capabilities. Marketplace/automation can now read the shipped SEO Suite surface area from the manifest. capell.json.
Empty CHANGELOG. CHANGELOG.md has only a placeholder “Prepared package metadata…” line. A premium first-party paid package with priority support needs real release notes. CHANGELOG.md.
Docs drift. docs/overview.md lists migrations dated 2026_04_18_* and omits RobotsTxtController in one place / PageSpeed tables; actual migrations are 2026_05_10_* and 2026_05_29_*. docs/overview.md.
i18n completeness unverified for new strings. Only resources/lang/en/ exists. Every new check label, doctor message, and PageSpeed/notification string must resolve via __() keys (capell-seo-suite::generic.seo_check_*); there is no second locale to prove keys exist and no test asserting all SeoCheckKeyEnum labels have translations. resources/lang/en/*, src/Enums/SeoCheckKeyEnum.php.
AI robustness edge: token-usage assumption. PrismProvider::chat() reads $response->usage->promptTokens + completionTokens and $response->usage unconditionally for the debug log; a provider returning null usage (some Prism providers / Ollama) would throw inside the success path after a successful generation. Guard usage access. src/Support/PrismProvider.php.
Done/Shipped: keyed SEO Suite health diagnostics. SeoSuiteHealthCheck now exposes the full diagnostic set plus key-specific checks for the four manifest health rows, avoiding one generic dashboard result for every SEO surface. src/Health/SeoSuiteHealthCheck.php, tests/Feature/Health/SeoSuiteHealthCheckTest.php.

5. Marketplace & Selling

Critique of current copy. The capell.json marketplace summary and composer description diverge. Composer says “SEO tools for Capell (metadata panels, structured data, social meta, AI ai-orchestrator)” — note the literal, unpolished token “AI ai-orchestrator”, which also leaks into the config prompt strings (“You are a helpful ai-orchestrator…”). The manifest summary is a flat, comma-spliced feature list (“adds X, Y, Z, and diagnostics”) with no benefit, no audience, and no hook — it reads like a changelog, not a pitch.

Improved 1-sentence summary:

Ship search-ready pages by default: live SEO scoring, schema.org structured data, broken-link and redirect management, Google Search Console insights, and first-class AI-discovery output (llms.txt, page Markdown, AI-crawler controls) — all inside the Capell page editor.

Improved 3–4 sentence listing description:

SEO Suite turns Capell into a search-and-AI optimisation platform. Editors get an in-context SEO panel that scores every page, previews Google and social results, and suggests internal links and metadata with optional AI assistance, while operators get broken-link tracking, redirect opportunities, Search Console dashboards, and PageSpeed audits. It is the only Capell package built for the AI-search era: generate and govern llms.txt, llms-full.txt, and per-page Markdown, and control exactly which AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot) may train on or surface your content. A built-in doctor verifies route ownership, content types, cache headers, sitemap parity, and public-output safety so generated SEO output never leaks admin internals.

Screenshot/media gaps. The marketplace block now promotes 14 committed Capell runner PNGs for page SEO, audit, Search Console, broken links, AI Creator, sitemap, and translation coverage. Remaining high-converting captures require runner fixture depth rather than metadata edits: AI Discovery profiles, SEO settings, not-found URL data from Insights, public llms.txt/robots.txt/Markdown plain-text output, an animated GIF of the AI metadata-suggestion flow, a before/after SEO-score shot, and the AI-crawler policy toggle screen.

Pricing/tier/bundle positioning. premium + search-seo bundle + paid/first-party/priority/private-docs is appropriate — this is a deep, schema-owning, AI-integrated package, not an add-on. Manifest supports now explicitly name capell-app/blog, capell-app/publishing-studio, capell-app/url-manager, capell-app/media-library, and capell-app/media-ai, matching shipped article schema, publish gates, redirect opportunities, and media metadata consumers. Position AI Discovery + Search Console as the upsell hook over a hypothetical free/basic metadata tier, and bundle naturally with an Insights/Analytics Extension Suite.

Top differentiators / value props. (1) AI-search/GEO readiness as a native, governed feature — rare in CMS SEO plugins. (2) Public-output safety doctor — a trust feature no Yoast competitor markets. (3) One editor surface spanning metadata, schema, links, Search Console, and PageSpeed. Target buyer persona: the Capell agency/site-operator who manages multi-site, multi-language properties and is being asked by clients “are we visible in ChatGPT/AI Overviews?”.

Suggested keywords/tags: seo, structured-data, schema.org, llms.txt, ai-seo, generative-engine-optimization, search-console, pagespeed, broken-links, redirects, meta-tags, open-graph.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref
Done/Shipped: Add anonymous/non-admin public-output safety tests for `/llms.txt`, `/index.md`, `/robots.txt`. Evidence: `GenerateLlmsTxtActionTest` covers anonymous and signed-in non-admin AI Discovery output through `PublicOutputLeakScanner`.	Done	M	High	§4
Done/Shipped: Wire up the 11 dormant `SeoCheckKeyEnum` checks (canonical, schema, alt, links…). Evidence: `BuildPageSeoReportAction` covers all 15 enum cases and integration coverage asserts every key appears in issues or passed checks.	Done	L	High	§2
Done/Shipped: Make `SeoSuiteHealthCheck` perform real per-key probes. Evidence: `SeoSuiteHealthCheckTest` covers manifest key mapping for page report, schema graph, broken links, and AI Discovery.	Done	M	High	§2/§4
Done/Shipped: Strengthen `leakMatches()` beyond `signature=`/`expires=`. Evidence: scanner tests cover authoring/admin/Livewire/editor/model/page/draft markers plus false-positive-safe public prose.	Done	M	High	§2/§4
Shipped 2026-06-05: Correct manifest `cacheSafety`, `permissions`, `settings`, PageSpeed capabilities	Done	S	Med	§4
Fix `defaultPageSpeedDigestRecipients()` to filter in-query	Done	S	Med	§2 — Done 2026-06-04: role filtering now stays in the recipient query with focused coverage.
Done/Shipped: Scope AI circuit breaker per provider; guard null Prism usage. Evidence: `PrismProviderAndCacheTest` covers provider-isolated breaker state and missing Prism usage on the chat success path.	Done	S	Med	§2/§4
Done/Shipped 2026-06-08: Weighted SEO score with category breakdown. Evidence: `CalculateSeoScoreActionTest` covers category weighting and bounded scores, and the page SEO panel renders breakdown data.	Done	M	High	§2
Done/Shipped 2026-06-08: On-page content analysis (H1, headings, word count, keyword density). Evidence: `AnalyzePageContentActionTest` covers heading order, H1 count, word count, and keyword density inputs.	Done	L	High	§3
Done/Shipped 2026-06-08: Focus-keyword workflow graded by the audit. Evidence: `BuildPageSeoReportActionTest` proves missing H1, heading order, and focus keyword issues enter the report and score breakdown.	Done	M	High	§3
Done/Shipped 2026-06-08: Redirect manager UI (bulk/regex/410). Evidence: URL Manager now imports empty-target 410 rows, resolves managed 410 rules separately from redirects, and registers middleware before 404 capture.	Done	L	High	§3
Done/Shipped 2026-06-08: User-level AI-generation authorization + cost persistence/dashboard. Evidence: lifecycle, pipeline, policy, and AI metrics tests cover permission checks, cost recording, and dashboard spend totals.	Done	M	Med	§2/§3
Recapture SEO Suite workflow screenshots before promotion; generic dashboard/settings and duplicate Site Health captures were demoted. Deferred until styled runner recapture is available; not an implementation blocker.	Later	S	Med	§5
Done/Shipped: Promote real screenshots + rewrite marketplace summary/description. Evidence: `capell.json` and Composer copy now share the search-ready summary, and marketplace media promotes 14 committed Capell runner PNGs.	Done	S	High	§5
Shipped 2026-06-08: Consume Media Library / Media AI image metadata in schema output	Done	S	Med	§2/§5
Embedding/semantic internal-link + anchor-text suggestions	Later	L	Med	§2/§3
AI-answer/GEO visibility tracking (ChatGPT/Perplexity/AI Overviews citations)	Later	L	High	§3
Search Console striking-distance opportunity report in editor	Later	M	Med	§3