archify-vscode-ext/SKILL.md

---
name: archify-vscode-ext
description: >
  Author, validate, render and manage Archify diagrams (.archify YAML files of the kinds
  architecture, workflow, sequence, dataflow and lifecycle) and Archify models: a folder
  with main.archify on top, shared elements in *.archify-registry files, ref: components,
  diagram: links and C4-style folders, as read by the Archify Diagram Viewer VS Code
  extension. Bundles the Archify validator and renderer, so diagrams are checked and
  rendered to HTML without VS Code. Use this skill when asked to create, edit, fix,
  validate, render or organise .archify files, build a C4 or architecture model as code,
  add a shared element or a registry, scaffold a model folder, or explain why a diagram
  does not validate, even if the user only says "draw the architecture", "make a diagram
  of this system", "put the diagrams together" or "the diagram shows an error".
license: MIT
compatibility: Requires Node.js 18+, bash and go-task (task). No network access; Archify is bundled under scripts/vendor.
metadata:
  author: root-at-skic
  version: "1.0"
  origin-repository: https://gitea.lego-cloud.eu/vscode-extensions-skills/archify-vscode-ext.git
  targets: Archify Diagram Viewer (root-at-skic.archify-vscode-ext)
---

# Archify diagrams and models

Write diagrams as text next to the code, in the form the Archify Diagram Viewer extension opens as interactive pictures. One `.archify` file is one diagram. A folder with `main.archify` on top is a model: diagrams that belong together, shared elements defined once in a registry, and links between diagrams.

## Overview

Archify (MIT, by tt-a1i) is the renderer and validator. The extension bundles it; so does this skill (`scripts/vendor/archify`), so every task here runs on plain Node and needs nothing installed. The model layer (registry, `ref`, `diagram:` links) is the extension's; this skill resolves it the same way the extension does before Archify sees a diagram. Every task prints YAML on stdout (`success: true|false` first) and logs to stderr.

Install with `npx skills add https://gitea.lego-cloud.eu/vscode-extensions-skills/archify-vscode-ext.git --global`, update with `npx skills update --global`; or clone and `git pull`. One copy per machine. All tasks run from this skill's `scripts/` folder:

```bash
cd <this-skill>/scripts
task --list-all
```

| Task | What it does |
|---|---|
| `task model:validate -- --dir="<model or file inside>"` | Registry, every diagram (refs resolved, Archify validator), every `diagram:` link. Exit 1 on any error. Works on a single diagram outside a model too. |
| `task model:list -- --dir="<model>"` | What the model page shows: metadata, diagrams by folder, registry elements with "used in N diagrams", decisions with status and the diagrams that reference them. |
| `task model:scaffold -- --dir="<folder>" --id="<id>" --name="<name>" [--description="…"] [--c4]` | Creates `main.archify`; with `--c4` also `registry/` and the `0100-context`, `0200-containers`, `0300-components` folders with starter diagrams. Never overwrites. |
| `task model:scaffold -- --dir="<folder>" --example="<name>" [--id="<id>"] [--name="<name>"] [--description="…"]` | Copies a complete example model: `c4-standard-web-app`, `c4-e-shop` or `c4-event-based-integration` (the same three the extension offers under *Archify \| New Model…*). Id, name and description default to the example's own. Never overwrites. |
| `task model:resolve -- --file="<diagram>" [--out="<file.json>"]` | The Archify JSON the extension hands to Archify, for the plain Archify CLI or CI. |
| `task diagram:validate -- --file="<diagram>"` | One diagram through Archify (refs resolved when inside a model). |
| `task diagram:render -- --file="<diagram>" --out="<file.html>"` | Standalone HTML page for people without VS Code. |
| `task test` | The skill's own checks against the examples and scaffolded models. |
| `task sync` | Refresh `scripts/vendor/archify` from an Archify checkout (maintainers only). |

Options for validate and render: `--quality=showcase` (stricter composition checks), `--repo-root=<checkout>` for diagrams with `meta.repository` and `sources`.

## Workflow

### 1. Diagram or model?

