@stellisoft/stellify-mcp 0.1.34 → 0.1.36

package/README.md

@@ -352,6 +352,20 @@ Search for routes/pages in the project by name.
 
 ---
 
+### Views & Blade Templates
+
+Stellify stores Blade views as elements instead of files. The root element's `name` field maps to the view name:
+
+- Element with `name="notes.index"` → `view('notes.index', $data)`
+- Element with `name="layouts.app"` → `@extends('layouts.app')`
+- Element with `name="components.card"` → `<x-card>`
+
+Use `update_element` to set the `name` on a root element after creating it with `html_to_elements`.
+
+**Convention for reusable templates:** Attach layouts, components, and partials to a template route (e.g., `/template/app-layout`, `/template/card`) to keep them organized and editable.
+
+---
+
 ### Element Tools (UI Components)
 
 #### `create_element`
@@ -360,12 +374,80 @@ Create a new UI element. Provide either `page` (route UUID) for root elements, o
 **Parameters:**
 - `type` (required): Element type - one of:
   - HTML5: `s-wrapper`, `s-input`, `s-form`, `s-svg`, `s-shape`, `s-media`, `s-iframe`
-  - Components: `s-loop`, `s-transition`, `s-freestyle`, `s-motion`
+  - Components: `s-transition`, `s-freestyle`, `s-motion`
   - Blade: `s-directive`
   - Shadcn/ui: `s-chart`, `s-table`, `s-combobox`, `s-accordion`, `s-calendar`, `s-contiguous`
 - `page` (optional): UUID of the page/route (for root elements)
 - `parent` (optional): UUID of the parent element (for child elements)
 
+**Using `s-directive` for Blade Conditionals:**
+
+`s-directive` elements output Blade directives (like `@if`, `@foreach`, `@endif`). They are **sibling elements** — they don't wrap children. To conditionally render content:
+
+1. Create an `s-directive` element with a statement for the opening directive (e.g., `@if(...)`)
+2. Create the content element(s) as the **next sibling(s)**
+3. Create another `s-directive` element with a statement for the closing directive (e.g., `@endif`)
+
+Example — conditionally showing an image:
+```
+// 1. Create statement for @if
+create_statement_with_code({
+  file: "<file-uuid>",
+  code: "@if($item->featured_image)"
+})
+
+// 2. Create opening directive element and set its statement
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<if-directive-uuid>", data: { "statement": "<if-statement-uuid>" } })
+
+// 3. Create the image as the next sibling
+html_to_elements({ page: "<route-uuid>", elements: "<img class=\"w-full\" />" })
+// Then update with dynamic src:
+update_element({ uuid: "<img-uuid>", data: { "srcField": "featured_image" } })
+
+// 4. Create statement for @endif
+create_statement_with_code({ file: "<file-uuid>", code: "@endif" })
+
+// 5. Create closing directive element
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<endif-directive-uuid>", data: { "statement": "<endif-statement-uuid>" } })
+```
+
+The three elements render in order as siblings:
+```blade
+@if($item->featured_image)
+<img class="w-full" src="{{ $item->featured_image }}" />
+@endif
+```
+
+**Using `s-directive` for Loops:**
+
+```
+// 1. Create @foreach directive
+create_statement_with_code({ file: "<file-uuid>", code: "@foreach($posts as $item)" })
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<foreach-uuid>", data: { "statement": "<foreach-statement-uuid>" } })
+
+// 2. Create loop content (article with dynamic fields)
+html_to_elements({ page: "<route-uuid>", elements: "<article><h2></h2><p></p></article>" })
+// Update elements to use loop item fields:
+update_element({ uuid: "<h2-uuid>", data: { "textField": "title" } })  // → {{ $item->title }}
+update_element({ uuid: "<p-uuid>", data: { "textField": "excerpt" } }) // → {{ $item->excerpt }}
+
+// 3. Create @endforeach directive
+create_statement_with_code({ file: "<file-uuid>", code: "@endforeach" })
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<endforeach-uuid>", data: { "statement": "<endforeach-statement-uuid>" } })
+```
+
+**Loop Item Attributes:**
+Inside `@foreach` loops, use these attributes on elements to reference `$item`:
+- `textField: "fieldName"` → outputs `{{ $item->fieldName }}`
+- `hrefField: "fieldName"` → outputs `href="{{ $item->fieldName }}"`
+- `srcField: "fieldName"` → outputs `src="{{ $item->fieldName }}"`
+- `hrefExpression: "{{ route('posts.show', $item->slug) }}"` → for complex expressions
+- `srcExpression`, `altExpression` → same pattern for other attributes
+
 ---
 
 #### `update_element`
