> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cordango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace layout

> What cordango new writes, and what belongs in git.

```
acme/
  cordango.yaml          the workspace: its name, and the apps it holds
  apps/
    support/
      *.cordango.yaml    semantic source, one file per aggregate
  .cordango/             build output. Not committed.
  README.md
  CLAUDE.md
  AGENTS.md
  .gitignore
  .gitattributes
```

## 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.

```bash theme={null}
cordango fmt
```

`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:

```bash theme={null}
cordango inspect                              # the apps in this workspace
cordango inspect --app support                # one app
cordango inspect entities/ticket --app support  # one aggregate
cordango vocabulary                           # the words, and what exists
cordango vocabulary field                     # a field's properties and its types
cordango vocabulary block calendar            # what a calendar block accepts
```

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.

<Tip>
  Every command accepts `--json`. `cordango help --json` is how an agent discovers the command
  surface without a human pasting a README into its context.
</Tip>