Developer Reference

Fernlight — Developer Reference

Current as of 13 October 2026. The free theme handles presentation. Companion has free and premium editions of one plugin; Pro adds paid draft workflows. Migrator is a separate staging-first tool.

Current versions

  • Fernlight theme: 1.2.62 approved and live on WordPress.org.
  • Fernlight Companion Free: 1.3.13 submitted for WordPress.org recheck on 12 October 2026; approval pending.
  • Fernlight Migrator beta: 1.2.18 site download; 1.2.19 prepared, full migration-fidelity verification pending.
  • Fernlight Companion Pro: 1.3.13 released through Freemius.

Product boundaries

  • Theme: templates, template parts, theme.json tokens, style variations, block styles, editor styles, bundled fonts, screenshot, RTL, and editable block patterns. No custom REST routes, no content writes, no external service calls, no workflow settings.
  • Companion Free: editorial blocks, optional reading/archive/search behavior, and read-only Site Intelligence. Owner-operated settings and Starter Content can change the site; the AI reports do not create drafts or publish.
  • Migration beta: optional one-time plugin for staging-first audits and Fernlight draft copies from supported builder content. It preserves originals and records provenance.
  • Pro: premium edition of Companion, distributed by Freemius. It replaces the free edition and retains included free features. The free archive contains no Freemius SDK; the premium archive uses premium-only licensing and update delivery. Stable fernlight_pro_* identifiers remain unchanged.

Theme architecture

  • WordPress 6.7+ and PHP 8.0+.
  • Block theme using theme.json version 3.
  • The theme loads a base stylesheet, modular component styles, and a print stylesheet. Archive, single-post, and WooCommerce modules load where applicable. Readable CSS sources accompany the minified files under assets/css/.
  • No front-end JavaScript from the theme.
  • Patterns auto-register from patterns/*.php; pattern categories are registered in inc/block-patterns.php.
  • Block styles are registered in inc/block-styles.php.

Companion discovery surfaces

Runtime discovery and AI-tool context live in Fernlight Companion, not in the theme. Companion exposes read-only REST routes and WordPress Abilities where available, including manifest, capabilities, site context, recommendations, validation, exports, and content inventory.

Migration beta

Use Fernlight Migration on staging first. It audits Kadence, Stackable, CoBlocks, and core/block-theme content, then can create Fernlight draft copies with confidence notes, gap explanations, and provenance. Originals are not modified.

Pro workflows

Pro is the gated action layer. It creates reviewable drafts, briefs, workbenches, and handoff packs from owner-supplied intent and guardrails. It does not replace the free theme and does not publish without human review.

Packaging and access

Both Companion editions use fernlight-companion/fernlight-companion.php. Replace the installed edition through WordPress Upload Plugin; keep one edition active. The free package contains no licensing SDK or premium implementation. The premium package includes the Freemius SDK and licensed premium tools.

Theme and Companion require WordPress 6.7+ and PHP 8.0+. The current public Migrator beta requires WordPress 6.5+ and PHP 8.0+ and declares testing through WordPress 7.0. Its prepared 1.2.19 update declares testing through 7.1; it is not yet the public download.

Public discovery starts at /wp-json/fernlight/v1/manifest and /wp-json/fernlight/v1/capabilities. Site-context and other private reports require an authenticated user with the appropriate editing capability. AI draft workflows appear under Tools → Fernlight AI Connections; licensing is under Appearance → Fernlight Companion → License & Pro. These existing admin labels and fernlight_pro_* identifiers remain stable.

Connect, inspect, draft, review

Open Tools → Fernlight AI Connections → Connect AI Client. An administrator saves owner purpose, audience, voice, protected material, reference pages, and environment confirmation under Site Context → Site Brief. Review Editing Guidelines, then use a compatible authenticated AI client to inspect the selected page, discuss changes, and request a separate Pro draft. Follow its review link or open Draft Review; compare the draft with the current source and publish manually.

REST works without MCP Adapter when the client supports authenticated REST. MCP is optional, requires a separately installed adapter, and exposes only the selected Fernlight tool groups. Plan eligibility, WordPress permissions, and MCP exposure are separate checks. A successful server check does not verify an external AI client connection; actual configured Codex/Claude acceptance remains pending. See the AI Tools Guide.

Authenticated first read: GET /wp-json/fernlight/v1/ai/agent-brief or fernlight/get-agent-brief. Use the brief to confirm site identity, environment, and saved owner intent, then request detailed context or page inspection as needed. The public manifest remains the tool reference. Site-wide local analytics requires administrator-level manage_options; it is separate from the public performance summary. Source-version tokens and retry identifiers are not required. Repeated draft-creation requests can create separate drafts.