AI editors & AGENTS.md

Because a pulled site is just files on disk, you can edit it with an AI coding assistant — Claude Code, Cursor, GitHub Copilot, Codex, and others. To make those assistants effective, the CLI can drop in a guide that teaches them how the platform works.

Work in a parent workspace

The recommended layout is a parent workspace folder with one pulled site per subfolder and a single AGENTS.md at the root:

clients/
  AGENTS.md         ← one guide, shared by every site
  acme-dental/
  northwind/

Open the whole clients/ folder in your editor. The assistant reads the root AGENTS.md and can work across all your sites at once, and the guide sits above your site folders — so it's never part of any site.

`acira init`

Run this once at the root of your workspace (the folder that holds your pulled sites):

acira init

It writes an AGENTS.md file — a reference manual describing how Acira sites are structured and what they can do (pages, logic, the database, auth, email, and the rest). Claude Code, GitHub Copilot and Gemini CLI read it on their own; for Codex it also writes a small .codex/ config so the whole guide is read. If your workspace or a folder above it has its own CLAUDE.md, add an @AGENTS.md line to it, since Claude Code then reads that file instead of AGENTS.md. With this in place, your AI editor understands the platform's conventions instead of guessing at them.

It also writes REFERENCE.md, the guide's companion for when something behaves unexpectedly: edge cases, failures that show no error, and the reasons behind the rules. It isn't loaded into your assistant by default — the assistant reads it when something surprises it, and you can point it there while debugging.

The guide files (AGENTS.md, REFERENCE.md, .codex/) are developer-local tooling — never site content. They live above your site folders, and even if one ends up inside a site, the CLI excludes it from publishing and linting. So you can safely commit them to your own repo without them ever reaching a live site.

Why it matters

Framework knowledge is the difference between an assistant that writes correct, idiomatic Acira code and one that invents patterns that won't work. AGENTS.md gives the assistant the same platform contract the in-app coding agent works from, so local AI editing produces the same quality of output.

A typical workflow

mkdir clients && cd clients
acira pull acme-dental    # → ./acme-dental
acira init                # teach your AI editor the platform (writes AGENTS.md here)

cd acme-dental
acira preview             # live local preview while you work
# ...edit acme-dental/ with Claude Code / Cursor, using the workspace guide...
acira lint
acira publish -m "Add the bookings page"

Keeping the guide current

The platform reference in AGENTS.md tracks the platform itself. Re-run acira init at the workspace root after upgrading the CLI to refresh it, so your assistant always has the current contract.

Prompting still matters

An AI editor is only as good as the brief you give it. The guidance in Prompting the agent applies here too — describe outcomes, work in focused steps, and give it real content and context.