Where Are Named Client Profiles Stored in diagram-design? Complete Guide to Profile Location and Management

Named client profiles in diagram-design are stored as individual Markdown files in ~/.diagram-design/profiles/, with each profile named as <slug>.md containing a metadata header and complete style guide.

The diagram-design repository by cathrynlavery manages visual consistency across projects through client profiles — reusable style configurations that define colors, fonts, and design rules. Understanding where these profiles live on your filesystem is essential for backup, version control, and team collaboration workflows.

Profile Storage Location and File Structure

Primary Directory: ~/.diagram-design/profiles/

Diagram-design maintains a profile library in your home directory under a hidden folder. This location ensures profiles persist across project directories and remain isolated from the installed plugin code.

Aspect	Specification
Base directory	~/.diagram-design/profiles/
File format	Markdown (.md extension)
Naming convention	<slug>.md (kebab-case identifier)
Example path	~/.diagram-design/profiles/acme-corp.md

Profile File Contents

Each .md file combines YAML frontmatter metadata with free-form Markdown content:

• Required metadata header: profile, created, source-url
• Body: Complete style guide documentation for that client

The built-in default profile exists at ~/.diagram-design/profiles/default.md but is read-only — the system prevents overwriting this file to preserve baseline functionality during updates.

Profile Resolution Mechanism

When diagram-design encounters a .diagram-design marker file specifying profile: <slug>, it resolves the profile through a direct filesystem lookup:

1. Parse the profile value from the project marker
2. Construct path: ~/.diagram-design/profiles/<slug>.md
3. Load and validate the file contents

This library-first resolution means multiple projects can reference the same client profile without duplicating files, while升级s to diagram-design itself never touch your custom profiles.

Working with Stored Profiles: Code Examples

Load a Client Profile Programmatically

# Locate and read an existing client profile

import os
from pathlib import Path

home = Path.home()
profile_path = home / ".diagram-design" / "profiles" / "acme-corp.md"

if profile_path.is_file():
    with profile_path.open(encoding="utf-8") as f:
        profile_contents = f.read()
    print("Profile loaded:", profile_path)
else:
    print("Profile not found:", profile_path)

Create a New Profile via Command Line

# Initialize the profiles directory if needed

mkdir -p ~/.diagram-design/profiles

# Create a profile with required metadata header

cat > ~/.diagram-design/profiles/my-client.md <<'EOF'
profile: my-client
created: 2026-09-06
source-url: none

# My-Client Style Guide

## Colors

- Primary: #2E5BFF
- Secondary: #FF6B2E

## Typography

- Headings: Inter Bold
- Body: Inter Regular
EOF

# Optional: associate with current project

echo "profile: my-client" > .diagram-design

List All Available Profiles

# View all stored client profiles

ls ~/.diagram-design/profiles/*.md

Core Source Files Defining Profile Storage

According to the diagram-design source code, these files govern how profiles are stored, formatted, and accessed:

File	Purpose
references/profiles.md	Specification document defining library location, file format, and resolution rules
commands/profile.md	CLI implementation for list, save, load, update, reset, delete operations
prompts/profile.md	Interactive prompt definitions guiding profile management workflows
skills/diagram-design/SKILL.md	Entry point explaining profile resolution and .diagram-design marker interaction

The profiles.md reference specification is the authoritative source for storage conventions, while commands/profile.md provides the user-facing interface for manipulating files in ~/.diagram-design/profiles/.

Migration and Backup Considerations

Since profiles live in your home directory rather than project repositories:

• Back up ~/.diagram-design/profiles/ to preserve client configurations
• Sync across machines using dotfiles repositories or cloud storage
• Version control individual profiles by tracking the .md files externally

The read-only default.md ensures you always have a fallback, but custom profiles depend entirely on this directory's integrity.

Summary

• Named client profiles are stored in ~/.diagram-design/profiles/ as <slug>.md Markdown files
• Each profile contains a required metadata header (profile, created, source-url) plus style guide content
• The default profile at default.md is read-only and protected from overwrites
• Profile resolution bypasses the installed working copy, enabling shared installations across multiple clients
• Core specifications live in references/profiles.md with CLI operations defined in commands/profile.md

Frequently Asked Questions

Can I change the default profile storage location?

No. The ~/.diagram-design/profiles/ path is hardcoded in the resolution logic defined in references/profiles.md. The system relies on this consistent location to locate profiles regardless of where diagram-design is installed or invoked.

What happens if I delete a profile referenced by a project?

The project marker still specifies profile: <slug>, but profile resolution will fail at runtime. The commands/profile.md CLI does not validate cross-references when deleting — maintain your own tracking or use the list command to audit usage before removal.

How do I share client profiles with my team?

Since profiles exist outside version control, share the .md files directly. Copy files into ~/.diagram-design/profiles/ on each teammate's machine, or symlink the directory to a shared cloud storage location. The specification in references/profiles.md does not currently support remote profile fetching.

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