Demo Kit — Improvement & Growth Plan

Package: capell-app/demo-kit · Kind: package · Tier: free · Product group: Capell Foundation · Bundle: foundation · Status: Draft

1. Snapshot

Demo Kit is the demo-seeding engine for the Capell package suite. It is a tooling/dev package, not a marketplace seller: it provisions demo users, languages, sites, pages, media, and a curated Foundation showcase homepage so package demos, sales reviews, screenshots, and QA all start from known data. Orchestration is layered: FullDemoCommand (capell:demo-kit-full-demo) builds a deterministic plan via BuildDemoGenerationPlanAction, calls capell:admin-demo to seed core/admin data through DemoCreator/AdminDemoCommand, then calls capell:demo to fan out to each installed package’s own demo command (src/Console/Commands/FullDemoCommand.php). Per-package registration is manifest-driven: each package declares commands.demo in its capell.json, and FullDemoCommand::demoPackageNames() discovers them via CapellCore::getInstalledPackages() + PackageData::getDemoCommand() (lines 203-223). Surfaces: admin + frontend; deps: capell-app/admin, capell-app/core, capell-app/frontend, plus fakerphp/faker. No migrations, no settings, no permissions, no declared capabilities.

Current marketplace summary leads with Demo Kit as the deterministic demo engine for Capell. Composer description is aligned. marketplace.screenshots[] declares the extension card plus the committed light/dark Capell admin runner captures from docs/screenshots.json. The frontend widget PNGs remain committed runner evidence, but they are no longer promoted as buyer-facing screenshots after visual audit showed they render as bare default “Demo” pages rather than styled Capell product surfaces. The runner contract also includes one required-false consent priming capture so anonymous frontend screenshots do not include Insights consent chrome.

2. Improvements (existing functionality)

1. Forward the chosen author to package demos — FullDemoCommand passes '--user' => $this->option('user') !== null (a boolean) to capell:demo, whose signature is {--user} (a value-less flag). The real username is dropped, so package-contributed demo content (blog posts, etc.) is not attributed to the selected author even though capell:admin-demo is given the value correctly on the same run. Make capell:demo accept {--user=} and forward the string, consistent with admin-demo. — src/Console/Commands/FullDemoCommand.php:108, src/Console/Commands/DemoCommand.php (signature) — S

2. Forward --seed to package demos for true determinism — FullDemoCommand forwards --seed to capell:admin-demo (line 90) but not to the capell:demo package fan-out (lines 106-113). README states --seed “makes the generated plan repeatable for screenshots, tests, and bug reports,” but package-owned demo content (address, blog) is generated non-deterministically regardless of seed. Either thread the seed through capell:demo → each package’s demo command, or document the boundary explicitly. — src/Console/Commands/FullDemoCommand.php:106-113; README “Demo Generation” — M

3. Done/Shipped: removed duplicated option parse. capell:demo-kit-full-demo now resolves --page-count once, reuses it for the generated plan and admin demo call, and the changelog records the fix. — src/Console/Commands/FullDemoCommand.php, CHANGELOG.md — S

4. Tighten the manifest health-check label to match behaviour — capell.json healthChecks[0].label claims Demo Kit “surfaces, providers, and install health are discoverable by Diagnostics,” but DemoKitHealthCheck only implements compatibleCapellApiVersion() (the suite-wide ChecksExtensionHealth marker pattern, same as SeoSuiteHealthCheck/DiagnosticsHealthCheck). The substantive 13-check logic lives in AssertDefaultDemoInstallHealthAction and is reachable only via the capell:demo-kit-doctor CLI. Reword the label to describe the API-version contract, and surface the doctor action through Diagnostics (see §3). — capell.json (healthChecks), src/Health/DemoKitHealthCheck.php — S

5. Done/Shipped: hard-coded showcase contract is visible in health diagnostics. AssertDefaultDemoInstallHealthAction now includes a dedicated “Default demo showcase widget keys” check that verifies every configured opening/showcase/widget-asset key exists as a Layout Builder widget record, so Foundation showcase key drift is reported by both capell:demo-kit-doctor and Diagnostics. — src/Actions/Diagnostics/AssertDefaultDemoInstallHealthAction.php, src/Data/DemoProfileData.php — M

