# Theme Concierge

## Package docs status

This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/theme-concierge` |
| Package slug | `theme-concierge` |
| Product group | Capell Themes |
| Tier | premium |
| Bundle | `themes` |
| Runtime contexts | `frontend`, `console` |
| Capell version | `^1.0` |
| Catalogue role | extension |
| Release channel | Labs |
| Source repository | `capell-app/packages` |
| Source path | `packages/theme-concierge` |
| Docs source | `packages/theme-concierge/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/theme-concierge/capell.json) |

<!-- prettier-ignore-start -->

## What This Plugin Adds

Theme Concierge is an **Available**, **No schema impact** Capell theme in the **Capell Themes** product group. It ships as `capell-app/theme-concierge` and extends these surfaces: frontend, console.

Theme Concierge adds canonical guided-intake paths, one-question-at-a-time branching, visible answer dossiers, triage outcomes, and structured handoff to bookings, forms, or email.

Editors compose normal Layout Builder content while visitors can follow, share, revisit, and complete a service-intake path that remains usable without JavaScript.

Evidence: [`src/Actions/ResolveConversationStateAction.php`](src/Actions/ResolveConversationStateAction.php), [`src/Enums/WidgetComponentEnum.php`](src/Enums/WidgetComponentEnum.php), [`resources/views/sections/conversation-stage.blade.php`](resources/views/sections/conversation-stage.blade.php), [`resources/views/sections/intake-handoff-form.blade.php`](resources/views/sections/intake-handoff-form.blade.php), [`src/Support/Demo/ConciergeDemoContent.php`](src/Support/Demo/ConciergeDemoContent.php), [`resources/js/concierge-frontend.js`](resources/js/concierge-frontend.js), [`resources/css/theme-concierge.css`](resources/css/theme-concierge.css).

Status details:

- Status: Available
- Tier: premium
- Bundle: themes
- Composer package: `capell-app/theme-concierge`
- Namespace: `Capell\ThemeConcierge`
- Theme key: `concierge`

## Why It Matters

**For developers:** The package keeps path validation, SEO state, optional-integration resolution, rendering, and progressive navigation inside a focused theme boundary with no public database queries.

**For teams:** Service teams receive a concise recap of what a visitor selected before the enquiry, reducing repeated questions while preserving an immediate urgent route.

Evidence: [`src/Actions/ApplyConversationHeadStateAction.php`](src/Actions/ApplyConversationHeadStateAction.php), [`src/Support/ConciergeConversationContext.php`](src/Support/ConciergeConversationContext.php), [`src/View/Components/ConversationStage.php`](src/View/Components/ConversationStage.php), [`src/Actions/MapPathToFormPayloadAction.php`](src/Actions/MapPathToFormPayloadAction.php), [`resources/views/sections/urgent-route-banner.blade.php`](resources/views/sections/urgent-route-banner.blade.php), [`resources/views/sections/partials/summary-dossier-content.blade.php`](resources/views/sections/partials/summary-dossier-content.blade.php).

## Screens And Workflow

Screenshot contract: `docs/screenshots.json`.

![Fernbrook Veterinary Practice Concierge theme with a single guided question, visit-plan dossier, and urgent-care escape route](assets/marketplace/theme-concierge-card.svg)

Desktop, tablet, and mobile variants remain defined in the screenshot contract; this list groups them by workflow.

- Concierge Homepage intake (frontend, optional).
- Concierge Question directory (frontend, optional).
- Concierge Vaccination visit plan (frontend, optional).
- Concierge Structured handoff (frontend, optional).
- Concierge Urgent route (frontend, optional).
- Concierge Empty question index (frontend, optional).
- Concierge Invalid path recovery (frontend, optional).

## Technical Shape

