brand-intent 0.6.0 → 0.8.0

package/README.md

@@ -34,12 +34,21 @@ ext install studiostoll.brand-intent-lang
 
 ### 2. Run init
 
-Installs the Brand Intent skill for your AI agent. The skill handles everything else: onboard your brand through a guided interview, explore the Krume bakery reference, generate and validate on-brand content.
+Installs two skills into your AI agent: `/brand-intent` and `/brief`. Together they cover the full loop. Onboard your brand, explore the Krume bakery reference, generate and validate on-brand content, and export a portable brief.
 
 ```bash
 npx brand-intent init
 ```
 
+### 3. Use your brand
+
+Two skills are now installed in your AI agent.
+
+- **`/brand-intent`** authors, validates, and generates on-brand content from your Brand Intent files.
+- **`/brief`** exports a portable `{brand-id}-brief.md`. Use it to hand the brand to a tool that doesn't read Brand Intent directly, like a Claude Design project, another LLM, or a collaborator.
+
+Edit your Brand Intent files whenever strategy or expression evolves. Regenerate briefs after any change.
+
 ## Documentation
 
 - [Specification](SPEC.md): formal grammar for all five file types

package/cli/index.mjs

@@ -9,7 +9,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_ROOT = resolve(__dirname, '..');
 
-const SKILL_FILE = join(PKG_ROOT, 'skills', 'brand-intent.md');
+const SKILL_FILES = ['brand-intent.md', 'brief.md'];
 
 // ── Harness detection ──
 
