Shortcut / definitions registry with claim semantics (split from #149)

Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity

Closed feature request

Colby Knox · 6d ago ·closed by Colby Knox

Split out of #149 (the hero-standard issue) -- this is a separate feature and shares nothing with heroes except the "raise the quality bar" framing.

What

A canonical shorthand registry so agents resolve user shorthand to a package: ad = adom-desktop, hd = hydrogen-desktop, abe = adom-browser-extension. Today adom/definitions exists but only as a GLOSSARY SKILL ("what is [term]") -- read by the AI, no enforcement, no claim table. This wants a real registry with CLAIM SEMANTICS.

Claim semantics

First definition wins.
A new claim on a taken shortcut is REJECTED, showing the existing meaning: "ad is already adom-desktop; pick a new shortcut for adom-dealmaker."

Shape (small, self-contained)

shortcuts table: shortcut (unique), target (owner/slug), claimant, created_at, optional note.
POST /api/shortcuts (claim; 409 + existing meaning on collision), GET /api/shortcuts (resolve/list).
Surface it so agents consult it: a hint on ambiguous shorthand input, and a resolve endpoint the CLI/hook can call.

Decisions taken (Colby, 2026-07-15)

Split into its own issue (this one). The hero parts of #149 (crop fix + aspect lint + cost nudge) shipped separately.

1 Reply

Colby Knox · 4d ago

Shipped to prod. The registry exists with exactly the claim semantics specced here:

API

POST /api/shortcuts {shortcut, target, note?} (auth required): claim. First definition wins. A claim on a taken shortcut is a 409 SHORTCUT_TAKEN whose message IS the resolution: "'ad' is already adom/adom-desktop; pick a new shortcut for ...", with the existing target and claimant in data. Re-claiming the same (shortcut, target) is an idempotent 200, so scripts can assert their shortcuts safely.
GET /api/shortcuts (public): the full table.
GET /api/shortcuts/:shortcut (public): resolve one, case-insensitive; coded SHORTCUT_NOT_FOUND on a miss.
DELETE /api/shortcuts/:shortcut: release, claimant or admin only.

Guardrails

Shortcuts are 1-32 chars of a-z 0-9 - _, stored lowercase.
A target must be an EXISTING page, owner-qualified: no dangling shorthand (same "a name you claim must exist" posture as the dead-dependency publish gate).
Claimant is recorded and served by handle; carbon ids stay DB-only.

Agents actually consult it: a package-resolve miss on a bare name that IS a registered shortcut now returns a SHORTCUT_MATCH hint naming the target ("'ad' is a registered shortcut for adom/adom-desktop") instead of a bare 404, so "install ad" teaches the resolution at exactly the moment it fails.

Verified on staging end-to-end (claim, collision showing the existing meaning, idempotent re-claim, case-insensitive resolve, release, and the resolve-miss hint) plus a 32-assert suite.

CLI half (small): shortcut claim/resolve/list/release verbs, and optionally consulting GET /api/shortcuts/:name before giving up on a bare pkg install <name> miss. The new codes (SHORTCUT_TAKEN, SHORTCUT_NOT_FOUND, BAD_SHORTCUT, BAD_SHORTCUT_TARGET) all carry field/self-contained messages and render through the generic pipeline; no bespoke arms needed.

The original seeds from the issue (ad, hd, abe) are left unclaimed deliberately: claims should come from the owners who want them, now that first-come is enforced.