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

> Learn how the `--quality showcase` flag in archify validate enforces stricter visual rules and upgrades rendering for publication-ready diagrams. Get exclusive SHOWCASE PASS receipts.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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](https://github.com/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.

```bash

# 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](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md#L97), 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`](https://github.com/tt-a1i/archify/blob/main/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

```bash
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

```bash

# 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

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