---
name: anchor-viz
description: Draw a faithful architecture or structure diagram of a real codebase or project by scanning the actual repo, never guessing. Use for system architecture, request lifecycle, data model, state transitions, type structure, draw the architecture, map this project, 画架构图.
---

# anchor-viz

Investigate by diagramming. The diagram is the byproduct; the value is forcing
real investigation before drawing.

## Forced Procedure

1. **Route the request.** Choose one `diagramKind` from the table below. If the
   user's intent fits multiple kinds, ask one short clarification instead of
   guessing.
2. **Find evidence for that kind.** For `architecture`, enumerate roots,
   manifests, workspace/build/native/container/edge/infra/source-only signals.
   For other kinds, find the bounded entrypoint, schema, state enum, workflow,
   or module/type namespace before drawing.
3. **Classify shape or scope.** For `architecture`, state one project shape and
   cite evidence: `single-frontend`, `single-backend`, `coupled-fullstack`,
   `monorepo`, `library`, `native`, `native+edge`, `source-only code`, or
   `non-code`. For other kinds, state the bounded scope and the files that prove
   it.
4. **Apply the non-code decision.** Never declare non-code only because manifests
   are absent. First scan roots; then run a bounded source-extension/code-signal
   scan. If both are absent, or docs/vault signals clearly dominate, do not
   fabricate a code diagram. Draw the real top-level structure or ask what the
   user wants.
5. **Match the user's language.** Human-facing diagram text follows the user's
   primary language: titles, display labels, edge/message labels, shape notes,
   and short explanations. Keep code-facing identifiers source-native: Mermaid
   IDs, file paths, symbols, package names, class/function/module names, and
   established technical terms such as API, SDK, CLI, HTTP, SwiftUI, AppKit, or
   React.
6. **Draw only evidenced relationships.** Use the evidence contract for the
   selected kind. Every node, participant, entity, state, type, and edge/message
   must come from a file read.
7. **Enforce complexity gates.** Keep `architecture` at 12-15 top-level nodes by
   default. For other kinds, use the validator's participant/message,
   entity/relationship, state/transition, or type/member limits. Split into
   drill-down diagrams when needed.
8. **Mark provenance.** Add render-neutral comments for every element before
   storing:
   `%% techne:source <elementRef> <path>[#<symbol>]` or, for relationship-like
   elements only, `%% techne:inferred <relationshipRef> <reason>`. Entity-like
   elements always need verified `techne:source`; relationship-like elements
   need file+symbol proof unless explicitly inferred with sourced endpoints.
   Use `actor` for human sequence participants so the actor path-only allowance
   is mechanically scoped. Solid relationships mean read-from-code. Dashed or
   labeled relationships mean inference only where the selected Mermaid type
   supports it.
9. **Emit, validate, store, build viewer, open when interactive.** Write Mermaid
   source first, validate it, store it with `scripts/store_viz.py`, always build
   the self-contained viewer, and only open it when the session is interactive.

## Diagram Routing

| User intent | `diagramKind` | Mermaid `type` | Evidence focus |
| --- | --- | --- | --- |
| Project architecture, module/service/package topology | `architecture` | `flowchart` / `graph` | Manifests, workspaces, imports, services, bindings, infra edges. |
| Request lifecycle, command/job flow, actor conversation | `interaction` | `sequenceDiagram` | Entrypoint, ordered calls/messages, handlers, clients, queues. |
| Tables, entities, persistence relationships | `data-model` | `erDiagram` | Schema, migrations, ORM/entity declarations, foreign keys, associations. |
| Status/order/task/review lifecycle | `state-model` | `stateDiagram-v2` / `stateDiagram` | Status constants, state machines, reducers, guards, transition handlers. |
| Classes, interfaces, structs, protocols, bounded type structure | `type-structure` | `classDiagram` | Type declarations, inheritance, implementation, composition, public method groups. |

Examples:

- "map this project" -> `architecture`.
- "show how login request flows" -> `interaction`.
- "draw the database relationships" -> `data-model`.
- "how does order status change" -> `state-model`.
- "show the public types in this module" -> `type-structure`.

## Script Usage

- Validate Mermaid and altitude:
  `node skills/anchor-viz/scripts/validate-mermaid.mjs diagram.md --project /path/to/project --max-nodes 15`
- Store a diagram in a target project:
  `python3 skills/anchor-viz/scripts/store_viz.py --project /path/to/project --name login-flow --title "Login flow" --diagram diagram.md --shape monorepo`
- Build the self-contained viewer, opening it only when interactive:
  `python3 skills/anchor-viz/scripts/build_viewer.py --project /path/to/project --open`

The validator expects `mermaid@11.15.0` and `jsdom` to be installed in one of
these places: `TECHNE_VIZ_NODE_MODULES`, `skills/anchor-viz/scripts/node_modules`, the
current working directory, or an ancestor directory.

## Stop Conditions

- Stop and ask if you cannot inspect the project files.
- Stop and ask if the requested diagram kind is ambiguous.
- Stop before drawing unsupported architecture for a non-code project.
- Stop before drawing a non-architecture diagram without a bounded entrypoint,
  schema, status lifecycle, or module/type scope.
- Stop before storing a diagram that fails syntax validation, provenance
  validation, or a complexity gate.
- Do not create `.techne/` content inside this repository while authoring the
  skill itself.