Introduction

Divine is a local-first framework for building WordPress themes fast with agents. It is theme-only: all work happens in real theme files, inside git-backed worktrees, and then gets checked, previewed, reviewed, and deployed as files. Nothing about Divine asks you to learn a parallel content model or a hosted build service. You edit a theme, you look at it, you ship it.

These docs explain how that workflow fits together: how a worktree isolates a change, how the canvas and signed browser preview show you the result, how the dv CLI validates a theme without booting WordPress, and how a finished theme is exported to run on a client site with no Divine plugin installed.

What Divine Does

Agents are good at writing theme code and bad at knowing whether it is safe to ship. A single half-finished edit to the active theme reaches live visitors immediately, and a malformed template or an unescaped value is hard to catch by reading a diff. Divine exists to make theme work inspectable before it reaches the site’s active theme.

Divine turns an installed WordPress theme into an app: a workspace you build inside. Each task gets its own worktree, a git-backed copy of that theme under wp-content/themes. An agent or a person edits normal files in the worktree, runs dv check to validate them in PHP, and previews the result in a canvas of rendered pages and blocks or in a signed in-app browser session. When the change looks right, you review the diff and deploy the accepted files back into the app theme. When the theme is ready for a client, you export it as a self-contained zip.

The result is a tight loop where the live theme keeps serving visitors the approved version while many worktrees can be built, checked, and reviewed in parallel. The active theme only changes when you deliberately deploy into it.

The Build Loop

Every Divine task has the same shape. You work in a worktree, prove the change locally, look at it, review the diff, and only then promote files into the app theme.

1. Create or select a worktree for one task.
2. Edit normal theme files in that worktree.
3. Run dv check . from the theme to validate the change.
4. View the result in the canvas, or open a signed browser preview.
5. Review the diff and resolve any conflicts.
6. Deploy the accepted files back into the app theme.
7. Run dv export . to ship the finished theme to a client site.

Because the change lives in the worktree until you deploy, a worktree preview can look and behave completely differently from the live site while the public site stays untouched. Deploy mirrors files only; it never copies WordPress posts, options, uploads, or plugin state.

Concepts To Know

A handful of terms recur throughout these docs. Understanding them first makes everything else easier to follow.

Concept	What it means
App	An installed WordPress theme registered with Divine as a workspace. On single-site this is the active theme; on multisite it is one network site and its active theme.
Worktree	A git-backed copy of an app theme under wp-content/themes, scoped to one task. The app theme keeps serving visitors until a worktree is deployed.
Preview	A private, signed view of a theme: the canvas renders pages and blocks from files, and the browser opens the theme on the real clean site URL for one request.
Deploy	The explicit step that mirrors accepted worktree files back into the app theme. It moves files only, never database state.
Export	Packaging an app or worktree as a standalone theme zip that runs on a client site with no Divine plugin.
dv check	The native PHP validator. Fast mode runs without WordPress, network access, or shelling out; --full adds a WordPress render dry-run in CI or wp-env.
dv show	A URL builder that prints a capturable page, block, or compare URL. It constructs URLs only; the agent or browser tool captures the screenshot.
dv export	The CLI form of export. A plain path export does not require a running WordPress site or app registration.
Harness / AGENTS.md	The Divine-owned guide and tooling files Divine generates into every theme, including AGENTS.md, CLAUDE.md, dv, .githooks/pre-commit, and .divine/manifest.json.
divine.json	The theme-level source of truth for runtime performance intent. Authors own its contents; Divine may scaffold it but does not overwrite it.
Standalone runtime	The divine-runtime/ copy bundled into exported themes so the theme runs without the Divine plugin.

How These Docs Are Organized

These docs follow the order of the build loop, grouped into five sections.

Getting Started sets Divine up and walks one full loop. Getting Started installs the plugin and takes you through a worktree, check, preview, review, and deploy. Admin Workspace describes the fullscreen admin app and its canvas, browser, code, review, history, and export surfaces. Access and Capabilities covers who can use Divine and what a preview token grants.

Apps and Worktrees is the unit of work. Apps and Worktrees explains how apps and worktrees are created, cloned, deployed, and destroyed. Previews covers the canvas and the signed browser preview. Security Model lays out the structural guarantees: what stays on the live site, how preview tokens are scoped, and why dv check is safe to run anywhere.

Building is the dv CLI and the authoring contract. The Theme Harness documents the generated AGENTS.md, dv shim, pre-commit hook, and manifest. dv check validates a theme, dv show builds capturable render URLs, and Theme Authoring covers where theme code belongs and the dv_tw_* helpers.

Shipping is how a finished theme leaves Divine. Deploy promotes worktree files into the app theme, Theme Export packages the standalone client zip, and The Standalone Runtime explains the bundled runtime that lets the theme run with no Divine plugin.

Reference documents the rest: Performance and divine.json, the Configuration Reference of constants and filters, the REST API, Multisite, the generated Hooks reference, and Operations and Troubleshooting.

The sidebar links every page in this order, so you do not need to navigate by hand from here.

The Safety Contract

Divine’s guarantees are structural, not advisory. Outside a Divine preview session, WordPress behaves normally: the active theme, normal admin, REST, cron, feeds, search, sitemaps, login, and WP_Query all keep using the live site state. Divine only swaps the theme inside a valid, signed preview, and only for that request. The preview uses the selected app or worktree files while WordPress posts, options, users, plugins, sessions, and uploads remain the same site data.

Deploy is files-only and one-directional. Promoting a worktree mirrors its theme files into the app theme and never copies posts, options, uploads, or any database sandbox. On multisite, deploy targets the selected site’s active theme only. Worktree pages are files: a worktree-only page is visible in the canvas because it is a theme file, but it is never added to the WordPress pages list until its files are deployed.

The check surface is deliberately cheap. dv check runs in PHP without booting WordPress, opening network connections, or shelling out, so an agent can validate a change in the loop without any running site. The generated pre-commit hook runs that fast check automatically, and --full is the opt-in lane that adds a WordPress render dry-run in CI or wp-env.

This structure does not replace good judgment. You should still review agent work, keep the source theme committed, and look at a preview before you deploy.

Current Surfaces And Limits

Divine exposes one fullscreen admin app under the Divine menu and workspace REST routes under /wp-json/divine/v1/ for apps, worktrees, canvas snapshots, code, git history, export, browser state, and UI state. The admin page and every workspace route require the Divine management capability, which defaults to manage_options on single-site and manage_network on multisite.

Divine deliberately ships no shell, MCP server, WP-CLI command runtime, hosted execution surface, or multisite workspace backend. There is no Pro, managed, hosted-lockdown, or Docker-hosted runtime. Agents work through real worktree files, the dv CLI, and the same administrator-gated REST services the workspace uses. The deployment model is also deliberate: the Divine plugin is the build and authoring environment, and a finished theme is exported self-contained so it runs on a client site with no Divine plugin present.