@company-semantics/contracts 92.0.0 → 93.1.0

package/src/chat/__tests__/page-context.test.ts

@@ -23,13 +23,21 @@
  *   no-sibling-imports invariant intact (the same pattern as
  *   runtime-profile.test.ts).
  *
- * It is skipped when the app is not checked out beside this repo — contracts
- * consumed standalone from npm, or contracts CI, which by design has no app
- * checkout because contracts is the root of the dependency tree. The inverted
- * marker test makes the reporter say so rather than showing a silent pass.
+ * Where the app is read from: `resolveSibling` (tests/workspace-sibling.ts), the
+ * workspace's sibling rule (ci ADR-CI-276): this session's app worktree when
+ * the session holds one, else app's committed origin/main; never a primary's
+ * working tree. It used to probe `<workspace>/company-semantics-app` (the
+ * PRIMARY) and `../company-semantics-app` from cwd for
+ * `src/platform/route-parser.ts`, a path app has since moved to
+ * `src/lib/nav/route-parser.ts`, so it skipped everywhere (ci ADR-CI-294
+ * follow-up). A moved file now fails the read.
+ *
+ * Inside the workspace a missing or unreadable app FAILS this file. The parity
+ * tests skip, and the inverted marker test says why, only in a standalone
+ * clone (no other company-semantics-* checkout beside it): contracts consumed
+ * from npm, or contracts CI, which by design has no app checkout because
+ * contracts is the root of the dependency tree.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, sep } from "node:path";
 import { describe, it, expect } from "vitest";
 import {
   ChatPageContextSchema,
@@ -37,6 +45,7 @@ import {
   CHAT_PAGE_SCOPES,
   CHAT_PAGE_ENTITY_TYPES,
 } from "../schemas.js";
+import { resolveSibling } from "../../../tests/workspace-sibling.js";
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -56,52 +65,22 @@ const A_DOCUMENT_BODY = `# Q3 plan\n${"Revenue grew. ".repeat(200)}`;
 // Locating the app checkout that governs this run
 // ---------------------------------------------------------------------------
 
-/**
- * Probed in order:
- *   1. The app worktree mirroring this one. Ralph checks the same branch of
- *      every repo out at the same relative path, so a contracts worktree has an
- *      app worktree beside it carrying the branch's route grammar. The app MAIN
- *      checkout sits on another branch entirely, and comparing against it would
- *      report drift for a value this branch already corrected.
- *   2. The app main checkout in the same workspace.
- *   3. The plain sibling guess, for a non-worktree local dev layout.
- */
-function resolveAppRoot(): string | undefined {
-  const candidates: string[] = [];
-
-  const segments = process.cwd().split(sep);
-  const contractsIdx = segments.lastIndexOf("company-semantics-contracts");
-  if (contractsIdx !== -1) {
-    const workspaceRoot = segments.slice(0, contractsIdx).join(sep);
-    const worktreeSuffix = segments.slice(contractsIdx + 1);
-    const appRoot = resolve(workspaceRoot, "company-semantics-app");
-    if (worktreeSuffix.length > 0) {
-      candidates.push(resolve(appRoot, ...worktreeSuffix));
-    }
-    candidates.push(appRoot);
-  }
-  candidates.push(resolve(process.cwd(), "..", "company-semantics-app"));
-
-  return candidates.find((root) =>
-    existsSync(resolve(root, "src", "platform", "route-parser.ts")),
-  );
-}
+const APP_ROUTE_PARSER = "src/lib/nav/route-parser.ts";
 
-const APP_ROOT = resolveAppRoot();
-const appAvailable = APP_ROOT !== undefined;
+// Throws (failing this file loudly) inside the workspace when the app cannot
+// be resolved; null only in a standalone clone.
+const app = await resolveSibling("company-semantics-app");
+const appAvailable = app !== null;
 
 /** The body of the app's `export type Route = ...;` union, as a string. */
 function appRouteUnionSource(): string {
-  const source = readFileSync(
-    resolve(APP_ROOT!, "src", "platform", "route-parser.ts"),
-    "utf8",
-  );
+  const source = app!.read(APP_ROUTE_PARSER);
   // Terminated by the blank line after the union, because `;` also ends every
   // member field inside it.
   const match = source.match(/export type Route =([\s\S]*?);\r?\n\r?\n/);
   if (!match?.[1]) {
     throw new Error(
-      "Could not locate the `Route` union in app src/platform/route-parser.ts. " +
+      `Could not locate the \`Route\` union in app ${APP_ROUTE_PARSER}. ` +
         "If the declaration was renamed or restructured, update this test — do " +
         "NOT delete it, or the view vocabulary can drift out of step unseen.",
     );

package/src/chat/__tests__/runtime-profile.test.ts

@@ -18,59 +18,35 @@
  *   imports, keeping the contracts no-sibling-imports invariant intact (the
  *   same pattern as tests/org/reserved-slug-roundtrip.test.ts).
  *
- * They are skipped when the backend is not checked out beside this repo — e.g.
- * contracts consumed standalone from npm, or contracts CI, which by design has
- * no backend checkout because contracts is the root of the dependency tree.
- * Drift introduced on the backend side is therefore NOT gated by contracts CI;
- * it is caught here in a workspace checkout, and the inverted marker test below
- * makes the reporter say so rather than showing a silent pass.
+ * Where the backend is read from: `resolveSibling` (tests/workspace-sibling.ts),
+ * the workspace's sibling rule (ci ADR-CI-276): this session's backend worktree
+ * when the session holds one, else backend's committed origin/main; never a
+ * primary's working tree, which may hold another session's uncommitted work.
+ * It used to probe `<workspace>/company-semantics-backend` (the PRIMARY) and
+ * `../company-semantics-backend` from cwd (ci ADR-CI-294 follow-up).
+ *
+ * Inside the workspace a missing or unreadable backend FAILS this file. The
+ * parity tests skip, and the inverted marker test says why, only in a
+ * standalone clone (no other company-semantics-* checkout beside it): contracts
+ * consumed from npm, or contracts CI, which by design has no backend checkout
+ * because contracts is the root of the dependency tree. Drift introduced on the
+ * backend side is therefore NOT gated by contracts CI; it is caught here in a
+ * workspace checkout.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, sep } from "node:path";
 import { describe, it, expect } from "vitest";
 import {
   CHAT_RUNTIME_PROFILES,
   DEFAULT_CHAT_RUNTIME_PROFILE,
 } from "../runtime-profile.js";
+import { resolveSibling } from "../../../tests/workspace-sibling.js";
 
-/**
- * Locate the backend checkout that governs this run.
- *
- * Probed in order:
- *   1. The backend worktree mirroring this one. Ralph checks the same branch of
- *      every repo out at the same relative path, so a contracts worktree has a
- *      backend worktree beside it carrying the branch's constants. The backend
- *      MAIN checkout sits on another branch entirely, and comparing against it
- *      would report drift for a value this branch already corrected.
- *   2. The backend main checkout in the same workspace.
- *   3. The plain sibling guess, for a non-worktree local dev layout.
- */
-function resolveBackendRoot(): string | undefined {
-  const candidates: string[] = [];
-
-  const segments = process.cwd().split(sep);
-  const contractsIdx = segments.lastIndexOf("company-semantics-contracts");
-  if (contractsIdx !== -1) {
-    const workspaceRoot = segments.slice(0, contractsIdx).join(sep);
-    const worktreeSuffix = segments.slice(contractsIdx + 1);
-    const backendRoot = resolve(workspaceRoot, "company-semantics-backend");
-    if (worktreeSuffix.length > 0) {
-      candidates.push(resolve(backendRoot, ...worktreeSuffix));
-    }
-    candidates.push(backendRoot);
-  }
-  candidates.push(resolve(process.cwd(), "..", "company-semantics-backend"));
-
-  return candidates.find((root) =>
-    existsSync(resolve(root, "src", "chat", "orchestrator", "factory.ts")),
-  );
-}
-
-const BACKEND_ROOT = resolveBackendRoot();
-const backendAvailable = BACKEND_ROOT !== undefined;
+// Throws (failing this file loudly) inside the workspace when the backend
+// cannot be resolved; null only in a standalone clone.
+const backend = await resolveSibling("company-semantics-backend");
+const backendAvailable = backend !== null;
 
 function readBackendSource(...relative: string[]): string {
-  return readFileSync(resolve(BACKEND_ROOT!, ...relative), "utf8");
+  return backend!.read(relative.join("/"));
 }
 
 /** Extract the single capture of `pattern`, or explain what moved. */

package/src/generated/openapi-routes.ts

@@ -95,6 +95,7 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
   '/api/factory/kpis': ['GET'],
+  '/api/factory/lineage': ['GET'],
   '/api/factory/quality/changes': ['POST'],
   '/api/factory/quality/corpus': ['GET'],
   '/api/factory/quality/deployments': ['POST'],

package/src/message-parts/README.md

@@ -17,6 +17,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `SuggestedRepliesPart` is a surface but NOT a governed one: a chip fires an ordinary user turn (no `executionId`, no `submitEndpoint`), is stateless (clicking never consumes it) and advisory (the composer stays enabled) — so it is outside the at-most-one-governed-surface-per-turn rule
 - `WorkflowProgressPart` is the second non-governed surface: a two-field ANCHOR (`workflowId`, `workflowType`) to a durable background workflow. It presents no decision, carries no result snapshot (minted at t=0; parts are never rewritten) and no `startedAt` (operational state stays off immutable content), and names no domain vocabulary — live state is hydrated from the generic workflow projection read
 - `InputRequestPart` (`data-input-request` on the wire) is the GENERIC, GOVERNED anchor for a reviewed request: `{ requestType, requestId, stepCount, withheldCount }`, with every invariant of the structure-review anchor (anchor only — no cards, no endpoints, no staleness hashes; counts against the at-most-one-governed-surface-per-turn rule; emission is orchestration-driven). `isInputRequestDataPartShape` checks `requestType` as a non-empty string, NOT as a member of `INPUT_REQUEST_TYPES`: an unknown type renders nothing but never invalidates a persisted part
+- `AffordanceOfferPart` (`data-affordance-offer` on the wire) is the fourth non-governed surface: the next steps a pushed chat OFFERS, frozen with it as `OfferedAffordance` instances (control ADR `affordance-system`). Ids and args only — never labels, hrefs or a projected id (`review.open`), at most `MAX_OFFERED_AFFORDANCES`; written once with its message and never re-derived; the app renders each as a real control, re-gated per viewer. Built by `WireSurfaceBuilder.affordanceOffer`; emission is orchestration-driven (the proactive chat writer), never a model choice
 - `StructureReviewPart` (`data-structure-review`) is FROZEN, not retired: it stays in `SurfacePart` and parses forever because persisted transcripts carry it, and org-structure keeps emitting it
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
@@ -24,6 +25,9 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 ## Public API
 
 - `AddPartResult` _(type)_ — Result of adding a part to the builder.
+- `AffordanceOfferData` _(type)_ — Affordance offer data payload: the frozen, ordered offer.
+- `AffordanceOfferDataPart` _(type)_ — Affordance offer data part (wire format, as persisted in `chat_messages.parts`).
+- `AffordanceOfferPart` _(type)_ — Affordance offer message part (semantic type, as rendered).
 - `AssistantMessagePart` _(type)_ — All assistant message part types.
 - `CONFIRMATION_LABELS` — Human-readable confirmation dialog titles for each execution kind.
 - `CandidateSource` _(type)_ — How the frontend sources candidate values for an editable field. - `inline`: the options are shipped with the…
@@ -116,6 +120,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 
 **Internal domains:**
 
+- `affordances`
 - `chat`
 - `execution`
 - `input-requests`

package/src/message-parts/affordance-offer.ts

@@ -0,0 +1,44 @@
+/**
+ * Affordance Offer Part Types
+ *
+ * The next steps a message OFFERS, frozen with it (control ADR
+ * affordance-system). A pushed proactive chat carries its composer's
+ * `affordances` here so the app renders them as real controls — re-gated per
+ * viewer at render, live availability read separately, executed only by the
+ * server — instead of as chips that merely send a prompt.
+ *
+ * AFFORDANCE OFFER INVARIANTS:
+ * - OFFERED INSTANCES ONLY. Ids and their args, never labels or hrefs (the app
+ *   owns both), never a projected id (`review.open`), at most
+ *   MAX_OFFERED_AFFORDANCES.
+ * - WRITTEN ONCE, with the message it belongs to; never re-derived.
+ * - SHARE-SAFE. Ids and opaque target ids only.
+ * - NON-GOVERNED. It presents no decision and consumes no surface budget.
+ * - Emission is orchestration-driven (the proactive chat writer), never a model
+ *   choice.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part
+ * types to null and drops it.
+ */
+
+import type { OfferedAffordance } from "../affordances/affordance";
+
+/** Affordance offer data payload: the frozen, ordered offer. */
+export interface AffordanceOfferData {
+  affordances: readonly OfferedAffordance[];
+}
+
+/** Affordance offer message part (semantic type, as rendered). */
+export interface AffordanceOfferPart {
+  type: "affordance-offer";
+  data: AffordanceOfferData;
+}
+
+/**
+ * Affordance offer data part (wire format, as persisted in
+ * `chat_messages.parts`). Uses AI SDK's data-{name} convention.
+ */
+export interface AffordanceOfferDataPart {
+  type: "data-affordance-offer";
+  data: AffordanceOfferData;
+}

package/src/message-parts/index.ts

@@ -97,6 +97,13 @@ export type {
   WorkflowOutcomeDataPart,
 } from "./workflow-outcome";
 
+// Affordance offer types (non-governed, the frozen offer on a pushed chat)
+export type {
+  AffordanceOfferData,
+  AffordanceOfferPart,
+  AffordanceOfferDataPart,
+} from "./affordance-offer";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -22,6 +22,7 @@ import type { InputRequestPart } from "./input-request";
 import type { SuggestedRepliesPart } from "./suggested-replies";
 import type { WorkflowProgressPart } from "./workflow-progress";
 import type { WorkflowOutcomePart } from "./workflow-outcome";
+import type { AffordanceOfferPart } from "./affordance-offer";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -130,6 +131,10 @@ export interface TablePart {
  * workflow's execution epoch, carried on its settlement message. It presents no
  * decision; a review disposition is delivered as its own InputRequestPart.
  *
+ * AffordanceOfferPart is the fourth non-governed member: the next steps a pushed
+ * chat offers, frozen with it as affordance instances (control ADR
+ * affordance-system). It presents no decision and consumes no surface budget.
+ *
  * InputRequestPart is GOVERNED, like StructureReviewPart: it anchors a reviewed
  * request that asks the person to decide, so it counts against the
  * at-most-one-governed-surface-per-turn budget. It is the generic anchor;
@@ -148,7 +153,8 @@ export type SurfacePart =
   | InputRequestPart
   | SuggestedRepliesPart
   | WorkflowProgressPart
-  | WorkflowOutcomePart;
+  | WorkflowOutcomePart
+  | AffordanceOfferPart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -39,6 +39,10 @@ import type {
   WorkflowOutcomeData,
   WorkflowOutcomeDataPart,
 } from "./workflow-outcome";
+import type {
+  AffordanceOfferData,
+  AffordanceOfferDataPart,
+} from "./affordance-offer";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -272,6 +276,20 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build an affordance-offer data part: the frozen next steps a pushed chat
+   * offers (control ADR affordance-system). Non-governed; ids and args only.
+   *
+   * @param data - The offered affordance instances, in the producer's order
+   * @returns Wire-format affordance offer part
+   */
+  affordanceOffer(data: AffordanceOfferData): AffordanceOfferDataPart {
+    return {
+      type: "data-affordance-offer",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

package/src/notifications/README.md

@@ -131,9 +131,23 @@ deliberately (ADR-CONTRACTS-086):
   `chat.mention`: a kind is composable prose for a caller with an explicit
   trigger, and naming it on a plan would make the proactive pipeline send it
   autonomously — notify/'s INV-1 to grant, not this union's.
-- This domain depends on NOTHING outside itself. The `notifications → email`
-  imports that existed while both layers did are gone with the directory, and
-  nothing may reintroduce one.
+- This domain depends on nothing outside itself except one **type-only** import:
+  `content.ts` reads `OfferedAffordance` from `../affordances/affordance` for
+  `CallToAction.affordance`. The `notifications → email` imports that existed
+  while both layers did are gone with the directory, and nothing may reintroduce
+  one.
+- `CallToAction.affordance` names the catalog affordance a link performs
+  (control ADR affordance-system; contracts ADR
+  affordance-catalog-wave-and-grounded-ctas). It is present exactly when the
+  link does what a catalog id names — the three `billing.*` kinds
+  (`billing.open`), `chat.shared` (`chat.open` with the payload's `chatId`),
+  `companyMd.access_request_approved` (`companyMd.openDoc` with `docId`) and
+  `org.unit_owner_granted` (`team.open` with `unitId`) — and the label line
+  carries `// cta-grounded: <id>`. It is absent for an OTP code (no `href`) and
+  for a link no catalog id names (an invite acceptance, a comment). Renderers
+  ignore it and draw the link as before. Body prose around a call to action
+  states facts and never tells the reader what to do; the `cta-prose-ratchet`
+  guard and `__tests__/grounded-ctas.test.ts` hold that line.
 - A kind IS its definition. Every `NotificationKind` has facts in `payloads.ts`
   and a `compose` in `kinds/`, both compiler-enforced via `NotificationPayloads[K]`.
 - Capability belongs to the **renderer** (`Renderer.supports`), never to an

package/src/notifications/__tests__/README.md

@@ -13,6 +13,10 @@ to.
 - `render-snapshot.test.ts` + `__snapshots__/` — those fixtures rendered through
   the email channel, as vitest snapshots. This is the fence: **a diff here means
   a real sent email changed.**
+- `grounded-ctas.test.ts` — a linked call to action whose link a catalog id
+  names carries that affordance, targeting the fixture payload's own id; a code
+  to copy never carries one; and no grounded or share notification body tells
+  the reader what to do (control ADR affordance-system).
 
 ## The retired output-parity golden (ADR-CONTRACTS-087)
 

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

@@ -552,7 +552,7 @@ exports[`email render > billing.auto_recharge_failed · Default 1`] = `
 <p class="csr-p-normal">Acme Corp tried to top up its AI balance automatically and the charge was not completed.</p>
 <p class="csr-p-tight">Workspace: Acme Corp</p>
 <p class="csr-p-normal">Status: Top-up failed</p>
-<p class="csr-p-normal">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits rather than running the same card again — so updating the payment method is what resolves this.</p>
+<p class="csr-p-normal">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits before charging the same card a second time — so updating the payment method is what resolves this.</p>
 <table cellpadding="0" cellspacing="0" border="0" class="cs-cta cs-cta-hover csr-cta-box-normal">
   <tr><td class="csr-cta-cell-linked">
     <a href="https://app.companysemantics.ai/org/billing" class="cs-link csr-cta-anchor">&gt;&gt; <span class="csr-cta-label">OPEN BILLING</span> &lt;&lt;</a>
@@ -588,7 +588,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Acme Corp tried to top up its AI balance automatically and the charge was not completed.</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 20px 0;">Status: Top-up failed</p>
-<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits rather than running the same card again — so updating the payment method is what resolves this.</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits before charging the same card a second time — so updating the payment method is what resolves this.</p>
 <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 0 20px 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/org/billing" class="cs-link" style="display: block; padding: 16px 24px; color: #0047FF; text-decoration: none;">&gt;&gt; <span style="text-decoration: underline;">OPEN BILLING</span> &lt;&lt;</a>
@@ -610,8 +610,8 @@ Status: Top-up failed
 
 AI work carries on until the remaining balance
 is spent, and then pauses. The next attempt is
-not immediate — the system waits rather than
-running the same card again — so updating the
+not immediate — the system waits before charging
+the same card a second time — so updating the
 payment method is what resolves this.
 
 *------------------------*
@@ -1590,7 +1590,7 @@ exports[`email render > chat.shared · Long title 1`] = `
 <body class="csr-body">
 <div class="csr-frame">
 <p class="csr-p-normal">Hi there,</p>
-<p class="csr-p-normal">A chat was shared with you. You can take part in it.</p>
+<p class="csr-p-normal">A chat was shared with you, and you are a participant.</p>
 <hr class="cs-faint csr-chat-rule-top">
 <table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-24">
   <tr>
@@ -1654,7 +1654,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
 <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;">
 <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;">A chat was shared with you. You can take part in it.</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">A chat was shared with you, and you are a participant.</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>
@@ -1699,8 +1699,8 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   "subject": "A chat has been shared with you",
   "text": "Hi there,
 
-A chat was shared with you. You can take part in
-it.
+A chat was shared with you, and you are a
+participant.
 
 ────────────────────────────────────────────────
 
@@ -2909,7 +2909,7 @@ exports[`email render > companyMd.access_request_approved · Editor 1`] = `
   <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">Open to view.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">The document is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -2962,7 +2962,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <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;">Open to view.</td></tr>
+      <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;">The document is ready for you.</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>
@@ -2995,7 +2995,8 @@ Your access request was approved.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-[c_S]  │ Open to view.                │
+       │ The document is ready for    │
+[c_S]  │ you.                         │
        └──────────────────────────────┘
 
        *----------------*
@@ -3257,7 +3258,7 @@ exports[`email render > companyMd.access_request_approved · Viewer 1`] = `
   <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">Open to view.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">The document is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -3310,7 +3311,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <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;">Open to view.</td></tr>
+      <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;">The document is ready for you.</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>
@@ -3343,7 +3344,8 @@ Your access request was approved.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-[c_S]  │ Open to view.                │
+       │ The document is ready for    │
+[c_S]  │ you.                         │
        └──────────────────────────────┘
 
        *----------------*
@@ -5059,7 +5061,7 @@ exports[`email render > org.unit_owner_granted · Delegate with expiry 1`] = `
   <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">Open the team to get started.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">Platform Engineering is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -5113,7 +5115,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <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;">Open the team to get started.</td></tr>
+      <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;">Platform Engineering is ready for you.</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>
@@ -5150,8 +5152,8 @@ strategy, and execution against goals.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-       │ Open the team to get         │
-[c_S]  │ started.                     │
+       │ Platform Engineering is      │
+[c_S]  │ ready for you.               │
        └──────────────────────────────┘
 
        *-----------------------*
@@ -5249,7 +5251,7 @@ exports[`email render > org.unit_owner_granted · Unit owner + message 1`] = `
   <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">Open the team to get started.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">Platform Engineering is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -5316,7 +5318,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <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;">Open the team to get started.</td></tr>
+      <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;">Platform Engineering is ready for you.</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>
@@ -5358,8 +5360,8 @@ strategy, and execution against goals.
                             Jordan Lee
 
        ┌──────────────────────────────┐
-       │ Open the team to get         │
-[c_S]  │ started.                     │
+       │ Platform Engineering is      │
+[c_S]  │ ready for you.               │
        └──────────────────────────────┘
 
        *-----------------------*
@@ -5853,7 +5855,7 @@ exports[`email render > share.granted · Meeting · viewer · no title 1`] = `
   <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">Open to view.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">It is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -5905,7 +5907,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <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;">Open to view.</td></tr>
+      <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;">It is ready for you.</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>
@@ -5937,7 +5939,7 @@ A meeting was shared with you.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-[c_S]  │ Open to view.                │
+[c_S]  │ It is ready for you.         │
        └──────────────────────────────┘
 
        *----------------*

package/src/notifications/__tests__/fixtures.ts

@@ -102,6 +102,7 @@ add("org.unit_owner_granted", "Unit owner + message", {
   unitName: "Platform Engineering",
   roleLabel: "Unit owner",
   ctaUrl: `${APP}/org/unit/42`,
+  unitId: "unit_42",
   message: "Welcome aboard — glad to have you owning this team.",
 });
 add("org.unit_owner_granted", "Delegate with expiry", {
@@ -110,6 +111,7 @@ add("org.unit_owner_granted", "Delegate with expiry", {
   unitName: "Platform Engineering",
   roleLabel: "Delegate",
   ctaUrl: `${APP}/org/unit/42`,
+  unitId: "unit_42",
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
@@ -144,6 +146,7 @@ add("security.alert", "Unusual login location", {
 
 const CHAT_BASE = {
   sharedByName: "Alex Rivera",
+  chatId: "chat_7f3a",
   access: "read",
 } as const;
 add("chat.shared", "Default", {
@@ -220,14 +223,16 @@ add("companyMd.access_request_approved", "Editor", {
   docTitle: "Engineering Handbook",
   accessLevel: "editor",
   docUrl: `${APP}/doc/handbook`,
+  docId: "node_42",
 });
-// The approver's note replaces the "Open to view." prompt rather than stacking
+// The approver's note replaces the "The document is ready for you." line rather than stacking
 // on it — the branch this variant exists to pin.
 add("companyMd.access_request_approved", "Editor with message", {
   approverName: "Jordan Lee",
   docTitle: "Engineering Handbook",
   accessLevel: "editor",
   docUrl: `${APP}/doc/handbook`,
+  docId: "node_42",
   message: "Welcome aboard — start with the onboarding section.",
 });
 add("companyMd.access_request_approved", "Viewer", {
@@ -235,6 +240,7 @@ add("companyMd.access_request_approved", "Viewer", {
   docTitle: "Engineering Handbook",
   accessLevel: "viewer",
   docUrl: `${APP}/doc/handbook`,
+  docId: "node_42",
 });
 
 add("companyMd.access_request_denied", "With reason", {