# Diagram Design profiles.md Contract: Storage, Markers, and Recovery

> Understand the profiles.md contract for Diagram Design, detailing storage locations, project markers, and default profile recovery. Learn about profile management in this technical guide.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: api-reference
- Published: 2026-08-21

---

**The [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) contract defines the complete specification for profile storage locations, project marker files, and recovery of the built-in default profile within the Diagram Design skill.**

The [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) file in the `cathrynlavery/diagram-design` repository serves as the authoritative blueprint for how the skill manages user profiles across projects. This contract governs hard-coded file paths, metadata schema validation, and the deterministic behavior of CLI verbs like `save`, `load`, and `reset`. Understanding these rules ensures safe profile persistence and reliable project-specific style guide resolution.

## Profile Storage Locations and File Paths

The contract mandates four distinct storage concepts with immutable paths that are never altered by updates.

| Concept | Path (expanded) | Purpose |
|---------|-----------------|---------|
| **Profile library** | `~/.diagram-design/profiles/` | Holds one Markdown file per named profile (`<slug>.md`). |
| **Profile file** | `~/.diagram-design/profiles/<slug>.md` | The persistent copy of a client’s style guide plus a metadata header. |
| **Working copy** | `<install-dir>/references/style-guide.md` | The active file the skill reads/writes when no project marker exists. |
| **Project marker** | `<project-root>/.diagram-design` | A tiny text file that binds a project to a specific profile (`profile: <slug>`). |

The contract insists that **profiles must never live inside an installed plugin** because the plugin directory may be replaced during an update. This separation protects user data from being overwritten during skill upgrades.

## Project Marker Contract and Resolution Logic

When a project contains a `.diagram-design` file, the skill follows a strict validation protocol before loading any profile.

### Marker File Format and Validation Rules

The skill reads the marker file as **untrusted data** and expects exactly one line matching the pattern `profile: <slug>`. Whitespace is allowed, and a final newline is optional. The extracted `<slug>` must validate against the regex `[a-z0-9][a-z0-9-]{0,63}`.

If validation succeeds, the skill **directly reads** the corresponding profile file from the library (`~/.diagram-design/profiles/<slug>.md`) and uses it as the effective style guide. No copy-over to the installed working copy occurs.

### Fallback Behavior for Invalid Markers

If the marker is missing, malformed, or contains an invalid slug, the skill **ignores** the marker with a one-line explanation and falls back to marker-less resolution. This prevents path traversal attacks and ensures deterministic behavior even with corrupted project metadata.

```text

# Example: Creating a valid project marker

echo "profile: acme" > .diagram-design

```

## Profile File Format and Metadata Schema