- Service providers: `Capell\ThemeConcierge\ConciergeThemeServiceProvider`.
- Config files: `packages/theme-concierge/config/capell-theme-concierge.php`.
- Actions: `ApplyConversationHeadStateAction`, `BuildConversationUrlAction`, `BuildQuestionIndexAction`, `FilterItemsByPathTagsAction`, `InstallConciergeThemeDemoAction`, `MapPathToFormPayloadAction`, `ResolveConversationStateAction`.
- Data objects: `ConciergeFormPayloadData`, `ConciergeRecipeData`, `ConversationAnswerData`, `ConversationChoiceData`, `ConversationStateData`, `QuestionIndexEntryData`.
- Command signatures: `capell:theme-concierge-demo`.
- Console command classes: `ConciergeDemoCommand`.
- Manifest contributions: `admin-page: Capell\ThemeConcierge\Manifest\ThemeManagementPageContribution`.
- Health checks: `Capell\ThemeConcierge\Health\ThemeConciergeHealthCheck`.
- Blade views: `packages/theme-concierge/resources/views/sections/conversation-stage--embedded.blade.php`, `packages/theme-concierge/resources/views/sections/conversation-stage--split.blade.php`, `packages/theme-concierge/resources/views/sections/conversation-stage.blade.php`, `packages/theme-concierge/resources/views/sections/intake-handoff-form.blade.php`, `packages/theme-concierge/resources/views/sections/partials/conversation-stage.blade.php`, `packages/theme-concierge/resources/views/sections/partials/summary-dossier-content.blade.php`, `packages/theme-concierge/resources/views/sections/path-breadcrumb-trail.blade.php`, `packages/theme-concierge/resources/views/sections/question-index-directory.blade.php`, `packages/theme-concierge/resources/views/sections/reassurance-proof-strip.blade.php`, `packages/theme-concierge/resources/views/sections/summary-dossier-card--sticky.blade.php`, `packages/theme-concierge/resources/views/sections/summary-dossier-card.blade.php`, `packages/theme-concierge/resources/views/sections/team-match-cards.blade.php`, `and 4 more`.
- Cache tags: `theme-concierge`.

## Data Model

This theme has no schema impact. It relies on core Capell site, page, locale, and theme records instead of declaring package-owned tables.

## Install Impact

- Required packages: `capell-app/core`, `capell-app/theme-foundation`, `capell-app/frontend`, `capell-app/layout-builder`.
- Admin navigation: declares `admin-page: ThemeManagementPageContribution`; each Filament page or resource controls its own navigation visibility.
- Admin/editor extensions: none declared.
- Permissions: none declared in `capell.json`.
- Public routes: none declared.
- Database changes: no package migrations declared.
- Config: `config/capell-theme-concierge.php`.
- Settings: no package settings declared.
- Queues or schedules: none declared.
- Cache tags: `theme-concierge`.
- Commands: `capell:theme-concierge-demo`.

## Common Pitfalls

- Keep required Capell packages on compatible v4 releases: `capell-app/core`, `capell-app/theme-foundation`, `capell-app/frontend`, `capell-app/layout-builder`.
- Review package configuration before production-like verification: `config/capell-theme-concierge.php`.
- Keep public Blade and cached HTML free of authoring markers, model IDs, permissions, signed editor URLs, and lazy database queries.
- Custom write integrations must preserve invalidation for `theme-concierge` cache tags.

## Troubleshooting

| Symptom | Likely cause | Check | Fix |
| --- | --- | --- | --- |
| Package surface is missing after install | Provider or manifest is not loaded | Confirm `capell.json`, package `composer.json`, and provider registration | Reinstall the package, refresh Composer autoload, and clear host caches |
| Public output leaks unexpected state | Render data, cache variation, or authoring boundary has regressed | Check public Blade, cache tags, and public-output safety tests | Move data loading out of Blade and rerun the package public-output tests |

## Quick Start

1. Install the package: `composer require capell-app/theme-concierge`.
2. Review `config/capell-theme-concierge.php` before enabling the package.
3. Run `php artisan list` and verify the package command signatures are registered.

## Next Steps

- [Package docs](README.md)
- [Overview](overview.md)
- Configuration files: [`config/capell-theme-concierge.php`](config/capell-theme-concierge.php).
- [Troubleshooting](#troubleshooting)
- [Screenshot contract](screenshots.json)
- [Marketplace assets](assets/marketplace/)
- [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md)
- [Capell documentation design system](../../docs/DESIGN_SYSTEM.md)
- [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md)
- Related packages: [Theme Foundation](../theme-foundation/README.md), [Layout Builder](../layout-builder/README.md), [Blog](../blog/README.md), [Bookings](../bookings/README.md), [Form Builder](../form-builder/README.md), [Search](../search/README.md), [Widget Countdown](../widget-countdown/README.md), [Widget Location Map](../widget-location-map/README.md).
- Focused tests: `vendor/bin/pest packages/theme-concierge/tests --configuration=phpunit.xml`.

<!-- prettier-ignore-end -->