@blockbite/agent-context 0.1.0

package/mcp-tools.json

@@ -0,0 +1,222 @@
+{
+  "version": "0.1.0",
+  "tools": {
+    "blockbite-connection-status": {
+      "mcp": "blockbite-connection-status",
+      "mode": "project-selection",
+      "purpose": "Check Platform authentication, selected project, and Studio reachability.",
+      "localFallback": null,
+      "readOnly": true
+    },
+    "blockbite-projects-list": {
+      "mcp": "blockbite-projects-list",
+      "mode": "project-selection",
+      "purpose": "List BlockBite Platform projects available to the connected account.",
+      "localFallback": null,
+      "readOnly": true
+    },
+    "blockbite-project-select": {
+      "mcp": "blockbite-project-select",
+      "mode": "project-selection",
+      "purpose": "Select the active BlockBite Platform project for subsequent Studio tool calls.",
+      "localFallback": null,
+      "readOnly": false
+    },
+    "blockbite-islands-list": {
+      "mcp": "blockbite-islands-list",
+      "mode": "read",
+      "purpose": "List published BlockBite islands on the selected WordPress site.",
+      "localFallback": "Use the WordPress admin or supported local CLI for island inventory; do not read public REST island endpoints.",
+      "readOnly": true
+    },
+    "blockbite-agent-onboarding": {
+      "mcp": "blockbite/agent-onboarding",
+      "mode": "read",
+      "plane": "workspace",
+      "scope": "agent:onboarding",
+      "purpose": "Return workspace layout, sandbox rules, preview URLs, readiness, and recommended tool order.",
+      "localFallback": "wp bb learn --format=codex",
+      "readOnly": true
+    },
+    "blockbite-workspace-status": {
+      "mcp": "blockbite/workspace-status",
+      "mode": "read",
+      "plane": "workspace",
+      "scope": "workspace:read",
+      "purpose": "Inspect workspace root, source mode, directories, counts, and build state.",
+      "localFallback": "wp bb learn",
+      "readOnly": true
+    },
+    "blockbite-workspace-list": {
+      "mcp": "blockbite/workspace-list",
+      "mode": "read",
+      "plane": "workspace",
+      "scope": "workspace:read",
+      "purpose": "List files below the BlockBite workspace using safe relative paths.",
+      "localFallback": "List files under the resolved BlockBite workspace root after running wp bb learn.",
+      "readOnly": true
+    },
+    "blockbite-workspace-read": {
+      "mcp": "blockbite/workspace-read",
+      "mode": "read",
+      "plane": "workspace",
+      "scope": "workspace:read",
+      "purpose": "Read an allowed text file from the BlockBite workspace.",
+      "localFallback": "Read the workspace file after resolving the workspace root with wp bb learn.",
+      "readOnly": true
+    },
+    "blockbite-workspace-search": {
+      "mcp": "blockbite/workspace-search",
+      "mode": "read",
+      "plane": "workspace",
+      "scope": "workspace:search",
+      "purpose": "Search allowed workspace text files and return matching paths and excerpts.",
+      "localFallback": "Use rg within the resolved BlockBite workspace.",
+      "readOnly": true
+    },
+    "blockbite-template-analyze": {
+      "mcp": "blockbite/template-analyze",
+      "mode": "read",
+      "plane": "workspace-with-db-overlay",
+      "scope": "workspace:read",
+      "purpose": "Analyze a dynamic-template package, fields, seeds, records, and styling validation.",
+      "localFallback": "Inspect templates/<slug>/ files and run wp bb validate before editing.",
+      "readOnly": true
+    },
+    "blockbite-template-render-preview": {
+      "mcp": "blockbite/template-render-preview",
+      "mode": "preview",
+      "plane": "workspace",
+      "scope": "preview:render",
+      "purpose": "Render a seed-backed dynamic-template preview without touching live posts.",
+      "localFallback": "Open /?blockbite_preview=1&template=true&slug=<slug> or the matching file-backed preview URL.",
+      "readOnly": true
+    },
+    "blockbite-validate-workspace": {
+      "mcp": "blockbite/validate-workspace",
+      "mode": "read",
+      "plane": "workspace",
+      "scope": "workspace:validate",
+      "purpose": "Validate workspace package files without mutating content.",
+      "localFallback": "wp bb validate",
+      "readOnly": true
+    },
+    "blockbite-build-status": {
+      "mcp": "blockbite/build-status",
+      "mode": "build",
+      "plane": "workspace",
+      "scope": "workspace:read",
+      "purpose": "Read auto-build mode and dirty bundle status for production or sandbox output.",
+      "localFallback": "wp bb learn, then use wp bb autobuild only in auto-build mode.",
+      "readOnly": true
+    },
+    "blockbite-build-run": {
+      "mcp": "blockbite/build-run",
+      "mode": "build",
+      "plane": "build",
+      "scope": "build:assets",
+      "purpose": "Start a signed auto-build run for dirty bundles.",
+      "localFallback": "wp bb autobuild",
+      "readOnly": false
+    },
+    "blockbite-sync-plan-create": {
+      "mcp": "blockbite/sync-plan-create",
+      "mode": "read",
+      "plane": "workspace-with-db-overlay",
+      "scope": "sync-plan:create",
+      "purpose": "Create a draft sync plan comparing template files with database records.",
+      "localFallback": "Use local package inspection and wp bb dynamic-template/dynamic-content commands only after reviewing the target package.",
+      "readOnly": true
+    },
+    "blockbite-sync-plan-diff": {
+      "mcp": "blockbite/sync-plan-diff",
+      "mode": "read",
+      "plane": "workspace-with-db-overlay",
+      "scope": "sync-plan:diff",
+      "purpose": "Return explicit current-state comparisons for a draft sync plan.",
+      "localFallback": "Compare local package files and registered dynamic-template/dynamic-content state before syncing.",
+      "readOnly": true
+    },
+    "blockbite-template-update-draft": {
+      "mcp": "blockbite/template-update-draft",
+      "mode": "read",
+      "plane": "sandbox",
+      "scope": "template:update-draft",
+      "purpose": "Plan sandbox edits for an existing template and return suggested tools and preview guidance.",
+      "localFallback": "Read templates/<slug>/, edit local files, then run wp bb validate and the appropriate update/sync commands.",
+      "readOnly": true
+    },
+    "blockbite-sandbox-status": {
+      "mcp": "blockbite/sandbox-status",
+      "mode": "read",
+      "plane": "sandbox",
+      "scope": "sandbox:status",
+      "purpose": "Show sandbox readiness and pending change ledger.",
+      "localFallback": "Use the WordPress MCP connection screen or wp bb sandbox commands when available.",
+      "readOnly": true
+    },
+    "blockbite-workspace-write": {
+      "mcp": "blockbite/workspace-write",
+      "mode": "sandbox-write",
+      "plane": "sandbox",
+      "scope": "workspace:write",
+      "purpose": "Write one allowed text file to the sandbox workspace.",
+      "localFallback": "Write files in the resolved local workspace after reading the relevant skill and references.",
+      "readOnly": false
+    },
+    "blockbite-workspace-patch": {
+      "mcp": "blockbite/workspace-patch",
+      "mode": "sandbox-write",
+      "plane": "sandbox",
+      "scope": "workspace:patch",
+      "purpose": "Apply a search-and-replace patch to a sandbox workspace file.",
+      "localFallback": "Patch local workspace files with a focused diff after reading the file.",
+      "readOnly": false
+    },
+    "blockbite-template-scaffold": {
+      "mcp": "blockbite/template-scaffold",
+      "mode": "sandbox-write",
+      "plane": "sandbox",
+      "scope": "template:scaffold",
+      "purpose": "Scaffold a full template package in the sandbox.",
+      "localFallback": "wp bb template scaffold --slug=<slug> --type=<type> --variant=<variant>",
+      "readOnly": false
+    },
+    "blockbite-template-create-draft": {
+      "mcp": "blockbite/template-create-draft",
+      "mode": "sandbox-write",
+      "plane": "sandbox",
+      "scope": "template:create-draft",
+      "purpose": "Create a new template draft in the sandbox, analyze it, and return preview/approval URLs.",
+      "localFallback": "wp bb template scaffold --slug=<slug> --type=<type>, then wp bb validate and preview with seed data.",
+      "readOnly": false
+    },
+    "blockbite-build-assets": {
+      "mcp": "blockbite/build-assets",
+      "mode": "build",
+      "plane": "sandbox",
+      "scope": "build:assets",
+      "purpose": "Ensure sandbox upload build directories exist.",
+      "localFallback": "wp bb autobuild prepares local build outputs in auto-build mode.",
+      "readOnly": false
+    },
+    "blockbite-design-token-write": {
+      "mcp": "blockbite/design-token-write",
+      "mode": "sandbox-write",
+      "plane": "sandbox-with-db",
+      "scope": "design-token:write",
+      "purpose": "Write Tailwind v4 design token CSS to the sandbox design-token row.",
+      "localFallback": "Edit dev/css/design-tokens.css and run wp bb design-tokens local-to-db.",
+      "readOnly": false
+    },
+    "blockbite-asset-import": {
+      "mcp": "blockbite/asset-import",
+      "mode": "sandbox-write",
+      "plane": "sandbox-with-assets",
+      "scope": "asset:import",
+      "purpose": "Import Figma MCP asset URLs into sandbox uploads and return local media seed metadata.",
+      "localFallback": "Download/import assets into WordPress media or the workspace asset convention before using them in seeds.",
+      "readOnly": false
+    }
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@blockbite/agent-context",
+  "version": "0.1.0",
+  "description": "BlockBite agent skills, MCP tool index, local fallbacks, references, and examples.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skills",
+    "references",
+    "examples",
+    "index.json",
+    "mcp-tools.json"
+  ],
+  "exports": {
+    "./skills/*": "./skills/*",
+    "./references/*": "./references/*",
+    "./examples/*": "./examples/*",
+    "./index.json": "./index.json",
+    "./mcp-tools.json": "./mcp-tools.json",
+    "./package.json": "./package.json"
+  }
+}

