docs(api): join on natural keys, demote surrogate id (TRA-891)

[mikestankavich]

What

Corrects the TRA-885 advice that integrators should use the surrogate id as their durable foreign key. Reframes id as a stable internal reconciliation anchor (not a business key), adds natural-key join guidance, and demotes id on the versioning page.

Changes (docs-only)

• resource-identifiers.md — removed "Use id as your durable foreign key when you mirror TrakRF data." (the one actively-wrong, dependency-inducing published line). Reframed id as an internal anchor + added a "Joining your system of record" subsection: assets/locations join on external_key; general rule = natural key where one exists, else id as a reconciliation handle.
• changelog.md — reworded the TRA-885 entry to drop the FK prescription (kept the global-uniqueness/opaque facts).
• versioning.md — added an id-demotion note. Deliberately did not publish an absolute id-permanence guarantee (that would re-sell the dependency this ticket removes).

Prerequisite verification (against live app.preview.trakrf.id/api/openapi.yaml)

• external_key is present and required on both AssetView and LocationView (ticket flagged locations as "unconfirmed" — now confirmed). ✓
• customer_identifier does not exist on the API — the field is external_key; docs keep that name.
• The wrong advice lived only in docs prose, not in OpenAPI field descriptions → docs-only PR, no paired platform change.
• Delta/incremental sync is not advertised anywhere → nothing to retract or caveat.

⚠️ Deviation from ticket scope — needs your call at merge

The ticket lists per-entity join guidance for users (email→id) and organizations (slug→id). Verification shows neither is a public joinable resource: /users/* are internal-only, there's no public User schema, and the only public org endpoint is the singleton /orgs/me ({id, name, scopes, api_key_id} — no slug). Per the ticket's own rule ("do not document a join key that is not present"), I omitted the user/org email/slug guidance rather than publishing aspiration, and instead stated the general rule + a note that users/org-admin aren't public joinable resources in v1. If you want those documented anyway (e.g. as roadmap), say so and I'll adjust.

Validation

• pnpm build passes — no broken-link/anchor warnings (the new #joining-your-system-of-record cross-links from resource-identifiers.md and versioning.md resolve).
• Edited docs are prettier-clean (pre-existing prettier warnings on docs/api/* exist on main and are untouched here).

Spec: superpowers/specs/2026-05-30-tra-891-api-identity-join-guidance-design.md
Plan: superpowers/plans/2026-05-30-tra-891-api-identity-join-guidance.md

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	85aeacb
Status:	✅  Deploy successful!
Preview URL:	https://e8a5c53b.docs-4n7.pages.dev
Branch Preview URL:	https://preview.docs-4n7.pages.dev

View logs