# How the Client Profile Marker Resolution System Works in Diagram Design

> Learn how the client profile marker resolution system works in diagram design. Discover how .diagram-design files prevent workspace clashes and ensure effective style guide application.

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

---

**Diagram Design resolves the effective style guide for every diagram generation by first inspecting a project-root marker file named `.diagram-design`, which isolates client profiles so that parallel workspaces never clash on a shared [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).**

The `cathrynlavery/diagram-design` repository implements a robust client profile marker resolution system that keeps client-specific style guides isolated across parallel workspaces. This marker-first architecture ensures that the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is never overwritten when a marker is present, preserving plugin files across updates while allowing precise control over which profile governs each project.

## Marker-First Resolution Flow

### Inspecting the Project Marker

When Diagram Design initiates diagram generation, it first checks for the existence of a marker file at `<project-root>/.diagram-design`. This file acts as a trusted pointer that determines which client profile to load. According to the skill definition in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (lines 23-24), the system reads this marker as untrusted data that must match a strict grammar before proceeding.

The marker file must contain exactly:

```text
profile: <slug>

```

Where `<slug>` identifies the specific client profile to load.

### Validating the Profile Slug

The extracted slug undergoes strict validation against a regular expression defined in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) (lines 71-78). The slug must match the pattern:

```

[a-z0-9][a-z0-9-]{0,63}

```

This constraint ensures lowercase alphanumeric characters and hyphens only, preventing filesystem conflicts and ensuring cross-platform compatibility. Invalid slugs trigger an immediate fallback to marker-less resolution.

### Loading from the Profile Library

Once validated, Diagram Design loads the corresponding profile directly from the user's home-directory library at:

```

~/.diagram-design/profiles/<slug>.md

```

This direct read operation bypasses any copy-over of the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), ensuring that plugin updates never overwrite client-specific customizations. As documented in ADR 0006 (lines 65-84), this approach maintains strict isolation between parallel workspaces by keeping profile resolution external to the plugin installation directory.

## Fallback Resolution and Edge Cases

### The Default Profile Shortcut

The marker may specify `profile: default` as a special case. When detected, the system loads the built-in [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) profile and skips the onboarding gate entirely. This provides a fast path for projects that require standard styling without custom overrides.

### Marker-Less Resolution

If the `.diagram-design` marker is absent, malformed, or references a non-existent profile, the system executes **marker-less resolution**. It reads the installed [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md), scans for a leading profile header, and determines whether the guide represents a custom-unsaved configuration or the shipped default. This fallback mechanism ensures backward compatibility for legacy projects while encouraging migration to the marker-based system.

## Schema Validation and Back-Fill

After loading any profile—whether via marker or fallback—Diagram Design performs a **current-schema structural check** as defined in the profiles reference. This validation ensures the profile contains all required semantic-role rows and typography entries defined by the current schema version.

Missing rows are automatically back-filled from the pristine shipped guide. The system then offers the user an `update <slug>` command to persist the repaired snapshot, ensuring profiles remain forward-compatible as the schema evolves.

## CLI Workflow Examples

The following commands demonstrate the complete marker-based workflow:

```bash

# 1. Save the current style guide as a new profile

diagram-design profile save acme

# => creates ~/.diagram-design/profiles/acme.md and offers to write the marker

# 2. Add a marker to the project so it always uses the saved profile

echo "profile: acme" > .diagram-design

# (or run the command that writes the marker for you)

diagram-design profile load acme   # writes the marker if you approve

# 3. Generate a diagram – the system will resolve the marker first

diagram-design draw flowchart my-diagram.yml

# → reads ~/.diagram-design/profiles/acme.md directly; no copy-over occurs

```

## Summary

- **Marker isolation**: The `.diagram-design` file at the project root acts as the single source of truth for profile selection, preventing workspace collisions.
- **Validated slugs**: Profile identifiers must match the `[a-z0-9][a-z0-9-]{0,63}` pattern defined in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) (lines 71-78).
- **Direct library reads**: Valid markers trigger direct reads from `~/.diagram-design/profiles/<slug>.md`, never touching the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).
- **Graceful degradation**: Missing or invalid markers fall back to scanning the installed style guide per the logic in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) (lines 23-24).
- **Schema integrity**: Automatic back-filling from the shipped guide ensures profiles remain complete and upgrade-safe.

## Frequently Asked Questions

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

The system falls back to **marker-less resolution**, reading the installed [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) to determine if a custom profile header exists. If no header is found, it treats the guide as either a custom-unsaved configuration or the default shipped version. This ensures existing projects continue to function while encouraging adoption of the marker system.

### How does the system validate profile slugs?

Slugs are validated against the regular expression `[a-z0-9][a-z0-9-]{0,63}` as defined in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) (lines 71-78). The pattern requires lowercase alphanumeric starting characters, permits hyphens, and limits length to 64 characters to ensure filesystem safety and parsing reliability.

### Where are client profiles stored on disk?

Client profiles reside in the user's home directory at `~/.diagram-design/profiles/<slug>.md`. This location separates client customizations from the plugin installation, ensuring that updates to Diagram Design never overwrite saved profiles and that profiles remain available across multiple projects via marker references.

### Why does the system use marker-first resolution instead of modifying [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)?

According to ADR 0006 (lines 65-84), marker-first resolution keeps parallel workspaces isolated by externalizing profile selection from the plugin files. This architecture prevents the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) from being overwritten when switching between client contexts, enables version control of profile assignments per project, and allows the plugin to update its default guides without risking client data loss.