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

> Learn to reference a client profile in a diagram-design project by creating a marker file in your project root. Easily link client data to your diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```text
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash

# 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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md):

**List available profiles:**

```bash
diagram-design profile list

```

**Switch to a different profile (writes new marker):**

```bash
diagram-design profile switch beta

```

**Update an existing profile after modifications:**

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). As implemented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.