brand-intent 0.1.3 → 0.1.5

package/README.md

@@ -17,9 +17,9 @@ Brand Intent is a set of five composable file types that encode brand knowledge
 | 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? |
+| Brand | `.brand` | How is it expressed? |
+| Format | `.format` | Where does it appear? |
+| Purpose | `.purpose` | What is this content for? |
 | Composition | `.composition` | How are elements composed? |
 
 ## Get started
@@ -29,23 +29,15 @@ Brand Intent is a set of five composable file types that encode brand knowledge
 Syntax highlighting, autocomplete, and validation for all five file types.
 
 ```
-ext install stoll.brand-intent-lang
+ext install studiostoll.brand-intent-lang
 ```
 
-### 2. Install skills for your AI agent
+### 2. Run init
 
-```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.
+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.
 
 ```bash
-npx brand-intent init --from krume
+npx brand-intent init
 ```
 
 ## Documentation
@@ -54,10 +46,6 @@ npx brand-intent init --from krume
 - [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

package/brands/krume/krume.brand

@@ -27,10 +27,15 @@ theme Laden
   text-primary:   $primary
   text-secondary: $secondary
   text-tertiary:  $accent1
+  text-subtle:    #A89282
+  text-muted:     #C4B5A7
   logo:           $primary
+  sticker-bg:     $accent1
+  sticker-fg:     $primary
   cta:            $accent2
   label-bg:       $accent1
   label-fg:       $primary
+  icon:           $secondary
   divider:        $accent1
 
 theme Tafel
@@ -38,33 +43,61 @@ theme Tafel
   text-primary:   $white
   text-secondary: #D4C4B0
   text-tertiary:  #8A7A68
+  text-subtle:    #6A5A48
+  text-muted:     #4A3A28
   logo:           $accent1
+  sticker-bg:     $accent2
+  sticker-fg:     $white
   cta:            $accent1
   label-bg:       $accent2
   label-fg:       $white
+  icon:           #D4C4B0
   divider:        $accent1
 
 # ── Typography ──
-# Libre Franklin: utilitarian, no-nonsense, legible.
-# Not a display typeface. Not decorative. Feels like signage.
+# Hanken Grotesk: clean, geometric, contemporary.
+# ABC Stefan Simple: display face for hero moments.
 
 font primary
-  name:     Libre Franklin
+  name:     Hanken Grotesk
   fallback: sans-serif
   source:   google
 
+font secondary
+  name:     ABC Stefan Simple
+  fallback: sans-serif
+  source:   local
+
+typography display
+  font:        $secondary
+  weight:      400
+  size:        8
+  lineHeight:  1.1
+  autofit-min: 5
+  autofit-max: 12
+
 typography headline
   weight:      700
   strong:      800
-  size:        6          # cqh - large but not shouting
+  size:        6
   lineHeight:  1.15
   autofit-min: 4
   autofit-max: 10
 
 typography kicker
-  weight:      500
-  size:        3.5
+  weight:      400
+  size:        2.6
   lineHeight:  1.3
+  autofit-min: 2.5
+  autofit-max: 3.5
+
+typography quote
+  weight:      700
+  strong:      800
+  size:        5.5
+  lineHeight:  1.2
+  autofit-min: 4
+  autofit-max: 8
 
 typography body
   weight:      400
@@ -76,6 +109,12 @@ typography caption
   size:        2.2
   lineHeight:  1.4
 
+typography attribution
+  weight:         300
+  size:           2.2
+  lineHeight:     1.4
+  letterSpacing:  0.08
+
 typography label
   weight:      600
   size:        2
@@ -83,10 +122,10 @@ typography label
   uppercase
 
 typography number
-  weight:      300
-  size:        14        # intentionally large - display element
-  lineHeight:  0.9
-  letterSpacing: -0.03
+  weight:         300
+  size:           14
+  lineHeight:     0.9
+  letterSpacing:  -0.03
 
 # ── Spacing ──
 
@@ -105,31 +144,12 @@ divider line
   width: 100%
   color: divider
   align: left
-  spacing: xs
+  spacing: s
 
-divider short
-  thickness: 0.2
-  width: 25%
+divider ruler
+  thickness: 0.8
+  width: 20%
   color: divider
   align: left
-  spacing: s
+  spacing: m
 
-# ── 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/cli/index.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
-import { join, dirname, resolve, basename } from 'path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { createInterface } from 'readline';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -10,108 +11,77 @@ const PKG_ROOT = resolve(__dirname, '..');
 
 const SKILL_FILE = join(PKG_ROOT, 'skills', 'brand-intent.md');
 
-// ── Harness detection and install paths ──
+// ── Harness detection ──
 
-const HARNESS_DIRS = {
-  claude:  '.claude/commands',
-  cursor:  '.cursor/rules',
-  gemini:  '.gemini',
-  copilot: '.github/copilot-instructions',
-};
+const HARNESSES = [
+  { id: 'claude',  label: 'Claude Code',      dir: '.claude/commands' },
+  { id: 'cursor',  label: 'Cursor',           dir: '.cursor/rules' },
+  { id: 'gemini',  label: 'Gemini CLI',       dir: '.gemini' },
+  { id: 'copilot', label: 'VS Code Copilot',  dir: '.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 HARNESSES.filter(h => {
+    const parent = h.dir.split('/')[0];
+    return existsSync(join(cwd, parent));
+  });
+}
+
+// ── Readline ──
+
+let _rl;
+function rl() {
+  if (!_rl) {
+    _rl = createInterface({ input: process.stdin, output: process.stdout });
   }
-  return found;
+  return _rl;
+}
+function closeRl() {
+  if (_rl) { _rl.close(); _rl = null; }
 }
 
-// ── Commands ──
+function ask(q) {
+  return new Promise((res) => rl().question(q, res));
+}
+
+// ── Install skill ──
 
-function installSkills(cwd) {
+async 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);
+  let harnesses = detectHarnesses(cwd);
 
   if (harnesses.length === 0) {
-    // No harness detected — install to .claude/ by default
-    harnesses.push({ name: 'claude', dir: HARNESS_DIRS.claude });
+    console.log('  Which AI tools do you use?\n');
+    HARNESSES.forEach((h, i) => {
+      console.log(`  ${i + 1}) ${h.label}`);
+    });
+    console.log(`  ${HARNESSES.length + 1}) all of the above`);
+    console.log('');
+    const answer = await ask(`  Choose [1-${HARNESSES.length + 1}]: `);
+    const idx = parseInt(answer, 10) - 1;
+    if (idx === HARNESSES.length) {
+      harnesses = HARNESSES;
+    } else if (idx >= 0 && idx < HARNESSES.length) {
+      harnesses = [HARNESSES[idx]];
+    } else {
+      harnesses = [HARNESSES[0]];
+    }
   }
 
-  let installed = 0;
-  for (const { name, dir } of harnesses) {
+  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(`  ✓ ${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);
+    console.log(`  \u2713 ${label} \u2014 ${dir}/brand-intent.md`);
   }
 
