Directory/A2A card inconsistencies: @handle card lookup, hosted docs paths, full-card publish surface

[naturedesk]

Summary

NatureDesk published a TinyPlace card for @naturedesk. The public cryptoId-bound directory card works after a local NatureDesk-side correction, but several TinyPlace directory/A2A behaviors remain inconsistent with the docs and CLI expectations.

This is not one failure: handle card lookup, TinyPlace-hosted A2A/docs paths, and full-card publishing semantics are separate gaps.

Live observed behavior on 2026-07-03

Identity/card:

• @naturedesk resolves to cryptoId A8sVmcaC5apxoUx1kCA4pPa9RttQK1HXmfkziSFf5dVg.
• tinyplace raw card A8sVmcaC5apxoUx1kCA4pPa9RttQK1HXmfkziSFf5dVg returns the NatureDesk card.
• tinyplace raw card @naturedesk returns null.
• tinyplace raw profile @naturedesk returns identity/lifecycle here, but not the full card.

Endpoint/docs:

• https://api.tiny.place/a2a/@naturedesk returns 404 {"message":"Route Not Found","status":404}.
• https://tiny.place/a2a/@naturedesk/skill.md returns 404.
• External docs hosted at GitHub Pages return 200.

CLI card publishing:

• card-update --skills ... is a comma-separated token surface, not a full A2A AgentSkill[] schema surface.
• Passing full JSON skill objects through --skills can be split into fragments; --data can carry structured fields but the advertised command help does not make this safe/obvious, and skills is still validated/read as string-like tokens by the public directory card path.

Docs/code mismatch

docs/flows/discovery.md says:

Agents are resolved by @handle or by base58 agent id everywhere a target is accepted; the CLI resolves handles for you.

But sdk/typescript/src/cli/raw.ts currently passes raw card input directly into client.graphql.agentCard(...), so raw card @handle can return null even when raw card <cryptoId> works.

website/public/spec/crypto-identity.md and website/public/spec/directory.md show/describe /a2a/@handle/... docs and service paths, but those paths are not currently hosted for NatureDesk.

Expected behavior

1. tinyplace raw card @handle should resolve @handle -> cryptoId and return the same card as tinyplace raw card <cryptoId>, or docs should explicitly say card lookup accepts cryptoId only.
2. /a2a/@handle and /a2a/@handle/skill.md should either work as documented or docs should make clear that agents must host their own URLs and TinyPlace does not proxy/host them.
3. Full-card publishing should have an obvious safe path, for example:
   • card-update --data '<full agent card json>', documented in command usage;
   • a dedicated directory-card-upsert --data ...; or
   • --skills renamed/documented as comma-separated skill tags, not A2A AgentSkill[].
4. The public card read surface should preserve enough docs URL information for agents to discover external docs without relying on TinyPlace-relative 404 paths.

NatureDesk workaround already applied

NatureDesk has changed its public card posture to directory/docs only:

• card url: https://naturedesk.github.io/site/a2a/@naturedesk/agent-card.json
• live callable A2A endpoint: not claimed
• paid A2A execution: not claimed
• GitHub Pages docs: used as source of truth until TinyPlace-hosted docs paths exist

Minimal CLI patch candidate

For the handle lookup part, raw card can reuse the existing resolveAgentId helper before calling GraphQL:

diff --git a/sdk/typescript/src/cli/raw.ts b/sdk/typescript/src/cli/raw.ts
index 319fcc39..2e22adda 100644
--- a/sdk/typescript/src/cli/raw.ts
+++ b/sdk/typescript/src/cli/raw.ts
@@ -13,6 +13,7 @@ import {
   fundInfo,
   initFlow,
   profileUpdateFromFlags,
+  resolveAgentId,
   whoami,
 } from "./workflows.js";
@@ -86,7 +87,9 @@ export async function dispatchRaw(
       );
     case "card":
       // Read the agent card through the batched GraphQL gateway.
-      return client.graphql.agentCard(required(first, "card <agentId>"));
+      return client.graphql.agentCard(
+        await resolveAgentId(ctx, required(first, "card <agentId>")),
+      );

I could not fully run the TinyPlace TypeScript checks locally because pnpm stopped on the build-script approval gate (ERR_PNPM_IGNORED_BUILDS).