Skip to content

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.

  • Version 0.1.0-beta
  • Status Beta
  • WordPress 7.0+
  • PHP 8.2+
  • GPL-2.0-or-later

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.

SurfaceRole
Hewn Blank themeMinimal companion block theme and the recommended starting point.
Hewn reference themeDesigned FSE example with templates, tokens and sample components.
Hewn ChildChild theme extending Hewn Blank.
Hewn pluginRegistry, server renderer, bindings, visual editor, Workspace, changesets, REST, MCP, quality and rescue.
Visual editorAdmin-only React UI for structure, component properties, bindings and preview.
WorkspaceAsk/Build/Fix chat surface that proposes change cards and previews.
MCP bridgeLocal Cursor server and WordPress MCP adapter for safe read/propose/apply tools.
Beta, manual distribution

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

RequirementDetail
WordPress7.0 or later. The website’s old 6.7 minimum is incorrect.
PHP8.2 or later.
DevelopmentNode.js 22, pnpm 10, Composer 2 and Docker for wp-env.
DistributionFour release ZIPs: plugin, Blank theme, reference theme and Child theme, plus a checksum manifest.
OptionalWordPress 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.

The visual editor is feature-flagged

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.

  1. Choose a page and a mode: Ask, Build or Fix.
  2. Connect a WordPress AI provider in Settings → Connectors. Ask and deterministic plans work without one; Build/Fix stop without a provider.
  3. Review the composition plan and change cards.
  4. Preview the change, then approve and apply through the change-set pipeline.
  5. 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, the hewn_production capability 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) and ndx/v1 (compatibility).
  • Local MCP commands include mcp install cursor, mcp serve and health.
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

CapabilityMeaning
hewn_inspectRead project, components and site.
hewn_proposePropose changes.
hewn_previewRender and compare previews.
hewn_apply_stagingApply to staging.
hewn_approveApprove change sets.
hewn_productionApply 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

SymptomWhat to check
hewn/mount unsupportedThe plugin is inactive or its mount block assets are missing.
Build/Fix does nothingConfigure a WordPress AI provider in Settings → Connectors.
Visual editor disabledThe feature flag is off, safe mode is on, or the active theme uses the generic adapter.
Production apply refusedRequires production writes, capability and human approval.
MCP token 401/403Expired/revoked token, wrong site binding, MCP disabled, writes disabled or tool not in scope.
Approval stopped workingSalt rotation or site URL change invalidates HMAC approval/audit proofs. Reapprove.
Quality report inconclusiveSome checks need WordPress escaping functions; browser coverage is one page and not Lighthouse.
Rescue missingwp-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.

What are we
building next?

Tell us about it