6. Consolidate the three overlapping demo entry points — capell:demo, capell:admin-demo, and capell:demo-kit-full-demo have overlapping option sets and subtle signature drift (--user flag vs --user= value; --force present on some, not others; --seed on some). The README and capell.json.demoParams already treat full-demo as the canonical entry. Document each command’s role crisply and align option naming/types so the fan-out is lossless. — src/Console/Commands/*, README “Commands” — M

3. Missing Features (gaps)

capabilities: [] is empty in capell.json — correct for a tooling package, so gaps are measured against demo-tooling norms rather than seller capabilities.

• Demo coverage for every package (table-stakes, currently the biggest gap). Only 3 of ~50 packages declare a commands.demo: demo-kit (capell:demo-kit-full-demo), blog (capell:blog-demo), address (capell:address-demo). Every other package (events, bookings, form-builder, knowledge-base, comments, contacts, etc.) seeds nothing through the fan-out. The orchestration is excellent but starved of contributors. Add a capell:demo-kit-doctor-style report that lists installed packages with no demo command, and drive a campaign to add per-package demo commands. This is the single highest-leverage growth item — demo completeness is what makes demo sites sell. — ties to per-package demo registration norm — differentiator once complete

• Done/Shipped: idempotent / resettable seeding. capell:demo-kit-full-demo --reset forwards to capell:admin-demo --reset, and ResetDemoSitesAction deletes only sites whose names are in the generated plan before reseeding. Demo users remain idempotent, unrelated sites are left alone, and repeated screenshot/QA runs can start from a clean named demo surface.

• Done/Shipped: Diagnostics-surfaced demo health. DemoKitHealthCheck::runDiagnostics() now returns the rich AssertDefaultDemoInstallHealthAction checks, so Diagnostics can aggregate the same homepage, widget order/count, media, runtime asset, capability graph, cache eligibility, and public-render-contract assertions exposed by capell:demo-kit-doctor. — src/Health/DemoKitHealthCheck.php, src/Actions/Diagnostics/AssertDefaultDemoInstallHealthAction.php, capell.json

• Done/Shipped: multi-site / multi-locale demo realism includes RTL coverage. Plan generation supports --site-count, --languages=all|en,fr|random:3, and the curated language pool now includes Arabic with direction: rtl. DummyContentGeneratorAction ships hand-written copy for en/fr/de/it/es/ar with a generic fallback, so demo sites can exercise bidirectional content instead of English-shaped filler only.

• Done/Shipped: screenshot-automation support baseline. docs/screenshots.json defines the Capell runner contract (requiresInstalledPackage, per-entry target/surface/useCase), and the package now commits runner PNG baselines for the admin page plus both package-owned frontend widget renders in light and dark modes. Extending the seeded-state + screenshot contract across all packages remains the larger differentiator.

4. Issues / Risks

• No production environment guard (highest risk). FullDemoCommand::handle() gates only on --force + interactivity (src/Console/Commands/FullDemoCommand.php:33-37); there is no app()->environment() check. CreateDemoUsersAction creates a super-admin [email protected] with password password (src/Actions/CreateDemoUsersAction.php:19-25). A stray --force run (or an automation hook) against a production DB would mint a known-credential superadmin and seed demo sites/pages. Add an environment guard that refuses to run in production unless an explicit override flag is set, and never seed a known-password superadmin outside local/testing.

• --user boolean bug is untested. FullDemoCommandTest registers vendor/example-package with demoParams including user but asserts only TrackingDemoCommand::$executionOrder, never that the username value arrives (tests/Feature/Commands/FullDemoCommandTest.php). The §2.1 defect is invisible to the suite. Add an assertion that the forwarded --user value matches the input.

• Done/Shipped: Foundation showcase key drift is diagnosed. The doctor now checks configured opening/showcase/widget-asset keys against actual Layout Builder widget records, and the same assertion is surfaced through Diagnostics via DemoKitHealthCheck::runDiagnostics(). Package demo-command coverage is also reported by capell:demo.

• Done/Shipped: quick seed profile for CI/screenshots. capell:demo-kit-full-demo --quick now applies compact defaults when scale options are omitted: one generated site, English only, and three pages per site. Explicit --sites, --site-count, --languages, and --page-count values still win, so larger sales demos remain unchanged. — src/Console/Commands/FullDemoCommand.php, tests/Feature/Commands/FullDemoCommandTest.php

• Done/Shipped: locale-aware seeded site meta. DemoCreator::setupSite() now derives global site meta from the default demo language and stores per-translation localized business name, description, footer content/copy, and phone fields for English, French, German, Italian, and Spanish demo sites. — src/Support/Creator/DemoCreator.php

• Done/Shipped: CHANGELOG has real package history. CHANGELOG.md records seed forwarding, production guards, user forwarding, the duplicated page-count parse fix, marketplace copy, and health-label changes.

5. Marketplace & Positioning

Demo Kit is an internal/tooling package (tier: free, bundle: foundation, commercial.proposedLicense: free), not a marketplace seller — its commercial value is indirect: it powers the demo sites that drive conversion for every paid package, and it owns the screenshot contract that feeds marketing assets. Positioning should lean into that “engine behind the demos” role rather than pretending to be an end-user feature.

Critique — current copy is flat and undersells the orchestration.

• marketplace.summary / composer.description both say roughly “example content and media for local Capell demos.” They omit the actual differentiators: deterministic/seeded plans, per-package demo fan-out, multi-site/multi-locale generation, and a CLI doctor.
• Improved marketplace.summary: “The demo engine for Capell: deterministic, multi-site, multi-language sample content and media. Generates a curated showcase site, fans out to each installed package’s own demo command, and ships a health doctor so every demo, screenshot, and QA run starts from known data.”
• Improved composer.description: “Deterministic demo-data orchestration for Capell — seeds users, sites, languages, pages, media and a Foundation showcase homepage, and dispatches per-package demo commands.”

Role in sales: demo completeness is the conversion lever. The §3 gap (3/50 packages seed data) directly limits how compelling a full demo site looks; closing it is a revenue-adjacent investment, not just devx. Role in screenshot automation: docs/screenshots.json + --seed already position Demo Kit as the source of repeatable marketing imagery; threading seed through package demos and committing baseline captures would make it the canonical asset pipeline.

Screenshot/media status: The marketplace manifest exposes the extension card plus the light/dark Demo Kit admin runner captures. The committed frontend widget captures stay in docs/screenshots.json as evidence for the current render targets, but they are held out of marketplace media until the runner can recapture styled package-owned public widget states instead of the bare default “Demo” page. The contract also keeps a required-false consent priming capture for clean anonymous frontend screenshots. Remaining optional media depth is styled frontend widget recapture plus multi-site/multi-locale output.

Keywords/tags (8–12): demo-data, seeding, fixtures, screenshot-automation, multi-site, multi-language, deterministic-seed, qa-tooling, showcase, foundation, cms-demo, developer-tooling.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref
Add production environment guard + no known-password superadmin outside local/testing	Done	S	High	§4 — closed 2026-06-05: demo commands now share a production guard with explicit --allow-production override and regression coverage.
Fix --user forwarded as boolean to capell:demo	Done	S	High	§2.1 — closed 2026-06-05: capell:demo accepts {--user=} and full-demo forwards the selected author value to package demos.
Add test asserting --user value reaches package demos	Done	S	Med	§4 — closed 2026-06-05: FullDemoCommandTest asserts the package demo receives the author email verbatim.
Drive per-package commands.demo coverage (campaign + “missing demo” report)	Done	L	High	§3 — closed 2026-06-05: capell:demo now reports selected packages that do not declare commands.demo, with feature coverage for mixed runnable/missing package selections.
Thread --seed through capell:demo package fan-out (or document boundary)	Done	M	High	§2.2 — closed 2026-06-05: full-demo forwards the resolved seed to package demos and DemoCommandTest covers seed forwarding only for packages that declare the parameter.
Done/Shipped: Surface AssertDefaultDemoInstallHealthAction in Diagnostics admin, not CLI-only	Done	M	High	§3, §2.4 — DemoKitHealthCheck::runDiagnostics() now returns the same rich demo install checks used by capell:demo-kit-doctor.
Reword manifest healthCheck label to match marker behaviour	Done	S	Low	§2.4 — closed 2026-06-05: manifest health copy now states the API-version compatibility contract instead of over-claiming install probes.
Rewrite marketplace summary + composer description	Done	S	Med	§5 — closed 2026-06-05: manifest/composer copy now leads with deterministic demo-data orchestration, multi-site/language seeding, and per-package fan-out.
Done/Shipped: Populate marketplace screenshots to match screenshots.json + commit baselines	Done	M	Med	§5 — closed 2026-06-06: Capell runner captured admin, demo-page-content, and homepage-section targets with light/dark PNG baselines, all promoted into capell.json.
Done/Shipped: Localize seeded site meta (footer/business/phone) via locale-aware content	Done	M	Med	§4 — DemoCreator::setupSite() now writes localized business, footer, phone, and description metadata per demo language.
Done/Shipped: Guard against demo-key drift by checking Foundation showcase widget keys	Done	M	Med	§2.5, §4 — doctor/Diagnostics now report missing configured opening/showcase/widget-asset keys as demo health failures.
Add idempotent/reset path for re-runnable seeding	Done	M	Med	§3 — 2026-06-06: added --reset to full/admin demo commands and ResetDemoSitesAction to remove only generated-plan site names before reseeding.
Add --quick seed profile for CI/screenshot speed	Done	M	Low	§4 — 2026-06-06: capell:demo-kit-full-demo --quick now defaults omitted scale options to one site, English only, and three pages per site.
Broaden curated locale pool + add RTL demo coverage	Done	M	Low	§3 — 2026-06-06: added Arabic language metadata with direction: rtl, Arabic dummy content, and plan/content coverage.
Done/Shipped: Remove duplicated page-count parse + start a real CHANGELOG	Done	S	Low	§2.3, §4