# AI-native block development

Files and no build step, which is what agents are good at.

[Read the docs](https://blockstudio.dev/docs/dev/ai/)

A silent screen recording: a coding agent builds a complete WordPress site with 10 custom blocks and 6 pages from a single prompt.

## Describe a block, get a block

AI coding agents can scaffold blocks, pages, and patterns from one prompt. No GUI and no database, just files.

~/starter-theme

❯ Create a pricing block with three tiers, a monthly/annual toggle, and a CTA for each tier.

✓ Created pricing/block.json

✓ Created pricing/index.php

✓ Created pricing/style.css

❯ Now create a pricing page with a hero and FAQ section.

✓ Created pages/pricing/page.json

✓ Created pages/pricing/index.php

Files

blockstudio/

├── pricing/ New

├── block.json

├── index.php

└── style.css

pages/

├── pricing/ New

├── page.json

└── index.php

## File-based everything

Blocks, pages, patterns, and extensions are directories with JSON config and templates. Agents read and write them natively.

## Zero database config

No admin panels to click through. Every setting is a JSON key, so an agent can scaffold the library without a browser.

## Predictable structure

Every block follows the same convention: block.json, a template, and optional styles. Learn the pattern once.

## Context, not guesswork

A compact index of the documentation, plus the full text for tools that want all of it.

### An index the agent reads first

`blockstudio-llm.txt` lists every document once, with its route, source file, purpose, and the settings, hooks, PHP functions, and CLI commands it owns. At about 11k tokens an agent reads it whole, then opens only the page it needs.

`blockstudio-llm-full.txt` carries every document and JSON schema in one file, about 169k tokens, for tools that want the whole corpus. Turn on `ai.enableContextGeneration` and your site serves both.

[AI integration docs](https://blockstudio.dev/docs/dev/ai/)

blockstudio-llm.txt

```
# Blockstudio documentation index

This is the primary context file for coding assistants. It is an index, not
the documentation itself. Each entry names one document, what it is for, and
the identifiers that document owns. Read this index, then open only the
document you need.

Every document is addressable two ways: as a URL on https://blockstudio.dev,
and as a Markdown file in the Blockstudio repository. The full text of every
document and schema is also available in one file at /blockstudio-llm-full.txt
for tools that want everything at once.
```

## A contract for your project

The documentation describes Blockstudio. AGENTS.md describes the project the agent is about to change.

### One command writes AGENTS.md

`vendor/bin/blockstudio-agents` describes the project it runs in: what it contains, which features `blockstudio.json` enables, what analysis will reject, and the commands that apply.

Every line comes from your files, your settings, or the selected analysis preset. Regenerating keeps the notes you wrote by hand, and `--check` fails when the contract is stale.

[Project contract](https://blockstudio.dev/docs/dev/phpstan/#project-contract-for-coding-agents)

AGENTS.md

```
# Blockstudio contract for Acme

## Project

- Kind: WordPress theme `Acme`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.

## What this project contains

- Blocks: 1 in `blockstudio`.
- Pages: 1 in `pages`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
```

## Mistakes caught before commit

Four analysis presets, each a superset of the last, and a hook that runs them on every commit.

### Analysis that knows block.json

The `blockstudio/phpstan` presets read your blocks, pages, and settings. A template that reads a field its `block.json` never declared, or echoes it unescaped, fails analysis.

Templates read a `$a` typed from the `block.json` beside them, with a concrete PHP type for every field type, and `Db::get()` returns records shaped by `db.php`. A misspelled settings path or hook name fails with the closest real name suggested.

Set `githooks.commit` and run `vendor/bin/blockstudio-githooks sync`: the managed pre-commit hook runs the same analysis, so a broken block never reaches a commit.

[Analysis presets](https://blockstudio.dev/docs/dev/phpstan/#analysis-presets)

blockstudio.json

```
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": { "preset": "extreme-theme" },
  "githooks": { "commit": true }
}
```

## [base](https://blockstudio.dev/docs/dev/phpstan/#analysis-presets)

Every $a key a template reads exists in block.json; hooks, settings paths, and block tags are real.

## [theme](https://blockstudio.dev/docs/dev/phpstan/#analysis-presets)

Theme headers, declared assets, %selector% scoping, field defaults, and repeater bounds.

## [extreme-theme](https://blockstudio.dev/docs/dev/phpstan/#analysis-presets)

PHPStan max, escaped output, no shelling out, valid Tailwind classes, and clean JavaScript.

## [wordpress-render](https://blockstudio.dev/docs/dev/phpstan/#live-wordpress-rendering)

Extreme theme plus a live WordPress render probe you supply. It runs without a shell, and a failed render becomes a finding.

## [Twig, Blade, and scripts](https://blockstudio.dev/docs/dev/phpstan/#what-it-checks)

Twig, Blade, and block tags are checked against the same fields. The extreme layer also reads JavaScript and Interactivity directives against your markup and stores.

## [Existing projects](https://blockstudio.dev/docs/dev/phpstan/#adopting-analysis-on-an-existing-project)

A PHPStan baseline holds back recorded findings while new code meets the full preset. blockstudioScanRoots reads block libraries outside the root, and shipped stubs type the public API.

## Inventory and rendering from PHP

A few calls let an agent see what a project registers, render any part of it and check what it stored.

### Ask the project, render the answer

`Canvas::inventory()` returns every page, block, pattern, Site Editor template, template part, and UI example a project registers, without rendering anything.

`Render::document()` renders any of them as a complete HTML document with exactly the assets it used, so an agent can check its work outside the editor.

`Canvas::documents()` renders exactly the records you select. `Render::composition()` and `Render::content()` return nested declarations or serialized block content as HTML, and `Ui::inventory()` and `Ui::examples()` list the bundled component families with one renderable declaration each.

For one block, `bs_block_fields()`, `bs_block_extension_fields()`, `bs_block_values()`, and `bs_block_assets()` return its fields, values, and assets without rendering it, and `bs_validate_block()` checks stored attributes before you save them.

[Programmatic rendering](https://blockstudio.dev/docs/blocks/rendering/#structured-compositions-and-complete-documents)

inspect.php

```
use Blockstudio\Canvas;
use Blockstudio\Render;

$project = Canvas::inventory(['blocks' => true]);

foreach ($project['inventory']['blocks'] as $block) {
  echo $block['name'] . "\n";
}

$doc = Render::document(
  ['name' => 'acme/hero', 'data' => ['heading' => 'Hello']],
  ['title' => 'Hero preview']
);

file_put_contents('hero.html', $doc['html']);
```

## Less than half the tokens per page

Agents write plain HTML. Blockstudio turns it into serialized WordPress block markup on sync: less to generate and less to get wrong.

### Blockstudio

What agents write

About 135 tokens

index.php

```
<h1>Build Websites That Convert</h1>
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>

<block name="core/columns">
  <block name="core/column">
    <h3>Lightning Fast</h3>
    <p>Pages load in under one second.</p>
  </block>
  <block name="core/column">
    <h3>Easy to Use</h3>
    <p>No technical skills required.</p>
  </block>
  <block name="core/column">
    <h3>SEO Optimized</h3>
    <p>Built-in best practices from day one.</p>
  </block>
</block>

<img src="/dashboard.jpg" alt="Dashboard" />
```

### WordPress

What the parser writes for it

About 310 tokens

post_content

```
<!-- wp:heading {"level":1} -->
<h1 class="wp-block-heading">Build Websites That Convert</h1>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>
<!-- /wp:paragraph -->
<!-- wp:columns -->
<div class="wp-block-columns">
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Lightning Fast</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Pages load in under one second.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Easy to Use</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>No technical skills required.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">SEO Optimized</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Built-in best practices from day one.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->
<!-- wp:image {"alt":"Dashboard","url":"/dashboard.jpg"} -->
<figure class="wp-block-image"><img src="/dashboard.jpg" alt="Dashboard"/></figure>
<!-- /wp:image -->
```

Measured on the two panels above: 540 characters of HTML against the 1,233 characters of block markup the stock parser writes for it, divided by four, the usual estimate of characters per token. The markup is shown with line breaks added for reading.

## Less output to generate

Agents write HTML without block delimiters, generated classes, or wrapper markup.

## Less to get wrong

The parser guarantees valid block output from the simpler input.

## Faster and cheaper

Fewer output tokens mean faster responses and lower model costs.

## Works with every AI coding tool

Any agent that can read and write files works with Blockstudio out of the box.

Claude Code

Codex CLI

Gemini CLI

Cursor

Windsurf

Amp

## Built for the AI workflow

Blocks, pages, patterns, settings. Everything is a file an agent can read, write, and modify.

## Two files per block

A JSON config and a template are the entire block. The small surface makes first-pass generation reliable.

## 27 field types

Text, files, repeaters, colors, dates, and more, defined in JSON. Selects populate from posts, terms, and users.

## JSON Schema validation

Every config has a schema, which gives agents exact rules and catches mistakes immediately.

## Auto-registration

Drop files into a directory and blocks register automatically, without another config list.

## Canvas overview

Every managed page, or every block with its default values, in one zoomable view.

## Live canvas

Live mode refreshes the affected artboards over Server-Sent Events about a second after a save. Click a label to focus one artboard.

## Tailwind built-in

TailwindPHP compiles the classes each page uses, with no Node configuration.

## Element Grabber

Copy an element’s template path and markup as instant context for an agent.

## HTML to blocks

Pages and patterns are plain files that become native WordPress blocks.

## Render smoke test

wp bs blocks render renders every block the way a page does and exits with 1 when a template raises a notice, warning, or error.

## Stored content checks

wp bs blocks validate checks the saved fields of posts, and pages sync warns about attributes a block stores but never renders.

## Inspect from the terminal

List settings, custom fields, and assets with wp bs, and compile a snippet or file with wp bs tailwind compile or wp bs scss compile.

Plus

## The official extension kit

Premium site templates, AI system instructions, and a private Discord community. One-time purchase, lifetime updates.

- 500+ site templates
- AI system instructions
- Lifetime updates
- Private Discord community

[Get Plus](https://blockstudio.dev/plus/)
