brand-intent 0.21.0 → 0.23.0

package/examples/krume/krume.identity

@@ -65,6 +65,14 @@ voice
     - Superlative ohne Substanz (bestes Brot, einzigartiger Geschmack)
     - Wellness- oder Gesundheitsversprechen (gut für dich, clean eating)
 
+  # instead: the phrase to avoid and what Krume writes instead.
+  # A pair teaches the rewrite, not just the ban.
+
+  instead:
+    - "beste Zutaten" -> Tipo 1 und Roggen 1150 aus der Mühle in Dachau
+    - "mit Liebe gebacken" -> achtzehn Stunden Teigruhe
+    - "frisch aus dem Ofen" -> seit 6 Uhr im Regal
+
 # ── Values ──
 # Not keywords - behavior statements. Each value describes
 # how it manifests in what we say and do.
@@ -74,11 +82,15 @@ values
     Wir benennen den Prozess, nicht das Ergebnis.
     Backzeit in Stunden, Mehlsorte beim Namen.
     Kein Brot ohne nachvollziehbaren Weg vom Korn zum Laib.
+    say: Der Roggen steht seit gestern Abend.
+    not: Mit Liebe handgemacht.
 
   Ehrlichkeit
     Kein Brot ohne Zutatenliste. Keine Versprechen
     die der Teig nicht halten kann. Wenn etwas
     nicht gelungen ist, sagen wir das.
+    say: Heute kein Dinkel. Der Teig wollte nicht.
+    not: Leider ausverkauft, schau morgen wieder vorbei!
 
   Kiez
     Der Laden gehört zur Weserstraße wie der Späti
@@ -125,3 +137,61 @@ anti-audience discount-hunters
                Supermarkt-Toastbrot vergleicht, ist hier falsch.
                Wir erklären gerne warum es kostet was es kostet -
                aber wir rechtfertigen uns nicht.
+
+# ── Imagery ──
+# The image counterpart of voice: yes/no rules for photos and film.
+# Framing and colour treatment live in krume.brand.
+
+imagery
+  always:
+    - echte Arbeitsschritte in der Backstube, nichts nachgestellt
+    - Mehl, Teig und Werkzeug mit Gebrauchsspuren
+    - Tageslicht oder das Licht der Backstube
+  never:
+    - gestellte Lächeln in die Kamera
+    - Brot als Deko auf Leinen und Holzbrett
+    - KI-generierte oder KI-veränderte Bildinhalte
+
+image-theme Vier Uhr morgens
+  Die Backstube vor Ladenöffnung: Hände im Teig,
+  Mehl auf der Arbeitsfläche, der Ofen offen.
+
+image-theme Über den Tresen
+  Stammkunden und Laufkundschaft am Tresen,
+  Brot wechselt die Hand, die Weserstraße im Hintergrund.
+
+# ── Goals ──
+# What a post is for, independent of its format.
+# Shares: monthly target for Instagram.
+
+goal craft
+  label:    Handwerk zeigen
+  share:    60%
+  question: Wie entsteht das Brot?
+  always:
+    - einen konkreten Arbeitsschritt, eine Mehlsorte oder eine Zeit nennen
+
+goal kiez
+  label:    Kiez
+  share:    30%
+  question: Wer kommt hierher und warum?
+  always:
+    - eine Person mit Vornamen und ihrem Grund zu kommen
+
+goal service
+  label:    Service
+  share:    10%
+  question: Was gibt es heute, wann ist offen?
+  always:
+    - Tag, Uhrzeit und Sorte konkret nennen
+
+# ── Review ──
+# Asked before anything goes out. Each one is a yes/no question.
+
+review
+  copy:
+    - Nennt der Text Sorte, Mehl, Gewicht oder Backzeit?
+    - Klingt er wie die Bäckerin hinterm Tresen?
+  image:
+    - Zeigt das Bild einen echten Arbeitsschritt oder echte Kundschaft?
+    - Ist das Brot Lebensmittel, nicht Dekoration?

package/examples/krume/purposes/daily-bread.purpose

@@ -42,37 +42,45 @@ slot primary
   typography: headline
   color:      text-primary
   maxLength:  30
-  samples:
-    - Roggenlaib
-    - Weizenmisch
-    - Dinkelvollkorn
 
 slot secondary
   label:      Gewicht & Preis
   typography: kicker
   color:      text-secondary
   maxLength:  25
-  samples:
-    - 750 g · 5,80 €
-    - 500 g · 4,20 €
-    - 1 kg · 7,50 €
 
 slot meta
   label:      Beschreibung
   typography: caption
   color:      text-secondary
   maxLength:  100
-  samples:
-    - Roggen 1150, 18 Stunden Teigführung, Kümmel aus dem Wendland.
-    - Tipo 1 aus der Drax-Mühle, 72 % Hydration.
-    - Saisonale Walnüsse vom Wochenmarkt, Emmer-Vollkorn.
 
 slot label
   label:      Badge
   typography: label
   color:      label-fg
   maxLength:  20
-  samples:
-    - Heute frisch
-    - Nur samstags
-    - Neu im Laden
+
+# ── Examples ──
+# Whole pages: all slots written together about one bread.
+
+example
+  topic: The classic rye loaf, today's bread
+  label:     Heute frisch
+  primary:   Roggenlaib
+  secondary: 750 g · 5,80 €
+  meta:      Roggen 1150, 18 Stunden Teigführung, Kümmel aus dem Wendland.
+
+example
+  topic: The wheat blend, only on Saturdays
+  label:     Nur samstags
+  primary:   Weizenmisch
+  secondary: 500 g · 4,20 €
+  meta:      Tipo 1 aus der Drax-Mühle, 72 % Hydration.
+
+example
+  topic: New in the shop: emmer bread with walnuts
+  label:     Neu im Laden
+  primary:   Emmer-Walnuss
+  secondary: 1 kg · 7,50 €
+  meta:      Saisonale Walnüsse vom Wochenmarkt, Emmer-Vollkorn.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",

package/parser/README.md

@@ -34,3 +34,4 @@ const brand = parseBrandFile(
 ## Notes
 
 - These parsers throw on validation errors, with the filename and line number included in the error message.
+- Non-fatal findings (deprecated syntax) are returned in `warnings` (`parsePurposeFile`) as `file:line: message`, so implementations can show them in their UI.

package/parser/brandParser.ts

@@ -169,6 +169,10 @@ export interface ParsedFramingDef {
   horizon: number | null;
   /** The photographic task, one line. */
   description?: string;
+  /** What a text adds to a photo in this framing, one line. */
+  caption?: string;
+  /** Identity goal ids this framing serves. */
+  goals?: string[];
 }
 
 export type CounterFormat = '1' | '01' | '1.' | '(1)' | 'i';
@@ -209,6 +213,14 @@ export interface ParsedAssetDef {
   group?: string;
   /** Photos only: name of the date window the photo fits (`when:`). Absent → all year. */
   when?: string;
+  /** Photos only: the framing module the photo was taken in. */
+  framing?: string;
+  /** Photos only: where the photo was taken. */
+  place?: string;
+  /** Photos only: who is shown, with name and role. */
+  person?: string;
+  /** Photos only: date taken, YYYY-MM-DD. */
+  taken?: string;
 }
 
 export type LogoAlign = 'left' | 'center' | 'right';
@@ -1784,6 +1796,9 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (raw.props['generator']) def.generator = raw.props['generator'];
     if (raw.props['group']) def.group = raw.props['group'];
     if (raw.props['when']) def.when = raw.props['when'];
+    for (const key of ['framing', 'place', 'person', 'taken'] as const) {
+      if (raw.props[key]) def[key] = raw.props[key];
+    }
     // generator-params are stored as "generator-params.KEY" by the sub-block parser.
     const paramEntries: [string, number][] = [];
     for (const [k, v] of Object.entries(raw.props)) {
@@ -1814,13 +1829,20 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     }
     result.windows = windows;
   }
