# How Client Profiles Work and Resolve Across Different Project Contexts in Diagram Design

> Discover how Diagram Design client profiles work and resolve across project contexts. Learn about profile markers and automatic style-guide merging for efficient design.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-15

---

**Client profiles in Diagram Design are named, version-controlled style-guide snapshots stored in `~/.diagram-design/profiles/`, resolved first by project marker (`profile: <slug>` in `.diagram-design`) or by copying profile contents into the working [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) when no marker exists.**

Managing visual consistency across multiple clients is a core challenge in design systems. The Diagram Design plugin solves this through **client profiles**—reusable, namespaced configurations that eliminate the need to manually edit [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) for every project change. This article explains how profiles are stored, validated, and resolved depending on whether your project uses a marker file.

## What Are Client Profiles?

A **client profile** is a complete, self-contained style guide (semantic roles, typography tables, and component definitions) saved as a single markdown file with a mandatory metadata header. Profiles enable:

- **Multi-tenant workflows**: One Diagram Design installation serves many customers
- **Version control**: Each profile is a discrete file that can be tracked, branched, or archived
- **Instant context switching**: Load "acme-corp" styling for one project, "beta-healthcare" for another

### Profile Storage Architecture

| Component | Location | Purpose |
|-----------|----------|---------|
| **Profile library** | `~/.diagram-design/profiles/` | Central directory for all profile files |
| **Profile file** | `~/.diagram-design/profiles/<slug>.md` | Individual named configuration |
| **Built-in default** | [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) in profile library | Read-only baseline, auto-created on first use |
| **Project marker** | `.diagram-design` in project root | Optional override pointing to a specific profile |
| **Working-copy header** | `profile:` line in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) | Records which profile was last loaded (copy-over mode) |

As defined in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md), the profile file format requires a header like:

```markdown
profile: acme-corp

# Semantic Roles

...

```

## How Profile Resolution Works

Diagram Design applies a **strict priority order** when determining which style guide to use. This ensures predictable behavior whether you're working in a marked project or experimenting ad hoc.

### Rule 1: Marker-First Resolution (Preferred)

If a `.diagram-design` file exists and contains a valid `profile: <slug>` line, the plugin **reads directly from `~/.diagram-design/profiles/<slug>.md`** without modifying the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

This guarantees:
- Project isolation from plugin updates
- No accidental overwrites of shared configuration
- Immediate reflection of profile library changes

If the marker references a missing profile, the user is prompted to select from available slugs (`profile list`) before proceeding.

### Rule 2: Copy-Over Resolution (Fallback)

When no `.diagram-design` marker exists, running `profile load <slug>` **copies the full profile content into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)**, overwriting after explicit confirmation. The working copy receives a fresh `profile:` header tracking the loaded slug.

Use this mode for:
- Quick experimentation without project commitment
- Projects that don't need permanent profile binding
- Legacy workflows predating the marker system

### Rule 3: Default Profile Handling

The `default` profile is reserved and protected:
- Cannot be overwritten by user saves
- Auto-created from shipped defaults if absent
- Loadable without marker creation

Per [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) [L53](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md#L53), the first save or load operation triggers default snapshot creation if needed.

## Profile Validation and Integrity

Diagram Design enforces strict constraints to prevent malformed configurations from corrupting projects.

### Slug Constraints

Valid profile slugs must match:
- Maximum 64 characters
- Lower-case ASCII only
- Letters, digits, and hyphens exclusively
- `default` is reserved and cannot be used for custom profiles

Invalid slugs are rejected at parse time with clear error messages.

### Schema Back-Filling

When loading any profile, Diagram Design compares semantic-role and typography tables against shipped defaults. Missing rows are **automatically back-filled**, and the user is offered `profile update <slug>` to persist the repaired snapshot to the library. This maintains forward compatibility as the schema evolves.

## Resolution Differences by Project Context

| Context | Resolution Path | Key Behavior | Typical Commands |
|---------|-----------------|--------------|----------------|
| **Marked project** (`profile: acme` in `.diagram-design`) | Direct read from library | No write to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md); profile updates reflect immediately | `profile list`, `profile show`, `profile delete <slug>` |
| **Unmarked project** | Copy-over to working copy | Explicit confirmation before overwrite; header tracks active profile | `profile load <slug>`, `profile save <slug>`, `profile update <slug>` |
| **First-time setup** | Default creation + selection | Pristine [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) generated if missing | `profile load default` |
| **Broken marker** | Fallback to working copy | Warning issued; user offered marker rewrite | `profile load <slug>` with correction prompt |

These behaviors are codified in **ADR 0006** ([`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)) and enforced by validation scripts.

## Practical Command Reference

```bash

# List all saved profiles with active indicator

diagram-design profile

# Save current effective style guide as new profile

diagram-design profile save acme-corp

# Load profile into current project (copy-over if unmarked)

diagram-design profile load acme-corp

# Create permanent project marker

echo "profile: acme-corp" > .diagram-design

# Show active profile and source file location

diagram-design profile show

# Update library profile after schema back-fill

diagram-design profile update acme-corp

```

All commands route through the implementation documented in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) and [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md).

## Key Implementation Files

| File | Responsibility |
|------|--------------|
| [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) | Canonical profile format, resolution rules, and validation logic |
| [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) | User-facing command syntax and examples |
| [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md) | Agent prompt definitions for Pi/Claude integration |
| [`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) | Architectural rationale for marker-first design |
| [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) | Ensures profile surface documentation stays synchronized |

## Summary

- **Client profiles** are named, version-controlled snapshots stored in `~/.diagram-design/profiles/<slug>.md`
- **Resolution is marker-first**: a valid `.diagram-design` file bypasses the working copy entirely
- **Copy-over mode** activates when no marker exists, explicitly confirming before overwriting [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)
- **The `default` profile** is protected and auto-generated, serving as a stable baseline
- **Schema back-filling** maintains compatibility as Diagram Design evolves, with optional persistence via `profile update`
- All behaviors are validated by [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py) and documented in **ADR 0006**

## Frequently Asked Questions

### What happens if I delete a profile that's referenced by a project marker?

Diagram Design detects the missing profile during resolution, informs you which slug is missing, lists available alternatives (`profile list`), and prompts you to select a replacement before proceeding. The marker is not automatically rewritten until you confirm.

### Can I use the same profile across multiple projects simultaneously?

Yes. Multiple projects can reference the same profile via their `.diagram-design` markers. Each project reads from the shared `~/.diagram-design/profiles/<slug>.md` without interference. Updates to the profile file reflect immediately in all marked projects on their next operation.

### Why does copy-over mode require confirmation while marker mode doesn't?

Copy-over modifies your working [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), which may contain uncommitted changes. Marker mode performs read-only operations against the profile library, presenting no data-loss risk. This distinction protects accidental overwrites in unmarked projects while keeping marked projects frictionless.

### How do I migrate an unmarked project to use marker-based resolution?

Run `profile load <slug>` to ensure your working copy matches the desired profile, then create the marker with `echo "profile: <slug>" > .diagram-design`. Future operations will read directly from the library. Optionally delete the `profile:` line from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) to avoid confusion, though it's ignored when the marker is present.