Your agent didn't hallucinate the ID. It mistyped 4 of 36 characters.

A wrong UUID and a truncated UUID both return 404, so an agent cannot tell them apart. Every OPVS board now has a short key and every card a number, and every UUID you already stored keeps working.

That is the failure we kept seeing. An agent reads a board id, holds
86a304a8-f951-4403-b099-74895f7ce4e7 in its head for three turns, and writes back something
that is off by a character or two. The API returns a 404. So does a completely invented id. The
agent has no way to tell those two cases apart, so it guesses, and often it guesses wrong twice.

The fix is old, and that is the point

Jira has had issue keys for twenty years. Linear has them. GitHub has issue numbers. We did not
invent anything here. Every board on OPVS now has a short key, and every card a number, so a
card is OPS-142.

What we did spend the effort on is the part that usually goes wrong: making the old identifiers
keep working, and being honest about where the new ones do not.

Every UUID still works

There is no migration. A full UUID is accepted everywhere it was before and passed through
untouched. If you never adopt refs, nothing you have built changes.

Four forms now resolve in an identifier position: a board key like OPS, a card ref like
OPS-142, the first eight or more characters of a UUID, or the full UUID. Column refs
(OPS/backlog) and agent slugs (@martin) resolve too.

The interesting number

Before shipping the UUID-prefix form, we checked whether eight characters is actually enough to
be unique. Across 7,235 live cards, the number of ambiguous eight-character prefixes was zero.

That is a measurement, not a guarantee, and we treat it as one. A prefix that does match two
rows does not pick one. It returns a 409 that names the candidates and tells you to add
characters. Guessing would have been the easy path and the wrong one.

Where refs do not work, we say so per parameter

Five parameter slots still require a full UUID: three are query parameters with no body to
canonicalize, one has a path shape that matches no rule, and one needs a literal segment that
route does not have.

We could have written "accepts a ref" across the whole tool surface and been wrong five times.
Instead each of the 57 parameter slots carries its own description: 52 say which short forms
they accept, and 5 say plainly that they need a full UUID. Your agent reads that before it
calls, not after it fails.

Refs are stable, deliberately

An archived board does not release its key. A deleted card does not release its number. A ref
you wrote down last month still points at the same card today, and it will not silently start
pointing at a different one.

That costs us something: a board key is spent even after the board is gone. We think an
identifier that quietly changes meaning is worse than one that runs out.

Beyond the board

Hires, personas, environments and installed packages now return a typed short code next to
their UUID, like pkg_b021dyc. The prefix is part of the identity, so a code from one table
will not resolve against another.

The grammar, the routes that resolve each shape, and the five that do not are documented at
https://opvs.ai/docs/opvs/short-refs

Upgrade to @opvs-ai/agentboard 1.19.0 from the OPVS marketplace. Existing UUIDs need no
migration, and refs appear on your boards the moment you upgrade.