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.

Inspect and resolve disagreements between brand sources — when web extraction says one primary color, Figma says another, and the PDF guidelines say a third. Mode 'show' lists every conflicting field across web/visual/figma/guidelines/manual sources with each source's value, confidence, and the recommended winner per brand.config.yaml source_priority. Mode 'resolve' commits one source as the winner for a specific field (requires field + source). Use when brand_audit reports conflicts, after ingesting multiple sources, or when colors/fonts/logos look inconsistent in compiled outputs. Returns the conflict list in show mode, or the updated field value in resolve mode. Run brand_compile after resolving to refresh tokens and runtime artifacts. NOT for validating .brand/ structure (use brand_audit) or scoring content (use brand_audit_content).

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 the buyer journey stages a content strategy targets — the path from first touch to decision. Ships with 4 defaults that work for most B2B brands (First Touch, Context & Meaning, Validation & Proof, Decision Support), each with buyer mindset, content goal, story types, narrative elements, claims policy, and tone shift. Mode 'interview' presents the defaults as a table and prompts for customization. Mode 'record' writes the final stages to .brand/strategy.yaml — pass answers as a JSON array of stage objects (or a single stage to update one), or omit to accept the defaults verbatim. Mode 'view' returns the current stages. Use during Session 4 (content strategy) after personas/themes are sketched. Returns stage definitions and writes strategy.yaml in record mode. After this, run brand_build_personas.

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).

Publish-time brand gate — single PASS/FAIL verdict on a finished piece of content before it ships. Use when asked 'can I publish this?', 'is this ready to ship?', or in CI/CD pipelines that block on brand violations. Verifies on-palette colors, brand fonts, anti-pattern rules, and never-say words across the whole input. Strict mode also fails on soft (advisory) anti-patterns. Returns PASS or FAIL with the specific failures. NOT for mid-stream linting while writing — use brand_check for fast per-field feedback. NOT for 0-100 scoring or drift analysis — use brand_audit_content. NOT for HTML/CSS structural rules — 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.

Inline brand linter — call this WHILE writing content or code, the way you call a type-checker. <50ms pass/fail on any combination of text (voice/never-say/AI-isms), color (palette match with ΔE distance), font (typography match), or css (anti-pattern violations). Designed for tight loops: write a sentence, brand_check it, fix, continue. Returns specific actionable fixes per failed input. Requires brand_compile to have run first. NOT a publish-time gate — use brand_check_compliance for the single PASS/FAIL verdict before shipping. NOT for 0-100 scoring — use brand_audit_content. NOT for HTML/CSS rule violations — use brand_preflight.

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.

Bundle the compiled brand system into a portable artifact for a specific destination. Use when asked 'share my brand', 'export for ChatGPT/Cursor/team', 'generate brand guidelines', 'make a one-pager', or 'create a brand PDF'. Target 'chat': self-contained markdown for upload to any AI conversation (Claude, ChatGPT, Gemini). Target 'code': MCP server config + CLAUDE.md/.cursorrules snippet. Target 'team': human-readable brand guidelines for designers/writers/marketers. Target 'email': ~500-word summary for Slack or email. Target 'claude-skill': SKILL.md with embedded logo + rules for persistent Claude artifacts. Target 'pdf': branded PDF with swatches, type, anti-patterns, and voice. Set include_logo=false to drop the embedded SVG/data URI when size matters. Writes to .brand/exports/ and returns the full content (markdown targets) or a generation summary (pdf). Requires brand_compile to have run first. NOT for previewing one section — use brand_preview.

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.

Send a feedback signal to the brandsystem team about a tool or workflow. Use when a tool errors, extraction misses obvious data, the workflow felt harder than it should, an agent's path got blocked, or something worked particularly well and should be preserved. Set category to one of: 'bug' (broken), 'friction' (works but painful), 'feature_request' (capability missing), 'data_quality' (results wrong/incomplete), 'praise' (worth keeping), 'agent_signal' (structured telemetry — also pass signal + tool_used + signal_context; brand context auto-fills from .brand/config). Provide a one-line summary plus optional detail/severity/context. Writes to ~/.brandsystem/feedback/ AND attempts a fire-and-forget POST to brandcode.studio (drains backlog if previously offline). Returns the feedback ID and remote-send status. NOT for reading existing feedback — use brand_feedback_review. NOT for changing item status — use brand_feedback_triage.

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.