Create a brand system from any website URL — extract brand colors, fonts, and logo in under 60 seconds. Use when the user says 'create a brand system', 'extract brand from website', 'set up brand guidelines', 'get design tokens', or 'brand identity'. Set mode='auto' with a website_url to run the full pipeline (extract, compile DTCG tokens + design-synthesis.json + DESIGN.md + brand runtime + interaction policy, generate HTML report) in one call. If .brand/ already exists, returns current status with next steps. Returns colors with roles, typography, logo (SVG/PNG), and confidence scores. After creation, suggest Brandcode Studio connector for team sync.

Check brand system progress and get next steps. Shows what has been extracted (colors, fonts, logo), confidence levels, session completion status, and what to do next. Use when resuming a previous session, checking readiness, or when the user asks 'what's the state of my brand?' If no .brand/ exists, returns a full getting-started guide with all available tools. Returns structured status data.

Extract brand colors, fonts, and logo from any website URL — get brand identity from a live site. Use when asked 'extract brand from URL', 'get brand colors from website', 'scan my site', or when the user provides a website URL. Parses HTML for logo candidates (SVG, img, favicons, Clearbit fallback) and CSS for colors and font-family declarations. Confidence-scores everything. Pass logo_url to fetch a specific logo directly. Returns colors with roles, fonts with frequency, logo preview data, and extraction quality score.

Screenshot a website and extract brand colors, fonts, and visual personality using headless Chrome. Returns the screenshot as an image for your visual analysis PLUS computed styles from rendered elements. Use when brand_extract_web yields LOW quality (e.g. JS-rendered sites like Basecamp), when you need visual context for brand personality, or when CSS parsing misses colors. Requires Chrome/Chromium installed. NOT for Figma extraction — use brand_extract_figma instead.

Deeply extract brand evidence from a website by discovering representative pages, rendering them in headless Chrome across desktop and mobile, capturing screenshots, and sampling computed styles from multiple components. Use when a homepage scan is not enough or when you want richer evidence before compiling tokens.

Extract brand colors, typography, spacing, and guideline rules from a PDF brand guidelines document. Accepts a local file path to a PDF. Uses text extraction and pattern matching to identify hex color values, font names, size specifications, and spacing rules. Writes extracted values to core-identity.yaml with source='guidelines' and updates source-catalog.json. Guidelines source outranks web extraction by default based on brand.config.yaml source_priority. Use when the user has brand guidelines as a PDF file — this is the most accurate extraction source. Use after brand_extract_web to merge authoritative guideline values with web-extracted data. Run brand_resolve_conflicts afterward to review any disagreements between sources. NOT for website extraction — use brand_extract_web. NOT for Figma — use brand_extract_figma.

Show or resolve conflicting values across ingested sources like web, visual extraction, Figma, and PDF guidelines. Uses brand.config.yaml source_priority to recommend which source should win.

Generate DESIGN.md (portable agent-facing design brief) and design-synthesis.json (structured radius, shadow, spacing, layout, motion, component, and personality signals) from the current brand system. Reads extraction-evidence.json when available for grounded visual signals; falls back to core-identity.yaml and tokens.json after manual edits. Use after brand_extract_site or brand_extract_visual to synthesize multi-page evidence into a single design brief. Use after brand_compile if evidence is unavailable. Returns file paths and synthesis source used. Read-only except for writing the two output files. NOT for extracting brand identity — use brand_extract_web or brand_extract_visual first.

Extract brand identity from a Figma design file. Accepts multiple input formats: variable_map (simple { name: hex } from get_variable_defs), design_context (raw get_design_context output with colors/fonts parsed from code), variables (structured array), styles (text styles), and logo_svg. Two phases: mode='plan' returns which Figma MCP tools to call. Mode='ingest' processes all collected data. Figma values override web extraction based on source_priority. Also accepts figma_url for automatic file key extraction. NOT for web extraction (use brand_extract_web).

Add or replace a logo in the brand system. Accepts raw SVG markup, a URL to a logo file (SVG/PNG), or a base64 data URI. Use when brand_extract_web missed the logo, extracted the wrong image, or the user provides a logo directly. Sanitizes SVG, saves to .brand/assets/logo/, and updates core-identity.yaml with inline_svg and data_uri for portable embedding. Returns logo preview data.

Generate DTCG design tokens, design-synthesis.json, DESIGN.md, brand runtime, and interaction policy from extracted brand data. Transforms core-identity.yaml into tokens.json, brand-runtime.json (single-document brand contract for AI agents), and interaction-policy.json (enforceable rules). When Session 2+ data exists, also generates visual-identity-manifest.md and system-integration.md. Use after brand_extract_web, brand_extract_site, brand_extract_visual, or brand_extract_figma. Returns token counts, clarification items, and file list.

