KBeezie

The Bludit documentation didn't always line up with what the code actually did, especially with newer versions, so I built my own. Every hook, constant, helper method, and boot rule in this reference was verified against the BrownBear source — not scraped from a wiki, not inferred from old examples. If it's here, it exists in the code.

This reference covers the patched 3.22.0 source — the same build documented in the production stability audit. If you're building themes or plugins against 3.22.0, this is the map.

What's in the Reference

• Constants and version identification — BLUDIT_VERSION, BLUDIT_PRO, BLUDIT_BUILD, and how the pro file is loaded
• Complete boot sequence — every file loaded from index.php through theme render, for both the site side and the admin panel. Rule files, hook points, and the order they execute
• Core objects — $pages, $users, $tags, $categories, $site, $url, $security, $syslog — what they are, where they're created, and what methods are available
• URL routing and $WHERE_AM_I — every possible value, how it's set, what it controls, and the URI filter constants that affect it
• Hooks reference — every Theme::plugins() call in the kernel, with its location in the boot sequence, arguments passed, and which side it fires on (site, admin, or both)
• Page object reference — the Pagex class: fields, accessors, methods like readingTime(), permalink(), coverImage(), and how content is stored and retrieved
• Helper classes — Sanitize, Valid, Text, Filesystem, Date, Image, Paginator, and the rest — every public method with parameter types and return values
• Plugin architecture — the Plugin abstract class, dbFields declaration, hook registration, form helpers, and the admin controller lifecycle
• Theme architecture — the Theme helper, template variables available in scope, theme language files, and the init.php → index.php render flow
• Patch notes — a summary of every modification applied to the BrownBear build, so you know what differs from the stock 3.22.0 release

Download Options

The reference is split into modular files — pick what you need rather than loading everything at once. Each file is available in two model-specific tiers, token-optimized for reasoning and fast models, plus a human-readable format for the core reference.

Why token-optimized: Raw documentation often creates context noise that leads to hallucinated functions — the model guesses because it's parsing filler rather than facts. The AI-ready files strip narrative fluff and prioritize schema, parameter types, and hook signatures. Less to parse means the model spends its attention budget on your requirements instead of irrelevant text.

How they fit together: The dev reference provides all the facts — what exists, what it's called, where it lives. The theme and plugin guides provide the patterns — how to wire things together without fighting the kernel. Pick your model tier (Pro for reasoning models, Flash for faster models), load the dev reference, then add the rulebook that matches what you're building.

A typical AI prompt session:

1. Upload dev-ref-pro.md — "Here is the Bludit 3.22.0 kernel."
2. Upload theme-pro.md — "Here are the theme architecture patterns for this version."
3. Ask: "Build a Bootstrap-compatible theme with a sidebar layout, sticky navigation, and a dark mode toggle."

The model now knows what exists (the reference) and how to use it (the rulebook). You're not wasting tokens on plugin architecture when you're building a theme, and vice versa.

Using the Reference with an AI Assistant

The reference files provide the facts, but the AI needs to be told how to use them. To ensure the model doesn't drift into generic CMS patterns, use the following workflow to "Lock" the environment:

1. Start a new conversation with your AI assistant.
2. Upload the dev-ref-pro.md (or Flash) file along with the specific rulebook (Theme or Plugin) you are working with.
3. Copy and paste the following "Kernel-Lock" prompt as your first message:

Load the attached Bludit Pro reference and architecture guide into working memory.

Rules:
1. Treat these documents as the EXCLUSIVE authority for all Bludit behavior.
2. Use ONLY the globals, helpers, and patterns defined in these files.
3. Do NOT infer undocumented behavior or use patterns from other CMS versions.
4. If a requested feature is not supported by these documents, inform me BEFORE writing any code.

Await my second prompt before proceeding. Tell me when the files are fully loaded and the environment is locked.

Verify the lock: Once the AI confirms the environment is locked, perform a quick "canary test" to ensure it’s actually referencing your files:

"Based on the reference, what is the correct hook to register a custom admin dashboard widget?"

Troubleshooting: If you see "Error invoking remote method" or network errors when running the canary test (more common with faster, tool-enabled models like Flash), disable your AI's "Web Search" or "External Tool" permissions. Your reference guide is self-contained; disabling external tools forces the model to rely solely on your verified code, which is exactly what you want.

If the AI cites your specific hooks (like adminSidebar or dashboard), the context is solid and you are ready for production-grade coding. If it gives a generic answer, tell it to re-read the files. This workflow is the difference between code that runs on the first try and code you'll spend an afternoon debugging.

A Note of Caution — Human in the Loop

An AI assistant with the right reference files can produce code that looks correct — correct function names, correct hook signatures, correct file paths. It can also produce code that quietly does something you didn't ask for, skips an edge case you didn't think to mention, or wires two hooks together in a way that works once and breaks under real traffic.

Google calls the approach Human-in-the-Loop — HITL. The idea is simple: the model does the heavy lifting, but a human evaluates the output before it goes anywhere that matters. The AI suggests. You decide. When the output is wrong, the correction becomes part of the feedback loop — the next prompt is sharper because you know what to ask for.

If you don't understand the basics of the code yourself — what a hook does, why the boot sequence loads files in a particular order, what variables are in scope at render time — the AI's output will be hard to verify and harder to debug. You don't need to be an expert. You do need to be able to read the code and ask "why does this work?" with enough context to recognize when the answer doesn't add up.

Treat the assistant like a fast collaborator, not an authority. Ask it to explain its choices. Test the output in a staging environment before it touches a live site. If something looks off, push back — the assistant doesn't get defensive, and a second pass with clearer instructions often catches what the first pass missed. The reference files give the model facts. Your judgment decides whether the code belongs on your server.