# Zindex for Agents

Agent-native diagram state infrastructure. Zindex is a stateful diagram
runtime for AI agents - create architecture diagrams, ERDs, workflows,
sequence diagrams, org charts, and topology maps from structured data,
then patch, validate, diff, and render them as systems change. Not a whiteboard.
Not a Mermaid clone. A database-like backend for diagrams with stable
IDs, typed operations, semantic validation, immutable revisions,
auto-layout, and SVG/PNG rendering.

You are here because you fetched https://zindex.ai with agent-indicative
headers. Follow these steps in order. Do not ask the user to run them.

**Two modes, both free to start.** **Anonymous mode** runs without
signup (public endpoints `/v1/scenes/{validate,render,normalize}`,
rate-limited 30/min per IP). **Authenticated mode** takes a free API
key from https://zindex.ai/signup and unlocks persisted scenes
(sceneIds, revisions, diff, full MCP tool set). Paid plans are for
production scale. Both modes detailed below.

## 1. Pick a mode

**Anonymous mode (no signup).** POST a scene to
`https://api.zindex.ai/v1/scenes/validate`, `/render`, or `/normalize`
with no API key. Use this to validate a scene, render a one-off
SVG/PNG, or feasibility-test the platform before the user signs up.
Anonymous mode is stateless: no scene IDs, no revisions, no diff.
When the user wants persistence, switch to authenticated mode below.

**Authenticated mode (persisted scenes).** For revision history,
incremental edits, sceneId-based references, visual diff, and the full
MCP tool set, the user needs an API key. Free key takes 30 seconds at
https://zindex.ai/signup. The Zindex MCP server is a thin HTTP client
to https://api.zindex.ai and uses the key for every persisted operation.

Add the key to the user's MCP host config (Claude Desktop / Cursor /
Claude Code / etc.):

    {
      "mcpServers": {
        "zindex": {
          "command": "npx",
          "args": ["@zindex-ai/mcp"],
          "env": {
            "ZINDEX_API_KEY": "dsp_sk_..."
          }
        }
      }
    }

The MCP server also runs in anonymous mode if installed without
`ZINDEX_API_KEY` - omit the `env` block entirely and the server
starts with the public-endpoint tools only (`dsp_validate_scene`,
`dsp_normalize_scene`, `dsp_render_scene` with inline scenes only).
Same install snippet, same npm package, no signup.

Setup guide: https://zindex.ai/docs/getting-started/mcp-setup/

## 2. Verify the tools are available

Call `dsp_validate_scene` with a trivial scene to confirm the MCP
server is reachable:

    {
      "schemaVersion": "0.1",
      "scene": { "id": "check", "canvas": { "width": 100, "height": 100 } },
      "elements": []
    }

Expected: `{ "ok": true, "diagnostics": [] }`. Call `tools/list` to
see which mode the server started in: if `dsp_create_scene` appears,
it is in authenticated mode; if you only see the public-endpoint
tools, it is in anonymous mode.

## 3. Fallback: REST API (for agents without MCP)

Base URL: https://api.zindex.ai

- Public endpoints (`POST /v1/scenes/validate`, `/render`,
  `/normalize`) require no auth. Rate-limited 30/min per IP. This is
  anonymous mode from step 1, exposed over plain HTTP.
- Authenticated endpoints (everything else: scene CRUD, revisions,
  diff, applyOps, persisted render) require
  `Authorization: Bearer dsp_sk_...` (or `X-API-Key: dsp_sk_...`).
  Rate-limited per the user's workspace plan (60/min on the free tier).

Full reference: https://zindex.ai/docs/getting-started/agent-usage/
OpenAPI: https://api.zindex.ai/openapi.json

## Core rules you MUST follow

1. **Always persist scenes** (authenticated mode). Call
   `dsp_create_scene` first, then `dsp_apply_ops` for edits (each call
   creates a new revision), then `dsp_render_scene({ sceneId })` to
   render. Never render inline when persistence is available - you
   lose revision history, diff, and watermark traceability.