+  const photoOnly = ['when', 'framing', 'place', 'person', 'taken'];
   for (const [kind, arr] of [['logo', logosRaw], ['video', videosRaw], ['illustration', illustrationsRaw]] as const) {
-    const a = arr.find(r => r.props['when']);
-    if (a) throw new Error(`${fileName}: ${kind} "${a.id}": when: is for photos only`);
+    for (const key of photoOnly) {
+      const a = arr.find(r => r.props[key]);
+      if (a) throw new Error(`${fileName}: ${kind} "${a.id}": ${key}: is for photos only`);
+    }
   }
   for (const p of photosRaw) {
     const when = p.props['when'];
     if (when && !result.windows?.[when]) throw new Error(`${fileName}: photo "${p.id}" references unknown window "${when}"`);
+    const taken = p.props['taken'];
+    if (taken && !/^\d{4}-\d{2}-\d{2}$/.test(taken)) throw new Error(`${fileName}: photo "${p.id}": taken: must be YYYY-MM-DD, got "${taken}"`);
+    const framing = p.props['framing'];
+    if (framing && !framingsRaw.some(f => f.id === framing)) throw new Error(`${fileName}: photo "${p.id}" references unknown framing "${framing}"`);
   }
 
   if (logosRaw.length > 0 || photosRaw.length > 0 || videosRaw.length > 0 || illustrationsRaw.length > 0) {
@@ -1987,7 +2009,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
 
   // Finalise framing modules
   if (framingsRaw.length > 0) {
-    const known = new Set(['label', 'horizon', 'description']);
+    const known = new Set(['label', 'horizon', 'description', 'caption', 'goals']);
     result.framings = framingsRaw.map(({ id, line, props }) => {
       for (const [key, { line: l }] of Object.entries(props)) {
         if (!known.has(key)) throw new Error(`${fileName}:${l}: unknown framing property "${key}"`);
@@ -2003,6 +2025,8 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       }
       const def: ParsedFramingDef = { id, label: props['label']?.value || id, horizon };
       if (props['description']?.value) def.description = props['description'].value;
+      if (props['caption']?.value) def.caption = props['caption'].value;
+      if (props['goals']?.value) def.goals = props['goals'].value.split(',').map(g => g.trim()).filter(Boolean);
       return def;
     });
   }

package/parser/identityParser.ts

@@ -2,7 +2,8 @@
  * Parser for .identity brand identity files.
  *
  * Line-based format with indentation-based blocks.
- * Contains brand strategy: essence, promise, voice, pillars, audiences, values.
+ * Contains brand strategy: essence, promise, voice, pillars, audiences, values,
+ * imagery, goals and review checks.
  * No visual properties of any kind.
  */
 
@@ -40,6 +41,14 @@ export interface ParsedIdentity {
   values?: ParsedValue[];
   /** Explicitly not-our-audience segments keyed by ID */
   antiAudiences?: Record<string, ParsedAntiAudience>;
+  /** Rules for photos and film: what the imagery always shows and never shows */
+  imagery?: ParsedImagery;
+  /** Named image themes, in declaration order */
+  imageThemes?: ParsedImageTheme[];
+  /** Communication goals keyed by ID (e.g. the shares of a content mix), in declaration order */
+  goals?: Record<string, ParsedGoal>;
+  /** Questions to check before publishing */
+  review?: ParsedReview;
 }
 
 export interface ParsedVoice {
@@ -53,6 +62,15 @@ export interface ParsedVoice {
   always: string[];
   /** Concrete rules the brand never breaks */
   never: string[];
+  /** Phrases to replace, each with the brand's own wording */
+  instead?: ParsedReplacement[];
+}
+
+export interface ParsedReplacement {
+  /** The phrase to avoid */
+  avoid: string;
+  /** What the brand writes instead */
+  use: string;
 }
 
 export interface ParsedPillars {
@@ -96,13 +114,56 @@ export interface ParsedValue {
   name: string;
   /** Behavior statement — what this value means in practice */
   behavior: string;
+  /** Example lines that carry this value */
+  say?: string[];
+  /** Counter-examples: lines that miss it */
+  not?: string[];
+}
+
+export interface ParsedImagery {
+  /** What every photo and film shows */
+  always: string[];
+  /** What the imagery never shows */
+  never: string[];
+}
+
+export interface ParsedImageTheme {
+  /** Theme title (free-form) */
+  name: string;
+  /** Name of the narrative this theme belongs to */
+  narrative?: string;
+  /** What the images show */
+  text: string;
+}
+
+export interface ParsedGoal {
+  /** Human-readable goal name */
+  label: string;
+  /** Target share of the content mix, 0–100 */
+  share?: number;
+  /** The question content for this goal answers */
+  question?: string;
+  /** Narratives this goal draws on */
+  narratives?: string[];
+  /** Rules content for this goal follows */
+  always?: string[];
+  /** Rules content for this goal never breaks */
+  never?: string[];
+}
+
+export interface ParsedReview {
+  /** Questions for texts */
+  copy?: string[];
+  /** Questions for photos and film */
+  image?: string[];
 }
 
 // ── Parser ────────────────────────────────────────────────────────────────────
 
-type Block = 'top' | 'voice' | 'pillars' | 'audience' | 'anti-audience' | 'values' | 'narrative';
+type Block = 'top' | 'voice' | 'pillars' | 'audience' | 'anti-audience' | 'values' | 'narrative' | 'imagery' | 'image-theme' | 'goal' | 'review';
 type NarrativeState = { name: string; primary: boolean; text: string };
-type ListTarget = 'always' | 'never' | 'primary' | 'secondary' | 'avoid';
+type ListTarget = 'always' | 'never' | 'instead' | 'primary' | 'secondary' | 'avoid'
+  | 'imagery-always' | 'imagery-never' | 'goal-always' | 'goal-never' | 'review-copy' | 'review-image';
 
 export function parseIdentityFile(content: string, fileName: string): ParsedIdentity {
   const lines = content.split('\n');
@@ -122,12 +183,22 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
   const audiences: Record<string, Partial<ParsedAudience>> = {};
   const antiAudiences: Record<string, Partial<ParsedAntiAudience>> = {};
   const values: ParsedValue[] = [];
+  const imagery: ParsedImagery = { always: [], never: [] };
+  let imageryDeclared = false;
+  const imageThemes: ParsedImageTheme[] = [];
+  let currentImageTheme: ParsedImageTheme | null = null;
+  const goals: Record<string, Partial<ParsedGoal> & { line: number }> = {};
+  let currentGoal = '';
+  const review: ParsedReview = {};
+  let reviewDeclared = false;
 
   let block: Block = 'top';
   let currentAudience = '';
   let currentAntiAudience = '';
   let currentValueName = '';
   let currentValueBehavior = '';
+  let currentValueSay: string[] = [];
+  let currentValueNot: string[] = [];
   let listTarget: ListTarget | null = null;
   let continuationKey: string | null = null;
 
@@ -144,10 +215,29 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
 
   function flushValue() {
     if (currentValueName && currentValueBehavior) {
-      values.push({ name: currentValueName, behavior: currentValueBehavior.trim() });
+      const value: ParsedValue = { name: currentValueName, behavior: currentValueBehavior.trim() };
+      if (currentValueSay.length > 0) value.say = currentValueSay;
+      if (currentValueNot.length > 0) value.not = currentValueNot;
+      values.push(value);
     }
     currentValueName = '';
     currentValueBehavior = '';
+    currentValueSay = [];
+    currentValueNot = [];
+  }
+
+  function flushImageTheme() {
+    if (currentImageTheme && currentImageTheme.text) {
+      imageThemes.push({ ...currentImageTheme, text: currentImageTheme.text.trim() });
+    }
+    currentImageTheme = null;
+  }
+
+  /** Close the free-text blocks before a new block or top-level key starts. */
+  function flushBlock() {
+    if (block === 'values') flushValue();
+    if (block === 'narrative') flushNarrative();
+    if (block === 'image-theme') flushImageTheme();
   }
 
   for (let i = 0; i < lines.length; i++) {
@@ -167,10 +257,13 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
     if (block === 'values' && /^\s{2,}/.test(raw) && !raw.trim().startsWith('#')) {
       const indent = raw.match(/^(\s*)/)?.[1].length ?? 0;
       const text = raw.trim();
+      const example = text.match(/^(say|not):\s*(.+)$/);
       if (indent <= 2 && !text.includes(':')) {
         // New value name (2-space indent)
         flushValue();
         currentValueName = text;
+      } else if (currentValueName && example) {
+        (example[1] === 'say' ? currentValueSay : currentValueNot).push(example[2].trim());
       } else if (currentValueName) {
         // Behavior text (4+ space indent) or continuation
         currentValueBehavior += (currentValueBehavior ? ' ' : '') + text;
@@ -189,6 +282,15 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
       continue;
     }
 
+    // ── Image theme block: optional narrative reference, then text lines ──
+    if (block === 'image-theme' && currentImageTheme && /^\s{2,}/.test(raw) && !raw.trim().startsWith('#')) {
+      const trimmed = raw.trim();
+      const ref = trimmed.match(/^narrative:\s*(.+)$/);
+      if (ref) currentImageTheme.narrative = ref[1].trim();
+      else currentImageTheme.text += (currentImageTheme.text ? '\n' : '') + trimmed;
+      continue;
+    }
+
     // ── Indented continuation lines ──
     if (/^\s{2,}/.test(raw) && !raw.trim().startsWith('-') && !raw.trim().includes(':')) {
       const continuation = raw.trim();
@@ -215,6 +317,19 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
         case 'primary': pillars.primary!.push(value); break;
         case 'secondary': (pillars.secondary ??= []).push(value); break;
         case 'avoid': pillars.avoid!.push(value); break;
+        case 'instead': {
+          const arrow = value.indexOf('->');
+          if (arrow === -1) throw new Error(`${fileName}:${lineNum}: voice.instead item must be "PHRASE -> REPLACEMENT", got "${value}"`);
+          const unquote = (s: string) => s.trim().replace(/^["„“](.*)["“”]$/, '$1');
+          (voice.instead ??= []).push({ avoid: unquote(value.slice(0, arrow)), use: unquote(value.slice(arrow + 2)) });
+          break;
+        }
+        case 'imagery-always': imagery.always.push(value); break;
+        case 'imagery-never': imagery.never.push(value); break;
+        case 'goal-always': (goals[currentGoal].always ??= []).push(value); break;
+        case 'goal-never': (goals[currentGoal].never ??= []).push(value); break;
+        case 'review-copy': (review.copy ??= []).push(value); break;
+        case 'review-image': (review.image ??= []).push(value); break;
       }
       continuationKey = null;
       continue;
@@ -235,6 +350,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
           case 'rhythm': voice.rhythm = val; break;
           case 'always': listTarget = 'always'; break;
           case 'never': listTarget = 'never'; break;
+          case 'instead': listTarget = 'instead'; break;
           default:
             throw new Error(`${fileName}:${lineNum}: unknown voice key "${key}"`);
         }
@@ -273,6 +389,38 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
           default:
             throw new Error(`${fileName}:${lineNum}: unknown anti-audience key "${key}"`);
         }
+      } else if (block === 'imagery') {
+        switch (key) {
+          case 'always': listTarget = 'imagery-always'; break;
+          case 'never': listTarget = 'imagery-never'; break;
+          default:
+            throw new Error(`${fileName}:${lineNum}: unknown imagery key "${key}"`);
+        }
+      } else if (block === 'goal' && currentGoal) {
+        const goal = goals[currentGoal];
+        switch (key) {
+          case 'label': goal.label = val; break;
+          case 'question': goal.question = val; break;
+          case 'share': {
+            const m = val.match(/^(\d+(?:\.\d+)?)%$/);
+            const n = m ? parseFloat(m[1]) : NaN;
+            if (!(n >= 0 && n <= 100)) throw new Error(`${fileName}:${lineNum}: goal share must be a percentage between 0% and 100%, got "${val}"`);
+            goal.share = n;
+            break;
+          }
+          case 'narratives': goal.narratives = val.split(',').map(s => s.trim()).filter(Boolean); break;
+          case 'always': listTarget = 'goal-always'; break;
+          case 'never': listTarget = 'goal-never'; break;
+          default:
+            throw new Error(`${fileName}:${lineNum}: unknown goal key "${key}"`);
+        }
+      } else if (block === 'review') {
+        switch (key) {
+          case 'copy': listTarget = 'review-copy'; break;
+          case 'image': listTarget = 'review-image'; break;
+          default:
+            throw new Error(`${fileName}:${lineNum}: unknown review key "${key}"`);
+        }
       }
       continue;
     }
@@ -282,8 +430,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
     if (topMatch) {
       const [, key, value] = topMatch;
       const val = value.trim();
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'top';
       listTarget = null;
       continuationKey = null;
@@ -327,8 +474,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
 
     // ── Block headers ──
     if (raw.match(/^voice\s*$/)) {
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'voice';
       listTarget = null;
       continuationKey = null;
@@ -336,8 +482,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
     }
 
     if (raw.match(/^pillars\s*$/)) {
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'pillars';
       listTarget = null;
       continuationKey = null;
@@ -345,8 +490,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
     }
 
     if (raw.match(/^values\s*$/)) {
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'values';
       listTarget = null;
       continuationKey = null;
@@ -355,8 +499,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
 
     const narrativeMatch = raw.match(/^narrative\s+(.+?)\s*$/);
     if (narrativeMatch) {
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'narrative';
       currentNarrative = { name: narrativeMatch[1].trim(), primary: false, text: '' };
       listTarget = null;
@@ -364,10 +507,49 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
       continue;
     }
 
+    if (raw.match(/^imagery\s*$/)) {
+      flushBlock();
+      block = 'imagery';
+      imageryDeclared = true;
+      listTarget = null;
+      continuationKey = null;
+      continue;
+    }
+
+    if (raw.match(/^review\s*$/)) {
+      flushBlock();
+      block = 'review';
+      reviewDeclared = true;
+      listTarget = null;
+      continuationKey = null;
+      continue;
+    }
+
+    const imageThemeMatch = raw.match(/^image-theme\s+(.+?)\s*$/);
+    if (imageThemeMatch) {
+      flushBlock();
+      block = 'image-theme';
+      currentImageTheme = { name: imageThemeMatch[1].trim(), text: '' };
+      listTarget = null;
+      continuationKey = null;
+      continue;
+    }
+
+    const goalMatch = raw.match(/^goal\s+(\S+)\s*$/);
+    if (goalMatch) {
+      flushBlock();
+      block = 'goal';
+      currentGoal = goalMatch[1];
+      if (goals[currentGoal]) throw new Error(`${fileName}:${lineNum}: duplicate goal "${currentGoal}"`);
+      goals[currentGoal] = { line: lineNum };
+      listTarget = null;
+      continuationKey = null;
+      continue;
+    }
+
     const audienceMatch = raw.match(/^audience\s+(\S+)\s*$/);
     if (audienceMatch) {
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'audience';
       currentAudience = audienceMatch[1];
       audiences[currentAudience] ??= {};
@@ -378,8 +560,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
 
     const antiAudienceMatch = raw.match(/^anti-audience\s+(\S+)\s*$/);
     if (antiAudienceMatch) {
-      if (block === 'values') flushValue();
-      if (block === 'narrative') flushNarrative();
+      flushBlock();
       block = 'anti-audience';
       currentAntiAudience = antiAudienceMatch[1];
       antiAudiences[currentAntiAudience] ??= {};
@@ -389,9 +570,8 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
     }
   }
 
-  // Flush last value/narrative if in those blocks
-  if (block === 'values') flushValue();
-  if (block === 'narrative') flushNarrative();
+  // Flush the last free-text block
+  flushBlock();
 
   // ── Validation ──────────────────────────────────────────────────────────────
 
@@ -416,6 +596,23 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
     if (!aa.description) throw new Error(`${fileName}: anti-audience "${id}" missing required field "description:"`);
   }
 
+  const narrativeNames = new Set(narratives.map(n => n.name));
+  for (const theme of imageThemes) {
+    if (theme.narrative && !narrativeNames.has(theme.narrative)) {
+      throw new Error(`${fileName}: image-theme "${theme.name}" references unknown narrative "${theme.narrative}"`);
+    }
+  }
+
+  let shareTotal = 0;
+  for (const [id, goal] of Object.entries(goals)) {
+    if (!goal.label) throw new Error(`${fileName}:${goal.line}: goal "${id}" missing required field "label:"`);
+    for (const name of goal.narratives ?? []) {
+      if (!narrativeNames.has(name)) throw new Error(`${fileName}:${goal.line}: goal "${id}" references unknown narrative "${name}"`);
+    }
+    shareTotal += goal.share ?? 0;
+  }
+  if (shareTotal > 100) throw new Error(`${fileName}: goal shares add up to ${shareTotal}%, more than 100%`);
+
   // ── Hex value exclusion rule ──
   const hexPattern = /#[0-9A-Fa-f]{3,8}\b/;
   if (hexPattern.test(content.replace(/#.*$/gm, ''))) {
@@ -442,6 +639,14 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
   if (Object.keys(antiAudiences).length > 0) {
     result.antiAudiences = antiAudiences as Record<string, ParsedAntiAudience>;
   }
+  if (imageryDeclared) result.imagery = imagery;
+  if (imageThemes.length > 0) result.imageThemes = imageThemes;
+  if (Object.keys(goals).length > 0) {
+    result.goals = Object.fromEntries(
+      Object.entries(goals).map(([id, { line: _line, ...goal }]) => [id, goal as ParsedGoal]),
+    );
+  }
+  if (reviewDeclared) result.review = review;
 
   return result;
 }

package/parser/index.ts

@@ -3,7 +3,7 @@
 // they take a string (file content) and filename, return a parsed object.
 
 export { parseIdentityFile } from './identityParser';
-export type { ParsedIdentity, ParsedVoice, ParsedPillars, ParsedAudience, ParsedAntiAudience, ParsedValue } from './identityParser';
+export type { ParsedIdentity, ParsedVoice, ParsedReplacement, ParsedPillars, ParsedAudience, ParsedAntiAudience, ParsedValue, ParsedImagery, ParsedImageTheme, ParsedGoal, ParsedReview } from './identityParser';
 
 export { parseBrandFile } from './brandParser';
 export {
@@ -69,7 +69,7 @@ export { parseFormatFile } from './formatParser';
 export type { ParsedFormat } from './formatParser';
 
 export { parsePurposeFile } from './purposeParser';
-export type { ParsedPurpose, ParsedPurposeSlot, Density, ListMarker } from './purposeParser';
+export type { ParsedPurpose, ParsedPurposeSlot, ParsedExample, CountRange, Density, ListMarker } from './purposeParser';
 
 export { parseCompositionFile } from './compositionParser';
 export type {

package/parser/purposeParser.ts

@@ -43,25 +43,50 @@ export interface ParsedPurpose {
   cameraFacing?: 'front' | 'rear';
   /** `framing: <id>` — the brand framing module photos for this purpose are shot in. */
   framing?: string;
+  /** `goal: <id>` — the identity goal this purpose serves by default. */
+  goal?: string;
   /** When false, photo/video analysis skips this purpose (no AI text generation). Default: true. */
   analyze?: boolean;
   /** Default icon for the icon slot. Resolves in the brand set first, then Phosphor (see resolveIconRef). */
   defaultIcon?: IconRef;
   /** Optional prompt text shown in the empty background placeholder. Default: "Select a background". */
   bgPrompt?: string;
+  /** Example pages: all texts of one page written together, one topic each. Built from deprecated
+   *  slot `samples:` (paired by position, `legacy: true`) when the file has no `example` blocks. */
+  examples: ParsedExample[];
+  /** Deprecations and other non-fatal findings, as "file:line: message". Implementations show them. */
+  warnings: string[];
+}
+
+/** One `example` block: a whole page about one topic. */
+export interface ParsedExample {
+  /** What the page is about, one sentence. Becomes the page topic. */
+  topic?: string;
+  /** Identity goal id; overrides the purpose `goal:` for this page. */
+  goal?: string;
+  /** Date window name from the `.brand` `windows` block; undefined = all year. */
+  when?: string;
+  /** Text per slot. List items are newline-separated. Slots with `value:` never appear. */
+  texts: Partial<Record<SlotId, string>>;
+  /** True when built from deprecated slot `samples:`. */
+  legacy?: boolean;
 }
 
 export interface ParsedPurposeSlot {
   id: SlotId;
   label: string;
-  /** Sample text variants for this slot. Picked randomly on page creation. */
+  /** @deprecated Slot `samples:` from older files; content lives in `ParsedPurpose.examples`.
+   *  Empty for files with `example` blocks; `[value]` for a fixed-value slot. */
   samples: string[];
-  /** Date window per sample (parallel to `samples`), from a trailing `@name` marker; undefined = all year.
-   *  Absent when no sample in the slot has a marker. Names resolve against the `.brand` `windows` block. */
+  /** @deprecated Date window per legacy sample (parallel to `samples`), from a trailing `@name` marker. */
   sampleWindows?: (string | undefined)[];
-  /** Fixed value — when set, this slot is never AI-generated or shuffled. Mutually exclusive with samples. */
+  /** Fixed value — when set, this slot is never AI-generated or shuffled. Never part of an example. */
   value?: string;
   maxLength: number;
+  /** Editorial word range (`words: 3..8`). Guidance on top of the hard `maxLength`. */
+  words?: CountRange;
+  /** Editorial sentence range (`sentences: 1..2`). Guidance on top of the hard `maxLength`. */
+  sentences?: CountRange;
   /** 'text' (default) or 'list'. */
   slotType?: 'text' | 'list';
   /** Max number of items (list slots only). */
@@ -109,6 +134,12 @@ export interface ParsedPurposeSlot {
   }>;
 }
 
+/** Inclusive count range; `words: 3` is { min: 3, max: 3 }. */
+export interface CountRange {
+  min: number;
+  max: number;
+}
+
 // ── Constants ─────────────────────────────────────────────────────────────────
 
 const VALID_SLOTS = new Set<string>(['primary', 'secondary', 'detail', 'meta', 'cta', 'label']);
@@ -142,10 +173,18 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
   let camera: boolean | undefined;
   let cameraFacing: 'front' | 'rear' | undefined;
   let framing: string | undefined;
+  let goal: string | undefined;
   let analyze: boolean | undefined;
   let defaultIcon: IconRef | undefined;
   let bgPrompt: string | undefined;
   const slots: ParsedPurposeSlot[] = [];
+  const warnings: string[] = [];
+  const examples: (ParsedExample & { line: number; keyLines: Partial<Record<string, number>> })[] = [];
+  // Example block being built, and the slot key whose multi-line value is being read (4-space lines)
+  let currentExample: (typeof examples)[number] | null = null;
+  let exampleMultiKey: SlotId | null = null;
+  // First line of a deprecated slot `samples:` (0 = none)
+  let legacySamplesLine = 0;
   // For backward compat: track first # line text for fallback id
   let firstHashText = '';
 
@@ -163,7 +202,6 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     const s = currentSlot;
     if (!s.id) throw new Error(`${fileName}:${lineNum}: slot missing id`);
     if (!s.label) throw new Error(`${fileName}:${lineNum}: slot "${s.id}" missing label`);
-    if ((!s.samples || s.samples.length === 0) && !s.iconOnly && !s.value) throw new Error(`${fileName}:${lineNum}: slot "${s.id}" missing samples or value`);
     if (!s.maxLength) throw new Error(`${fileName}:${lineNum}: slot "${s.id}" missing maxLength`);
     if (s.iconOnly) {
       if (s.marker && s.marker !== 'icon') throw new Error(`${fileName}:${lineNum}: slot "${s.id}": iconOnly needs "marker: icon", got "${s.marker}"`);
@@ -204,6 +242,17 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     currentSlot = null;
   }
 
+  function finalizeExample() {
+    currentExample = null;
+    exampleMultiKey = null;
+  }
+
+  /** A top-level line closes the open slot or example block. */
+  function closeBlocks(lineNum: number) {
+    finalizeSlot(lineNum);
+    finalizeExample();
+  }
+
   for (let i = 0; i < lines.length; i++) {
     const lineNum = i + 1;
     const raw = lines[i];
@@ -234,7 +283,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
 
     // scope block header
     if (line === 'scope' && !raw.startsWith(' ')) {
-      finalizeSlot(lineNum);
+      closeBlocks(lineNum);
       inScopeBlock = true;
       inContextBlock = false;
       inVoiceBlock = false;
@@ -244,7 +293,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
 
     // context block header
     if (line === 'context' && !raw.startsWith(' ')) {
-      finalizeSlot(lineNum);
+      closeBlocks(lineNum);
       inContextBlock = true;
       inScopeBlock = false;
       inVoiceBlock = false;
@@ -253,7 +302,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
 
     // voice block header
     if (line === 'voice' && !raw.startsWith(' ')) {
-      finalizeSlot(lineNum);
+      closeBlocks(lineNum);
       inVoiceBlock = true;
       inScopeBlock = false;
       inContextBlock = false;
@@ -261,6 +310,44 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
       continue;
     }
 
+    // example block header: one whole page
+    if (line === 'example' && !raw.startsWith(' ')) {
+      closeBlocks(lineNum);
+      inScopeBlock = inContextBlock = inVoiceBlock = false;
+      currentExample = { texts: {}, line: lineNum, keyLines: {} };
+      examples.push(currentExample);
+      continue;
+    }
+
+    // example block lines: `key: value`, or bare `key:` followed by 4-space lines (list items, line breaks)
+    if (currentExample && raw.startsWith('  ')) {
+      if (raw.startsWith('    ')) {
+        if (!exampleMultiKey) throw new Error(`${fileName}:${lineNum}: unexpected "${line}" in example (multi-line text follows a bare "slot:" line)`);
+        const prev = currentExample.texts[exampleMultiKey];
+        currentExample.texts[exampleMultiKey] = prev ? `${prev}\n${line}` : line;
+        continue;
+      }
+      exampleMultiKey = null;
+      const colonIdx = line.indexOf(':');
+      if (colonIdx === -1) throw new Error(`${fileName}:${lineNum}: expected "key: value" in example, got "${line}"`);
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      if (key in currentExample.keyLines) throw new Error(`${fileName}:${lineNum}: duplicate "${key}" in example`);
+      currentExample.keyLines[key] = lineNum;
+      if (key === 'topic' || key === 'goal' || key === 'when') {
+        if (!value) throw new Error(`${fileName}:${lineNum}: empty ${key}`);
+        if (key === 'when' && !/^[a-z][a-z0-9-]*$/.test(value)) throw new Error(`${fileName}:${lineNum}: invalid window name "${value}" (lowercase kebab-case)`);
+        currentExample[key] = value;
+        continue;
+      }
+      if (!VALID_SLOTS.has(key)) throw new Error(`${fileName}:${lineNum}: unknown example key "${key}" (expected topic, goal, when or a slot id)`);
+      if (value) currentExample.texts[key as SlotId] = value;
+      else exampleMultiKey = key as SlotId;
+      continue;
+    } else if (currentExample && !raw.startsWith(' ')) {
+      finalizeExample();
+    }
+
     // scope block properties (2-space indent)
     if (inScopeBlock && raw.startsWith('  ') && !raw.startsWith('    ')) {
       if (line.startsWith('audience:')) {
@@ -349,6 +436,12 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
       continue;
     }
 
+    // Goal: one of the identity's `goal NAME` blocks
+    if (line.startsWith('goal:') && !raw.startsWith(' ')) {
+      goal = line.slice(5).trim() || undefined;
+      continue;
+    }
+
     // Photo/video analysis control
     if (line.startsWith('analyze:')) {
       analyze = line.slice(8).trim() !== 'false';
@@ -369,14 +462,14 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
 
     // Backward compat: "icon: warning-circle" (deprecated — use defaultIcon:)
     if (line.startsWith('icon:') && !raw.startsWith(' ')) {
-      console.warn(`${fileName}:${lineNum}: deprecated "icon:" — use "defaultIcon:" instead`);
+      warnings.push(`${fileName}:${lineNum}: deprecated "icon:" — use "defaultIcon:" instead`);
       defaultIcon = parseIconRef(line.slice(5), `${fileName}:${lineNum}`);
       continue;
     }
 
     // Slot start
     if (line.startsWith('slot ')) {
-      finalizeSlot(lineNum);
+      closeBlocks(lineNum);
       const slotId = line.slice(5).trim();
       if (!VALID_SLOTS.has(slotId)) throw new Error(`${fileName}:${lineNum}: unknown slot "${slotId}"`);
       currentSlot = { id: slotId as SlotId, samples: [], typography: {} as ParsedPurposeSlot['typography'] };
@@ -492,6 +585,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
           continue;
         }
         if (prop.startsWith('samples:')) {
+          legacySamplesLine ||= lineNum;
           const raw = prop.slice(8).trim();
           if (!raw) {
             // Bare `samples:` — enter multi-line mode
@@ -513,12 +607,12 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
           continue;
         }
         if (prop === 'icons: true' || prop === 'icons:true') {
-          console.warn(`${fileName}:${lineNum}: deprecated "icons: true" — use "marker: counter" or "marker: icon"`);
+          warnings.push(`${fileName}:${lineNum}: deprecated "icons: true" — use "marker: counter" or "marker: icon"`);
           currentSlot.marker = currentSlot.marker ?? 'counter';
           continue;
         }
         if (prop === 'icons: false' || prop === 'icons:false') {
-          console.warn(`${fileName}:${lineNum}: deprecated "icons: false" — use "marker: none"`);
+          warnings.push(`${fileName}:${lineNum}: deprecated "icons: false" — use "marker: none"`);
           currentSlot.marker = currentSlot.marker ?? 'none';
           continue;
         }
@@ -581,6 +675,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
         continue;
       }
       if (prop.startsWith('samples:')) {
+        legacySamplesLine ||= lineNum;
         const raw = prop.slice(8).trim();
         if (!raw) {
           // Bare `samples:` — enter multi-line mode
@@ -597,6 +692,15 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
         currentSlot.maxLength = n;
         continue;
       }
+      if (prop.startsWith('words:') || prop.startsWith('sentences:')) {
+        const key = prop.startsWith('words:') ? 'words' : 'sentences';
+        const v = prop.slice(key.length + 1).trim();
+        const m = v.match(/^(\d+)(?:\.\.(\d+))?$/);
+        const range = m ? { min: parseInt(m[1], 10), max: parseInt(m[2] ?? m[1], 10) } : null;
+        if (!range || range.min <= 0 || range.max < range.min) throw new Error(`${fileName}:${lineNum}: invalid ${key} "${v}" — expected N or MIN..MAX`);
+        currentSlot[key] = range;
+        continue;
+      }
       if (prop.startsWith('typography:')) {
         currentSlot.typographyRef = prop.slice(11).trim();
         continue;
@@ -655,13 +759,13 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     throw new Error(`${fileName}:${lineNum}: unexpected "${line}"`);
   }
 
-  // Finalize last slot
-  finalizeSlot(lines.length);
+  // Finalize last block
+  closeBlocks(lines.length);
 
   // Backward compat: if no id: line but we have a first # line, use it as id
   if (!id) {
     if (firstHashText) {
-      console.warn(`${fileName}: deprecated — add "id: ${firstHashText}" line (first # line used as fallback id)`);
+      warnings.push(`${fileName}: deprecated — add "id: ${firstHashText}" line (first # line used as fallback id)`);
       id = firstHashText;
     } else {
       throw new Error(`${fileName}: missing purpose id (add "id:" line)`);
@@ -682,5 +786,64 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     context = contextLines.join('\n').trim();
   }
 
-  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, cameraFacing, framing, analyze, defaultIcon, bgPrompt };
+  const parsedExamples = resolveExamples(examples, slots, legacySamplesLine, fileName, warnings);
+
+  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, cameraFacing, framing, goal, analyze, defaultIcon, bgPrompt, examples: parsedExamples, warnings };
+}
+
+/** Validate `example` blocks against the declared slots, or build examples from deprecated slot
+ *  `samples:` (paired by position) when the file has none. Mixing both is an error. */
+function resolveExamples(
+  examples: (ParsedExample & { line: number; keyLines: Partial<Record<string, number>> })[],
+  slots: ParsedPurposeSlot[],
+  legacySamplesLine: number,
+  fileName: string,
+  warnings: string[],
+): ParsedExample[] {
+  const byId = new Map(slots.map(s => [s.id, s]));
+  const contentSlots = slots.filter(s => !s.value && !s.iconOnly);
+
+  if (examples.length > 0) {
+    if (legacySamplesLine) throw new Error(`${fileName}:${legacySamplesLine}: slot "samples:" next to "example" blocks — move the texts into the examples`);
+    for (const ex of examples) {
+      const at = (key: string) => `${fileName}:${ex.keyLines[key] ?? ex.line}`;
+      const filled = Object.keys(ex.texts) as SlotId[];
+      if (filled.length === 0) throw new Error(`${fileName}:${ex.line}: example without slot texts`);
+      for (const slotId of filled) {
+        const slot = byId.get(slotId);
+        if (!slot) throw new Error(`${at(slotId)}: example fills slot "${slotId}", which the purpose does not declare`);
+        if (slot.value) throw new Error(`${at(slotId)}: slot "${slotId}" has a fixed value and takes no example text`);
+        const text = ex.texts[slotId]!;
+        if (text.split('\n').some(l => SAMPLE_WINDOW_MARKER.test(l))) throw new Error(`${at(slotId)}: window marker in example text — use "when:" on the example`);
+        if (slot.slotType === 'list') {
+          for (const item of text.split('\n')) {
+            const { icon } = parseListItem(item);
+            if (icon && slot.marker !== 'icon') throw new Error(`${at(slotId)}: slot "${slotId}": item "${item}" names an icon, but the list has no "marker: icon"`);
+          }
+        }
+      }
+    }
+    for (const slot of contentSlots) {
+      if (!examples.some(ex => ex.texts[slot.id])) throw new Error(`${fileName}: slot "${slot.id}" is filled by no example`);
+    }
+    return examples.map(({ line: _line, keyLines: _keyLines, ...ex }) => ex);
+  }
+
+  for (const slot of contentSlots) {
+    if (slot.samples.length === 0) throw new Error(`${fileName}: slot "${slot.id}" has no text — add "example" blocks or a "value:"`);
+  }
+  if (!legacySamplesLine) return [];
+  warnings.push(`${fileName}:${legacySamplesLine}: deprecated slot "samples:" — write whole pages as "example" blocks`);
+  const sampled = slots.filter(s => !s.value && s.samples.length > 0);
+  const count = Math.max(...sampled.map(s => s.samples.length));
+  return Array.from({ length: count }, (_, i) => {
+    const texts: Partial<Record<SlotId, string>> = {};
+    let when: string | undefined;
+    for (const slot of sampled) {
+      const idx = i % slot.samples.length;
+      texts[slot.id] = slot.samples[idx];
+      when ??= slot.sampleWindows?.[idx];
+    }
+    return { texts, ...(when ? { when } : {}), legacy: true };
+  });
 }

package/skills/brand-intent.md

@@ -38,11 +38,19 @@ Identity → Brand → Format → Purpose → Composition
 
 **Required:** essence, promise, voice (register, persona, rhythm, always/never), pillars, audience segments.
 
-**Optional:** tagline, positioning, mission, vision, archetype, narrative, values (with behavior statements), anti-audience segments.
+**Optional:** tagline, positioning, mission, vision, archetype, narrative, values (with behavior statements and `say:`/`not:` examples), anti-audience segments, imagery, image-theme, goal, review.
 
 **The `always`/`never` construct is your primary guardrail.** These are concrete, testable rules. When generating or reviewing content, check every item in `never:` and confirm every item in `always:`. They are not suggestions; they are constraints.
 
-**`values`** are not just keywords; each has a behavior statement that describes how it manifests. Use these to inform decisions when voice rules don't cover a situation.
+**`voice.instead`** pairs a phrase to avoid with the brand's own wording. When a draft contains the phrase, use the replacement as the model for the rewrite.
+
+**`values`** are not just keywords; each has a behavior statement that describes how it manifests. Use these to inform decisions when voice rules don't cover a situation. `say:` lines are examples to match in tone, `not:` lines are the tone to avoid.
+
+**`imagery`** is the image counterpart of `voice`: `always`/`never` rules for photos and film. Apply them when reviewing a photo or writing an image brief or prompt. **`image-theme`** blocks name subjects for photos and film, some tied to a narrative.
+
+**`goal`** says what a piece of content is for, independent of its format. A purpose names a default goal with `goal:`. Follow the goal's `always`/`never` rules and answer its `question`. `share:` is a planning target, not a rule for a single piece.
+
+**`review`** lists yes/no questions to check before publishing: `copy` for texts, `image` for photos and film.
 
 **`anti-audience`** segments define who the brand is explicitly *not* for. Never generate content that sounds like it's addressing an anti-audience. This is as important as `voice.never`.
 
@@ -92,11 +100,11 @@ When generating content for a specific purpose, read all layers silently (do not
 
 ### Reading layers (internal, not shown to user):
 
-1. **Read `.identity`** — voice.always/never (hard constraints), persona, register, pillars.avoid, anti-audience, values, positioning
+1. **Read `.identity`** — voice.always/never/instead (hard constraints), persona, register, pillars.avoid, anti-audience, values and their examples, positioning; the goal named by the purpose
 2. **Read `.brand`** — voice-constraints: sentence-max, headline-pattern, number-format, register
 3. **Apply `scope` from `.purpose`** — audience and pillar filters narrow the upstream context
 4. **Apply `context` from `.purpose`** — slot-specific instructions, follow literally
-5. **Generate per-slot content** — respect maxLength, use samples as structural reference (match pattern, not words), follow context instructions
+5. **Generate per-slot content** — respect maxLength and any `words:`/`sentences:` range, use the purpose's `example` pages as structural reference (match pattern, not words; all slots of one output share one topic), follow context instructions
 
 ### Output format:
 
@@ -117,7 +125,13 @@ After generating or reviewing content, validate against these rules in order:
 6. **`sentence-max`:** Count words in every sentence. Does any exceed the limit? If yes, split.
 7. **`headline-pattern`:** Does the headline follow the specified pattern? If not, restructure.
 8. **`maxLength`:** Does each slot's content fit within its character limit? If not, shorten.
-9. **`register`:** Does the formality level match? (e.g., if `informal, Du`, no formal address)
+9. **`words:` / `sentences:`:** Is each slot within its editorial range, where one is set? If not, adjust.
+10. **`register`:** Does the formality level match? (e.g., if `informal, Du`, no formal address)
+11. **`voice.instead`:** Does the text contain a phrase from the instead list? If yes, rewrite along the replacement.
+12. **`goal`:** Where a goal applies, does the text follow its rules and answer its question?
+13. **`review.copy`:** Answer each question with yes or no. Any no is a failure.
+
+When reviewing a photo, check `imagery.always`/`never`, the brand's framing (horizon position) and each `review.image` question.
 
 ## What NOT to Do
 
@@ -238,7 +252,7 @@ Read the files and walk the user through them:
 - **`krume.identity`** — the strategic layer: essence, voice, values, audiences. Start here.
 - **`krume.brand`** — derived expression: colors, themes, typography, spacing. Every decision traces back to identity.
 - **`formats/`** — canvas dimensions, safe zones, grid. Where content appears.
-- **`purposes/`** — content type with semantic slots, samples, constraints. What content does.
+- **`purposes/`** — content type with semantic slots, constraints, and example pages. What content does.
 - **`compositions/`** — spatial arrangement of slots. How elements are placed.
 
 If `examples/krume/` doesn't exist, tell the user to run `npx brand-intent init` first.

package/skills/brief.md

@@ -39,7 +39,9 @@ The brief is a snapshot. Regenerate it after any change to `.identity`, `.brand`
 6. **Auto-derive the Guardrails section** from `.identity`:
    - every item in `voice.never`
    - every item in `voice.always`
+   - every `voice.instead` pair
    - `pillars.avoid` list
+   - every item in `imagery.never` and `imagery.always`
    - every `anti-audience` block (label + description)
 
    The Guardrails *section in the brief* is derived. Never add a `guardrails:` block to the DSL — guardrails live inside `.identity` already.
@@ -93,6 +95,26 @@ _Role: how this brand sounds._
 _Role: behavior statements, not keywords._
 
 - **{name}** — {behavior}
+  - Say: {each say: line}
+  - Not: {each not: line}
+
+## Imagery (optional)
+_Role: what photos and film show. Only emitted if `imagery` or `image-theme` is present._
+
+- **Image themes:** for each — **{name}** ({narrative, if set}) — {text}
+
+## Goals (optional)
+_Role: what a piece of content is for, independent of its format. Only emitted if `goal` blocks are present._
+
+- **{label}** ({share, if set}) — {question}
+  - Narratives: {narratives}
+  - Always: {each always item} · Never: {each never item}
+
+## Review (optional)
+_Role: yes/no questions before publishing. Only emitted if `review` is present._
+
+- **Copy:** {each review.copy question}
+- **Image:** {each review.image question}
 
 ## Content Pillars
 _Role: what the brand talks about, and what it avoids._
@@ -132,6 +154,12 @@ _Role: hard rules any generator, agent, or reviewer must enforce._
 **Always:**
 - {each voice.always item}
 
+**Instead:**
+- "{avoid}" → {use}
+
+**Imagery never / always:**
+- {each imagery.never item} / {each imagery.always item}
+
 **Avoid topics:**
 - {each pillars.avoid item}
 
@@ -151,7 +179,9 @@ For each purpose, emit **glossed** tags — not verbatim DSL values:
   - **Logo:** gloss — `text` = "wordmark (text logo)"; `mark` = "graphic mark"; other values pass through verbatim.
   - Scope: {scope audience + pillars}
   - Context: {context prose per slot}
-  - Slots: for each slot — id, typography, maxLength, samples. Omit `color:` references (theme-internal detail). Override hints (`hyphenate`, `textAlign`) pass through as-is.
+  - Goal: {goal label}, if set
+  - Examples: each `example` block as one page — topic (if set), then slot texts. For files with deprecated slot `samples:`, list them per slot and note that they are not paired.
+  - Slots: for each slot — id, typography, maxLength, words/sentences range if set. Omit `color:` references (theme-internal detail). Override hints (`hyphenate`, `textAlign`) pass through as-is.
 
 ## Formats (optional)
 _Role: where content appears. Only emitted if any `.format` files are present._

package/vscode-extension/syntaxes/brand.tmLanguage.json

@@ -451,7 +451,7 @@
       }
     },
     "asset-value": {
-      "match": "^(\\s{2,})(label|src|lottie|gltf|generator|group)(:\\s*)(.*)|^(\\s{2,})(aspect|scale)(:\\s*)(\\S+)|^(\\s{2,})(animated|generator-params|align-left|align-center|align-right)\\s*$|^(\\s{2,})(loop)(?:(:\\s*)(true|false))?\\s*$",
+      "match": "^(\\s{2,})(label|src|lottie|gltf|generator|group|when|framing|place|person|taken|description|caption|goals)(:\\s*)(.*)|^(\\s{2,})(aspect|scale)(:\\s*)(\\S+)|^(\\s{2,})(animated|generator-params|align-left|align-center|align-right)\\s*$|^(\\s{2,})(loop)(?:(:\\s*)(true|false))?\\s*$",
       "captures": {
         "2": { "name": "support.type.property-name.brand-intent-brand" },
         "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },

package/vscode-extension/syntaxes/identity.tmLanguage.json

@@ -25,16 +25,16 @@
       }
     },
     "named-block": {
-      "comment": "Block headers: voice, pillars, values, narrative NAME, audience NAME, anti-audience NAME",
+      "comment": "Block headers: voice, pillars, values, imagery, review, narrative NAME, audience NAME, anti-audience NAME, image-theme NAME, goal NAME",
       "patterns": [
         {
-          "match": "^(voice|pillars|values)\\s*$",
+          "match": "^(voice|pillars|values|imagery|review)\\s*$",
           "captures": {
             "1": { "name": "keyword.control.brand-intent-identity" }
           }
         },
         {
-          "match": "^(narrative|audience|anti-audience)\\s+(\\S.*)",
+          "match": "^(narrative|audience|anti-audience|image-theme|goal)\\s+(\\S.*)",
           "captures": {
             "1": { "name": "keyword.control.brand-intent-identity" },
             "2": { "name": "entity.name.type.brand-intent-identity" }
@@ -43,7 +43,7 @@
       ]
     },
     "indented-property": {
-      "match": "^(\\s{2,})(register|persona|rhythm|always|never|primary|secondary|avoid|label|profile|motivation|language|description)(:)\\s+(.*)",
+      "match": "^(\\s{2,})(register|persona|rhythm|always|never|instead|primary|secondary|avoid|label|profile|motivation|language|description|say|not|narrative|share|question|narratives|copy|image)(:)\\s+(.*)",
       "captures": {
         "2": { "name": "support.type.property-name.brand-intent-identity" },
         "3": { "name": "punctuation.separator.key-value.brand-intent-identity" },

package/vscode-extension/syntaxes/purpose.tmLanguage.json

@@ -19,6 +19,7 @@
     { "include": "#bg-prompt-field" },
     { "include": "#context-header" },
     { "include": "#slot-header" },
+    { "include": "#example-header" },
     { "include": "#override-header" },
     { "include": "#override-value" },
     { "include": "#list-property" },
@@ -123,7 +124,7 @@
       }
     },
     "framing-field": {
-      "match": "^(framing:)\\s+([\\w-]+)",
+      "match": "^(framing:|goal:)\\s+([\\w-]+)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-purpose" },
         "2": { "name": "entity.name.type.brand-intent-purpose" }
@@ -156,6 +157,12 @@
         "2": { "name": "entity.name.tag.brand-intent-purpose" }
       }
     },
+    "example-header": {
+      "match": "^(example)\\s*$",
+      "captures": {
+        "1": { "name": "keyword.control.brand-intent-purpose" }
+      }
+    },
     "override-header": {
       "match": "^\\s+(override:)\\s*$",
       "captures": {
@@ -216,7 +223,7 @@
       ]
     },
     "property": {
-      "match": "^\\s+(label|samples|value|maxLength|font|size|opsz|lineHeight|letterSpacing|align|typography|color|type|editable)(:)\\s+(.*)",
+      "match": "^\\s+(label|samples|value|maxLength|words|sentences|font|size|opsz|lineHeight|letterSpacing|align|typography|color|type|editable|topic|goal|when|primary|secondary|detail|meta|cta)(:)\\s+(.*)",
       "captures": {
         "1": { "name": "support.type.property-name.brand-intent-purpose" },
         "2": { "name": "punctuation.separator.brand-intent-purpose" },
@@ -241,8 +248,8 @@
       }
     },
     "sample-icon-continuation": {
-      "comment": "[ID] icon prefix on list item continuation lines",
-      "match": "^(\\s{6,})(\\[[^\\]]+\\])",
+      "comment": "[ID] icon prefix on list items (example blocks, legacy sample continuation lines)",
+      "match": "^(\\s{4,})(\\[[^\\]]+\\])",
       "captures": {
         "2": { "name": "entity.name.function.brand-intent-purpose" }
       }
@@ -258,13 +265,13 @@
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
       "patterns": [
         {
-          "match": "^(id:|name:|compositions:|density:|defaultIcon:|scope|voice|palette:|logo:|photo:|video:|camera:|framing:|analyze:|bg-prompt:|context|slot)(?=\\s|$)",
+          "match": "^(id:|name:|compositions:|density:|defaultIcon:|scope|voice|palette:|logo:|photo:|video:|camera:|framing:|goal:|analyze:|bg-prompt:|context|slot|example)(?=\\s|$)",
           "captures": {
             "1": { "name": "keyword.control.brand-intent-purpose" }
           }
         },
         {
-          "match": "^\\s+(label|samples|value|maxLength|font|size|opsz|lineHeight|letterSpacing|align|typography|color|type|override|audience|pillars|editable)(?=:|\\s|$)",
+          "match": "^\\s+(label|samples|value|maxLength|words|sentences|font|size|opsz|lineHeight|letterSpacing|align|typography|color|type|override|audience|pillars|editable|topic|goal|when|primary|secondary|detail|meta|cta)(?=:|\\s|$)",
           "captures": {
             "1": { "name": "support.type.property-name.brand-intent-purpose" }
           }