Unregistering an APX Project Should Not Erase Its APC Contract

A project can stop being active on one machine without stopping being a project. That distinction matters when you clean up an APX installation, move between computers, or register the wrong directory by mistake.

The practical rule is simple: removing an APX project registration should remove the local runtime relationship, not the portable APC contract.

APC is the portable context layer. Its AGENTS.md and .apc/ directory live with the project and can be reviewed, copied, or committed. APX is the daily-use runtime and tooling layer. It registers that project with a local daemon, runs agents against it, and keeps runtime state under ~/.apx/. Those layers have different owners and different lifetimes.

The cleanup command is deliberately narrow

APX registers a project explicitly:

apx project add /path/to/repo

During registration, APX reads the project's AGENTS.md and .apc/project.json. The filesystem remains the source of truth for portable context; APX records enough local information to work with that project on this machine.

Later, this command removes that local registration:

apx project remove /path/to/repo

The command does not delete the project files. In particular, it does not delete AGENTS.md, .apc/project.json, agent definitions, skills, or shared MCP hints. The project folder remains a valid APC project for Codex, Claude Code, APX on another machine, or another compatible tool.

That restraint is useful. A developer may unregister a temporary checkout. A team may remove an old path after a disk migration. A person may decide that a research directory no longer needs an active APX runtime. None of those decisions means the project's shared instructions should vanish.

Runtime cleanup is a separate decision

APX also keeps machine-local state under ~/.apx/projects/<apx_id>/: conversations, messages, task logs, cached data, routine state, and agent runtime memory. That state is intentionally not part of APC and should never be confused with the portable project definition.

Unregistering a project therefore answers one question only: should this local APX daemon keep this project in its active registry? It does not answer whether the repository should keep its instructions, or whether local runtime history should be retained for later inspection.

This split avoids two opposite mistakes:

1. Treating a local cleanup command as permission to destroy shared project context.
2. Treating runtime state as if it were safe to ship with the project just because it exists near the project in the APX UI.

Re-register from the contract

If the project becomes relevant again, register the same directory again:

cd /path/to/repo
apx project add .

APX can read the portable files again because they never depended on the old registration. The stable apx_id in .apc/project.json identifies the project definition; it is not a reason to bury runtime history inside the repository.

This gives project maintenance a clean boundary. Keep APC files when the project still needs durable, shareable guidance. Remove an APX registration when this machine no longer needs to operate that project. Decide separately what to do with local runtime state.

Portable context should outlive a local registry entry. APC preserves the contract; APX makes that contract useful while the project is active.