Portable Context Does Not Mean Portable Runtimes

Portable context does not necessarily imply portable runtimes, according to the distinction made between APC and APX in their respective roles. APC serves as the portable context layer, encompassing project contracts like AGENTS.md, .apc/agents, and .apc/project.json. This ensures that a project can be cloned and maintained across different machines without altering its core structure.

On the other hand, APX is the runtime and tooling layer that enables the actual execution of the project's context on the local machine. However, it's crucial to note that APX's runtime capabilities are discovered locally and do not form part of APC. This distinction is paramount because a project can be portable in terms of its context (defined by APC), yet the machine's runtime environment can vary significantly from one system to another.

For instance, one laptop might have codex and claude installed, while another may only have gemini and ollama. A Continuous Integration (CI) runner might have none of these. If a system erroneously treats runtime availability as an integral part of the project's context, it risks misleading the user or developer. The repository would indicate one thing, but the actual machine might exhibit a different behavior, consequently leading to fragile handoffs and unreliable project execution.

To mitigate this, APX offers a solution by making runtime detection a local operation. Before initiating any process, the command `apx env detect` can be executed to pinpoint which runtime CLIs, engines, and tools are truly available on the current machine. This addresses the issue of runtime availability, ensuring that the project's context aligns with what the machine can actually execute.

The practical workflow exemplified involves first running `apx env detect` to confirm the local runtime capabilities, followed by `apx run reviewer --runtime codex` to review a diff using the codex runtime if it is installed. If it isn't, the failure to run is attributed to the missing runtime on that specific machine, independent of the quality of the APC repository's portability.

Additionally, the separation between `apx run` and `apx exec` commands further solidifies this boundary. `apx run` delegates to an external runtime binary, building the system prompt and managing the external tool's interaction with the model and shell execution. Conversely, `apx exec` operates within APX itself, directly calling configured engines.

This division assists in maintaining honest portability, allowing the same APC project to be reproduced on different machines without modifications. Consequently, APX can then assess: which runtimes are installed locally, which engines are configured, and which toolchain is accessible at any given time. These are runtime questions, distinct from the project-contract queries addressed by APC.

The APX introduction documents further emphasize this design philosophy, clearly stating that while the filesystem retains the source of truth for durable project meaning, runtime state, such as sessions, conversations, messages, caches, and other transient data, are stored under `~/.apx/` and should not be included in the repository.

This logical separation ensures that runtime availability is treated as a machine fact, rather than a project artifact. In conclusion, the guiding principle is straightforward: APC should define the project in a manner that remains intact through cloning, review, and handoff, whereas APX should accurately ascertain the current machine's executable capabilities.

The project's contract should remain small and unchanging, while APX handles the dynamic aspects of runtime invocation and session tracking. By adhering to these guidelines, portable context becomes a reliable tool that avoids vendor lock-in and circumvents the need for repeated setup. The truth is, portability should stop at the right boundary - the project can travel, but the runtime must still be validated before execution.