Package Demo Audit Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Audit every package in isolation, capture the exact admin/frontend surfaces each package adds, document screenshots and use cases, and produce feature suggestions per package.

Architecture: Use one fresh accessible Capell demo app as the reproducible harness, reset it between packages, and install only Capell core plus the package under audit and its declared hard dependencies. Each package is handled sequentially inside its batch so screenshots, menus, docs, and feature suggestions are attributable to that package instead of to previously installed packages.

Tech Stack: Capell 4, Laravel, Filament, Composer path repositories, Devilbox or local PHP 8.3 runtime, Playwright/browser screenshot capture, Pest for package-level verification.

---

Operating Rules

• Work in /Users/ben/Sites/packages/capell/capell-packages-4.
• Do not use php artisan in this package repo. Inside the separate demo app, use artisan only when the app install flow requires it.
• Use $write-developer-docs for every package documentation pass: inspect providers, routes, Filament resources/pages/widgets, Actions, config, migrations, tests, README, and existing package docs before changing prose.
• Use $humanizer before finalizing package docs: remove generic generated prose, keep the writing specific to the package, and cut claims that are not backed by code or tests.
• Keep the demo app outside this repo, at /Users/ben/Sites/packages/capell/capell-package-demo-audit.
• Use core Capell packages as the baseline: capell-app/core, capell-app/admin, capell-app/frontend, capell-app/installer, and capell-app/marketplace when required by the app install.
• For each audit run, install the target package plus only the hard dependencies declared by that package’s capell.json. Do not install optional dependencies unless the package surface being documented explicitly requires them; if an optional dependency is used, record it in the package audit notes.
• Before capturing screenshots, compare the current admin menu against the core baseline. Any menu item not added by the target package or its hard dependencies must be removed from the demo app before capture.
• Every Filament page, resource index, create/edit/view form, relation manager, widget, custom action modal, settings page, dashboard panel, and custom control added by the target package needs a screenshot entry.
• Every public frontend route, Blade render path, widget, injected render hook, theme view, beacon behavior, cache behavior, and public action added by the target package needs a screenshot entry and a short use case.
• Manifest entries are not enough for the final pass. Each required entry must have a captured image file or an explicit blocker with the command, URL, and missing setup that prevented capture.
• Keep screenshots minimal: seed only enough data to show the package’s contribution clearly.
• For packages with no visible frontend, document that explicitly in docs/overview.md and in the package audit notes.
• Anonymous and non-admin public screenshots must not expose authoring markers, package internals, model IDs, editor URLs, or admin-only labels.

Deliverables Per Package

Each package audit produces or updates:

• packages/{package}/README.md: accurate install summary, what the package adds, and links to docs.
• packages/{package}/docs/overview.md: install flow, demo setup, admin surfaces, frontend surfaces, use cases, screenshot list, known risks, and feature suggestions.
• packages/{package}/docs/screenshots.json: complete screenshot contract for all admin and frontend surfaces.
• docs/package-screenshot-manifest.json: regenerated aggregate manifest from package screenshot manifests.
• docs/package-testing-audit.md: package checklist result, verification commands, and audit notes.
• docs/internal/package-feature-suggestions.md: package-by-package feature suggestions ranked by value and implementation risk.
• Screenshot image files in the demo/docs output path: public/docs/screenshots/packages/{package} in the demo app or generated docs deployment.

Batch Ownership

Dispatch one worker per batch. Each worker must process its assigned packages one by one, resetting the demo app between packages.

• Agent 1: access-gate, address, agent-bridge, ai-orchestrator, api, block-library, blog, campaign-studio
• Agent 2: content-sections, dashboard-reports, demo-kit, deployments, diagnostics, document-lifecycle, email-studio, events
• Agent 3: form-builder, foundation-theme, frontend-authoring, frontend-optimizer, ga4-reports, hero, html-cache, insights
• Agent 4: layout-builder, login-audit, media-ai, media-library, migration-assistant, navigation, newsletter, notes
• Agent 5: password-policy, public-actions, publishing-studio, search, seo-suite, site-discovery, tags, theme-agency
• Agent 6: theme-corporate, theme-saas, translation-manager, welcome-tour, wordpress-importer

Task 1: Create The Fresh Demo Harness

Files:

• Create: /Users/ben/Sites/packages/capell/capell-package-demo-audit/

• Create: docs/package-demo-audit-harness.md

• Step 1: Inspect Capell app bootstrap instructions

Run:

sed -n '1,220p' ../capell-4/README.md
sed -n '1,220p' ../capell-4/composer.json

Expected: identify the exact Capell app install command and any required environment variables.

