# What Happens During the First-Run Gate in a New Diagram-Design Project? > Understand the first-run gate in a new diagram-design project. Learn how it validates structure, creates profiles, and caches completion markers before commands run. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: internals - Published: 2026-08-21 --- **The first-run gate is a bootstrap routine that validates project structure, creates a default profile if missing, and caches a completion marker before allowing any diagram commands to execute.** When you initialize a new project using the `cathrynlavery/diagram-design` toolkit, the library intercepts your first command with a **first-run gate** that ensures the environment is properly configured. This lightweight bootstrap routine prevents runtime errors by verifying that required profiles and assets exist before any diagram generation logic runs. ## How the First-Run Gate Validates New Projects ### Detecting an Uninitialized Environment The gate checks for the presence of [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) in the `profiles/` directory. If this file is absent, the system assumes this is the project's initial execution and triggers the full bootstrap sequence according to the logic defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md). ### Running the Structural Validator Before creating any files, the gate invokes the structural validator implemented in [`commands/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/doctor.md). This routine parses existing configurations, verifies that all required fields are present, and confirms that referenced assets—such as Mermaid files or DrawIO sources—exist and are syntactically valid. ### Scaffold Generation If no profile exists, the gate automatically generates a minimal [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) scaffold in the `profiles/` directory. This placeholder configuration provides the necessary structure for the tool to operate, which users can later customize for their specific diagram requirements. ### Caching the Completion State After successful validation, the gate creates a hidden marker file inside `.cache/` to record that initialization is complete. Subsequent invocations detect this marker and bypass the gate entirely, proceeding directly to the requested command without repeating validation steps. ## Practical Command Examples Execute a command on a brand-new project to trigger the gate: ```bash diagram-design import-mermaid ./my-diagram.mmd ``` Manually invoke the structural validator without auto-generating files: ```bash diagram-design doctor ``` Run commands after the gate has completed (marker exists in `.cache/`): ```bash diagram-design export-diagram --format svg ``` Use a pre-existing custom profile to skip default scaffold creation: ```bash diagram-design --profile custom import-mermaid ./my-diagram.mmd ``` ## Core Implementation Files The first-run gate logic is distributed across several key files in the repository: - **[`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)**: Defines profile structure and default profile resolution logic used by the gate to locate [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md). - **[`commands/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/doctor.md)**: Implements the structural validator that verifies project integrity during the bootstrap phase. - **[`skills/diagram-design/references/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/doctor.md)**: Internal reference documenting the diagnostic routines invoked by the gate. - **[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)**: Explains profile file management and the mechanism for skipping the gate when valid profiles exist. ## Summary - The **first-run gate** intercepts initial commands to prevent runtime errors from missing configurations in `cathrynlavery/diagram-design`. - It validates project structure using the `doctor` command logic before any diagram operations execute. - Missing [`profiles/default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles/default.md) triggers automatic scaffold generation to ensure the tool has a valid configuration. - A marker file in `.cache/` ensures one-time execution, allowing subsequent runs to skip validation and proceed immediately. - The gate supports custom profiles via the `--profile` flag to override default behavior and bypass automatic profile creation. ## Frequently Asked Questions ### What triggers the first-run gate in diagram-design? The gate triggers when the tool detects that [`profiles/default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles/default.md) is missing, indicating an uninitialized project. This check occurs before executing any diagram generation command, ensuring the environment meets minimum requirements. ### How do I manually run the validation without creating a default profile? Invoke the `doctor` command directly. This runs the structural validator documented in [`commands/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/doctor.md) without triggering the automatic scaffold generation that occurs during the standard first-run sequence. ### Where does diagram-design store the first-run completion marker? The tool creates a hidden marker file inside the `.cache/` directory after successful initial validation. Presence of this file causes subsequent commands to bypass the gate and execute immediately. ### Can I use a custom profile to skip the first-run gate entirely? Yes. Specify an existing profile using the `--profile` flag followed by the profile name. If the specified profile exists in the `profiles/` directory, the gate assumes the project is pre-configured and proceeds directly to command execution.