Bundled Vault Templates Should Be Tombstoned, Not Deleted

A bundled agent template is part of the APX runtime.

That means hiding it should not work like deleting a project file.

APX gets this right by tombstoning bundled vault templates instead of pretending they are user-owned files that can simply disappear.

That detail matters because APC and APX own different layers.

APC is the portable context layer. It keeps project-owned context in the repository: AGENTS.md, .apc/agents/, .apc/skills/, .apc/mcps.json, and other durable files that should travel with the repo.

APX is the daily-use runtime and tooling layer. It owns machine-wide templates, local runtime state, imports, sessions, message logs, and user overrides under ~/.apx/.

The agent vault belongs on the APX side.

Why delete is the wrong model

The APX vault is explicitly layered.

In src/core/apc/parser.js, the comments define three pieces:

• bundled defaults in assets/agent-vault-defaults/
• user templates in ~/.apx/agents/
• tombstones in ~/.apx/agents/.removed.json

Reading merges bundled and user templates by slug, with the user layer winning. Writing always goes to the user layer. Removing a bundled slug does not delete the packaged file. It adds a tombstone so the slug stays hidden until restored.

That is the correct behavior.

A bundled template ships with APX itself. It is runtime content, not project context and not user-authored state by default. If APX tried to delete the packaged file, it would blur ownership badly.

A local runtime should be able to say, "do not show me this default," without rewriting the APX installation or pretending the template never existed.

What the CLI already says

The CLI command in src/interfaces/cli/commands/agent.js makes the rule plain.

cmdAgentVaultRm() reports three different outcomes:

• bundled default tombstoned
• user template deleted
• user override deleted and bundled default tombstoned

That split is important because those are different ownership cases.

A user-owned file under ~/.apx/agents/<slug>.md can be deleted.

A bundled default cannot. It can only be hidden.

Then cmdAgentVaultRestore() lifts the tombstone and makes the bundled default visible again.

That is better than fake deletion because it preserves a stable source of truth: APX still ships the template, while the local runtime remembers the operator's preference.

Where APC enters the picture

The APC side starts only when a project chooses to own an agent locally.

The docs in docs/src/content/docs/capabilities/agent-vault.mdx show the practical split:

apx agent import cody-developer
apx agent import tessa-qa --copy

Without --copy, APX just registers the template and reads it from the vault at runtime.

With --copy, APX writes a real project-local file into .apc/agents/.

That is the moment APC takes ownership.

Now the agent definition is part of repository context, reviewable with the rest of the project, and safe to customize for this repo only.

So the boundary stays clean:

• vault template hidden or restored: APX runtime concern
• project-local copied agent: APC project concern

Practical example

Imagine APX ships a bundled tessa-qa template.

One user does not want that template appearing in vault listings, so they run:

apx agent vault rm tessa-qa

APX should remember that preference locally in ~/.apx/agents/.removed.json.

It should not touch project repositories.

It should not mutate the bundled package.

It should not remove tessa-qa from a project that already imported it earlier, because imported agents are resolved separately and existing project use should not vanish just because the vault listing changed.

That exact protection is documented in readAgents() too: imported vault agents resolve with includeRemoved: true, so hiding a vault template does not silently delete an already-imported project agent.

Small mechanism, correct boundary

Tombstones are a small storage mechanism, but they encode a larger design rule.

Bundled runtime assets should stay bundled.

Local operator preferences should stay local.

Project-owned context should move into APC only when the project explicitly copies and owns it.

That is why tombstones are better than deletion here.

They let APX manage machine-wide defaults honestly, while APC remains the place for durable project context.

Hide runtime defaults in APX.

Copy project truth into APC.

Do not confuse those two forms of ownership.