docs: TRA-877 bb-2.3 docs hygiene (items 2, 5) + asset-location de-quote#198
Conversation
|
🚀 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 |
Deploying docs with
|
| Latest commit: |
a5cec40
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://16816daf.docs-4n7.pages.dev |
| Branch Preview URL: | https://docs-tra-877-bb23-docs-prose.docs-4n7.pages.dev |
…(TRA-877) bb-2.3 hygiene item 2. The "Filing support tickets" section documented an x-railway-request-id edge header that the current deployment no longer emits — the path is GKE/Traefik/Cloudflare now, no Railway (confirmed with infra). It's a stale artifact from the old Railway deploy era, not an edge-conditional behavior, so drop the Railway paragraph and table row and keep only the x-request-id guidance. No edge caveat added: there is no edge-injected request-id header today (a Traefik requestid middleware would be separate, out of scope), so documenting one would be aspirational and a future staleness magnet.
…eded (TRA-877) bb-2.3 hygiene item 5. The contract-track wrapper claimed "Tags are not in v1 public-API scope," which contradicts the spec (tags expose POST/DELETE .../tags subresources on assets and locations, gated by the parent resource's :write scope) and was disproven empirically — all three bb-2.3 sessions round-tripped session-created tags. The fixture genuinely ships no tag rows, so reframe from "not in scope" to "not pre-seeded," and tell the tester to exercise the surface by creating their own.
…-identifiers
Bundled with the TRA-877 docs PR per bb-2.3 cross-session consensus
(unanimous bb-231/232/233). The page quoted an error `detail` string
verbatim in two spots (the location-immutability prose and the location_id
table row), and the live string had drifted. But `detail` is explicitly
non-contractual ("do not branch on this value"; the auth page tells
integrators detail wording may evolve), so re-pinning the new string — the
original framing of the dropped TRA-877 item 6 — just resets the drift
clock until the next backend wording tweak.
De-quote instead of re-sync: state the boundary in the docs' own words
(asset location is scan-derived, not externally writable in v1), reference
Errors -> validation errors for the read_only behavior, and keep the two
stable navigational pointers (GET /api/v1/reports/asset-locations, GET
/api/v1/assets/{asset_id}/history). Eliminates the whole drift class rather
than chasing one instance. Behavior verified: location_id /
location_external_key on asset POST/PATCH return 400 / code: read_only.
mikestankavich
force-pushed
the
docs/tra-877-bb23-docs-prose-hygiene
branch
from
78a7ef8 to
e8a15c9
Compare
|
🚀 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 |
mikestankavich
changed the title
…-2.3 retirement) The BB33 changelog entry announced the Errors-page x-request-id vs x-railway-request-id distinction and links to "Filing support tickets" — the section the bb-2.3 item-2 fix just retired. Left untouched it would contradict the live page (a dangling reference flagged during bb-2.3 review). Per the changelog's own convention, append a _(Superseded …)_ note rather than rewriting history: the x-railway-request-id reference is retired (deployment is GKE/Traefik/Cloudflare, no such header), the page now documents only x-request-id, and the x-request-id guidance in the entry still stands.
|
🚀 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 |
|
Added a 4th commit ( Non-blocking follow-up (out of scope here, noted by bb-231): the |
…entifiers Consistency pass folding in the observation bb-231 flagged during #198 review: the read-only field table's id / created_at / updated_at / deleted_at rows still quoted verbatim service `message` strings — the same non-contractual drift-magnet class just de-quoted for location_*. Replace the verbatim quotes with behavior described in the docs' own words (server-managed/immutable; code: read_only; echo the current value or omit the field), reframe the column header from "Rejection message names" to "Rejection behavior," and note in the intro that the literal message/detail wording is non-contractual (branch on code, not detail). No verbatim service-message quote remains anywhere in the table. Behavior verified by bb-231 on BB1.
|
🚀 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 |
1 participant
The docs-prose portion of the TRA-877 bb-2.3 hygiene bundle, plus a bundled drift-proofing fix. Prose-only, no platform dependency. Three commits.
Scope note: TRA-877's platform items (1, 3, 4) and the static-spec asset refresh are not here — they land platform-first per the paired-PR rule. After bb-2.3 cross-session validation, the ticket was rescoped to 5 items (the original "item 6" was dropped — see below).
Item 2 —
docs/api/errors.md(TRA-877)Retire the stale
x-railway-request-idguidance in "Filing support tickets." The deployment is GKE/Traefik/Cloudflare-fronted now — no Railway in the path (confirmed with infra), so the header is a dead artifact, not edge-conditional. Removed the Railway paragraph + table row; kept thex-request-idguidance. No edge caveat added — there's no edge-injected request-id header today (a Traefikrequestidmiddleware would be separate/out-of-scope), so documenting one would be aspirational and a future staleness magnet.Item 5 —
tests/blackbox/BB_PRE_KEY.md(TRA-877)Corrected "Tags are not in v1 public-API scope" → tags expose
POST/DELETE …/tagssubresources gated by the parent's:writescope, and all three bb-2.3 sessions round-tripped session-created tags. Reframed to "not pre-seeded on fixture rows," with a nudge to exercise the surface.Bundled —
docs/api/resource-identifiers.mdde-quote (replaces dropped item 6)The original item 6 was "mirror the live asset-location
read_onlydetail string verbatim." bb-2.3 cross-session consensus (unanimous bb-231/232/233) reclassified it as "real drift, but non-contractual — not worth mirroring" and dropped it from TRA-877:detailis explicitly do-not-branch / may-evolve, so re-pinning a verbatim quote just resets the drift clock. Since the page already quoted the (now-stale) string in two spots, the correct fix is to de-quote, not re-sync:read_onlybehavior.GET /api/v1/reports/asset-locations,GET /api/v1/assets/{asset_id}/history).No verbatim detail-string quote remains in prose or the
location_idtable row. Per Mike's call, bundled here rather than spun into its own ticket (trivial; rationale captured in this PR + the cc2cc thread). Behavior verified contract-accurate:location_id/location_external_keyon assetPOST/PATCH→400/code: read_only.Verification
pnpm buildpasses (broken-link/MDX check clean; endpoint paths backticked so MDX doesn't parse{asset_id}).errors.md(pre-existingmaindrift); the one-row table is prettier-clean.TRA-877 (items 2, 5) + bundled de-quote.
🤖 Generated with Claude Code