Getting Started

View as Markdown

Divine runs entirely inside WordPress and works with installed themes. It leans on the systems WordPress already provides: the active theme, the admin menu, capabilities, and the REST API. Getting started means installing the plugin, opening the workspace, creating a git-backed worktree, editing a file, validating it with dv check, previewing it, reviewing the diff, and deploying the accepted work back into the app theme. This page walks through that path end to end.

Requirements

Divine is built for local-first theme development where an agent or a person edits real theme files and reviews them before they go live. Before installing, confirm your environment meets the following requirements.

Requirement	Why it matters
WordPress with the REST API available	The admin app and every workspace operation run over REST under `/wp-json/divine/v1/`.
PHP 8.2 or newer	The minimum runtime the plugin and the standalone runtime support.
A WordPress administrator account	The workspace is gated by the Divine management capability: `manage_options` on single-site, `manage_network` on multisite.
A git-initialized theme directory	Worktrees copy the theme’s `.git`, so the source theme must have at least one commit before a worktree can be created.
Writable `wp-content/themes` and uploads	Worktrees live under `wp-content/themes`; exports and cache files live in uploads.
PHP `zip` extension	Required for standalone theme export.

Divine reads git state with bundled PHP code, so the web request does not need a git binary on the host. You still need to initialize and commit the source theme once, because worktree creation fails when the source theme has no .git directory.

Install And Activate

Install and activate Divine like any other WordPress plugin. Activation installs the control-plane table that stores app and worktree records, and on first run it registers the preview runtime, the workspace REST routes, the standalone runtime boot path, and the fullscreen admin app.

Activation does not change your active theme or touch any content. Until you create a worktree and deploy it, Divine reads theme files and renders signed previews; it never writes to the live theme on its own.

Open The Workspace

Where the Divine workspace appears depends on whether the install is single-site or multisite. This is deliberate: Divine treats multisite as a network-admin surface and single-site as a normal-admin surface, and it registers the menu in exactly one of those places so the app never appears twice.

On a single-site install, Divine is a top-level Divine item in the normal wp-admin menu, gated by manage_options. The multi-app sidebar is hidden because there is one app: the active theme.

On a multisite install, Divine runs from network admin only, gated by manage_network. The multi-app sidebar is shown and lists the real network sites from get_sites(), each with its active theme as an app. Opening the regular per-site admin does not show Divine; the menu is registered on network_admin_menu instead of admin_menu.

When you open the page, Divine strips the normal wp-admin asset stack and mounts a fullscreen React app that talks to /wp-json/divine/v1/ with the standard WordPress REST nonce.

Prepare A Theme

Worktrees are git copies, so the theme you want to build must be a git repository with at least one commit. From the theme directory:

git init
git add -A
git commit -m "Initial theme state"

If the source theme has no .git directory, worktree creation fails with a validation error. You only need to do this once per source theme.

Create Your First Worktree

A worktree is a git-backed copy of an app theme, scoped to one task. You create it from the admin workspace by selecting the app and choosing a name and a clone source. The clone source is either main (the app theme as it is now) or another existing worktree.

When Divine creates a worktree it copies the source theme into a new directory under wp-content/themes, refreshes the Divine-managed files in the copy, and records the worktree in the control-plane table. The managed files are the harness Divine owns in every theme: AGENTS.md, CLAUDE.md, the dv shim, .githooks/pre-commit, and .divine/manifest.json. Divine commits that managed-files baseline so the worktree starts from a clean git state and your own edits show up as the only changes.

From this point on, the worktree is just a theme directory. You can edit it in the Code view of the workspace, or directly on disk with your own editor or an agent, and Divine will pick up the changes.

Edit A Theme File

Theme work belongs in normal theme files. Author pages under pages/<slug>/index.php with a matching page.json, blocks under blocks/, patterns under patterns/, and put brand and surface values in @theme in style.css. Use Divine’s runtime helpers dv_tw_merge() and dv_tw_variants() directly in templates rather than adding theme-local class-composition wrappers.

For a first change, edit a file under pages/ so you can watch it appear in the canvas. A worktree-only page that does not exist in the WordPress database is still visible in the canvas, because the canvas renders pages from files, not from wp_posts.

Run dv check

dv check validates a theme directory. It is the fast gate you run before you preview or deploy. Fast mode is the default and runs the native Divine, Blockstudio-derived, and TailwindPHP layers in PHP, without booting WordPress, opening network connections, or shelling out. The generated pre-commit hook runs this automatically on commit.

Run it from inside the theme directory with the generated dv shim:

./dv check .
./dv check --json .
./dv check --full .

--full is the opt-in lane for CI or wp-env. It may bootstrap WordPress in-process to add the render dry-run, so it is not part of the fast loop.

The exit code tells you the result, which is what lets the pre-commit hook and CI gate on it.

Code	Meaning
`0`	No findings.
`1`	Findings were reported.
`2`	Usage or internal error.

When you are working from the plugin source rather than a generated theme, the equivalent entrypoints are bin/divine-check <theme-path> and composer check -- <theme-path>.

View A Preview

Divine gives you two ways to look at a worktree, and they answer different questions. The canvas answers “does this page or block render correctly from files,” and the browser answers “does this theme behave correctly on the real site.”

The canvas shows pages and blocks rendered from the selected target’s theme files. It switches between pages and blocks, desktop, tablet, and mobile viewports, and a changed-block marker, and it picks up on-disk edits through a lightweight file manifest without reloading the whole workspace. Use the canvas for fast visual iteration on file-backed pages and blocks.

The browser opens the selected app or worktree in an embedded frame with a short-lived, signed preview session. The visible URL is the real clean site URL while Divine applies the selected theme copy in the background, so theme PHP and frontend assets run exactly as they would after deploy. Use the browser when you need to exercise real WordPress routing, real WP_Query, or admin-side behavior.

When you need a capturable URL instead of an interactive view, the dv show command prints one without taking the screenshot itself:

./dv show page home --worktree my-worktree --width 1440
./dv show block hero --worktree my-worktree
./dv show compare page:home@app page:home@worktree

dv show resolves URLs only. Open the returned URL with a browser or screenshot tool when you need visual proof.

The Full Loop End To End

With the pieces in place, one complete task looks like this. Each step builds on the previous one, and the live theme does not change until the deploy step.

Open the Divine menu and select your app.
Create a worktree and choose main as the clone source.
Edit a file under pages/, or use the Code view in the workspace.
Run ./dv check . against the worktree theme directory.
Confirm the change in the canvas, then open the browser preview to see it on the real site.
Open the review panel, read the diff, and resolve any conflicts.
Deploy the accepted files back into the app theme.

After deploy, the app theme contains the file changes and the worktree is removed, including its directory and its registry record. Deploy refuses to run while conflicts remain, so the review panel is the gate that keeps unresolved work out of the app theme. When the theme is ready for a client, run ./dv export . to build the standalone, self-contained zip.

A Good First Task

Before asking an agent to build a real page, run a small task that exercises the whole pipeline so you can confirm every surface is wired up. The following prompt creates a worktree, makes one visible change, validates it, and produces a capturable preview.

Create a worktree named "Initial Divine test" from main, add a simple page under
pages/hello/ with a heading, run "./dv check .", and print the dv show page URL
for the new page in the worktree.

If the agent creates the worktree, the page appears in the canvas, dv check reports 0, and you can open the dv show URL in a browser, your installation is ready for real work.