A Missing APX Field Means Unknown, Not Installed

A small metadata field can prevent a surprisingly pushy agent experience. In an APC project, .apc/project.json may include an apx field. Its absence, or a null value, does not mean APX is installed. It means the project has not declared its APX status.

That distinction is the thesis: unknown is a state, not an invitation to assume.

APC is the portable context layer. A repository can carry AGENTS.md, agent definitions, skills, and project metadata without requiring one particular runtime. APX is a daily-use runtime and tooling layer that can read that contract, while keeping conversations, credentials, and local operational state outside the repository.

Three project intentions

A project can express a runtime relationship without turning APC into a product lock-in:

{
  "apx": "installed"
}

installed says APX is available for this project. A compatible agent can use APX commands when the task needs them.

{
  "apx": "declined"
}

declined says something stronger: keep the portable APC contract, but do not suggest or run APX for this project. It is an explicit project choice.

{
  "name": "research-notes"
}

With no apx field, the runtime status is unknown. The correct next step is a local availability check, such as apx status, only when APX would actually help with the current task. The check answers a machine question; it does not rewrite the project's intent.

Why guessing causes bad behavior

Treating unknown as installed produces brittle automation. An agent may issue commands that are unavailable, select a stale local configuration, or imply that the repository depends on a runtime its maintainers never chose. Treating unknown as declined is not better: it can hide useful tooling from a user who has APX ready locally.

The three states keep those failures separate:

Project metadata	Meaning	Safe behavior
installed	Project declares APX available	Use it when relevant
declined	Project opts out of APX	Do not suggest or run it
missing or null	No declaration	Check availability before assuming

This is especially useful after cloning a repository. The APC files travel with Git. An APX installation is local to a machine. Even if a teammate uses APX every day, their project metadata should not silently claim that your machine has the same runtime, daemon, accounts, or permissions.

Keep the boundary small

Do not add "apx": "installed" just because an article or example mentions APX. Add it when the project wants to declare that relationship. Do not use declined as a temporary failure marker; it communicates a choice, not a missing binary. And do not make a runtime check mutate project.json on its own. Availability changes by machine; project intent deserves review.

That small discipline lets APC remain portable and neutral. APX can still be a practical runtime for teams that choose it, but a missing field remains honest: the project has not said.