-  const brandDest = join(cwd, `brands/${brandName}`);
-  copyDirRecursive(brandSrc, brandDest);
-  console.log(`  ✓ brand files → brands/${brandName}/`);
-  console.log(`\nAdded "${brandName}" brand files to your project.`);
+  return harnesses;
 }
 
 // ── CLI entry point ──
@@ -123,41 +93,44 @@ const cwd = process.cwd();
 const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
 console.log(`Brand Intent v${pkg.version}\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;
-  }
+if (command && command !== 'init' && command !== 'install-skills' && command !== '--help' && command !== '-h') {
+  console.log(`  Unknown command: ${command}\n`);
+}
 
-  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;
-  }
+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 install-skills     Same as init (alias)');
+  console.log('');
+  console.log('Example:');
+  console.log('  npx brand-intent init');
+  process.exit(0);
+}
 
-  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;
+// Both "init" and "install-skills" do the same thing now
+const installed = await installSkills(cwd);
+closeRl();
+
+// Show next steps with skill-specific commands
+const hasClaudeCode = installed.some(h => h.id === 'claude');
+const hasCursor = installed.some(h => h.id === 'cursor');
+
+console.log('\n  Done. Now open your AI agent and try:\n');
+console.log('    "Onboard my brand"');
+console.log('    "Show me the Krume bakery example"');
+
+if (hasClaudeCode || hasCursor) {
+  console.log('\n  Or use the skill directly:\n');
+  if (hasClaudeCode) {
+    console.log('    /brand-intent onboard     Create your brand through a guided interview');
+    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');
+  }
+  if (hasCursor) {
+    console.log('    @brand-intent onboard     Create your brand through a guided interview');
+    console.log('    @brand-intent example     Scaffold the Krume reference implementation');
+  }
 }
+
+console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
@@ -20,6 +20,9 @@
     "brand-identity",
     "design-system"
   ],
+  "scripts": {
+    "release": "./scripts/release.sh"
+  },
   "files": [
     "cli/",
     "skills/",

package/skills/brand-intent.md

@@ -6,6 +6,8 @@ description: Generate and validate on-brand content using Brand Intent files
 
 **Scope:** `$ARGUMENTS`
 
+> If `$ARGUMENTS` is "onboard": run the guided brand onboarding interview (see Onboarding section below).
+> If `$ARGUMENTS` is "example": scaffold the Krume bakery reference implementation into `examples/krume/` and explain what each file does.
 > If `$ARGUMENTS` names a purpose (e.g. "daily-bread", "event", "quote"): compose context from the five layers and generate content for that purpose.
 > If `$ARGUMENTS` is "validate": read the most recent generated or provided content and run the validation checklist against the brand files.
 > If `$ARGUMENTS` is empty: discover all `.identity`, `.brand`, `.purpose` files in the project, summarize the brand voice and list available purposes.
@@ -98,9 +100,6 @@ When generating content for a specific purpose, read all layers silently (do not
 
 ### Output format:
 
-For each brand that has the requested purpose:
-
-- If multiple brands exist, show the **brand name** as a heading
 - Show each **slot** with its generated content — nothing else
 - After the content, show a **compact validation summary** (pass/fail per rule, only call out failures in detail)
 
@@ -132,27 +131,115 @@ After generating or reviewing content, validate against these rules in order:
 Brand Intent files follow this structure:
 
 ```
-# Single brand
 brandname.identity
 brandname.brand
 formats/*.format
 purposes/*.purpose
 compositions/*.composition
+```
+
+To find the active brand, look for the `.identity` and `.brand` files at the project root. There is exactly one of each per project.
+
+## Onboarding: Create a New Brand
+
+When `$ARGUMENTS` is "onboard", guide the user through a structured interview to create their brand files. Do NOT jump to file creation — the interview comes first.
+
+### Interview Flow
+
+Have a natural conversation. Don't dump all questions at once — adapt based on answers. Group questions into rounds of 2-4.
+
+**Round 1: Identity**
+- Brand name? (and brand ID — lowercase, no spaces, used in filenames)
+- What does this brand do? One sentence.
+- Language? (e.g., de, en)
+- Essence — the irreducible truth in 3-8 words?
+
+Listen for tone, confidence, specificity. A founder who says "we make artisan coffee" vs "we roast single-origin in a garage in Kreuzberg" gives you very different brands.
+
+**Round 2: Voice & Personality**
+- If this brand were a person talking to a customer, who would they be?
+- Formal or informal?
+- What does this brand ALWAYS do in communication? (2-3 concrete rules)
+- What does this brand NEVER do? (2-3 concrete anti-patterns)
+
+The user will often describe what the brand is NOT before what it IS. Capture both.
+
+**Round 3: Visual Direction**
+- Describe the color palette. Hex values, or a mood? (e.g., "warm earth tones", "cold Nordic blue")
+- What fonts define this brand? (primary + body. If unknown: serif or sans-serif? Heavy or light?)
+
+If the user describes a mood: propose a palette of 4-5 colors (primary, secondary, accent1, accent2, white/background) and confirm before proceeding.
+
+**Round 4: Content & Audience**
+- Who are the 1-2 main audiences? For each: who are they, what do they want, how should you talk to them?
+- Anti-audience — someone this brand is explicitly NOT for?
+- What content topics are on-brand? (primary pillars)
+- What topics should the brand avoid?
+
+### Synthesis
 
-# Multi-brand
-brands/brandname/brandname.identity
-brands/brandname/brandname.brand
-formats/*.format           ← shared
-purposes/*.purpose         ← shared
-compositions/*.composition ← shared
+After the interview, present a Brand Brief for confirmation:
+
+```
+## Brand Brief: [Brand Name]
+ID: [brandid] | Language: [language]
+Essence: [essence]
+
+Voice: [persona], [register]
+Always: [rules]
+Never: [anti-patterns]
+
+Colors: primary [hex], secondary [hex], accent [hex], background [hex]
+Font: [primary font name]
+
+Audiences: [summaries]
+Pillars: [topics] | Avoid: [topics]
 ```
 
-To find the active brand, look for `.identity` and `.brand` files. There is exactly one of each per brand.
+Ask the user to confirm or adjust. Iterate until they're happy.
+
+### File Generation
+
+Once confirmed, generate these files at the project root:
+
+1. **`[brandid].identity`** — essence, promise, tagline, archetype, voice (register, persona, rhythm, always/never), pillars, audience blocks, anti-audience blocks. Follow the structure of the Krume reference.
 
-## Relationship to Impeccable
+2. **`[brandid].brand`** — id, name, language, locale, brand-colors, at least one theme (mapping semantic slots to color references), font blocks, typography blocks (headline, body, caption, label at minimum), spacing, dividers. Use `$name` references for theme colors.
 
-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)
+3. **`purposes/starter.purpose`** — a starter purpose with slots that have on-brand sample content derived from the identity. Samples must be in the brand's language and respect voice rules.
+
+### Rules
+
+- **Every voice rule, value, and narrative must come from the user's answers.** Don't invent brand personality.
+- **Sample content in purposes must match the brand's language.**
+- **Don't skip the interview.** Even if the user says "just make a brand called X" — ask at least the essentials (essence, voice, colors, one audience).
+- **Typography sizes use `cqmin` units.** Use these sensible defaults unless the user specified otherwise: headline 6, body 2.8, caption 2.2, label 2.
+- **Spacing defaults:** unit cqmin, xs 1.5, s 2, m 3, l 5, xl 6.5.
+
+## Example: Scaffold the Krume Reference
+
+When `$ARGUMENTS` is "example", copy the Krume bakery reference files into `examples/krume/` in the current project. The Krume files are distributed with the npm package.
+
+Run this shell command to copy them:
+
+```bash
+node -e "
+const pkg = require.resolve('brand-intent/package.json');
+const root = require('path').dirname(pkg);
+const { cpSync, mkdirSync } = require('fs');
+const dest = 'examples/krume';
+mkdirSync(dest, { recursive: true });
+for (const d of ['brands/krume', 'formats', 'purposes', 'compositions']) {
+  const src = require('path').join(root, d);
+  try { cpSync(src, require('path').join(dest, d.replace('brands/krume', '')), { recursive: true }); } catch {}
+}
+console.log('Krume example scaffolded into examples/krume/');
+"
+```
 
-Apply both. Impeccable governs execution quality. Brand Intent governs brand specificity.
+Then explain to the user what each file does:
+- **`.identity`** — the strategic layer: essence, voice, values, audiences. Read this first.
+- **`.brand`** — derived expression: colors, themes, typography, spacing. Every decision traces back to identity.
+- **`.format`** — canvas dimensions, safe zones, grid. Where content appears.
+- **`.purpose`** — content type with semantic slots, samples, constraints. What content does.
+- **`.composition`** — spatial arrangement of slots. How elements are placed.