How to Manage Brand Identities with Archify's `brands` Command

Archify's brands command lets you attach deterministic vector badges to diagram nodes by selecting from 107 built-in marks or capturing external logos with cryptographic pinning for reproducible rendering.

The tt-a1i/archify repository treats brand identity as a first-class architectural primitive. By attaching brands to the primary nodes of architecture, workflow, sequence, data-flow, or lifecycle diagrams, you render compact, deterministic badges in the upper-right corner without overriding node topology or semantic meaning.

Understanding Archify's Brand Identity System

In Archify, a brand functions as an immutable identity marker rather than decorative metadata. When attached to a node, it produces a provenance-backed vector mark that clearly identifies the underlying product or service.

The Built-in Catalogue of 107 Marks

Archify ships with a bounded catalogue containing 107 provenance-backed vector marks. Each entry defines a canonical ID, human-readable aliases, and categorical metadata (domain and category). These definitions reside in archify/brand-marks/README.md within the repository.

The catalogue enforces strict normalization: you reference brands by their canonical ID or any registered alias, ensuring consistent rendering across all diagram types.

Querying Built-in Brands with the CLI

To inspect available brands, use the brands sub-command defined in archify/bin/archify.mjs. The CLI accepts search terms matching names, aliases, domains, or categories.

# List matching built-in brands with machine-readable output

node bin/archify.mjs brands "OpenAI" --json

Implementation reference: The usage string for this sub-command appears at lines 26-27 of archify/bin/archify.mjs.

When the query resolves to a built-in brand, Archify returns structured metadata:

{
  "id": "openai",
  "aliases": ["OpenAI", "openai.com"],
  "domain": "ai",
  "category": "cloud"
}

The --json flag ensures machine-parseable output suitable for scripting or automated diagram generation.

Capturing External Brand Assets

When diagrams reference products absent from the built-in catalogue, you must capture official brand assets before rendering. Archify performs safe, bounded fetches of remote logos and pins them to cryptographic digests.

The Capture Workflow

Use the brands capture sub-command to fetch and pin external logos:

# Capture a brand from an official URL

node bin/archify.mjs brands capture "https://example.com/logo.png" --json

Implementation reference: The brands capture clause is defined in archify/bin/archify.mjs (lines 26-27), with runtime behavior documented in archify/references/brand-marks.md.

The command returns a JSON object containing:

• url — The original source URL
• sha256 — Cryptographic digest of the fetched image
• source — Metadata including MIME type and byte size

Archify accepts PNG, JPEG, WebP, and ICO formats only. SVG images are explicitly rejected to prevent rendering inconsistencies.

Validating Brand Integrity During Rendering

During diagram generation, Archify validates that the brand object's sha256 digest matches the previously captured version. If the remote image changes or becomes unreachable, rendering fails with a diagnostic directing you to re-capture the brand.

This mechanism ensures reproducible builds: diagrams render identically regardless of external CDN changes or logo updates.

Embedding Brands in Diagram Definitions

To attach a brand to a node, embed the captured object verbatim under the brand field in your diagram JSON:

{
  "nodes": [
    {
      "id": "frontend",
      "type": "service",
      "label": "Web Front-End",
      "brand": {
        "url": "https://example.com/logo.png",
        "sha256": "a3f5c1…e9d4",
        "source": { "mime": "image/png", "bytes": 8421 }
      }
    }
  ]
}

The JSON schema at archify/schemas/brand.schema.json (referenced in archify/schemas/README.md) validates this structure. During rendering, the badge appears in the upper-right corner of the node without displacing the semantic type icon or label.

Best Practices for Brand Attribution

According to archify/SKILL.md (lines 70-73), follow these authoring guidelines:

1. Never infer brands from vague role descriptors like "database" or "cache". Always specify a built-in ID or explicit capture.

2. Apply brands only to first-class components — optional but explicit markers for products that constitute core architectural elements.

3. Preserve semantic sigils — The brand badge is additive; do not replace the node's type indicator with the logo.

Adhering to these rules prevents ambiguous visual encoding and maintains diagram accessibility.

Summary

• Archify manages brand identities as first-class primitives with 107 built-in marks and support for external captures.
• Query the catalogue using node bin/archify.mjs brands <query> --json to resolve canonical IDs and aliases.
• Capture external logos with brands capture <url> --json, which pins images to SHA-256 digests for deterministic rendering.
• Reference captured brands by embedding the full JSON object (including sha256) in node definitions.
• Validate integrity automatically during rendering to prevent drift from upstream logo changes.

Frequently Asked Questions

How do I search for a specific brand in Archify's catalogue?

Use the brands sub-command with your search term and the --json flag. The CLI searches against canonical IDs, aliases, domains, and categories defined in archify/brand-marks/README.md. For example, node bin/archify.mjs brands "Vercel" --json returns the canonical ID and metadata if the brand exists in the 107-mark catalogue.

What happens if I use a brand URL without capturing it first?

Rendering fails with a clear diagnostic error. Archify requires cryptographic pinning via brands capture before any external URL can appear in a diagram's brand field. This ensures the sha256 digest exists for validation during the render phase.

Can I use SVG images for brand badges in Archify?

No. Archify explicitly rejects SVG formats during the capture process. The brands capture command only accepts PNG, JPEG, WebP, or ICO files. This restriction prevents vector rendering inconsistencies and ensures deterministic rasterization across output formats.

Where does Archify store the cryptographic digest for captured brands?

The digest resides in your diagram's node definition itself, within the brand object's sha256 field. Archify does not maintain a global registry; instead, the captured JSON blob (including url, sha256, and source metadata) travels with the diagram source, making brand references portable and self-validating.

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