Gillish Cairnstone: Documentation

Install & activate#

Cairnstone ships from the wp.org plugin directory once the v3.0.0 launch lands. Until then it is distributed as a direct zip download from Gillish. Install the standard way:

In your WordPress admin, go to Plugins → Add New → Upload Plugin.
Pick the gillish-cairnstone.zip file and upload it.
Click Activate.

Requirements: WordPress 6.9 or newer, PHP 8.3 or newer. Cairnstone works on PHP up through 8.5 and WordPress through the 7.0 release-candidate line. On older hosts the plugin will refuse to activate with a notice rather than silently break.

Cairnstone runs standalone, with one exception: the visitor-country signal used by Conditional Content location rules is provided by Gillish Node, so country rules need Node installed and active. Everything else works without Node, including the built-in crawler classifier; when Node is present Cairnstone borrows its more comprehensive crawler-classification list. Cairnstone itself makes no external requests and ships no location database.

After activation a new top-level entry appears in the WordPress admin sidebar: Cairnstone. Selecting it opens the Settings page. The menu carries these sub-entries; the Conditional Content sub-entry disappears when that module is turned off.

Blocks. The standard WordPress list of every Cairnstone Block workspace post you have built. Each row is one custom block-type.
Conditional Content. Analytics for the Conditional Content module: an overview tile with a daily-count chart, a top-blocks table, and a per-variant drill-down when you click into a block. Appears only when the Conditional Content module is enabled under Settings → General.
AI activity. A read-only log of every call an AI assistant made to your site in the last 30 days. See AI assistants below.
Settings. Up to five tabs:
- General. Module on / off toggles, one row per library block and per core module.
- Site defaults. Site-wide settings for blocks that support them: your Social profiles, a Brand colours catalogue, a Shadow presets catalogue, and Responsive breakpoints (the two widths where the tablet and phone layouts begin, see Responsive layout). The colour and shadow catalogues are the named sets the Look panel offers: edit a built-in one (Soft, Medium, Strong, Glow for shadows) and it changes everywhere it is used, or add your own with a live preview. A Reset button restores the built-in defaults.
- Block settings. Per-block configuration. For Affiliate Disclosure: a default background for the note (a soft yellow tint by default) that you can recolour with the colour picker or switch off; and a full set of editable disclosure templates: rename the five built-in examples, rewrite their text, give each its own background, text, and link colour, and add your own templates for any market, jurisdiction, or language (or remove your own again). When you place a disclosure block, its Template dropdown lists them all, and the one you pick brings its colours to the note. A single block can still set its own colours, which always win, and an unchanged built-in still follows any installed translation. For Conditional Content: visitor-preview fixtures. Appears only when at least one of those two modules is enabled.
- Integrations. Two toggles: Detect visitor country, with a status line that tells you whether Gillish Node is active to provide the data; and Cairnstone data, which shows or hides the Cairnstone data field picker across the blocks that support it (a Pro feature, on by default).
- AI assistants. One toggle that lets AI assistants draft blocks for you. Off until you turn it on. See AI assistants below.

This documentation lives at html.gillish.com/cairnstone/documentation.

The Cairnstone Block workspace#

The Cairnstone Block workspace is where you build new block-types. Each published post in this workspace becomes a block your site can drop into any post or page through the regular block inserter.

To create one:

Go to Cairnstone → Blocks → Add New.
Give it a title. The title becomes the block's display name in the inserter.
Build the block's structure using Gutenberg's normal block editor. You can nest Cairnstone library blocks, Gutenberg core blocks, and third-party blocks freely.
Publish.

The published post becomes a real, reusable block. Your new block appears under the Cairnstone, My blocks category in every post / page inserter, with the name gillish-cairnstone/<your-slug>. Editing the workspace post later updates every place the block is in use.

The workspace is the canonical Cairnstone surface. Many of the things the inspector lets you do (the universal Look panel, the Visibility recipes, the Schema panel) are most useful inside the workspace editor where you are designing a reusable block. They still work on regular posts and pages but the surface is built for the workspace.

Writing the text in a block. Cairnstone's content blocks (FAQ, Hero, How-to, Testimonial, Author Bio, and the rest) are written straight in the block on the page, the same way you type a normal paragraph. Select a few words and you get the same formatting toolbar you have anywhere in WordPress: bold, italic, underline, links, and any other tools the plugins on your site add to it. The block's settings (layout, colours, visibility) stay in the sidebar; the words live in the block. One exception: a button label, like a Hero call to action, keeps just bold and italic, since a button is already a link and a link inside a link will not work.

The inspector panels#

Cairnstone adds three panels to Gutenberg's Block Inspector (the right-hand sidebar in the editor). Every block you select shows them on top of whatever the block ships with itself.

Look (per-state styling)

Sits in the Styles tab of the inspector, in the Cairnstone Block workspace. The Look panel styles any block, including third-party blocks that ship no styling of their own, and it is built around visual states: a block can have one look at rest and a different look when a visitor points at it, tabs to it, presses it, or when it is turned off.

A row of state buttons sits at the top of the panel:

Default is the resting look. Every other state starts from it and changes only what you set.
Hover applies when the visitor moves the mouse over the block.
Focus applies when the visitor tabs to the block with the keyboard.
Active applies while the visitor is clicking or pressing the block.
Disabled applies when the block is turned off. Unlike the others, the mouse and keyboard do not trigger it; the block has to be marked as turned off, so a plain block keeps its Default look unless something turns it off.

Pick a state, then set any control below. A small dot lights on each state that carries its own look, so you can see at a glance which ones you have changed. Switch back to Default to edit the resting look; a state you leave untouched simply inherits Default.

Every control can differ per state:

