@blockbite/agent-context 0.1.0

package/references/tailwind-utilities.md

@@ -0,0 +1,108 @@
+# BlockBite Tailwind Utilities
+
+Use this reference when writing Tailwind classes in BlockBite templates, block
+styles, preview templates, or workspace CSS. BlockBite loads the
+`@blockbite/tailwind` plugin in the generated Tailwind pipeline, so these
+utilities are available without adding another build step.
+
+Use unprefixed classes unless the workspace explicitly configures a Tailwind
+class prefix.
+
+## Grid Area Utilities
+
+Use `grid-area-[cols/rows]` on a container to create a CSS grid with explicit
+column and row counts.
+
+Use `area-[row-start/col-start/row-end/col-end]` on direct children to set the
+child placement. The `area-*` utility stores the value in `--area`; the
+`grid-area-*` container applies it to direct children.
+
+```liquid
+<section class="grid-area-[12/6] gap-4">
+  <article class="area-[2/2/4/6] rounded-lg bg-white p-6">
+    ...
+  </article>
+</section>
+```
+
+`area-[2/2/4/2]` is valid syntax, but remember that CSS grid line values follow
+`row-start / column-start / row-end / column-end`. Choose end lines that create
+the intended span. Slash and dash separators are accepted, for example
+`area-[2-2-4-6]`.
+
+## Direct-Child Variants
+
+Use `children:*` for all direct children and `children-<tag>:*` for supported
+direct child elements. These are useful for rich text, generated block output,
+and repeated child elements where adding a class to each child is noisy.
+
+Supported element variants:
+
+- `children-p:*`
+- `children-a:*`
+- `children-img:*`
+- `children-ol:*`
+- `children-ul:*`
+- `children-li:*`
+- `children-h1:*`
+- `children-h2:*`
+- `children-blockquote:*`
+
+```liquid
+<div class="children-p:mb-4 children-a:underline children-img:rounded-lg">
+  {{ props.fields.body | bb_str | raw }}
+</div>
+```
+
+## Prose And Rich Text
+
+For rich text/prose wrappers, combine direct-child variants with normal Tailwind
+utilities. Use Tailwind color utilities such as `text-white`, so the child
+variant form is `children:text-white`, `children-p:text-white`, or
+`children-a:text-white`.
+
+```liquid
+<div class="children:text-white children-p:mb-4 children-p:text-white children-a:text-white children-a:underline children-h2:text-white">
+  {{ props.fields.body | bb_str | raw }}
+</div>
+```
+
+Do not use `children:color-white` unless the workspace has explicitly defined a
+custom `color-white` utility. In standard Tailwind syntax, text color is
+`text-white`.
+
+## Containers
+
+Use BlockBite container classes for site-width alignment before writing custom
+width CSS:
+
+- `container`: standard site-width wrapper using `--bb-container-width`.
+- `container-wide`: wider wrapper using `--bb-container-wide-width`.
+- `container-full`: full-width wrapper using `--bb-container-full-width` and
+  full-container padding when configured.
+- `container-inner`: applies calculated inner left and right padding without
+  constraining width.
+- `container-inner-left`: aligns only the left side to the standard container
+  inset.
+- `container-inner-right`: aligns only the right side to the standard container
+  inset.
+
+These classes read BlockBite container CSS variables from the workspace theme
+and generated design-token layer.
+
+```liquid
+<section class="container-full bg-neutral-950 py-20">
+  <div class="container-inner">
+    <div class="max-w-3xl children:text-white children-p:text-white">
+      {{ props.fields.body | bb_str | raw }}
+    </div>
+  </div>
+</section>
+```
+
+## Other Utilities And Variants
+
+- `b_mask-text`: clips the background to text; pair it with background classes.
+- `editor:*`: scopes a utility to `.editor-styles-wrapper &` for editor-only
+  adjustments. Use this only when the frontend and editor genuinely need
+  different styling.

package/skills/analyze-template/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: analyze-template
+description: Analyze a BlockBite dynamic template package (files, fields.yaml, seeds.json, and matching DB records) before editing. Use when the user wants to understand or audit an existing template.
+---
+
+# Analyze a BlockBite template
+
+## Steps
+
+1. Ensure a project is selected (connection-status / project-select).
+2. Call `blockbite-template-analyze` with either `{ "slug": "<slug>" }` or
+   `{ "view": "templates/<slug>/template.liquid" }`.
+3. Set `{ "preferSandbox": true }` to inspect pending sandbox changes first.
+4. Summarize package files, `fields.yaml` validity, `seeds.json` shape, and the
+   read-only dynamic-template / dynamic-content records.
+
+## Next
+
+- Preview with the render-preview skill.
+- Plan edits with the update-template-draft skill (writes go to the sandbox).

