diff --git a/.planning/phases/04-theme-engine/04-CONTEXT.md b/.planning/phases/04-theme-engine/04-CONTEXT.md
new file mode 100644
index 0000000..adf2334
--- /dev/null
+++ b/.planning/phases/04-theme-engine/04-CONTEXT.md
@@ -0,0 +1,82 @@
+# Phase 4: Theme Engine - Context
+
+**Gathered:** 2026-02-04
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Render themes with layouts, partials, and Vue integration. Includes asset management and multiple rendering modes (SPA, hybrid, static). Theme creation tooling and CLI scaffolding are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Template Syntax
+- String templates with interpolation (not ScalaTags) — designers can work with HTML directly
+- Twig-style syntax for includes: `{% partial 'header' %}`
+- Variable passing supports both named parameters and context objects:
+  - Simple: `{% partial 'card' title='Hello' count=5 %}`
+  - Complex: `{% partial 'card' with cardData %}`
+- Components expose variables implicitly — templates can use component data directly (WinterCMS style)
+
+### Layout Composition
+- Pages declare layout in front matter YAML: `layout: default`
+- WinterCMS-style placeholder system:
+  - `{% page %}` injects main page content
+  - Named placeholders supported: `{% placeholder 'sidebar' %}`
+- Flat layout structure only — no layout inheritance
+  - Use partials for shared pieces across layouts
+- Theme metadata in `theme.yaml` at theme root
+
+### Asset Pipeline
+- Research best Scala ecosystem options for manifest/bundling
+  - Manifest file preferred if no better standard tool exists
+- Hot reload essential for development workflow
+- Production optimization requirements:
+  - Minification with content hashing for cache busting
+  - Separate bundles: vendor, app, critical CSS
+- Plugin asset injection like WinterCMS:
+  - `addCss()` and `addJs()` for global hooks
+  - Component-scoped assets load when components are used
+  - Both mechanisms supported
+
+### Rendering Modes
+- Theme default in `theme.yaml`, per-page override in front matter
+- Three modes: `spa`, `hybrid`, `static`
+- SPA mode: Server renders HTML, Vue 3 hydrates on client
+- Hybrid mode: Page-level granularity (whole page is either server or SPA)
+- Static mode supports both:
+  - Build-time generation via CLI command
+  - On-demand generation with caching
+
+### Claude's Discretion
+- Specific string template library/implementation for Scala
+- Asset bundling tool selection (investigate Scala ecosystem)
+- Hot reload implementation approach
+- Exact Vue hydration setup
+- Cache invalidation strategy for static mode
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- Template syntax should feel familiar to WinterCMS developers — Twig-style tags
+- Asset injection API similar to WinterCMS `addCss()` and `addJs()` functions
+- Hot reload is essential — CSS/JS changes must reflect immediately in dev mode
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 04-theme-engine*
+*Context gathered: 2026-02-04*