@@ -383,7 +465,18 @@ Update an existing UI element.
 - `locked`: Prevent editing (boolean)
 - `tag`: HTML tag (div, input, button, etc.)
 - `classes`: CSS classes array `["class1", "class2"]`
-- `text`: Element text content
+- `text`: Static text content
+- `statements`: Array of statement UUIDs for dynamic Blade content
+
+**Loop item fields** (for elements inside `@foreach` loops, references `$item`):
+- `textField`: Field name → outputs `{{ $item->fieldName }}`
+- `hrefField`: Field name → outputs `href="{{ $item->fieldName }}"`
+- `srcField`: Field name → outputs `src="{{ $item->fieldName }}"`
+
+**Expression attributes** (for complex Blade expressions):
+- `hrefExpression`: Full Blade expression for href (e.g., `"{{ route('posts.show', $item->slug) }}"`)
+- `srcExpression`: Full Blade expression for src
+- `altExpression`: Full Blade expression for alt
 
 **Event handlers** (set value to method UUID):
 - `click`: @click
@@ -441,8 +534,31 @@ Convert HTML to Stellify elements in ONE operation. This is the fastest way to b
 - `elements` (required): HTML string to convert
 - `page` (optional): Route UUID to attach elements to. Omit for Vue components.
 - `selection` (optional): Parent element UUID to attach to (alternative to page)
+- `file` (optional): Vue component file UUID. Pass this to auto-wire @click handlers to method UUIDs.
 - `test` (optional): If true, returns structure without creating elements
 
+**⚠️ CRITICAL: Multiple Root Elements**
+
+When passing HTML with **multiple root-level elements** (e.g., `<header>`, `<main>`, `<footer>`), only the **FIRST root element** gets attached to the route via `routeParent`. Other elements are created but become **orphaned** (not attached to the route).
+
+**Wrong approach (causes orphaned elements):**
+```
+html_to_elements(page: routeUUID, elements: "<header>...</header><main>...</main><footer>...</footer>")
+// Result: Only <header> is attached to the route. <main> and <footer> are orphaned!
+```
+
+**Correct approach (make separate calls for each root element):**
+```
+// Call 1: Header
+html_to_elements(page: routeUUID, elements: "<header>...</header>")
+
+// Call 2: Main content
+html_to_elements(page: routeUUID, elements: "<main>...</main>")
+
+// Call 3: Footer
+html_to_elements(page: routeUUID, elements: "<footer>...</footer>")
+```
+
 **Features:**
 - Parses HTML structure
 - Creates all elements with proper nesting

package/dist/index.js

