archsmith: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (Claude Code, Cursor, Copilot, Codex, etc.) working on the ArchSmith repository itself.

Scope: this file configures agents contributing to this repo. It complements CONTRIBUTING.md (the human-facing build/governance doc) rather than replacing it — read both, and don't duplicate one into the other if you're updating them.

What this is

A renderer, CLI, and MCP server that turn a validated JSON IR (intermediate representation) into an SVG diagram, in one fixed layered/swimlane house style. See README.md for the full pitch and the IR shape. The short version: @archsmith/renderer is a pure function (IR in, SVG out, no LLM call inside it) — interpretation (sketch/description → IR) is deliberately someone else's job, not this repo's.

Architecture at a glance

npm workspaces monorepo. Four packages, strict one-way dependency chain — each package only knows about the one directly below it:

@archsmith/cli  ─┐
                 ├──▶ @archsmith/renderer ──▶ @archsmith/schema
@archsmith/mcp-server  ─┘

• packages/schema — the JSON Schema (diagram-schema.json) plus governed registries (registries/{colors,icons,sub-layers}.json). Registry entries are house-style contracts, not per-diagram decisions.
• packages/renderer — pure function: validated IR in, SVG string out. No I/O beyond reading its own bundled font. No LLM call anywhere inside it. Layout is organized as layout/ (per-column assembly), boxes/ (individual shapes), text/ (font measurement + wrapping via the embedded Arimo font, using fontkit), and svg/ (node model + serialization + font embedding). TypeScript project references (tsc -b) handle inter-package build order — no manual ordering needed.
• packages/cli — the archsmith binary. Thin commander-based wrapper around render() / validate(). render exits 1 on validation errors, 2 on rendering errors. Also has the author subcommand, an interactive Ink-based wizard — see archsmith author, below.
• packages/mcp-server — the archsmith-mcp binary. A sibling of the CLI, not a wrapper: calls render() / validate() from @archsmith/renderer directly. server.ts builds the McpServer while index.ts is a thin entrypoint that wires it to StdioServerTransport; the split exists so server.test.ts can connect a real MCP Client over an in-memory transport pair. Never write to stdout — stdout is the JSON-RPC channel and a stray console.log (even for debugging) corrupts the protocol stream. Use console.error for diagnostics.