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). It also writes small shims so different assistants pick it up automatically (for example a CLAUDE.md for Claude Code, and a .codex/ config for Codex). With this in place, your AI editor understands the platform's conventions instead of guessing at them.

The guide files (AGENTS.md, CLAUDE.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.