Overview Diagram

Generates a human-friendly overview infographic showing what the project is, how to get started, what's inside, and how it all connects.

Execution

Step 1 — Locate Project Root

ls .agents/ Cargo.toml 2>/dev/null || echo "NOT_FOUND"

Step 2 — Generate the Diagram

python .agents/skills/architecture-diagram/scripts/generate_overview.py \
  --root . \
  --out .template/overview.excalidraw \
  --svg-out .template/overview.svg

The script auto-discovers at runtime:

• Workspace crates → cargo metadata (with Cargo.toml glob fallback)
• AI skills → .agents/skills/*/ directories
• Commands → .opencode/commands/*.md
• Quality checks → config/xtask.json tier check lists
• CI jobs → job IDs across .github/workflows/*.yml

Step 3 — Sync to Docs

cp .template/overview.svg docs/src/overview.svg

scripts/sync-architecture.sh performs steps 2 and 3 in one shot and is what the Update Overview Diagram workflow runs.

Step 4 — Confirm and Report

After the script exits:

1. Tell the user the output path.
2. Report counts: N crates · M skills.
3. If counts differ from the last known state, summarize what changed.

Output

• .template/overview.excalidraw — editable Excalidraw source
• .template/overview.svg — generated SVG for docs embedding

What the stats mean

The "BY THE NUMBERS" cards are derived, never hand-written. If a number looks wrong, fix the discovery logic rather than editing the generated files.

Quality Checks previously scraped scripts/quality-gates.sh for cargo invocations. That script is now a thin wrapper around cargo xtask, so the count collapsed to 1 while the real gate ran nineteen checks. Do not reintroduce command-scraping for this number.

Optional Dependencies

Node.js (for SVG/PNG export)

Required for SVG/PNG export from Excalidraw:

npm ci

Without Node.js, use --no-export to generate only the .excalidraw source. Never commit a partially regenerated diagram: if export fails, the stale SVG stays in place and silently keeps advertising old counts. Check that the EXPORTED: lines appear before committing.

cargo must be on PATH for accurate crate discovery. Without it the script falls back to parsing Cargo.toml globs and prints a warning — that path now reports the same totals, but the warning is a signal that the run is degraded.

CLI Flags

Rationalizations

Red Flags

• Committing workspace changes without regenerating the overview.
• Manually editing the SVG instead of using the generator script.
• Direct push failures caused by missing retry loops or unhandled concurrent updates on main (see case update-diagram-push-20260917 in .agents/ci/regression-matrix.json).

Why the PNG is not committed

PNG export rasterises through the local font stack, so the same diagram yields different bytes on a CI runner than on a developer machine. The SVG and Excalidraw outputs are byte-identical everywhere. Because nothing embeds the PNG — the README and docs both use overview.svg — committing it produced a spurious "regenerate overview diagram" PR on every workflow run. Generate one ad hoc with --png-out when you need a raster preview; do not commit it.