• Step 2: Create a brand new demo app

Use the app bootstrap command found in Step 1. The target directory must be:

/Users/ben/Sites/packages/capell/capell-package-demo-audit

Expected: the app boots with Capell core/admin/frontend only, before any optional package under audit is installed.

• Step 3: Configure local package path repositories

Inside /Users/ben/Sites/packages/capell/capell-package-demo-audit/composer.json, add path repositories for:

[
    {
        "type": "path",
        "url": "../capell-packages-4/packages/*",
        "options": {
            "symlink": true
        }
    },
    {
        "type": "path",
        "url": "../capell-4/packages/*",
        "options": {
            "symlink": true
        }
    }
]

Expected: composer require capell-app/{package}:4.x-dev resolves local package code.

• Step 4: Make the app accessible

Run the app through Devilbox or the simplest available local PHP runtime. The app must be reachable in a browser at one stable URL, for example:

https://capell-package-demo-audit.test

Expected: admin and frontend URLs load in a browser and can be captured by Playwright or the in-app browser.

• Step 5: Document the harness

Create docs/package-demo-audit-harness.md with:

# Package Demo Audit Harness

Demo app path: `/Users/ben/Sites/packages/capell/capell-package-demo-audit`
Browser URL: `https://capell-package-demo-audit.test`
PHP runtime: Devilbox or documented equivalent
Core baseline packages: `capell-app/core`, `capell-app/admin`, `capell-app/frontend`, `capell-app/installer`, `capell-app/marketplace`

## Reset Command

Document the exact command sequence used to return the app to core baseline before installing the next package.

## Admin Account

Document the local admin email and role used for screenshots.

## Screenshot Output

Screenshots are written to `public/docs/screenshots/packages/{package}`.

Task 2: Capture The Core Baseline

Files:

• Create: docs/internal/core-demo-baseline.md

• Create: docs/internal/core-admin-menu-baseline.json

• Step 1: Install only the core baseline

Reset the demo app and install only the baseline Capell app packages.

Expected: no package from /Users/ben/Sites/packages/capell/capell-packages-4/packages is installed.

• Step 2: Capture baseline admin menu

Export the Filament navigation labels, resource/page classes, route names, and URLs into docs/internal/core-admin-menu-baseline.json.

Expected shape:

{
    "capturedAt": "2026-05-19",
    "appUrl": "https://capell-package-demo-audit.test",
    "items": [
        {
            "label": "Dashboard",
            "class": "Capell\\Admin\\...",
            "routeName": "filament.admin.pages.dashboard",
            "url": "/admin"
        }
    ]
}

• Step 3: Capture baseline public frontend

Create docs/internal/core-demo-baseline.md with the home page URL, admin dashboard URL, and a short list of core-only screens.

Expected: later package audits can diff against this baseline and avoid documenting unrelated menu items.

Task 3: Add The Package Audit Template

Files:

• Create: docs/internal/package-audit-template.md

• Create or modify: docs/internal/package-feature-suggestions.md

• Step 1: Create the per-package audit template

Create docs/internal/package-audit-template.md:

# {Package Name} Audit

Package: `{package}`
Composer name: `{composerName}`
Hard dependencies installed: `{hardDependencies}`
Optional dependencies installed: `{optionalDependencies}`
Demo URL: `{demoUrl}`

## Install Verification

- Composer require command:
- Migration/setup command:
- Package discovery result:
- Package tests:

## Admin Surfaces Added

| Surface | URL | Screenshot | Notes |
| ------- | --- | ---------- | ----- |

## Frontend Surfaces Added

| Surface | URL | Screenshot | Use case |
| ------- | --- | ---------- | -------- |

## Menu Diff

List only menu entries added by this package or its hard dependencies.

## Screenshot Coverage

Confirm every Filament page, resource, form, widget, action modal, relation manager, settings page, frontend route, render hook, and public Blade output has a screenshot entry.

## Public Safety Checks

Confirm anonymous and non-admin frontend output exposes no authoring/admin surface.

## Feature Suggestions

| Suggestion | User value | Implementation risk | Package fit |
| ---------- | ---------- | ------------------- | ----------- |

## Risks And Follow-Ups

Record broken UI, missing docs, missing screenshot coverage, package conflicts, or suspicious dependencies.

• Step 2: Create feature suggestions index

Create docs/internal/package-feature-suggestions.md:

# Package Feature Suggestions

Suggestions are collected during isolated package audits. Each suggestion must be tied to a real observed package surface and ranked by user value and implementation risk.

| Package | Suggestion | User value | Implementation risk | Notes |
| ------- | ---------- | ---------- | ------------------- | ----- |

