File formats

A project is a directory of plain files. This section specifies each one. Here's the whole layout, using the Petstore API:

my-project/
├── .api-craft/
│   ├── config.json                      # project config
│   └── cache/                           # GITIGNORED
│       ├── responses/                   # request history
│       │   └── petstore-api/…
│       └── workflow-runs/               # workflow run history
└── apis/
    ├── workflow/                        # RESERVED: project-scoped workflows
    │   ├── pet-lifecycle.json           # a workflow
    │   └── scripts/
    │       └── pet-lifecycle/…          # its assert/condition/transform scripts
    └── petstore-api/
        ├── api.json                     # API metadata
        ├── spec.imported.json           # raw imported OpenAPI spec (immutable)
        ├── schema.rules.json            # resource/operation mapping rules
        ├── resources/
        │   └── Pet/
        │       ├── _resource.json        # resource + operation metadata
        │       └── requests/
        │           ├── get-pet.json                # public instance
        │           ├── .local.debug.json           # GITIGNORED (private)
        │           └── .temp.get.json              # GITIGNORED (temp)
        ├── requests/                     # standalone instances (no operation)
        ├── middlewares/                  # before/after hooks + custom auth (TypeScript)
        └── environments/
            ├── schema.json               # variable declarations
            ├── dev.json                  # values
            └── dev.secrets.env           # GITIGNORED (secrets)

How the files relate

config.json lists the APIs directory and project-wide settings.
Each API has api.json (metadata + defaults + overrides) and spec.imported.json (the raw spec). The two combine in memory into the effective spec; see OpenAPI as the source of truth.
schema.rules.json maps spec operations into resources and operations.
_resource.json holds the metadata you add per resource and per operation (notes, overrides, locally-defined operations).
Request instances under requests/ are concrete calls. Environments supply the variables they reference.
middlewares/ holds the TypeScript functions an API's requests can call, before/after hooks and custom auth.
apis/workflow/ is a reserved directory, not an API: it holds workflows, which are project-scoped and may target several APIs in one run. No API can be named workflow.

Committed vs gitignored

Everything is committed except:

Path	Why it's gitignored
`.api-craft/cache/`	Local request and workflow-run history, machine-specific.
`*/.local..json`	Personal (private) request instances.
`*/.temp..json`	Scratch (temp) request instances.
`*/.secrets.env`	Secret environment values.
`apis//tsconfig.json`, `apis//.api-craft/`	Generated editor tooling for scripts.

The version field on each JSON file identifies its format. The pages below specify the current version of each.