Pollora · ogorzalka · Sep 29, 2026 · Sep 29, 2026
diff --git a/README.md b/README.md
@@ -27,24 +27,35 @@ buzz/
 │   ├── page.html
 │   └── 404.html
 ├── parts/                # header.html / footer.html, each delegating to a pattern too
+├── patterns/              # Static patterns, registered by WordPress itself
+│   ├── masthead.php       # The actual header markup
+│   ├── index-list.php     # The journal index: a post loop, large titles, hairline rules
+│   ├── article.php        # A single post's body, plus comments
+│   ├── page-body.php      # A plain page's body
+│   ├── not-found.php      # The 404 message
+│   └── design-system.php  # Every native block, styled — offered in the inserter
 ├── resources/views/patterns/
-│   ├── masthead.html      # The actual header markup — no PHP needed
-│   ├── colophon.blade.php # The footer — Blade, for the one thing that needs real PHP: the year
-│   ├── index-list.html    # The journal index: a post loop, large titles, hairline rules
-│   ├── article.html       # A single post's body, plus comments
-│   ├── page-body.html     # A plain page's body
-│   └── not-found.html     # The 404 message
+│   └── colophon.blade.php # The footer — Blade, for the one thing that needs real PHP: the year
 ├── theme.json             # The design system: palette, the two-family type scale, spacing, styles
 ├── resources/assets/
 │   ├── css/app.css        # @theme static tokens (colour only — see below) + the few hand-authored rules
 │   └── fonts/              # Self-hosted Playfair Display + Source Serif 4 (OFL, Google Fonts, latin subset)
 └── app/Providers/AssetServiceProvider.php
 ```
 
-A theme's `resources/views/patterns` can hold both `.blade.php` (compiled, for real PHP) and plain
-`.html` files (used verbatim, for a pattern that needs none) — most of Buzz's patterns are plain
-`.html`, since a block theme's patterns are mostly static block markup once the dynamic blocks
-(`post-title`, `post-content`, `post-terms`…) are doing the work themselves.
+One rule decides where a file goes: **the theme root holds what WordPress reads itself**
+(`templates/`, `parts/`, `patterns/`, `theme.json`, `style.css` — the layout the Site Editor exports
+too), and **`resources/views/` holds Blade, compiled by Pollora**.
+
+So a static pattern is a native WordPress one, `patterns/*.php`: block markup under a header
+docblock (`Title`, `Slug`, `Categories`…). Most of Buzz's patterns are, since the dynamic blocks
+(`post-title`, `post-content`, `post-terms`…) do the work themselves. A pattern that needs Laravel
+— the colophon's year, here — is a Blade view in `resources/views/patterns/*.blade.php`, registered
+by Pollora.
+
+WordPress caches the list of a theme's `patterns/` files: a new file shows up once that cache is
+cleared (`wp eval 'wp_get_theme()->delete_pattern_cache();'`), or at once with
+`WP_DEVELOPMENT_MODE=theme`.
 
 ## Design system
 
@@ -82,4 +93,4 @@ mismatch there breaks every asset and font URL silently.
 A first, deliberately simple version: six templates, six patterns, no style variations. See
 [`Pollora/framework`](https://github.com/Pollora/framework) for the FSE support this theme relies
 on, and the framework's changelog for the two fixes this theme's construction found and fixed
-(`.html` block patterns, a block theme's `404.html` answering the right HTTP status).
+(a block theme's `404.html` answering the right HTTP status, its `error404` body class).
diff --git a/resources/views/patterns/article.html → patterns/article.php b/resources/views/patterns/article.html → patterns/article.php
@@ -1,9 +1,11 @@
-<!--
-Title: Article
-Slug: buzz/article
-Categories: buzz/patterns
-Inserter: false
--->
+<?php
+/**
+ * Title: Article
+ * Slug: buzz/article
+ * Categories: buzz/patterns
+ * Inserter: false
+ */
+?>
 <!-- wp:group {"tagName":"main","align":"wide","style":{"spacing":{"margin":{"top":"var:preset|spacing|lg","bottom":"var:preset|spacing|lg"}}},"layout":{"type":"constrained","contentSize":"42rem"}} -->
 <main class="wp-block-group alignwide" style="margin-top:var(--wp--preset--spacing--lg);margin-bottom:var(--wp--preset--spacing--lg)">
     <!-- wp:group {"style":{"spacing":{"margin":{"bottom":"var:preset|spacing|md"}}}} -->