@@ -69,12 +69,15 @@ function scaffoldExample(targetDir) {
 // ── Install skill ──
 
 async function installSkills(cwd) {
-  if (!existsSync(SKILL_FILE)) {
-    console.error('Error: skill file not found at', SKILL_FILE);
-    process.exit(1);
-  }
+  const skills = SKILL_FILES.map(name => {
+    const path = join(PKG_ROOT, 'skills', name);
+    if (!existsSync(path)) {
+      console.error('Error: skill file not found at', path);
+      process.exit(1);
+    }
+    return { name, content: readFileSync(path, 'utf-8') };
+  });
 
-  const skill = readFileSync(SKILL_FILE, 'utf-8');
   let harnesses = detectHarnesses(cwd);
 
   if (harnesses.length === 0) {
@@ -98,9 +101,11 @@ async function installSkills(cwd) {
   for (const { label, dir } of harnesses) {
     const target = join(cwd, dir);
     mkdirSync(target, { recursive: true });
-    const dest = join(target, 'brand-intent.md');
-    writeFileSync(dest, skill, 'utf-8');
-    console.log(`  \u2713 ${label} \u2014 ${dir}/brand-intent.md`);
+    for (const { name, content } of skills) {
+      const dest = join(target, name);
+      writeFileSync(dest, content, 'utf-8');
+      console.log(`  ✓ ${label} — ${dir}/${name}`);
+    }
   }
 
   return harnesses;
@@ -121,7 +126,7 @@ if (command && command !== 'init' && command !== 'install-skills' && command !==
 
 if (!command || command === '--help' || command === '-h') {
   console.log('Usage:');
-  console.log('  brand-intent init              Install the Brand Intent skill for your AI agent');
+  console.log('  brand-intent init              Install the Brand Intent and Brief skills for your AI agent');
   console.log('  brand-intent install-skills     Same as init (alias)');
   console.log('');
   console.log('Example:');
@@ -138,7 +143,7 @@ if (targetDir !== cwd) {
 }
 console.log('\n  This will:');
 console.log('  \u2014 Copy the Krume bakery reference into examples/krume/');
-console.log('  \u2014 Install the Brand Intent skill for your AI agent\n');
+console.log('  \u2014 Install the Brand Intent and Brief skills for your AI agent\n');
 const proceed = await ask('  Proceed? (Y/n) ');
 if (proceed.trim().toLowerCase() === 'n') {
   closeRl();
@@ -158,4 +163,5 @@ console.log('    /brand-intent onboard     Create your brand through a guided in
 console.log('    /brand-intent example     Scaffold the Krume reference implementation');
 console.log('    /brand-intent validate    Validate content against your brand rules');
 console.log('    /brand-intent             Discover brand files and available purposes');
+console.log('    /brief                    Generate a portable brand brief');
 console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
@@ -33,7 +33,11 @@
     "design-system"
   ],
   "scripts": {
-    "release": "./scripts/release.sh"
+    "release": "./scripts/release.sh",
+    "test": "tsx tests/brandParser.test.ts && tsx tests/realBrands.test.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0"
   },
   "files": [
     "cli/",

package/parser/brandParser.ts

@@ -6,6 +6,19 @@
  * handles expression-layer primitives only (colors, typography, dividers, assets, badge styles).
  */
 
+import type {
+  BrandColorGroup,
+  BrandColorEntry,
+  ColorMode,
+  PaletteStrategy,
+  Adherence,
+  AdherenceTolerances,
+  ColorBounds,
+  StateColors,
+  GroupKey,
+  NeutralRole,
+} from './types';
+
 // ── Parsed type ────────────────────────────────────────────────────────────────
 
 export interface ParsedBrand {
@@ -31,10 +44,26 @@ export interface ParsedBrand {
   favicon?: string;
   /** Path to OG image asset (relative to /public), used for social sharing previews */
   ogImage?: string;
-  /** Core brand color primitives: name → hex (e.g. primary, secondary, accent1, accent2, white) */
+  /** Core brand color primitives: name → hex (e.g. primary, secondary, accent1, accent2, white).
+   *  Always present when any colors are declared — grouped-syntax brands get a flat projection
+   *  generated from all entries, so legacy consumers keep working unchanged. */
   brandColors?: Record<string, string>;
   /** Structured print specs per brand color: name → {pantone?, hks?, cmyk?} */
   brandColorPrint?: Record<string, BrandColorPrintSpec>;
+  /** Grouped-syntax representation (v0.8.0+). Present only when the `brand-colors` block uses the grouped form. */
+  colorGroups?: BrandColorGroup[];
+  /** Per-brand fixed state colors (problem/warning/success/info/inactive). */
+  stateColors?: StateColors;
+  /** Bounds for guided derivation (luminance + saturation floor). */
+  colorBounds?: ColorBounds;
+  /** Color resolution mode. Defaults behave as `static` when absent. */
+  colorMode?: ColorMode;
+  /** Palette strategy default for Path A (guided shuffle). Optional. */
+  colorStrategy?: PaletteStrategy;
+  /** Adherence level for guided derivation. Optional — engine-side default per level. */
+  colorAdherence?: Adherence;
+  /** Per-brand tolerance overrides for the declared adherence level. */
+  colorAdherenceOverrides?: AdherenceTolerances;
   /** Inline themes: theme name → slot name → resolved hex color (only when tokensSource === 'inline') */
   themes?: Record<string, Record<string, string>>;
   /** Print annotations from inline # comments: slot name → annotation text */
@@ -131,6 +160,13 @@ export interface ParsedDividerDef {
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
 
+const GROUP_KEYWORDS = new Set<string>(['primary', 'secondary', 'accent', 'neutral']);
+const NEUTRAL_ROLES = new Set<NeutralRole>(['light', 'subtle', 'mid', 'muted', 'dark']);
+const STATE_KEYS = new Set<string>(['problem', 'warning', 'success', 'info', 'inactive']);
+const VALID_COLOR_MODES = new Set<ColorMode>(['static', 'dynamic', 'guided']);
+const VALID_STRATEGIES = new Set<PaletteStrategy>(['monochrome', 'duotone', 'tricolor', 'spectrum']);
+const VALID_ADHERENCES = new Set<Adherence>(['strict', 'on-brand', 'flexible']);
+
 /**
  * Expand a 3-digit hex to 6-digit. Pass-through for 6 or 8-digit.
  * Returns null for invalid input.
@@ -244,7 +280,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta';
+  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -253,6 +289,18 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const brandColors: Record<string, string> = {};
   const brandColorPrint: Record<string, BrandColorPrintSpec> = {};
   let currentBrandColorName = '';
+
+  // Grouped brand-colors state (v0.8.0+).
+  // Shape is detected lazily: when the first non-blank indented line inside `brand-colors`
+  // is a bare group keyword, the block switches to grouped mode. Otherwise it stays flat.
+  type GroupedShape = 'unknown' | 'flat' | 'grouped';
+  let brandColorsShape: GroupedShape = 'unknown';
+  const colorGroups: BrandColorGroup[] = [];
+  let currentGroup: BrandColorGroup | null = null;
+  let currentGroupedEntry: BrandColorEntry | null = null;
+  const stateColorsRaw: Record<string, string> = {};
+  const colorBoundsRaw: Record<string, string> = {};
+  const adherenceOverridesRaw: Record<string, string> = {};
   const themes: Record<string, Record<string, string>> = {};
   const themeDescriptions: Record<string, string> = {};
   const spacingRaw: Record<string, string> = {};
@@ -282,7 +330,123 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (isIndented) {
       if (activeBlock === 'brand-colors') {
         const trimmed = raw.trimStart();
+        if (trimmed === '') continue;
         const indentLen = raw.length - trimmed.length;
+
+        // Shape detection: first non-blank indented line decides.
+        // Grouped = bare group keyword (`primary`/`secondary`/`accent`/`neutral`) at 2-space indent.
+        // Flat    = `key: value` at 2-space indent.
+        if (brandColorsShape === 'unknown') {
+          if (GROUP_KEYWORDS.has(trimmed) && indentLen <= 2) {
+            brandColorsShape = 'grouped';
+          } else {
+            brandColorsShape = 'flat';
+          }
+        }
+
+        if (brandColorsShape === 'grouped') {
+          // ── Grouped shape ────────────────────────────────────────────────
+          const groupKwMatch = GROUP_KEYWORDS.has(trimmed) && indentLen <= 2;
+          if (groupKwMatch) {
+            const key = trimmed as GroupKey;
+            if (colorGroups.some(g => g.key === key)) {
+              throw new Error(`${fileName}:${lineNum}: duplicate color group "${key}"`);
+            }
+            currentGroup = { key, entries: [] };
+            colorGroups.push(currentGroup);
+            currentGroupedEntry = null;
+            continue;
+          }
+          if (!currentGroup) {
+            throw new Error(
+              `${fileName}:${lineNum}: grouped brand-colors entries must appear inside a group block (primary/secondary/accent/neutral)`,
+            );
+          }
+          // Group-level properties at 4-space indent OR color-entry header / sub-properties.
+          // We distinguish by: entry header = starts with `#` or `$`.
+          if (trimmed.startsWith('#') || trimmed.startsWith('$')) {
+            // New entry. Header forms:
+            //   "#HEX  Display Name"
+            //   "$group.role"
+            if (trimmed.startsWith('#')) {
+              // Split header: "#HEX  Name" — hex then whitespace then name
+              const headerMatch = trimmed.match(/^(#[0-9a-fA-F]{3,8})(?:\s+(.+))?$/);
+              if (!headerMatch) {
+                throw new Error(
+                  `${fileName}:${lineNum}: expected "#HEX  Name" entry header, got "${trimmed}"`,
+                );
+              }
+              const hex = normalizeHex(headerMatch[1]);
+              if (!hex) {
+                throw new Error(
+                  `${fileName}:${lineNum}: invalid hex "${headerMatch[1]}"`,
+                );
+              }
+              const name = (headerMatch[2] ?? '').trim();
+              if (!name) {
+                throw new Error(
+                  `${fileName}:${lineNum}: color entry needs a display name after the hex`,
+                );
+              }
+              currentGroupedEntry = { hex, name };
+              currentGroup.entries.push(currentGroupedEntry);
+            } else {
+              // $group.role reference — resolved in finalisation pass.
+              const refMatch = trimmed.match(/^\$([a-z]+)\.([a-z-]+)$/i);
+              if (!refMatch) {
+                throw new Error(
+                  `${fileName}:${lineNum}: expected "$group.role" reference, got "${trimmed}"`,
+                );
+              }
+              currentGroupedEntry = {
+                hex: '',
+                name: '',
+                referencedFrom: `${refMatch[1]}.${refMatch[2]}`,
+              };
+              currentGroup.entries.push(currentGroupedEntry);
+            }
+            continue;
+          }
+          // `key: value` line — either group property (indent ≤ 4) or entry sub-property.
+          const colonIdx = trimmed.indexOf(':');
+          if (colonIdx === -1) continue;
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          // Group property lives at indent 4 and only appears before the first entry.
+          if (indentLen <= 4 && !currentGroupedEntry) {
+            if (key === 'meaning') {
+              currentGroup.meaning = value;
+            } else if (key === 'distribution') {
+              if (currentGroup.key === 'neutral') {
+                throw new Error(
+                  `${fileName}:${lineNum}: neutral group cannot declare distribution — it's the scale, not a selection target`,
+                );
+              }
+              const pct = parseFloat(value.replace(/%$/, ''));
+              if (isNaN(pct)) {
+                throw new Error(
+                  `${fileName}:${lineNum}: distribution "${value}" is not a number`,
+                );
+              }
+              currentGroup.distribution = pct;
+            }
+            continue;
+          }
+          // Entry sub-property.
+          if (!currentGroupedEntry) continue;
+          if (key === 'role') {
+            currentGroupedEntry.role = value;
+            if (value === 'default') currentGroupedEntry.isDefault = true;
+          } else if (key === 'meaning') {
+            currentGroupedEntry.meaning = value;
+          } else if (key === 'pantone' || key === 'hks' || key === 'cmyk') {
+            if (!currentGroupedEntry.print) currentGroupedEntry.print = {};
+            currentGroupedEntry.print[key] = value;
+          }
+          continue;
+        }
+
+        // ── Flat shape (legacy) ────────────────────────────────────────────
         const colonIdx = trimmed.indexOf(':');
         if (colonIdx !== -1) {
           const key = trimmed.slice(0, colonIdx).trim();
@@ -308,6 +472,36 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         continue;
       }
+      if (activeBlock === 'state-colors') {
+        const trimmed = raw.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          stateColorsRaw[key] = value;
+        }
+        continue;
+      }
+      if (activeBlock === 'color-bounds') {
+        const trimmed = raw.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          colorBoundsRaw[key] = value;
+        }
+        continue;
+      }
+      if (activeBlock === 'color-adherence') {
+        const trimmed = raw.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          adherenceOverridesRaw[key] = value;
+        }
+        continue;
+      }
       if (activeBlock === 'theme' && currentThemeName) {
         // slot: #HEX or $ref  # optional comment
         const colonIdx = raw.indexOf(':');
@@ -406,14 +600,30 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
-    // Non-indented line ends any active block
-    activeBlock = 'none';
-
+    // Blank lines are ignored — they don't close active blocks (grouped brand-colors
+    // relies on blank lines between groups for readability).
     if (raw.trim() === '') continue;
 
+    // Non-indented non-blank line ends any active block
+    activeBlock = 'none';
+
     // brand-colors — starts the brand color primitives block
     if (raw.trim() === 'brand-colors') {
       activeBlock = 'brand-colors';
+      currentGroup = null;
+      currentGroupedEntry = null;
+      continue;
+    }
+
+    // state-colors — flat block of problem/warning/success/info/inactive
+    if (raw.trim() === 'state-colors') {
+      activeBlock = 'state-colors';
+      continue;
+    }
+
+    // color-bounds — luminance + saturation floor for guided derivation
+    if (raw.trim() === 'color-bounds') {
+      activeBlock = 'color-bounds';
       continue;
     }
 
@@ -496,18 +706,178 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       case 'cta':
         activeBlock = 'cta';
         break;
+      case 'color-mode':
+        if (!VALID_COLOR_MODES.has(value as ColorMode)) {
+          throw new Error(`${fileName}:${lineNum}: color-mode must be "static", "dynamic", or "guided", got "${value}"`);
+        }
+        result.colorMode = value as ColorMode;
+        break;
+      case 'color-strategy':
+        if (!VALID_STRATEGIES.has(value as PaletteStrategy)) {
+          throw new Error(`${fileName}:${lineNum}: color-strategy must be one of monochrome/duotone/tricolor/spectrum, got "${value}"`);
+        }
+        result.colorStrategy = value as PaletteStrategy;
+        break;
+      case 'color-adherence':
+        if (!VALID_ADHERENCES.has(value as Adherence)) {
+          throw new Error(`${fileName}:${lineNum}: color-adherence must be "strict", "on-brand", or "flexible", got "${value}"`);
+        }
+        result.colorAdherence = value as Adherence;
+        // Optional indented overrides follow.
+        activeBlock = 'color-adherence';
+        break;
       default:
         // Unknown keys silently ignored for forward compatibility
         break;
     }
   }
 
-  // Store brand colors
+  // ── Finalise grouped brand-colors (v0.8.0+) ────────────────────────────────
+  if (colorGroups.length > 0) {
+    // Resolve $group.role references in declaration order — a reference may only point
+    // to a group earlier in the list than its containing group.
+    const resolvedNames = new Set<string>();
+    for (let gi = 0; gi < colorGroups.length; gi++) {
+      const group = colorGroups[gi];
+      for (const entry of group.entries) {
+        if (!entry.referencedFrom) {
+          // Normal entry — ensure its name doesn't collide (important for flat projection).
+          if (resolvedNames.has(entry.name)) {
+            throw new Error(`${fileName}: duplicate color name "${entry.name}" in brand-colors`);
+          }
+          resolvedNames.add(entry.name);
+          continue;
+        }
+        // Reference shape: "<group>.<role>"
+        const [refGroupKey, refRole] = entry.referencedFrom.split('.');
+        const refGroupIdx = colorGroups.findIndex(g => g.key === refGroupKey);
+        if (refGroupIdx === -1) {
+          throw new Error(`${fileName}: reference "$${entry.referencedFrom}" targets unknown group "${refGroupKey}"`);
+        }
+        if (refGroupIdx >= gi) {
+          throw new Error(`${fileName}: reference "$${entry.referencedFrom}" must point to a group declared earlier (forward/self references forbidden)`);
+        }
+        const refGroup = colorGroups[refGroupIdx];
+        // Find the target entry. `default` matches explicit or first-declared default.
+        let target: BrandColorEntry | undefined;
+        if (refRole === 'default') {
+          target = refGroup.entries.find(e => e.isDefault) ?? refGroup.entries[0];
+        } else {
+          target = refGroup.entries.find(e => e.role === refRole);
+        }
+        if (!target) {
+          throw new Error(`${fileName}: reference "$${entry.referencedFrom}" — no entry with role "${refRole}" in group "${refGroupKey}"`);
+        }
+        entry.hex = target.hex;
+        entry.name = target.name;
+        // Don't add referenced name to resolvedNames — it's already registered under the target.
+      }
+
+      // Apply default selection rule for identity groups.
+      if (group.key !== 'neutral' && group.entries.length > 0) {
+        const explicit = group.entries.find(e => e.isDefault);
+        if (!explicit) {
+          // First-declared wins implicitly.
+          group.entries[0].isDefault = true;
+        }
+      }
+
+      // Neutral-group role validation.
+      if (group.key === 'neutral') {
+        for (const entry of group.entries) {
+          if (entry.role && !NEUTRAL_ROLES.has(entry.role as NeutralRole)) {
+            throw new Error(
+              `${fileName}: neutral entry "${entry.name}" role "${entry.role}" is not in the fixed vocabulary (light | subtle | mid | muted | dark)`,
+            );
+          }
+        }
+      }
+    }
+
+    result.colorGroups = colorGroups;
+
+    // Build flat projection so legacy consumers keep working unchanged.
+    // Key convention: the entry's display name lowercased, spaces → hyphens.
+    // Name collisions already rejected above, so the projection is deterministic.
+    for (const group of colorGroups) {
+      for (const entry of group.entries) {
+        const key = entry.name.toLowerCase().replace(/\s+/g, '-');
+        if (!brandColors[key]) {
+          brandColors[key] = entry.hex;
+          if (entry.print) brandColorPrint[key] = entry.print;
+        }
+      }
+    }
+  }
+
+  // Store brand colors (flat projection)
   if (Object.keys(brandColors).length > 0) {
     result.brandColors = brandColors;
     if (Object.keys(brandColorPrint).length > 0) result.brandColorPrint = brandColorPrint;
   }
 
+  // ── Finalise state-colors / color-bounds / adherence overrides ────────────
+  if (Object.keys(stateColorsRaw).length > 0) {
+    const state: StateColors = {};
+    for (const [key, value] of Object.entries(stateColorsRaw)) {
+      if (!STATE_KEYS.has(key)) continue; // forward-compat: ignore unknown
+      const hex = normalizeHex(value);
+      if (!hex) {
+        throw new Error(`${fileName}: state-colors "${key}" value "${value}" is not a valid hex`);
+      }
+      (state as Record<string, string>)[key] = hex;
+    }
+    if (Object.keys(state).length > 0) result.stateColors = state;
+  }
+
+  if (Object.keys(colorBoundsRaw).length > 0) {
+    const bounds: ColorBounds = {};
+    if (colorBoundsRaw.light !== undefined) bounds.light = parseFloat(colorBoundsRaw.light);
+    if (colorBoundsRaw.dark !== undefined) bounds.dark = parseFloat(colorBoundsRaw.dark);
+    if (colorBoundsRaw['saturation-floor'] !== undefined) {
+      bounds.saturationFloor = parseFloat(colorBoundsRaw['saturation-floor']);
+    }
+    result.colorBounds = bounds;
+  }
+
+  if (Object.keys(adherenceOverridesRaw).length > 0) {
+    const overrides: AdherenceTolerances = {};
+    if (adherenceOverridesRaw['hue-tolerance'] !== undefined) {
+      overrides.hueTolerance = parseFloat(adherenceOverridesRaw['hue-tolerance']);
+    }
+    if (adherenceOverridesRaw['sat-tolerance'] !== undefined) {
+      overrides.satTolerance = parseFloat(adherenceOverridesRaw['sat-tolerance']);
+    }
+    if (Object.keys(overrides).length > 0) result.colorAdherenceOverrides = overrides;
+  }
+
+  // ── Minimum-structure validation for color-mode: guided ───────────────────
+  if (result.colorMode === 'guided') {
+    if (colorGroups.length === 0) {
+      throw new Error(
+        `${fileName}: color-mode: guided requires grouped brand-colors syntax — flat syntax is not sufficient. See the Minimum Structure section in the guided-colors spec.`,
+      );
+    }
+    const primary = colorGroups.find(g => g.key === 'primary');
+    const neutral = colorGroups.find(g => g.key === 'neutral');
+    if (!primary) {
+      throw new Error(`${fileName}: color-mode: guided requires a "primary" group`);
+    }
+    if (!neutral) {
+      throw new Error(`${fileName}: color-mode: guided requires a "neutral" group`);
+    }
+    const neutralRoles = new Set(neutral.entries.map(e => e.role).filter(Boolean));
+    if (!neutralRoles.has('light')) {
+      throw new Error(`${fileName}: color-mode: guided requires neutral group to declare at least role "light"`);
+    }
+    if (!neutralRoles.has('dark')) {
+      throw new Error(`${fileName}: color-mode: guided requires neutral group to declare at least role "dark"`);
+    }
+    if (primary.entries.length === 0) {
+      throw new Error(`${fileName}: color-mode: guided requires primary group to have at least one color`);
+    }
+  }
+
   // Finalise inline tokens — resolve $ref values against brandColors, apply optional alpha.
   //
   // Theme slot grammar:

package/parser/index.ts

@@ -7,6 +7,19 @@ export type { ParsedIdentity, ParsedVoice, ParsedPillars, ParsedAudience, Parsed
 
 export { parseBrandFile } from './brandParser';
 export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle } from './brandParser';
+export type {
+  ColorMode,
+  PaletteStrategy,
+  Adherence,
+  AdherenceTolerances,
+  ColorBounds,
+  StateColors,
+  GroupKey,
+  IdentityGroupKey,
+  NeutralRole,
+  BrandColorEntry,
+  BrandColorGroup,
+} from './types';
 
 export { parseFormatFile } from './formatParser';
 export type { ParsedFormat } from './formatParser';

package/parser/types.ts

@@ -15,3 +15,80 @@ export interface ZoneInsets {
 
 /** Text alignment options. */
 export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+
+// ── Guided colors (v0.8.0) ────────────────────────────────────────────────────
+
+/** Color resolution mode declared at the brand level. */
+export type ColorMode = 'static' | 'dynamic' | 'guided';
+
+/** Palette construction strategy for guided shuffle (Path A only). */
+export type PaletteStrategy = 'monochrome' | 'duotone' | 'tricolor' | 'spectrum';
+
+/** Adherence level — how tightly guided derivation follows brand groups. */
+export type Adherence = 'strict' | 'on-brand' | 'flexible';
+
+/** Optional per-brand tolerance overrides for the declared adherence level. */
+export interface AdherenceTolerances {
+  /** Hue drift tolerance in degrees. */
+  hueTolerance?: number;
+  /** Saturation variance tolerance in percentage points. */
+  satTolerance?: number;
+}
+
+/** Bounds for all guided derivation — brand scales, state variants, neutral interpolation. */
+export interface ColorBounds {
+  /** Max luminance for derived tints (0–1). Never brighter than this. */
+  light?: number;
+  /** Min luminance for derived shades (0–1). Never darker than this. */
+  dark?: number;
+  /** Min saturation (0–100) for derived colors — prevents washed-out grays. */
+  saturationFloor?: number;
+}
+
+/** Fixed per-brand state (problem / success / warning / info / inactive) colors. */
+export interface StateColors {
+  problem?: string;
+  warning?: string;
+  success?: string;
+  info?: string;
+  inactive?: string;
+}
+
+/** Identity group keys (neutral is structurally distinct). */
+export type IdentityGroupKey = 'primary' | 'secondary' | 'accent';
+/** All four group keys. */
+export type GroupKey = IdentityGroupKey | 'neutral';
+
+/** Fixed neutral-role vocabulary — ordered light → dark. */
+export type NeutralRole = 'light' | 'subtle' | 'mid' | 'muted' | 'dark';
+
+/** One entry within a brand color group. */
+export interface BrandColorEntry {
+  /** Resolved 6-digit hex (uppercase). */
+  hex: string;
+  /** Display name as authored (`#HEX  Name` → "Name"). Reference entries inherit the target's name. */
+  name: string;
+  /** Authored role (identity groups) or fixed neutral-role vocabulary (neutral group). */
+  role?: string;
+  /** Marks this entry as the group default. Only meaningful in identity groups. */
+  isDefault?: boolean;
+  /** Authored meaning string — human-facing only, engine ignores. */
+  meaning?: string;
+  /** When the entry was declared via a `$group.role` reference, the reference path (informational only). */
+  referencedFrom?: string;
+  /** Print specs authored on this entry (Pantone, HKS, CMYK). */
+  print?: { pantone?: string; hks?: string; cmyk?: string };
+}
+
+/** One color group within the `brand-colors` block. */
+export interface BrandColorGroup {
+  /** Group key — fixed vocabulary. */
+  key: GroupKey;
+  /** Authored meaning — human-facing only. */
+  meaning?: string;
+  /** Selection-probability weight (0–100). Invalid on neutral. */
+  distribution?: number;
+  /** Ordered entries as declared. */
+  entries: BrandColorEntry[];
+}
+

package/skills/brief.md

@@ -0,0 +1,197 @@
+---
+description: Generate a portable markdown brand brief from Brand Intent DSL files
+---
+
+# Brief
+
+**Scope:** `$ARGUMENTS`
+
+> If `$ARGUMENTS` is empty: auto-detect the active brand from the current working directory (see File Discovery in the Brand Intent skill) and generate its brief.
+> If `$ARGUMENTS` names a brand id (e.g. "krume", "studio-stoll"): locate that brand folder under the current working directory and generate its brief.
+> If no brand is found: tell the user to run `/brand-intent onboard` (or `npx brand-intent init` to scaffold the Krume example) and stop.
+
+You are generating a **portable brand brief** — a single markdown file, `{brand-id}-brief.md`, written at the brand root. The brief is format-agnostic: it can be dropped into any tool that doesn't read Brand Intent files directly — a Claude Design project, another LLM, a human collaborator.
+
+The brief is **derived**, not authored. Every value comes verbatim from the DSL files. You never rephrase, interpret, or invent.
+
+## When to Regenerate
+
+The brief is a snapshot. Regenerate it after any change to `.identity`, `.brand`, `.purpose`, `.format`, or `.composition` files. The header always stamps the generation timestamp and the Brand Intent DSL version so stale briefs are detectable.
+
+## Procedure
+
+1. **Resolve the brand root.** Find the folder containing both `{brand-id}.identity` and `{brand-id}.brand`. If either file is missing, stop and tell the user to run `/brand-intent onboard`.
+
+2. **Read the required files.**
+   - `{brand-id}.identity` — strategic layer
+   - `{brand-id}.brand` — derived expression layer
+
+3. **Read optional files if present.** Each becomes a labeled optional section in the brief. If absent, omit the section entirely — do not emit empty headers.
+   - `{brand-id}.purpose` at brand root (rare)
+   - any files under `purposes/` (multiple allowed)
+   - any files under `formats/`
+   - any files under `compositions/`
+
+4. **Read the Brand Intent DSL version.** Try resolving the installed `brand-intent` package's `package.json` version. If unreachable (the skill runs in a harness, not always inside the brand-intent repo), use `"unknown"`.
+
+5. **Compose the brief** per the template below. Extract values verbatim — never rephrase or interpret. If a field is absent in the DSL, omit its row; never invent.
+
+6. **Auto-derive the Guardrails section** from `.identity`:
+   - every item in `voice.never`
+   - every item in `voice.always`
+   - `pillars.avoid` list
+   - 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.
+
+7. **Write the file.** Output path: `{brand-root}/{brand-id}-brief.md`. If the file exists, confirm overwrite in one line before proceeding.
+
+8. **Report.** Print one line: `Wrote {path}. Regenerate after any DSL change.`
+
+## Output Template
+
+Write exactly this structure. Each section includes a one-line **role description** so the brief self-documents when pasted into any context.
+
+```markdown
+# {Brand Name} — Brand Brief
+
+> Portable brief derived from Brand Intent DSL files.
+> Brand Intent version: {version} · Generated: {ISO timestamp}
+> Source of truth lives in the DSL files. Regenerate after any DSL change.
+
+## Essence
+_Role: the irreducible truth of the brand._
+
+{identity.essence}
+
+## Promise
+_Role: what the brand commits to deliver._
+
+{identity.promise}
+
+## Positioning / Mission / Vision / Tagline / Archetype
+_Role: strategic frame. Only rows that exist in the identity are emitted._
+
+- **Positioning:** {...}
+- **Mission:** {...}
+- (etc. — skip any row whose field is absent)
+
+## Narratives
+_Role: the brand's stories. The primary narrative is the default story._
+
+- **{name}** (primary) — {text}
+- **{name}** — {text}
+
+## Voice
+_Role: how this brand sounds._
+
+- **Register:** {voice.register}
+- **Persona:** {voice.persona}
+- **Rhythm:** {voice.rhythm}
+
+## Values
+_Role: behavior statements, not keywords._
+
+- **{name}** — {behavior}
+
+## Content Pillars
+_Role: what the brand talks about, and what it avoids._
+
+- **Primary:** {pillars.primary}
+- **Secondary:** {pillars.secondary}
+- **Avoid:** {pillars.avoid}
+
+## Audiences
+_Role: who the brand speaks to._
+
+For each audience segment in `.identity`:
+
+- **{label}**
+  - Profile: {...}
+  - Motivation: {...}
+  - Language guidance: {...}
+
+## Expression (from .brand)
+_Role: derived expression conditions — the "how it looks and sounds" layer, not expression itself._
+
+- **Language / locale:** {brand.language} / {brand.locale}
+- **Color primitives:** list each `brand-colors` entry as `name → hex`
+- **Themes:** list each theme with its slot-to-color mappings
+- **Typography styles:** for each named style — font, weight, size (always append unit `cqh` — container-query-height, responsive to the canvas height), lineHeight, letterSpacing, flags like `uppercase`, autofit-min/max if present
+- **Fonts:** for each font block — name, source, variants
+- **Spacing scale:** unit + named steps (e.g. `cqmin` — container-query-min, responsive to the shorter canvas side; xs/s/m/l/xl)
+- **Dividers:** if present, list each
+- **Voice constraints:** `sentence-max`, `headline-pattern`, `number-format`, `register` (if absent in `.brand`, note "not declared" — do not omit the row)
+
+## Guardrails (auto-derived)
+_Role: hard rules any generator, agent, or reviewer must enforce._
+
+**Never:**
+- {each voice.never item}
+
+**Always:**
+- {each voice.always item}
+
+**Avoid topics:**
+- {each pillars.avoid item}
+
+**Anti-audiences:**
+- **{label}** — {description}
+
+## Purposes (optional)
+_Role: content types — what each piece of content is trying to do. Only emitted if any `.purpose` files are present._
+
+For each purpose, emit **glossed** tags — not verbatim DSL values:
+
+- **{id}** — {name}
+  - Compositions: {composition ids}
+  - **Density:** gloss the value — `light` = "minimal slots filled, headline-forward"; `medium` = "balanced slot fill"; `full` = "all slots populated". Emit as `{value} — "{gloss}"`.
+  - **Palette:** gloss — `dynamic` = "inherits theme colors at render time"; `fixed` = "uses a specific theme"; other values pass through verbatim.
+  - **Uses photo:** translate `camera:` field — `true` → "yes"; `false` → "no". Do not emit "camera: false".
+  - **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.
+
+## Formats (optional)
+_Role: where content appears. Only emitted if any `.format` files are present._
+
+For each format, label axes and units explicitly:
+
+- **{id}** ({label} {sublabel}) — category: {category}
+  - **Size:** {width} × {height} px
+  - **Grid:** {rows} rows × {cols} cols — always state which number is which. The DSL writes `grid: ROWS COLS`.
+  - **Danger zone:** {top} {right} {bottom} {left} px (platform UI overlay insets)
+  - **Crop:** {top} {right} {bottom} {left} px, or "none"
+  - **Comfort zone:** {value}% inset from the usable area
+
+## Compositions (optional)
+_Role: spatial arrangement of slots. Only emitted if any `.composition` files are present._
+
+For each composition, gloss the layout mode and decode positioning tokens:
+
+- **{id}** ({name})
+  - **Mode:** gloss — `flow` = "sequential vertical stack of slots with tunable spacers between them"; `grid` = "2D cell placement on the format grid". Emit as `{mode} — "{gloss}"`.
+  - **Image:** if present, state whether it's full-bleed or panel-scoped (`full` → "full-bleed background", other values pass through).
+  - **Sticky bar:** translate `sticky: top m` as "pinned to top edge, size/padding `m` (from spacing scale)"; list each item (e.g. `label left`, `logo right`) with position noted.
+  - **Flow:** emit the raw flow string for precision, then a one-line prose gloss describing what the layout visually produces. Decode tokens:
+    - `spacer-xs/s/m/l/xl` — spacer using the named step from the spacing scale
+    - `spacer-auto` — flexible spacer that absorbs remaining space
+    - `{slot} left/center/right` — slot with its text alignment
+    - `panel {anchor} {width} {height}` — a constrained panel anchored to an edge or corner (e.g. `panel bottom-left 2/3 1/1` = "panel anchored to bottom-left, 2/3 canvas width × full canvas height")
+    - `split {edge} {fraction}` — the canvas is split at the given edge and fraction (e.g. `split bottom 1/2` = "canvas split horizontally, content occupies bottom half")
+    - `divider-{name}` — references a divider style from `.brand`
+    - `columns:N gap:{size}` — the slot renders as N columns with the named gap
+
+---
+Generated by `/brief` from brand-intent v{version}. To change anything in this brief, edit the DSL files and regenerate.
+```
+
+## Rules
+
+- **No rephrasing.** Values are extracted verbatim from the DSL files.
+- **No interpretation.** If a field is ambiguous, emit it as-is; don't explain it.
+- **Omit absent optional sections entirely.** No empty headers, no "none" placeholders.
+- **Never add `guardrails:` to the DSL.** The Guardrails section in the brief is always derived from existing `.identity` fields.
+- **Never invent.** If `voice.always` is empty, the Always list is empty. Don't fill gaps.
+- **Claude Design is an example, not a dependency.** This brief works anywhere. Don't phrase it as Claude-specific.