docs(skills): sever the X-Tenant-ID cause-and-effect in the auth guide

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code

[os-sam]

Fixes#5704

What was wrong

skills/objectui/guides/auth-permissions.md, "Multi-tenancy" joined two true facts with a colon that read as cause-and-effect: createAuthenticatedFetch sends X-Tenant-ID, and the backend applies row-level isolation — implying the header is what makes tenant scoping work. Measured truth:

• Scoping comes from the session — resolveAuthzContext (framework), which reads session.activeOrganizationId and no request header.
• The header is an edge routing hint, one of six TenantRoutingConfigSchema identification sources, ranked second — behind subdomain.
• Trusting it as identity is the recorded plugin-sharing vulnerability (forged attribution / link enumeration).

The skill was teaching the exact belief that caused that fix.

The change

Rewrote the one paragraph to say scoping comes from the session, name the header as a routing hint rather than identity, and repoint to packages/auth/README.md, "The X-Tenant-ID edge contract" (added by #5279 / PR #5706, re-verified present at that path on origin/main before linking) for the full contract — what it means, who stamps/reads it, and the unstamped-first-request window. Net +2 lines in a 348-line file, per the net-line budget on this card.

Whole-package value-density

skills/objectui/ (this repo's one published skill: SKILL.md + guides/ + rules/ + README.md) is 5688 lines before this change, 5690 after. The section keeps its size and gains a correction that removes a security-adjacent misconception from prose an AI integrator reads before wiring multi-tenancy — no tutorial content was added, no other paragraph touched.

Verification

• node scripts/check-changeset-presence.mjs → ✅ No source of a released package changed in this range, so no changeset is owed. (the file isn't under any package directory the gate tracks) — no changeset added.
• node scripts/check-skills-paths.mjs → green, with a positive control: corrupting the new packages/auth/README.md reference to a nonexistent path turned the gate red (❌ 1 stated path does not exist), then restoring it turned it green again — confirms the gate actually reads the new line.
• node scripts/check-control-bytes.mjs, node scripts/check-doc-fence-languages.mjs → green.
• pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx (the only test in the repo that lifts a block from this guide file — a different section, the PermissionProvider example) → 8 passed (8), unaffected by this edit.
• Re-verified the repoint target myself on origin/main before linking: packages/auth/README.md:140 is ## The \X-Tenant-ID` edge contract`.
• Read the shipped code path this card is about (resolveAuthzContext, plugin-sharing, TenantRoutingConfigSchema) — the shipped product does not trust the header as identity; the false belief was confined to this doc paragraph, consistent with triage's Task grading. Not re-escalating.

Governed surface — human merge required, left as draft

This PR's diff is under skills/**, which scripts/check-governed-queue-guard.mjs / .github/workflows/governed-surface-guard.yml treat as governed (GOVERNED_SURFACES includes skills/ — "the published skills catalog"). Per that guard: do not mark ready, do not enqueue, do not enable auto-merge. This PR stays in draft for a maintainer (os-zhuang / hotlong) to merge by hand.

---

Generated by Claude Code