- One picture, no shared things: a single `.archify` file anywhere. Skip to step 4 and write inline elements (`id`, `type`, `label`).
- Several pictures of one system, the same elements in more than one of them, levels (context, containers, components), "click the API to see inside": a model. Start with step 2.

A diagram inside a model is still a plain diagram: it opens, renders and exports on its own.

### 2. Start a model

New folder:

```bash
task model:scaffold -- --dir="/path/to/online-shop" --id="online-shop" --name="Online Shop" --description="Web shop, API, workers and stores." --c4
```

Or start from a complete example and rename it (`examples/` lists the three; C4 - Standard Web App, C4 - E-Shop, C4 - Event-Based Integration):

```bash
task model:scaffold -- --dir="/path/to/hub" --example="c4-event-based-integration" --id="hub" --name="Integration Hub"
```

Existing folder of diagrams: add `main.archify` with the `model` block (see `references/formats.md`); every `.archify` below it is now part of the model. `--c4` is a convention, not a requirement: any folders, any depth.

The model's root is the nearest folder above a file that holds `main.archify`. Nothing else marks it. `main.archify` may also hold a diagram of its own (the overview), below the `model` block.

### 3. Add a shared element

Put it in a `*.archify-registry` file under the root (one file or many; `registry/people`, `registry/systems`, `registry/containers` is the C4 split). The key is the id, unique across all registry files:

```yaml
schema_version: 1
elements:
  api:
    type: backend            # Archify component type, fixed for the element
    label: API
    sublabel: Node.js
    brand: node-js           # optional, an Archify brand id
    description: >
      Owns authentication, orders and the catalogue.
    diagram: 0300-components/api.archify   # the diagram that explains it, relative to the root
```

Fields that reach Archify: `type`, `label`, `sublabel`, `tag`, `icon`, `brand`, `sources`. `description` and `diagram` belong to the model only. Write `description` with `>` (a folded block): a plain scalar with `: ` in it is a YAML error.

### 4. Write a diagram

```yaml
schema_version: 1
diagram_type: architecture
meta:
  title: Containers
  output: containers.html      # required by Archify; relative .html path
components:
  - ref: api                   # from the registry; id defaults to "api"
    pos: [460, 160]
    size: [130, 60]
  - ref: db
    label: Orders DB           # label, sublabel, tag may be overridden
    pos: [670, 260]
    size: [130, 60]
  - id: cron                   # unshared, inline, as in any diagram
    type: backend
    label: Nightly job
    pos: [670, 460]
    size: [130, 60]
connections:
  - { from: api, to: db, label: SQL }
```

- `ref` plus the diagram's own geometry (`pos`, `size`, or `row`/`col`). `id: db-replica` with `ref: db` draws the same element under another id.
- Override only `label`, `sublabel`, `tag`. `type`, `brand`, `icon`, `sources` come from the registry; if they differ, it is a different element.
- A component may add `diagram: <path>` to link to another diagram; it wins over the registry's link.
- Connections, boundaries, lanes and everything else are plain Archify and use the ids.

Read `references/authoring.md` before writing a diagram of a kind you have not written in this session: the five kinds, fields, the position grid, labels, boundaries and the validator's error codes with their fixes.

### 5. Validate after every change

```bash
task model:validate -- --dir="/path/to/online-shop"
```

Read the output top down:

- `summary.errors` and `summary.warnings`; `diagramsOk` of `diagrams`.
- `problems`: model-level (duplicate ids across registries, a nested `main.archify`, bad links in registries).
- `diagrams[].problems`: per file, each with `file`, `line`, `pointer` (JSON pointer into the file, `/components/3/ref`), `code` for Archify's own diagnostics, and the message. Archify messages often end with a suggested fix (`move "db" pos to [178, 70]`, `labelAt`); apply that value rather than guessing.

Fix in this order: YAML syntax, registry problems, unknown refs and forbidden overrides, schema errors (`schema/…`), node overlap and out-of-range placement, edges through nodes, crossings and corridors, label clearance. Run again until `success: true`. For one file, `task diagram:validate -- --file=…` is faster. `--quality=showcase` adds composition warnings; use it before a diagram is shown to people.

### 6. Render for people without VS Code

