Nought Suite Hewn Documentation
Structured pages.
Editable afterwards.
Hewn is a WordPress theme family plus a companion plugin, visual editor, Workspace, change-set pipeline and MCP bridge. Pages are built from registered components; content stays in WordPress or ACF; new executable PHP goes through source control, not the browser.
Start here
What Hewn actually is
Hewn is not a page builder with a private canvas. It is a theme family and a product plugin that share a component schema. Templates, components and design tokens live in the repository; posts, pages, media and field values live in WordPress.
| Surface | Role |
|---|---|
| Hewn Blank theme | Minimal companion block theme and the recommended starting point. |
| Hewn reference theme | Designed FSE example with templates, tokens and sample components. |
| Hewn Child | Child theme extending Hewn Blank. |
| Hewn plugin | Registry, server renderer, bindings, visual editor, Workspace, changesets, REST, MCP, quality and rescue. |
| Visual editor | Admin-only React UI for structure, component properties, bindings and preview. |
| Workspace | Ask/Build/Fix chat surface that proposes change cards and previews. |
| MCP bridge | Local Cursor server and WordPress MCP adapter for safe read/propose/apply tools. |
The current release is 0.1.0-beta. There is no WordPress.org or self-hosted updater in the repository; release ZIPs and release.json are built manually. Test on staging and keep the signed release artefacts.
Before installing
Requirements and installation
| Requirement | Detail |
|---|---|
| WordPress | 7.0 or later. The website’s old 6.7 minimum is incorrect. |
| PHP | 8.2 or later. |
| Development | Node.js 22, pnpm 10, Composer 2 and Docker for wp-env. |
| Distribution | Four release ZIPs: plugin, Blank theme, reference theme and Child theme, plus a checksum manifest. |
| Optional | WordPress MCP Adapter for the HTTP MCP server; a configured WordPress AI provider for Build/Fix. |
Install and activate the Hewn plugin, then activate one of the Hewn themes. Hewn Blank is the supported base. The reference theme is for the designed example. The plugin registers the hewn/mount block; without the plugin, that block cannot render a component tree.
Theme family
Blank, Reference and Child
Hewn Blank
Minimal WordPress shell plus the component runtime. Recommended for client work and new builds.
Hewn Reference
A full-site editing demonstration with designed templates, semantic HTML, tokens and 12 example components.
Hewn Child
Extends Hewn Blank so custom CSS and template overrides survive parent updates.
Templates and template parts are normal WordPress FSE files. A page can use normal WordPress blocks or a Hewn component tree. The theme is the look; the plugin owns the component registry, renderer and editor.
The model
Components, schemas and server rendering
Components are registered with JSON Schema contracts for props, slots, bindings and query presets. PHP and TypeScript validators share the same schema. The server renderer composes validated component trees; the browser editor is a control surface, not the renderer.
- A component can expose typed props, named slots, repeatable children and content bindings.
- Bindings connect a prop to native WordPress meta or ACF fields.
- Query presets and loops support repeatable content without storing a private document.
- Generated components are declarative only: tree, accordion and carousel. Hewn does not generate PHP, JavaScript or CSS from the browser.
- New executable components go through source control and deployment.
Fields
Content models and field bindings
Content models declare the fields a page or component expects. When ACF is available, Hewn generates field groups. Without ACF, it registers native nonce-protected meta boxes. Text, media, links, groups and repeaters can be bound to either.
FieldCraft is optional. When present, populated ACF refactors can route through FieldCraft. Gravity Forms forms can be referenced through the optional GFAPI bridge.
Visual editor
The visual editor
The editor is admin-only React. It shows the page structure tree, a searchable component library, schema-driven property controls, binding and query settings, and an iframe preview at 390 px, 768 px and 1280 px.
FeatureFlags::VISUAL_INSPECTOR defaults to false outside the development channel. The Editor screen exposes an “Enable visual editor” action. Safe mode also disables it. Generic third-party block themes use a reduced adapter: component rendering and structure remain, but the visual editor and token pipeline are disabled.
Agent workspace
Workspace
Workspace is the default Hewn admin screen. Ask analyses the project, Build composes a page, and Fix proposes repairs. A plan becomes change cards, then a preview and apply path. There is no unrestricted shell, SQL or arbitrary filesystem write.
- Choose a page and a mode: Ask, Build or Fix.
- Connect a WordPress AI provider in Settings → Connectors. Ask and deterministic plans work without one; Build/Fix stop without a provider.
- Review the composition plan and change cards.
- Preview the change, then approve and apply through the change-set pipeline.
- Use Save/Start over to keep or discard the working state.
Governance
Change sets, preview, approval and rollback
Every write is a change set: draft → validated → planned → approved → applying → applied, with an explicit rollback path. Agents can propose; a human must approve. Production is never the default environment.
- Validation: JSON Schema, operation compiler, PHP/JSON/CSS/token validation, Quality Engine preflight and postcondition fingerprints.
- Preview: signed preview tokens, default TTL 900 seconds, noindex canvas and hidden admin bar.
- Approval: approver, time, correlation ID, expiry, plan SHA-256 and HMAC proof. Changing the plan invalidates approval.
- Production:
HEWN_ALLOW_PRODUCTION_WRITES=true, thehewn_productioncapability and human approval. - Rollback: requires a verified recovery point, refuses if the project changed after apply, and rechecks health. A failed apply can auto-revert.
Reliability
Rescue, safe mode and recovery
Hewn installs an mu-plugin rescue handler on activation. It captures fatals, exposes an emergency route and health probes, and keeps a last-known-good pin. If mu-plugins is not writable, activation can still succeed without rescue; check the Rescue screen.
Safe mode disables the visual editor and MCP writes while keeping native WordPress screens, frontend rendering and recovery available. Diagnostics exports PHP, WordPress, theme, adapter, schema, quarantine and edition details with secrets redacted.
Integration
MCP, agent tokens and REST
MCP is off on fresh installs. When enabled, the WordPress MCP Adapter exposes read, propose, preview and apply tools with scoped bearer tokens. Writes also require the experimental MCP write flag and a filter/capability check.
- Agent tokens are shown once, hashed at rest, expire after 24 hours, max 20 active sessions, and are bound to site, environment, tools and resources.
- A session cannot be granted propose and approve together.
- Invalid bearer tokens return 401 and never fall back to the browser user.
- REST namespaces are
hewn/v1(canonical) andndx/v1(compatibility). - Local MCP commands include
mcp install cursor,mcp serveandhealth.
hewn-mcp/mcp
hewn-mcp/tool/project.inspect
hewn-mcp/tool/component.list
hewn-mcp/tool/changeset.validate
hewn-mcp/tool/changeset.apply Design and checks
Design Kernel, Quality Engine and generated components
Design Kernel
Canonical tokens, brand profiles, generated theme.json/CSS, and contrast/role/variant/responsive lint.
Quality Engine
Revision-bound report with static theme/token/template/component checks, an axe browser runner and one deterministic repair. Browser coverage is one seeded page, not every page.
Generated components
Declarative tree, accordion and carousel components only, with versioned updates and template migrations. No generated executable files.
AI media
Provider-neutral previews through the WordPress AI Client, signed candidates, explicit save to Media Library and provenance.
Access
Permissions and audit
| Capability | Meaning |
|---|---|
hewn_inspect | Read project, components and site. |
hewn_propose | Propose changes. |
hewn_preview | Render and compare previews. |
hewn_apply_staging | Apply to staging. |
hewn_approve | Approve change sets. |
hewn_production | Apply to production. |
Audit entries use a site-salted HMAC chain over actor, action, environment, correlation, result, redacted payload and timestamp. The audit API reports integrity for up to 500 newest entries. Retention is 90 days by default.
Honest edges
Limits and troubleshooting
| Symptom | What to check |
|---|---|
hewn/mount unsupported | The plugin is inactive or its mount block assets are missing. |
| Build/Fix does nothing | Configure a WordPress AI provider in Settings → Connectors. |
| Visual editor disabled | The feature flag is off, safe mode is on, or the active theme uses the generic adapter. |
| Production apply refused | Requires production writes, capability and human approval. |
| MCP token 401/403 | Expired/revoked token, wrong site binding, MCP disabled, writes disabled or tool not in scope. |
| Approval stopped working | Salt rotation or site URL change invalidates HMAC approval/audit proofs. Reapprove. |
| Quality report inconclusive | Some checks need WordPress escaping functions; browser coverage is one page and not Lighthouse. |
| Rescue missing | wp-content/mu-plugins may not be writable. Check Diagnostics and the Rescue screen. |
No self-hosted updater, no translated catalogues, no multisite CI, no external penetration test, and no remote/team services in the Connected edition. Distribution is manual ZIP + release.json.
Documentation for Hewn 0.1.0-beta, checked against the product source. Where this page and the installed product disagree, the installed product is authoritative.