@@ -569,16 +569,15 @@ Use the returned UUID with html_to_elements (page parameter) or get_route for fu
     },
     {
         name: 'create_element',
-        description: `Create a UI element. Provide page (route UUID) for root elements, or parent (element UUID) for children. Use s-loop for v-for elements.`,
+        description: `Create a UI element. Provide page (route UUID) for root elements, or parent (element UUID) for children.`,
         inputSchema: {
             type: 'object',
             properties: {
                 type: {
                     type: 'string',
                     enum: [
-                        's-wrapper', 's-input', 's-form', 's-svg', 's-shape', 's-media', 's-iframe',
-                        's-loop', 's-transition', 's-freestyle', 's-motion',
-                        's-directive'
+                        's-wrapper', 's-input', 's-form', 's-svg', 's-shape', 's-media',
+                        's-freestyle', 's-directive'
                     ],
                     description: 'Element type - must be one of the valid Stellify element types',
                 },
@@ -596,7 +595,24 @@ Use the returned UUID with html_to_elements (page parameter) or get_route for fu
     },
     {
         name: 'update_element',
-        description: `Update a UI element. Data object: tag, classes, text, event handlers (method UUIDs), classBindings. Include context for significant UI components.`,
+        description: `Update a UI element. Data object: tag, classes, text, event handlers (method UUIDs), classBindings. Set 'name' on root elements to create Blade views (e.g., name="notes.index" for view('notes.index')).
+
+**For elements inside @foreach loops (SSR/Blade):**
+Use these attributes to reference the loop variable (defaults to \`$item\`):
+- \`textField\`: Field name for text content → outputs \`{{ $item->fieldName }}\`
+- \`hrefField\`: Field name for href → outputs \`href="{{ $item->fieldName }}"\`
+- \`srcField\`: Field name for src → outputs \`src="{{ $item->fieldName }}"\`
+
+**For complex Blade expressions in attributes:**
+Use expression attributes when you need more than simple field access (e.g., route helpers, method calls):
+- \`hrefExpression\`: Blade expression for href → outputs \`href="..."\` with the expression
+- \`srcExpression\`: Blade expression for src → outputs \`src="..."\` with the expression
+- \`altExpression\`: Blade expression for alt → outputs \`alt="..."\` with the expression
+
+Example: \`hrefExpression: "{{ route('posts.show', $item->slug) }}"\`
+
+**For Blade text content:**
+Use the \`statements\` array with statement UUIDs containing Blade code. The statement's \`code\` property will be output directly for Blade to evaluate.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -685,12 +701,50 @@ Note: To reorder elements, use update_element to modify the parent element's 'da
     },
     {
         name: 'html_to_elements',
-        description: `Convert HTML to Stellify elements. Returns element UUIDs to use in save_file template array.
+        description: `Convert HTML to Stellify elements.
+
+**IMPORTANT - Choose the right approach:**
+
+**For SSR/Blade Pages (WordPress imports, static content, layouts):**
+- MUST pass 'page' (route UUID) - elements attach to the route for server-side rendering
+- This is the most common use case
+
+**For Vue Components (client-side interactivity):**
+- Omit 'page' - elements are standalone, referenced by file's template array
+- Returns UUIDs to use in save_file's template array
+
+**Where elements go:**
+- Pass 'page' (route UUID): Elements attached to the route for SSR rendering
+- Pass 'selection' (element UUID): Elements attached as children of existing element
+- Omit both: Elements are standalone (Vue components only) - use returned UUIDs in save_file's template array
+
+**⚠️ CRITICAL: Multiple Root Elements Limitation**
+When HTML contains multiple root-level elements (e.g., <header>, <main>, <footer>), only the FIRST root element gets attached to the route. Other elements become orphaned!
+
+**WRONG:** \`html_to_elements(page: routeUUID, elements: "<header>...</header><main>...</main><footer>...</footer>")\`
+→ Only <header> attaches to route. <main> and <footer> are orphaned!
 
-Auto-detects Vue bindings ({{ var }}). For Vue components, omit 'page'. For pages, provide route UUID.
+**CORRECT:** Make separate calls for each root element:
+1. \`html_to_elements(page: routeUUID, elements: "<header>...</header>")\`
+2. \`html_to_elements(page: routeUUID, elements: "<main>...</main>")\`
+3. \`html_to_elements(page: routeUUID, elements: "<footer>...</footer>")\`
+
+**OR** wrap all elements in a single container div.
 
 **@click auto-wiring:** Pass 'file' UUID to auto-resolve @click="methodName" handlers. Methods must exist in the file first.
 
+**Blade Syntax Handling:**
+For SSR/Blade pages, do NOT pass raw Blade expressions in text or attributes. The HTML parser stores them literally which causes rendering issues. Instead:
+
+1. **For static HTML:** Pass clean HTML without Blade syntax, then use \`update_element\` to add dynamic behavior
+2. **For loop content:** After creating elements, use \`update_element\` with:
+   - \`textField\`, \`hrefField\`, \`srcField\` for simple field access (outputs \`{{ $item->field }}\`)
+   - \`hrefExpression\`, \`srcExpression\`, \`altExpression\` for complex expressions
+   - \`statements\` array with statement UUIDs for text content with Blade code
+3. **For conditionals:** Use \`s-directive\` elements as siblings (see update_element docs)
+
+**Loop variable:** Inside \`@foreach\` loops created with \`s-directive\`, the default loop variable is \`$item\`. Use \`textField: "title"\` to output \`{{ $item->title }}\`.
+
 Prefer SVG icons over emoji (encoding issues).`,
         inputSchema: {
             type: 'object',
@@ -701,11 +755,11 @@ Prefer SVG icons over emoji (encoding issues).`,
                 },
                 page: {
                     type: 'string',
-                    description: 'Route UUID to attach elements to. Optional for Vue components.',
+                    description: 'Route UUID to attach elements to. REQUIRED for SSR/Blade pages (WordPress imports, static content, layouts). Only omit for Vue component templates.',
                 },
                 selection: {
                     type: 'string',
-                    description: 'Parent element UUID to attach to (alternative to page)',
+                    description: 'Parent element UUID to attach to (alternative to page). Use when adding children to existing elements.',
                 },
                 file: {
                     type: 'string',
@@ -1154,7 +1208,7 @@ Changes are EPHEMERAL (not saved). For persistent changes, use update_element or
                 },
                 api: {
                     type: 'boolean',
-                    description: 'Generate API-style responses (default: true)',
+                    description: 'Generate API-style responses (default: true). Set to FALSE for SSR/Blade pages (controllers return views). Set to TRUE for API endpoints (controllers return JSON).',
                 },
             },
             required: ['name'],
@@ -1405,22 +1459,45 @@ const SERVER_INSTRUCTIONS = `Stellify is a coding platform where code is stored
 
 - Files are stored as json. The json has a data key that references its methods (using uuids), and each method has a data key that references statements, and each statement has a data key that references clauses.
 
-## Workflow (follow every step)
-1. Research: Call get_project to understand current structure.
-2. **If JS/Vue task**: Call \`get_stellify_framework_api\` to check for composables before writing custom code.
-3. Plan: Map out the solution before calling tools.
-4. Create: create_file, create_method (with body), create_statement_with_code
-5. **Handle mount file**: Check \`appJs\` in create_file response. If \`action_required\` exists, ask user about mount file before proceeding.
-6. Wire: html_to_elements (pass file UUID to auto-wire @click handlers)
-7. Finalize: save_file with template/data/statements arrays (include frameworkImports for composables)
-8. Verify: Call \`get_assembled_code\` to check the output
-9. Test: Use run_code or broadcast_element_command to verify behavior
+## Choosing Between SSR Pages and Vue Components
+
+**Use SSR/Blade Pages (routes + elements) when:**
+- Building static pages, layouts, or content pages
+- Importing from WordPress, HTML templates, or static sites
+- No client-side interactivity needed beyond links/forms
+- SEO is important
+
+**Use Vue Components (files with type='js', extension='vue') when:**
+- Client-side interactivity is required (counters, toggles, dynamic forms)
+- Real-time updates needed
+- Complex state management
+
+**CRITICAL DIFFERENCE:**
+- SSR Pages: Elements attach directly to routes. Use \`html_to_elements\` with \`page\` parameter (route UUID). Elements render via Blade.
+- Vue Components: Elements are standalone, referenced by file's \`template\` array. Use \`html_to_elements\` WITHOUT \`page\` parameter.
+
+## Workflow for SSR Pages (most common)
+1. Research: Call get_project to understand current structure
+2. Create route: \`create_route\` for each page
+3. Add elements: \`html_to_elements\` with \`page\` parameter set to route UUID
+4. Wire controller (if needed): \`save_route\` with controller and controller_method UUIDs
+
+## Workflow for Vue Components (client-side interactivity)
+1. Research: Call get_project to understand current structure
+2. **Call \`get_stellify_framework_api\`** to check for composables before writing custom code
+3. Create file: \`create_file\` with type='js', extension='vue'
+4. Create methods: \`create_method\` (with body parameter)
+5. Create state: \`create_statement_with_code\` for refs/reactive
+6. Create template: \`html_to_elements\` WITHOUT \`page\` parameter (returns UUIDs)
+7. **Handle mount file**: Check \`appJs\` in create_file response. If \`action_required\` exists, ask user about mount file
+8. Finalize: \`save_file\` with template/data/statements arrays (include frameworkImports for composables)
+9. Verify: Call \`get_assembled_code\` to check the output
 `;
 // Legacy detailed instructions preserved as comments for reference if needed
 // Create MCP server
 const server = new Server({
     name: 'stellify-mcp',
-    version: '0.1.34',
+    version: '0.1.36',
 }, {
     capabilities: {
         tools: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellisoft/stellify-mcp",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "mcpName": "io.github.MattStellisoft/stellify-mcp",
   "description": "MCP server for Stellify - AI-native code generation platform",
   "main": "dist/index.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Stellify-Software-Ltd/stellify-mcp",
     "source": "github"
   },
-  "version": "0.1.34",
+  "version": "0.1.36",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@stellisoft/stellify-mcp",
-      "version": "0.1.34",
+      "version": "0.1.36",
       "transport": {
         "type": "stdio"
       },

package/skills/wordpress-import.md

@@ -0,0 +1,238 @@
+---
+name: wordpress-import
+description: "Use this skill when importing WordPress sites into Stellify. Invoke with /wordpress-import to start the guided workflow. Covers: analyzing WordPress exports, converting post types to Eloquent models, transforming PHP templates to Vue components, migrating forms and plugins, and creating routes and API endpoints."
+license: MIT
+metadata:
+  author: stellify
+---
+
+# WordPress Import Skill
+
+You are importing a WordPress site into Stellify by reading its PHP theme files and recreating the site as a structured Laravel application using the Stellify MCP tools.
+
+**Match the rendering approach of the WordPress site.** If content is server-rendered in WordPress (which most of it will be — posts, pages, archives, navigation), create Blade templates. If a feature uses JavaScript for client-side interactivity (AJAX forms, dynamic filtering, live search, infinite scroll, modals, sliders), create a Vue component for that specific piece. The default is Blade — only reach for Vue when the WordPress source is doing something that genuinely requires JS.
+
+## Step 1 — Identify the Active Theme
+
+Look in `./wp-content/themes/` to find the active theme. If there are multiple themes, check for the most recently modified one, or the one with the most template files. If unsure, ask which theme to import.
+
+Before proceeding, ask the user:
+
+> **How do you want to handle the database?**
+>
+> **A) Connect to existing WordPress database** — Models map directly to the WordPress tables (`wp_posts`, `wp_users`, etc.) using the existing column names. No migrations, no data copying. Your Laravel app reads and writes to the same database WordPress uses. This is the fastest path.
+>
+> **B) Fresh database** — Create new Laravel migrations with clean column names (`title` instead of `post_title`, etc.). You start with an empty database and can optionally migrate content from WordPress later.
+
+These are the only questions you may ask. Do not ask anything else.
+
+## Step 2 — Inventory the Theme
+
+Read the full theme directory. Categorise every file:
+
+- **Core templates**: index.php, single.php, page.php, archive.php, search.php, 404.php, front-page.php, home.php
+- **Structural partials**: header.php, footer.php, sidebar.php
+- **Template parts**: anything in template-parts/ or patterns/
+- **Functions**: functions.php (and any files it includes/requires)
+- **Styles**: style.css, any CSS/SCSS files
+- **Config**: theme.json if present (block theme configuration)
+
+Print the inventory before proceeding.
+
+## Step 3 — Analyse functions.php
+
+Read functions.php thoroughly. Extract:
+
+- **Custom post types** registered via `register_post_type()` → these become Laravel models
+- **Taxonomies** registered via `register_taxonomy()` → these become models or enums
+- **Navigation menus** registered via `register_nav_menus()` → these define nav structure
+- **Widget areas** registered via `register_sidebar()` → note for layout
+- **Enqueued scripts/styles** via `wp_enqueue_script/style()` → note any JS dependencies
+- **Custom image sizes** via `add_image_size()` → note for media handling
+- **Theme supports** via `add_theme_support()` → note post formats, thumbnails, etc.
+- **Shortcodes** via `add_shortcode()` → these become Blade includes or components
+- **AJAX handlers** via `wp_ajax_*` → these become API routes
+- **Any included files** → read those too
+
+## Step 4 — Plan the Laravel Structure
+
+Before calling any Stellify tools, plan:
+
+- **Models:** One per post type (Post, Page, plus any custom types from Step 3)
+- **Controllers:** One per model with index/show actions
+- **Routes:** Match WordPress URL structure (archive at `/`, singles at `/{slug}`, taxonomies at `/category/{slug}`)
+- **Views:** Mirror WordPress template hierarchy — layout from header+footer, index/show views per post type, partials from template-parts
+- **Migrations (Mode B only):** One per model with fields from WordPress core + any custom fields found in templates
+
+## Step 5 — Build in Stellify (Order of Operations)
+
+Execute the plan using Stellify MCP tools in this order. This order matters — parent records must exist before children.
+
+### 5a. Create Models, Migrations & Controllers
+
+Use the `create_resources` tool with `api: false` to generate models and controllers together. The `api: false` flag ensures controller methods return data arrays (for Blade views) rather than JSON responses.
+
+**If Mode A (connect to existing WordPress database):**
+
+Create resources that map to the existing WordPress tables. No migrations. Set the model's table and primary key to match WordPress.
+
+```php
+// Example Post model
+class Post extends Model {
+    protected $table = 'wp_posts';
+    protected $primaryKey = 'ID';
+    
+    // Scope to only published posts (not revisions, drafts, etc.)
+    public function scopePublished($query) {
+        return $query->where('post_status', 'publish')
+                     ->where('post_type', 'post');
+    }
+}
+```
+
+Key WordPress table mappings:
+- Posts & Pages → `wp_posts` (distinguished by `post_type` column: 'post', 'page', or custom types)
+- Categories & Tags → `wp_terms` + `wp_term_taxonomy` + `wp_term_relationships`
+- Users → `wp_users`
+- Post meta / custom fields → `wp_postmeta`
+- Comments → `wp_comments`
+- Navigation menus → `wp_posts` with `post_type = 'nav_menu_item'` + `wp_terms` with taxonomy `nav_menu`
+
+In Blade templates, use WordPress column names:
+- `$post->post_title` (not `$post->title`)
+- `$post->post_content` (not `$post->content`)
+- `$post->post_excerpt` (not `$post->excerpt`)
+- `$post->post_name` (this is the slug)
+- `$post->post_date` (not `$post->published_at`)
+- `$post->post_status` (not `$post->status`)
+
+**If Mode B (fresh database):**
+
+Create new resources with clean Laravel migrations for each model identified in Step 4. Use clean column names (`title`, `slug`, `content`, `excerpt`, `status`, `published_at`, etc.). After the import is complete, suggest a data migration SQL query or artisan command that maps data from the WordPress tables to the new schema.
+
+### 5b. Refine Controller Methods
+
+`create_resources` (Step 5a) scaffolds controllers automatically. Review and refine the generated methods to ensure they query the right data. Controller methods in Stellify return data arrays — Stellify automatically merges these into the Blade view context. For example:
+
+```php
+// CORRECT for Stellify — returns a data array, Stellify handles the view binding
+public function index(): array
+{
+    return ['posts' => Post::where('status', 'published')->latest('published_at')->paginate(10)];
+}
+
+public function show(Post $post): array
+{
+    return ['post' => $post];
+}
+
+// WRONG — do not return JSON
+public function index()
+{
+    return Post::where('status', 'published')->get();
+}
+
+// WRONG — do not call view() directly, Stellify handles this
+public function index()
+{
+    return view('posts.index', compact('posts'));
+}
+```
+
+**Mode A note:** WordPress stores posts, pages, and custom post types all in `wp_posts`, distinguished by the `post_type` column. Controllers must scope queries accordingly — e.g. `Post::where('post_type', 'post')->where('post_status', 'publish')`. It also stores revisions and auto-drafts in the same table, so always filter by `post_status`.
+
+### 5c. Create Routes
+Create route entries mapping URLs to controller methods.
+
+### 5d. Create the Layout (layouts/app.blade.php)
+Read header.php and footer.php. Create a single Blade layout that combines:
+- The HTML structure from header.php (doctype, head, opening body, nav)
+- `@yield('content')` for page content
+- The structure from footer.php (closing elements, footer content)
+
+Translate WordPress functions to Blade:
+- `wp_head()` → `@vite(['resources/css/app.css', 'resources/js/app.js'])` and `<meta>` tags
+- `wp_footer()` → nothing needed (Vite handles it)
+- `wp_nav_menu()` → `@include('partials.nav')`
+- `bloginfo('name')` → `{{ config('app.name') }}`
+- `bloginfo('description')` → `{{ config('app.description', '') }}`
+- `body_class()` → appropriate Tailwind classes
+- `language_attributes()` → `lang="{{ str_replace('_', '-', app()->getLocale()) }}"`
+
+### 5e. Create Blade Views
+For each WordPress template file, read the PHP and create the equivalent Blade view using `html_to_elements`. **All views use `@extends('layouts.app')` and `@section('content')`.**
+
+**⚠️ Multiple Root Elements:** When converting HTML with multiple root-level elements (e.g., `<header>`, `<main>`, `<footer>`), only the first root element gets attached to the route. Make separate `html_to_elements` calls for each root element.
+
+**WordPress → Blade translation guide:**
+
+Mode A uses WordPress column names; Mode B uses clean Laravel names.
+
+**IMPORTANT:** Inside `@foreach` loops, use `$item` as the loop variable. This matches the Stellify assembler's expectations for `textField`, `hrefField`, `srcField` attributes.
+
+| WordPress | Blade (Mode A) | Blade (Mode B) | Stellify Attribute |
+|-----------|----------------|----------------|-------------------|
+| `the_title()` | `{{ $item->post_title }}` | `{{ $item->title }}` | `textField: "title"` |
+| `the_content()` | `{!! $item->post_content !!}` | `{!! $item->content !!}` | statement with code |
+| `the_excerpt()` | `{{ $item->post_excerpt }}` | `{{ $item->excerpt }}` | `textField: "excerpt"` |
+| `the_permalink()` | `{{ route('posts.show', $item->post_name) }}` | `{{ route('posts.show', $item->slug) }}` | `hrefExpression: "..."` |
+| `the_date()` | `{{ $item->post_date->format('d M Y') }}` | `{{ $item->published_at->format('d M Y') }}` | statement with code |
+| `the_author()` | `{{ $item->author->display_name }}` | `{{ $item->author->name }}` | statement with code |
+| `get_template_part()` | `@include('partials.post-card', ['post' => $item])` | same | s-directive |
+| `have_posts()` | `@foreach($posts as $item)` | same | s-directive pair |
+
+**Conditional Rendering with `s-directive`:**
+
+WordPress blocks that render conditionally (like `<!-- wp:post-featured-image -->`) use `s-directive` elements. See the MCP tool documentation for the sibling pattern — create an opening directive, content elements, then a closing directive as siblings.
+
+Common WordPress conditionals to convert (use `$item` inside loops):
+- `<!-- wp:post-featured-image -->` → `@if($item->featured_image)` ... `@endif`
+- `<!-- wp:post-excerpt -->` → `@if($item->post_excerpt)` ... `@endif`
+- `<!-- wp:post-comments -->` → `@if($item->comments->count() > 0)` ... `@endif`
+- `<!-- wp:query-no-results -->` → `@if($posts->isEmpty())` ... `@endif` (outside loop)
+
+**Iteration (The Loop):**
+
+WordPress's "The Loop" (`have_posts() / the_post()`) maps to `@foreach` directives. Use `s-directive` elements for the opening `@foreach` and closing `@endforeach`.
+
+**IMPORTANT - Loop Variable:** The default loop variable is `$item`. When creating elements inside a loop:
+1. Do NOT pass raw Blade syntax to `html_to_elements` — it will be stored literally
+2. Create clean HTML first, then use `update_element` to add dynamic attributes:
+   - `textField: "title"` → outputs `{{ $item->title }}`
+   - `hrefField: "slug"` → outputs `href="{{ $item->slug }}"`
+   - `srcField: "featured_image"` → outputs `src="{{ $item->featured_image }}"`
+3. For complex expressions (route helpers, method calls), use:
+   - `hrefExpression: "{{ route('posts.show', $item->slug) }}"`
+   - `srcExpression: "{{ $item->featured_image }}"`
+4. For text with Blade code, create a statement with `create_statement_with_code`, then add its UUID to the element's `statements` array via `update_element`
+
+Example loop structure using `s-directive` siblings:
+```
+1. s-directive with statement: "@foreach($posts as $item)"
+2. article element (content to repeat)
+3. s-directive with statement: "@endforeach"
+```
+
+### 5f. Create Partials & Components
+Convert template-parts/ files into Blade partials using `@include`. Static partials receive data via the second argument: `@include('partials.post-card', ['post' => $post])`. If a template part relies on JavaScript for interactivity (e.g. a slider, a filterable gallery, a live search form), create a Vue component instead and ensure it is registered and mounted in `app.js`.
+
+### 5g. Style with Tailwind
+Do not try to port WordPress CSS. Read the visual intent from the theme's CSS/theme.json and apply Tailwind utility classes directly in the Blade templates. For example:
+- WordPress container → `<div class="max-w-4xl mx-auto px-4">`
+- WordPress navigation → `<nav class="flex items-center gap-6">`
+- WordPress post grid → `<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">`
+
+## Step 6 — Review (Optional)
+
+If requested, summarize what was created and note any WordPress features that couldn't be mapped.
+
+## Important Rules
+
+- **Blade for SSR, Vue for interactivity.** If the WordPress source is server-rendered PHP (posts, pages, archives, menus, layouts), create Blade templates using `@extends`, `@section`, `@include`, `@foreach`, `{{ }}` and `{!! !!}`. If the WordPress source uses JavaScript for interactivity (AJAX, dynamic filtering, sliders, modals, live search, infinite scroll), create a Vue component. When creating Vue components, ensure they are registered and mounted in `app.js` via `createApp` — do not just import them.
+- **Do not ask questions** except the two permitted in Step 1 (which theme, and which database mode). Make reasonable decisions and document them.
+- **Work file by file** — read a WordPress file, create the Stellify equivalent, move to the next.
+- **Show progress** — print what you're reading and what you're creating as you go.
+- **Handle block themes** — if theme.json exists and templates are in HTML with block markup (`<!-- wp:xxx -->`), parse the block structure rather than traditional PHP templates. The output is still Blade (or Vue where the block is interactive).
+- **Style with Tailwind** — do not port WordPress CSS. Interpret the visual intent and use Tailwind utilities.
+- **Be pragmatic** — focus on the core templates that define the site's main pages. Skip hyper-specific template variations unless they're clearly important.
+- **Content handling depends on database mode** — In Mode A (existing DB), the content is already there via the WordPress tables. In Mode B (fresh DB), content is separate and can be migrated later.