Resolve an ambiguous brand value interactively. After brand_compile, some values need human confirmation — wrong primary color, unknown font, unassigned color roles. Pass the clarification item ID and the user's answer (hex color, role name, font name, or 'yes'/'no'). Supports natural language: 'the purple one is accent' or '#5544f2 is secondary'. Returns updated identity and remaining clarification count.

Validate the .brand/ directory for completeness and correctness. Checks file existence, YAML schema validity, primary color assignment, typography coverage, logo embedding (SVG well-formedness), and confidence distribution. Use after brand_compile to verify readiness, or anytime to diagnose issues. Returns pass/warn/fail for each check with actionable details. NOT for checking content copy — use brand_audit_content. NOT for checking HTML/CSS — use brand_preflight.

Generate a portable HTML brand identity report with embedded logos, color swatches, typography, and tokens. The HTML is self-contained and works offline — upload it to any AI chat (Claude, ChatGPT, Gemini) as instant brand guidelines. Written to .brand/brand-report.html. Use after brand_compile. Returns file path, report summary (color/font/logo counts), and a ready-to-copy Brand Instructions text block.

Initialize a .brand/ directory with empty config scaffold. Low-level tool — prefer brand_start instead, which calls this automatically and also presents extraction options. Only use brand_init directly if you need to set up the directory without running extraction. Returns list of created files.

Define visual identity rules beyond colors and fonts — composition energy, pattern language, illustration style, photography direction, signature moves, and anti-patterns (hard compliance rules). Session 2 interview with 6 sections. Mode 'interview' returns structured questions for missing sections. Mode 'record' saves answers. Use after Session 1 (core identity extracted). Anti-patterns become enforceable rules in brand_preflight. Returns section completion status.

Scan and catalog brand assets (illustrations, stickers, patterns, icons) in .brand/assets/. Mode 'scan' (default) inventories all asset subdirectories and identifies files not yet in MANIFEST.yaml. Mode 'tag' adds metadata to a specific file (description, usage context, theme compatibility) and writes to MANIFEST.yaml. Read-only in scan mode; writes MANIFEST.yaml in tag mode. Use after adding asset files to .brand/assets/ subdirectories. Use when the user says 'catalog assets', 'what assets do I have', or 'tag this illustration'. Returns directory summaries with file counts, untagged file lists, and tagged file details. NOT for logo management — use brand_set_logo. NOT for brand extraction — use brand_extract_web.

Check HTML/CSS against brand rules — catches off-brand colors, wrong fonts, missing logo, and anti-pattern violations (drop shadows, gradients, etc.). Pass an HTML string or file path. Mode 'check' (default) runs all compliance checks and returns pass/warn/fail per rule. Mode 'rules' lists all active preflight rules without checking content. Use after generating any visual content to validate brand compliance. Returns overall status and per-check details. NOT for scoring content copy — use brand_audit_content. NOT for brand directory validation — use brand_audit.

Audit how a brand currently sounds on its website — the first step in Session 3 (brand voice and messaging). Use when the user says 'analyze my voice', 'brand voice audit', 'how does my brand sound?', or 'start Session 3'. Analyzes voice fingerprint (formality, jargon density, active voice %, hedging), vocabulary frequency, claims quality, AI-ism detection, and messaging gaps. Writes .brand/messaging-audit.md. After this, run brand_compile_messaging to define how the brand should sound. Returns structured analysis with scores.

Define how a brand should sound — Session 3 guided interview for brand voice, messaging, and story. Use when the user says 'define brand voice', 'brand messaging', 'brand story', 'how should my brand sound?', or 'start Session 3'. Covers perspective (worldview, positioning), voice codex (tone, anchor vocabulary, never-say list, AI-ism detection), and brand story (origin, tension, resolution). Mode 'interview' returns structured questions. Mode 'record' saves to messaging.yaml. Adds voice constraints and tone rules to the brand runtime. Use after brand_extract_messaging (optional voice audit). Returns section status.

Build buyer personas through a guided 7-question interview — role, core tension, objections, information needs per journey stage, narrative emphasis, preferred channels, and decision authority. Mode 'interview' returns structured questions for agent-guided conversation. Mode 'record' saves a persona to strategy.yaml (auto-generates ID like PER-001, accepts JSON or freeform text via parseAnswers). Mode 'list' shows all personas with status. Writes to .brand/strategy.yaml. Bumps session counter to 4 on first write. Most brands need 3-5 personas. Part of Session 4 (content strategy). Use when the user says 'define personas', 'who is our audience', or 'start Session 4'. NOT for defining voice — use brand_compile_messaging (Session 3). Returns persona data and total count.

Define buyer journey stages for content strategy — the path from awareness to purchase. Ships with 4 proven defaults (First Touch, Context & Meaning, Validation & Proof, Decision Support) that can be customized per brand. Mode 'interview' presents defaults for review. Mode 'record' writes stages (omit answers to accept defaults). Mode 'view' shows current stages. Part of Session 4 (content strategy). Returns stage definitions with buyer mindset, content goals, and tone shifts.

