Clarify that `st2 resource` manages linked references, not agent state

[schickling-assistant]

Problem

st2 resource add|ls|read|remove manages durable linked-reference records stored under an agent's resources/links/ directory.

That surface is distinct from both:

• the agent's native durable state under resources/inbox, resources/archive, and resources/context; and
• typed Resource bindings declared in Agent Spec and projected through st2 agents --json.

Current top-level help already calls the command “linked resources,” but subcommand help and human output still shorten that to an agent's “resources.” A reader can reasonably mistake the command for an inventory of the state tree or of declared Resource bindings.

Narrow scope

Use agent vocabulary and make the linked-reference boundary explicit in help and output wording:

• st2 resource --help says it manages linked references and is not an inventory of agent state or Agent Spec Resource bindings;
• add, ls, read, and remove describe link records consistently; and
• human list/read output uses wording that does not imply all durable agent material.

Non-goals

• renaming or removing the shipped st2 resource command;
• changing storage paths or link-record wire format;
• adding a generic inventory API for inbox, archive, context, status, links, or other future state;
• changing Agent Spec Resource bindings; or
• unifying linked references, declared Resource identities, and mutable agent state.

A structured durable-state inventory is a separate consumer contract and should be proposed separately only when a concrete consumer needs it. This help-only clarification remains GitHub backlog, not active WORK or SITREP.

[schickling-assistant]

Superseded — the second sense is being removed, not worded around

Design interview 2026-08-27. This issue scoped a help-only clarification and listed "renaming or removing the shipped st2 resource command" as a non-goal. That non-goal is reversed: the linked-record plane is retired, so there is no second sense of resource left to disambiguate.

Why wording alone was not enough. The read surfaces were inverted against their authority:

	Resource binding	link record
machine surface	st2 agents --json	none
human surface	none	st2 resource ls
requirement	R20, R21	none
invariant	INVARIANTS.md:22	none

The plane with spec authority had no human surface at all. The plane with none owned the short, obvious verb. An agent looking for its declared bindings found the linked-record verb first, because it was the only one whose name matched what it was looking for. Rewording # N resources for <id> would not have changed that — it would still be the only resource command, still reading the other plane.

Why the plane went rather than the words. Measured on a live catalog of 655 declarations: link records were adopted by 82 declarations (12.5%), creation decayed from 45/day on 2026-08-08 to none after 2026-08-26, and the only reader in the source tree was its own ls/read verb — no projection, roster, or doctor consumed one. axe work update --artifact <path> --pty <name> now covers the job, matching the observed relation values (output 185, evidence, produces) and the 8 pty:// URLs.

Your framing was right about the boundary. #61's resolution had already stated it correctly on 2026-07-30 — "st2 resource add|ls|read|remove manages durable linked-reference records; it does not mutate an Agent Spec Resource binding" — and it never reached the command's own words. With one plane, it no longer needs to.

Also worth recording here: templates/bus.st2.md:100-101 still advertises the verb to every agent on the bus, which is what produced the adoption. Removing that is part of the same change.

Decision: docs/vrs/.decisions/0008-the-linked-record-plane-is-retired.md. Pending upstream maintainer approval; leaving open for that.

Posted on behalf of @schickling

field	value
agent_identity	unknown
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	Claude Code
agent_tool_version	2.1.237
agent_runtime	Claude Code 2.1.237
tooling_profile	dotfiles@11eaf2d-dirty