@@ -7,6 +7,15 @@ body:
       value: |
         Thanks for filing a bug. Please fill in the sections below so we can reproduce and fix it.
         **Do not include credentials, tokens, or `logindata.json` content in this issue.**
+
+        **Is this Medtronic's fault, or ours?** If Medtronic changed something — a
+        route now 404s or 405s, the version list moved, a country appeared, a status
+        code changed — that is a *vendor observation*, not a bridge bug. Check the
+        map first ([NovaLux12/carelink-api-research](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/00-summary-the-map.md))
+        and file it there via its
+        [new-finding form](https://github.com/NovaLux12/carelink-api-research/issues/new?template=01-new-finding.yml);
+        its drift sweep is what notices. File it here if the vendor surface is
+        unchanged and this bridge still misbehaves.
   - type: input
     id: version
     attributes:
 
@@ -38,6 +38,26 @@ The fork should only carry changes that landed in or were submitted upstream.
 - [ ] No divergence — the change is also applicable to (or already submitted to) upstream
 - [ ] Diverges from upstream — see explanation above
 
+## Vendor-surface impact
+
+<!--
+Medtronic publishes no API documentation, so every claim about it rests on
+[NovaLux12/carelink-api-research](https://github.com/NovaLux12/carelink-api-research).
+If this PR changes, adds, or re-verifies a vendor claim — a route, a status code,
+the discovery pin, the version list, device vocabulary, an error class — say so.
+-->
+
+- [ ] No vendor-surface change (pure bridge logic)
+- [ ] Vendor claim checked against the [research map](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/00-summary-the-map.md)
+- [ ] Vendor change observed — filed upstream as a [finding](https://github.com/NovaLux12/carelink-api-research/issues/new?template=01-new-finding.yml): <link>
+
+`npm run drift:check` (maintainer release step only — needs a sibling clone of
+the research repo plus `hurl` and `jq`; write `n/a` if not applicable):
+
+```
+drift:check exit: __
+```
+
 ## Checklist
 
 - [ ] My change matches the contribution guidelines in CONTRIBUTING.md
 
@@ -21,3 +21,15 @@ jobs:
       - run: npm ci
       - run: npm run typecheck
       - run: npm test
+
+  cross-links:
+    # Every vendor claim in this repo cites NovaLux12/carelink-api-research.
+    # Those links float on `main`, so a rename on that side would silently
+    # 404 them. This makes the breakage loud at PR time.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - run: npm run links:check -- --online
@@ -152,6 +152,15 @@ A research pass into CareLink's live API surface, followed by the fixes
 it produced. The branch is one squashed commit carrying both the code and
 the documentation changes, so this entry covers both.
 
+The underlying evidence for this pass — and every claim in it — is filed in
+the sister research repo,
+**[NovaLux12/carelink-api-research](https://github.com/NovaLux12/carelink-api-research)**
+([start with the map](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/00-summary-the-map.md),
+dated findings in
+[`findings-log/`](https://github.com/NovaLux12/carelink-api-research/tree/main/findings-log)).
+That repo is re-verified continuously, so a drift found after this entry
+should be reported there, not here.
+
 Every CareLink fact below was verified live on 2026-10-08 unless it is
 labelled **INFERRED** (from a third-party client or Medtronic's own
 published assets) or **UNVERIFIED** (needs a real CareLink credential).
 
@@ -22,6 +22,19 @@ dependency), write an ADR in `docs/adr/` first. The
 
 1. Open an issue first for anything non-trivial (small typo
    fixes don't need an issue).
+
+   **Is it a bridge bug or a vendor observation?** This bridge is a
+   *client*; most interesting problems are not its bugs. If Medtronic
+   changed something — a route exists/doesn't, a version list moved, a
+   new country, a changed status code, a renamed field — file it in
+   **[NovaLux12/carelink-api-research](https://github.com/NovaLux12/carelink-api-research)**,
+   the research repo that maps and continuously re-verifies this
+   surface, using its
+   [new-finding form](https://github.com/NovaLux12/carelink-api-research/issues/new?template=01-new-finding.yml).
+   Its weekly drift sweep is what catches a change before it becomes a
+   bridge outage. Issues on this repo are for bridge behaviour. The test:
+   *if Medtronic did nothing, would it still be broken?* Yes → bridge
+   issue. No → research finding.
 2. Fork the repo, create a branch.
 3. Make the change.
 4. Make sure `npm test` and `npm run typecheck` pass. (`npx tsc --noEmit`
@@ -106,6 +119,16 @@ most useful thing you can do is:
 That gives the next maintainer something to test against
 without needing their own real pump.
 
+**If the real-data probe taught you something about the vendor
+surface** — not just about this bridge — that belongs in the research
+repo too. File it via its
+[new-finding form](https://github.com/NovaLux12/carelink-api-research/issues/new?template=01-new-finding.yml)
+and cite the `findings-log/` path it lands in from your PR, so the
+finding is pinned rather than only described. The bridge's own
+vendor claims live in
+[`docs/vendor-api/README.md`](./docs/vendor-api/README.md), which records
+which finding each source comment rests on.
+
 ## Releasing (maintainers)
 
 Version metadata must stay in sync — v0.1.1 through v0.1.3
@@ -118,15 +141,34 @@ happened. For every release:
 2. Move the `[Unreleased]` items in CHANGELOG.md into a new
    dated version section and update the compare links at the
    bottom.
-3. Merge those changes via PR like any other.
-4. Tag the merge commit: `git tag vX.Y.Z && git push origin vX.Y.Z`.
-5. Cut the release: `gh release create vX.Y.Z --title vX.Y.Z --notes "..."`
+3. **Run the vendor-surface regression suite: `npm run drift:check`.**
+   It executes
+   [`regression/hurl/run.sh`](https://github.com/NovaLux12/carelink-api-research/blob/main/regression/hurl/run.sh)
+   from a sibling clone of the research repo, and needs `hurl` and `jq`
+   installed. **Do this before you tag** — a non-zero exit means Medtronic
+   moved something under us, and tagging a release that is already broken
+   would make the tag the published record of it.
+
+   Two things to know before you run it. It **sends live traffic to
+   Medtronic's production servers** — around 60 requests across nine
+   hosts, two seconds apart, read-only apart from two pinned POSTs. That
+   is the research repo's deliberate probing budget, and running it more
+   than once per release is not free politeness. And it needs a network
+   round trip, so a **network failure is not drift**: the sweep's own
+   rule is that only two consecutive reds count, because CI network
+   failures look exactly like vendor drift.
+   If it fails, re-run once; if it fails again, read
+   [`docs/vendor-api/README.md`](./docs/vendor-api/README.md), decide with
+   the evidence, and only then proceed.
+4. Merge those changes via PR like any other.
+5. Tag the merge commit: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+6. Cut the release: `gh release create vX.Y.Z --title vX.Y.Z --notes "..."`
    — the notes should match the CHANGELOG entry
    (security-relevant changes get a clear callout per
    [SECURITY.md](./SECURITY.md)).
-6. Check ROADMAP.md — a phase marked "shipped" must have
+7. Check ROADMAP.md — a phase marked "shipped" must have
    a matching tag and release.
-7. If a new architectural decision was made in this
+8. If a new architectural decision was made in this
    release, the ADR should already exist in `docs/adr/`.
    Confirm the index table is up to date.
 
 
@@ -19,7 +19,9 @@ uploading what it gets.
 > [`docs/vendor-api/README.md`](./docs/vendor-api/README.md) records which finding
 > each one rests on. **Go there first** when debugging a fetch failure, checking
 > whether a route still exists, or changing how this bridge talks to CareLink —
-> and report what you find there, where a drift sweep will notice it.
+> and report what you find there, where a
+> [drift sweep](https://github.com/NovaLux12/carelink-api-research/blob/main/.github/workflows/drift-sweep.yml)
+> will notice it.
 
 > **How close is this to the official app?** The **data** path is the
 > same one the official CareLink app uses — the bridge takes its login
 
@@ -202,7 +202,8 @@ refusal). If it is ever wired in it must stay **opt-in and
 off by default**: it is a second, much larger data surface
 than the fetch loop. Details in
 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md#live-carelink-api-surface)
-("Reports API").
+("Reports API"); the vendor-side host and gateway evidence is in
+[NovaLux12/carelink-api-research](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/07-admin-portal-and-reporting.md).
 
 ## v0.3.0 — reliability (shipped 2026-09-09, #58)
 
@@ -285,6 +286,8 @@ this bridge actually uses is **unverified**, and a second
 identity is not buildable on top of an unverified one. That
 is the second of the two cheapest authenticated checks in
 [Pre-pump authenticated checks](#pre-pump-authenticated-checks-cheapest-first).
+The namespace comparison itself is mapped in
+[carelink-api-research docs/02 §4 "What a client must actually use"](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/02-auth-tenants-and-flows.md#4-what-a-client-must-actually-use).
 The multi-patient fan-out fixture item is also one of the
 things the reports API might unblock — see the v0.2.0
 maintenance note above.
@@ -299,7 +302,9 @@ cheapest checks that need a real account token, in order:
    flow still work at all? It exercises discovery → PKCE → token
    exchange → refresh, and it is the only check that catches an Auth0
    drift before it becomes a November emergency. It needs no data fetch
-   and no pump.
+   and no pump. The pin's evidence and the family fallback
+   (`3.7`/`3.8`) are in
+   [carelink-api-research docs/03](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/03-discovery-and-versions.md).
 2. **`GET /api/carepartner/v2/users/me` vs `GET /patient/users/me`.**
    Both answer `401` without a token, so **which one actually returns
    data with a valid token is unknown** — and that is the open question
@@ -337,6 +342,17 @@ blocked on a real pump or a real capture.
 
 Active open work, cross-referenced from issues:
 
+> **Vendor-surface source of truth.** Facts about CareLink itself
+> (which routes exist, which versions answer, what changed since
+> this roadmap was written) live in
+> **[NovaLux12/carelink-api-research](https://github.com/NovaLux12/carelink-api-research)** —
+> [start with the map](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/00-summary-the-map.md),
+> pick future work from
+> [docs/11 suggested areas](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/11-suggested-research-areas.md).
+> Its weekly drift sweep opens issues there when the surface
+> moves; bridge issue #76 mirrors the reports-API lead, and
+> #12 tracks what a real token settles.
+
 | Item | Issue | Status |
 |------|-------|--------|
 | Pre-pump operator checklist | [#7](https://github.com/NovaLux12/carelink-bridge/issues/7) | open |
 
@@ -10,6 +10,23 @@ vulnerabilities. GitHub Security Advisories are the only
 channel that guarantees a private, tracked response for
 this repo.
 
+**What goes where.** This advisory channel is for vulnerabilities
+in *this bridge's code* — the token handling, the file writes,
+the fetch loop. Two related things live elsewhere:
+
+- **An exposure in Medtronic's own surface** — a published key,
+  an internal hostname in a public artefact, an auth gap — is a
+  research finding, not a bridge bug. **Never** report it here,
+  redacted or otherwise. Their intake and redaction rules are in
+  [NovaLux12/carelink-api-research's `SECURITY.md`](https://github.com/NovaLux12/carelink-api-research/blob/main/SECURITY.md);
+  follow those, not this page. They maintain
+  [security findings](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/08-security-findings.md)
+  on the vendor surface — and whether an exposure is already known,
+  publishable, or held back is their call, so please still report it
+  rather than assuming it is covered.
+- **A login, upload, or crash failure** with an unchanged vendor
+  surface is a plain bug — use the [bug form](https://github.com/NovaLux12/carelink-bridge/issues/new?template=bug.yml).
+
 ## Threat model
 
 This bridge handles:
 
@@ -273,7 +273,10 @@ The full 23-cell matrix, the two orthogonal axes of the discovery URL,
 and the guard that must check the cumulus track rather than the mere
 presence of the config key are in
 [ADR 0002](./adr/0002-discovery-app-version-pin.md). The verification
-date is in the constant's own header comment.
+date is in the constant's own header comment. The wider matrix, and the
+evidence that probing a newer cell re-derives a known document rather than
+revealing a new API, is maintained continuously in the research repo's
+[discovery & versions page](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/03-discovery-and-versions.md).
 
 ### Discovery-document tripwires (issue #77)
 
@@ -593,6 +596,13 @@ portal's public JS bundle also ships a hardcoded key present in the
 vendor's public bundle, tracked privately; that value is **not**
 reproduced in this repository.
 
+Vendor-side detail — the brokers, the AWS gateways behind them, and the
+CloudFront origin failure on the metadata broker — is mapped in the
+research repo's
+[admin portal & reporting page](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/07-admin-portal-and-reporting.md),
+with the credential-handling posture in its
+[security findings page](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/08-security-findings.md).
+
 If it is ever integrated it must stay **opt-in and off by default** —
 this is a second, much larger data surface than the fetch loop and
 should not be pulled on every cycle.
 
@@ -205,6 +205,14 @@ journald and points the operator at the constant to inspect.
 
 ## Notes
 
+- **Canonical version-matrix map lives in the research repo.** This ADR's
+  table is authoritative *for the bridge's pin*, but the wider cell-by-cell
+  matrix, the "what does probing a new version re-derive" result, and the
+  live re-verification history are maintained continuously in
+  [NovaLux12/carelink-api-research — `docs/03` discovery & versions](https://github.com/NovaLux12/carelink-api-research/blob/main/docs/03-discovery-and-versions.md)
+  and pinned by its regression suite. If a future probe contradicts the
+  table above, check there first and **file the discrepancy there** (its
+  weekly drift sweep is what notices) rather than editing this ADR in place.
 - Source: `src/discovery.ts` (the file's own header comment records
   a summary of the version matrix and the verification date).
 - **Re-probed live on 2026-10-08** (23 cells, unauthenticated, both