What Happens During the First-Run Gate in a New Diagram-Design Project?

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 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.

Running the Structural Validator

Before creating any files, the gate invokes the structural validator implemented in 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 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:

diagram-design import-mermaid ./my-diagram.mmd

Manually invoke the structural validator without auto-generating files:

diagram-design doctor

Run commands after the gate has completed (marker exists in .cache/):

diagram-design export-diagram --format svg

Use a pre-existing custom profile to skip default scaffold creation:

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: Defines profile structure and default profile resolution logic used by the gate to locate default.md.
• commands/doctor.md: Implements the structural validator that verifies project integrity during the bootstrap phase.
• skills/diagram-design/references/doctor.md: Internal reference documenting the diagnostic routines invoked by the gate.
• 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 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 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 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.

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