# 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** `demo@example.com` 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                                                                                                                                                                      |