Byrde — BlueCrocus site builder

WordPress plugin for full-site pages and posts. Standalone templates; the active theme does not render Byrde documents. Visual work: (1) tokens + library definitions, (2) studio canvas with Blocks and Pages libraries.

Features

• Byrde Pages — CPT byrde_landing internally; kinds page | post | legal. URLs at /, /{slug}, /blog/{slug}
• Studio — Library (Blocks | Pages), canvas, stack reorder/shuffle, token toolbar
• PageTemplates — Landing, Contact, About, Pricing, Blog index/post, Legal
• SiteDesign — Light/dark tokens, font pairings, radius. CSS variables only
• Contact Form — Validation, honeypot, attribution, Postmark / wp_mail(), byrde_lead CPT
• SEO — Indexable by default; JSON-LD from published PageDocument
• Auto-Updates — Self-hosted JSON (updates.bluecrocus.ca), not GitHub as live channel

Requirements

• WordPress 6.0+ (tested up to 6.7)
• PHP 8.0+
• Node.js 20+

Installation

From GitHub Release (Recommended)

1. Download byrde.zip from the latest release
2. In WordPress, go to Plugins → Add New → Upload Plugin
3. Upload the ZIP and activate

From Source

git clone git@github.com:tales-bluecrocus/byrde.git
cd byrde
composer install --no-dev
cd front-end
npm install
npm run build

Then symlink or copy the byrde/ folder into wp-content/plugins/.

Configuration

Plugin Settings

Go to Settings → Theme Settings in the WordPress admin. Configure:

• Brand — Logo, phone number, email
• Brand Colors — Dark/light mode primary, accent, and text colors
• Button Style — Border width, radius, shadow, text colors per mode
• Google Reviews — Rating, review count, reviews URL
• Footer — Tagline, description, address, business hours, copyright
• Social Links — Facebook, Instagram, YouTube, Yelp, Google
• SEO — Site name, tagline, description, keywords, OG image
• Schema — LocalBusiness type, address, geo coordinates, opening hours, service radius
• Analytics — GA4 Measurement ID, GTM Container ID, Meta Pixel ID, Google Ads conversion labels
• Legal — Privacy policy, terms, cookie settings URLs
• Contact Form — Postmark API token, to/from/CC/BCC emails, subject line

Visual Editor

Go to Byrde Pages → New from template, then Edit with Byrde.

The studio lets you:

• Insert sections from the Blocks library and instantiate Pages from templates
• Shuffle a section for another definition in the same category
• Reorder / delete / clear the stack
• Edit block slots (no free CSS)
• Change SiteDesign tokens (primary, radius, fonts, light/dark)
• Save draft (PageDocument) and Publish

Tech Stack

Project Structure

byrde/
├── byrde.php                     # Plugin entry point (constants, autoload, boot)
├── src/                          # PHP classes (PSR-4, namespace Byrde\)
│   ├── Plugin.php                # Bootstrap: instantiates all modules
│   ├── Core/                     # Constants, Helpers, Logo
│   ├── Assets/                   # AssetManager (enqueue, preload, critical CSS)
│   ├── Settings/                 # Theme settings CRUD + Cache (12 hosting/CDN purge layers)
│   ├── Security/                 # Cleanup (XML-RPC), Validators, RateLimiter, CookieConsent
│   ├── Content/                  # CPT, TemplateLoader, SEO, Shortcodes, LegalPages
│   ├── API/                      # REST endpoints, ContactForm, Abilities (MCP)
│   ├── Admin/                    # SettingsPage, PageEditor, Onboarding
│   └── Migration/                # Theme→Plugin migration, color schema migrations (v2→v4)
├── front-end/                    # React application
│   ├── index.html                # Production entry (lightweight, no editor)
│   ├── editor.html               # Editor entry (includes ThemeEditor)
│   ├── vite.config.ts            # Production build config
│   ├── vite.config.editor.ts     # Editor build config (separate output)
│   ├── src/
│   │   ├── main.tsx              # Production bootstrap (+ onboarding lazy load)
│   │   ├── editor-main.tsx       # Editor bootstrap (imports ThemeEditor)
│   │   ├── App.tsx               # Shared app (7 nested context providers)
│   │   ├── components/           # React components (one per section)
│   │   │   ├── ThemeEditor/      # Visual editor sidebar + panels
│   │   │   ├── Onboarding/       # Setup wizard
│   │   │   └── ui/               # shadcn/ui primitives
│   │   ├── context/              # React Contexts (Settings, GlobalConfig, SectionTheme, HeaderConfig, Content, Sidebar)
│   │   ├── hooks/                # Custom hooks (useSettings, useSectionPalette, useAnalytics)
│   │   ├── lib/                  # Utilities (analytics, phone formatting)
│   │   └── utils/                # Color utilities, headline rendering
│   └── dist/                     # Production build (generated, hashed filenames)
│       └── .vite/manifest.json   # Asset manifest for PHP resolution
├── templates/
│   ├── template-landing.php      # Standalone HTML for landing pages (React mount)
│   └── template-legal.php        # Server-rendered legal pages (no React)
├── docs/                         # Additional documentation
├── .claude/agents/               # Claude Code specialized agents
│   ├── backend.md                # @backend — PHP, REST API, WordPress
│   ├── frontend.md               # @frontend — React, TypeScript, Vite, shadcn
│   ├── devops.md                 # @devops — Build, release, CI/CD
│   ├── reviewer.md               # @reviewer — Code review, security, a11y
│   ├── marketing.md              # @marketing — SEO, analytics, PPC tracking
│   └── design.md                 # @design — UI/UX, design system, WCAG
├── .config/                      # Release & build scripts
│   ├── bump-version.sh           # Auto-increment version (patch/minor/major)
│   ├── create-release.sh         # Create a tagged release
│   └── build-zip.sh              # Build local ZIP for manual upload
└── .github/workflows/
    └── release.yml               # GitHub Actions: build + release on tag push

