Use this page before changing seeded demo, builder, integration, or membership flows.

These notes are for engineers working inside the BookFlow repo. They point to the implementation surfaces, safe reset paths, and test commands that prove a docs or demo change still works.

Local setup

Run commands from the project root. Keep demo-only behavior behind the configured demo flag.

composer install
npm install
php artisan key:generate
php artisan bookflow:install-fresh --seed-demo --force
php artisan bookflow:health-check
php artisan bookflow:preflight --json
php artisan optimize:clear

Production warning: Do not run destructive refresh or reseed commands against production data. The demo reset path is for local/seeded Nimbus data.

Safe reset and reseed

Need	Command or path	What it affects
Fresh local install	php artisan bookflow:install-fresh --seed-demo --force	Drops tables, migrates, seeds base data, seeds Nimbus demo, links storage, and clears caches.
Full demo records	php artisan bookflow:demo-reset --tenant=nimbus	Rebuilds Nimbus demo customers, bookings, memberships, packages, integrations, wallet, and support-compatible records.
Storefront media and builder pages	php artisan bookflow:storefront-reseed	Refreshes Nimbus media, rich metadata, homepage blocks, custom pages, drafts, and revisions.
AI premium docs screenshots	npm run docs:screenshots	Starts a local Nimbus demo session, logs in as the seeded vendor admin, and captures the actual AI settings, audit, receptionist, reports, and website helper screens.
Health/readiness	php artisan bookflow:health-check or /demo/status	Checks install, seed, wallet, Mailpit, Stripe sandbox, integration, builder, and resettable action readiness.
System preflight	php artisan bookflow:preflight --json or /system/preflight	Checks environment, storage, scheduler freshness, providers, update/license readiness, demo data, and required screenshot assets.
Support bundle	php artisan bookflow:support-bundle	Creates a redacted ZIP with preflight, config-safe support evidence, recent operations, and diagnostics for support review.
Scheduled reports	php artisan bookflow:scheduled-reports --tenant=nimbus	Processes due owner/admin report subscriptions and records completed or failed report runs.
Guided demo restart	/demo/restart	Uses the app demo reset flow; only available when demo mode is enabled.

Where code lives

Guided demo

Journey definitions, modes, acts, feature keys, proof targets, and risk metadata live in the demo journey service. The widget behavior lives in the public demo JS/CSS assets.

Seed data

Nimbus, Olivia, demo bookings, memberships, packages, support cases, media, and integration fixtures are created by the BookFlow demo seeder and storefront reseed command.

Builder

Studio screens, preview partials, builder services, package surface, block CSS, and public storefront rendering must stay compatible with existing saved block payloads.

Integrations

Connector managers, workflow simulator, custom app connector, webhook controller, sync logs, event templates, and field mappings define the safe integration workflow.

Memberships

Plan rules, benefit resolution, customer wallet, booking snapshots, payment ledger, usage ledger, package credits, and dependents should be tested together.

AI premium layer

Tenant AI preferences live in business settings, approved snippets live in the AI knowledge base, provider activity is recorded in AI usage logs, and AI action drafts must remain confirmation-only.

System proof

Preflight, operations dashboard, scheduled tasks, support bundles, update checks, and diagnostics live in the platform system tools and console commands.

Billing and wallet

Signup checkout, subscription transactions, wallet top-up sessions, wallet payment debits, receipts, and webhook/callback handlers must stay traceable by reference.

Docs assets

Static docs pages live under documentation/pages. Screenshots, annotated callouts, and diagrams live under documentation/assets/media.

AI proof screenshots

The premium AI and marketplace confidence screenshots are real captures from the seeded Nimbus tenant, not generated artwork. Keep these files current whenever AI settings, receptionist workflow, report summary, website helper, preflight, support bundle, operations, privacy, staff mobile, or scheduled report UI changes.

Nimbus demo AI proof path showing simulator, fallback, and live provider state — Demo proof path: the screenshots document rules fallback, simulator mode, missing-key fallback, and the live-provider-ready state without claiming autonomous booking actions.

npm run docs:screenshots

The screenshot runner writes files to documentation/assets/media/bookflow/ai and documentation/assets/media/bookflow/marketplace, and should fail loudly if login, routing, or any target screen breaks.

BookFlow system preflight screenshot — Marketplace confidence proof: preflight checks real local readiness while provider rows clearly show configured, simulator, or missing states.

BookFlow operations dashboard screenshot — Operations proof: scheduled task runs and failed job actions are platform-admin system tools.

External flow safety

Use simulators or seeded replay. Billing callbacks, signed webhooks, TicketPro support flow, ecommerce entitlement events, FlowOS messages, AI provider fallback paths, and custom app workflows should be demonstrated with signed local simulators or seeded replay data. Do not call irreversible real external services from the demo.

Test commands

php artisan bookflow:health-check
php artisan test tests\Feature\BookFlow\GuidedDemoTest.php
php artisan test tests\Feature\BookFlow\BookFlowDemoSeederTest.php
php artisan test tests\Feature\BookFlow\AiReceptionistSettingsTest.php
php artisan test tests\Feature\BookFlow\AiPremiumDocsTest.php
php artisan test tests\Feature\BookFlow\IntegrationsTest.php
php artisan test tests\Feature\BookFlow\ReportsAndPortalTest.php
php artisan test tests\Feature\BookFlow\TenantRoutingTest.php
php artisan test tests\Feature\BookFlow
npm run docs:screenshots
php artisan bookflow:preflight --json
php artisan bookflow:scheduled-reports --tenant=nimbus
php artisan bookflow:support-bundle

For docs-only edits, also run a static link check over documentation/index.html and documentation/pages/*.html, then open the docs home and this page at desktop and mobile widths.

Public docs publishing

The source docs live in the Booking app under documentation. The public Ovion docs hub keeps a cleaned copy under D:\Xampp\htdocs\docs\apps\booking so the live docs domain stays static and low-inode.

Rule	Reason
Copy existing HTML pages, CSS, JS, and referenced non-video media only.	Keeps the public docs useful without copying source-only project files.
Exclude markdown, scripts, reports, JSON manifests, test artifacts, caches, and videos.	Reduces inode count and avoids publishing internal QA/source files.
Use shared docs assets for duplicate favicons and installer screenshots.	Prevents repeating identical files across app manuals.
Do not copy root-level bookflow-standout-*.png images unless a later release needs them.	They are marketplace artwork, not required for this public docs refresh.
Run a missing-reference scan after cleanup.	Confirms every local href and src still resolves in the static copy.

Developer checklist

Keep documentation navigation complete and static so it works without JavaScript.
When adding a docs page, add it to the canonical sidebar on every docs HTML page.
When changing demo steps, keep feature keys, proof targets, expected results, and risk metadata present.
When changing builder payloads, keep old saved blocks valid and prove public rendering still works.
When changing memberships, prove the admin rules, customer wallet, booking snapshot, payment ledger, and usage ledger together.
When changing integrations, prove incoming event, mapped fields, local result, linked record, payload drawer, and operator next action.
When changing public docs, refresh the app source docs first, then rebuild the cleaned low-inode docs hub copy.