@company-semantics/contracts 57.0.0 → 58.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "57.0.0",
+  "version": "58.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -142,7 +142,7 @@
     "@types/node": "^22.20.1",
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
     "markdownlint-cli2": "^0.23.2",
@@ -151,8 +151,8 @@
     "tsx": "^4.23.12",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.67.0",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11",
     "yaml": "^2.9.0"
   },
   "pnpm": {

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'ffeb6e367b38' as const;
-export const SPEC_HASH_FULL = 'ffeb6e367b385ad32f7b46e4e74d276786d6cdf175352e57d0fc229dc8f506af' as const;
+export const SPEC_HASH = '49b741e4372d' as const;
+export const SPEC_HASH_FULL = '49b741e4372d56fb1a87312fe62f6e86ffd4987de590d03414ee833a4b6586b0' as const;

package/src/api/generated.ts

@@ -4834,6 +4834,10 @@ export interface components {
         };
         SendInviteBatchRequest: {
             expectedRevision: number;
+            message?: string;
+            roleByPersonId?: {
+                [key: string]: "admin" | "member";
+            };
         };
         InviteValidationResult: {
             valid: boolean;
@@ -5989,6 +5993,14 @@ export interface components {
                 /** @enum {string} */
                 relationshipType: "solid" | "dotted";
             }[];
+            unplaced: {
+                personId: string;
+                fullName: string;
+                /** @enum {string} */
+                state: "needs_review" | "excluded";
+                /** @enum {string} */
+                reason: "insufficient_evidence" | "conflicting_evidence" | "ambiguous_boundary" | "service_account" | "not_workforce" | "inactive";
+            }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
         IngestionOperationPollResponse: {

package/src/index.ts

@@ -798,20 +798,72 @@ export type {
 export {
   CanonicalPersonSchema,
   CanonicalOrgUnitSchema,
+  CanonicalPositionStatusSchema,
   CanonicalPositionSchema,
   CanonicalOccupancySchema,
   CanonicalReportingEdgeSchema,
+  CanonicalUnresolvedManagerResolutionSchema,
+  CanonicalUnresolvedManagerSchema,
   CanonicalFactsSchema,
 } from "./org/index";
 export type {
   CanonicalPerson,
   CanonicalOrgUnit,
+  CanonicalPositionStatus,
   CanonicalPosition,
   CanonicalOccupancy,
   CanonicalReportingEdge,
+  CanonicalUnresolvedManagerResolution,
+  CanonicalUnresolvedManager,
   CanonicalFacts,
 } from "./org/index";
 
+// Org-structure inference: a StructureInferenceSnapshot of the persisted graph
+// goes in, a StructureProposal — a proposed desired state, never database
+// commands — comes out. Typed evidence, targetUnitId for durable identity, and
+// exactly one PersonStructureOutcome per person in the snapshot. (PRD-00955)
+//
+// Acceptance attaches StructureProvenance — proposalOrigin, acceptedBy and
+// authority as three ORTHOGONAL axes, so accepting an AI proposal never rewrites
+// its origin as manual. mayOverrideAuthority is the single definition of
+// precedence, and it consults `authority` only. (PRD-00956)
+export {
+  StructureEvidenceSchema,
+  TOPOLOGY_ONLY_EVIDENCE_KINDS,
+  StructureUnitAuthoritySchema,
+  StructureProposalOriginSchema,
+  StructureAcceptedBySchema,
+  StructureAuthoritySchema,
+  StructureProvenanceSchema,
+  mayOverrideAuthority,
+  ProposedOrgUnitSchema,
+  PersonStructureOutcomeSchema,
+  StructureReviewItemSchema,
+  StructureProposalSchema,
+  StructurePersonFactSchema,
+  StructureReportingFactSchema,
+  ExistingUnitFactSchema,
+  ExistingPlacementFactSchema,
+  StructureInferenceSnapshotSchema,
+} from "./org/index";
+export type {
+  StructureEvidence,
+  StructureUnitAuthority,
+  StructureProposalOrigin,
+  StructureAcceptedBy,
+  StructureAuthority,
+  StructureProvenance,
+  ProposedOrgUnit,
+  PersonStructureOutcome,
+  StructureReviewItem,
+  StructureProposal,
+  StructurePersonFact,
+  StructureReportingFact,
+  ExistingUnitFact,
+  ExistingPlacementFact,
+  StructureInferenceSnapshot,
+} from "./org/index";
+
 // Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,

package/src/integrations/README.md

@@ -16,6 +16,10 @@ alongside `Meetings`, `Comms`, and `Docs`.
 
 - `HrConnectionStatusSchema` is a read projection: count and sync fields are
   `null` until the first successful sync (a connected, never-synced integration).
+- `revokedReason` is non-null only when `credentialState` is `'unusable'`, and
+  its enum mirrors the backend's `ConnectionRevokedReason` exactly — the app
+  `parse`s this projection, so a value missing from the enum throws rather than
+  degrades (ADR-CONTRACTS-138).
 - `HrConnectInputSchema` carries only the customer's provider `subdomain`; no
   secrets or provider credentials live in contracts.
 - Pure vocabulary — `zod` is the only runtime import (vocabulary-guard).

package/src/integrations/schemas.ts

@@ -83,6 +83,32 @@ export const HrConnectionStatusSchema = z
       description:
         "Health of the most recent sync; null when no sync has run yet.",
     }),
+    revokedReason: z
+      .enum([
+        "token_refresh_failed",
+        "missing_refresh_token",
+        "member_removed",
+        "app_uninstalled",
+        "tokens_revoked",
+      ])
+      .nullable()
+      .meta({
+        description:
+          "Why the credential died, when `credentialState` is 'unusable'. " +
+          "'token_refresh_failed' — the provider rejected the refresh grant, " +
+          "which is a sign-in that simply aged out and is fixed by " +
+          "reconnecting. 'missing_refresh_token' — there is nothing left to " +
+          "refresh with, so reconnecting is the ONLY repair. " +
+          "'member_removed' — the person whose account backed this " +
+          "connection left the org, so someone else must reconnect it. " +
+          "'app_uninstalled' / 'tokens_revoked' — the grant was withdrawn on " +
+          "the provider's side, and reconnecting will fail again until it is " +
+          "restored there. The distinction matters because the four cases " +
+          "ask different things of the reader: three are 'click Reconnect' " +
+          "and one is 'go fix it in the provider first'. Null whenever " +
+          "`credentialState` is not 'unusable', and null on a connection " +
+          "revoked before this field existed.",
+      }),
   })
   .meta({
     description: "Connection-status projection for an HR integration.",

package/src/notifications/__tests__/__snapshots__/monospace-budget.test.ts.snap

@@ -11,6 +11,7 @@ exports[`monospace budget > overhangs only where content is atomic 1`] = `
   "https://app.companysemantics.ai/doc/handbook?thread=th_456",
   "https://app.companysemantics.ai/invite/abc123",
   "https://app.companysemantics.ai/invite/def456",
+  "https://app.companysemantics.ai/invite/ghi789",
   "https://app.companysemantics.ai/meeting/8842",
   "https://app.companysemantics.ai/org/unit/42",
   "https://app.companysemantics.ai/owner-transfer/accept/tok123",

package/src/notifications/__tests__/__snapshots__/registry.test.ts.snap

@@ -24,6 +24,7 @@ exports[`NOTIFICATION_DEFINITIONS > titles every kind 1`] = `
   "companyMd.access_requested · With message": "Someone requested access to a document",
   "org.invite · Admin": "You've been invited to join Acme Corp on Company Semantics",
   "org.invite · Member": "You've been invited to join Acme Corp on Company Semantics",
+  "org.invite · Member + note": "You've been invited to join Acme Corp on Company Semantics",
   "org.ownership_transfer · No note (admin)": "You've been invited to become a workspace owner",
   "org.ownership_transfer · With note + from": "You've been invited to become a workspace owner",
   "org.ownership_transfer_completed · Default": "Workspace ownership has been transferred",

package/src/notifications/__tests__/__snapshots__/render-snapshot.test.ts.snap

@@ -3481,6 +3481,213 @@ If you weren't expecting this, no action is
 required.
 
 
+/* EOM */
+ⓒ 2026 • Company Semantics
+https://companysemantics.ai
+",
+}
+`;
+
+exports[`email render > org.invite · Member + note 1`] = `
+{
+  "amp": "<!DOCTYPE html>
+<html amp4email data-css-strict lang="en">
+<head><meta charset="utf-8">
+<script async src="https://cdn.ampproject.org/v0.js"></script>
+<style amp4email-boilerplate>body{visibility:hidden}</style>
+<style amp-custom>.csr-body { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; color: #1a1a1a; background-color: #ffffff; margin: 0; padding: 0; }
+.csr-frame { max-width: 520px; margin: 0 auto; }
+.csr-p-normal { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0; }
+.csr-p-tight { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0; }
+.csr-p-none { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0; }
+.csr-eom { color: #bbb; }
+.csr-signature-link { color: #0047FF; text-decoration: none; }
+.csr-warning { color: #e7000b; }
+.csr-hr-normal { border: none; border-top: 1px solid #bbb; margin: 0 0 20px 0; }
+.csr-hr-tight { border: none; border-top: 1px solid #bbb; margin: 0 0 4px 0; }
+.csr-hr-none { border: none; border-top: 1px solid #bbb; margin: 0; }
+.csr-hero-normal { max-width: 100%; margin: 0 0 20px 0; }
+.csr-hero-tight { max-width: 100%; margin: 0 0 4px 0; }
+.csr-hero-none { max-width: 100%; margin: 0; }
+.csr-cta-box-normal { display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0 0 20px 0; max-width: 220px; }
+.csr-cta-box-tight { display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0 0 4px 0; max-width: 220px; }
+.csr-cta-box-none { display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0; max-width: 220px; }
+.csr-cta-cell-linked { text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; }
+.csr-cta-cell-code { padding: 16px 24px; text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; }
+.csr-cta-label { text-decoration: underline; }
+.csr-cta-anchor { display: block; padding: 16px 24px; color: #0047FF; text-decoration: none; }
+.csr-cta-code { color: #0047FF; }
+.csr-chat-rule-top { border: none; border-top: 1px solid #bbb; margin: 12px 0 24px 0; }
+.csr-chat-rule-bottom { border: none; border-top: 1px solid #bbb; margin: 24px 0 12px 0; }
+.csr-chat-row-24 { margin: 0 0 24px 0; }
+.csr-chat-row-16 { margin: 0 0 16px 0; }
+.csr-chat-attribution { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch; }
+.csr-chat-avatar-left { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap; }
+.csr-chat-avatar-left-hidden { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap; }
+.csr-chat-avatar-right { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; white-space: nowrap; }
+.csr-chat-avatar-right-hidden { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap; }
+.csr-chat-channel-left { width: 100%; text-align: left; }
+.csr-chat-channel-right { width: 100%; text-align: right; }
+.csr-chat-bubble-wrap { display: inline-block; max-width: 100%; vertical-align: bottom; }
+.csr-bubble-user { border-radius: 8px 8px 0 8px; padding: 10px 14px; text-align: right; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666; }
+.csr-bubble-assistant { border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666; }
+.csr-dots-over-cta { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 20px; font-weight: bold; color: #666; text-align: center; margin: 0 0 16px 0; }
+.csr-dots-cell { width: 100%; text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 20px; font-weight: bold; color: #666; }
+.csr-cta-stack { display: inline-block; text-align: left; }
+.cs-cta-hover:hover { background-color: #d1ffff; }</style></head>
+<body class="csr-body">
+<div class="csr-frame">
+<p class="csr-p-normal">Hi there,</p>
+<p class="csr-p-normal">Acme Corp uses Company Semantics.</p>
+<hr class="cs-faint csr-chat-rule-top">
+<table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-24">
+  <tr>
+    <td class="csr-chat-avatar-left-hidden">[c_S]</td>
+    <td class="csr-chat-channel-right"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
+      <tr><td class="cs-bubble csr-bubble-user">We start planning next quarter on Monday — glad you are joining.</td></tr>
+    </table></td>
+    <td class="csr-chat-avatar-right">(•̀_ರ╮)</td>
+  </tr>
+  <tr>
+    <td></td>
+    <td class="cs-meta csr-chat-attribution">Alex Rivera</td>
+    <td></td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-16">
+  <tr>
+    <td class="csr-chat-avatar-left">[c_S]</td>
+    <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
+      <tr><td class="cs-bubble csr-bubble-assistant">Join to accept the invitation.</td></tr>
+    </table></td>
+    <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-24">
+  <tr>
+    <td class="csr-chat-avatar-left-hidden">[c_S]</td>
+    <td class="csr-chat-channel-left"><div class="csr-cta-stack"><table cellpadding="0" cellspacing="0" border="0" class="cs-cta cs-cta-hover csr-cta-box-none">
+  <tr><td class="csr-cta-cell-linked">
+    <a href="https://app.companysemantics.ai/invite/ghi789" class="cs-link csr-cta-anchor">&gt;&gt; <span class="csr-cta-label">JOIN</span> &lt;&lt;</a>
+  </td></tr>
+</table></div></td>
+    <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
+  </tr>
+</table>
+<hr class="cs-faint csr-chat-rule-bottom">
+<p class="csr-p-tight">From: Alex Rivera</p>
+<p class="csr-p-tight">Workspace: Acme Corp</p>
+<p class="csr-p-tight">Role: Member</p>
+<p class="csr-p-normal">Expires: Jun 13, 2026</p>
+<p class="csr-p-none">This invitation was sent via Company Semantics.<br>If you weren&#39;t expecting this, no action is required.</p>
+<p class="csr-p-none"><br><br><span class="cs-faint csr-eom">/* EOM */</span><br>ⓒ 2026 • Company Semantics<br><a href="https://companysemantics.ai" target="_blank" rel="noopener noreferrer" class="cs-link csr-signature-link">https://companysemantics.ai</a></p>
+</div>
+</body>
+</html>",
+  "html": "<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<style>.cs-cta-hover:hover { background-color: #d1ffff !important; }
+@media (prefers-color-scheme: dark) {
+body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
+.cs-faint { color: #666 !important; border-top-color: #666 !important; }
+.cs-meta { color: #8a8a8a !important; }
+.cs-cta { border-color: #00ffff !important; }
+.cs-cta-hover:hover { background-color: #154848 !important; }
+.cs-bubble { background: #154848 !important; color: #ffffff !important; }
+.cs-dots { color: #8a8a8a !important; }
+.cs-link { color: #00ffff !important; }
+.cs-destructive { color: #ff6b6b !important; }
+}</style>
+<!--[if mso]><style>.cs-cta td { padding: 16px 24px !important; }
+.cs-cta a { padding: 0 !important; }</style><![endif]--></head>
+<body style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; color: #1a1a1a; background-color: #ffffff; margin: 0; padding: 0;">
+<div style="max-width: 520px; margin: 0 auto;">
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Hi there,</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Acme Corp uses Company Semantics.</p>
+<hr class="cs-faint" style="border: none; border-top: 1px solid #bbb; margin: 12px 0 24px 0;">
+<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
+  <tr>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: right;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 0 8px; padding: 10px 14px; text-align: right; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">We start planning next quarter on Monday — glad you are joining.</td></tr>
+    </table></td>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>
+  <tr>
+    <td></td>
+    <td class="cs-meta" style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">Alex Rivera</td>
+    <td></td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 16px 0;">
+  <tr>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Join to accept the invitation.</td></tr>
+    </table></td>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
+  <tr>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: left;"><div style="display: inline-block; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" class="cs-cta cs-cta-hover" style="display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0; max-width: 220px;">
+  <tr><td style="text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px;">
+    <a href="https://app.companysemantics.ai/invite/ghi789" class="cs-link" style="display: block; padding: 16px 24px; color: #0047FF; text-decoration: none;">&gt;&gt; <span style="text-decoration: underline;">JOIN</span> &lt;&lt;</a>
+  </td></tr>
+</table></div></td>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>
+</table>
+<hr class="cs-faint" style="border: none; border-top: 1px solid #bbb; margin: 24px 0 12px 0;">
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">From: Alex Rivera</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Workspace: Acme Corp</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Role: Member</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Expires: Jun 13, 2026</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0;">This invitation was sent via Company Semantics.<br>If you weren&#39;t expecting this, no action is required.</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0;"><br><br><span class="cs-faint" style="color: #bbb;">/* EOM */</span><br>ⓒ 2026 • Company Semantics<br><a href="https://companysemantics.ai" target="_blank" rel="noopener noreferrer" class="cs-link" style="color: #0047FF; text-decoration: none;">https://companysemantics.ai</a></p>
+</div>
+</body>
+</html>",
+  "subject": "You've been invited to join Acme Corp on Company Semantics",
+  "text": "Hi there,
+
+Acme Corp uses Company Semantics.
+
+────────────────────────────────────────────────
+
+       ┌──────────────────────────────┐
+       │       We start planning next │
+       │ quarter on Monday — glad you │
+       │                 are joining. │  (•̀_ರ╮)
+       └──────────────────────────────┘
+                           Alex Rivera
+
+       ┌──────────────────────────────┐
+       │ Join to accept the           │
+[c_S]  │ invitation.                  │
+       └──────────────────────────────┘
+
+       *----------------*
+       |   >> JOIN <<   |
+       *----------------*
+
+       https://app.companysemantics.ai/invite/ghi789
+────────────────────────────────────────────────
+
+From: Alex Rivera
+Workspace: Acme Corp
+Role: Member
+Expires: Jun 13, 2026
+
+This invitation was sent via Company Semantics.
+If you weren't expecting this, no action is
+required.
+
+
 /* EOM */
 ⓒ 2026 • Company Semantics
 https://companysemantics.ai

package/src/notifications/__tests__/fixtures.ts

@@ -86,6 +86,15 @@ add("org.invite", "Member", {
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
+add("org.invite", "Member + note", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/ghi789`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  message: "We start planning next quarter on Monday — glad you are joining.",
+});
+
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",
   recipientName: "Sam Chen",

package/src/notifications/__tests__/org-invite.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The invitation's optional note.
+ *
+ * An invite is often the first thing someone ever receives from a workspace, so
+ * the one line of human context on it does real work — and it has to arrive
+ * ATTRIBUTED. A note rendered as product copy reads as boilerplate, which is
+ * the one thing it is not.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { createRenderContext } from "../context";
+import type { ChatUnitItem, NotificationContent } from "../content";
+import { orgInviteDefinition } from "../kinds/org-invite";
+import type { NotificationPayloads } from "../payloads";
+
+const CONTEXT = createRenderContext();
+
+const payload = (
+  over: Partial<NotificationPayloads["org.invite"]> = {},
+): NotificationPayloads["org.invite"] => ({
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: "https://app.companysemantics.ai/invite/abc123",
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  ...over,
+});
+
+function chatItems(content: NotificationContent): ChatUnitItem[] {
+  const elements = content.sections.flatMap((s) => s.elements);
+  const unit = elements.find((e) => e.type === "chatUnit");
+  if (!unit || unit.type !== "chatUnit") throw new Error("no chat unit");
+  return [...unit.items];
+}
+
+describe("org.invite", () => {
+  it("carries the note as the inviter's own words, above the join prompt", () => {
+    const items = chatItems(
+      orgInviteDefinition.compose(
+        payload({ message: "Glad you are joining." }),
+        CONTEXT,
+      ),
+    );
+    expect(items[0]).toEqual({
+      type: "message",
+      role: "user",
+      text: "Glad you are joining.",
+      from: "Alex Rivera",
+    });
+    // The prompt survives the note: the message is WHY someone was invited, the
+    // prompt is what to do about it.
+    expect(items[1]).toMatchObject({
+      role: "assistant",
+      text: "Join to accept the invitation.",
+    });
+  });
+
+  it("renders no message block at all without one", () => {
+    const items = chatItems(orgInviteDefinition.compose(payload(), CONTEXT));
+    expect(items.some((i) => i.type === "message" && i.role === "user")).toBe(
+      false,
+    );
+    expect(items[0]).toMatchObject({ role: "assistant" });
+  });
+
+  it("keeps the call to action last either way", () => {
+    for (const message of [undefined, "Welcome."]) {
+      const items = chatItems(
+        orgInviteDefinition.compose(payload({ message }), CONTEXT),
+      );
+      expect(items[items.length - 1]).toMatchObject({ type: "callToAction" });
+    }
+  });
+});

package/src/notifications/__tests__/render-snapshot.test.ts

@@ -92,6 +92,14 @@ add("org.invite", "Member", {
   acceptUrl: `${APP}/invite/def456`,
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
+add("org.invite", "Member + note", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/ghi789`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  message: "We start planning next quarter on Monday — glad you are joining.",
+});
 
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",

package/src/notifications/kinds/org-invite.ts

@@ -7,6 +7,7 @@
  * nothing left to catch. See ADR-CONTRACTS-085.
  */
 
+import type { ChatUnitItem } from "../content";
 import type { NotificationDefinition } from "../definition";
 
 import { formatExpiry, NOTICE, titleCase } from "../text";
@@ -14,7 +15,31 @@ import { formatExpiry, NOTICE, titleCase } from "../text";
 export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
   kind: "org.invite",
   compose: (payload, context) => {
-    const { inviterName, orgName, role, acceptUrl, expiresAt } = payload;
+    const { inviterName, orgName, role, acceptUrl, expiresAt, message } =
+      payload;
+
+    // The inviter's own words come FIRST and keep their name on them, above the
+    // prompt to join — a note attributed to nobody reads as product copy, which
+    // is the one thing it is not. The join prompt stays either way: the message
+    // is why this person was invited, the prompt is what to do about it.
+    const items: ChatUnitItem[] = [
+      ...(message
+        ? [
+            {
+              type: "message" as const,
+              role: "user" as const,
+              text: message,
+              from: inviterName,
+            },
+          ]
+        : []),
+      {
+        type: "message",
+        role: "assistant",
+        text: "Join to accept the invitation.",
+      },
+      { type: "callToAction", label: "JOIN", href: acceptUrl },
+    ];
 
     return {
       metadata: {
@@ -26,17 +51,7 @@ export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
           elements: [
             { type: "greeting" },
             { type: "body", text: `${orgName} uses Company Semantics.` },
-            {
-              type: "chatUnit",
-              items: [
-                {
-                  type: "message",
-                  role: "assistant",
-                  text: "Join to accept the invitation.",
-                },
-                { type: "callToAction", label: "JOIN", href: acceptUrl },
-              ],
-            },
+            { type: "chatUnit", items },
             {
               type: "keyValueTable",
               rows: [

package/src/notifications/payloads.ts

@@ -51,6 +51,13 @@ export interface NotificationPayloads {
     acceptUrl: string;
     /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
     expiresAt: string;
+    /**
+     * Optional note from the inviter, shown above the join prompt and attributed
+     * to them — the same shape `share.granted` and `org.unit_owner_granted` give
+     * a granter's message. Absent means no message block at all, never an empty
+     * one.
+     */
+    message?: string;
   };
   "org.unit_owner_granted": {
     /** Display name of the person who granted access */