package/skills/block-style/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: block-style
+description: Create or refine BlockBite shared block styles for workspace blocks. Use when the user wants Tailwind-powered styles for blocks such as bb/button, core/button, bb/group, quote, cards, or any blocks/<namespace>/<block>/styles/*.template.liquid variant, including checking workspace block availability and regenerating frontend assets with wp bb autobuild.
+---
+
+# Block Style
+
+Create or refine a shared block style in the active BlockBite workspace.
+
+Before authoring DSL tags, read `../references/block-dsl.md` when it exists.
+For BlockBite-specific Tailwind utilities such as `area-[...]`, `grid-area-[...]`, and `children:*`, read `../references/tailwind-utilities.md` when it exists.
+When choosing token-backed Tailwind classes, run `wp bb design-tokens db-to-local` if needed and read `<workspace>/dev/css/design-tokens.css`.
+
+## Agent Contract
+
+The agent is the interface; WP-CLI is only the executor. Do not rely on interactive CLI prompts. Resolve the block and style name from the chat, infer sensible defaults when safe, then run commands with full flags.
+
+## Build Mode Contract
+
+Treat BlockBite's reported build mode as authoritative:
+
+- auto-build: after template, style, script, or block-style edits, run `ddev wp bb autobuild`; if Node.js is unavailable, open the signed browser fallback URL.
+- custom-build: do not use the signed browser runner; use the project-specific frontend build pipeline.
+- Default to auto-build for template and site work unless `wp bb learn`, `wp bb init`, or `dev/template-start/latest.json` explicitly reports custom-build.
+- Do not infer custom-build from development manifests in mounted plugins or neighboring projects.
+- Do not start, repair, shim, or mutate external Vite/Webpack setup unless the user explicitly asks for plugin development or custom-build work.
+- If autobuild stalls or fails, report the runner status and stop before changing build setup.
+
+## Workspace Contract
+
+Block styles live in:
+
+```text
+<workspace>/blocks/<namespace>/<block>/styles/<style-slug>.template.liquid
+```
+
+The generated CSS lives in:
+
+```text
+<workspace>/autobuild/css/block-styles.css
+```
+
+Never edit `autobuild/css/block-styles.css` by hand. In auto-build mode, run:
+
+```bash
+ddev wp bb autobuild
+```
+
+If Node.js is unavailable, open the printed browser fallback URL and wait for
+the runner to finish before inspecting generated output.
+
+## Workflow
+
+1. Resolve the workspace root and inspect `<workspace>/blocks/<namespace>/<block>`.
+2. If the block folder is missing, check whether the plugin provides it and use:
+
+   ```bash
+   ddev wp bb offload <namespace>/<block> --workspace
+   ```
+
+3. Read `<workspace>/dev/css/design-tokens.css` when token choices matter.
+4. Read the block's `manifest.json` and existing `styles/*.template.liquid`.
+5. Reuse an existing style when it already matches the requested role.
+6. Create or update a style DSL file with Tailwind classes on the block tag.
+7. Build according to the reported build mode. In auto-build mode, run `ddev wp bb autobuild`.
+8. If Node.js is unavailable, open the printed signed browser fallback URL and wait for success.
+9. Inspect `autobuild/css/block-styles.css` for the expected selector and classes.
+
+## Style DSL
+
+Use the same DSL as dynamic templates:
+
+```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>
+```
+
+For `bb/button`, prefer styling child atoms in the same style file when needed:
+
+- `.wp-block-bb-richtext` through nested `<bb-richtext>`
+- `.wp-block-bb-icon` through nested `<bb-icon>`
+
+## Template Usage
+
+When a dynamic template contains a button, first check whether `bb/button` exists in `<workspace>/blocks`.
+
+Use shared styles for repeated visual variants instead of repeating long Tailwind button classes inside each template.
+
+Use the style by applying the block style attribute supported by the block/component, for example `bb-style` when available, or by using the existing block style selected in WordPress/editor flows.
+
+## Finish
+
+Report:
+
+- block name
+- style slug and file path
+- whether the block was already present or offloaded
+- build command result
+- selector found in `autobuild/css/block-styles.css`

package/skills/connect/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: connect
+description: Connect this agent to the BlockBite Platform MCP server and confirm the connection is live. Use when the user mentions connecting BlockBite, signing in to BlockBite, or when MCP tool calls fail with an authentication error.
+---
+
+# Connect to BlockBite
+
+BlockBite Platform is the single MCP server. The agent talks only to Platform;
+Platform routes approved calls to the selected WordPress Studio site.
+
+## Steps
+
+1. Ensure the `blockbite` MCP server is configured (remote HTTP to the Platform
+   `/mcp` endpoint). The plugin ships this in its MCP config.
+2. On first use, complete the Platform OAuth flow in the browser when prompted.
+3. Verify the connection by calling `blockbite-connection-status`.
+4. If no project is selected yet, call `blockbite-projects-list` then
+   `blockbite-project-select`.
+
+## Notes
+
+- You never handle WordPress bearers or site URLs directly. Platform owns
+  project routing, the Studio bearer, and audit.
+- If a call returns a project-selection-required error, run the project-select
+  skill before retrying.

package/skills/connection-status/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: connection-status
+description: Check the BlockBite MCP connection, the selected project, and whether Studio tools are reachable. Use when the user asks if BlockBite is connected or when diagnosing failing tool calls.
+---
+
+# BlockBite connection status
+
+## Steps
+
+1. Call `blockbite-connection-status` (no arguments).
+2. Report: authenticated account, `selected_project`, Studio `site_url`, and
+   whether a Studio bearer is available.
+3. If not connected, run the connect skill. If no project is selected, run the
+   project-select skill.
+
+## `bearer_available: false` is normal after selecting a project
+
+Platform mints the Studio bearer **lazily, on the first Studio tool call** —
+selecting a project intentionally clears it. So `bearer_available: false`
+immediately after `blockbite-project-select` is expected and does **not** mean
+Studio tools are unusable.
+
+- Do **not** treat `bearer_available: false` as a blocker, and **never** fall
+  back to the site's public WordPress REST API (e.g. `/wp-json/...`).
+- To proceed, just call the Studio tool you need (for example
+  `blockbite-islands-list` or `blockbite-workspace-status`). The first such call
+  performs the bearer exchange with WordPress; a follow-up
+  `blockbite-connection-status` will then show `bearer_available: true`.
+- Only if that first Studio tool call returns a `studio_*` error (e.g.
+  `studio_auth_failed`, `studio_bearer_exchange_failed`, `studio_unreachable`)
+  is there a real connection problem — see Troubleshooting.
+
+## Troubleshooting
+
+- `studio_auth_failed`: Platform could not authenticate to the site. Ask the user
+  to reconnect the project from the BlockBite Platform dashboard.
+- `manage_secret_missing`: the site has not completed the management handshake;
+  reconnect the WordPress site so Platform can re-mint the signing secret.

package/skills/create-template-draft/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: create-template-draft
+description: Create a new BlockBite template draft in the sandbox, then preview it. Use when the user wants to build a new section, hero, FAQ, or pattern. All writes stay in the sandbox.
+---
+
+# Create a BlockBite template draft
+
+Writes always target the sandbox overlay. Production is never modified until the
+user approves the sandbox in WordPress.
+
+## Steps
+
+1. Ensure a project is selected.
+2. Call `blockbite-template-create-draft` with a `{ "name": "<section name>" }`
+   or `{ "slug": "<slug>", "type": "<section|hero|faq|...>" }`.
+3. Return the preview URL as the deliverable, plus the approval URL so the user
+   can promote the sandbox.
+4. Iterate with `blockbite-workspace-write` / `blockbite-workspace-patch` and
+   re-preview with the render-preview skill.
+5. After the user approves the sandbox package, use `blockbite-build-status`
+   and `blockbite-build-run` if bundles are dirty. Do not run Node.js, import
+   BlockBite build chunks, or call build request endpoints directly.
+
+## Islands and page sections
+
+When the user asks for an "island", header, hero, nav, footer, or any reusable
+section, author it as a **dynamic-template package** under
+`templates/<slug>/`:
+
+- `template.liquid` — markup with Tailwind utilities / semantic class names
+- `style.css` — keyframes, pseudo-elements, complex selectors only
+- `fields.yaml` — field schema (and `subcollections` if repeated rows)
+- `seeds.json` — preview/sample data
+
+Before writing, read the bundled canonical example at
+`example-use/blockbite/templates/dynamic-template-reference/`. It demonstrates
+the complete package: Liquid data resolution with `bb_seed` / `bb_source`, repeated
+`subcollections`, scoped semantic CSS, local `module.ts` behavior, and
+`manifest.json` wiring.
+
+Do **not** hand-write `islands/<slug>/island-pattern.html`, and do **not** wrap a
+section in a raw `<!-- wp:html --><style>…</style>` block. That `islands/`
+compiled-blocks format (`format: blockbite-ui-dsl`, `mode: compiled-blocks`) is
+generated by the editor/compiler — there is no agent tool to author it.
+
+## Guardrails
+
+- Run `blockbite-agent-onboarding` first if you are unsure of workspace paths or
+  sandbox rules.
+- Check `blockbite-sandbox-status` to see pending changes before adding more.
+- After the package is written, return the `blockbite_preview_mcp` preview URL.
+  Do **not** open a browser or use browser automation to verify — the preview
+  URL is how the user reviews the result.
+- MCP build orchestration stays in MCP tools: use `blockbite-build-status` /
+  `blockbite-build-run`, never local probes.

package/skills/design-tokens/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: design-tokens
+description: Use when working with BlockBite design tokens, workspace dev/css/design-tokens.css, Tailwind theme token availability, or the `wp bb design-tokens` CLI used by agents and local development.
+---
+
+# BlockBite Design Tokens
+
+Use this skill when a task depends on BlockBite design tokens or Tailwind theme tokens.
+
+## Source Of Truth
+
+- `dev/css/design-tokens.css` is the writable local source of truth.
+- Saved design tokens live in Studio under the `design-tokens` item handle.
+- The database `content` column stores the same Tailwind v4 `@theme` CSS as `dev/css/design-tokens.css`.
+- The database `data` column stores a derived `DesignTokenIndex` for Studio UI, MCP, and previews.
+- Agents may add any valid Tailwind v4 `@theme` variable, including custom namespaces. Do not force output into the old normalized token schema.
+- Do not read or write `dev/design-tokens.yaml`; it is no longer part of the token workflow.
+
+## CLI
+
+Sync the workspace CSS and derived token index:
+
+```bash
+wp bb init
+wp bb update skills
+wp bb design-tokens
+wp bb design-tokens db-to-local
+wp bb design-tokens local-to-db
+wp bb design-tokens build
+wp bb design-tokens check
+```
+
+`wp bb init` refreshes this context and installs missing workspace skills. It does not ask interactive CLI questions. Use `wp bb update skills` to overwrite shipped skill boilerplates in `dev/skills` only.
+
+Useful options:
+
+```bash
+wp bb design-tokens db-to-local --out=/absolute/path/dev/css/design-tokens.css
+wp bb design-tokens local-to-db --in=/absolute/path/dev/css/design-tokens.css
+wp bb design-tokens check --in=/absolute/path/dev/css/design-tokens.css
+```
+
+## Workflow
+
+1. Refresh tokens with `wp bb design-tokens db-to-local` when the workspace file may be stale.
+2. Read `<workspace>/dev/css/design-tokens.css` and parse top-level Tailwind v4 `@theme` declarations.
+3. Prefer token classes generated by the parsed namespaces, such as `text-{token}` from `--text-*`, `font-{token}` from `--font-*`, `bg-{token}` / `text-{token}` / `border-{token}` from `--color-*`, `rounded-{token}` from `--radius-*`, and `shadow-{token}` from `--shadow-*`.
+4. Missing font-size steps, color shades, radius values, and other namespace entries are allowed; do not assume unconfigured tokens exist.
+5. For block style work, combine this with the `block-style` skill and the shared DSL reference at `../references/block-dsl.md` when available.
+
+## Contract
+
+Write Tailwind v4 `@theme` CSS, not normalized token arrays or the previous YAML-style schema.
+Manual CSS edits do not update Studio until `wp bb design-tokens local-to-db` runs.

package/skills/document-blueprint/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: document-blueprint
+description: Create or refine BlockBite workspace document blueprints that assemble full WordPress pages from ordered dynamic-template sections, section seed files, and existing content blueprints without writing directly to the database.
+---
+
+# Document Blueprint
+
+Use this skill when the user wants a full page/document assembled from existing BlockBite dynamic templates and content blueprints.
+
+Document blueprints are workspace files. Do not write page content directly into the database. The import flow overwrites a selected page with managed `bb/dynamic-template` blocks and imports section seed files into block-instance dynamic content sources.
+
+## File Contract
+
+Create document blueprints under:
+
+```txt
+<workspace>/document-blueprints/<slug>/
+  blueprint.json
+  sections/
+    <section-key>.seed.json
+```
+
+`blueprint.json`:
+
+```json
+{
+  "title": "Home",
+  "description": "Home page document blueprint",
+  "sections": [
+    {
+      "key": "hero",
+      "name": "Hero",
+      "template": "home-hero",
+      "dynamicContent": "home-hero",
+      "tag": "section",
+      "align": "full",
+      "seed": "sections/hero.seed.json"
+    }
+  ]
+}
+```
+
+Section seed files:
+
+```json
+{
+  "fields": {
+    "headline": "Production headline",
+    "body": "Production copy"
+  },
+  "subcollections": {}
+}
+```
+
+Field keys in `fields` and `subcollections` must match the target content blueprint handles or field ids.
+
+## Workflow
+
+1. If no document blueprint exists, scaffold one:
+
+```bash
+ddev wp bb document-blueprint scaffold --slug=home
+```
+
+For multiple pages or content-heavy page plans, prefer the PHP/WP-CLI generator
+instead of ad hoc Node/Python scripts:
+
+```bash
+ddev wp bb document-blueprint generate --file=document-blueprints.spec.json
+ddev wp bb document-blueprint generate --file=document-blueprints.spec.json --overwrite
+```
+
+Spec files may contain one blueprint object, a `blueprints` array, or a `pages`
+array. Each section must include `key` and `template`; `dynamicContent` defaults
+to `template`. Put seed content directly on the section as `fields` and
+`subcollections`, or as a `seedData` object:
+
+```json
+{
+  "blueprints": [
+    {
+      "slug": "style-editor",
+      "title": "Style Editor",
+      "description": "Conversion page for the visual style editor.",
+      "sections": [
+        {
+          "key": "header",
+          "name": "Page header",
+          "template": "editorial-centered-statement",
+          "fields": {
+            "eyebrow": "Style Editor",
+            "heading": "Style WordPress blocks without leaving the editor.",
+            "text": "Use visual controls, responsive targeting, and Tailwind-compatible class input."
+          },
+          "subcollections": {}
+        }
+      ]
+    }
+  ]
+}
+```
+
+2. Replace scaffold placeholder slugs with existing registered slugs:
+
+- `template`: dynamic template slug.
+- `dynamicContent`: content blueprint slug. If omitted, it defaults to the template slug.
+
+3. For each section, read the target template/content schema before editing the seed. Keep section keys stable because re-import matches managed sections by `blueprint + section`.
+
+4. Keep one seed file per section. Use `fields` for section-level values and `subcollections` for repeaters.
+
+5. Validate before importing:
+
+```bash
+ddev wp bb document-blueprint validate
+ddev wp bb document-blueprint validate --slug=home
+```
+
+6. For visual review before import, create a file-backed preview package:
+
+```txt
+<workspace>/templates/<blueprint-slug>-preview/template.liquid
+```
+
+Use the `bb_document_blueprint` filter so BlockBite renders the blueprint sections in order with their section seed files:
+
+```liquid
+<main class="bb-document-blueprint-preview" data-bb-document-blueprint-preview="home">
+  {{ "home" | bb_document_blueprint | raw }}
+</main>
+```
+
+Open it through the normal template preview route:
+
+```txt
+/?blockbite_preview=1&template=true&view=templates/<blueprint-slug>-preview/template.liquid&dataMode=seed
+```
+
+This preview is read-only. It must not create a page, update `post_content`, or import dynamic content source rows.
+
+7. Import from the Studio Document blueprints UI only after the selected page is safe to overwrite.
+
+## Import Semantics
+
+The importer writes only managed dynamic template blocks into page `post_content`. Existing unmarked blocks are removed because document blueprint import is explicitly overwrite.
+
+Managed blocks are marked with:
+
+```json
+{
+  "bbMeta": {
+    "documentBlueprint": {
+      "blueprint": "home",
+      "section": "hero"
+    }
+  }
+}
+```
+
+On re-import, matching managed document blueprint sections reuse/update their existing block-instance source rows instead of duplicating them.
+
+## Preview Semantics
+
+`bb_document_blueprint` reads `document-blueprints/<slug>/blueprint.json`, loads each section seed from that blueprint folder, and renders each referenced `templates/<section.template>/template.liquid` with the blueprint seed as `item` and `live: true`.
+
+Use this for in-between page review. Use the importer only when the user wants the blueprint written into a real WordPress page.