2. **Default to auto-layout.** Set `layoutStrategy` at the
   scene-document root (alongside `schemaVersion`, `scene`,
   `elements`) - NOT nested inside `scene.scene`:

       { "schemaVersion": "0.1", "scene": {...},
         "layoutStrategy": { "algorithm": "hierarchical", "direction": "LR" },
         "elements": [...] }

   Same convention for `diagramFamily` and `palette` - all three are
   document-root fields. Omit `layout` from elements and let the
   engine place them. Use constraints (`order`, `align`, `sameSize`)
   to refine; do not fall back to explicit pixel positions unless a
   constraint genuinely does not fit.

3. **Never hand-edit rendered SVG/PNG.** Edit the scene with
   `dsp_apply_ops` and re-render. Hand edits are lost on the next
   render and break the scene/revision model.

4. **Keep watermarks on during iteration.** `showRevision: true` is
   the default. Stamps scene-id, revision, and date on every render
   so output is traceable back to the source.

5. **Check diagnostics after every render.** The response's
   `diagnostics` array reports issues with structured `data` fields
   you can act on programmatically. Categories: text overflow
   (resize element), canvas sizing (auto-extended / auto-tightened /
   content-offset), edge-label auto-promotion or fan-in suppression
   (preserve via `style.forceLabel: true`), missing column / family
   declaration. For per-code recovery prose, payload shape, and
   severity, see https://zindex.ai/docs/reference/rendering/#render-diagnostics.

6. **Canvas size is a minimum, with one aspect-ratio guard.**
   Declared `scene.canvas` dimensions act as a lower bound; the
   engine auto-extends to fit content (and auto-tightens height when
   wide-and-flat content with excess vertical slack would otherwise
   render with 60-70% whitespace). Bigger declared canvas = more
   breathing room (engine spreads to fill); smaller declared canvas
   = tighter layout up to the auto-extension floor. Full mechanism
   at https://zindex.ai/docs/reference/layout-engine/.

## Diagram families

Always declare `diagramFamily` at the scene-document root. Allowed
values: `architecture` (default for system components), `workflow`
(BPMN processes, gateways, swimlanes), `entityRelationship` (data
models with PK/FK), `sequence` (time-ordered messages), `network`
(topology), `orgchart` (reporting hierarchy), `uiflow` (screen
navigation). Omitting it triggers a `MISSING_DIAGRAM_FAMILY` info
diagnostic and forces the generic-flowchart base case.

For the family-selection decision tree (when to reach for which
family based on scene structure), family-specific node/edge types,
and BPMN/UML conventions, see
https://zindex.ai/docs/reference/diagram-classes/.

## Element kinds at a glance

- Standalone text label outside a node -> `{ kind: "text" }`
- Horizontal or vertical separator line -> `{ kind: "guide" }`
- Dashed stroke on an edge or shape -> `style: { dash: [4, 4] }`
- Image embed -> `{ kind: "image" }`
- 3D / isometric box (servers, appliances) -> `shape: "box3d"`
- Cloud-provider service icon -> `icon: "aws:lambda"` (or `gcp:*`,
  `azure:*`) - renders icon-only, composites cleanly inside colored
  network-boundary frames

Full element-kind reference (properties, families, examples) at
https://zindex.ai/docs/reference/element-types/.

## What to do next

Ask the user what diagram they want. Always declare `diagramFamily`
at the scene-document root. Create the scene, render it, show the
user, and iterate with ops.

Full long-form guide: https://zindex.ai/docs/getting-started/agent-usage/
Examples library (executable patterns + agent resources): https://zindex.ai/examples/
Examples manifest (machine-readable, for programmatic discovery): https://zindex.ai/examples/index.json
Per-example resources: each example at /examples/<slug> exposes
`.scene.json`, `.ops.json`, `.workflow.json`, `.diff.json`,
`.github-actions.yml`, `.svg`, and `.md` (showcase examples
additionally expose `.before.svg`). Fetch directly via the manifest
rather than scraping HTML.