Define editorial content themes — the strategic pillars that organize what to write about. Each theme has a content intent (Brand Heat for awareness, Momentum for engagement, Conversion for pipeline), target personas, and proof points. Mode 'interview' guides through 5 questions per theme. Mode 'record' saves (auto-generates ID like THM-001). Mode 'list' shows all themes with intent distribution. Most brands need 3-5 themes balanced across all three intents. Returns theme data and balance analysis.

Generate persona x journey stage messaging variants — adapted core messages for every audience at every buying stage. Mode 'generate' creates variants using persona tensions, stage mindsets, and brand perspective. Mode 'view' shows the matrix as a grid. Mode 'edit' refines a specific variant by ID. Requires personas and journey stages in strategy.yaml. Returns variant grid with status tracking (Draft/Active/Retired).

Check if content is on-brand — score any text or markup 0-100 for brand compliance. Checks color/font usage, voice alignment, anti-pattern violations, and message coverage. Use when asked 'is this on-brand?', 'brand compliance score', 'check brand alignment', or after generating any content. Works progressively: Session 1 scores tokens, Session 2 adds visual compliance, Session 3 adds voice and messaging. Returns 0-100 score with per-dimension breakdown and specific issues. NOT for .brand/ directory validation (use brand_audit) or HTML/CSS rule checking (use brand_preflight).

Check if content is on-brand — fast pass/fail gate for brand compliance before publishing. Use when asked 'is this on-brand?', 'brand compliance gate', 'can I publish this?', or in CI/CD pipelines. Verifies on-palette colors, brand fonts, anti-pattern rules, and never-say words. Returns PASS or FAIL with specific failures. Enable strict mode for soft anti-patterns. For detailed 0-100 scoring, use brand_audit_content. NOT for HTML/CSS rule checking (use brand_preflight).

Batch audit multiple content items to detect systematic brand drift. Scores each item against brand identity, computes corpus-level statistics (mean, median, stddev), and identifies recurring patterns across items (e.g., same off-palette color in 4/5 items). Writes a detailed drift report to .brand/drift-report.md. Use when reviewing a content corpus, auditing a website, or checking whether brand identity is being applied consistently across multiple pieces.

Read the compiled brand runtime contract (brand-runtime.json). Returns the brand system that AI agents load as context for on-brand output. Supports slicing: 'full' (~1200 tokens, everything), 'visual' (~200 tokens, colors + fonts + anti-patterns), 'voice' (~400 tokens, tone + vocabulary + perspective), 'minimal' (~100 tokens, primary color + heading font). Use slices when passing brand context to sub-agents — smaller context reduces token cost and agent satisficing. Live Mode aware: when enabled via brand_brandcode_live, the runtime refreshes from the hosted Brandcode runtime on each call (subject to cache TTL). Falls back silently to the local mirror on network error. Read-only. Run brand_compile to refresh.

Fast inline brand gate — check text, colors, fonts, or CSS against the compiled brand identity in under 50ms. Pass one or more inputs: text (voice violations, never-say, AI-isms), color (palette match with ΔE distance), font (typography match), css (visual anti-pattern violations). Returns pass/fail with specific fixes. Call this reflexively while generating content or code, the way you'd run a linter. Requires brand_compile to have run first. NOT for deep audits — use brand_audit_content for comprehensive scoring.

Generate a visual proof page showing the brand applied to common UI patterns — color swatches, typography hierarchy, buttons, cards, and a WCAG contrast matrix. Writes .brand/brand-preview.html. Screenshot-ready, shareable, built from brand-runtime.json only. Use when the user says "show me my brand", "preview the brand", "does this look right?", or after extraction to validate results. Requires brand_compile to have run first. NOT the full report — use brand_report for comprehensive data.

Activate Brandcode Studio connection for saving and pushing brands. Preferred mode: "activate" displays a short code (e.g. BRAND-7K4X) for the user to enter at brandcode.studio/activate — no copy-paste of tokens needed. Also supports: "status" (check auth), "login" (magic link fallback), "set_key" (manual token), "logout" (clear credentials). Use when the user wants to save their brand to Studio or says "activate", "connect to Brandcode", or "save my brand online". NOT needed for extraction, preview, or brand_check — those work without auth.

Connect a local .brand/ to Brandcode Studio. Two modes: "pull" (default) downloads an existing hosted brand by URL/slug. "save" uploads the local .brand/ to Studio (requires prior auth via brand_brandcode_auth). Use when the user says "connect to Brandcode", "pull from Studio", "save brand to Studio", or "upload my brand". Returns brand name, slug, sync token, and connection details.

