How the `--quality showcase` Flag Works in `archify validate`: A Complete Guide

The --quality showcase flag in archify validate overrides the default quality profile to enforce stricter visual composition rules, emit a special SHOWCASE · PASS receipt, and upgrade rendering output for publication-ready diagrams.

archify validate is the command-line validation engine for the tt-a1i/archify diagram toolchain. By default, it runs diagrams through the standard quality profile, but the --quality showcase flag switches to a stricter regime designed for public-facing, publication-quality output. This article breaks down exactly what changes when you use this flag, where the logic lives in the source code, and how to apply it in practice.

What --quality showcase Actually Does

When you append --quality showcase to a validate command, Archify performs four distinct behaviors that differ from the default profile.

1. Overrides Source Profile Metadata

The CLI parser in archify/bin/archify.mjs (lines 64-72) validates the --quality flag and forces its value to take precedence over any meta.quality_profile field embedded in the diagram's JSON source. This means explicit command-line control always wins.

# Even if the JSON defines "standard", this forces showcase

archify validate workflow diagram.json --quality showcase

2. Enforces Stricter Composition Rules

According to the CHANGELOG.md, the showcase profile tightens several visual-quality thresholds:

• Interior X-crossings become blocking errors instead of warnings
• Bend count per connector is capped lower
• Node spacing requirements are stricter

These checks ensure diagrams meet professional presentation standards.

3. Emits a Dedicated Receipt

Passing validation under the showcase profile generates a SHOWCASE · PASS receipt in the output. This structured artifact is designed for downstream consumption—CI pipelines, publishing workflows, or quality gates that need programmatic verification of showcase-grade compliance.

4. Influences Rendering and Delivery

Because validate, render, and deliver share the same quality-profile pipeline, the --quality showcase flag also affects:

• SVG export fidelity (higher resolution, cleaner curves)
• HTML artifact generation
• Final delivery packaging

Using the flag consistently across commands ensures the rendered output actually satisfies the validation rules it was checked against.

Source Code Locations

Understanding where this behavior is implemented helps with debugging and extension.

File	Relevant Lines	Purpose
archify/bin/archify.mjs	64-72	CLI parsing, flag validation, profile override logic
archify/test/cli.test.mjs	—	Test coverage for profile overriding and error handling when invalid profiles are supplied
CHANGELOG.md	97	Feature introduction and behavior documentation

The CLI entry point demonstrates that --quality accepts only standard or showcase, with validation failing fast if another value is provided.

Practical Usage Examples

Basic Validation with Showcase Profile

archify validate workflow examples/agent-tool-call.workflow.json \
    --quality showcase --json

This outputs structured JSON including the SHOWCASE · PASS receipt if validation succeeds, or detailed composition errors if the stricter checks fail.

Render-Then-Validate Workflow

# First render with showcase quality

archify render workflow examples/agent-tool-call.workflow.json out.html \
    --quality showcase

# Then validate the rendered artifact

archify validate workflow out.html --quality showcase --json

Both steps must use the same profile to guarantee consistency between what's rendered and what's validated.

CI-Friendly Delivery Pipeline

archify deliver workflow examples/agent-tool-call.workflow.json final.html \
    --quality showcase --open --json

The deliver command bundles render, validate, and artifact generation. The --quality showcase flag propagates through all three phases, failing the entire pipeline if any phase doesn't meet showcase standards.

When to Use Showcase vs. Standard

Scenario	Recommended Profile
Draft iteration, internal review	standard (default)
Public documentation, blog posts, presentations	showcase
Automated CI quality gates for published diagrams	showcase
Quick debugging of rendering issues	standard

The showcase profile adds validation overhead—use it when visual polish matters, not during rapid iteration.

Summary

• --quality showcase overrides any embedded meta.quality_profile in the source JSON
• Stricter composition rules block common layout imperfections like excessive bends or tight X-crossings
• SHOWCASE · PASS receipt provides machine-verifiable proof of quality for CI pipelines
• Shared pipeline means the flag affects validate, render, and deliver commands consistently
• Implementation lives in archify/bin/archify.mjs with test coverage in archify/test/cli.test.mjs

Frequently Asked Questions

What happens if I pass an invalid quality profile?

Archify validates the --quality flag immediately in archify/bin/archify.mjs and exits with an error if the value isn't standard or showcase. The test suite in archify/test/cli.test.mjs locks in this behavior.

Does --quality showcase affect diagram layout or just validation?

Both. The profile affects validation rules first, but because render and deliver use the same quality pipeline, the flag also influences export resolution, SVG curve rendering, and HTML artifact generation. Always use consistent --quality values across commands in the same workflow.

Can I set showcase as the default for all commands?

The source code shows no environment variable or config file mechanism for defaulting to showcase—you must specify --quality showcase explicitly each time. This design ensures the stricter, slower checks are opt-in.

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