APX Init Is the Bridge From AGENTS.md to a Real APC Project

APC gives a project one portable home for context. APX makes that home usable every day. The clean handoff between those two layers starts with apx init.

A cloned repo can already contain useful rules, but until APX sees an initialized APC project, it has no stable project boundary to work with. That is why apx init matters. It does not add noise. It turns a folder with instructions into a project that APX can recognize, load, and operate on.

AGENTS.md is startup rules, not the whole project

In APX, AGENTS.md is the startup file for agents and tools that understand the convention. The scaffold makes that clear: it is read by AGENTS.md-aware tools, and it is not the agent registry itself. Actual agent definitions live in .apc/agents/<slug>.md.

That split is useful. AGENTS.md tells tools how to behave in this repo. .apc/ holds the project-specific APC data that APX can build on.

What apx init actually writes

The apx init command is simple on purpose. It creates the APC project shape at a chosen path and writes the key files APX expects. The CLI help says it initializes APC project files in the current directory or a target path, and the scaffold writes project metadata into .apc/project.json.

That metadata matters more than the folder name. It gives the project a stable identity, a display name, and the marker APX uses to know that this directory is not just any repo. If APX does not find that project marker, commands that depend on project context refuse to continue.

That behavior is a feature, not a limitation. It prevents APX from guessing.

Why this boundary helps daily work

The practical value is that setup stays explicit:

cd my-repo
apx init
apx agent add editor --role "Software Developer" --model inherit
apx memory editor

After apx init, the repo has a stable APC root. APX can then use the project files in .apc/, while the runtime state stays machine-local under ~/.apx/. That separation keeps the portable layer clean and the local layer disposable.

So the rule of thumb is simple:

• APC is the portable context layer.
• APX is the daily-use runtime and tooling layer.
• apx init is the bridge between them.

If you skip that bridge, you get scattered files and tool-specific assumptions. If you use it, the repo becomes something APX can trust every day.

That is the real job of apx init: not just setup, but making the project legible to the runtime.