Task 4: Package Audit Loop

Files:

• Modify: packages/{package}/README.md
• Modify or create: packages/{package}/docs/overview.md
• Modify or create: packages/{package}/docs/screenshots.json
• Modify: docs/package-testing-audit.md
• Modify: docs/internal/package-feature-suggestions.md

Repeat these steps for each package in the assigned batch.

• Step 1: Read package metadata

Run:

sed -n '1,220p' packages/{package}/composer.json
sed -n '1,220p' packages/{package}/capell.json
find packages/{package}/src/Filament -type f | sort
find packages/{package}/resources/views -type f | sort
find packages/{package}/routes -type f | sort

Expected: identify composer name, hard dependencies, optional dependencies, admin surfaces, frontend surfaces, and setup commands.

• Step 2: Reset demo app

In /Users/ben/Sites/packages/capell/capell-package-demo-audit, run the reset sequence documented in docs/package-demo-audit-harness.md.

Expected: app returns to the core baseline before installing the next package.

• Step 3: Install target package and hard dependencies

Install the target package with its capell.json hard dependencies. Use Composer path repositories so package code comes from this repo.

Expected: composer show 'capell-app/*' lists core baseline packages, hard dependencies, and the single target package. It must not list unrelated optional packages.

• Step 4: Run package setup

Run migrations, seeders, install commands, and demo commands listed in the package README or docs/overview.md.

Expected: the package has minimal demo content for screenshots and no unrelated package data.

• Step 5: Run package tests from this repo

Run the narrowest package test suite:

vendor/bin/pest packages/{package}/tests --configuration=phpunit.xml

Expected: package tests pass, or failures are recorded in docs/package-testing-audit.md with exact failing test names.

• Step 6: Capture menu diff

Compare the current Filament admin menu to docs/internal/core-admin-menu-baseline.json.

Expected: the diff contains only the target package and hard-dependency surfaces. If another package appears, remove it from the demo app and repeat the capture.

• Step 7: Capture admin screenshots

For every added Filament surface, capture desktop screenshots. Include mobile screenshots when the surface is responsive, dense, or likely to collapse awkwardly.

Required admin captures:

• Resource index table
• Create form
• Edit form
• View/infolist page, when present
• Relation managers, when present
• Custom action modals
• Custom widgets
• Dashboard panels
• Settings pages
• Custom Filament pages
• Empty state when it is materially different from the populated state

Expected: screenshots are saved under public/docs/screenshots/packages/{package} and referenced from packages/{package}/docs/screenshots.json.

• Step 8: Capture frontend screenshots and use cases

For every public route, render hook, theme view, widget, public action, or Blade output, capture screenshots and write a use case in packages/{package}/docs/overview.md.

Expected: each frontend screenshot answers: who uses this, what they are trying to do, and what package behavior is visible.

• Step 9: Check public safety

View frontend pages as anonymous and as a normal non-admin user.

Expected: no authoring HTML, authoring JavaScript, editable markers, model IDs, field paths, labels, package internals, permissions, selectors, or signed editor URLs appear in public HTML.

• Step 10: Update package docs

Update README.md and docs/overview.md so they match the real install and demo flow.

Expected: docs contain no claims that were not verified in the isolated demo app.

• Step 11: Update screenshot manifest

Create or update packages/{package}/docs/screenshots.json with entries for every required screenshot.

Expected manifest shape:

{
    "package": "{package}",
    "composerName": "capell-app/{composer-name}",
    "composerRequires": ["capell-app/{hard-dependency}"],
    "outputDirectory": "public/docs/screenshots/packages/{package}",
    "entries": [
        {
            "id": "{stable-screenshot-id}",
            "title": "{Human readable title}",
            "surface": "admin",
            "targetType": "admin-surface",
            "target": "{Filament resource or page class}",
            "required": true,
            "docsPage": "packages/{package}/docs/overview.md",
            "output": "{stable-screenshot-id}.png"
        }
    ],
    "browserTests": []
}

• Step 12: Record feature suggestions

Add at least three feature suggestions to docs/internal/package-feature-suggestions.md unless the package is intentionally tiny. Suggestions must come from observed package behavior, not imagination detached from the UI.

Expected: each suggestion includes user value, implementation risk, and why it belongs in this package.

• Step 13: Update package testing audit

Update docs/package-testing-audit.md with the package checklist result, commands run, screenshot status, and known risks.

Expected: package status is understandable without reopening the demo app.

Task 5: Regenerate Aggregate Screenshot Manifest

Files:

• Create: scripts/build-package-screenshot-manifest.js

