# How the Client Profile System Works with Project Markers in diagram-design

> Discover how the diagram-design client profile system utilizes project markers to load custom client profiles, overriding defaults for personalized workflows.

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

---

**The client profile system in diagram-design uses a hidden `.diagram-design` marker file in a project's root to determine which client-specific profile to load from `~/.diagram-design/profiles/`, bypassing the shared working copy when a valid marker is present.**

The `cathrynlavery/diagram-design` repository implements a flexible client profile system that separates shared style guides from client-specific configurations. This article explains how the **client profile system** interacts with **project markers** to load customized diagram styles based on the presence of a `.diagram-design` file.

## Profile Storage and the Default Profile

According to [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) (lines 9-23), the system maintains a strict separation between the installed working copy and user-defined profiles.

### The Profile Library Layout

Each client profile exists as a single markdown file stored in `~/.diagram-design/profiles/<slug>.md`. The system ships with a built-in `default` profile that users can **load** or **reset** to, but cannot **overwrite, update, or delete**. This ensures baseline functionality remains available even when user profiles are corrupted or missing.

### Slug Naming Constraints

Profile identifiers (slugs) must adhere to strict validation rules defined in the source at lines 30-33 of [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md). Slugs are limited to **64 ASCII characters** consisting only of letters, digits, or hyphens. The system rejects spaces, dots, slashes, and other special characters to prevent path traversal and ensure valid filenames across operating systems.

## Project Markers and Profile Resolution

The core mechanism connecting a project to a specific client profile is the **project marker** file.

### The .diagram-design Marker File

A hidden file named `.diagram-design` placed in a project's root directory controls profile selection. When this file contains exactly `profile: <slug>`, the skill **directly reads** the corresponding profile from `~/.diagram-design/profiles/` and **skips** the installed working copy entirely. The marker may also specify `profile: default` to force use of the shipped default without creating a snapshot.

Critically, as documented in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) (lines 132-135), markers are only honored after the user **explicitly consents** to write or replace them, preventing accidental project configuration changes.

### Resolution Order and Fallback Behavior

The resolution logic implemented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (lines 23-31) follows this strict hierarchy:

1. **Check for marker**: If `.diagram-design` exists and references a valid profile slug, the skill loads that profile **as-is** without copying it to the working copy.
2. **Validate marker**: If the marker is malformed or points to a non-existent profile, the skill reports the error and offers `profile list` to select a valid alternative.
3. **Fallback to working copy**: If no marker exists (or it specifies `default` with no snapshot), the skill falls back to the installed working copy. If the working copy contains only shipped defaults, the system presents the *style-guide gate* for onboarding.

## Managing Profiles via CLI Commands

The `profile` command, defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md), implements verbs that interact with both the profile library and project markers.

### Listing and Loading Profiles

The `profile list` command displays all available profiles, marking the active one—either the profile selected via project marker or the working copy header. When using `profile load <slug>` in a project with an existing marker, the skill reads the named profile but **does not copy** it over the working copy, preserving the separation between client configurations.

### Saving Profiles and Creating Markers

The `profile save <slug>` command writes the current effective style guide as a new profile file to `~/.diagram-design/profiles/`. After saving, the skill may offer to write the project marker, but this occurs **only with explicit user consent** (profiles.md lines 123-130). If the project directory is unwritable, the profile saves successfully to the home library, and the user receives a prompt to manually create the marker file containing `profile: <slug>`.

## Practical Examples

### Listing Available Profiles

```bash
$ diagram-design profile list
✔ default            # built-in (read-only)

✔ blue-brand         # user-saved profile

✔ red-client         # user-saved profile ← active (project marker)

```

### Creating a Profile and Project Marker

```bash
$ diagram-design profile save my-new-profile
✔ Saved profile to ~/.diagram-design/profiles/my-new-profile.md
? Write a project marker to use this profile for the current project? (y/N) y
✔ Wrote .diagram-design marker with `profile: my-new-profile`

```

### Loading a Profile Without Altering the Working Copy

```bash
$ cat .diagram-design
profile: blue-brand

$ diagram-design profile load blue-brand
✔ Loaded profile "blue-brand" (no copy-over, marker used)

```

### Resetting to the Default Profile

```bash
$ diagram-design profile reset default
✔ Reset to shipped default; marker removed if present

```

## Summary

- **Client profiles** are stored as individual markdown files in `~/.diagram-design/profiles/<slug>.md`, separate from the shared working copy.
- **Project markers** (`.diagram-design` files) contain a single line `profile: <slug>` that directs the skill to load a specific client configuration.
- **Resolution priority** checks for markers first, loading profiles as-is without copying, then falls back to the installed working copy if no valid marker exists.
- **User consent** is mandatory for creating or replacing project markers, preventing accidental configuration changes.
- The `profile` command provides verbs (`list`, `load`, `save`, `update`, `reset`, `delete`) to manage the library and interact with markers.

## Frequently Asked Questions

### What is the purpose of the .diagram-design project marker?

The `.diagram-design` file acts as a project marker that tells the skill which client profile to load from `~/.diagram-design/profiles/`. When present in a project's root directory with content `profile: <slug>`, it causes the skill to bypass the shared working copy and use the specified client-specific style guide directly.

### Can I override the default profile in diagram-design?

Yes, you can create custom profiles using `profile save <slug>` and activate them via project markers. While you cannot modify the built-in `default` profile itself (it is read-only), you can override its usage on a per-project basis by setting `profile: default` in a marker file or by creating and loading custom profiles that supersede the default behavior.

### How does the skill handle missing or invalid project markers?

If a `.diagram-design` marker points to a non-existent profile or contains malformed syntax, the skill reports the specific error and offers the `profile list` command to help you select a valid profile. If no marker exists at all, the system gracefully falls back to the installed working copy, potentially triggering the style-guide onboarding flow if the working copy contains only default content.

### Where are client profiles stored in diagram-design?

Client profiles are stored in the user's home directory at `~/.diagram-design/profiles/<slug>.md`, with each profile existing as a separate markdown file. This location is distinct from the installed working copy of the style guide, allowing profiles to persist across project directories and skill updates.