Colour set. A named set (Trust blue, Brand stone-blue, Accent, Alert, Neutral, plus any sets your site defines) that fills background, text, and link colour in one pick. Choose a set, then override any single colour below.
Background, Text, and Link colour. Set each on its own, from your theme's colour swatches.
Typography. Font, weight, size, line height, letter spacing, line indent (indents the first line of a paragraph), underline, capitals, and italic. Text alignment (left, centre, right, or justified) that follows the reading direction, so it mirrors correctly in right-to-left languages. A Scale text with screen size switch, so the text shrinks on small screens and grows back on wide ones, never below a readable size. A Drop cap switch that enlarges the first letter of the first paragraph into a magazine-style initial, with a size control for how many lines tall it is. A Vertical text switch that stands the text up as a column with upright, readable letters. And a free angle that tilts the text in place, which you can combine with vertical text. A Content position setting places the block's content at the top, middle, or bottom of its box, and shows when the block is taller than its content (equal-height columns, for example). A Text balancing setting evens out how a heading's lines break, so it never leaves one lonely word on the last line. The underline and strikethrough can be styled further, shown once a line is on: a line style (solid, dashed, dotted, double, or wavy), a line colour (the line is coloured on its own, the text keeps its colour), a thickness, and an underline offset (the gap from the text). For a double line, a thicker line also widens the gap between the two lines. A Limit lines setting cuts the block's lead paragraph off after a set number of lines with an ellipsis, so cards in a row stay the same height.
Border and Outline, together in one section (both are frames around the block). The border sets width, style, colour, and opacity, for all four sides at once or each side on its own, plus a corner radius you can set for all corners together or one at a time. The outline draws a frame just outside the block; unlike a border it takes up no space, so turning it on never nudges the layout. Set the outline's width, style (solid, dashed, dotted, or double), colour, and an offset that pushes it out from the edge or pulls it inwards. Useful as a hover or focus ring.
Shadows, three kinds in one section, each with its own heading and a one-line note so they never blur together. Drop shadow: a raised shadow cast outside the box. Pick a ready-made one by name (Soft, Medium, Strong, a colourful Glow, plus any your site defines) or choose Custom to set offset, blur, spread, and colour by hand; pick a ready-made one and the detailed sliders tuck away, switch back to Custom and they return, remembering the last custom shadow you set. Inner shadow: the opposite, a shadow inside the box for a recessed, pressed-in look; the two stack, so a block can be both lifted and dented. Text shadow: a shadow on the block's text rather than its box (hidden on blocks with no text, such as the Section Divider and the Image block).
Filters. Visual effects over the whole block: blur, brightness, contrast, saturation, grayscale, sepia, and invert, each on its own slider. A Background blur blurs whatever sits behind the block for a frosted-glass look (the block needs to be a little see-through for it to show). One setting for the whole block, not per state.
Media fit. On a block that holds an image or video, this sets how the media fills its box: cover (fill and crop), contain (fit with no crop), fill, none, or scale-down, plus a focal point that decides which part stays in view when it is cropped. On the Image block, pair it with an aspect ratio to crop a photo neatly into a fixed shape. One setting for the whole block.
Padding and Margin, grouped with the size controls in a section named Size & spacing. Both are per-side, with linked or unlinked sides. A Minimum height slider keeps the block at least a set height (handy for full-height sections or equal-height columns). An Aspect ratio locks the block to a fixed shape (16:9, 1:1, and others) so it keeps its proportions as the page resizes, and an Overflow setting decides what happens to content bigger than the block: clip it, scroll it, or hide it. A Stacking order number decides which block sits in front when blocks overlap (a higher number is in front, a lower or negative number is behind), and an Isolate layer switch keeps a block and its contents on their own layer, so nothing inside overlaps the blocks around it. A block that already sticks while scrolling keeps its own position. These apply to the whole block.
Opacity. A 0–100% slider.

The Weight list shows only the weights your chosen font actually ships. If a font runs from Light to Extra bold, for example, you will not see Thin or Black in the list, because the font has no such letters to draw. Pick a different font and the list updates to match. When no font is set, every weight is offered.

The text sizes you set respect each visitor's own text-size choice. A reader who has set their browser to show larger text sees your text grow to match, while everyone else sees exactly the size you set.

An Advanced panel holds three more controls:

Gradient background. A blend between a start colour and an end colour, at an angle you choose. It sits over the plain background colour.
Transform. A lift (the block rises), a scale (it grows or shrinks a little), and a rotation (a tilt up to a half turn each way), perfect for a Hover state where a button nudges up and grows.
Transition. One speed for the whole block that makes every state change glide instead of snapping. Set it to zero for an instant change. Gradient and Transform are per-state like the rest of the panel; Transition is one setting for the block. For visitors who have asked their device for less motion, the movement (lift, scale, rotation) snaps into place while the colour and shadow still fade gently, so the change stays clear without the part of the motion some people find uncomfortable.

You can see all of this without leaving the editor. Point at, tab to, or press a block in the workspace and it shows its real Hover, Focus, or Active look right there in the canvas, gliding at the Transition speed you set. You no longer have to publish the page to check how an interaction feels.

In the workspace these controls are the one place to style a block, so they stand in for Gutenberg's own colour, typography, and border panels there. A block placed in a regular post or page keeps Gutenberg's native styling instead: the per-state Look panel is a workspace tool, while the Visibility, Interactions, and Schema panels below show wherever you edit. See Where the panels appear for the full picture.

Look settings save with the block. The Default look renders as inline styling and each extra state as a small scoped style rule, applied at page load; nothing is written to your theme files.

At the foot of the Look stack a read-only CSS panel lists the style names this block puts on the published page. The names are grouped by where they come from, and each one copies with a single click, so if you like to write your own CSS you can target the block exactly. The list reads from the saved page rather than the editor, so it refreshes when you save. Nothing here changes the block; it only shows you the names.

Visibility

Sits in the Settings tab of the inspector. Decides whether a block renders for a given visitor.

The panel shows eighteen named recipes grouped into five intent groups:

Device. mobile, tablet, desktop. Show the block on a specific form factor.
Audience. logged_in, logged_out, only_admins, hide_admins. Gate on WordPress login state and admin role.
Location. in_country, not_in_country, in_countries, between_times. Gate on visitor country (provided by Gillish Node) or on the visitor's local clock.
Traffic. from_referrer, from_utm, only_crawlers, hide_crawlers. Gate on how the visitor arrived, including bot / search-engine traffic.
Behaviour. first_time, returning, frequent. Gate on visit count (stored in a long-lived cookie).

Click a recipe to apply it; the panel switches to a compact summary of the chosen rule with edit fields for the parameters (country picker, referrer pattern, time window, and so on). To remove the rule, click Always show at the top of the recipe list.

For conditions the recipes do not cover, the bottom of the panel reveals a Custom rule entry. This opens the rule builder: an AND/OR tree where every node is either a single condition (signal + operator + value) or a nested group. Fourteen signals crossed with ten operators (equals, not equals, in, not in, contains, matches regex, greater than, less than, between, not between). The custom rule is the same data structure the recipes generate, just exposed for direct editing.

The custom rule builder is a Cairnstone Pro feature. The eighteen recipes work on every tier.

Interactions

Sits in the Settings tab of the inspector. The Interactions panel makes a block react to what the visitor does, without writing any code. Every interaction reads as a plain sentence: When something happens, then do something.

Click Add an interaction and pick the two halves:

When. The visitor clicks the block, points at it, tabs to it, or presses Enter on it. The block can also react on its own when it scrolls into view, out of view, or past a point you set.
Then. What happens. The wired choices today: toggle one of the block's visual states (so a Look state you styled springs to life), scroll the page to another block, save a visitor signal (which the Visibility panel can read later), set a bound value, or write a style variable on a target.

