Your Project Version and APC Version Answer Different Questions

A project can change without changing its agent-context format. That is why APC's .apc/project.json has two version fields: version for the project and apc for the APC format the project expects. Treating them as one number makes routine releases look like context migrations, or hides a real compatibility change behind an ordinary release.

APC is the portable, repository-owned context layer: files such as AGENTS.md and .apc/ travel with the project. APX is the daily-use runtime and tooling layer that reads that context and runs agents. A machine-readable project file helps those two layers meet without making the repository depend on one person's runtime setup.

Read the fields separately

The APC metadata specification shows this minimal shape:

{
  "name": "My Project",
  "version": "0.1.0",
  "apc": "0.1.0",
  "created": "2026-05-08T00:00:00Z"
}

name identifies the project in human-readable form. created records when its APC metadata set was created. The two version values have different subjects:

Suppose a team ships a feature and moves its application from 0.1.0 to 0.2.0. Its agent files, rules, and metadata format still follow APC 0.1.0. The project version can move to 0.2.0 while apc stays at 0.1.0. Those values are allowed to differ because they track different things.

Now imagine the team updates its context files for a newer APC target format. That is a context compatibility decision. Review the apc value and the files together; do not silently make it match the application release number. The metadata should describe the on-disk context the repository actually contains.

Why a reader needs both

A person reviewing a pull request can tell whether a change is an application release, a context-format change, or both. A compatible tool can find .apc/project.json at a stable location and inspect the project's declared APC target before interpreting its context. APX is one runtime that uses APC project context, but the file remains a project artifact rather than an APX session record.

This also keeps private operational state out of the metadata file. Credentials, provider accounts, conversations, caches, and local sessions belong to the runtime or machine. The project name and intended format can be reviewed and committed with the repository.

A small migration detail

Early implementations sometimes wrote apf instead of apc for the format version. The current APC draft says compatible consumers should accept that historical key for migration, while new projects should write apc. That is a compatibility note, not a reason to put both keys in every new file.

When reviewing .apc/project.json, ask three concrete questions: Does version match the project's intended release? Does apc match the format its context files use? If an older apf key appears, is this a migration case? This takes a minute and prevents a project release number from accidentally becoming a protocol declaration.

See the minimal APC project example for a complete starting layout.