Attribute a version to its package across prose distance, and put content/docs behind the gate (#13981) (#14017)

`check:vendor-version-stamps` did not read `content/docs`, and adding the root
alone was measured to be insufficient rather than merely weak: the one site that
matters, a customer-facing attestation in `permissions/authentication.mdx`,
still landed UNATTRIBUTED because the package name sits ~90 characters back
across a wrapped prose line, past the character window attribution used.

Attribution is now two rules, neither of them a width: a name reaches to the end
of its SENTENCE (a blank line, a bullet, a heading, a JSX tag, a `.` or a `;`
outside a parenthetical), and the NEAREST CLAIMANT wins — every package in the
tree may claim, with the vocabulary read from `pnpm-lock.yaml`. Widening the old
window instead was swept and rejected with numbers: at gap 120 it attributes 23
more sites and binds `better-call@1.3.7`, `@better-auth/utils@0.4.2`,
`minimatch 10.2.3` and an internal `'0.0.0-polyfill'` sentinel to a watched
family member none of them is about, and at 200 it reds a permanently true
historical sentence. `--attribution-sweep` prints both mechanisms side by side.

Attribution alone did not separate the docs population's two buckets, so the
classifier gains one shape: an UNANCHORED MEASUREMENT — "measured on 1.7.1"
resting a standing claim on a reading taken against a version that no longer
installs, with nothing saying when. The rule is POSITIONAL, because a
sentence-wide substring test reds "Measured on the configuration the range
*does* govern (…), 1.7.1 behaves identically" — where the verb governs a
configuration, not the version.

The gate found six stamps the old attribution could not see. All six are
repaired the way the gate itself teaches — the sentence is scoped or anchored,
never restamped, so no measurement is manufactured.


Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

content/docs/permissions/authentication.mdx

@@ -850,11 +850,12 @@ fallback: omit it and the member simply joins no team.
 
 <Callout type="warn" title="This is an ObjectStack mount, not a better-auth route">
 better-auth declares `addMember` as a **server-only** API with no HTTP path of
-its own — measured on 1.7.1, where `addMember` builds its endpoint with no path
-argument while every sibling in the same module (`/organization/remove-member`,
-`/organization/list-members`, `/organization/leave`, …) passes one. So the
-vendor's documentation does not list this URL, and an audit that enumerates
-better-auth's mounted surface will not find it there either. ObjectStack mounts it ahead of the
+its own — measured on the then-installed 1.7.1, where `addMember` builds its
+endpoint with no path argument while every sibling in the same module
+(`/organization/remove-member`, `/organization/list-members`,
+`/organization/leave`, …) passes one. So the vendor's documentation does not
+list this URL, and an audit that enumerates better-auth's mounted surface will
+not find it there either. ObjectStack mounts it ahead of the
 catch-all and wraps the vendor's server-only endpoint; the vendor's own checks
 (already-a-member, membership limit, team resolution, hooks) are not
 reimplemented.

packages/cli/test/init.test.ts

@@ -388,13 +388,13 @@ describe('benign peer-skew declarations (#10326)', () => {
 
   it('kept the @better-auth/utils widening when the better-call pin retired (#3653)', () => {
     // @better-auth/scim appeared in TWO entries for two unrelated reasons, and
-    // they retire on different days — which HAPPENED: the better-call one went
-    // with the rc pin (stable 1.7.1 peers better-call 1.4.0), while the utils
-    // one outlives it (stable 1.7.1 still peers @better-auth/utils 0.4.2;
-    // its own retirement key is the pnpm 10.31 floor). Deleting both together
-    // — the obvious move when the rc pin lifted — would have silently put the
-    // utils report back on a newcomer's first screen; this pin is what stops
-    // that regression from ever landing quietly.
+    // they retire on different days — which HAPPENED in #3653: the better-call
+    // one went with the rc pin (stable 1.7.1 peers better-call 1.4.0), while
+    // the utils one outlives it (stable 1.7.1 still peers @better-auth/utils
+    // 0.4.2; its own retirement key is the pnpm 10.31 floor). Deleting both
+    // together — the obvious move when the rc pin lifted — would have silently
+    // put the utils report back on a newcomer's first screen; this pin is what
+    // stops that regression from ever landing quietly.
     expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>better-call']).toBeUndefined();
     expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>@better-auth/utils']).toBe('0.5.0');
   });

packages/plugins/plugin-auth/src/admin-has-permission-endpoint.ts

@@ -105,8 +105,9 @@ const isPlainObject = (v: unknown): v is Record<string, unknown> =>
 
 /**
  * The permission-query bodies the installed vendor handler EVALUATES, and no
- * others (see the header for why both directions matter). Measured on
- * better-auth 1.7.1 (`dist/plugins/admin/routes.mjs`, `userHasPermission`):
+ * others (see the header for why both directions matter). Measured on the
+ * then-installed better-auth 1.7.1 (`dist/plugins/admin/routes.mjs`,
+ * `userHasPermission`):
  *
  *  - the zod body schema is `{ userId?: coerce.string, role?: string }`
  *    intersected with `xor(permission | permissions)`, each a

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -2101,9 +2101,10 @@ export class AuthManager {
         // resolved `baseURL` origin and treats `trustedOrigins` as purely
         // ADDITIVE, so an empty list and an omitted key are equivalent and
         // both leave exactly the deployment's own origin trusted; every other
-        // origin is refused with `403 INVALID_ORIGIN`. Measured against
-        // better-auth 1.7.1 (`getTrustedOrigins` in `dist/context/helpers.mjs`,
-        // `validateOrigin` in `dist/api/middlewares/origin-check.mjs`).
+        // origin is refused with `403 INVALID_ORIGIN`. Measured against the
+        // then-installed better-auth 1.7.1 (`getTrustedOrigins` in
+        // `dist/context/helpers.mjs`, `validateOrigin` in
+        // `dist/api/middlewares/origin-check.mjs`).
         if (
           process.env.NODE_ENV !== 'production' &&
           !origins.length && (!corsOrigin || corsOrigin === '*')

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -2556,7 +2556,7 @@ export class AuthPlugin implements Plugin {
     // ────────────────────────────────────────────────────────────────────
     // #9941 — organization/add-member. better-auth declares `addMember`
     // WITHOUT an HTTP path (server-only `auth.api.addMember`; measured on the
-    // installed 1.7.1), so the catch-all never mounts it — yet the
+    // then-installed 1.7.1), so the catch-all never mounts it — yet the
     // `sys_member` `add_member` toolbar action has always targeted this URL,
     // and on a multi-org posture it is the only UI path that can attach an
     // existing user to an organization. This mount restores that declared

packages/plugins/plugin-auth/src/organization-add-member.ts

@@ -7,7 +7,7 @@
  * ── Why this mount exists (the measurement) ─────────────────────────────────
  *
  * better-auth declares `addMember` WITHOUT an HTTP path — measured on the
- * installed 1.7.1, `dist/plugins/organization/routes/crud-members.mjs`:
+ * then-installed 1.7.1, `dist/plugins/organization/routes/crud-members.mjs`:
  * `addMember` returns `createAuthEndpoint({ method: "POST", ... })` (no path
  * argument), while its siblings keep theirs
  * (`createAuthEndpoint("/organization/remove-member", …)`,