The synced brand folder

Your brand lives in the Braaand folder on your computer. When Claude builds something, it copies the brand in, so it's always safe and always works. When the brand changes, run sync and tell Claude "pick up the latest brand" — it shows you what changed.

That's the whole model. braaand sync writes every brand you can access into one canonical folder (default ~/Documents/Braaand), and that folder is a consumable dependency, not just an asset mirror: build-ready token artifacts, real font and logo files, guidelines as markdown, and a self-describing instruction file for any coding agent.

Three rendering tiers

Local previews don't replace Braaand's renderer — they're a third tier with its own job:

What's in the folder

Braaand/
├── CLAUDE.md                  # what this folder is + rules, for any agent
├── sync.json                  # machine state: brands, versions, timestamps
├── _shared/                   # Braaand-owned preview chrome
│   ├── shell.html             #   header/footer/styles previews compose into
│   ├── motion.json / .js      #   Braaand house motion presets (GSAP)
│   └── vendor/gsap.min.js     #   vendored, so previews work offline
└── reform-society/            # one folder per brand
    ├── CLAUDE.md              # brand instructions: paths, colors, voice, rules
    ├── brand.json             # everything machine-readable, incl. deep links
    ├── dist/                  # BUILD-READY, regenerated every sync:
    │   ├── tokens.json        #   W3C Design Tokens (DTCG)
    │   ├── tokens.css         #   every --brand-* custom property
    │   ├── fonts.css          #   @font-face → ../fonts/ (relative, offline)
    │   ├── tailwind.preset.js #   Tailwind v3 preset
    │   └── tailwind.tokens.css#   Tailwind v4 @theme block
    ├── fonts/ logos/ images/ icons/ guidelines/ docs/
    └── Previews/              # LOCAL-ONLY — sync never touches this
        └── preview.html       # always the latest preview, overwritten

Everything except Previews/ is owned by sync: hand-edits get overwritten, deleted server assets get removed. Previews and any _-prefixed folder inside a brand are local-only — sync never writes, deletes, or uploads them.

The dist contract

• Generated deterministically from brand data on every sync — never hand-edited.
• Every file starts with a provenance header:

/* Reform Society · brand v14 · synced 2026-07-17T09:42Z · generated by Braaand — do not edit */

• tokens.json follows the W3C Design Tokens Community Group format, and every token carries an ai.braaand.cssVar extension naming its --brand-* counterpart.
• The CSS variable names are identical to what Braaand renders ads with — a site built from dist/ and the ads stay in lockstep.

Brand versions

Every brand carries a version number (v14) that bumps only when the brand's visual identity changes — colors, fonts, logos, tokens. Editing prose (voice, notes) doesn't bump it. The version is stamped into every dist file, shown in sync status, and is what makes "a rebrand ships like a dependency update" literal: projects carry a copy stamped v14; when the brand moves to v15, sync + a diff shows exactly what changed before anything updates.

Choosing what syncs

A brand with thousands of library photos shouldn't force a multi-gigabyte first sync. Brand settings → Sync has an Assets policy per brand:

• Everything (default) — the full library.
• Brand essentials — fonts, logos, icons, guidelines, and documents, plus the brand's default image. The heavy photo classes stay in the cloud.
• Essentials + a collection — essentials plus whatever you've linked into a chosen collection. Curate the photos that matter locally by dragging them into it.

Identity assets always sync — dist/fonts.css and the logo paths stay valid under every policy. brand.json still catalogs every asset: excluded ones keep their remote url (and are marked synced: false) so agents work local-first with a remote fallback. Need a one-off full mirror regardless of policy? braaand sync --all.

Commands

braaand sync                      # sync every brand to the canonical folder
braaand sync reform-society       # one brand
braaand sync status --json        # root, per-brand version + staleness — the discovery endpoint
braaand sync set-root ~/Sites/Braaand
braaand path reform-society       # print a brand's folder path

The root is machine-level (stored in ~/.braaand/config.json). After each sync the CLI reports root + freshness to Braaand, so the app and the MCP sync_status tool can tell an agent whether a local folder exists without touching your filesystem.

Sync also keeps an installed braaand skill fresh: if ~/.claude/skills/braaand/ exists on your machine, each sync refreshes its SKILL.md from the current canonical version (it never installs the skill on machines that don't have it; opt out with "skillAutoUpdate": false in ~/.braaand/config.json). Not installed yet? braaand skill install sets it up — and agents reading the folder will offer it to you once, since sync status --json reports skill.installed and the folder's own instructions tell them to ask.

Prototyping on brand (no code needed)

Open Claude Code (or any agent with the braaand skill) and just ask:

"Show me Reform Society's fonts and colors"

The agent finds your synced folder, composes the requested sections into Braaand's preview shell — real fonts, real hex values, Braaand's house motion — and opens Previews/preview.html. Follow-ups like "larger, on black" edit the same file and reopen it. The conversation is the UI; the folder is the deliverable.