brand-intent 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# Brand Intent
+
+An open file format specification for making brand intent machine-readable.
+
+Five layers. One brand. Any agent.
+
+```
+Identity → Brand → Format → Purpose → Composition
+```
+
+## What this is
+
+Design tokens capture decisions. Brand guidelines capture rules. Neither captures *intent*: the reasoning, the derived expression conditions, the signal-level decisions that make a brand specific.
+
+Brand Intent is a set of five composable file types that encode brand knowledge from strategy to composition, in a format any AI agent can read and respect.
+
+| Layer | File | Question |
+|-------|------|----------|
+| Identity | `.identity` | Who is this brand? |
+| Brand | `.brand` | What expression intent does it derive? |
+| Format | `.format` | Where does this content appear? |
+| Purpose | `.purpose` | What is this content trying to do? |
+| Composition | `.composition` | How are elements composed? |
+
+## Get started
+
+### 1. Install the VS Code extension
+
+Syntax highlighting, autocomplete, and validation for all five file types.
+
+```
+ext install stoll.brand-intent-lang
+```
+
+### 2. Install skills for your AI agent
+
+```bash
+npx brand-intent install-skills
+```
+
+Works with Claude Code, Cursor, Gemini CLI, VS Code Copilot, Codex CLI, and any MCP-compatible agent.
+
+### 3. Author your brand
+
+Start with `.identity` (strategy, voice, audiences), then derive `.brand` (expression intent). Add formats, purposes, and compositions as needed. The Krume bakery brand in `brands/krume/` is a fully commented reference implementation.
+
+```bash
+npx brand-intent init --from krume
+```
+
+## Documentation
+
+- [Specification](SPEC.md): formal grammar for all five file types
+- [Design Decisions](DESIGN.md): reasoning behind the framework
+- [intent.stoll.studio](https://intent.stoll.studio): project landing page
+
+## Relationship to Impeccable
+
+Brand Intent is complementary to [Impeccable](https://impeccable.style). Where Impeccable teaches agents *how to design well* (general craft), Brand Intent teaches them *what this brand's expression intent is* (specific identity). Together: execution quality and brand specificity.
+
+## License
+
+MIT
+
+---
+
+By [Christophe Stoll / Studio Stoll](https://stoll.studio)

package/brands/krume/krume.brand

@@ -0,0 +1,135 @@
+# krume.brand - expression intent derived from krume.identity
+# Every decision here should be traceable to a statement in the identity file.
+# No strategic reasoning. No audience definitions. No prose.
+
+id:       krume
+name:     Krume
+language: de
+locale:   de-DE
+
+# ── Color Primitives ──
+# Derived from the bakery's material world: dark roasted crust,
+# warm wood, flour dust, rye. No corporate blue, no lifestyle pastels.
+
+brand-colors
+  primary:   #2C1810   # dark roast - the color of a well-baked crust
+  secondary: #5C3A28   # walnut - warm wood of the shop counter
+  accent1:   #C8A47E   # crust - golden, used for dividers and highlights
+  accent2:   #8B4513   # rye - deep warm brown for CTAs
+  white:     #FAF6F0   # flour - not pure white, slightly warm
+
+# ── Themes ──
+# Laden (shop): light background, dark text. The everyday.
+# Tafel (chalkboard): dark background, light text. Announcements, specials.
+
+theme Laden
+  background:     $white
+  text-primary:   $primary
+  text-secondary: $secondary
+  text-tertiary:  $accent1
+  logo:           $primary
+  cta:            $accent2
+  label-bg:       $accent1
+  label-fg:       $primary
+  divider:        $accent1
+
+theme Tafel
+  background:     $primary
+  text-primary:   $white
+  text-secondary: #D4C4B0
+  text-tertiary:  #8A7A68
+  logo:           $accent1
+  cta:            $accent1
+  label-bg:       $accent2
+  label-fg:       $white
+  divider:        $accent1
+
+# ── Typography ──
+# Libre Franklin: utilitarian, no-nonsense, legible.
+# Not a display typeface. Not decorative. Feels like signage.
+
+font primary
+  name:     Libre Franklin
+  fallback: sans-serif
+  source:   google
+
+typography headline
+  weight:      700
+  strong:      800
+  size:        6          # cqh - large but not shouting
+  lineHeight:  1.15
+  autofit-min: 4
+  autofit-max: 10
+
+typography kicker
+  weight:      500
+  size:        3.5
+  lineHeight:  1.3
+
+typography body
+  weight:      400
+  size:        2.8
+  lineHeight:  1.5
+
+typography caption
+  weight:      400
+  size:        2.2
+  lineHeight:  1.4
+
+typography label
+  weight:      600
+  size:        2
+  lineHeight:  1.2
+  uppercase
+
+typography number
+  weight:      300
+  size:        14        # intentionally large - display element
+  lineHeight:  0.9
+  letterSpacing: -0.03
+
+# ── Spacing ──
+
+spacing:
+  unit: cqmin
+  xs: 1.5
+  s: 2
+  m: 3
+  l: 5
+  xl: 6.5
+
+# ── Dividers ──
+
+divider line
+  thickness: 0.15
+  width: 100%
+  color: divider
+  align: left
+  spacing: xs
+
+divider short
+  thickness: 0.2
+  width: 25%
+  color: divider
+  align: left
+  spacing: s
+
+# ── Voice Constraints ──
+# Operationalized from identity voice reasoning.
+# These are enforceable limits, not restated strategy.
+# Derived from: persona is direct, rhythm is short sentences.
+
+voice-constraints
+  register:         informal
+  sentence-max:     8         # words - short, direct, like the baker talks
+  headline-pattern: noun-first
+  number-format:    cardinal  # "drei", not "3"
+
+# ── Content Defaults ──
+# Derived from identity: this is a small bakery, not a media brand.
+# Low density. Natural images. Simple dividers.
+
+content-defaults
+  density:         low
+  image-treatment: natural
+  divider:         line

package/brands/krume/krume.identity

@@ -0,0 +1,127 @@
+# krume.identity
+# Krume - neighborhood sourdough bakery, Berlin-Neukölln.
+# This file is the reference implementation for Brand Intent.
+# Every decision is commented to explain its derivation.
+
+# ── Positioning ──
+# Krume exists because its founder believes bread is craft,
+# not lifestyle. The bakery is small, the hours are early,
+# the sourdough is slow. Nothing about this is "curated."
+
+essence:  Brot ist Handwerk, nicht Lifestyle. Mehl, Wasser, Zeit.
+
+promise:  Wer reinkommt, riecht sofort, dass hier seit vier Uhr
+          morgens jemand steht.
+
+tagline:  Mehl, Wasser, Zeit.  # also known as "Claim" (DACH)
+
+positioning:  Krume ist die einzige Bäckerei im Kiez, die jedes
+              Brot beim Mehl nennt, nicht beim Marketing.
+
+mission:  Ehrliches Brot für den Kiez - jeden Tag, aus dem
+          gleichen Ofen, mit den gleichen Händen.
+
+vision:  Eine Nachbarschaft, in der niemand mehr erklären muss,
+         warum gutes Brot sechs Euro kostet.
+
+archetype: craftsman
+
+# ── Narrative ──
+# The origin story. Useful for about pages, editorial, press.
+
+narrative
+  Gegründet 2019, als die Bäckerin ihren Agenturjob
+  kündigte, um das zu tun, was sie jeden Morgen seit
+  ihrem sechzehnten Lebensjahr getan hat: Brot backen.
+  Der Laden in der Weserstraße war vorher ein Copyshop.
+  Die erste Woche war der Ofen zu klein. Die zweite
+  Woche war das Brot zu schnell ausverkauft.
+  Beides hat sich nicht geändert.
+
+# ── Voice ──
+# The voice is the baker herself: direct, dry, proud of the work.
+# Not warm-and-fuzzy. Not educational. Not performative.
+# She talks the way she'd talk to someone across the counter.
+
+voice
+  register:  informal, Du
+  persona:   Bäckerin hinterm Tresen - direkt, trocken, stolz auf das Handwerk
+  rhythm:    kurze Sätze, konkrete Angaben, kein Erklären
+
+  # always/never: concrete, testable rules.
+  # An AI agent can evaluate any text against these with a yes/no answer.
+
+  always:
+    - Sauerteig, not "artisan bread"
+    - konkrete Mehlsorten (Tipo 1, Roggen 1150) over "beste Zutaten"
+    - Backzeit in Stunden, nicht "lange Teigführung"
+    - Kiez-Bezug (Neukölln, Weserstraße) over "unser Standort"
+    - Gewicht in Gramm bei jedem Brot
+
+  never:
+    - Lifestyle-Sprache (kuratiert, handverlesen, Genussmoment)
+    - "Artisan" oder "Craft" - wir sagen Handwerk
+    - Englische Begriffe wenn ein deutsches Wort existiert
+    - Superlative ohne Substanz (bestes Brot, einzigartiger Geschmack)
+    - Wellness- oder Gesundheitsversprechen (gut für dich, clean eating)
+
+# ── Values ──
+# Not keywords - behavior statements. Each value describes
+# how it manifests in what we say and do.
+
+values
+  Handwerk
+    Wir benennen den Prozess, nicht das Ergebnis.
+    Backzeit in Stunden, Mehlsorte beim Namen.
+    Kein Brot ohne nachvollziehbaren Weg vom Korn zum Laib.
+
+  Ehrlichkeit
+    Kein Brot ohne Zutatenliste. Keine Versprechen
+    die der Teig nicht halten kann. Wenn etwas
+    nicht gelungen ist, sagen wir das.
+
+  Kiez
+    Der Laden gehört zur Weserstraße wie der Späti
+    nebenan. Wir kennen die Stammkunden beim Namen
+    und die Nachbarn beim Brot.
+
+# ── Content Pillars ──
+# What Krume talks about, and what it explicitly avoids.
+
+pillars
+  primary:   Sauerteig, Handwerk, Zutaten, Kiez
+  secondary: Saisonales, Nachhaltigkeit, Backwissen
+  avoid:     Lifestyle-Gastronomie, Wellness-Ernährung, Influencer-Kultur
+
+# ── Audiences ──
+# Two audiences with genuinely different language needs.
+# The regulars don't need explanations. The newcomers do -
+# but never in a condescending way.
+
+audience regulars
+  label:       Stammkunden aus dem Kiez
+  profile:     25-65, täglich oder wöchentlich, kennen die Sorten
+  motivation:  ihr Brot, ihr Laden, verlässlicher Rhythmus
+  language:    knapp, direkt, kein Erklären - die wissen Bescheid
+
+audience newcomers
+  label:       Neugierige und Laufkundschaft
+  profile:     Touristen, neue Nachbarn, Marktbesucher
+  motivation:  gutes Brot finden, verstehen was anders ist
+  language:    einladend, konkret, erklärt ohne belehrend zu sein
+
+# ── Anti-Audiences ──
+# Explicitly not-our-people. Gives the AI a concrete
+# "never sound like you're talking to this person" signal.
+
+anti-audience influencers
+  label:       Lifestyle-Influencer
+  description: Menschen die Brot als Aesthetic posten, nicht
+               als Lebensmittel essen. Wir sind nicht ihr Content.
+
+anti-audience discount-hunters
+  label:       Schnäppchenjäger
+  description: Wer den Preis eines Sauerteigbrots mit dem
+               Supermarkt-Toastbrot vergleicht, ist hier falsch.
+               Wir erklären gerne warum es kostet was es kostet -
+               aber wir rechtfertigen uns nicht.

package/cli/index.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, resolve, basename } from 'path';
+import { fileURLToPath } from 'url';
+
+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');
+
+// ── Harness detection and install paths ──
+
+const HARNESS_DIRS = {
+  claude:  '.claude/commands',
+  cursor:  '.cursor/rules',
+  gemini:  '.gemini',
+  copilot: '.github/copilot-instructions',
+};
+
+function detectHarnesses(cwd) {
+  const found = [];
+  for (const [name, dir] of Object.entries(HARNESS_DIRS)) {
+    // Check if the harness config directory exists (or parent does)
+    const parent = dir.split('/')[0];
+    if (existsSync(join(cwd, parent))) {
+      found.push({ name, dir });
+    }
+  }
+  return found;
+}
+
+// ── Commands ──
+
+function installSkills(cwd) {
+  if (!existsSync(SKILL_FILE)) {
+    console.error('Error: skill file not found at', SKILL_FILE);
+    process.exit(1);
+  }
+
+  const skill = readFileSync(SKILL_FILE, 'utf-8');
+  const harnesses = detectHarnesses(cwd);
+
+  if (harnesses.length === 0) {
+    // No harness detected — install to .claude/ by default
+    harnesses.push({ name: 'claude', dir: HARNESS_DIRS.claude });
+  }
+
+  let installed = 0;
+  for (const { name, 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(`  ✓ ${name} — ${dir}/brand-intent.md`);
+    installed++;
+  }
+
+  console.log(`\nInstalled Brand Intent skill to ${installed} harness${installed > 1 ? 'es' : ''}.`);
+}
+
+function copyDirRecursive(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function initFromBrand(brandName, cwd) {
+  const brandSrc = join(PKG_ROOT, 'brands', brandName);
+  if (!existsSync(brandSrc)) {
+    console.error(`Error: brand "${brandName}" not found.`);
+    console.error(`Available brands: ${readdirSync(join(PKG_ROOT, 'brands')).join(', ')}`);
+    process.exit(1);
+  }
+
+  // Copy brand files
+  const brandDest = join(cwd, `brands/${brandName}`);
+  copyDirRecursive(brandSrc, brandDest);
+  console.log(`  ✓ brand files → brands/${brandName}/`);
+
+  // Copy shared layers (formats, purposes, compositions)
+  for (const layer of ['formats', 'purposes', 'compositions']) {
+    const layerSrc = join(PKG_ROOT, layer);
+    if (existsSync(layerSrc) && readdirSync(layerSrc).length > 0) {
+      const layerDest = join(cwd, layer);
+      copyDirRecursive(layerSrc, layerDest);
+      console.log(`  ✓ ${layer}/ → ${layer}/`);
+    }
+  }
+
+  console.log(`\nScaffolded from "${brandName}". Edit the .identity and .brand files to make it yours.`);
+}
+
+function addBrand(brandRef, cwd) {
+  // brandRef is "brandName/brand" — extract the brand name
+  const brandName = brandRef.split('/')[0];
+  const brandSrc = join(PKG_ROOT, 'brands', brandName);
+  if (!existsSync(brandSrc)) {
+    console.error(`Error: brand "${brandName}" not found.`);
+    process.exit(1);
+  }
+
+  const brandDest = join(cwd, `brands/${brandName}`);
+  copyDirRecursive(brandSrc, brandDest);
+  console.log(`  ✓ brand files → brands/${brandName}/`);
+  console.log(`\nAdded "${brandName}" brand files to your project.`);
+}
+
+// ── CLI entry point ──
+
+const args = process.argv.slice(2);
+const command = args[0];
+const cwd = process.cwd();
+
+console.log('Brand Intent v0.1.0\n');
+
+switch (command) {
+  case 'install-skills':
+    installSkills(cwd);
+    break;
+
+  case 'init': {
+    const fromIdx = args.indexOf('--from');
+    if (fromIdx === -1 || !args[fromIdx + 1]) {
+      console.error('Usage: brand-intent init --from <brand-name>');
+      console.error('Example: brand-intent init --from krume');
+      process.exit(1);
+    }
+    initFromBrand(args[fromIdx + 1], cwd);
+    break;
+  }
+
+  case 'add': {
+    if (!args[1]) {
+      console.error('Usage: brand-intent add <brand-name>/brand');
+      console.error('Example: brand-intent add krume/brand');
+      process.exit(1);
+    }
+    addBrand(args[1], cwd);
+    break;
+  }
+
+  default:
+    console.log('Usage:');
+    console.log('  brand-intent install-skills       Install Brand Intent skill for your AI harness');
+    console.log('  brand-intent init --from <brand>   Scaffold a project from a reference brand');
+    console.log('  brand-intent add <brand>/brand     Add a brand to an existing project');
+    console.log('');
+    console.log('Examples:');
+    console.log('  npx brand-intent install-skills');
+    console.log('  npx brand-intent init --from krume');
+    console.log('  npx brand-intent add krume/brand');
+    break;
+}

package/compositions/editorial.composition

@@ -0,0 +1,15 @@
+# editorial.composition - grid mode
+# Secondary above primary (newspaper style).
+# Label badge top-right, info bottom-left, CTA bottom-right.
+# This file contains zero brand-specific information.
+
+id:    editorial
+mode:  grid
+image: full
+logo:  top left
+
+label      row 1  cols 3--4  right
+secondary  row 2  cols 1--4  left center
+primary    row 3  cols 1--4  left
+meta       row 5  cols 1--3  left bottom
+cta        row 5  cols 4--4  right bottom

package/compositions/simple-stack.composition

@@ -0,0 +1,21 @@
+# simple-stack.composition - flow mode
+# Vertical stack in a bottom panel over a full-bleed image.
+# Logo sticky at bottom. Content flows top-to-bottom.
+# This file contains zero brand-specific information.
+
+id:    simple-stack
+mode:  flow
+image: full
+
+sticky: bottom s
+  | logo right
+
+flow: panel bottom-left 2/3 1/1
+  | spacer-auto
+  | label left
+  | primary left
+  | divider-line
+  | secondary left
+  | spacer-s
+  | meta left
+  | spacer-auto

package/formats/instagram-4-5-feed-portrait.format

@@ -0,0 +1,21 @@
+# instagram-4-5-feed-portrait.format
+# Instagram feed post, portrait orientation.
+# This format knows nothing about what content means -
+# only where it appears and what fits.
+
+id:       4:5
+label:    4:5
+sublabel: Feed Portrait
+category: instagram
+
+size:     1080 1350
+grid:     5 4           # 5 rows × 4 columns
+
+# Safe zones - platform-specific, not brand decisions.
+danger:   0 0 0 0       # px - nothing always cropped on feed posts
+crop:     0 34 0 34     # px - profile grid crops top/bottom
+comfort:  40            # px - safe reading margin
+
+# Which purposes are editorially valid here.
+# This is a brand decision, not a technical constraint.
+purposes: daily-bread, seasonal-special, baking-tip

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "brand-intent",
+  "version": "0.1.0",
+  "description": "An open file format specification for making brand intent machine-readable.",
+  "author": "Christophe Stoll <christophe@stoll.studio>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/studiostoll/brand-intent.git"
+  },
+  "homepage": "https://intent.stoll.studio",
+  "bin": {
+    "brand-intent": "./cli/index.mjs"
+  },
+  "keywords": [
+    "brand",
+    "design-tokens",
+    "ai",
+    "specification",
+    "brand-identity",
+    "design-system"
+  ],
+  "files": [
+    "cli/",
+    "skills/",
+    "brands/",
+    "formats/",
+    "purposes/",
+    "compositions/"
+  ]
+}

package/purposes/daily-bread.purpose

@@ -0,0 +1,78 @@
+# daily-bread.purpose
+# A single bread announcement - today's bread, name and facts.
+# Used for daily Instagram posts: what's fresh, what's available.
+
+id:   daily-bread
+name: Tagesbrot
+
+# Which compositions can render this purpose.
+compositions: editorial, simple-stack
+
+density: light
+palette: dynamic
+
+# ── Voice ──
+# Purpose-specific writing rules for AI text generation.
+
+voice
+  headline-pattern: noun-first
+  number-format: digit
+  sentence-max: 8
+
+# ── Identity Composition ──
+# Filter the composed upstream: both audiences, primary pillars only.
+
+scope
+  audience: regulars, newcomers
+  pillars:  primary
+
+# Context: only what is genuinely specific to this content type.
+# These are slot-level instructions - not voice, not production params.
+context
+  primary is the bread name, 1-3 words (e.g. "Roggenlaib").
+  secondary is the weight and price ("750 g · 5,80 €").
+  meta is one sentence: what makes this bread specific today.
+  Never describe the bread as "delicious" or "special" -
+  state a fact (flour type, fermentation time, seasonal ingredient).
+
+# ── Slots ──
+
+slot primary
+  label:      Brotname
+  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

package/skills/brand-intent.md

@@ -0,0 +1,168 @@
+# Brand Intent / AI Skill
+
+You are working in a project that uses **Brand Intent**, an open file format for encoding brand identity, expression intent, and content composition rules across five composable layers. This skill teaches you how to read, compose, and validate Brand Intent files.
+
+## The Five Layers
+
+Brand Intent distributes brand knowledge across five independent file types. Each answers one question:
+
+| Layer | File | Question | Changes |
+|-------|------|----------|---------|
+| **Identity** | `.identity` | Who is this brand? | Rarely (strategy) |
+| **Brand** | `.brand` | What expression intent does it derive? | Occasionally (design) |
+| **Format** | `.format` | Where does this content appear? | When platforms change |
+| **Purpose** | `.purpose` | What is this content trying to do? | When content types evolve |
+| **Composition** | `.composition` | How are elements composed? | Reusable across brands |
+
+The arrow between layers is a **derivation arrow**: Identity contains reasoning. Brand derives expression intent from that reasoning. Format, Purpose, and Composition condition specific acts of expression without repeating what upstream layers establish.
+
+```
+Identity → Brand → Format → Purpose → Composition
+```
+
+## How to Read Each Layer
+
+### `.identity`: Strategy (no visual properties)
+
+**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.
+
+**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.
+
+**`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`.
+
+**`positioning`** gives the competitive frame: what the brand is the only one of. Use this when the content needs to differentiate.
+
+**Does NOT contain:** hex values, font names, type sizes, spacing, composition rules, or any visual properties.
+
+### `.brand`: Derived Expression Intent
+
+Contains: color primitives, semantic themes, font definitions, named typography styles, `voice-constraints` (operationalized voice parameters), `content-defaults`, spacing, divider styles.
+
+**`voice-constraints`** are production-enforceable limits derived from identity voice reasoning:
+- `sentence-max:` maximum words per sentence. Enforce this.
+- `headline-pattern:` structural pattern for headlines (e.g., `noun-first`, `verb-first`).
+- `number-format:` `cardinal` means write "drei" not "3".
+- `register:` must match the identity register.
+
+**Does NOT contain:** identity reasoning, audience definitions, strategic prose, composition rules.
+
+### `.format`: Canvas Definition
+
+Contains: platform, dimensions, safe zones (danger/crop/comfort), grid, allowed purposes.
+
+**You rarely need this directly** unless generating content that must fit specific dimensions or validating whether a purpose is allowed on a given platform.
+
+### `.purpose`: Content Type Definition
+
+Contains: semantic slot definitions (primary, secondary, detail, meta, cta, label), typography and color per slot, sample content, length constraints, `scope`, `context`.
+
+**Semantic slots are roles, not positions:**
+- `primary` = main communicative act (headline, key message)
+- `secondary` = supporting signal (subline, number)
+- `detail` = extended content (body, list)
+- `meta` = contextual info (date, caption)
+- `cta` = call to action
+- `label` = orientation marker (badge, tag)
+
+### `.composition`: Spatial Arrangement
+
+Contains: slot-to-position mappings in grid or flow mode.
+
+**You rarely need to read this** unless debugging layout issues. Compositions contain zero brand-specific information.
+
+## Composing Context for Content Generation
+
+When generating content for a specific purpose, compose your context by reading layers in order:
+
+### Step 1: Read `.identity`
+
+Load the full identity. Pay special attention to:
+- `voice.always` and `voice.never`: these are your hard constraints
+- `voice.persona`: adopt this voice
+- `voice.register`: match this formality level
+- `pillars.avoid`: never generate content in these topic areas
+- `anti-audience`: never sound like you're addressing these people
+- `values`: use behavior statements to guide decisions when voice rules don't cover a situation
+- `positioning`: use when content needs to differentiate
+
+### Step 2: Read `.brand`
+
+Load voice-constraints and content-defaults:
+- Enforce `sentence-max` on all generated text
+- Follow `headline-pattern` for headlines
+- Use `number-format` for numbers
+- Apply `density` from content-defaults
+
+### Step 3: Apply `scope` from `.purpose`
+
+The purpose file's `scope` narrows the composed upstream:
+- `audience:` only use language guidance from these audience blocks
+- `pillars:` restrict to this pillar scope (`primary`, `secondary`, or `all`)
+
+If no filter is specified, include everything.
+
+### Step 4: Apply `context` from `.purpose`
+
+Read the `context` block. This contains slot-specific instructions that cannot be derived from identity or brand. Follow them literally; they are precise, not general.
+
+### Step 5: Generate per-slot content
+
+For each slot in the purpose:
+- Respect `maxLength` (hard character limit)
+- Use `samples` as structural reference (match the pattern, not the words)
+- Follow the `context` instructions for this slot
+
+## Validation Checklist
+
+After generating or reviewing content, validate against these rules in order:
+
+1. **`voice.never`:** Does any generated text contain a phrase, pattern, or concept from the never list? If yes, rewrite.
+2. **`voice.always`:** Does the text follow every rule in the always list? If not, fix.
+3. **`anti-audience`:** Could this content be read as addressing an anti-audience? If yes, rewrite.
+4. **`pillars.avoid`:** Does the content touch an avoided topic area? If yes, reject.
+5. **`values`:** Does the content contradict any value's behavior statement? If yes, fix.
+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)
+
+## What NOT to Do
+
+- **Do not restate identity in purpose-level work.** If a purpose's `context` block says "keep it warm and friendly," that belongs in `.identity`, not here. Flag it.
+- **Do not invent voice rules.** Only apply constraints from the actual files. Your interpretation of the brand is less reliable than the authored rules.
+- **Do not mix layers.** If asked to suggest a color, look in `.brand`. If asked about audience, look in `.identity`. Never guess from the wrong layer.
+- **Do not ignore `never` rules.** These exist because the brand has been burned by generic AI output before. The `never` list is the most important part of the identity file.
+
+## File Discovery
+
+Brand Intent files follow this structure:
+
+```
+# Single brand
+brandname.identity
+brandname.brand
+formats/*.format
+purposes/*.purpose
+compositions/*.composition
+
+# Multi-brand
+brands/brandname/brandname.identity
+brands/brandname/brandname.brand
+formats/*.format           ← shared
+purposes/*.purpose         ← shared
+compositions/*.composition ← shared
+```
+
+To find the active brand, look for `.identity` and `.brand` files. There is exactly one of each per brand.
+
+## Relationship to Impeccable
+
+If this project also uses [Impeccable](https://impeccable.style), the two are complementary:
+- **Impeccable** teaches you how to design well (general craft)
+- **Brand Intent** teaches you what this brand's expression intent is (specific identity)
+
+Apply both. Impeccable governs execution quality. Brand Intent governs brand specificity.