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

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 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 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 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	Records which profile was last loaded (copy-over mode)

As defined in skills/diagram-design/references/profiles.md, the profile file format requires a header like:

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.

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, 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 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; 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 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) and enforced by validation scripts.

Practical Command Reference

# 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 and prompts/profile.md.

Key Implementation Files

File	Responsibility
skills/diagram-design/references/profiles.md	Canonical profile format, resolution rules, and validation logic
commands/profile.md	User-facing command syntax and examples
prompts/profile.md	Agent prompt definitions for Pi/Claude integration
docs/adr/0006-client-profiles-and-marker-first-resolution.md	Architectural rationale for marker-first design
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
• 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 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, 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 to avoid confusion, though it's ignored when the marker is present.

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