Each profile file is a standard [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with a single leading metadata comment that follows a strict **strip-then-prepend** rule.

```markdown
<!-- diagram-design-profile
name: Acme Corporation
slug: acme
source-url: https://example.com
created: 2026-08-14
updated: 2026-08-14
notes: Primary web brand
-->

# Style Guide

…

```

### The Strip-then-Prepend Rule

Before any save or update operation, the skill **strips** any existing metadata header, then **prepends** a freshly rendered header containing current timestamps. The body content after the header is copied **byte-for-byte**; the skill never rewrites token values inside the style guide tables.

### Date Formats and Optional Fields

The contract requires **dates to use `YYYY-MM-DD` format**. Missing optional fields must be explicitly expressed as `none` rather than being omitted. This schema consistency ensures that parsing remains deterministic across different versions of the skill.

## Default Profile Recovery and Initialization

The built-in `default` profile serves as a recovery copy of the pristine [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) shipped with the package.

### Default.md Initialization from Pristine Source

On first-run (or when [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) is absent), the skill performs the following recovery procedure:

1. **Reads** the pristine shipped file from the installation directory.
2. **Creates** the profile library directory (`mkdir -p ~/.diagram-design/profiles`).
3. **Writes** [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) with a freshly rendered header where `slug: default`.

Subsequent `reset` commands simply **load** this [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) profile. No snapshot of a customized style guide may ever become `default`, ensuring a clean recovery path.

### Corruption Handling and Reset Behavior

If the shipped pristine copy cannot be read (e.g., the install is corrupted), the skill reports that the *default snapshot could not be created* and disables the `reset` verb until a clean package is available. This prevents the propagation of corrupted baseline data.

```bash

# Example: Resetting to the built-in default

diagram-design profile reset

# The skill ensures ~/.diagram-design/profiles/default.md exists,

# then loads it either via the marker or by copying over the working copy

```

## Structural Validation and Schema Back-filling

Before every generation, the skill runs a **current-schema structural check** (implemented around lines 96-105 in the contract logic). This validation:

- Ensures required rows exist in the `### Semantic roles` table and the `## Typography` table.

- Back-fills missing rows from the current pristine defaults, leaving existing values untouched.
- Offers an `update <slug>` command to persist the repaired snapshot to the profile library.

This mechanism ensures that legacy profiles remain compatible with new skill versions without overwriting user customizations.

## CLI Verb Procedures and Contract Compliance

All public verbs defined in the contract obey the storage-marker-recovery rules:

- **`save <slug>`**: Strips existing headers, prepends fresh metadata, and writes to `~/.diagram-design/profiles/<slug>.md`. Optionally updates the working copy header.
- **`load <slug>`** (or **`switch <slug>`**): Writes the chosen profile over the working copy **only** when no marker exists; otherwise updates the project marker file.
- **`reset`**: Defined as "load `default`", following the same marker-aware flow to restore the pristine baseline.
- **`delete <slug>`**: Never removes the library directory, only the requested file, after confirming the slug is not `default` (which is protected).

```bash

# Example: Saving the current style guide as a new profile

diagram-design profile save acme

# The skill strips headers, prepends fresh metadata with today's date,

# and writes to ~/.diagram-design/profiles/acme.md

```

## Summary

- The [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) contract hard-codes paths to `~/.diagram-design/profiles/` for persistent storage and `<project-root>/.diagram-design` for project markers.
- Profile files use a metadata header format with mandatory `YYYY-MM-DD` dates and a **strip-then-prepend** update rule.
- The project marker binds directories to profiles via a `profile: <slug>` line validated against `[a-z0-9][a-z0-9-]{0,63}`.
- Recovery relies on a pristine [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) generated from the shipped [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), with safeguards against installation corruption.
- Structural checks (lines 96-105) back-fill missing schema rows without overwriting existing values.

## Frequently Asked Questions

### What happens if the `.diagram-design` marker file contains an invalid slug?

The skill validates the slug against the regex `[a-z0-9][a-z0-9-]{0,63}`. If validation fails, the skill **ignores** the entire marker, outputs a one-line explanation indicating "invalid slug", and falls back to marker-less resolution. This security measure prevents path traversal and ensures the skill never attempts to load files outside the profile library.

### How does the skill protect user profiles during plugin updates?

According to the contract, profiles must never reside inside the installed plugin directory. The skill stores all user data in `~/.diagram-design/profiles/`, which is external to `<install-dir>`. Because these paths are hard-coded and never altered by updates, replacing the plugin directory during an upgrade leaves user profiles untouched.

### What is the difference between the working copy and the profile library?

The **working copy** at `<install-dir>/references/style-guide.md` acts as a scratch pad that the skill reads and writes when no project marker is present. The **profile library** at `~/.diagram-design/profiles/` contains the canonical named profiles (`<slug>.md`). When a valid project marker exists, the skill bypasses the working copy entirely and reads style guide data directly from the library file specified by the marker.

### How does the skill handle a corrupted installation when creating the default profile?

If the skill cannot read the pristine shipped [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) during initialization, it reports that the default snapshot could not be created and disables the `reset` command. This prevents the generation of a corrupted [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) file. The skill will continue to operate with existing user profiles, but recovery to the built-in default remains unavailable until a clean package installation restores the pristine reference file.