How to Reference a Client Profile in a Diagram-Design Project

To reference a client profile in a diagram-design project, create a marker file named .diagram-design in your project root containing profile: <slug>, where <slug> matches the filename of a stored profile in ~/.diagram-design/profiles/<slug>.md.

The cathrynlavery/diagram-design repository implements a marker-first resolution system that allows multiple workspaces to share a single installation while maintaining distinct style guides. This article explains how to create, validate, and reference client profiles using the project's marker-based configuration files and CLI tools.

Understanding the Client Profile System

A client profile is a complete snapshot of a style-guide.md stored in the user's home directory library. The system uses these profiles to override the default working copy, enabling per-project styling without modifying the global installation.

Profile Storage Location

All profile files reside in ~/.diagram-design/profiles/ as individual Markdown files named after their slug (a unique identifier). According to skills/diagram-design/references/profiles.md, each profile file contains the complete style guide content along with metadata headers indicating the display name, source URL, and creation notes.

The Project Marker File

The .diagram-design marker file serves as the configuration checkpoint. When present in the project root, this file must contain exactly one line following the grammar:

profile: <slug>

The <slug> must match the regex pattern [a-z0-9][a-z0-9-]{0,63}. Any deviation from this format—including extra whitespace, comments, or malformed slugs—causes the system to treat the marker as invalid and proceed with marker-less resolution as defined in skills/diagram-design/SKILL.md.

Setting Up a Client Profile Reference

Creating the Profile File

First, generate a profile from your current effective style guide using the CLI:

# Save current style guide as "acme" profile

diagram-design profile save acme

The command interactively prompts for a display name, source URL, and notes, then writes the file to ~/.diagram-design/profiles/acme.md.

Adding the Project Marker

Create the marker file in your project root to activate the profile:

echo "profile: acme" > .diagram-design

This single-line file instructs the diagram generation engine to bypass the installed skills/diagram-design/references/style-guide.md and load ~/.diagram-design/profiles/acme.md instead.

Validation and Slug Requirements

The engine validates the slug against the regex [a-z0-9][a-z0-9-]{0,63}. Valid slugs start with a letter or number, contain only lowercase alphanumeric characters and hyphens, and are between 1 and 64 characters long. Invalid markers trigger a silent fallback to the working copy without raising errors, as the system treats marker files as untrusted user data.

Resolving Profile References at Runtime

The resolution logic implemented in skills/diagram-design/SKILL.md follows a strict marker-first sequence:

1. Inspect the project root for .diagram-design
2. Parse the marker to extract the slug using strict grammar rules
3. Load the profile from ~/.diagram-design/profiles/<slug>.md if the slug is valid and the file exists
4. Fallback to working copy if the marker is missing, malformed, or references a non-existent profile

When falling back to the installed working copy (skills/diagram-design/references/style-guide.md), the system checks for a leading profile header to identify which profile was previously loaded, potentially prompting the user to save the current state as a new profile.

Managing Profiles via CLI

The diagram-design CLI provides verbs for profile management documented in commands/profile.md:

List available profiles:

diagram-design profile list

Switch to a different profile (writes new marker):

diagram-design profile switch beta

Update an existing profile after modifications:

diagram-design profile update acme

The switch verb either writes a new marker file or copies the profile into the working copy depending on user consent, as detailed in skills/diagram-design/references/profiles.md under the Verb procedures section.

Programmatic Profile Reference

Automate profile selection in Python scripts by writing the marker before invocation:

import subprocess
import pathlib

project_root = pathlib.Path('.')
marker = project_root / '.diagram-design'

# Write the profile marker

marker.write_text('profile: acme\n')

# Generate diagram using the referenced profile

subprocess.run(['diagram-design', 'generate', '--type', 'flowchart'])

This approach ensures CI/CD pipelines and automated workflows reference the correct client profile without manual CLI interaction.

Summary

• Client profiles are stored as complete style-guide.md snapshots in ~/.diagram-design/profiles/<slug>.md
• Project markers use a single-line .diagram-design file with the format profile: <slug>
• Marker-first resolution checks the project root before falling back to the installed working copy at skills/diagram-design/references/style-guide.md
• Slug validation requires the pattern [a-z0-9][a-z0-9-]{0,63}; invalid markers are ignored silently
• CLI tools (save, switch, update) manage profile creation and project assignment

Frequently Asked Questions

What happens if the .diagram-design marker file is missing?

The system falls back to the installed working copy located at skills/diagram-design/references/style-guide.md. As implemented in skills/diagram-design/SKILL.md, the resolution logic treats a missing marker as a signal to use the default style guide, checking for a leading profile header to determine if a previous profile was loaded.

How do I validate the profile slug format?

The slug must match the regex [a-z0-9][a-z0-9-]{0,63}. According to skills/diagram-design/references/profiles.md, valid slugs start with a lowercase letter or number, contain only alphanumeric characters and hyphens, and are between 1 and 64 characters long. The engine rejects any marker not conforming to this grammar.

Can multiple projects share the same client profile?

Yes. Any number of projects can reference the same profile slug in their respective .diagram-design marker files. Since profiles are stored centrally in ~/.diagram-design/profiles/, multiple workspaces can share a single installation without overwriting each other's styles, as documented in docs/adr/0006-client-profiles-and-marker-first-resolution.md.

Where does the system look for profile files if the marker is invalid?

If the marker contains malformed content or an invalid slug, the system proceeds with marker-less resolution and loads the working copy from skills/diagram-design/references/style-guide.md. The engine treats marker files as untrusted data and never raises errors for invalid content, instead silently defaulting to the installed style guide.

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