Scroll to the target is the jump-link maker: put it on an image or a button, point it at a section further down, and a click glides the page there. Visitors who prefer reduced motion get an instant jump instead of the glide. To pick the target, click Pick a block and then click the block on the canvas, or choose it from the list.

Each saved interaction shows as one summary row ("When Click → Scroll to the target"). Click the row to edit it, or use its menu to test it right in the editor, duplicate it, or delete it. The Active switch at the top pauses every interaction on the block without deleting anything.

A few choices in the picker are listed but not wired yet (they are marked as coming later). Picking one saves your intent; nothing fires on the page until the matching feature ships.

Schema

The Schema panel adds JSON-LD structured data to a block so search engines like Google can show rich results in search (a recipe card with cook time and ratings, an FAQ with expandable questions, a product with price and availability, and so on). The panel appears only on blocks whose manifest opts in; most blocks won't show a Schema section, and that is expected.

When you open the section on a supported block, you get a single toggle. Switch it on and a vertical type picker reveals six Schema.org types: Article (blog posts, news, editorial), Product (items you sell, with price and availability), FAQ (question and answer blocks), HowTo (step-by-step instructions), Event (with date and location), and Recipe (with ingredients and steps). Library blocks come with the right type pre-picked (FAQ to FAQ schema, How-to to HowTo), so you rarely choose by hand.

FAQ and How-to send their own search data already. Both blocks build the hidden search-engine notes from your questions or steps on their own, on by default in the block's own settings, with nothing to fill in. Leave the Schema panel off and that built-in version is what search engines get. Turn the Schema panel on and the panel takes over the job: you fill the question or step pairs in the panel, and the block's built-in version goes quiet. The data is never sent twice. A note is only sent when it carries real content, so a freshly enabled panel with empty fields sends nothing rather than something half-filled.

The pricing blocks send their own search data too. Comparison Table and Pricing Cards each add hidden price data so search engines can read your plans: every plan with a set price becomes a structured offer (price, currency, and the plan's button link), and the block sums up your whole range from the lowest to the highest plan price. It is on by default; a Show plans in search results switch in the block's settings turns it off. It uses each plan's default billing-period price in your main currency (a visitor's local currency from geo-pricing is not sent, since search engines see the default view), and it skips any "Contact us"-style plan that has no number. These two blocks do not use the Schema panel above; this built-in version is the whole story for them.

The panel reads top to bottom in one flow: the toggle and type picker first, then the required fields appear directly below once you pick a type, so there is no hopping between tabs. Anything beyond the essentials, the optional Schema.org properties for the chosen type plus a developer custom-code field (labelled "For developers", for anything Cairnstone does not surface as a named field), lives in a single More options section you open only when you need it.

Inside Details, each required field renders in one of three states:

Filled: you typed a value into the field. Nothing more to do.
Auto-filled from Heading: the block already carries the value you'd type. The field reads from your block's own content (the heading text, the price, the published date) and renders read-only with a quiet muted-blue tag naming the source. Edit the block's heading and the schema's headline updates automatically.
Required: the block has no value to read from, and you haven't typed one. The field shows a warn-color border and a status badge; the footer at the bottom of the panel reads N required fields missing. See Details. until you fill them.

Some Schema.org types take repeating data, and each one has its own row editor. FAQ pages take question and answer pairs. How-tos take steps, each with a title and instructions. Recipes take both: ingredient rows (one per ingredient) and step rows. The rows render inside Details as a card list: one card per row, with + Add and a small × remove button per card. The remove action carries a Snackbar with Undo, so accidental removes are recoverable.

The footer at the bottom of the panel always tells you the current state in plain language: Ready for rich results as Product schema. when emission is active, Not shown in search results. when the toggle is off, Pick a type to start. when the toggle is on but no type is chosen yet, N required fields missing. See Details. when required fields are empty. When emission is active, the footer also carries a Test in Rich Results ↗ link that opens Google's Rich Results Test in a new tab with the current post's preview URL pre-filled, so you can confirm what Google sees without leaving the editor.

Beside the status, a See what search engines get line opens a plain-language preview of what this block will look like to search engines, for example "a product called Acme Widget" with each filled field listed below it and a "Still needed" note for anything left empty. It fills in as you type, so you can confirm the setup at a glance without reading code or opening the external test. It stays in the panel; the Rich Results link is still there when you want Google's own check.

Author context. When you open a regular post or page that contains a Cairnstone-built block with schema already configured in the Cairnstone Blocks editor, the Schema section shows the inherited setup as Using Article schema (set in Cairnstone blocks editor) with a quiet Override values button beside it. Most authors never click; the inheritance is what you want. If a specific page does need its own price, headline, or date, click Override values and the Details controls expand inline. A Back to inheriting from Cairnstone blocks link at the top of the override surface reverts to the inherited default when you no longer need the per-instance change.

Cairnstone data

Imagine you sell 20 products on your site. Each product has a price. Without Cairnstone data, you'd type the price into the Pricing block on every product page. That's 20 manual edits. When the price changes, all 20 need updating by hand.

Cairnstone data lets a block read content from somewhere else, like a "price" field on the product page itself. Type the price once on the page, and the block shows it. Same block, different prices on each product, no copy-paste.

How it works: type a field tag in your text. You write your text as normal and drop a tag like {Title} where the live value should go. A heading of Welcome to {Title} shows "Welcome to Summer Sale" on a page titled Summer Sale. You can use several in one field: {Title} by {Author}. The words around the tag are just text you typed, so you stay in full control of the wording.

Where to find it. Open a Cairnstone Block in the Cairnstone blocks editor (not a regular post) and select a block that offers it: today the Hero, Testimonial, Button, Discount Banner, and Author Bio. The Cairnstone data panel sits right under the block's own settings (just below Image on a Hero, for example). Click in.

Turning the panel off. The Cairnstone data panel is a Cairnstone Pro feature, on by default. To hide it, switch Cairnstone data off under Settings → Integrations, and the panel disappears from every block. Turning it off never changes a block that already reads a value: its data still shows on the page. And a field tag you typed straight into a regular Paragraph, Heading, or List (below) keeps working either way, because that does not use the panel.

What the panel offers. One row per text field on the block that can read from elsewhere. A Hero offers its heading, subheading, and the two button texts. Each row has an Insert a field dropdown. Pick a field and its tag drops into that text, at your cursor or at the end. Then keep typing around it. To remove it later, delete the tag from the text like any other word.

It also works in a normal Paragraph, Heading, or List. You don't need a Cairnstone block for this. Type a tag like {Title} straight into a regular Paragraph, Heading, or List on any post or page, and it fills in the same way when the page is shown. A Code block is left alone on purpose, so a {Title} you write there as an example stays as plain text.