• Modify: docs/package-screenshot-manifest.json

• Modify: package.json

• Step 1: Add the aggregate manifest builder

Create scripts/build-package-screenshot-manifest.js. The script must read every packages/*/docs/screenshots.json, merge their entries, preserve package-level browserTests, and write deterministic pretty JSON to docs/package-screenshot-manifest.json.

Required output shape:

{
    "generatedFor": "capell-docs-deployment",
    "source": "packages/*/docs/screenshots.json",
    "outputRoot": "public/docs/screenshots/packages",
    "requirements": [
        "Install the package under test.",
        "Composer require any package-level composerRequires before seeding demo data.",
        "Run package setup or demo commands listed in the package overview.",
        "Authenticate as an admin user with the required role or permission.",
        "Resolve admin-surface targets through Filament resource/page URLs when possible.",
        "Resolve frontend-url targets through seeded demo routes or package route names.",
        "Execute package-level browserTests when declared by the source screenshots manifest."
    ],
    "entries": [],
    "browserTests": []
}

Expected: aggregate manifest contains every screenshot entry and browser test from every audited package.

• Step 2: Add package scripts

Merge these scripts into the existing package.json scripts block:

{
    "scripts": {
        "screenshots:manifest": "node scripts/build-package-screenshot-manifest.js",
        "screenshots:validate": "node scripts/validate-screenshot-manifests.js"
    }
}

Expected: npm run screenshots:manifest rebuilds the aggregate file and npm run screenshots:validate confirms it matches package manifests.

• Step 3: Regenerate and validate

Run:

npm run screenshots:manifest
npm run screenshots:validate

Expected: docs/package-screenshot-manifest.json is deterministic and validation prints Screenshot manifests are in sync.

• Step 4: Validate package coverage

Compare package list to packages with screenshot manifests:

find packages -maxdepth 2 -name composer.json -print | sort
find packages -maxdepth 3 -path '*/docs/screenshots.json' -print | sort

Expected: every package with a visible admin or frontend surface has a screenshot manifest. Packages with no visible surface are explicitly documented in their overview.

Task 6: Cross-Package Conflict Pass

Files:

• Modify: docs/package-testing-audit.md

• Modify: affected package docs or manifests

• Step 1: Review Composer and Capell manifests

Run:

find packages -maxdepth 2 -name capell.json -print | sort
find packages -maxdepth 2 -name composer.json -print | sort

Expected: hard dependencies are declared in capell.json, optional dependencies are not installed during isolated screenshots unless explicitly needed, and conflicts are documented where needed.

• Step 2: Review admin navigation collisions

Use the captured menu diffs from every package.

Expected: no package audit screenshots include unrelated menu items from a previously installed package. If two packages intentionally share a navigation group, document the shared group and the package-specific items.

• Step 3: Review frontend collisions

Check package routes, view namespaces, asset names, render hooks, and public paths.

Expected: no screenshots or docs attribute another package’s frontend output to the package under audit.

Task 7: Final Verification

Files:

• Modify: docs/package-testing-audit.md

• Modify: docs/internal/package-feature-suggestions.md

• Modify: docs/package-screenshot-manifest.json

• Step 1: Run focused package tests for changed packages

For every package whose code or tests changed, run:

vendor/bin/pest packages/{package}/tests --configuration=phpunit.xml

Expected: tests pass or failures are documented with exact failing test names.

• Step 2: Run documentation checks

Run:

composer prettier
composer lint:changed

Expected: changed Markdown, JSON, Blade, PHP, CSS, and JS files are formatted.

• Step 3: Spot-check screenshots

Open at least one admin screenshot and one frontend screenshot from each package with visible surfaces.

Expected: screenshot is readable, minimal, seeded with useful data, and not hiding broken UI states.

• Step 4: Produce final audit summary

Update docs/package-testing-audit.md with:

• Packages completed
• Packages blocked
• Screenshot coverage gaps
• Public safety risks
• Menu conflict findings
• Top feature suggestions across all packages

Expected: Ben can decide which package improvements to prioritize without rerunning the whole audit.

Current Repo State Notes

As of 2026-05-19, package composer files exist for:

access-gate, address, agent-bridge, ai-orchestrator, api, block-library, blog, campaign-studio, content-sections, dashboard-reports, demo-kit, deployments, diagnostics, document-lifecycle, email-studio, events, form-builder, foundation-theme, frontend-authoring, frontend-optimizer, ga4-reports, hero, html-cache, insights, layout-builder, login-audit, media-ai, media-library, migration-assistant, navigation, newsletter, notes, password-policy, public-actions, publishing-studio, search, seo-suite, site-discovery, tags, theme-agency, theme-corporate, theme-saas, translation-manager, welcome-tour, wordpress-importer.

