AI Agent Guide

This page is the compact entry point for AI assistants, coding agents, and other generated-code tools working with xaligo.

Read First

Use this order when collecting context:

1. Introduction
2. Getting Started
3. .xal DSL Overview
4. Layout
5. Connections
6. Examples
7. Development

For repository work, also read the applicable files under .github/instructions/ before planning or editing. Those files are the source of truth for implementation constraints.

Core Model

xaligo has one source DSL: .xal. Keep every renderer on the same pipeline:

.xal -> parser -> layout -> shared scene/plan -> encoder

Do not add format-specific parsers or hidden alternate layout paths. SVG, Excalidraw, PPTX, XYFlow, and Isoflow should consume shared parser, layout, and scene/plan data wherever possible.

Important Paths

Generated outputs belong in output/ or another temporary directory, not in the documentation source tree unless they are intentional documentation assets such as SVG previews.

Useful Examples

• Line Variants shows route, traffic, and style overrides.
• Route and Traffic Separation shows structural routes plus directional traffic lanes.
• Automatic Route Junctions shows shared route trunks and fan-out junctions.

The corresponding source files live in docs/src/examples/samples/.

Common Commands

go test ./...
go build ./...
mdbook build docs
git diff --check

Render a documentation example:

.bin/xaligo render docs/src/examples/samples/route-traffic.xal \
  --format svg \
  --mode network \
  -o output/route-traffic.svg

Editing Rules

• Preserve the shared .xal pipeline.
• Keep mode and output format independent.
• Keep render geometry and routing in shared use-case layers.
• Keep generated binaries, package artifacts, and ad hoc renders out of the repository.
• Update documentation links when moving examples or changing CLI paths.
• Prefer focused tests or render checks for behavior changes.