package/references/block-dsl.md

@@ -0,0 +1,257 @@
+# Block DSL
+
+BlockBite dynamic templates can use HTML-like UI DSL tags inside
+`template.liquid`. This is the compact agent reference for the atom block DSL.
+It summarizes the docs in `packages/docs/src/06-atom-blocks`.
+
+## Core Rules
+
+- Use lowercase kebab-case tags: `<bb-button>`, `<bb-group>`,
+  `<core-paragraph>`.
+- A block name maps to a tag by replacing `/` with `-`: `bb/button` becomes
+  `<bb-button>`, `core/paragraph` becomes `<core-paragraph>`.
+- Attribute names are lowercase kebab-case. The compiler maps attributes such
+  as `link-url` and `content-tag` to internal camelCase props such as `linkUrl`
+  and `contentTag`.
+- Use `class` for Tailwind classes. Authored DSL classes are preserved by
+  default; use an explicit `{{ '...' | tw_merge }}` expression only when you
+  deliberately want Tailwind conflict resolution.
+- Token-backed Tailwind classes should be checked against the CSS-first source
+  at `<workspace>/dev/css/design-tokens.css`; use `wp bb design-tokens local-to-db`
+  after editing it or `wp bb design-tokens db-to-local` to refresh from DB content.
+- Attribute values can be literals, Liquid expressions such as
+  `{{ props.fields.title }}`, or Liquid block syntax for conditional values such
+  as `class="{% if item.featured %}border-black{% endif %}"`.
+- Keep Liquid block syntax inside attributes compact or use whitespace-trimmed
+  tags (`{%- ... -%}`), especially for `class` values.
+- Container tags can wrap child DSL tags. Media-style tags are normally
+  self-closing.
+- Use `field="{{ props.fields.some_object }}"` when a block supports a grouped
+  field object.
+
+## Example
+
+```liquid
+<bb-group class="grid gap-4">
+  <core-heading
+    level="2"
+    content="{{ props.fields.heading }}"
+    class="text-3xl font-semibold"
+  />
+  <core-paragraph
+    content="{{ props.fields.body }}"
+    class="text-base text-neutral-700"
+  />
+  <bb-button
+    link-url="{{ props.fields.cta.linkUrl }}"
+    link-title="{{ props.fields.cta.linkTitle }}"
+    link-target="{{ props.fields.cta.linkTarget }}"
+    class="inline-flex items-center rounded px-4 py-2"
+  />
+</bb-group>
+```
+
+## BlockBite Tags
+
+| Tag                   | Block               | Common attrs                                                                                                                                |
+| --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<bb-button>`         | `bb/button`         | `class`, `bb-style`, `field`, `link-url`, `link-title`, `link-target`, `text`, `content`, `label`, `role`, `id`, `tabindex`, `data`, `aria` |
+| `<bb-fill>`           | `bb/fill`           | `type`, `class`, `field`, `url`, `src`, `alt`, `autoplay`, `loop`, `hover`, `playOnScroll`, `direction`, `parentHover`                      |
+| `<bb-fills>`          | `bb/fills`          | `class`, child `<bb-fill>` layers                                                                                                           |
+| `<bb-frame>`          | `bb/frame`          | `class`, child content                                                                                                                      |
+| `<bb-group>`          | `bb/group`          | `class`, `tag`, `link-url`, `link-title`, `link-target`, child content                                                                      |
+| `<bb-icon>`           | `bb/icon`           | `class`, `field`, `svg-url`, `svg-id`, `url`, `src`, `link-url`, `link-title`, `link-target`, `role`, `id`, `tabindex`, `data`, `aria`      |
+| `<bb-image>`          | `bb/image`          | `class`, `url`, `src`, `field`, `alt`, `role`, `id`, `title`, `loading`, `decoding`, `data`, `aria`                                         |
+| `<bb-richtext>`       | `bb/richtext`       | `class`, `content`, `content-tag`, `content-string`, `text-align`, child fallback content                                                   |
+| `<bb-richtext-group>` | `bb/richtext-group` | `class`, `content`, `content-tag`, child content                                                                                            |
+| `<bb-shape>`          | `bb/shape`          | `class`, `svg-url`, `url`, `src`, child content                                                                                             |
+
+## Core Tags
+
+| Tag                | Block            | Common attrs                                                                                            |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------- |
+| `<core-heading>`   | `core/heading`   | `class`, `content`, `field`, `level`, `role`, `id`, `data`, `aria`                                      |
+| `<core-paragraph>` | `core/paragraph` | `class`, `content`, `field`                                                                             |
+| `<core-button>`    | `core/button`    | `class`, `url`, `link-url`, `text`, `title`, `link-title`, `link-target`, `rel`, `field`, child content |
+| `<core-buttons>`   | `core/buttons`   | `class`, child content                                                                                  |
+| `<core-image>`     | `core/image`     | `class`, `url`, `src`, `field`, `alt`                                                                   |
+| `<core-video>`     | `core/video`     | `class`, `field`, `src`, `url`, `poster`, `embed-url`, `title`, `provider-name-slug`, `media-class`     |
+| `<core-group>`     | `core/group`     | `class`, child content                                                                                  |
+| `<core-row>`       | `core/row`       | `class`, child content                                                                                  |
+| `<core-columns>`   | `core/columns`   | `class`, `columns`, child content                                                                       |
+
+Other core tags are available from the selected version's `core` folder, such
+as `core-html`, `core-list`, `core-quote`, `core-separator`, `core-shortcode`,
+and `core-video`.
+
+## Dynamic Template Pattern
+
+Choose the source type before writing bindings:
+
+- `block_instance`: the inserted template block instance owns `props.fields` and
+  `props.subcollections`.
+- `post_type`: the current CPT/single post source owns `props.fields` and
+  `props.subcollections`.
+- `block_instance` plus `post_relation`: the inserted instance owns a relation field;
+  with `include_source: true`, selected post source fields are nested under
+  that relation item, such as `props.fields.work.source.work.client`.
+
+Do not use relation-nested paths for templates that should render the current
+CPT item. Use `post_type` and direct field paths.
+
+Use the standard runtime prelude before DSL or HTML:
+
+```liquid
+{% assign seed_data = 'seeds.json' | bb_seed %}
+{% assign data = item | bb_source %}
+{% assign props = live | ternary: data, seed_data %}
+```
+
+Then bind fields through `props`:
+
+```liquid
+<core-heading content="{{ props.fields.title }}" />
+
+{% for item in props.subcollections.cards %}
+  <bb-group class="rounded border p-6">
+    <core-heading content="{{ item.heading }}" />
+    <bb-richtext content="{{ item.text }}" content-tag="div" />
+  </bb-group>
+{% endfor %}
+```
+
+## Fill Layers
+
+Use `bb-fills` and `bb-fill` for visual layers inside a dynamic template. This
+is the canonical API for hero backgrounds, image overlays, solid color layers,
+and gradients. Do not pass fills as props on `bb-group`; keep them as child
+layers inside the element that owns the sizing.
+
+```liquid
+<bb-group tag="section" class="relative isolate min-h-[720px] overflow-hidden">
+  <bb-fills>
+    <bb-fill
+      type="image"
+      field="{{ props.fields.hero_artwork }}"
+      class="opacity-70 sepia contrast-125"
+    />
+    <bb-fill
+      type="gradient"
+      class="bg-gradient-to-b from-brand-a/35 via-brand-a/15 to-brand-a/80"
+    />
+  </bb-fills>
+
+  <bb-richtext content="{{ props.fields.title }}" content-tag="h1" class="relative z-10" />
+</bb-group>
+```
+
+Supported fill types:
+
+- `image`: accepts `field`, `url`, or `src`; `alt` falls back to the media
+  field alt text. The `class` value is applied to `.b_media`.
+- `video`: accepts `url` or `src`. The `class` value is applied to `.b_fill`.
+- `lottie`: accepts `url` or `src`, plus `autoplay`, `loop`, `hover`,
+  `playOnScroll`, `direction`, and `parentHover`. The `class` value is applied
+  to `.b_fill`.
+- `solid` and `gradient`: render non-media `.b_fill` layers. Use Tailwind
+  background classes for the visual style.
+
+Use `bb-image` or `core-image` for content images that belong in the layout.
+When an image is only a background/fill layer, use `bb-fill type="image"` so the
+editor inline preview and media editing paths treat it like a fill instead of a
+normal-flow image.
+
+## Component Selection
+
+- Use `core-heading` and `core-paragraph` for simple text atoms.
+- Use `bb-richtext` when authored copy may contain inline formatting or HTML.
+- Use `bb-button` or `core-button` for links/actions; prefer grouped link
+  fields when possible.
+- When a template needs a reusable visual variant, especially buttons, check
+  `<workspace>/blocks/<namespace>/<block>` first and create/update a shared
+  block style instead of repeating long Tailwind classes inline.
+- Use `bb-image` or `core-image` for content media fields that should
+  participate in layout.
+- Use `core-video` for content videos. It supports uploaded/media-library video
+  via `field`, `src`, `url`, and `poster`, and YouTube embeds via `embed-url`
+  with `provider-name-slug="youtube"`. For YouTube, bind the actual URL to
+  `embed-url`; do not hand-roll raw iframes or `data-youtube-src` hydration in
+  templates.
+- Use `bb-group` for generic layout wrappers, repeated card bodies, and linked
+  media/card wrappers. When `link-url` is present it renders an anchor and
+  overrides `tag`.
+- Use `bb-fills` with child `bb-fill` layers for section backgrounds, overlays,
+  and editor-editable fill images.
+- Use `bb-frame` for framed or constrained section structures.
+- Use `bb-icon` and `bb-shape` for SVG fields/assets.
+
+## Shared Block Styles
+
+Block styles are authored with the same DSL in:
+
+```text
+<workspace>/blocks/<namespace>/<block>/styles/<style-slug>.template.liquid
+```
+
+They compile to:
+
+```text
+<workspace>/autobuild/css/block-styles.css
+```
+
+Never edit `autobuild/css/block-styles.css` by hand. Regenerate it after editing style
+templates:
+
+```bash
+wp bb autobuild
+```
+
+For example, a `bb/button` style can define the wrapper, rich text, and icon
+atoms in one shared variant:
+
+```liquid
+<bb-button class="inline-flex items-center rounded-full bg-brand-a-900 px-4 py-2 text-neutral-50">
+  <bb-richtext content-tag="span" class="font-body text-lg font-medium leading-[1.4]" />
+  <bb-icon class="size-4 shrink-0" />
+</bb-button>
+```
+
+If the block folder does not exist in the workspace, scaffold it first:
+
+```bash
+wp bb offload bb/button --workspace
+```
+
+## Design Token Context
+
+Design tokens are authored locally as Tailwind v4 `@theme` CSS. The workspace
+file lives at:
+
+```text
+<workspace>/dev/css/design-tokens.css
+```
+
+Refresh it from Studio with:
+
+```bash
+wp bb design-tokens db-to-local
+```
+
+After manual edits, update Studio and rebuild the derived database token index with:
+
+```bash
+wp bb design-tokens local-to-db
+```
+
+Use configured tokens to choose classes such as `font-body`,
+`text-neutral-100`, `bg-neutral-100`, and `border-neutral-100`.
+
+## Validation Notes
+
+- Use `wp bb props [namespace/block]` when prop names are unclear.
+- Use `wp bb autobuild` after editing block style templates to regenerate generated
+  CSS and queue all frontend bundles.
+- Keep field handles stable. Dynamic-content field ids live in the database,
+  not in `fields.yaml`.
+- Keep generated DSL readable. Remove noisy wrappers when plain HTML or a
+  smaller DSL tree is clearer.

package/references/islands.md

@@ -0,0 +1,111 @@
+# BlockBite Island Architecture
+
+Use this reference when cloning or recreating a page as a set of BlockBite dynamic-template islands.
+
+For syncing islands to Blockbite Platform (export bundles, preview snapshots, dashboard), see [[Island Platform Sync|Island-Platform-Sync]].
+
+For local island bundle export/import between WordPress projects ([#1946](https://github.com/block-bite/blockbite/issues/1946)), see [[Island Sync|Island-Sync]].
+
+## Start With Global Sweep Research
+
+Before implementing any island, inspect the original page from top to bottom:
+
+- Map the full page structure: nav, hero, sections, repeated patterns, footer, overlays, and sticky elements.
+- Capture responsive behavior across mobile, tablet, and desktop.
+- Identify assets: images, video, SVGs, fonts, icons, masks, gradients, and externally loaded media.
+- Inspect DOM, CSS, and JavaScript for the original site before coding each island.
+- Classify motion as CSS keyframes, GSAP/Webflow JavaScript, Alpine, or static.
+- Note repeated spacing, typography, color, border, and container rules so islands feel like one page.
+
+Do not start by coding the visible first section only. The global sweep determines island boundaries, shared styling, asset needs, and homepage assembly order.
+
+## Island Order
+
+Create independent islands in page order:
+
+1. Nav island.
+2. One island per homepage section, top to bottom.
+3. Footer island.
+
+Each island should be independently previewable before homepage assembly. For
+multi-section review, follow the `render-preview` workflow and create an
+aggregate preview package such as `templates/preview-home/template.liquid` rather
+than creating a temporary WordPress page.
+
+For file-backed previews, use:
+
+```text
+/?blockbite_preview=1&template=true&view=templates/<slug>/template.liquid
+```
+
+For registered templates, use:
+
+```text
+/?blockbite_preview=1&template=true&slug=<slug>
+```
+
+For aggregate previews, render child views with the `bb_template_preview` filter
+so each child template uses its own `seeds.json`:
+
+```liquid
+<main data-bb-preview="home">
+  {{ 'templates/nav/template.liquid' | bb_template_preview | raw }}
+  {{ 'templates/home-hero/template.liquid' | bb_template_preview | raw }}
+  {{ 'templates/footer/template.liquid' | bb_template_preview | raw }}
+</main>
+```
+
+Avoid plain `{% render 'child/template.liquid' %}` for standard dynamic-template
+packages in aggregate previews; it can inherit the parent preview seed context.
+
+## Template And Style Split
+
+Prefer Tailwind classes in `template.liquid` for layout, spacing, typography, color, and straightforward responsive behavior.
+
+Keep `style.css` for:
+
+- CSS keyframes.
+- Pseudo-elements.
+- Carousel or marquee mechanics.
+- Complex selectors.
+- Browser-specific fixes.
+- Behavior Tailwind cannot express cleanly.
+
+Keep island JavaScript close to the island that owns the behavior, usually in `module.ts`, and avoid global scripts unless the interaction is truly shared.
+
+## Cloned Or Reference Sites
+
+For cloned/reference sites, inspect the original DOM, CSS, and JS before coding each island:
+
+- Check computed styles, not only visible screenshots.
+- Look for Webflow/GSAP timelines, scroll triggers, Alpine directives, CSS animations, and transition delays.
+- Decide whether the exact motion matters or whether a simpler static or CSS-only version is sufficient.
+- Reuse assets intentionally; do not approximate inspection-critical images with generic placeholders.
+
+## Homepage Assembly
+
+After the aggregate preview is accepted, assemble the homepage with one
+`bb/dynamic-template` block per island in page content:
+
+```html
+<!-- wp:bb/dynamic-template {"contentId":"...","templateId":"...","sourceType":"block_instance","dataMode":"seed","engine":"liquid","tag":"section","align":"full","metadata":{"name":"Section name"}} /-->
+```
+
+Use clear metadata names for each island so the editor remains understandable.
+
+## Validation Flow
+
+Before registering or assembling:
+
+```bash
+ddev wp bb validate
+```
+
+After editing frontend templates, styles, scripts, or block styles:
+
+```bash
+ddev wp bb autobuild
+```
+
+If Node.js is unavailable, open the signed browser fallback URL printed by
+`wp bb autobuild` and wait for success.