Existing screenshot manifests are present for:

address, agent-bridge, ai-orchestrator, blog, campaign-studio, deployments, diagnostics, form-builder, foundation-theme, frontend-authoring, insights, login-audit, media-ai, media-library, migration-assistant, navigation, publishing-studio, search, seo-suite, tags, theme-agency, theme-corporate, theme-saas, wordpress-importer.

Existing overview docs are present for:

address, agent-bridge, ai-orchestrator, blog, campaign-studio, dashboard-reports, demo-kit, deployments, diagnostics, email-studio, form-builder, foundation-theme, frontend-authoring, ga4-reports, insights, login-audit, media-ai, media-library, migration-assistant, navigation, password-policy, publishing-studio, search, seo-suite, tags, theme-agency, theme-corporate, theme-saas, translation-manager, welcome-tour, wordpress-importer.

The first audit pass should prioritize packages missing screenshot manifests or overview docs, while still verifying existing manifests against the fresh isolated demo app.

Task 8: Deep Documentation And Screenshot Pass

Files:

• Modify: packages/{package}/README.md
• Modify: packages/{package}/docs/overview.md
• Modify: packages/{package}/docs/screenshots.json
• Create or update: screenshot image files under /Users/ben/Sites/packages/capell/capell-package-demo-audit/public/docs/screenshots/packages/{package}
• Modify: docs/package-testing-audit.md
• Modify: docs/internal/package-feature-suggestions.md

Repeat these steps for each package. Do not batch packages so tightly that docs become generic.

• Step 1: Read the package source before writing

Inspect the package’s providers, Filament classes, routes, views, Actions, config, migrations, tests, and existing docs:

find packages/{package}/src packages/{package}/resources packages/{package}/config packages/{package}/database packages/{package}/tests -maxdepth 5 -type f | sort
sed -n '1,220p' packages/{package}/README.md
test -f packages/{package}/docs/overview.md && sed -n '1,260p' packages/{package}/docs/overview.md
test -f packages/{package}/docs/screenshots.json && sed -n '1,260p' packages/{package}/docs/screenshots.json

Expected: the maintainer can point from every documented feature to a real class, route, config key, migration, test, or Blade view.

• Step 2: Verify install in the Laravel 13 harness

Install the target package and all hard dependencies in an isolated harness. For login-audit, the host app must use the Rappasoft Laravel 13 PR fork:

composer require 'rappasoft/laravel-authentication-log:dev-main as 6.0.1' capell-app/login-audit:4.x-dev -W

Expected: Composer resolves rappasoft/laravel-authentication-log from https://github.com/fdemb/laravel-authentication-log at PR #140 until upstream ships Laravel 13 support.

• Step 3: Seed minimal screenshot data

Create only the data needed to show the package’s own screens. Prefer package demo/install commands where they exist. If no command exists, document the exact records created and why.

Expected: screenshots show useful package state without unrelated menu clutter or demo bloat.

• Step 4: Capture every required screenshot

For each required docs/screenshots.json entry, open the actual URL/surface and write the screenshot file declared by the manifest. Capture admin and frontend surfaces as separate images. Capture anonymous/non-admin frontend states where public safety matters.

Expected: every required manifest entry has an image file or a documented blocker in docs/package-testing-audit.md.

• Step 5: Rewrite docs from the reader’s next action

Use $write-developer-docs standards. Package docs should say:

• what the package adds
• how to install it in a host app
• which admin and frontend surfaces appear
• which data/tables/settings/config keys it owns
• which commands/jobs/schedules/routes it registers
• how screenshots are seeded and captured
• how to verify package changes
• what can break if extension boundaries are changed carelessly

Expected: no package docs rely on broad claims such as “powerful”, “seamless”, “comprehensive”, or “robust” without concrete code-backed detail.

• Step 6: Run the humanizer pass

Read the whole changed README and overview. Remove chatbot residue, inflated claims, repeated sentence shapes, and filler.

Expected: the docs sound like a maintainer wrote them after testing the package, not like a generated product summary.

• Step 7: Verify

Run:

vendor/bin/pest packages/{package}/tests --configuration=phpunit.xml
jq empty packages/{package}/docs/screenshots.json
npm run screenshots:manifest
npm run screenshots:validate
git diff --check -- packages/{package}/README.md packages/{package}/docs docs/package-testing-audit.md docs/internal/package-feature-suggestions.md

Expected: package tests pass, screenshot manifests stay in sync, and changed docs have no whitespace errors.