```bash
task diagram:render -- --file="/path/to/online-shop/0200-containers/online-shop.archify" --out="/tmp/containers.html"
```

A standalone HTML page with Archify's viewer (focus, search, export). Links to other diagrams are not followed outside VS Code. `task model:resolve -- --file=… --out=x.json` gives the resolved JSON when someone wants to run the plain Archify CLI (`node scripts/vendor/archify/bin/archify.mjs validate architecture x.json --json`).

## Folder conventions

```
online-shop/
  main.archify                 model block (+ optional overview diagram)
  registry/*.archify-registry  shared elements, split any way
  0100-context/…               groups are folders; numbers only sort them
  0200-containers/…
  0300-components/…
```

Diagrams next to `main.archify` are listed first, ungrouped; deeper ones by folder path. Read `references/folders.md` for the layouts (single diagram, smallest model, grouped, C4 with 0400-code) and how levels hang together through `diagram:` links.

## Gotchas

- **Colons in plain scalars.** `description: Orders: the source of truth` is a YAML error (nested mapping). Use `description: >` and indent the text, or quote it. The same for labels with `: `.
- **The `model` block must not reach Archify.** Archify's schemas set `additionalProperties: false` at every level; any unknown key (`model`, `ref`, `description`, `diagram`, a typo like `colour`) fails as `schema/additionalProperties`. The tasks strip the model keys; everything else must be a schema field.
- **`type` and `brand` cannot be overridden** on a `ref` component. The validator reports `"type" of shared element "db" cannot be overridden`. Change the registry or use a different element.
- **Ids are unique per diagram.** Two `ref: db` entries in one diagram clash; give the second `id: db-replica`.
- **`ref` outside a model is an error.** Without `main.archify` above the file there is no registry; the extension would show the component as `external` with the ref name. Define it inline or create the model.
- **Overlapping labels need `labelAt`** (or `labelDx`/`labelDy`). Archify reports label clearance with a suggested point; set exactly that. Shortening the label is the last resort, never deleting it.
- **`meta.output` is required** and must be a relative POSIX `.html` path (`containers.html`); it is not where the render task writes, `--out` is.
- **Boxes need clear gaps.** Components closer than 8px fail; labels wider than the box fail (`6.5px` per character plus 13). The grid in `references/authoring.md` keeps a standard layout clear.
- **Links are relative to the model root**, never to the file, and must end in `.archify` and exist. `..` is refused.
- **A second `main.archify` deeper down** is reported, not nested. One model per tree.
- **Diagram kinds other than architecture** take `ref` too (workflow and dataflow `nodes`, sequence `participants`, lifecycle `states`), but the registry `type` must fit that kind: lifecycle states use their own type enum, and sequence participants have no `tag`.
- **Decisions are files, ids are words.** One `*.archify-decision` per decision (`decision:` block with id, title, status, date, elements, diagrams, supersedes; prose in context, decision, consequences). Diagrams point at them with `decisions: [<id>]` on the diagram, a node or an edge; the resolver strips the key. An unquoted numeric id (`0001`) is refused because YAML reads it as 1. When an agent changes the shape of a model (a new store, a new queue, a new boundary), it writes a decision and links the elements it touched.
- **Descriptions stay in the registry.** The extension shows an element's description as a tooltip in its Elements panel; nothing is generated into the diagram. Write `cards:` in a diagram only when you want text blocks below it.
- **No em dashes or smart quotes in ids**; ids match `^[a-zA-Z][a-zA-Z0-9_-]*$`.

## References

- Read `references/authoring.md` when writing or repairing a diagram: kinds, fields, grid, labels, boundaries, brands, validator codes and fixes.
- Read `references/formats.md` when writing `main.archify`, a registry, a `ref` or a link, or when unsure what the tasks strip before Archify runs.
- Read `references/folders.md` when laying out a model folder or explaining how the extension finds the root and groups diagrams.
- `examples/c4-standard-web-app/`, `examples/c4-e-shop/` and `examples/c4-event-based-integration/` are complete C4-style models that validate with 0 problems; copy their shape, or copy one with `model:scaffold --example`.