How diagram-design Supports Multi-Client Workflows with Named Profiles

Diagram-design enables a single installation to serve multiple clients through named profiles—independent style-guide files stored in ~/.diagram-design/profiles/ that isolate each client's branding, colors, fonts, and diagram settings.

Multi-client creative work demands strict separation between brand identities. Diagram-design solves this with a profile-based architecture that keeps each client's style guide independent from the core plugin files. According to the cathrynlavery/diagram-design source code, profiles are plain Markdown files with hidden headers containing metadata, allowing teams to switch between client configurations instantly without risking cross-contamination or data loss during updates.

Understanding Named Profiles in diagram-design

A named profile is a self-contained style guide stored outside the plugin installation. Each profile exists as <slug>.md in ~/.diagram-design/profiles/ and contains:

• A hidden profile header with name, slug, source-url, creation dates, and notes
• The complete style-guide body with semantic roles and typography rules

This separation guarantees that plugin updates never touch client profiles. The installed references/style-guide.md remains the working copy, while the profile library persists safely in the user's home directory.

Profile Resolution: How diagram-design Selects the Active Style Guide

The system determines which profile to apply through a strict three-tier resolution order, as implemented in the core resolution logic:

1. Project Marker (Highest Priority)

Diagram-design checks for a .diagram-design file in the project root. If found, it reads the profile: <slug> line and loads that profile directly from the home library.

# Example marker file at <project-root>/.diagram-design

profile: acme-corp

This marker-based approach makes profile selection portable—the configuration travels with the project, enabling parallel workspaces for different clients without file conflicts.

2. Working Copy Header (Fallback)

If no marker exists, the system inspects references/style-guide.md for a profile header. The header's slug field identifies the active profile.

3. Default Comparison (Final Fallback)

When neither marker nor header is present, diagram-design compares the installed style guide against shipped defaults. Semantic or typographic differences indicate a custom-unsaved style, which the user can persist as a new profile.

Profile Isolation and Safety Mechanisms

The architecture enforces strict boundaries between clients. These safety checks operate at every stage:

Step	Action	Safety Guard
Resolve marker	Parse profile: <slug> from .diagram-design	Validates against regex [a-z0-9][a-z0-9-]{0,63}; rejects malformed or unknown slugs
Load profile	Open ~/.diagram-design/profiles/<slug>.md	Verifies structural integrity; back-fills missing rows from defaults
Copy-over	Write profile to installed style-guide.md	Re-reads to confirm exact match; offers marker-only flow if unwritable
Save	Create new profile from effective guide	Blocks default overwrite; requires confirmation for existing profiles
Update	Refresh existing profile header	Preserves original created date; refuses default modification
Delete	Remove profile file	Warns if markers or headers still reference the profile; never glob-deletes

CLI Commands for Multi-Client Workflows

The commands/profile.md implementation provides direct control over profile operations:

# List all saved profiles

diagram-design profile list

# Save current style guide as new client profile

diagram-design profile save acme

# Create project marker for "acme" profile (recommended)

diagram-design profile load acme

# Display active profile in current project

diagram-design profile show

# Update profile after style guide edits

diagram-design profile update acme

# Remove obsolete client profile

diagram-design profile delete acme

Direct Installation Switching (No Marker)

For workflows that don't use project markers:

# Overwrite installed style guide with "acme" profile

diagram-design profile switch acme

The switch command bypasses marker creation entirely, useful for single-client environments or quick previews.

Key Implementation Files

Two source files define the complete multi-client system:

• skills/diagram-design/references/profiles.md — Profile specification covering file format, slug validation rules, and structural checks https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md

• commands/profile.md — CLI verb documentation for save, load, list, show, update, reset, and delete operations https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md

Summary

• Named profiles in diagram-design are isolated Markdown files stored in ~/.diagram-design/profiles/
• Project markers (.diagram-design files with profile: <slug>) enable portable, client-specific configurations
• Three-tier resolution checks markers first, then headers, then defaults to determine the effective style guide
• Safety mechanisms prevent default profile deletion, enforce slug validation, and warn against orphaned profile references
• Plugin updates remain safe because profiles live outside the installation directory

Frequently Asked Questions

How do I set up a new client workspace in diagram-design?

Run diagram-design profile save <client-slug> to capture your current style guide as a profile. Then run diagram-design profile load <client-slug> within the client's project directory to create a .diagram-design marker file. This binds the project to that profile permanently.

What happens to my profiles when I update the diagram-design plugin?

Nothing. Profiles reside in ~/.diagram-design/profiles/, completely outside the plugin installation. Updates only modify shipped files, leaving your client library untouched.

Can two projects use different profiles simultaneously?

Yes. Each project with its own .diagram-design marker file resolves its profile independently. The installed style-guide.md is only modified when you explicitly run load or switch commands without markers.

Why does diagram-design block overwriting the "default" profile?

The default profile serves as the immutable reference point. Blocking modifications ensures every custom profile derives from a known baseline and prevents accidental corruption of the system's fallback configuration.

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