The dropdown lists fields by name, in groups. No jargon, just the actual fields:

This post: The page the block sits on: Title, Excerpt, Date, Last modified, Link, Author, Post format. Insert Title into a heading and it shows the page title on every page that uses the block.
This post's category: The page's first category: Name, Slug, Description. Insert Name so every recipe page shows its category without you typing it.

Your own stored fields: type the tag yourself. The dropdown lists the built-in fields. For an extra field your theme or a plugin added, just type its name in braces, like {price}. If you're not sure what extra fields a post has, the WordPress Custom Fields setting (turn it on under Screen Options when editing a post) shows them. Anything in braces that isn't a real field is left exactly as you typed it, so the odd pair of brackets in normal text stays safe.

The cover image works a little differently. An image isn't text, so its row offers a short, image-only list instead of a dropdown of words: the page's Featured image, one of your own stored fields holding an image address, or an image from another block on the page. Pick Featured image and the block shows whatever featured image the page has set.

Button links and Gillish Node. A button's link field takes a plain web address, or, if you use the Gillish Node companion plugin, one of its short link tags like [node id="63"]. Paste the tag in and the button points to that managed link's real address. If the tag doesn't match a link (or Gillish Node isn't active), the button quietly drops its link rather than leading to a blank page. Button links are typed straight in; they don't use the field dropdown.

A worked example: prices on 20 product pages. Step 1: a "price" field gets set up on product pages (your theme or a plugin adds it; the WordPress Custom Fields setting is the simplest way for sites without a developer). Step 2: open the Pricing block in the Cairnstone blocks editor and click into its price text. Step 3: type {price} where the number should show, or write kr {price} to add your own label. Step 4: save the Cairnstone block. From now on, any product page with the price field set shows its own price. Step 5: change the price on a page once, and the block follows. No layouts to re-edit.

Auto-filling tags from Gillish Core

The field tags above ({Title}, {price}) read from the page they sit on. There is a second kind of tag, for site-wide values that are the same on every page: today's date, your site name, the copyright year, and more. These come from the Gillish Core companion plugin, and you write them in square brackets, like [today], [sitename], or [c] for the copyright year.

Type them straight into your text. Drop [today] into a heading, a button, a pricing plan name, a comparison-table cell, or any Cairnstone text field, and it fills in when the page is shown. A line like Offer ends [today] shows the real date on the page. You can mix these tags with your own words and with the field tags above.

They fill in everywhere the block appears, not only inside a normal post: the live page, the editor's Preview, and a block you export and import on another site. In the editor itself you see the tag as you typed it (for example [today]); it turns into the real value on the published page.

If a tag isn't available, your text is safe. These tags need the Gillish Core plugin active, with that tag turned on. If Core is off, or the tag is one Core doesn't know, it simply shows as the plain text you typed, so the page never breaks. Cairnstone adds no data tags of its own here; it reads whatever Gillish Core provides.

Where the panels appear

Cairnstone edits in two places, and it works a little differently in each, so your everyday posts stay clean.

The Cairnstone Block workspace is the design surface. Here the Look panel is the one place to style a block, so it stands in for WordPress's own colour, typography, and border controls. Visibility, Interactions, and Schema sit here too.
A regular post or page is for everyday writing. Here every block keeps its normal WordPress look controls, the ones you already know, and the Look panel steps aside so nothing is doubled up.

What Cairnstone still adds in a regular post, on every block, is Visibility, Interactions, and Schema, the parts that decide who sees a block and what search engines read. That is the point of these three: you can gate any block on the page, even a plain WordPress paragraph, on country, device, login state, and the rest.

So a plain block you did not build in the workspace, like a paragraph or a heading, stays exactly as it would be with Cairnstone switched off: its own normal look controls, plus those three panels. Cairnstone never paints its styling panel over a block it did not make.

Responsive layout (phone, tablet, desktop)#

The layout blocks adapt to the screen on their own. Columns hold the proportions you give them and stack when space runs out; Grid fits as many equal items per row as it can. That is usually all you need. When you want exact control, the layout blocks let you set a different layout for phone, tablet, and desktop.

Where the devices switch (your choice)

You decide where the tablet and phone layouts begin, under Settings → Cairnstone → Site defaults → Responsive breakpoints. Two numbers:

Desktop starts above (default 1024). Browser windows wider than this show the desktop layout; this width and below shows tablet.
Phone at or below (default 600). Browser windows this wide or narrower show the phone layout. In between is tablet.

These are browser-window widths, not your theme's content width. The defaults follow common screen sizes, but you set them to match your own theme and audience: a narrow theme might put desktop at 900, a wide one at 1200. Every layout block on the site follows these two numbers.

Columns: a different width per device

Each column can be a different width on each device. Click into one column (the panel on the right changes from Columns to Column), then use Set width for to pick Desktop, Tablet, or Phone and type the width. Leave a device empty and it follows the bigger screen. For example: 25 / 75 on desktop, 50 / 50 on tablet, stacked on phone.

The whole Columns block also carries an On small screens choice: stack the columns one under the other (the default, best for reading), or keep them side by side (good for a row of logos or icons).

Grid: how many per row per device

By default the Grid fits as many items per row as the Smallest item width allows. For exact control, set a fixed number per device: in the Grid's Layout panel use Set columns for (Desktop / Tablet / Phone) and Items per row. Leave it on Auto to keep the automatic fit, or set, for example, 4 on desktop, 2 on tablet, 1 on phone.

You only ever meet the per-device controls when you reach for them; the simple default on every layout block is unchanged.

The Preview button#

The Cairnstone Block workspace editor adds a Preview button in two places: a header-toolbar entry and an item in the document sidebar's Post Status area. Both carry the same label, Preview live ↗. Clicking it opens a preview of this Cairnstone block in a new tab, so you can see the block render in a real frontend context without copy-pasting the slug.

The button is always visible regardless of which inspector tab you have open. On unsaved drafts the label shortens to Preview live (no arrow), the button is disabled, and a hover tooltip reads "Save the post to preview."

Breaking-change resolution#

When you edit a published Cairnstone Block workspace post, Cairnstone compares the block layout before and after your change. Most edits are safe (e.g. tweaking copy, adjusting padding, recolouring a CTA): the block updates in place and every existing copy picks up the change the next time the page loads.

Some edits are structural: removing a child block, renaming a field, or moving a block to a different place in the layout. These edits will break instances of your block that are already in use elsewhere on the site. When Cairnstone detects a structural change on save, it pauses the publish flow and surfaces a sticky inline notice on the workspace edit screen with three resolution options:

