output:
Chunk ID: 922f3a
Wall time: 0.0000 seconds
Process exited with code 0
Original token count: 5684
Output:
specs/01-DATABASE-SCHEMA.md:492:### search_settings
specs/01-DATABASE-SCHEMA.md:494:Per-store search configuration (synonyms, stop words).
specs/01-DATABASE-SCHEMA.md:505:### search_queries
specs/01-DATABASE-SCHEMA.md:507:Search query log for analytics and autocomplete.
specs/01-DATABASE-SCHEMA.md:520:- `idx_search_queries_store_id` on (`store_id`) - FK lookup
specs/01-DATABASE-SCHEMA.md:521:- `idx_search_queries_store_created` on (`store_id`, `created_at`) - Time-range queries per store
specs/01-DATABASE-SCHEMA.md:522:- `idx_search_queries_store_query` on (`store_id`, `query`) - Autocomplete and popular search lookups
specs/01-DATABASE-SCHEMA.md:914:### analytics_events
specs/01-DATABASE-SCHEMA.md:916:Raw event stream for storefront analytics.
specs/01-DATABASE-SCHEMA.md:932:- `idx_analytics_events_store_id` on (`store_id`) - FK lookup
specs/01-DATABASE-SCHEMA.md:933:- `idx_analytics_events_store_type` on (`store_id`, `type`) - Filtering events by type per store
specs/01-DATABASE-SCHEMA.md:934:- `idx_analytics_events_store_created` on (`store_id`, `created_at`) - Time-range event queries
specs/01-DATABASE-SCHEMA.md:935:- `idx_analytics_events_session` on (`session_id`) - Session-based event grouping
specs/01-DATABASE-SCHEMA.md:936:- `idx_analytics_events_customer` on (`customer_id`) - Customer activity history
specs/01-DATABASE-SCHEMA.md:937:- `idx_analytics_events_client_event` UNIQUE on (`store_id`, `client_event_id`) - Client-side event deduplication
specs/01-DATABASE-SCHEMA.md:939:**Notes:** Event types include: `page_view`, `product_view`, `add_to_cart`, `remove_from_cart`, `checkout_started`, `checkout_completed`, `search`. This table will grow fast - consider periodic archiving or partitioning by date for production workloads beyond SQLite.
specs/01-DATABASE-SCHEMA.md:943:### analytics_daily
specs/01-DATABASE-SCHEMA.md:963:- `idx_analytics_daily_store_date` on (`store_id`, `date`) - Time-range metric queries (covered by PK but explicit for clarity)
specs/01-DATABASE-SCHEMA.md:971:### apps
specs/01-DATABASE-SCHEMA.md:984:- `idx_apps_status` on (`status`) - Filtering apps by status
specs/01-DATABASE-SCHEMA.md:996:| app_id | INTEGER | No | - | FK -> apps(id) ON DELETE CASCADE | |
specs/01-DATABASE-SCHEMA.md:1011:OAuth2 client credentials for apps.
specs/01-DATABASE-SCHEMA.md:1016:| app_id | INTEGER | No | - | FK -> apps(id) ON DELETE CASCADE | Parent app |
specs/01-DATABASE-SCHEMA.md:1432:    stores ||--o{ analytics_events : "records"
specs/01-DATABASE-SCHEMA.md:1433:    stores ||--o{ analytics_daily : "aggregates"
specs/01-DATABASE-SCHEMA.md:1434:    customers ||--o{ analytics_events : "generates"
specs/01-DATABASE-SCHEMA.md:1435:    apps ||--o{ app_installations : "installed via"
specs/01-DATABASE-SCHEMA.md:1437:    apps ||--o{ oauth_clients : "authenticates via"
specs/01-DATABASE-SCHEMA.md:1443:    analytics_events {
specs/01-DATABASE-SCHEMA.md:1449:    analytics_daily {
specs/01-DATABASE-SCHEMA.md:1455:    apps {
specs/01-DATABASE-SCHEMA.md:1515:        apps
specs/01-DATABASE-SCHEMA.md:1531:        search_settings
specs/01-DATABASE-SCHEMA.md:1551:        search_queries
specs/01-DATABASE-SCHEMA.md:1563:        analytics_events
specs/01-DATABASE-SCHEMA.md:1564:        analytics_daily
specs/01-DATABASE-SCHEMA.md:1581:    apps --> app_installations
specs/01-DATABASE-SCHEMA.md:1582:    apps --> oauth_clients
specs/01-DATABASE-SCHEMA.md:1591:    stores --> search_settings
specs/01-DATABASE-SCHEMA.md:1609:    stores --> search_queries
specs/01-DATABASE-SCHEMA.md:1624:    stores --> analytics_events
specs/01-DATABASE-SCHEMA.md:1625:    customers --> analytics_events
specs/01-DATABASE-SCHEMA.md:1626:    stores --> analytics_daily
specs/01-DATABASE-SCHEMA.md:1643:- **Batch 1** (no dependencies): `organizations`, `apps`
specs/01-DATABASE-SCHEMA.md:1645:- **Batch 3** (depends on Batch 2): `store_domains`, `store_users`, `store_settings`, `customers`, `themes`, `pages`, `navigation_menus`, `search_settings`, `shipping_zones`, `tax_settings`, `discounts`, `products`, `collections`, `app_installations`, `oauth_clients`
specs/01-DATABASE-SCHEMA.md:1646:- **Batch 4** (depends on Batch 3): `product_options`, `product_variants`, `product_media`, `collection_products`, `customer_addresses`, `carts`, `navigation_items`, `theme_files`, `theme_settings`, `search_queries`, `shipping_rates`, `oauth_tokens`, `webhook_subscriptions`
specs/01-DATABASE-SCHEMA.md:1647:- **Batch 5** (depends on Batch 4): `product_option_values`, `inventory_items`, `cart_lines`, `checkouts`, `orders`, `analytics_events`, `analytics_daily`, `webhook_deliveries`
specs/01-DATABASE-SCHEMA.md:1661:4. **Composite primary keys for pivot tables** - Tables like `store_users`, `collection_products`, `variant_option_values`, and `analytics_daily` use composite primary keys to naturally enforce uniqueness and serve as their own covering index for the most common query pattern.
specs/01-DATABASE-SCHEMA.md:1663:5. **Date-based indexes for time series** - Tables with temporal queries (orders, analytics, search queries, webhook deliveries) include indexes on date/timestamp columns scoped by store for efficient range scans.
specs/01-DATABASE-SCHEMA.md:1676:| 4 - Search | search_settings, search_queries | 2 |
specs/01-DATABASE-SCHEMA.md:1679:| 7 - Analytics | analytics_events, analytics_daily | 2 |
specs/01-DATABASE-SCHEMA.md:1680:| 8 - Apps and Webhooks | apps, app_installations, oauth_clients, oauth_tokens, webhook_subscriptions, webhook_deliveries | 6 |
specs/05-BUSINESS-LOGIC.md:80:products, collections, customers, orders, carts, checkouts, discounts, shipping_zones, themes, pages, navigation_menus, analytics_events, analytics_daily, webhook_subscriptions, inventory_items, search_queries.
specs/05-BUSINESS-LOGIC.md:96:| Manage apps | Yes | Yes | No | No |
specs/05-BUSINESS-LOGIC.md:97:| View analytics | Yes | Yes | Yes | No |
specs/05-BUSINESS-LOGIC.md:933:The platform uses a **Mock Payment Service Provider (PSP)** instead of real payment gateways. All payment processing happens in-process with no external API calls, no webhooks, and no redirects. This enables a fully functional checkout flow for development, testing, and demonstration purposes.
specs/05-BUSINESS-LOGIC.md:1434:**Endpoint:** `POST /api/storefront/v1/analytics/events`
specs/05-BUSINESS-LOGIC.md:1475:- Aggregates the previous day's raw `analytics_events` into `analytics_daily`.
specs/05-BUSINESS-LOGIC.md:1539:| `store_id` | No (UNINDEXED) | Used for filtering, not searching |
specs/05-BUSINESS-LOGIC.md:1541:| `title` | Yes | Product title, fully searchable |
specs/05-BUSINESS-LOGIC.md:1569:PROCEDURE search(store, queryString, limit = 20):
specs/05-BUSINESS-LOGIC.md:1584:Each search query is logged to `search_queries` with: store_id, query text, results_count, created_at. This data feeds into analytics and can inform autocomplete suggestions.
specs/05-BUSINESS-LOGIC.md:1594:| `OrderCreated` | Send confirmation email, dispatch webhooks (`order.created`), log analytics event |
specs/05-BUSINESS-LOGIC.md:1595:| `OrderRefunded` | Send refund notification email, dispatch webhooks (`order.refunded`), optionally restock |
specs/05-BUSINESS-LOGIC.md:1598:| `CheckoutCompleted` | Dispatch webhooks (`checkout.completed`) |
specs/05-BUSINESS-LOGIC.md:1601:| `ProductCreated` | Sync FTS5 index, dispatch webhooks (`product.created`) |
specs/05-BUSINESS-LOGIC.md:1602:| `ProductUpdated` | Sync FTS5 index, dispatch webhooks (`product.updated`) |
specs/05-BUSINESS-LOGIC.md:1603:| `ProductDeleted` | Remove from FTS5 index, dispatch webhooks (`product.deleted`) |
specs/05-BUSINESS-LOGIC.md:1606:| `FulfillmentShipped` | Send shipping notification email with tracking info, dispatch webhooks (`order.fulfilled` if fully fulfilled) |
specs/05-BUSINESS-LOGIC.md:1607:| `FulfillmentDelivered` | Update fulfillment record, dispatch webhooks |
specs/05-BUSINESS-LOGIC.md:1620:| `App\Jobs\AggregateAnalytics` | Daily at 01:00 UTC | Roll up raw analytics events into daily aggregates |
specs/05-BUSINESS-LOGIC.md:1655:| SearchService | `App\Services` | FTS5 search queries |
specs/04-STOREFRONT-UI.md:52:| Pages | Core storefront pages | home, collection, product, cart, search, page (static CMS) |
specs/04-STOREFRONT-UI.md:145:| Search Icon | Right group | Button that opens the search modal |
specs/04-STOREFRONT-UI.md:473:The product card is a reusable component used on collection pages, search results, and featured products sections.
specs/04-STOREFRONT-UI.md:547:| Icon | Large, muted search icon |
specs/04-STOREFRONT-UI.md:1414:Triggered by clicking the search icon in the header.
specs/04-STOREFRONT-UI.md:1436:| Search input | Large text, search icon prefix, autofocus on open. Live binding with 300ms debounce |
specs/04-STOREFRONT-UI.md:1441:| View all | Link at the bottom navigating to the full search results page |
specs/04-STOREFRONT-UI.md:1448:### 11.2 Search Results Page (GET /search?q=)
specs/04-STOREFRONT-UI.md:1462:| Empty state | "No results found for '{query}'. Try a different search term." with a search input to try again |
specs/04-STOREFRONT-UI.md:1501:| Search | Simple input + button, submits to search page |
specs/04-STOREFRONT-UI.md:1572:| Screen reader text | Visually hidden text for icon-only buttons (close, cart, search) |
specs/04-STOREFRONT-UI.md:1734:| SearchModal | Layout (global) | Autocomplete search overlay |
specs/04-STOREFRONT-UI.md:1735:| SearchResults | Search page | Full search results with filters |
specs/04-STOREFRONT-UI.md:1751:| open-search-modal | Header search icon click | SearchModal | None |
specs/04-STOREFRONT-UI.md:1752:| close-search-modal | SearchModal close actions | SearchModal | None |
specs/02-API-ROUTES.md:48:| GET | `/admin/products` | Product list - searchable, filterable by status, bulk actions | `Admin\Products\Index` |
specs/02-API-ROUTES.md:121:| GET | `/admin/apps` | Apps directory - list installed and available apps | `Admin\Apps\Index` |
specs/02-API-ROUTES.md:122:| GET | `/admin/apps/{installation}` | Installed app detail - scopes, webhooks, usage | `Admin\Apps\Show` |
specs/02-API-ROUTES.md:136:| GET | `/admin/analytics` | Analytics dashboard - sales, traffic, funnel, exports | `Admin\Analytics\Index` |
specs/02-API-ROUTES.md:142:| GET | `/admin/search/settings` | Search settings - synonyms, stopwords, reindex | `Admin\Search\Settings` |
specs/02-API-ROUTES.md:159:| GET | `/search` | Search results page with filter panel, sort dropdown, product grid | `Storefront\Search\Index` |
specs/02-API-ROUTES.md:203:These endpoints power the interactive storefront experience (cart drawer, checkout flow, search autocomplete, analytics).
specs/02-API-ROUTES.md:850:Process payment for a checkout using the selected payment method. All payment processing happens in-process via the Mock PSP - no external API calls, no redirects, no webhooks.
specs/02-API-ROUTES.md:1019:#### GET /api/storefront/v1/search
specs/02-API-ROUTES.md:1024:- **Rate limit:** `search` (30/min per IP)
specs/02-API-ROUTES.md:1097:#### GET /api/storefront/v1/search/suggest
specs/02-API-ROUTES.md:1102:- **Rate limit:** `search` (30/min per IP)
specs/02-API-ROUTES.md:1143:#### POST /api/storefront/v1/analytics/events
specs/02-API-ROUTES.md:1145:Batch submit storefront analytics events.
specs/02-API-ROUTES.md:1148:- **Rate limit:** `analytics` (60/min per IP)
specs/02-API-ROUTES.md:1186:| `events[].type` | string | Yes | One of: `page_view`, `add_to_cart`, `remove_from_cart`, `checkout_started`, `checkout_completed`, `search`. |
specs/02-API-ROUTES.md:1212:These endpoints provide programmatic access for integrations, CLI tools, and third-party apps. The admin web UI uses Livewire actions directly and does not call these endpoints.
specs/02-API-ROUTES.md:2719:| POST | `/api/admin/v1/stores/{storeId}/search/reindex` | `write-settings` | Trigger full search reindex (async) | `api.admin` (60/min) |
specs/02-API-ROUTES.md:2720:| GET | `/api/admin/v1/stores/{storeId}/search/status` | `read-settings` | Get current search index status | `api.admin` (60/min) |
specs/02-API-ROUTES.md:2722:#### POST /api/admin/v1/stores/{storeId}/search/reindex
specs/02-API-ROUTES.md:2724:Trigger a full search reindex for the store. Runs asynchronously via a queued job.
specs/02-API-ROUTES.md:2743:#### GET /api/admin/v1/stores/{storeId}/search/status
specs/02-API-ROUTES.md:2745:Get the current search index status.
specs/02-API-ROUTES.md:2770:| GET | `/api/admin/v1/stores/{storeId}/analytics/summary` | `read-analytics` | Get analytics summary for date range | `api.admin` (60/min) |
specs/02-API-ROUTES.md:2774:#### GET /api/admin/v1/stores/{storeId}/analytics/summary
specs/02-API-ROUTES.md:2776:Get analytics summary for a date range.
specs/02-API-ROUTES.md:2899:> **Note:** No inbound webhook endpoints are needed. All payment processing happens in-process via the Mock PSP -- there are no external payment provider callbacks. The webhook infrastructure defined in this section is reserved for **outbound** app webhooks (see Section 5, OAuth / App Ecosystem).
specs/02-API-ROUTES.md:2907:These endpoints implement OAuth2 authorization for third-party apps, powered by Laravel Passport.
specs/02-API-ROUTES.md:2979:Third-party apps use OAuth tokens to access store data via scoped endpoints.
specs/02-API-ROUTES.md:2983:| GET | `/api/apps/v1/stores/{storeId}/products` | `read-products` | List products (same schema as admin API) |
specs/02-API-ROUTES.md:2984:| GET | `/api/apps/v1/stores/{storeId}/orders` | `read-orders` | List orders |
specs/02-API-ROUTES.md:2985:| GET | `/api/apps/v1/stores/{storeId}/customers` | `read-customers` | List customers |
specs/02-API-ROUTES.md:3084:| `search` | 30 requests | 1 minute | IP address | Search and autocomplete endpoints |
specs/02-API-ROUTES.md:3085:| `analytics` | 60 requests | 1 minute | IP address | Analytics event ingestion |
specs/02-API-ROUTES.md:3086:| `webhooks` | 100 requests | 1 minute | IP address | Reserved for future outbound app webhook endpoints |
specs/02-API-ROUTES.md:3123:| `GET /api/storefront/v1/search` | `search` |
specs/02-API-ROUTES.md:3124:| `GET /api/storefront/v1/search/suggest` | `search` |
specs/02-API-ROUTES.md:3125:| `POST /api/storefront/v1/analytics/events` | `analytics` |
specs/02-API-ROUTES.md:3173:- **App API:** Versioned via URL path (`/api/apps/v1/`).
specs/09-IMPLEMENTATION-ROADMAP.md:17:| Search | Elasticsearch + Scout | SQLite FTS5 | Self-contained, no external service |
specs/09-IMPLEMENTATION-ROADMAP.md:24:| OAuth (apps) | Passport | Deferred/Stubbed | Simplifies initial build, can add later |
specs/09-IMPLEMENTATION-ROADMAP.md:47:    P7[Phase 7: Admin Panel]
specs/09-IMPLEMENTATION-ROADMAP.md:176:Applied on: products, collections, customers, orders, carts, checkouts, discounts, shipping_zones, themes, pages, navigation_menus, analytics_events, analytics_daily, webhook_subscriptions, inventory_items, search_queries.
specs/09-IMPLEMENTATION-ROADMAP.md:237:| Manage apps | Y | Y | N | N |
specs/09-IMPLEMENTATION-ROADMAP.md:238:| View analytics | Y | Y | Y | N |
specs/09-IMPLEMENTATION-ROADMAP.md:401:| `pages/` | `home.blade.php`, `collection.blade.php`, `product.blade.php`, `cart.blade.php`, `search.blade.php`, `page.blade.php` |
specs/09-IMPLEMENTATION-ROADMAP.md:672:- No external API calls, no webhooks, no redirects
specs/09-IMPLEMENTATION-ROADMAP.md:773:### Phase 7: Admin Panel
specs/09-IMPLEMENTATION-ROADMAP.md:807:| `Admin\Products\Index` | Product list with search, status filter, bulk actions (archive, delete), pagination |
specs/09-IMPLEMENTATION-ROADMAP.md:822:| `Admin\Orders\Index` | Order list with status filters, search by order number/email, date range |
specs/09-IMPLEMENTATION-ROADMAP.md:836:| `Admin\Customers\Index` | Customer list with search |
specs/09-IMPLEMENTATION-ROADMAP.md:862:1. `create_search_settings_table` - PK: `store_id`
specs/09-IMPLEMENTATION-ROADMAP.md:863:2. `create_search_queries_table` - FK: `store_id`
specs/09-IMPLEMENTATION-ROADMAP.md:872:| `search(Store $store, string $query, array $filters, int $perPage): LengthAwarePaginator` | FTS5 query with store scoping |
specs/09-IMPLEMENTATION-ROADMAP.md:873:| `autocomplete(Store $store, string $prefix, int $limit): Collection` | Prefix matching for search-as-you-type |
specs/09-IMPLEMENTATION-ROADMAP.md:886:| `Storefront\Search\Index` | Full search results page with filters (vendor, price range, collection), sort (relevance, price, newest), pagination |
specs/09-IMPLEMENTATION-ROADMAP.md:896:1. `create_analytics_events_table` - FK: `store_id`, `customer_id`
specs/09-IMPLEMENTATION-ROADMAP.md:897:2. `create_analytics_daily_table` - composite PK: `store_id` + `date`
specs/09-IMPLEMENTATION-ROADMAP.md:908:Event types: `page_view`, `product_view`, `add_to_cart`, `remove_from_cart`, `checkout_started`, `checkout_completed`, `search`.
specs/09-IMPLEMENTATION-ROADMAP.md:914:- Aggregates raw events into `analytics_daily` rows
specs/09-IMPLEMENTATION-ROADMAP.md:925:1. `create_apps_table`
specs/09-IMPLEMENTATION-ROADMAP.md:1217:| searches products by title | product titled "Organic Cotton Hoodie"; search "cotton" | product found in results | happy path |
specs/09-IMPLEMENTATION-ROADMAP.md:1570:| returns products matching search query | products: "Blue Cotton T-Shirt", "Red Wool Sweater"; search "cotton" | finds "Blue Cotton T-Shirt" | happy path |
specs/09-IMPLEMENTATION-ROADMAP.md:1571:| scopes search to current store | store A has "T-Shirt", store B has "T-Shirt Deluxe"; search "t-shirt" on store A | only store A product returned | authorization |
specs/09-IMPLEMENTATION-ROADMAP.md:1572:| returns empty for no matches | search "xyznonexistent" | empty results | edge case |
specs/09-IMPLEMENTATION-ROADMAP.md:1573:| logs search query for analytics | perform search | search_queries row created | happy path |
specs/09-IMPLEMENTATION-ROADMAP.md:1574:| paginates search results | 25 matching products, 12 per page | page 1 has 12, page 2 has 12, page 3 has 1 | happy path |
specs/09-IMPLEMENTATION-ROADMAP.md:1592:| tracks a page view event | POST analytics event: type=page_view | analytics_events row created | happy path |
specs/09-IMPLEMENTATION-ROADMAP.md:1604:| aggregates daily metrics from raw events | create events: 5 page_views, 3 add_to_carts, 2 checkout_completed; run AggregateAnalytics job | analytics_daily row with correct counts | happy path |
specs/09-IMPLEMENTATION-ROADMAP.md:1606:| runs idempotently | run aggregation twice for same date | analytics_daily row has correct values (not doubled) | edge case |
specs/09-IMPLEMENTATION-ROADMAP.md:1736:| `AnalyticsEvent` | Raw analytics event |
specs/09-IMPLEMENTATION-ROADMAP.md:1737:| `AnalyticsDaily` | Pre-aggregated daily analytics |
specs/09-IMPLEMENTATION-ROADMAP.md:1738:| `SearchSettings` | Per-store search configuration |
specs/09-IMPLEMENTATION-ROADMAP.md:1848:| `AggregateAnalytics` | Daily analytics aggregation |
specs/09-IMPLEMENTATION-ROADMAP.md:1944:- Configure rate limiters: `login` (5/min per IP), `api.admin` (60/min per token), `api.storefront` (120/min per IP), `checkout` (10/min per session), `search` (30/min per IP), `analytics` (60/min per IP), `webhooks` (100/min per IP)
specs/03-ADMIN-UI.md:95:Analytics                        -> admin.analytics.index
specs/03-ADMIN-UI.md:97:Apps                             -> admin.apps.index
specs/03-ADMIN-UI.md:232:| `loadKpis()` | Queries aggregated order/analytics data |
specs/03-ADMIN-UI.md:349:| `search` | `string` | Search query, live-debounced at 300ms |
specs/03-ADMIN-UI.md:371:| `products` | Paginated query result with search, filters, sorting applied. Eager loads `variants`, `media` (limit 1). Uses `withCount('variants')`. |
specs/03-ADMIN-UI.md:380:| [search icon] Search products...   [Status: All v] [Type: All v] |
specs/03-ADMIN-UI.md:714:| `search` | `string` | Search query |
specs/03-ADMIN-UI.md:724:| `collections` | Paginated, filtered, searched. Includes `withCount('products')`. |
specs/03-ADMIN-UI.md:773:| `searchResults` | Products matching `productSearch` that are not already assigned |
specs/03-ADMIN-UI.md:831:| `search` | `string` | Search by product title or SKU |
specs/03-ADMIN-UI.md:836:| `inventoryItems` | Paginated inventory items with variant and product eager loaded, filtered by search and stock level |
specs/03-ADMIN-UI.md:844:| [search] Search by product or SKU   [Stock: All v]               |
specs/03-ADMIN-UI.md:874:| `search` | `string` | Search by order number or customer email |
specs/03-ADMIN-UI.md:887:| `orders` | Paginated query with search, status filter, sorting. Eager loads `customer`. |
specs/03-ADMIN-UI.md:895:| [search] Search by order # or email...                           |
specs/03-ADMIN-UI.md:1148:| `search` | `string` | Search by name or email |
specs/03-ADMIN-UI.md:1152:| `customers` | Paginated, searched customers with `withCount('orders')` and `withSum('orders', 'total_amount')` |
specs/03-ADMIN-UI.md:1247:| `search` | `string` | Search by discount code |
specs/03-ADMIN-UI.md:1361:- Specific products: search input with live debounce. Results appear in a scrollable dropdown. Selected products shown as a list with remove (X) buttons.
specs/03-ADMIN-UI.md:1759:|            |  |                        | |  Show search:        |
specs/03-ADMIN-UI.md:1817:| `search` | `string` | Search by page title |
specs/03-ADMIN-UI.md:1959:**Route:** `GET /admin/apps`
specs/03-ADMIN-UI.md:1963:**Blade view:** `resources/views/livewire/admin/apps/index.blade.php`
specs/03-ADMIN-UI.md:2005:**Empty state:** "No apps installed" with descriptive text.
specs/03-ADMIN-UI.md:2022:| `webhooks` | `Collection` | Webhook subscriptions |
specs/03-ADMIN-UI.md:2117:- Endpoint URL input (type: url, placeholder: "https://example.com/webhooks")
specs/03-ADMIN-UI.md:2124:**Route:** `GET /admin/analytics`
specs/03-ADMIN-UI.md:2128:**Blade view:** `resources/views/livewire/admin/analytics/index.blade.php`
specs/03-ADMIN-UI.md:2151:| `updatedDateRange()` | Reloads analytics data |
specs/03-ADMIN-UI.md:2154:| `loadAnalytics()` | Master method to reload all analytics data |
specs/03-ADMIN-UI.md:2211:**Route:** `GET /admin/search/settings`
specs/03-ADMIN-UI.md:2215:**Blade view:** `resources/views/livewire/admin/search/settings.blade.php`
specs/03-ADMIN-UI.md:2252:| Words that are excluded from search indexing.                    |
specs/03-ADMIN-UI.md:2425:| `App\Livewire\Admin\Apps\Index` | `livewire.admin.apps.index` | `GET /admin/apps` |
specs/03-ADMIN-UI.md:2427:| `App\Livewire\Admin\Analytics\Index` | `livewire.admin.analytics.index` | `GET /admin/analytics` |
specs/03-ADMIN-UI.md:2428:| `App\Livewire\Admin\Search\Settings` | `livewire.admin.search.settings` | `GET /admin/search/settings` |


output:
Chunk ID: 11428b
Wall time: 0.0000 seconds
Process exited with code 0
Original token count: 9419
Output:
# Shop Build Progress

## Objective

Build a complete, self-contained Laravel shop system from `specs/*`, with implemented acceptance criteria mapped to evidence, passing automated checks, verified browser flows, independent QA, and meaningful commits.

## Current Status

- Status: in progress
- Active slice: Phase 7 - search/analytics/apps/webhooks
- Started from: Laravel Livewire/Fortify starter kit with no shop domain tables or models present
- Last updated: 2026-05-04

## Phased Plan

1. Foundation: SQLite config, tenancy tables/models/factories/seeders, store resolution middleware, store scoping, admin/customer auth foundations, policies, and Phase 1 tests.
2. Catalog: product, variant, inventory, collection, media schema/models/services, admin catalog CRUD, storefront browsing, and tests.
3. Storefront theme/layout: theme/page/navigation data, storefront layout, product/collection/search/page views, and smoke browser verification.
4. Cart/checkout/pricing: cart API/UI, discount, shipping, tax, checkout state machine, and tests.
5. Payments/orders/fulfillment: mock PSP, order creation, refunds, fulfillments, customer account order views, and tests.
6. Admin panel: dashboard and all admin list/form/detail pages from Spec 03, with Livewire/Flux interactions.
7. Search/analytics/apps/webhooks: SQLite search, event aggregation, developer token/webhook UI, delivery jobs, and tests.
8. Final verification: full Pest suite, Pint, frontend build, Playwright MCP customer/admin flows, independent QA, fixes, and completion audit.

## Acceptance Checklist

| Area | Criteria Source | Status | Evidence |
| --- | --- | --- | --- |
| Database schema | `specs/01-DATABASE-SCHEMA.md` | partial | Phase 1 tenancy/auth tables, Phase 2 catalog tables, Phase 3 theme/content/navigation tables, Phase 4 cart/checkout/pricing tables, and Phase 5 order/payment/fulfillment tables are implemented: customer_addresses, orders, order_lines, payments, refunds, fulfillments, fulfillment_lines. Search/analytics/app tables are still missing. |
| Routes/API | `specs/02-API-ROUTES.md` | partial | Phase 1 auth routes plus catalog/cart/order/customer/discount/content/settings UI routes exist: `/`, `/collections`, `/collections/{handle}`, `/products/{handle}`, `/cart`, `/checkout`, `/checkout/confirmation/{order}`, `/search`, `/pages/{handle}`, `/account`, `/account/orders/{order}`, `/admin/products`, `/admin/products/create`, `/admin/products/{product}/edit`, `/admin/collections`, `/admin/collections/create`, `/admin/collections/{collection}/edit`, `/admin/inventory`, `/admin/orders`, `/admin/orders/{order}`, `/admin/customers`, `/admin/customers/{customer}`, `/admin/discounts`, `/admin/discounts/create`, `/admin/discounts/{discount}/edit`, `/admin/pages`, `/admin/pages/create`, `/admin/pages/{page}/edit`, `/admin/navigation`, `/admin/themes`, `/admin/themes/{theme}/editor`, `/admin/settings`, `/admin/settings/shipping`, `/admin/settings/taxes`. Storefront REST API now includes cart line CRUD, checkout address/shipping/discount/payment-method selection, checkout payment completion, and token-gated order lookup under `/api/storefront/v1`. Admin REST API now includes store-scoped order list/detail, fulfillment creation, and refund creation under `/api/admin/v1/stores/{store}`. Storefront search/suggest, analytics, app/webhook APIs, and broader admin REST surfaces are still missing. |
| Admin UI | `specs/03-ADMIN-UI.md` | partial | Flux/Livewire admin shell now includes dashboard KPI/date-range reporting, catalog/product/collection/inventory management, order/customer/discount management, page index/form, navigation menu editor, theme grid, theme settings editor with iframe preview, general settings, domain management, shipping zone/rate management, and tax settings with auth protection and store scoping. Analytics/search/apps admin surfaces, checkout/notification settings tabs, advanced theme file editing, and product media upload UI are still missing. |
| Storefront UI | `specs/04-STOREFRONT-UI.md` | partial | Storefront layout, home, collections index/detail, product detail, search, breadcrumbs, price display, product cards, DB-backed pages, seeded navigation menus, cached theme settings, product add-to-cart persistence, cart drawer, cart page with discount and shipping estimates, checkout address/shipping/discount/payment-selection/order-submission UI, order confirmation, and customer order list/detail views render seeded and runtime data. |
| Business logic | `specs/05-BUSINESS-LOGIC.md` | partial | `ResolveStore`, `BelongsToStore`, `StoreScope`, role checks, customer guard provider, catalog product lifecycle transitions, SKU uniqueness, variant matrix rebuilding, inventory reserve/release/commit/restock, automatic variant inventory, variant option mapping, media resize/cleanup job, `CartService`, `DiscountService`, `ShippingCalculator`, `TaxCalculator`, `PricingEngine`, checkout transitions through completion, checkout expiration, abandoned cart cleanup, session cart lookup, cart discount handoff to checkout, customer login cart merge, product add-to-cart mutations, `PaymentService`, mock PSP, idempotent order creation, checkout UI/API order submission, session/customer/token-gated order confirmation and lookup, customer order-history scoping, admin dashboard order aggregates, admin customer address management, admin discount rule management, admin content/theme/navigation/settings orchestration, admin order UI/API action orchestration, `RefundService`, `FulfillmentService`, bank-transfer payment confirmation, and unpaid bank-transfer cancellation are implemented. |
| Auth/security | `specs/06-AUTH-AND-SECURITY.md` | partial | Admin Livewire login/logout, customer guard/provider, customer login/register, login rate limiting, session hardening, and resource policies implemented. Customer password reset and Sanctum token auth still missing. |
| Seed/test data | `specs/07-SEEDERS-AND-TEST-DATA.md` | partial | Seeders create Acme Fashion and Acme Electronics stores/domains/settings/admin access, 6 collections, 25 products, 127 variants, 127 inventory rows, 206 variant option pivots, 2 themes, 6 theme files, 2 theme settings rows, 6 pages, 4 navigation menus, 17 navigation items, 2 tax settings rows, 2 shipping zones, 6 shipping rates, 6 discounts, and no product media/runtime carts. Order/payment seed data is still missing. |
| Browser E2E plan | `specs/08-PLAYWRIGHT-E2E-PLAN.md` | partial | Manual Playwright MCP smoke coverage has verified storefront catalog browsing, product detail, add-to-cart, cart drawer/page, checkout through order completion, order confirmation, customer order list/detail, search, DB-backed content pages, seeded navigation, admin dashboard on desktop/mobile, admin product/collection/inventory/order/customer/discount/content/navigation/settings/theme pages, admin customer address creation, admin discount creation/editing/filtering, admin page creation, admin navigation item creation/save, admin theme editor preview, admin fulfillment creation/shipping/delivery, and auth flows without console warnings/errors on successful pages. Automated browser tests are still missing. |
| Roadmap phases | `specs/09-IMPLEMENTATION-ROADMAP.md` | in progress | Phase 1 foundation, Phase 2 catalog data/UI, Phase 3 theme/content/navigation data with storefront consumption, Phase 4 cart/checkout/pricing backend foundation, Phase 4 storefront cart/checkout UI through `payment_selected`, the Phase 4 cart/checkout REST API surface, cart-page estimates, Phase 5 order/payment backend foundation, Phase 5 refund/fulfillment services, Phase 5 storefront order completion/customer order surfaces, Phase 5 admin order management, Phase 5 order API surfaces, and Phase 6 admin dashboard/customer/discount/content/settings/theme/navigation management are implemented. Phase 7 search/analytics/apps/webhooks surfaces are next. |

## Verification Evidence

- 2026-05-03: `mcp__laravel_boost__.application_info` confirmed PHP 8.4, Laravel 12.51.0, Livewire 4.1.4, Flux 2.12.0, Pest 4.3.2, SQLite.
- 2026-05-03: `mcp__laravel_boost__.database_schema(summary: true)` returned no tables for the current configured database.
- 2026-05-03: `git status --short` showed no current worktree changes before implementation.
- 2026-05-03: `mcp__laravel_boost__.search_docs` consulted Laravel 12 middleware/auth/authorization/migration docs plus Livewire 4 and Pest 4 docs before code changes.
- 2026-05-03: Planning challenger sub-agent found the repo was still a starter kit and produced the acceptance checklist by vertical slice. Risks added here: missing Sanctum dependency, password_hash/Fortify coordination, route/API absence, and E2E count inconsistencies.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed on real `database/database.sqlite` after creating the missing SQLite file.
- 2026-05-03: `php artisan test --compact` passed: 45 tests, 121 assertions.
- 2026-05-03: `vendor/bin/pint --dirty --format agent` passed after formatting changes.
- 2026-05-03: `php artisan route:list --path=admin` showed `/admin`, `/admin/login`, `/admin/logout`; `php artisan route:list --path=account` showed `/account`, `/account/login`, `/account/register`.
- 2026-05-03: Boost schema summary confirmed Phase 1 tables: organizations, stores, store_domains, store_users, store_settings, customers, customer_password_reset_tokens, users with password_hash.
- 2026-05-03: Playwright MCP verified `http://shop.test/` loads, `http://shop.test/admin/login` renders, admin login with `admin@acme.test` / `password` reaches `/admin`, `http://shop.test/account/login` renders with no console warnings/errors after the Livewire layout fix, and customer login with `customer@acme.test` / `password` reaches `/account`.
- 2026-05-03: Independent Phase 2 QA agents reported no critical findings. High findings on lifecycle bypass, child tenant scoping, inventory store mismatch, variant option mapping, simplified seed data, and media status-only processing were addressed in the catalog data layer.
- 2026-05-03: `php artisan test --compact tests/Feature/Catalog` passed: 19 tests, 71 assertions.
- 2026-05-03: `php artisan test --compact` passed: 64 tests, 192 assertions.
- 2026-05-03: `vendor/bin/pint --dirty --format agent` fixed import/order/spacing, followed by passing catalog and full Pest suites.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed after the Phase 2 seed update.
- 2026-05-03: Boost schema summary confirmed Phase 2 catalog tables. Boost query counts after fresh seed: stores 2, products 25, variants 127, inventory_items 127, collections 6, product_media 0, variant_option_values 206.
- 2026-05-03: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page component routing/testing docs and Flux UI form/input/select/checkbox/button docs before catalog UI changes.
- 2026-05-03: `php artisan route:list --path=admin` showed 10 admin routes including product, collection, and inventory catalog pages. `php artisan route:list --path=collections`, `--path=products`, `--path=search`, and `--path=pages` showed storefront catalog/content routes.
- 2026-05-03: `php artisan test --compact tests/Feature/Catalog/CatalogUiTest.php` passed: 4 tests, 44 assertions.
- 2026-05-03: `php artisan test --compact tests/Feature/Catalog` passed: 23 tests, 115 assertions.
- 2026-05-03: `php artisan test --compact` passed: 68 tests, 236 assertions.
- 2026-05-03: `vendor/bin/pint --dirty --format agent` passed after formatting catalog UI changes.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed after catalog UI test changes.
- 2026-05-03: `npm run build` passed with Vite production assets generated under ignored `public/build`.
- 2026-05-03: Playwright MCP verified `http://shop.test/`, `/collections/t-shirts`, `/products/classic-cotton-t-shirt`, `/search?q=Cotton`, `/pages/about`, `/admin/products`, `/admin/products/create`, `/admin/collections`, and `/admin/inventory` render with no console warnings/errors.
- 2026-05-03: `mcp__laravel_boost__.search_docs` consulted Laravel 12 migration/model/factory/seeder/cache docs and Pest 4 database testing docs before Phase 3 data-layer changes.
- 2026-05-03: Phase 3 explorer QA confirmed the required theme/page/navigation migrations, models, enums, factories, seeders, services, and tests; noted the spec tree-navigation mismatch because `navigation_items` has no `parent_id`.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed after adding Phase 3 migrations and seeders.
- 2026-05-03: Boost schema summaries confirmed Phase 3 tables: themes, theme_files, theme_settings, pages, navigation_menus, navigation_items. Boost query counts after fresh seed: themes 2, theme_files 6, theme_settings 2, pages 6, navigation_menus 4, navigation_items 17.
- 2026-05-03: `php artisan test --compact tests/Feature/Storefront/ThemeDataTest.php` passed: 6 tests, 31 assertions.
- 2026-05-03: `php artisan test --compact tests/Feature/Storefront tests/Feature/Catalog` passed: 29 tests, 146 assertions.
- 2026-05-03: `php artisan test --compact` passed: 74 tests, 267 assertions.
- 2026-05-03: `vendor/bin/pint --dirty --format agent` passed after Phase 3 changes.
- 2026-05-03: `npm run build` passed after Phase 3 layout changes.
- 2026-05-03: Playwright MCP verified `http://shop.test/` renders seeded main navigation and `http://shop.test/pages/faq` renders DB-backed page content with no console warnings/errors.
- 2026-05-03: `mcp__laravel_boost__.search_docs` consulted Laravel 12 migration/job/scheduling/transaction docs and Pest 4 database testing docs before Phase 4 backend changes.
- 2026-05-03: Phase 4 explorer QA mapped the cart, checkout, discount, shipping, tax, pricing, and cleanup-job boundary; order creation/payment capture were kept for Phase 5 because order/payment tables are not implemented yet.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed after adding Phase 4 migrations and seeders.
- 2026-05-03: Boost schema summary confirmed Phase 4 tables: carts, cart_lines, checkouts, shipping_zones, shipping_rates, tax_settings, discounts. Boost query counts after fresh seed: carts 0, cart_lines 0, checkouts 0, shipping_zones 2, shipping_rates 6, tax_settings 2, discounts 6.
- 2026-05-03: `php artisan test --compact tests/Feature/Cart tests/Feature/Checkout` passed: 11 tests, 55 assertions.
- 2026-05-03: `vendor/bin/pint --dirty --format agent` fixed checkout/pricing style and import order, then passed after job test coverage was added.
- 2026-05-03: `php artisan test --compact` passed: 85 tests, 322 assertions.
- 2026-05-03: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page components, forms, validation, session, events, redirects, Flux modal/form controls, and Pest docs before Phase 4 cart/checkout UI changes.
- 2026-05-03: `php artisan route:list --path=cart` and `php artisan route:list --path=checkout` confirmed `/cart` and `/checkout` Livewire routes.
- 2026-05-03: `php artisan test --compact tests/Feature/Storefront/CartCheckoutUiTest.php` passed: 4 tests, 19 assertions.
- 2026-05-03: `php artisan test --compact tests/Feature/Storefront tests/Feature/Cart tests/Feature/Checkout tests/Feature/Catalog tests/Feature/Foundation/CustomerAuthTest.php` passed: 47 tests, 236 assertions.
- 2026-05-03: `vendor/bin/pint --dirty --format agent` passed after Phase 4 UI changes.
- 2026-05-03: `php artisan test --compact` passed: 89 tests, 341 assertions.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed after the Phase 4 UI changes.
- 2026-05-03: `npm run build` passed after the cart/checkout Blade changes.
- 2026-05-03: Playwright MCP verified `http://shop.test/products/classic-cotton-t-shirt` add-to-cart, `http://shop.test/cart`, and `http://shop.test/checkout` render and progress through shipping, discount, and reserve-items payment selection with Livewire update requests returning 200 and no new console warnings/errors. Missing favicon links were fixed with `public/favicon.svg`.
- 2026-05-03: `mcp__laravel_boost__.search_docs` consulted Laravel 12 JSON API tests/resources/form requests/route model binding docs and Pest 4 JSON expectation docs before the Phase 4 API changes.
- 2026-05-03: `php artisan route:list --path=api/storefront/v1` confirmed 12 storefront API routes for carts, cart lines, checkouts, checkout address, shipping method, discount apply/remove, and payment method selection.
- 2026-05-03: `php artisan test --compact tests/Feature/Api/StorefrontCartApiTest.php tests/Feature/Api/StorefrontCheckoutApiTest.php` passed: 6 tests, 73 assertions.
- 2026-05-03: `php artisan test --compact tests/Feature/Api tests/Feature/Cart tests/Feature/Checkout tests/Feature/Storefront` passed: 27 tests, 178 assertions.
- 2026-05-03: `php artisan test --compact` passed after the cart/checkout API changes: 95 tests, 414 assertions.
- 2026-05-03: `php artisan migrate:fresh --seed --no-interaction` passed after the cart/checkout API changes.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 form/computed-property validation docs, Flux input/select/button docs, Laravel validation docs, and Pest docs before the cart estimate UI changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Storefront/CartCheckoutUiTest.php` passed after the cart estimate UI changes: 5 tests, 30 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Storefront tests/Feature/Cart tests/Feature/Checkout tests/Feature/Api` passed after the cart estimate UI changes: 28 tests, 189 assertions.
- 2026-05-04: `npm run build` passed after the cart estimate Blade changes.
- 2026-05-04: Playwright MCP verified `http://shop.test/products/classic-cotton-t-shirt` add-to-cart, `http://shop.test/cart` discount application and shipping rates, and checkout handoff with discounted totals at `http://shop.test/checkout`; Livewire requests returned 200 and browser console had no warnings/errors.
- 2026-05-04: `php artisan test --compact` passed after the cart estimate UI changes: 96 tests, 425 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after the cart estimate UI changes.
- 2026-05-04: `mcp__laravel_boost__.application_info` confirmed Laravel 12.51.0, PHP 8.4, Livewire 4.1.4, Flux 2.12.0, Pest 4.3.2, and SQLite before Phase 5 order/payment changes.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Laravel 12 transaction, enum/encrypted cast, and Pest database testing docs before Phase 5 order/payment changes.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after the Phase 5 order/payment backend foundation changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Payments tests/Feature/Orders` passed after adding mock PSP and order completion coverage: 11 tests, 64 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Cart tests/Feature/Checkout tests/Feature/Payments tests/Feature/Orders` passed after the order completion changes: 22 tests, 119 assertions.
- 2026-05-04: `php artisan test --compact` passed after the Phase 5 order/payment backend foundation: 107 tests, 489 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after adding Phase 5 order/payment/fulfillment migrations and factories.
- 2026-05-04: Boost schema summaries confirmed Phase 5 runtime tables: orders, order_lines, payments, refunds, fulfillments, and fulfillment_lines.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Laravel 12 job/scheduling, transaction, event, relationship aggregate, and Pest testing docs before refund/fulfillment service changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Orders` passed after adding refund, fulfillment, and bank-transfer service coverage: 15 tests, 86 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Cart tests/Feature/Checkout tests/Feature/Payments tests/Feature/Orders` passed after refund/fulfillment changes: 32 tests, 167 assertions.
- 2026-05-04: `php artisan test --compact` passed after refund/fulfillment changes: 117 tests, 537 assertions.
- 2026-05-04: `php artisan schedule:list` confirmed `CancelUnpaidBankTransferOrders` is scheduled daily alongside checkout/cart cleanup jobs.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after refund/fulfillment service changes.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 redirects/forms/testing docs, Flux UI form/button/input docs, Laravel validation/redirect docs, and Pest docs before storefront order-completion UI changes.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after storefront order-completion UI changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Storefront/OrderViewsTest.php` passed: 4 tests, 23 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Storefront tests/Feature/Cart tests/Feature/Checkout tests/Feature/Orders` passed after storefront order-completion changes: 41 tests, 225 assertions.
- 2026-05-04: `php artisan test --compact` passed after storefront order-completion changes: 121 tests, 560 assertions.
- 2026-05-04: `npm run build` passed after checkout confirmation and customer account Blade changes.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after storefront order-completion changes.
- 2026-05-04: `mcp__laravel_boost__.get_absolute_url(path: "/products/classic-cotton-t-shirt")` resolved `http://shop.test/products/classic-cotton-t-shirt` before browser verification.
- 2026-05-04: Playwright MCP verified product add-to-cart through checkout order completion, `http://shop.test/checkout/confirmation/1`, `http://shop.test/account`, and `http://shop.test/account/orders/1`; order number, line item, totals, payment/fulfillment badges, and account order history rendered with no console warnings/errors.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page components/actions/security/testing docs, Flux UI button/modal/form docs, Laravel authorization docs, and Pest docs before admin order-management UI changes.
- 2026-05-04: `php artisan make:livewire Admin/Orders/Index --class --no-interaction`, `php artisan make:livewire Admin/Orders/Show --class --no-interaction`, and `php artisan make:test --pest Admin/OrderManagementTest --no-interaction` created the admin order slice files.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after admin order-management changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin/OrderManagementTest.php` passed: 5 tests, 30 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin tests/Feature/Orders tests/Feature/Catalog/CatalogUiTest.php` passed after admin order-management changes: 24 tests, 160 assertions.
- 2026-05-04: `php artisan route:list --path=admin/orders` confirmed `admin.orders.index` and `admin.orders.show` Livewire routes.
- 2026-05-04: `php artisan test --compact` passed after admin order-management changes: 126 tests, 590 assertions.
- 2026-05-04: `npm run build` passed after admin order Blade/sidebar changes.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after admin order-management changes.
- 2026-05-04: `mcp__laravel_boost__.get_absolute_url(path: "/admin/orders")` resolved `http://shop.test/admin/orders` before browser verification.
- 2026-05-04: Playwright MCP verified a seeded storefront checkout order appears in `http://shop.test/admin/orders`, `http://shop.test/admin/orders/1` shows line items/payments/totals/refund and fulfillment controls, and admin fulfillment creation, mark shipped, and mark delivered work with no current console warnings/errors. `browser_logs` only returned older May 3 auth-page warnings from a previously fixed issue.
- 2026-05-04: `mcp__laravel_boost__.application_info` reconfirmed Laravel 12.51.0, PHP 8.4, Livewire 4.1.4, Flux 2.12.0, Pest 4.3.2, and SQLite before the order API slice.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Laravel 12 JSON API resources, form requests, validation, route model binding, auth/rate limiting, and Pest JSON testing docs before the order API changes.
- 2026-05-04: `php artisan make:controller`, `php artisan make:request`, `php artisan make:resource`, `php artisan make:class`, and `php artisan make:test --pest` created the storefront/admin order API controllers, requests, resources, support token class, and tests.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after the order API changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Api/StorefrontOrderApiTest.php tests/Feature/Api/AdminOrderApiTest.php` passed: 5 tests, 38 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Api tests/Feature/Cart tests/Feature/Checkout tests/Feature/Orders tests/Feature/Payments` passed after the order API changes: 43 tests, 278 assertions.
- 2026-05-04: `php artisan route:list --path=api/storefront/v1 --except-vendor` showed 14 storefront API routes including checkout payment completion and token-gated order lookup.
- 2026-05-04: `php artisan route:list --path=api/admin/v1 --except-vendor` showed 4 admin order API routes for order list/detail, fulfillment creation, and refund creation.
- 2026-05-04: `php artisan test --compact` passed after the order API changes: 131 tests, 628 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after the order API changes.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page/form/testing docs, Flux UI input/select/button/badge docs, Laravel aggregate/query docs, and Pest docs before the admin dashboard changes.
- 2026-05-04: `php artisan make:livewire Admin/Dashboard --class --no-interaction` and `php artisan make:test --pest Admin/DashboardTest --no-interaction` created the admin dashboard slice files.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after the admin dashboard changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin/DashboardTest.php` passed: 2 tests, 13 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin` passed after the admin dashboard changes: 7 tests, 43 assertions.
- 2026-05-04: `php artisan route:list --name=admin.dashboard` confirmed `/admin` is now the Livewire admin dashboard route.
- 2026-05-04: `npm run build` passed after the admin dashboard Blade changes.
- 2026-05-04: `php artisan test --compact` passed after the admin dashboard changes: 133 tests, 641 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after the admin dashboard changes.
- 2026-05-04: `mcp__laravel_boost__.get_absolute_url(path: "/admin")` resolved `http://shop.test/admin` before browser verification.
- 2026-05-04: Playwright MCP verified `http://shop.test/admin` renders the dashboard on desktop and 390px mobile viewports with KPI cards, chart panel, top-products panel, and funnel counters; current Playwright console checks reported no warnings/errors. Boost `browser_logs` only returned older May 3 account-login warnings from a previously fixed issue.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page/pagination/form/testing docs, Flux UI input/select/button/badge/modal/table docs, Laravel relationship aggregate docs, and Pest docs before the admin customer-management changes.
- 2026-05-04: `php artisan make:livewire Admin/Customers/Index --class --no-interaction`, `php artisan make:livewire Admin/Customers/Show --class --no-interaction`, and `php artisan make:test --pest Admin/CustomerManagementTest --no-interaction` created the admin customer slice files.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after the admin customer-management changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin/CustomerManagementTest.php` passed: 4 tests, 26 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin` passed after the admin customer-management changes: 11 tests, 69 assertions.
- 2026-05-04: `php artisan route:list --path=admin/customers` confirmed `admin.customers.index` and `admin.customers.show` Livewire routes.
- 2026-05-04: `npm run build` passed after the customer admin Blade/sidebar changes.
- 2026-05-04: `php artisan test --compact` passed after the admin customer-management changes: 137 tests, 667 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after the admin customer-management changes.
- 2026-05-04: `mcp__laravel_boost__.get_absolute_url(path: "/admin/customers")` resolved `http://shop.test/admin/customers` before browser verification.
- 2026-05-04: Playwright MCP verified `http://shop.test/admin/customers` renders the customer table, seeded customer detail renders at `/admin/customers/1`, and the address modal creates a default address; current Playwright console checks reported no warnings/errors.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page/forms/security/testing/persistent-middleware docs, Flux UI radio/checkbox/input/select/button/badge/table/switch docs, Laravel validation/authorization/email-verification docs, Fortify email-verification docs, and Pest docs before the admin discount-management changes.
- 2026-05-04: `php artisan make:livewire Admin/Discounts/Index --class --no-interaction`, `php artisan make:livewire Admin/Discounts/Form --class --no-interaction`, and `php artisan make:test --pest Admin/DiscountManagementTest --no-interaction` created the admin discount slice files.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after the admin discount-management changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin/DiscountManagementTest.php` passed: 8 tests, 58 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Checkout/PricingServicesTest.php` passed after automatic discount pricing changes: 5 tests, 23 assertions.
- 2026-05-04: `php artisan route:list --name=admin.discounts` confirmed `admin.discounts.index`, `admin.discounts.create`, and `admin.discounts.edit` Livewire routes.
- 2026-05-04: `npm run build` passed after the discount admin Blade/sidebar changes.
- 2026-05-04: `php artisan test --compact` passed after the admin discount-management changes: 147 tests, 733 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after browser verification to restore the local SQLite database to seeded fixtures.
- 2026-05-04: `mcp__laravel_boost__.get_absolute_url(path: "/admin/discounts")` resolved `http://shop.test/admin/discounts` before browser verification.
- 2026-05-04: Playwright MCP verified `http://shop.test/admin/discounts` renders seeded discounts, `/admin/discounts/create` saves a browser-created active code discount through Livewire, the status switch label updates live, `/admin/discounts/{discount}/edit` renders the saved rule controls, search filters to the created discount, the type filter updates the table, Livewire update requests return 200, and current Playwright console checks report no warnings/errors.
- 2026-05-04: `mcp__laravel_boost__.search_docs` consulted Livewire 4 full-page/forms/testing docs, Flux UI input/select/textarea/checkbox/radio/button/table/switch docs, Laravel validation docs, and Pest docs before the admin content/settings/theme/navigation changes.
- 2026-05-04: `php artisan make:livewire` created `Admin/Settings/Index`, `Admin/Settings/Shipping`, `Admin/Settings/Taxes`, `Admin/Pages/Index`, `Admin/Pages/Form`, `Admin/Navigation/Index`, `Admin/Themes/Index`, and `Admin/Themes/Editor`; `php artisan make:test --pest` created `Admin/ContentManagementTest` and `Admin/SettingsManagementTest`.
- 2026-05-04: `vendor/bin/pint --dirty --format agent` passed after the admin content/settings/theme/navigation changes.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin/ContentManagementTest.php` passed: 5 tests, 38 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin/SettingsManagementTest.php` passed: 4 tests, 29 assertions.
- 2026-05-04: `php artisan test --compact tests/Feature/Admin` passed after the admin content/settings/theme/navigation changes: 28 tests, 194 assertions.
- 2026-05-04: `php artisan route:list --name=admin.pages`, `--name=admin.navigation`, `--name=admin.themes`, and `--name=admin.settings` confirmed 9 new Livewire admin routes for pages, navigation, themes, and settings.
- 2026-05-04: `npm run build` passed after the admin content/settings/theme/navigation Blade/sidebar changes.
- 2026-05-04: `php artisan test --compact` passed after the admin content/settings/theme/navigation changes: 156 tests, 800 assertions.
- 2026-05-04: `php artisan migrate:fresh --seed --no-interaction` passed after browser verification to restore the local SQLite database to seeded fixtures.
- 2026-05-04: `mcp__laravel_boost__.get_absolute_url(path: "/admin/pages")` resolved `http://shop.test/admin/pages` before browser verification.
- 2026-05-04: Playwright MCP verified `http://shop.test/admin/pages`, `/admin/pages/create`, `/admin/navigation`, `/admin/settings`, `/admin/settings/shipping`, `/admin/settings/taxes`, `/admin/themes`, and `/admin/themes/1/editor`; browser smoke saved a page, added/saved a navigation item, rendered settings/shipping/tax pages, rendered the theme editor iframe preview, and current Playwright console checks reported no warnings/errors. Boost `browser_logs` only returned older May 3 account-login warnings from a previously fixed issue.

## Decisions

- Follow the roadmap order strictly. Phase 1 is required before catalog, checkout, admin, storefront, and QA flows can be meaningfully implemented.
- Preserve the starter Fortify conventions where they do not conflict with the shop specs.
- Use integer minor units for all money columns and JSON text columns cast through Eloquent as specified.
- Keep `password_hash` as the database column for admin users and customers while exposing `password`/`getAuthPassword()` at the model layer for Fortify/Laravel auth compatibility.
- Seed both `shop.test` and `acme-fashion.test` as storefront domains for the first store so the goal URL and E2E spec URL can both resolve.
- Customer Livewire auth components persist `storeId` from the initial storefront request because Livewire update requests do not run through the original storefront route middleware.
- The seed specification contains an arithmetic conflict: Acme Fashion's per-product variant table sums to 117 variants, while the prose says 107. The implementation follows the concrete per-product table, resulting in 117 Fashion variants and 10 Electronics variants, 127 total.
- Child catalog models without a `store_id` column are tenant-scoped through their parent product relationship. Inventory keeps its denormalized `store_id` and enforces that it matches the variant product store at save time.
- Storefront content pages now resolve from the `pages` table and only published pages are rendered.
- The catalog admin form intentionally blocks active products without a priced variant and duplicate in-store SKUs during UI edits, mirroring service-layer invariants where the current CRUD surface touches product variants directly.
- Navigation tree support is flat for now because the Phase 3 schema defines `navigation_items.position` but no `parent_id`; `NavigationService::buildTree()` returns a flat tree-compatible array with empty children.
- Cart, checkout, and pricing runtime records are not seeded; only deterministic tax, shipping, and discount configuration is seeded. Runtime carts/checkouts are created by services and tests.
- The cart drawer reads the current session/customer cart without creating an empty cart on every storefront render; carts are created on first add-to-cart or checkout/cart service mutation.
- The checkout UI reserves inventory by selecting a payment method, then submits payment through `CheckoutService::completeCheckout()` so failed card payments can release reservations and return customers to payment selection.
- Order confirmation access is allowed for the authenticated owning customer or for the session that just placed the order via `last_order_id`.
- Customer account order list/detail routes use the `customer` guard and reload orders through explicit store/customer constraints.
- The cart REST API exposes `cart_version` as the public optimistic concurrency field while the service layer keeps its `expectedVersion` argument; `expected_version` remains accepted as a compatibility alias in API requests.
- Cart page discount codes are validated with `DiscountService`, saved in session, and applied to the checkout when the customer proceeds.
- Admin discount forms persist minimum purchase, product eligibility, and collection eligibility in the existing `discounts.rules_json` keys consumed by `DiscountService`; `one_per_customer` is captured for future redemption-history enforcement.
- `PricingEngine` applies an explicit checkout discount code first, then active automatic discounts returned by `DiscountService`.
- `orders.checkout_id` is intentionally added beyond the original schema table to enforce idempotent checkout completion without duplicate orders.
- Failed card payments release reserved inventory and move the checkout back to `shipping_selected` so customers can retry payment selection.
- Bank transfer order completion creates a pending order and payment while keeping inventory reserved until the later admin payment-confirmation flow.


command: sed -n '1,160p' /Users/fabianwesner/Herd/shop/.agents/skills/laravel-best-practices/SKILL.md && sed -n '1,140p' /Users/fabianwesner/Herd/shop/.agents/skills/pest-testing/SKILL.md

SKILL.md

type: read

aggregated_output:
---
name: laravel-best-practices
description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
license: MIT
metadata:
  author: laravel
---

# Laravel Best Practices

Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.

## Consistency First

Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.

Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.

## Quick Reference

### 1. Database Performance → `rules/db-performance.md`

- Eager load with `with()` to prevent N+1 queries
- Enable `Model::preventLazyLoading()` in development
- Select only needed columns, avoid `SELECT *`
- `chunk()` / `chunkById()` for large datasets
- Index columns used in `WHERE`, `ORDER BY`, `JOIN`
- `withCount()` instead of loading relations to count
- `cursor()` for memory-efficient read-only iteration
- Never query in Blade templates

### 2. Advanced Query Patterns → `rules/advanced-queries.md`

- `addSelect()` subqueries over eager-loading entire has-many for a single value
- Dynamic relationships via subquery FK + `belongsTo`
- Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
- `setRelation()` to prevent circular N+1 queries
- `whereIn` + `pluck()` over `whereHas` for better index usage
- Two simple queries can beat one complex query
- Compound indexes matching `orderBy` column order
- Correlated subqueries in `orderBy` for has-many sorting (avoid joins)

### 3. Security → `rules/security.md`

- Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
- No raw SQL with user input — use Eloquent or query builder
- `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
- Validate MIME type, extension, and size for file uploads
- Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields

### 4. Caching → `rules/caching.md`

- `Cache::remember()` over manual get/put
- `Cache::flexible()` for stale-while-revalidate on high-traffic data
- `Cache::memo()` to avoid redundant cache hits within a request
- Cache tags to invalidate related groups
- `Cache::add()` for atomic conditional writes
- `once()` to memoize per-request or per-object lifetime
- `Cache::lock()` / `lockForUpdate()` for race conditions
- Failover cache stores in production

### 5. Eloquent Patterns → `rules/eloquent.md`

- Correct relationship types with return type hints
- Local scopes for reusable query constraints
- Global scopes sparingly — document their existence
- Attribute casts in the `casts()` method
- Cast date columns, use Carbon instances in templates
- `whereBelongsTo($model)` for cleaner queries
- Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries

### 6. Validation & Forms → `rules/validation.md`

- Form Request classes, not inline validation
- Array notation `['required', 'email']` for new code; follow existing convention
- `$request->validated()` only — never `$request->all()`
- `Rule::when()` for conditional validation
- `after()` instead of `withValidator()`

### 7. Configuration → `rules/config.md`

- `env()` only inside config files
- `App::environment()` or `app()->isProduction()`
- Config, lang files, and constants over hardcoded text

### 8. Testing Patterns → `rules/testing.md`

- `LazilyRefreshDatabase` over `RefreshDatabase` for speed
- `assertModelExists()` over raw `assertDatabaseHas()`
- Factory states and sequences over manual overrides
- Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
- `recycle()` to share relationship instances across factories

### 9. Queue & Job Patterns → `rules/queue-jobs.md`

- `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
- `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
- Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
- `RateLimited` middleware for external API c…2256 chars truncated…`Concurrency::run()` for parallel execution

### 16. Migrations → `rules/migrations.md`

- Generate migrations with `php artisan make:migration`
- `constrained()` for foreign keys
- Never modify migrations that have run in production
- Add indexes in the migration, not as an afterthought
- Mirror column defaults in model `$attributes`
- Reversible `down()` by default; forward-fix migrations for intentionally irreversible changes
---
name: pest-testing
description: "Use this skill for Pest PHP testing in Laravel projects only. Trigger whenever any test is being written, edited, fixed, or refactored — including fixing tests that broke after a code change, adding assertions, converting PHPUnit to Pest, adding datasets, and TDD workflows. Always activate when the user asks how to write something in Pest, mentions test files or directories (tests/Feature, tests/Unit, tests/Browser), or needs browser testing, smoke testing multiple pages for JS errors, or architecture tests. Covers: test()/it()/expect() syntax, datasets, mocking, browser testing (visit/click/fill), smoke testing, arch(), Livewire component tests, RefreshDatabase, and all Pest 4 features. Do not use for factories, seeders, migrations, controllers, models, or non-test PHP code."
license: MIT
metadata:
  author: laravel
---

# Pest Testing 4

## Documentation

Use `search-docs` for detailed Pest 4 patterns and documentation.

## Basic Usage

### Creating Tests

All tests must be written using Pest. Use `php artisan make:test --pest {name}`.

### Test Organization

- Unit/Feature tests: `tests/Feature` and `tests/Unit` directories.
- Browser tests: `tests/Browser/` directory.
- Do NOT remove tests without approval - these are core application code.

### Basic Test Structure

Pest supports both `test()` and `it()` functions. Before writing new tests, check existing test files in the same directory to match the project's convention. Use `test()` if existing tests use `test()`, or `it()` if they use `it()`.

<!-- Basic Pest Test Example -->
```php
it('is true', function () {
    expect(true)->toBeTrue();
});
```

### Running Tests

- Run minimal tests with filter before finalizing: `php artisan test --compact --filter=testName`.
- Run all tests: `php artisan test --compact`.
- Run file: `php artisan test --compact tests/Feature/ExampleTest.php`.

## Assertions

Use specific assertions (`assertSuccessful()`, `assertNotFound()`) instead of `assertStatus()`:

<!-- Pest Response Assertion -->
```php
it('returns all', function () {
    $this->postJson('/api/docs', [])->assertSuccessful();
});
```

| Use | Instead of |
|-----|------------|
| `assertSuccessful()` | `assertStatus(200)` |
| `assertNotFound()` | `assertStatus(404)` |
| `assertForbidden()` | `assertStatus(403)` |

## Mocking

Import mock function before use: `use function Pest\Laravel\mock;`

## Datasets

Use datasets for repetitive tests (validation rules, etc.):

<!-- Pest Dataset Example -->
```php
it('has emails', function (string $email) {
    expect($email)->not->toBeEmpty();
})->with([
    'james' => 'james@laravel.com',
    'taylor' => 'taylor@laravel.com',
]);
```

## Pest 4 Features

| Feature | Purpose |
|---------|---------|
| Browser Testing | Full integration tests in real browsers |
| Smoke Testing | Validate multiple pages quickly |
| Visual Regression | Compare screenshots for visual changes |
| Test Sharding | Parallel CI runs |
| Architecture Testing | Enforce code conventions |

### Browser Test Example

Browser tests run in real browsers for full integration testing:

- Browser tests live in `tests/Browser/`.
- Use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories.
- Use `RefreshDatabase` for clean state per test.
- Interact with page: click, type, scroll, select, submit, drag-and-drop, touch gestures.
- Test on multiple browsers (Chrome, Firefox, Safari) if requested.
- Test on different devices/viewports (iPhone 14 Pro, tablets) if requested.
- Switch color schemes (light/dark mode) when appropriate.
- Take screenshots or pause tests for debugging.

<!-- Pest Browser Test Example -->
```php
it('may reset the password', function () {
    Notification::fake();

    $this->actingAs(User::factory()->create());

    $page = visit('/sign-in');

    $page->assertSee('Sign In')
        ->assertNoJavaScriptErrors()
        ->click('Forgot Password?')
        ->fill('email', 'nuno@laravel.com')
        ->click('Send Reset Link')
        ->assertSee('We have emailed your password reset link!');

    Notification::assertSent(ResetPassword::class);
});
```

### Smoke Testing

Quickly validate multiple pages have no JavaScript errors:

<!-- Pest Smoke Testing Example -->
```php
$pages = visit(['/', '/about', '/contact']);

$pages->assertNoJavaScriptErrors()->assertNoConsoleLogs();
```

### Visual Regression Testing

Capture and compare screenshots to detect visual changes.

### Test Sharding

Split tests across parallel processes for faster CI runs.

status: completed


output:
Chunk ID: 8068e1
Wall time: 0.0000 seconds
Process exited with code 0
Original token count: 3068
Output:
---
name: laravel-best-practices
description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
license: MIT
metadata:
  author: laravel
---

# Laravel Best Practices

Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.

## Consistency First

Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.

Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.

## Quick Reference

### 1. Database Performance → `rules/db-performance.md`

- Eager load with `with()` to prevent N+1 queries
- Enable `Model::preventLazyLoading()` in development
- Select only needed columns, avoid `SELECT *`
- `chunk()` / `chunkById()` for large datasets
- Index columns used in `WHERE`, `ORDER BY`, `JOIN`
- `withCount()` instead of loading relations to count
- `cursor()` for memory-efficient read-only iteration
- Never query in Blade templates

### 2. Advanced Query Patterns → `rules/advanced-queries.md`

- `addSelect()` subqueries over eager-loading entire has-many for a single value
- Dynamic relationships via subquery FK + `belongsTo`
- Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
- `setRelation()` to prevent circular N+1 queries
- `whereIn` + `pluck()` over `whereHas` for better index usage
- Two simple queries can beat one complex query
- Compound indexes matching `orderBy` column order
- Correlated subqueries in `orderBy` for has-many sorting (avoid joins)

### 3. Security → `rules/security.md`

- Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
- No raw SQL with user input — use Eloquent or query builder
- `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
- Validate MIME type, extension, and size for file uploads
- Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields

### 4. Caching → `rules/caching.md`

- `Cache::remember()` over manual get/put
- `Cache::flexible()` for stale-while-revalidate on high-traffic data
- `Cache::memo()` to avoid redundant cache hits within a request
- Cache tags to invalidate related groups
- `Cache::add()` for atomic conditional writes
- `once()` to memoize per-request or per-object lifetime
- `Cache::lock()` / `lockForUpdate()` for race conditions
- Failover cache stores in production

### 5. Eloquent Patterns → `rules/eloquent.md`

- Correct relationship types with return type hints
- Local scopes for reusable query constraints
- Global scopes sparingly — document their existence
- Attribute casts in the `casts()` method
- Cast date columns, use Carbon instances in templates
- `whereBelongsTo($model)` for cleaner queries
- Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries

### 6. Validation & Forms → `rules/validation.md`

- Form Request classes, not inline validation
- Array notation `['required', 'email']` for new code; follow existing convention
- `$request->validated()` only — never `$request->all()`
- `Rule::when()` for conditional validation
- `after()` instead of `withValidator()`

### 7. Configuration → `rules/config.md`

- `env()` only inside config files
- `App::environment()` or `app()->isProduction()`
- Config, lang files, and constants over hardcoded text

### 8. Testing Patterns → `rules/testing.md`

- `LazilyRefreshDatabase` over `RefreshDatabase` for speed
- `assertModelExists()` over raw `assertDatabaseHas()`
- Factory states and sequences over manual overrides
- Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
- `recycle()` to share relationship instances across factories

### 9. Queue & Job Patterns → `rules/queue-jobs.md`

- `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
- `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
- Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
- `RateLimited` middleware for external API calls; `Bus::batch()` for related jobs
- Horizon for complex multi-queue scenarios

### 10. Routing & Controllers → `rules/routing.md`

- Implicit route model binding
- Scoped bindings for nested resources
- `Route::resource()` or `apiResource()`
- Methods under 10 lines — extract to actions/services
- Type-hint Form Requests for auto-validation

### 11. HTTP Client → `rules/http-client.md`

- Explicit `timeout` and `connectTimeout` on every request
- `retry()` with exponential backoff for external APIs
- Check response status or use `throw()`
- `Http::pool()` for concurrent independent requests
- `Http::fake()` and `preventStrayRequests()` in tests

### 12. Events, Notifications & Mail → `rules/events-notifications.md`, `rules/mail.md`

- Event discovery over manual registration; `event:cache` in production
- `ShouldDispatchAfterCommit` / `afterCommit()` inside transactions
- Queue notifications and mailables with `ShouldQueue`
- On-demand notifications for non-user recipients
- `HasLocalePreference` on notifiable models
- `assertQueued()` not `assertSent()` for queued mailables
- Markdown mailables for transactional emails

### 13. Error Handling → `rules/error-handling.md`

- `report()`/`render()` on exception classes or in `bootstrap/app.php` — follow existing pattern
- `ShouldntReport` for exceptions that should never log
- Throttle high-volume exceptions to protect log sinks
- `dontReportDuplicates()` for multi-catch scenarios
- Force JSON rendering for API routes
- Structured context via `context()` on exception classes

### 14. Task Scheduling → `rules/scheduling.md`

- `withoutOverlapping()` on variable-duration tasks
- `onOneServer()` on multi-server deployments
- `runInBackground()` for concurrent long tasks
- `environments()` to restrict to appropriate environments
- `takeUntilTimeout()` for time-bounded processing
- Schedule groups for shared configuration

### 15. Architecture → `rules/architecture.md`

- Single-purpose Action classes; dependency injection over `app()` helper
- Prefer official Laravel packages and follow conventions, don't override defaults
- Default to `ORDER BY id DESC` or `created_at DESC`; `mb_*` for UTF-8 safety
- `defer()` for post-response work; `Context` for request-scoped data; `Concurrency::run()` for parallel execution

### 16. Migrations → `rules/migrations.md`

- Generate migrations with `php artisan make:migration`
- `constrained()` for foreign keys
- Never modify migrations that have run in production
- Add indexes in the migration, not as an afterthought
- Mirror column defaults in model `$attributes`
- Reversible `down()` by default; forward-fix migrations for intentionally irreversible changes
---
name: pest-testing
description: "Use this skill for Pest PHP testing in Laravel projects only. Trigger whenever any test is being written, edited, fixed, or refactored — including fixing tests that broke after a code change, adding assertions, converting PHPUnit to Pest, adding datasets, and TDD workflows. Always activate when the user asks how to write something in Pest, mentions test files or directories (tests/Feature, tests/Unit, tests/Browser), or needs browser testing, smoke testing multiple pages for JS errors, or architecture tests. Covers: test()/it()/expect() syntax, datasets, mocking, browser testing (visit/click/fill), smoke testing, arch(), Livewire component tests, RefreshDatabase, and all Pest 4 features. Do not use for factories, seeders, migrations, controllers, models, or non-test PHP code."
license: MIT
metadata:
  author: laravel
---

# Pest Testing 4

## Documentation

Use `search-docs` for detailed Pest 4 patterns and documentation.

## Basic Usage

### Creating Tests

All tests must be written using Pest. Use `php artisan make:test --pest {name}`.

### Test Organization

- Unit/Feature tests: `tests/Feature` and `tests/Unit` directories.
- Browser tests: `tests/Browser/` directory.
- Do NOT remove tests without approval - these are core application code.

### Basic Test Structure

Pest supports both `test()` and `it()` functions. Before writing new tests, check existing test files in the same directory to match the project's convention. Use `test()` if existing tests use `test()`, or `it()` if they use `it()`.

<!-- Basic Pest Test Example -->
```php
it('is true', function () {
    expect(true)->toBeTrue();
});
```

### Running Tests

- Run minimal tests with filter before finalizing: `php artisan test --compact --filter=testName`.
- Run all tests: `php artisan test --compact`.
- Run file: `php artisan test --compact tests/Feature/ExampleTest.php`.

## Assertions

Use specific assertions (`assertSuccessful()`, `assertNotFound()`) instead of `assertStatus()`:

<!-- Pest Response Assertion -->
```php
it('returns all', function () {
    $this->postJson('/api/docs', [])->assertSuccessful();
});
```

| Use | Instead of |
|-----|------------|
| `assertSuccessful()` | `assertStatus(200)` |
| `assertNotFound()` | `assertStatus(404)` |
| `assertForbidden()` | `assertStatus(403)` |

## Mocking

Import mock function before use: `use function Pest\Laravel\mock;`

## Datasets

Use datasets for repetitive tests (validation rules, etc.):

<!-- Pest Dataset Example -->
```php
it('has emails', function (string $email) {
    expect($email)->not->toBeEmpty();
})->with([
    'james' => 'james@laravel.com',
    'taylor' => 'taylor@laravel.com',
]);
```

## Pest 4 Features

| Feature | Purpose |
|---------|---------|
| Browser Testing | Full integration tests in real browsers |
| Smoke Testing | Validate multiple pages quickly |
| Visual Regression | Compare screenshots for visual changes |
| Test Sharding | Parallel CI runs |
| Architecture Testing | Enforce code conventions |

### Browser Test Example

Browser tests run in real browsers for full integration testing:

- Browser tests live in `tests/Browser/`.
- Use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories.
- Use `RefreshDatabase` for clean state per test.
- Interact with page: click, type, scroll, select, submit, drag-and-drop, touch gestures.
- Test on multiple browsers (Chrome, Firefox, Safari) if requested.
- Test on different devices/viewports (iPhone 14 Pro, tablets) if requested.
- Switch color schemes (light/dark mode) when appropriate.
- Take screenshots or pause tests for debugging.

<!-- Pest Browser Test Example -->
```php
it('may reset the password', function () {
    Notification::fake();

    $this->actingAs(User::factory()->create());

    $page = visit('/sign-in');

    $page->assertSee('Sign In')
        ->assertNoJavaScriptErrors()
        ->click('Forgot Password?')
        ->fill('email', 'nuno@laravel.com')
        ->click('Send Reset Link')
        ->assertSee('We have emailed your password reset link!');

    Notification::assertSent(ResetPassword::class);
});
```

### Smoke Testing

Quickly validate multiple pages have no JavaScript errors:

<!-- Pest Smoke Testing Example -->
```php
$pages = visit(['/', '/about', '/contact']);

$pages->assertNoJavaScriptErrors()->assertNoConsoleLogs();
```

### Visual Regression Testing

Capture and compare screenshots to detect visual changes.

### Test Sharding

Split tests across parallel processes for faster CI runs.


message: The spec confirms Phase 7 is split into four natural areas: SQLite product search and suggestions, storefront analytics ingestion/aggregation, admin analytics/search settings, and stubbed apps/webhooks. I’m checking the current code shape now so the next commit can land one vertical area with tests instead of a broad, fragile sweep.

phase: commentary


type: message

role: assistant

text: The spec confirms Phase 7 is split into four natural areas: SQLite product search and suggestions, storefront analytics ingestion/aggregation, admin analytics/search settings, and stubbed apps/webhooks. I’m checking the current code shape now so the next commit can land one vertical area with tests instead of a broad, fragile sweep.


server: laravel-boost

tool: application-info

type: text

database_engine: sqlite

roster_name: FORTIFY

package_name: laravel/fortify

roster_name: LARAVEL

package_name: laravel/framework

roster_name: PROMPTS

package_name: laravel/prompts

package_name: livewire/flux

roster_name: LIVEWIRE

package_name: livewire/livewire

roster_name: BOOST

package_name: laravel/boost

roster_name: MCP

package_name: laravel/mcp

roster_name: PAIL

package_name: laravel/pail

roster_name: PINT

package_name: laravel/pint

roster_name: SAIL

package_name: laravel/sail

roster_name: PEST

package_name: pestphp/pest

roster_name: PHPUNIT

package_name: phpunit/phpunit

roster_name: TAILWINDCSS

package_name: tailwindcss


tool: database-schema

engine: sqlite

key: varchar

value: text

expiration: integer

owner: varchar

cart_id: integer

variant_id: integer

quantity: integer

unit_price_amount: integer

line_subtotal_amount: integer

line_discount_amount: integer

line_total_amount: integer

store_id: integer

customer_id: integer

currency: varchar

cart_version: integer

status: varchar

created_at: datetime

updated_at: datetime

payment_method: varchar

email: varchar

shipping_address_json: text

billing_address_json: text

shipping_method_id: integer

discount_code: varchar

tax_provider_snapshot_json: text

totals_json: text

expires_at: datetime

collection_id: integer

product_id: integer

position: integer

title: varchar

handle: varchar

description_html: text

type: varchar

label: varchar

address_json: text

token: varchar

varchar

password_hash: varchar

code: varchar

value_type: varchar

value_amount: integer

starts_at: datetime

ends_at: datetime

usage_limit: integer

usage_count: integer

rules_json: text

connection: text

queue: text

payload: text

exception: text

failed_at: datetime

fulfillment_id: integer

order_line_id: integer

order_id: integer

tracking_company: varchar

tracking_number: varchar

tracking_url: varchar

shipped_at: datetime

delivered_at: datetime

quantity_on_hand: integer

quantity_reserved: integer

policy: varchar

total_jobs: integer

pending_jobs: integer

failed_jobs: integer

failed_job_ids: text

title: varchar

title: varchar

title: varchar


packages: laravel/framework livewire/livewire livewire/flux pestphp/pest

queries: full text search sqlite database query builder

queries: Livewire full page component pagination form testing

queries: Flux input select textarea checkbox button table badge