Sync local .brand/ with a connected Brandcode Studio brand. Two directions: "pull" (default) fetches the latest from Studio, delta-aware via syncToken. "push" uploads local changes to Studio (requires auth via brand_brandcode_auth). Requires a prior brand_brandcode_connect. Use when the user says "sync brand", "push to Studio", "pull latest brand", or "update Studio". Returns sync mode, changed areas, and sync token. NOT for initial connection — use brand_brandcode_connect. NOT for checking status — use brand_brandcode_status.

Inspect the Brandcode Studio connection for the current project. Read-only — reads .brand/brandcode-connector.json and .brand/brandcode-sync-history.json without making network requests. Shows connected brand slug, remote URL, sync token, last sync time, sync history, local package contents, and Phase 0 Brandcode MCP URL/status. Use when the user says "brandcode status", "check connection", "am I synced?", or "show brand connection". Returns structured connection data or a clear "not connected" message with instructions to run brand_brandcode_connect. NOT for syncing — use brand_brandcode_sync to pull updates.

Enable, disable, or inspect Live Mode on the Brandcode Studio connector. When ON, read-only tools (brand_runtime, brand_check, brand_audit_content, brand_check_compliance, brand_preview, brand_status) refresh from the hosted runtime on each call, within a short cache TTL (default 60s). Governance edits in Brand Console propagate on the next call without a manual sync. Requires a prior brand_brandcode_connect and brand_brandcode_auth. Use when the user says "go live", "enable live mode", "turn off live mode", "is live mode on?", or "make brand reads live". Returns the current mode, cache freshness, and sync token. Network failures during live reads silently fall back to the local mirror.

Connect a GitHub repository to Brandcode Studio for automatic brand syncing. The repo's .brand/ directory becomes the source of truth — push changes to git and Studio picks them up every 5 minutes. Requires auth (run brand_brandcode_auth first). Use when the user says "connect my repo", "sync from GitHub", "link my brand repo", or "set up git-connected brand".

Check the health and sync status of a git-connected brand repo. Shows last sync time, commit SHA, polling health, and recent sync events. Use when the user says "repo status", "is my repo syncing?", "check git connection", or "when did it last sync?".

Generate on-brand content — load full brand context (colors, typography, logo, voice, strategy) before creating any branded output. Use when asked 'generate on-brand content', 'write something in our brand voice', 'load brand context for writing', or before creating social graphics, web pages, blog posts, emails, presentations, or data viz. Specify content_type for the right mix of visual and voice rules. Does NOT generate content itself — provides the creation brief so you can generate on-brand. Run brand_preflight on output afterward. Returns a structured creation brief with all brand layers.

Generate portable brand files for any environment — Chat, Code, team sharing, or email. Target 'chat': self-contained markdown to upload to any AI conversation (Claude, ChatGPT, Gemini). Target 'code': MCP config + CLAUDE.md/.cursorrules snippet. Target 'team': clean brand guidelines for designers and writers. Target 'email': concise 500-word summary for Slack or email. Writes to .brand/exports/ and returns the full content. Use when the user wants to share their brand system or set up a new tool.

Take a Claude Design-style auto-generated SKILL.md, diff it against this project's .brand/governance/ YAML (narrative-library, valid-proof-points, anti-patterns, application-rules, taste-codes), and return an enriched SKILL.md with missing governance content injected, cited by governance ID, and grouped into canonical sections. Additive only — never rewrites existing content. Requires a .brand/ directory with at least one governance file. The typical flow: Claude Design auto-generates a SKILL.md during onboarding → pass it to this tool → replace the original with the enriched version → every subsequent generation grounds on governed narratives, Active/Watch proof points, hard-rule anti-patterns, and taste signals. This is the low-friction wedge for putting Brandcode governance into any Anthropic-product generation surface.

Report bugs, friction, feature ideas, data quality issues, praise, or structured agent signals to the brandsystem team. Use when a tool returns an error, extraction misses data, the workflow feels harder than it should, or something works particularly well. For structured agent telemetry, use category='agent_signal' with signal, tool_used, and signal_context fields — brand context is auto-populated from .brand/config. Stored locally in ~/.brandsystem/feedback/ for developer triage. Returns a feedback ID.

Review all agent feedback stored in ~/.brandsystem/feedback/. Read-only — reads local JSON files without network access. Shows summary stats (by category, severity, status) and individual items with timestamps. Filter by category (bug, friction, feature_request, agent_signal) or status (new, quarantined, acknowledged, fixed). Quarantined items were flagged for potential prompt injection. Use to triage feedback, spot recurring issues, and prioritize fixes. NOT for submitting feedback — use brand_feedback. NOT for changing item status — use brand_feedback_triage.

Update the status of a feedback item after review. Mark as 'acknowledged' (seen, will address), 'fixed' (resolved), or 'wontfix' (intentional, won't change). Add an optional triage note.