Cancel and edit. Reverts the post content to the pre-edit snapshot. The previously-published version of the block keeps serving as-is. The post returns to the editor as if the edit had not happened.
Migrate existing instances. Walks every post that uses this block. Cairnstone scans every entry in publish, draft, pending, private, or future status across every post type, excluding revisions and auto-drafts. Each instance's inner content is replaced with the new template. If the change is lossy (you removed a field, or a block in the same place lost one of its fields), a confirmation dialog warns you of the loss before the migration runs.
Publish as a new block. Asks you for a new slug (lowercase letters, numbers, hyphens only), creates a fresh workspace post under that slug with the just-edited content, and restores the original post to its snapshot. The old slug keeps serving the previous template; the new slug serves the new content. Both blocks live in the inserter.

The decision is yours per save. If you are not sure, Publish as a new block is the safest fallback: nothing breaks, nothing migrates, and you get a clean second block to iterate on. The slug you choose is rejected if it already exists or if it fails the slug-shape rules; WordPress does not silently auto-uniquify (a deliberate choice so the inserter entry never silently diverges from the slug you typed).

Block import & export#

Cairnstone blocks travel between sites as plain .gcblock.json files. A single block is one file; multiple blocks pack into a single .zip archive. The format is a JSON payload with six top-level fields (formatVersion, slug, title, composition, panelConfig, schemaVersion) and is diff-stable across re-exports: exporting the same block twice produces byte-identical output, so you can version-control your library in git if you want to.

Five surfaces make the round-trip easy. The first three live on the Cairnstone Block workspace editor (one block at a time); the last two live on the Cairnstone blocks list table.

Exporting one block from inside its editor

When you have a Cairnstone Block open for editing, the right sidebar carries a Block export panel between Phase 11's Block content panel and the standard Permalink panel. The panel holds a single ghost button reading "Export this block (.gcblock.json)". Click it; your browser downloads <slug>.gcblock.json immediately.

The button is disabled on unsaved drafts (a tooltip explains "Publish first to enable export."). WordPress does not generate a slug until you publish or autosave-with-slug, and the export route needs the slug to find the post.

Exporting one block from the list table

Open Cairnstone blocks from the admin menu. Hover any row; the standard WordPress row-actions cluster shows up below the title (alongside Edit, Trash, Quick Edit). One of the actions is Export. Click it and the .gcblock.json file downloads.

The Export link is omitted on rows that cannot export: blocks still in trash, and auto-draft rows that never got a title (and therefore never got a slug).

Exporting several blocks at once

On the same list table, tick the checkboxes for the blocks you want, open the Bulk actions dropdown above the table, choose Export selected, and click Apply. Your browser downloads a <your-site>-cairnstone-blocks-YYYY-MM-DD.zip archive containing one .gcblock.json per selected block.

The Apply button shows the standard WordPress spinner-busy state while the archive is being built, so you know the click registered.

Exporting every block at once

If you want the whole library in one archive, the list table's toolbar carries an Export all button next to Import (top-right, sibling to "Add new Cairnstone block"). One click downloads the same <your-site>-cairnstone-blocks-YYYY-MM-DD.zip archive shape as the bulk action, with every block that has a valid slug. Empty-slug drafts and trashed rows are skipped, matching the row-action rules.

If you have no exportable blocks yet (e.g. all your workspace posts are still auto-drafts), the click round-trips through an admin notice reading "Nothing to export. Add at least one Cairnstone block with a title first." rather than handing you an empty archive.

Importing blocks

The list table's toolbar also carries an Import button next to Add new Cairnstone block. Two interactions both produce the same result:

Click Import and pick one or more .gcblock.json files (or a .zip archive containing them) from your computer.
Drag the files from your desktop directly onto the list table. A calm full-table overlay fades in while you drag; releasing the files starts the import.

Either path opens a confirmation modal showing one row per file. Each row carries a coloured status pill that tells you what will happen on commit:

NEW (green): A clean import. The block does not collide with anything already on this site.
RENAMED (amber): The slug already exists on this site. The block will import with an auto-suffixed slug (e.g. pricing-fancy becomes pricing-fancy-2). The sub-line tells you the new slug before you commit.
NEWER FORMAT (red): The file was exported by a newer Cairnstone version than the one running on this site. Cairnstone refuses to read it rather than guessing at fields it doesn't know. Update Cairnstone, then try again.
INVALID (red, click to expand): The file is not a valid Cairnstone export (malformed JSON, missing required fields, slug shape doesn't match the rules). Click the pill to expand the specific field and reason.
MIGRATING (amber): The file was exported by an older Cairnstone version. Cairnstone runs an in-place migration to bring it up to the current format on commit.

If you decide you want to add more files while the modal is open, drag them directly onto the modal. They join the existing preview list. The modal stays open until you click Cancel or Import.

Click Import when you are happy with the preview. Cairnstone commits every importable row as a draft Cairnstone Block (status: draft, never auto-published). A confirmation snackbar at the bottom-left of the screen reads "Imported N blocks as drafts." (with "(M file was skipped.)" appended if any rows didn't commit). The modal closes; your new blocks now appear in the list table, ready to review and publish.

Importing without leaving the terminal

If you prefer the command line, four WP-CLI subcommands cover the same ground:

wp gillish-cairnstone list-blocks, list every Cairnstone Block on the site (formats: table, json, csv, yaml, count, ids).
wp gillish-cairnstone export-block <slug>, print one block as canonical pretty-printed JSON to stdout. Pipe it to a file or another command.
wp gillish-cairnstone import-block [--from=<file>], read a .gcblock.json from --from=<path> or stdin and commit it as a draft.
wp gillish-cairnstone wipe-blocks --yes, trash every Cairnstone Block on the site. Recoverable from the trash. The --yes flag is required.

The CLI uses the same wire-format and validation as the REST + modal flow, so a block exported via the editor imports cleanly via the CLI, and vice versa.

The library blocks#

Cairnstone ships with 21 library blocks: nineteen free, two Pro. Each is a hand-crafted Gutenberg block with its own variations, controls, and frontend behaviour. The blocks live in two inserter categories:

Cairnstone Free

Accordion. A list of collapsible items, each with a header and a content region of any blocks. Built on native HTML <details>, so it opens and closes with zero JavaScript and works with the keyboard. Each item's content is an inner-blocks slot: drop in anything. Choose a container style (all in one frame, or separated cards), space between items, header and content padding, borders and dividers, corner roundness, state-based colours for when an item is open, and a shadow. Six ready looks set the structure at once, and six committed colour schemes (Oxblood Velvet, Midnight Amethyst, Voltage, Harvest Table, Abyssal Teal, Cobalt Signal) give it a bold colour identity that stays readable on any theme; override anything afterwards.
Affiliate Disclosure. Disclosure copy that advertising rules require for pages with affiliate links. Pick a ready-made disclosure example for the main markets (United States, United Kingdom, European Union), plus Amazon Associates and an international default, or write your own. These are examples, not legal advice: the editor reminds you to check your own country's rules and place the note near your affiliate links. Renders as a single-paragraph note with an optional info icon, always visible when placed. Under Settings → Block settings → Affiliate Disclosure you can rename, reword, and colour the built-in examples and add your own for any market or language; the colours you set show while you edit and on the page, and a block's own colours always win.
Author Bio Card. A short author profile with photo, name, role, bio, and social links. Social URLs pull from your site-wide Social profiles setting by default, with optional per-block overrides. Adjustable photo size; toggle between three social-icon sizes.
Badge. A compact trust, status, or announcement mark (Approved, Verified, Best Seller, Limited, and similar). Fifteen pre-written presets across four intent groups; seven silhouettes (pill, rectangle, square, circle, shield, tab, triangle) with adjustable corner radius on rectangular shapes; optional icon, drop shadow, and link. For colour, start from a ready-made scheme or set your own background, text, and link colour. Those colours can change with the badge's state, so it can look one way at rest and another on hover, when reached by keyboard, when pressed, or when switched off.
Button. One clear call to action. A styleable button or link with three looks: filled, outline, and text. Set its colours and shape for every state, add an optional icon, and place it beside any block.
Carousel. A swipeable slideshow of any content. Show a row of slides that visitors swipe or click through, one at a time. Each slide holds any blocks, so a slide can be an image, a quote, a card, or a whole layout. Move between slides with the arrows or the dots, or turn on autoplay to advance them on a timer (it pauses when a visitor hovers or focuses it, and never plays for visitors who prefer reduced motion). With JavaScript off it stays a simple sideways scroller, so the content is always reachable. Six colour schemes give it a committed look, or leave it to follow the theme.
Counter. A number that counts up when it comes into view. Show a statistic that animates from a start value up to its final number the moment it scrolls into view. Add a prefix (like a currency symbol), a suffix (like a plus or a percent sign), and a label underneath. The final number is always in the page, so it reads correctly with JavaScript off and for search engines; the count-up is a visual touch that respects a visitor's reduced-motion setting. Six committed colour schemes give it a bold stat-card identity, or leave it to follow the theme.
Discount Banner. A time-windowed promotional block: heading, body, CTA, optional coupon code with one-click copy, optional countdown. Three layout variants (bar, card, floating corner) with four corner positions for the floating variant. Visitors can close the banner (a toggle you control), and it stays closed on their device until the campaign's wording, code, or end date changes. PHP renders the auto-hide check at request time, so the banner disappears after its end date.
FAQ. A list of question / answer pairs as native HTML <details> accordions. Zero JavaScript, keyboard-accessible. Optional FAQPage structured data (on by default) that helps search engines and AI assistants read your questions and answers. Open mode toggles between "any can be open" (default) and "only one open at a time." A Border set in the Styles tab can wrap the whole list or each question. Answers take the full inline toolbar, including inline images.
Hero. A top-of-page block with heading, subheading, and two calls to action, all written right in the block. Six layout variations: split-right, split-left, centered, left-aligned, overlay background, and minimal. All variations work without an image; the overlay variant degrades to centered when no image is set. On the split layouts you pick the image in the block, choose how big it loads (Medium, Large, or Full size), set a focal point, and can let visitors click it to open full size. The overlay variant uses the image as a darkened background, with an overlay-darkness slider.
How-to. A numbered how-to guide: ordered steps, each with a title, instructions, and an optional image, authored right in the block. Renders as a semantic ordered list with a calm number gutter (no boxed cards). Optional HowTo structured data (on by default) helps search engines and AI assistants read the steps in order. Number badges, a connecting line, the image position, and the space between steps are all adjustable. A Border or Shadow set in the Styles tab can wrap the whole how-to, or frame each step on its own. Pick how big the step images show, from Thumbnail up to Full size; each size loads the right image file, so pages stay sharp and fast. The image settings sit with the picker where you add each step image. Turn on Open full size on click (on by default) and visitors can click a step image to see it large in a clean built-in viewer, with previous / next to move between the guide's images. Right-click to save still works.
Image. A single image, with the parts the core image block leaves out. Pick the image in the block, choose how big it loads (Thumbnail, Small, Medium, Large, or Full size) so pages stay sharp and fast, then size and place it the standard WordPress way: drag an edge to set the width or type an exact size, lock it to a shape (square, wide, portrait, and more) to crop the picture neatly, and align it left, right, wide, or full width from the toolbar; a plain image stays centered on your text. Add an optional caption below it. A border and rounded corners frame the image itself, and the caption always sits outside that frame. The On click choice decides what happens when a visitor clicks: nothing, open full size in the same clean built-in viewer the other blocks use, open an image gallery, go to a link (type to search your own pages, or paste any address), save the image to the visitor's device, or save a file you pick (a PDF or a zip, for example, the classic free-download pattern). The gallery can use images you pick by hand (small arrows under each picture change the viewing order), or flip on Use the other images in this post and the viewer pages through the post's other images on its own; add a new image to the post and it joins without any upkeep. Open full size is the default; right-click to save still works, and the panel reminds you when a link or file is still missing. Because it is a Cairnstone block it inherits universal Conditional Content, so you can show an image only to certain visitors, which the core image block cannot do. The image description (alt text) comes from the Media Library, where you set it once on the file itself.
Logo Row. A row of logos you feature as social proof. Set the logo height, pick an alignment, and choose how the logos look: full color, grayscale, or a single ink (white) that keeps them visible on dark backgrounds. Drop them on a tinted band or in cards, and give each logo a link (a plain address or a Gillish Node link). Keep a payment or security logo in full color while the rest go monotone. Your theme paints the surrounding look.
Modal. A button that opens a dialog over the page. Place a button that opens a dialog holding any blocks: a sign-up form, a video, a message, a whole layout. It is built on the browser's own dialog, so it traps keyboard focus inside while open, closes on the Escape key or a click outside, and returns focus to the button when it closes. With JavaScript off, the content simply shows inline (and the button is hidden), so nothing is ever locked away. Pick the button look and the dialog size, and give it one of six colour schemes or leave it to follow the theme.
Reveal. Content that eases in as it scrolls into view. Wrap any blocks and have them ease into view the moment they scroll onto the screen. Pick the motion (fade, slide up or down or sideways, or a gentle zoom), how long it takes, and an optional delay. The content is always present in the page, so it reads correctly with JavaScript off and for search engines, and visitors who prefer reduced motion simply see it appear with no animation. Reveal once, or every time it scrolls back into view. Six colour schemes can turn it into a committed coloured card, or leave it to follow the theme.
Section Divider. A decorative break between content sections. Five styles: line, dots, asterisks, wave, and a centered label. Width and thickness adjust from the sidebar.
Table of Contents. Auto-generated, nested list of the headings on the current post. Picks up headings as you edit and on save (no manual maintenance). Set the level range, pick a list style (plain, numbered 1.1.1, the legal 1.a.i mix, roman, or bullets that step from a dot to a ring to a square by level), hide entries you do not want, and give a long heading a shorter label. Two live-reading aids you can switch on: the link for the section you are reading highlights as you scroll (a click lands the highlight exactly on the heading you picked), and an optional "Back to top" link. The list can also float beside the content as a panel, with the side, width, and height you set; it fades in, readers can dock it away and it stays docked for them, and it sits inline on phones. The editor preview shows your real headings, styled the way they render.
Tabs. A strip of tab labels that swaps the visible content panel below. Each tab holds its own content region, so you can drop any blocks inside. It follows the accessible tabs pattern with full keyboard support and correct roles for screen readers, and it stays readable with JavaScript off so search engines index every panel. Four ready looks style the strip (Underline, Pill, Folder, Minimal) and six committed colour schemes (Oxblood Velvet, Midnight Amethyst, Voltage, Harvest Table, Abyssal Teal, Cobalt Signal) give it a bold colour identity that stays readable on any theme, with the look and the colour set independently. You choose what happens on small screens: fold the tabs into a stacked, tappable list (announced properly to screen readers), or keep them as tabs that scroll sideways. Turn on shareable links to open a specific tab from a web address, and disable a tab to show it without letting visitors open it. Lay the tabs across the top or down the side; override any colour afterwards.
Testimonial. A single quoted endorsement with attribution. Photo, name, role, and optional 1–5 star rating. A gallery of six layouts: compact stacked, side-by-side, a full split-hero cover, an editorial magazine quote, a centred card, and a spotlight with the rating on top.

Cairnstone Pro

Comparison Table. An accessible feature-comparison table you can style by the column. Plans run across the top, features down the side, grouped into categories. Built as a semantic HTML table (caption, column and row headers, row-group labels) so screen readers and search engines read the comparison correctly. Just the table, with no baked-in heading, so you compose the surrounding content with other blocks.
Pricing Cards. Pricing tier cards you can style one card at a time. A row of plan cards, each with a name, price, short description, a call-to-action button, and a feature checklist. One plan can be marked recommended, lifted with an accent and a marker. An optional billing switch lets visitors flip between periods (such as monthly and yearly); each longer period then shows an automatic savings badge, and you can write your own wording for it (for example Save {percent}%). Just the cards, with no baked-in heading, so you compose the surrounding content with other blocks.

Cairnstone, My blocks

Saved Cairnstone Block workspace posts appear in this third inserter category. This is where the blocks you have built yourself show up.

Each library block has its own controls in the inspector (variations, content fields, layout switches). The universal Look and Visibility panels apply on top: every library block can carry its own colour, border, padding, shadow, and visibility rule (per state) without per-block configuration.

Comparison Table looks & cell patterns

The Comparison Table ships five ready-made looks that restyle the whole table, plus a separate Cell pattern control that tints the cells so a dense table stays easy to scan. The two combine freely: pick a look, then layer a pattern on top. Both follow the table's own colour, so they stay readable on any background, light or dark.

The five looks (Soft is the default; the rest are alphabetical):

Soft. The clean default: hairline dividers and air, a calm stone-blue accent. The other looks build on this base.
Bold. Filled plan headers and big prices, with the recommended plan lifted by a solid accent block. A confident orange-red accent.
Brutal. Neo-brutalist: an off-white surface, hard near-black borders, a sharp offset shadow, and an orange accent and call-to-action.
Dark. A dark canvas with light text and a stone-blue accent, the sibling of the Pricing Cards dark look.
Editorial. Restrained and typographic: a warm burgundy accent with quiet underlines instead of filled bands.

The Cell pattern control offers none, or one of four tints:

None. No cell tint. The default.
Zebra rows. Every second row takes a faint tint.
Column tracks. Every second column takes a faint tint.
Checkerboard. A row-by-column grid of tints.
Section bands. Fills the category band behind each group label (the soft filled band, now an opt-in pattern).

Conditional Content#

Conditional Content is the umbrella term for Cairnstone's visitor-targeted rendering. The Visibility panel (see above) is one surface; the Conditional Content block (a dedicated multi-variant block) is the other.

Render mode and your page cache

Cairnstone defaults to client-side rendering for Visibility rules: the block always ships to the browser, but is hidden by JavaScript if the rule does not match. This works behind every cache (LiteSpeed, WP Rocket, W3 Total Cache, etc.) because every visitor receives the same cached HTML and the personalisation happens in their browser.

The alternative server-side mode is faster for the visitor (no flash of content that then disappears) but only works when there is no page cache, or when the cache is varied by visitor signal. Page caches will cache the page including the server-rendered output, so server-mode on a cached site produces the wrong result for visitors who do not match the cached variant. The block editor surfaces a warning when you flip to server-mode on a site that looks cache-enabled.

Country signal: GeoIP setup

The location recipes (and the country signal in custom rules) need a visitor-country code. Cairnstone does not resolve country itself: it reads it from Gillish Node, which owns geolocation for the Gillish family. For country rules to match, two things must be true:

Gillish Node is installed and active. Node resolves the country and hands it to Cairnstone through a server-side bridge. Without Node, Cairnstone has no country source and the location recipes silently never match.
Detect visitor country is on. Under Settings → Integrations, turn on the Detect visitor country toggle. The status line there tells you whether Node is active to provide the data.

Cairnstone makes no external requests and ships no location database of its own. All country resolution happens inside Gillish Node, on your own server.

Preview as a visitor

While editing a post or page that contains a Conditional Content block, the editor toolbar gains a Preview as dropdown. The dropdown lists named visitor profiles ("Norwegian visitor on mobile", "US visitor logged in", etc.) that you have defined under Settings → Conditional Content. Selecting a profile re-renders the editor canvas as if that visitor were on the page: the matching variant becomes visible, the others hide.

To add or edit profiles, go to Settings → Block settings → Conditional Content. Cairnstone ships with nine default fixtures (iPhone, Android, iPad, Mac desktop, Windows desktop, no-visitor, EU visitor, US visitor, logged-in user). You can add, edit, or remove as needed.

AI assistants#

You can connect an AI assistant, like Claude or ChatGPT, to your site and ask it to build or change blocks for you. The assistant works through your own AI client; Cairnstone just gives it a safe, gated way in. Two things stay true at all times: the assistant can never publish on its own (everything it makes lands as a draft for you to review), and the whole drafting side stays off until you turn it on.

Turning it on

Go to Settings → AI assistants. There is one toggle, Let AI assistants draft Cairnstone blocks, and it is off by default.

Off (the default). Assistants can still read your blocks (this is always allowed for anyone signed in who connects a client). They cannot draft, change, or trash anything.
On. Assistants can also draft new blocks, change existing ones, and move blocks to the trash. Drafts always wait for you to review and publish. Only people who can manage your site's settings can turn this on, each through their own AI client.

Connecting a client needs a standard MCP connection plus a WordPress application password; that setup lives in your AI client, not in Cairnstone. Once connected and turned on, you can say something like "draft an FAQ block about shipping" and a new draft block appears in your Cairnstone blocks list, marked AI draft, ready for you to open, check, and publish.

The AI activity log

Every call an assistant makes, reading or drafting, is recorded for 30 days. Open Cairnstone → AI activity in the admin menu to see it.

The page lists each call with the time, who made it, what it did, and the result. You can filter by what the assistant did (reading or drafting), by result, or by time. Click View on any row to see exactly what the assistant sent and what Cairnstone sent back. Export CSV downloads the list as a spreadsheet for your records.

AI-drafted blocks also carry a small AI draft tag next to their title in the Cairnstone blocks list, so you can tell at a glance which drafts came from an assistant and still need a look. The tag disappears once you publish the block; the full history stays in the AI activity log.

Cairnstone Pro#

Cairnstone Pro is the paid tier. The free plugin works completely standalone; Pro adds blocks and features that build on the free foundation. Today the Pro tier carries:

Pricing Pro (the richer Pricing Table block, with monthly / annual toggle, sticky comparison header, per-tier icon picker, per-feature glyph overrides).
The custom rule builder in the Visibility panel (AND / OR rule trees across 14 signals and 10 operators, beyond the 18 recipes the free tier ships).
The Cairnstone data field picker (the point-and-click panel that binds a block's text and links to your stored data; its on / off switch lives under Settings → Integrations). Typing a field tag by hand keeps working on every tier.

The roadmap adds more Pro blocks and features over time. Free-tier authors see a "Cairnstone Pro" placeholder block in the inserter that names what is available; the block renders nothing on the frontend.

How to buy and activate

The purchase flow is not wired into the plugin yet. Until it lands:

Visit the Gillish website and pick the Cairnstone Pro tier.
Complete the purchase. A license key arrives by email.
When the in-plugin license panel ships (planned for the v3.0.0 launch on wp.org), you will enter the key from inside Cairnstone → Settings.

The free Cairnstone plugin is and will remain functionally complete on the wp.org plugin directory. The Pro upgrade happens through the plugin's own UI to a separate distribution channel; it is never a paywall on a wp.org-listed feature.

Multilingual sites#

Cairnstone blocks behave like any other Gutenberg block on a multilingual site. WPML, Polylang, and TranslatePress all treat Cairnstone-built blocks as standard content: translate the post, the block content goes with it.

Two specific notes:

The Language signal is a Cairnstone Pro feature, available only via the Visibility custom rule builder. The free-tier recipes do not include a language gate. When Pro is active, the Language signal reads the visitor's browser language (the Accept-Language header), not the language WPML or Polylang has assigned to the post. If you want to gate a block by post-language, use your translation plugin's own conditional logic.
The Conditional Content block's named variants each translate independently. A variant carrying English copy can become a Norwegian variant via the translation plugin without touching the variant's targeting rules.

Cairnstone itself ships English-only at v2.2. Other languages arrive as .po / .mo files; the i18n wrappers (`__()`, `esc_html__()`, etc.) are already in place across the plugin.

Troubleshooting#

The plugin will not activate

Cairnstone requires WordPress 6.9 or newer and PHP 8.3 or newer. If your PHP is older, an inline notice tells you so on the Plugins screen ("Gillish Cairnstone requires PHP 8.3 or newer. You are running PHP X.Y.Z.") and the plugin does not load. WordPress itself enforces the WP-version requirement and refuses to activate plugins whose header asks for a newer release.

Check both versions under Tools → Site Health, in the Info tab, or ask your host. If both are fine and activation still fails, your hosting PHP error log carries the fatal-error trace.

A block does not appear in the inserter

For a library block (Hero, Pricing Table, FAQ, and so on): check Settings → General and confirm the block's module toggle is on. Each library block has its own toggle, so disabling one block does not affect the others.

For a Cairnstone Block workspace post you just built: confirm the post is Published, not Draft. Cairnstone registers only Published workspace posts as live block-types; a Draft will not appear in the inserter on any other post.

The country recipe never matches

Visit Settings → Integrations and read the country-detection status line. If detection is off, turn on Detect visitor country. If the line says it is waiting for Gillish Node, install and activate the Gillish Node plugin: Node provides the country data Cairnstone reads.

Cairnstone does not resolve country itself; it reads it from Gillish Node through a server-side bridge. Without Node active, the location recipes silently never match no matter how the toggle is set.

White screen on activation

Rare, but if activating Cairnstone leaves the admin blank, the site has hit a fatal error somewhere. To recover:

Use SSH or your hosting's file manager to rename wp-content/plugins/gillish-cairnstone to anything else. WordPress deactivates the plugin on the next load and the admin comes back.
Log in and confirm the site is back.
Report the issue with your PHP version, your WordPress version, and the relevant lines from wp-content/debug.log (or your hosting's PHP error log).

Updating Cairnstone#

Until v3.0.0 lands on the wp.org plugin directory, updates are manual: download the latest zip from Gillish and re-upload via Plugins → Add New → Upload Plugin. WordPress's plugin installer detects the existing copy and offers Replace current with uploaded; pick that.

Once Cairnstone reaches wp.org, the normal WordPress plugin-update notification appears in the admin and one-click updates work as expected.

Always back up your site before updating any plugin that registers block-types. Cairnstone's breaking-change detection covers the Cairnstone Block workspace, but Cairnstone itself can change shape between major versions in ways that affect existing content.

Where to ask#

Until Cairnstone ships on the wp.org plugin directory, support runs through:

The Gillish website's contact page (link from the site footer).
Direct email to the address listed on the Gillish website.

Once Cairnstone reaches the wp.org plugin directory, the wp.org support forums become the canonical place. Bug reports there get tracked on the public GitHub mirror (the link will land in the v3.0.0 release notes).

Feature requests, ideas, and feedback are welcome through any of the same channels. This documentation page is also part of the support loop: when a question recurs, it lands here as a new sub-section in the relevant chapter.