diff --git a/resources/views/patterns/design-system.html → patterns/design-system.php b/resources/views/patterns/design-system.html → patterns/design-system.php
@@ -1,9 +1,11 @@
-<!--
-Title: Design system
-Slug: buzz/design-system
-Categories: buzz/patterns
-Inserter: true
--->
+<?php
+/**
+ * Title: Design system
+ * Slug: buzz/design-system
+ * Categories: buzz/patterns
+ * Inserter: true
+ */
+?>
 <!-- wp:group {"align":"wide","style":{"spacing":{"blockGap":"var:preset|spacing|lg"}},"layout":{"type":"constrained","contentSize":"42rem"}} -->
 <div class="wp-block-group alignwide">
 

diff --git a/resources/views/patterns/index-list.html → patterns/index-list.php b/resources/views/patterns/index-list.html → patterns/index-list.php
@@ -1,9 +1,11 @@
-<!--
-Title: Journal index list
-Slug: buzz/index-list
-Categories: buzz/patterns
-Inserter: false
--->
+<?php
+/**
+ * Title: Journal index list
+ * Slug: buzz/index-list
+ * Categories: buzz/patterns
+ * Inserter: false
+ */
+?>
 <!-- wp:group {"tagName":"main","align":"wide","style":{"spacing":{"margin":{"top":"var:preset|spacing|lg","bottom":"var:preset|spacing|lg"}}},"layout":{"type":"constrained","contentSize":"46rem"}} -->
 <main class="wp-block-group alignwide" style="margin-top:var(--wp--preset--spacing--lg);margin-bottom:var(--wp--preset--spacing--lg)">
     <!-- wp:query-title {"type":"archive"} /-->

diff --git a/resources/views/patterns/masthead.html → patterns/masthead.php b/resources/views/patterns/masthead.html → patterns/masthead.php
@@ -1,10 +1,12 @@
-<!--
-Title: Masthead
-Slug: buzz/masthead
-Categories: buzz/patterns
-Block Types: core/template-part/header
-Inserter: false
--->
+<?php
+/**
+ * Title: Masthead
+ * Slug: buzz/masthead
+ * Categories: buzz/patterns
+ * Block Types: core/template-part/header
+ * Inserter: false
+ */
+?>
 <!-- wp:group {"tagName":"header","align":"full","className":"buzz-masthead","style":{"spacing":{"padding":{"top":"var:preset|spacing|sm","bottom":"var:preset|spacing|sm"}}},"layout":{"type":"constrained"}} -->
 <header class="wp-block-group alignfull buzz-masthead" style="padding-top:var(--wp--preset--spacing--sm);padding-bottom:var(--wp--preset--spacing--sm)">
     <!-- wp:group {"align":"wide","layout":{"type":"flex","flexWrap":"wrap","justifyContent":"space-between","verticalAlignment":"center"}} -->

diff --git a/resources/views/patterns/not-found.html → patterns/not-found.php b/resources/views/patterns/not-found.html → patterns/not-found.php
@@ -1,9 +1,11 @@
-<!--
-Title: Not found
-Slug: buzz/not-found
-Categories: buzz/patterns
-Inserter: false
--->
+<?php
+/**
+ * Title: Not found
+ * Slug: buzz/not-found
+ * Categories: buzz/patterns
+ * Inserter: false
+ */
+?>
 <!-- wp:group {"tagName":"main","align":"wide","style":{"spacing":{"margin":{"top":"var:preset|spacing|xl","bottom":"var:preset|spacing|xl"}}},"layout":{"type":"constrained","contentSize":"36rem"}} -->
 <main class="wp-block-group alignwide" style="margin-top:var(--wp--preset--spacing--xl);margin-bottom:var(--wp--preset--spacing--xl)">
     <!-- wp:heading {"level":1,"fontSize":"article-title"} -->

diff --git a/resources/views/patterns/page-body.html → patterns/page-body.php b/resources/views/patterns/page-body.html → patterns/page-body.php
@@ -1,9 +1,11 @@
-<!--
-Title: Page body
-Slug: buzz/page-body
-Categories: buzz/patterns
-Inserter: false
--->
+<?php
+/**
+ * Title: Page body
+ * Slug: buzz/page-body
+ * Categories: buzz/patterns
+ * Inserter: false
+ */
+?>
 <!-- wp:group {"tagName":"main","align":"wide","style":{"spacing":{"margin":{"top":"var:preset|spacing|lg","bottom":"var:preset|spacing|lg"}}},"layout":{"type":"constrained","contentSize":"42rem"}} -->
 <main class="wp-block-group alignwide" style="margin-top:var(--wp--preset--spacing--lg);margin-bottom:var(--wp--preset--spacing--lg)">
     <!-- wp:post-title {"level":1,"style":{"spacing":{"margin":{"bottom":"var:preset|spacing|md"}}}} /-->