diff --git a/README.md b/README.md
index 2f5de4e..4e3b179 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,13 @@
-# Observata Theme
-
-Custom WordPress theme using Gutenberg blocks with Timber/Twig server-side rendering.
-
-
+# Observata
[](https://github.com/gotpop/observata/actions/workflows/lint.yml)
[](https://github.com/gotpop/observata/actions/workflows/test.yml)
[](https://github.com/gotpop/observata/actions/workflows/phpstan.yml)
+Custom WordPress theme using Gutenberg blocks with Timber/Twig server-side rendering.
+
+
+
## Stack
- **Timber 2.x** — Twig templating for PHP
@@ -16,7 +16,7 @@ Custom WordPress theme using Gutenberg blocks with Timber/Twig server-side rende
- **Three.js + Shaders** — WebGPU/WebGL hero shader effects
- No `theme.json` — all styling is hand-written CSS with custom properties
-## Architecture
+Architecture
All blocks are **server-rendered via Twig** (not PHP `render.php`). The render pipeline:
@@ -57,24 +57,39 @@ Timber is configured with three loader paths (`inc/theme-setup.php`):
Page-level templates live in `views/templates/`, extending `views/base.twig`.
-### PHP Modules (`inc/`)
-
-| File | Responsibility |
-| ------------------------ | ----------------------------------------------------------------- |
-| `theme-setup.php` | Timber init, menus, theme supports |
-| `enqueue-assets.php` | CSS inlining (SCRIPT_DEBUG gated), script deferral, font preloads |
-| `block-renderer.php` | Twig render callback, inner block serialization, context builders |
-| `blocks.php` | Block auto-discovery + registration, webpack runtime enqueue |
-| `twig-filters.php` | Custom Twig filters (`strip_html`) |
-| `seo.php` | Sitemap, robots.txt, canonical URLs |
-| `analytics.php` | GA4, Leadfeeder, Cookiebot settings |
-| `schema-markup.php` | Schema.org itemscope/itemprop |
-| `speculation-rules.php` | Chrome navigation prefetch |
-| `content-filters.php` | Title filters, read-more links |
-| `device-detection.php` | UA-based HTML classes |
-| `image-optimization.php` | WebP MIME, disables intermediate sizes |
-
-### Design Token System (3-Tier)
+PHP Modules (`inc/`)
+
+Each file handles **one concern**:
+
+| File | Responsibility |
+| --------------------------- | -------------------------------------------------- |
+| `theme-setup.php` | Timber init, menus, theme supports, env helpers |
+| `enqueue-assets.php` | CSS inlining (SCRIPT_DEBUG gated), script deferral |
+| `block-renderer.php` | Twig render callback + context injection helpers |
+| `block-helpers.php` | Hero split, block serialization, template map |
+| `blocks.php` | Block registration, editor runtime, allowed blocks |
+| `breadcrumbs.php` | Breadcrumb trail builder |
+| `twig-filters.php` | Custom Twig filters (`strip_html`) |
+| `seo.php` | Sitemap, robots.txt, canonical URLs |
+| `content-filters.php` | Title filters, read-more links |
+| `device-detection.php` | UA-based HTML classes |
+| `image-optimization.php` | WebP MIME, disables intermediate sizes |
+| `schema-markup.php` | Schema.org itemscope/itemprop |
+| `speculation-rules.php` | Chrome navigation prefetch |
+| `theme-settings.php` | Theme Settings admin page + sections |
+| `theme-settings-footer.php` | Footer content fields |
+| `analytics-ga4.php` | GA4 registration + output |
+| `analytics-leadfeeder.php` | Leadfeeder registration + output |
+| `analytics-cookiebot.php` | CookieBot registration + output |
+
+All functions are **fully typed** (parameter + return types). PHPStan runs at
+level 5 in CI to prevent type regressions.
+
+Design Token System
No `theme.json` — all styling uses hand-written CSS with a 3-tier custom property system:
@@ -86,7 +101,9 @@ No `theme.json` — all styling uses hand-written CSS with a 3-tier custom prope
Prefer utility classes in Twig templates, theme tokens in block CSS, and avoid base tokens directly.
-## Development
+Development
```bash
npm run start # webpack watch mode (blocks + client JS + global CSS)
@@ -113,20 +130,15 @@ define( 'SCRIPT_DEBUG', true );
This switches CSS from inlined `