Refiners are workspace-scoped, chainable post-generation transforms — brand voice, SEO hygiene, image generation, CTAs — that turn generic AI drafts into ready-to-ship pieces.

A refiner is a reusable post-generation transform that you apply to content. It's the layer between a generic AI-written draft and a brand-aligned, ready-to-ship piece. Most articles go through 2–4 refiners after the initial draft: one for brand voice, one for SEO hygiene, one for image generation, one for the CTA.

Refiners are workspace-scoped, library-grade, and chainable. The same refiner library applies to blog posts, landing pages, and (with the image variant) every piece of visual asset.

The short version

Three types: SIMPLE_REFINER (text), IMAGE_REFINER (one image), MULTI_IMAGE_REFINER (N images)
Apply one or many to a piece of content; each application produces a tracked revision
Workspace-scoped library; agencies can fork system refiners and customize per client
Refiner application is part of the Production · refine API

Why we modeled it this way

Three design constraints shaped this:

1. Drafts and final content are different jobs. The model writing the first draft and the model fixing voice / cutting fluff / adding the CTA aren't necessarily the same model, and shouldn't be the same prompt. Separating "write a draft" from "apply the brand voice" lets each step be tuned and observed independently. Bad drafts get cheap regens; bad refinement gets one fast pass.

2. Brand voice is the most common manual edit. Every team we talked to said: "I have to rewrite every AI-generated post to sound like us." Refiners productize that — once you have a brand-voice refiner that works, every future post gets the same treatment automatically.

3. Images belong in the same library. OG images, in-line illustrations, feature cards — these need brand consistency too. Stuffing image generation into the same library as text refinement means one place to manage brand standards.

The data model

{
  "id": "rfn_brand-voice",
  "type": "SIMPLE_REFINER",
  "title": "Acme brand voice",
  "description": "Confident, technical, second-person. Cut corporate cliches. Prefer short sentences.",
  "prompt": "Rewrite this article in Acme's voice. Use second person ...",
  "organizationId": "ws_acme",
  "createdAt": "2026-02-15T...",
  "updatedAt": "2026-05-20T..."
}

The three types

// SIMPLE_REFINER — text-only
{
  "type": "SIMPLE_REFINER",
  "prompt": "Rewrite this article in our brand voice ..."
}

// IMAGE_REFINER — one templated image
{
  "type": "IMAGE_REFINER",
  "prompt": "Generate an OG image illustrating the article's main idea",
  "templateId": "acme-og-card"
}

// MULTI_IMAGE_REFINER — N images, one per template
{
  "type": "MULTI_IMAGE_REFINER",
  "prompt": "Generate hero + in-line + CTA images",
  "templates": [
    { "templateId": "acme-hero",   "prompt": "Hero illustration aligned to article topic" },
    { "templateId": "acme-inline", "prompt": "Two in-line illustrations to break up scanning" },
    { "templateId": "acme-cta",    "prompt": "Bottom-of-article CTA card matching the article's offer" }
  ]
}

Templates referenced by templateId come from the image template registry (see Production · image).

When you apply refiners to a piece of content, each application is tracked:

"refinements": [
  { "refinerId": "rfn_brand-voice", "appliedAt": "2026-05-24T08:08:14Z", "invocationId": "inv_***" },
  { "refinerId": "rfn_seo-cleanup", "appliedAt": "2026-05-24T08:08:42Z", "invocationId": "inv_***" },
  { "refinerId": "rfn_og-image",    "appliedAt": "2026-05-24T08:09:01Z", "invocationId": "inv_***" }
]

Each refinement is a new Content revision under the hood — the original draft is preserved, every step is reversible.

How it interacts with other concepts

Concept	Relationship
Pillars	Each pillar can declare a default refiner set; content created in that pillar auto-applies them
BlogPost / LandingPage	Both accept refiners; both track refinement chains
Agent	`produce.refine` is a tool; the `content_factory` skill applies refiners as part of its pipeline
Image generation	`IMAGE_REFINER` / `MULTI_IMAGE_REFINER` are how brand-image generation gets reused across many articles
Approval Workflows	A refiner can declare `requiresApproval: true` — useful for high-edit refiners you want a human to see

System vs workspace refiners

System refiners ship with CitationBench: system.seo-hygiene, system.readability-pass, system.fact-check, system.fluff-cut. They're available in every workspace.
Workspace refiners are yours to author, edit, and version. Most agencies build 4–8 per client: brand voice, SEO cleanup, image set, CTA refresher.
You can fork a system refiner into your workspace to customize it without affecting the original.

Common patterns

1. The standard pipeline

produce.blog_post   (writes the draft)
  ↓
produce.refine      rfn_brand-voice
  ↓
produce.refine      rfn_seo-cleanup
  ↓
produce.refine      rfn_og-image    (MULTI_IMAGE_REFINER, generates hero + 2 inline)
  ↓
produce.publish

2. Default refiners per pillar

curl -X PATCH .../v1/produce/landing-page/pillar/pil_pricing -d '{
  "defaultRefinerIds": ["rfn_brand-voice", "rfn_pricing-cta", "rfn_og-image"]
}'

Now every landing page generated in that pillar auto-applies them.

3. Bulk refresh after a brand voice update

You edit rfn_brand-voice (e.g., tightened tone). Re-apply across the existing library:

curl -X POST .../v1/produce/refine/bulk -d '{
  "refinerId": "rfn_brand-voice",
  "scope": { "type": "blog_post", "tags": ["q2-2026"] }
}'

4. Conditional image set

A MULTI_IMAGE_REFINER can take the article's structured outline as input and pick templates based on it (e.g., "if the article has a 'pricing' section, also generate a pricing-comparison card").

5. Custom refiners via the agent

curl -X POST .../v1/agent/invoke -d '{
  "skill": "produce.refine",
  "input": {
    "contentId": "cnt_***",
    "refinerId": "custom:eli-style-pass"
  }
}'

Content Refiners: reusable transforms for brand-aligned content