feat: resolve agent cards directly from ai-catalog references in --agent-card flag

[Tehsmash]

Which area does this relate to?

• CLI code

What kind of feature are you proposing?

New command or flag

What would you like to see?

Allow --agent-card to accept an ai-catalog reference directly, so users can go from:

ai-catalog catalog add <catalog URL>
ai-catalog pull <reference> -o agent-card.json
a2acli send --agent-card agent-card.json

to:

ai-catalog catalog add <catalog URL>
a2acli send --agent-card <reference>

The CLI should detect when the value passed to --agent-card is an ai-catalog reference rather than a local file path, resolve it via the registered catalogs maintained by the ai-catalog CLI, fetch the Agent Card JSON, and use it as if it had been supplied as a local file.

To also support one-shot resolution without a pre-registered catalog, a scoped format should be accepted:

a2acli send --agent-card "<catalog-url-or-name>@<reference>"

This mirrors the pattern ai-catalog pull --scope <catalog URL> <reference> but inline as a single flag value.

Resolution order

1. If the value is a valid local file path that exists — use it as today (no change).
2. If the value matches <scope>@<reference> — resolve <reference> against <scope> (URL or registered catalog name) via the ai-catalog CLI.
3. Otherwise treat the value as a bare <reference> and resolve it against all registered ai-catalog catalogs (equivalent to ai-catalog pull <reference>).

Dependency

Requires the ai-catalog CLI to be installed and accessible on $PATH. If it is not found and a catalog reference is supplied, the CLI should emit a clear error pointing to the install instructions.

Why is this important?

Today, using a catalog-hosted agent requires a manual two-step dance: pull the card to a temp file, then pass that file. This is friction for humans and makes scripting / automation more fragile (temp file lifecycle, naming, cleanup). Native reference resolution makes catalog-backed agents first-class citizens alongside local card files.

Who benefits from this feature?

• Developers scripting agent calls in CI/CD pipelines who want a single stable reference rather than managing ephemeral JSON files.
• AI coding agents driving the CLI (e.g. Claude Code) that can use a catalog reference directly without filesystem side-effects.
• Any user who has already invested in organising agents in an ai-catalog and wants a seamless a2acli experience.

Would you be interested in helping build this feature?

Yes — I'd like to implement it

Additional context

• ai-catalog CLI repo: https://github.com/Agent-Card/ai-catalog-cli
• Relevant ai-catalog commands: catalog add, pull, pull --scope
• The @ separator in <scope>@<reference> is chosen to match common toolchain conventions (npm scopes, OCI references); open to alternatives if there is a conflict.

Code of Conduct

• I agree to follow this project's Code of Conduct