docs(realface): the published contract described the pre-seal API

[VickyXAI]

The RealFace group id was sealed in BlockRunAI/blockrun 4064e6c2 and the published docs still describe the API as it was before. One part of that actively misleads a working integration.

The part that breaks integrations

/status was documented as:

A groupId that is missing or not of the form legacy_rf_<digits> is 400; a well-formed id that does not exist is 404

It now answers 404 for both, and that is deliberate: a different answer for a real group than for an absent one confirms which groups exist, which rebuilds the enumeration oracle the seal removed. A caller who coded to "400 means malformed" is handling the wrong status today.

Rewritten to say what the route does, and why the two cases are not distinguished.

The examples are not inert either

legacy_rf_8137 appeared as the worked example in five places. ai-providers.ts records why that matters:

scanners probing the docs example legacy_rf_12345 were polluting the 5xx logs

which is the reason the not-found path is tagged at all. Replaced with elided rf1_…, and added a note that group_id is a ~215-character opaque handle to be stored and passed back verbatim — and that it is the credential for that enrollment, since anyone holding it can refresh the H5 link and enroll into the group.

Stale response samples

• realface.md — the realfaces listing sample showed groupId, removed from the response in blockrun#575
• virtual-portrait.md — same field in the portraits listing, removed in blockrun#578

A documented id shape that never existed

virtual-portrait.md documented "group_id": "tg_xyz9876543210". This service has never returned a tg_ prefix. submitVirtualPortrait records, verified empirically:

POST /v1/asset-groups { groupKind: "VIRTUAL_PORTRAIT" }
  → { code: 200, data: { assetGroupId: "legacy_rf_7629", … } }

The same sequential allocator RealFace groups come from. Corrected to the real shape, elided, and the field description now says plainly that no endpoint accepts it back — portrait enrollment mints its own group, so there is nothing to pass it to.

Verification

docs/ is consumed by blockrun's suite through a submodule symlink, so the edits were validated there rather than in isolation: with this tree in place, docs-canonical, docs-resilience, brand-numbers.docs, upstream-disclosure-prose, published-price-sync and tool-jobs all pass — 3674/3674 on the full run.

Found while closing out BlockRunAI/enterprise#162; the sol session independently flagged the same file.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KM7ZdEFd8JJN7KX5sRgYrs