# Phase: Experience Template System (11.4)

| Field | Value |
| --- | --- |
| Identifier | `experience-11.4` |
| Status | Complete |
| Owner | Platform |
| Module(s) | Templates, Template Versions, Template Instantiations |
| Service(s) | `experience` (Torbat Pages) |
| Depends On | `experience-11.3` |
| ADR(s) | [ADR-016](architecture/adr/ADR-016.md), [ADR-008](architecture/adr/ADR-008.md) |
| Manifest | [phase-manifest.yaml](ai-framework/phase-manifest.yaml) |

## Enterprise Phase Discovery Record

| Input | Finding |
| --- | --- |
| Roadmap / manifest | Next unfinished Experience phase = `experience-11.4` Template System |
| Prior handover | [phase-11-3.md](phase-handover/phase-11-3.md) — themes/layouts complete; no template catalog |
| Boundaries | Experience owns the template catalog; templates compose existing themes/layouts/components by reference only; no Core DB access |
| Existing codebase | Template scaffolding (models/services/schemas/repositories/commands/queries/policies/validators/specifications/APIs, and a `.future`-suffixed Alembic revision) already existed on disk but was intentionally unwired at the end of the Phase 11.3 repair |
| Missing vs DoD | Alembic head still pinned to `0004`; `app.models.templates` not imported; template routers not mounted; capability flags still `False`; no phase test suite |

Derived capabilities: a tenant catalog of reusable page-type templates; immutable published template versions carrying a `blueprint_json` shell; one-click instantiation of a published template version into a new page (optionally wiring an existing active theme/layout by reference and seeding component placement shells). **Not** forms, surveys, locales, media pipelines, or SEO — those remain Phase 11.5+.

## Objective

Re-wire and validate the existing Phase 11.4 Template System scaffolding on `experience_db` so tenants can define a template catalog, publish immutable template versions, and instantiate a published version into a concrete page — reusing the Phase 11.1 sites/pages resources and the Phase 11.3 theme/layout catalogs by reference only.

## Scope

### In Scope

- `ExperienceTemplate` (catalog: code, name, description, page_type, category, tags, starter-pack flag, status, latest/published version pointers)
- `ExperienceTemplateVersion` (immutable once published: `blueprint_json`, changelog)
- `TemplateInstantiation` (audit trail: template + version + site → created page, result/error payload)
- Policies, specifications, commands, queries
- Pagination / filter / sort / search on list APIs
- Permissions `experience.templates.*` (full `view|create|update|delete|manage` CRUD tree)
- Events `experience.template.*` / `experience.template_version.*` / `experience.template.instantiated`
- Alembic `0005_phase_114_templates` (head); version `0.11.4.0`
- `/capabilities` flags: `templates`, `template_versions`, `template_instantiation`

### Out of Scope

- Forms / surveys / appointment page shells — Phase 11.6
- Full localization + media reference pipeline — Phase 11.5
- SEO metadata / sitemap / PWA — Phase 11.7
- Owning the theme/layout/component engines themselves (Experience only *references* published theme/layout versions and component codes from a template's blueprint)

### Models

| Entity | Soft delete | Audit | Tenant | Optimistic lock |
| --- | --- | --- | --- | --- |
| ExperienceTemplate | Yes | Yes | Yes | Yes |
| ExperienceTemplateVersion | Yes | Yes | Yes | Yes |
| TemplateInstantiation | Yes | Yes | Yes | Yes |

### Permissions

`experience.templates.view|create|update|delete|manage`

### Events

`experience.template.created|updated|activated|deprecated|archived`

`experience.template_version.created|updated|published|retired`

`experience.template.instantiated`

### APIs

| Method | Path |
| --- | --- |
| * | `/api/v1/templates` (+ activate/deprecate/archive/delete) |
| * | `/api/v1/template-versions` (+ publish/retire) |
| * | `/api/v1/template-instantiations` (instantiate + list + get) |

### Artifact coverage (DoD)

| Artifact | Status |
| --- | --- |
| Discovery | This record |
| Policies / Specs / Commands / Queries | Implemented |
| Soft delete / Optimistic lock / Audit / Tenant | Yes |
| Pagination / Filter / Sort / Search | Yes |
| Background jobs | N/A — instantiation runs synchronously within the request |
| Forms / Surveys | Explicitly out of scope |

### Tests

- [x] Health / capabilities reflect phase 11.4
- [x] Full lifecycle: create template → create version → publish (auto-activates template) → explicit activate → instantiate (creates page) → list/get instantiations
- [x] Tenant isolation
- [x] Immutable published version update blocked (409) and re-publish blocked (409)
- [x] Architecture / permission / migration / docs

## Completion Criteria

- [x] Template APIs + validators + tests green
- [x] No forms/surveys engine
- [x] Docs / manifests / handover updated

## Related Documents

- [Handover](phase-handover/phase-11-4.md)
- [Phase 11.3](experience-phase-11-3.md)
- [Experience Roadmap](experience-roadmap.md)
- [ADR-016](architecture/adr/ADR-016.md)
- [ADR-008](architecture/adr/ADR-008.md)