How to Set Up and Use the Client Profile System for Multiple Brands

The Diagram Design client profile system for multiple brands enables a single installation to serve unlimited clients by storing each brand's style guide as an isolated profile in ~/.diagram-design/profiles/, which you activate via project markers or explicit CLI commands.

The cathrynlavery/diagram-design repository solves the multi-brand workflow problem through a robust profile management system defined in skills/diagram-design/references/profiles.md. Instead of maintaining separate software copies or constantly overwriting style-guide.md, you create persistent client profiles that capture complete brand configurations with metadata headers. This guide covers initializing your profile library, creating brand snapshots, and switching between them using the CLI wrapper implemented in commands/profile.md.

Initializing the Profile Library

Before creating your first client profile, ensure the library directory exists:

mkdir -p ~/.diagram-design/profiles

The system automatically generates a built-in default profile on first use. This pristine copy of the shipped style-guide.md serves as your fallback baseline, so you do not need to create it manually. According to the reference implementation, the default snapshot initializes automatically when you first execute a save or load operation if it does not already exist.

Creating Brand Profiles

To capture a new brand configuration, use the save verb. This serializes the current effective style guide into a named profile:

diagram-design profile save acme

The command executes the procedure defined in lines 10-21 of the profiles reference:

1. Reads the current effective style guide (working copy or previously loaded profile)
2. Prompts for display name, optional source-url, and optional notes
3. Validates the slug (acme) against the pattern ^[a-z0-9][a-z0-9-]{0,63}$
4. Strips any existing metadata comment and prepends a fresh header with created and updated timestamps
5. Writes the file to ~/.diagram-design/profiles/acme.md
6. Marks the profile active by writing profile: acme to the current directory's .diagram-design marker (after confirmation)

Switching Between Client Profiles

Activate a specific brand profile using the load verb or the shorthand syntax:

# Shorthand (defaults to load)

diagram-design profile acme

# Explicit verb

diagram-design profile load acme

As implemented in lines 25-35 of skills/diagram-design/references/profiles.md, this command:

1. Validates the slug against the regex pattern
2. Reads the canonical profile file from the library
3. Runs the current-schema structural check to back-fill any missing rows from newer schema versions (see lines 99-104)
4. Replaces any existing .diagram-design marker with profile: acme (after confirmation), leaving the installed style-guide.md untouched
5. If no marker exists, copies the full profile over style-guide.md and offers to create a marker for persistence

Managing Your Profile Inventory

Listing All Profiles

View every saved brand configuration with:

diagram-design profile list

This command inspects ~/.diagram-design/profiles/ and renders a table showing each profile's display name, slug, source-url, and updated date, highlighting the currently active profile. See the list verb specification in lines 37-44 of the reference documentation.

Inspecting Active Configuration

Check which profile is currently governing your diagrams:

diagram-design profile show

This outputs the active profile's name, slug, source file path, dates, and notes. If the working copy contains unsaved modifications, it reports custom-unsaved. If you have not yet created any snapshots, it displays default (not yet snapshotted).

Updating Existing Profiles

When you modify a style guide and need to overwrite an existing brand snapshot:

diagram-design profile update acme

This rewrites ~/.diagram-design/profiles/acme.md with the current effective style guide, preserving the original created date while updating the updated timestamp. You may also edit source-url and notes during this operation (lines 50-57).

Resetting to Factory Defaults

To discard customizations and return to the built-in default:

diagram-design profile reset

Equivalent to diagram-design profile load default, this command ensures default.md exists and activates it, either by updating the project marker or overwriting the working copy (lines 59-65).

Removing Obsolete Profiles

Delete a brand profile permanently:

diagram-design profile delete acme

After confirmation, this removes ~/.diagram-design/profiles/acme.md. If any project marker still references the deleted slug, the system warns you and offers to reassign the marker to default or another existing profile (lines 67-73).

Understanding Profile Resolution

When generating diagrams, the engine resolves the effective style guide through a specific hierarchy defined in lines 65-84 of the reference:

1. Project marker (<project-root>/.diagram-design) — If the file contains a valid profile: <slug> line, the system reads that profile directly
2. Working copy header — If the installed style-guide.md begins with a profile header naming an existing slug, that profile becomes active
3. Custom-unsaved detection — If semantic roles or typography tokens differ from shipped defaults, the guide is classified as custom-unsaved and you are prompted to save it

This resolution order ensures that different brand projects never interfere with each other, even within the same repository checkout.

Multi-Brand Workflow Example

Assume you manage three brands: Acme, BetaCo, and Gamma Ltd.

First, create the profiles:

diagram-design profile save acme
diagram-design profile save betaco
diagram-design profile save gamma-ltd

Then switch contexts per project:

# Acme project

cd /path/to/acme-project
diagram-design profile load acme

# BetaCo project

cd /path/to/betaco-project
diagram-design profile load betaco

Each directory now contains its own .diagram-design marker file specifying profile: acme or profile: betaco. When you run diagram-design draw in either location, the engine automatically applies the correct brand styling without additional flags.

Summary

• Initialize once: Create ~/.diagram-design/profiles/; the system handles the default snapshot automatically
• Save brand configurations: Use diagram-design profile save <slug> to capture snapshots with metadata headers
• Switch contexts: Use diagram-design profile load <slug> to write project markers that persist brand selection per directory
• Maintain inventory: Use list, show, update, and delete verbs to manage your profile library
• Resolution priority: The system checks project markers first, then working copy headers, ensuring isolated brand environments

Frequently Asked Questions

How does the Diagram Design client profile system store multiple brand configurations?

The system stores each brand as a separate Markdown file in ~/.diagram-design/profiles/<slug>.md. Each file contains a complete copy of the style guide with a metadata header tracking the display name, creation date, source URL, and notes. This approach keeps brand configurations isolated from the core installation and allows instant switching without file conflicts.

What is the difference between diagram-design profile save and diagram-design profile update?

The save verb creates a new profile from the current effective style guide, validating the slug and prompting for initial metadata. The update verb overwrites an existing profile file with the current working copy while preserving the original created date. Use save for new brands; use update when refining existing brand guidelines that have already been snapshotted.

Why does the system use a .diagram-design marker file instead of modifying style-guide.md directly?

The marker file (<project-root>/.diagram-design) containing profile: <slug> serves as a persistent pointer that survives repository clones and does not require modifying tracked files. This design allows the same repository to host multiple brand-specific subdirectories, each with its own marker, while keeping the actual style-guide.md file generic or unmodified in version control.

What happens if I delete a profile that is still referenced by a project marker?

The system detects the orphaned reference during the next resolution cycle and warns you that the marker points to a non-existent slug. It then offers to update the marker to default or another existing profile, preventing generation failures while maintaining project continuity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}