Sections

REST API

Base URL: /wp-json/byrde/v1

All authenticated endpoints require the X-WP-Nonce header.

Development

Prerequisites

node -v  # v20+
php -v   # 8.0+
composer -V

Frontend Development

cd front-end
npm install
npm run dev    # Vite dev server with HMR (open /editor.html for editor)

Production Build

cd front-end
npm run build  # Outputs to front-end/dist/ (two entries: production + editor)

PHP Autoload

composer dump-autoload  # Regenerate PSR-4 autoload after adding classes

Tests

cd front-end
npm test             # Run all tests
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

Releasing

Automated Release (via GitHub Actions)

# Bump patch version (1.1.0 → 1.1.1)
.config/bump-version.sh patch

# Bump minor version (1.1.0 → 1.2.0)
.config/bump-version.sh minor

# Bump major version (1.1.0 → 2.0.0)
.config/bump-version.sh major

# Or specify an exact version
.config/create-release.sh 2.0.0

This will:

1. Update the version in byrde.php (header + constant)
2. Commit and create an annotated git tag
3. Push to GitHub
4. GitHub Actions builds the frontend and packages the release ZIP

GitHub Releases are used for source-of-truth packaging only — they are not the update channel. To ship the update to live sites, upload the built ZIP and a matching metadata.json to updates.bluecrocus.ca (see below).

Manual ZIP + Metadata (for upload to the update server)

.config/build-zip.sh
# Output: ../byrde.zip + ../byrde-metadata.json

Then upload:

1. byrde.zip → https://updates.bluecrocus.ca/byrde/byrde-{VERSION}.zip
2. byrde-metadata.json → overwrite https://updates.bluecrocus.ca/byrde/metadata.json

Once metadata.json is live, sites running Byrde pick up the update on their next poll (or immediately via Check for updates).

How Auto-Updates Work

The plugin uses the Plugin Update Checker library (via Composer) against a self-hosted JSON metadata endpoint — not GitHub Releases/VCS. Byrde\Update\Checker registers the checker in Plugin::setup_update_checker().

1. WordPress polls https://updates.bluecrocus.ca/byrde/metadata.json every ~12h (WP core's built-in update schedule), or immediately when the admin clicks Check for updates on the Plugins screen
2. If metadata.json reports a newer version, WordPress shows the same native update notice as wordpress.org-hosted plugins
3. The admin clicks Update now and WordPress downloads the ZIP from download_url and installs it — one click, no manual upload

Metadata format

See docs/update-metadata.example.json. Fields: name, slug, version, download_url, homepage, requires, tested, requires_php, last_updated, sections.description, sections.changelog.

Overriding the metadata URL

By default the checker uses Constants::UPDATE_METADATA_URL. Override per-environment via, in order of precedence:

1. wp-config.php constant: define( 'BYRDE_UPDATE_METADATA_URL', 'https://example.com/byrde/metadata.json' );
2. Filter: add_filter( 'byrde_update_metadata_url', fn () => 'https://example.com/byrde/metadata.json' );

If the resolved URL is empty, the checker is a no-op (no updates checked).

Security

• Input validation and sanitization on all REST endpoints
• Rate limiting per user (saves, uploads) and per IP (contact form)
• Content size limits (512KB theme config, 1MB content, 5MB images)
• Item count limits (50 services, 100 testimonials, 50 FAQs, 100 service areas)
• MIME type verification and dimension checks on file uploads (max 3840x2160)
• Nonce-based authentication for all admin endpoints
• Permission checks per page (edit_post capability)
• Honeypot field on contact form
• XML-RPC disabled by default (byrde_disable_xmlrpc filter to override)
• Asset isolation on landing pages (two-layer: dequeue + tag filter)

Claude Code Agents

The project includes 6 specialized Claude Code agents in .claude/agents/:

18 agent skills are also installed (.agents/skills/) covering WordPress, React, shadcn/ui, analytics, PPC, debugging, design review, and MCP.

AI Agent Integration (MCP)

Byrde registers abilities via the WordPress Abilities API (WP 6.9+), which the official WordPress MCP Adapter plugin exposes as MCP tools for AI agents like Claude Desktop, Cursor, and others.

Setup

1. Install and activate the WordPress MCP Adapter plugin
2. Byrde abilities are registered automatically — no extra configuration needed

Available Abilities

Content updates support partial merges — you can update a single section without overwriting others.

Requirements

• WordPress 6.9+ (native Abilities API) or the developer-jeremylopez/wordpress-abilities-api Composer package
• WordPress MCP Adapter plugin for exposing abilities as MCP tools
• Both are optional — Byrde works normally without them

Cache Compatibility

The plugin automatically purges caches when settings or page content changes. Supported layers:

WordPress Core, LiteSpeed Cache, WP Super Cache, W3 Total Cache, WP Rocket, WP Fastest Cache, SG Optimizer, WP Engine, Kinsta, Cloudflare, Autoptimize, Breeze (Cloudways)

License

GPL v2 or later.