The source files
Semantic source lives in .cordango.yaml files, one per aggregate: an entity, a lifecycle, a role,
a screen. They are the source of truth and they are meant to be read, reviewed and diffed.
Editing them directly is fine. They describe what a thing is, not how it runs.
fmt rewrites every .cordango.yaml file in canonical form, so a diff shows a change in meaning
rather than a change in whitespace or key order.
The build directory
.cordango/ with the leading dot is build output. It is regenerated by cordango build and it is
not committed. cordango new writes a .gitignore that already excludes it.
Agent instructions
cordango new writes CLAUDE.md and AGENTS.md with the same generated text. Two conventions
want two filenames, and a workspace that taught two agents different rules would produce source only
one of them could maintain.
They teach the workflow rather than the schema. An agent arrives knowing how to find out:
That is deliberate. Everything specific is one cordango inspect away, which is what stops the
instructions growing back into a copy of the whole schema.
Every command accepts --json. cordango help --json is how an agent discovers the command
surface without a human pasting a README into its context.
