brand-intent 0.20.2 → 0.22.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
@@ -35,10 +35,13 @@
   ],
   "scripts": {
     "release": "./scripts/release.sh",
+    "typecheck": "tsc -p .",
     "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.test.ts && tsx tests/colorSystem.test.ts && tsx tests/icons.test.ts && tsx tests/purposeParser.test.ts && tsx tests/realBrands.test.ts"
   },
   "devDependencies": {
-    "tsx": "^4.19.0"
+    "@types/node": "^26.6.5",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.3"
   },
   "files": [
     "cli/",

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';
@@ -1658,8 +1670,9 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     });
   }
 
-  // Counter colours default to the label badge's.
+  // Counter colours default to the label badge's, headline to text-primary.
   for (const theme of Object.values(themes)) {
+    if (theme['headline'] === undefined && theme['text-primary'] !== undefined) theme['headline'] = theme['text-primary'];
     if (theme['counter-bg'] === undefined && theme['label-bg'] !== undefined) theme['counter-bg'] = theme['label-bg'];
     if (theme['counter-fg'] === undefined && theme['label-fg'] !== undefined) theme['counter-fg'] = theme['label-fg'];
   }
@@ -1783,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)) {
@@ -1813,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) {
@@ -1986,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}"`);
@@ -2002,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/colorSystem.ts

@@ -101,6 +101,7 @@ export function derivePairSlots(ground: string, figure: string, text: string): R
   const slots: Record<string, string> = {
     'background': ground,
     'text-primary': text,
+    'headline': text,
   };
   for (const [slot, alpha] of TEXT_TIERS) slots[slot] = withAlpha(text, alpha);
   for (const slot of ['logo', 'cta', 'divider', 'icon', 'illustration', 'sticker-bg', 'label-bg', 'counter-bg']) {

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, CountRange, Density, ListMarker } from './purposeParser';
 
 export { parseCompositionFile } from './compositionParser';
 export type {

package/parser/purposeParser.ts

@@ -43,6 +43,8 @@ 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). */
@@ -62,6 +64,10 @@ export interface ParsedPurposeSlot {
   /** Fixed value — when set, this slot is never AI-generated or shuffled. Mutually exclusive with samples. */
   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 +115,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,6 +154,7 @@ 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;
@@ -349,6 +362,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';
@@ -597,6 +616,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;
@@ -682,5 +710,5 @@ 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 };
+  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, cameraFacing, framing, goal, analyze, defaultIcon, bgPrompt };
 }

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 samples as structural reference (match pattern, not words), 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
 

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,8 @@ 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
+  - Slots: for each slot — id, typography, maxLength, words/sentences range if set, samples. 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

@@ -123,7 +123,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" }
@@ -216,7 +216,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)(:)\\s+(.*)",
       "captures": {
         "1": { "name": "support.type.property-name.brand-intent-purpose" },
         "2": { "name": "punctuation.separator.brand-intent-purpose" },
@@ -258,13 +258,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)(?=\\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)(?=:|\\s|$)",
           "captures": {
             "1": { "name": "support.type.property-name.brand-intent-purpose" }
           }