@company-semantics/contracts 92.0.0 → 93.0.0

package/src/notifications/kinds/billing-suspended.ts

@@ -57,8 +57,10 @@ export const billingSuspendedDefinition: NotificationDefinition<"billing.suspend
               },
               {
                 type: "callToAction",
+                // cta-grounded: billing.open
                 label: "OPEN BILLING",
                 href: billingUrl,
+                affordance: { id: "billing.open" },
               },
               {
                 type: "notice",

package/src/notifications/kinds/chat-shared.ts

@@ -15,7 +15,8 @@ import { NOTICE } from "../text";
 export const chatSharedDefinition: NotificationDefinition<"chat.shared"> = {
   kind: "chat.shared",
   compose: (payload, context) => {
-    const { chatTitle, chatUrl, access, previewText, sharedByName } = payload;
+    const { chatTitle, chatUrl, chatId, access, previewText, sharedByName } =
+      payload;
 
     const items: ChatUnitItem[] = [
       { type: "message", role: "user", text: chatTitle, from: sharedByName },
@@ -29,7 +30,13 @@ export const chatSharedDefinition: NotificationDefinition<"chat.shared"> = {
           ]
         : []),
       { type: "continuation" },
-      { type: "callToAction", label: "OPEN CHAT", href: chatUrl },
+      {
+        type: "callToAction",
+        // cta-grounded: chat.open
+        label: "OPEN CHAT",
+        href: chatUrl,
+        affordance: { id: "chat.open", args: { chatId } },
+      },
     ];
 
     return {
@@ -45,7 +52,7 @@ export const chatSharedDefinition: NotificationDefinition<"chat.shared"> = {
               type: "body",
               text:
                 access === "collaborate"
-                  ? "A chat was shared with you. You can take part in it."
+                  ? "A chat was shared with you, and you are a participant."
                   : "A chat was shared with you to read.",
             },
             { type: "chatUnit", items },

package/src/notifications/kinds/company-md-access-approved.ts

@@ -1,9 +1,9 @@
 /**
  * Company.md access-approved notification (sent to the requester).
  *
- * The chat unit carries EITHER the approver's own words or the bare "Open to
- * view." prompt — never both. An approver who wrote a note has already said what
- * the prompt would say, and stacking the two reads as a form letter with a
+ * The chat unit carries EITHER the approver's own words or the bare "The
+ * document is ready for you." line — never both. An approver who wrote a note
+ * has already said what the line would say, and stacking the two reads as a form letter with a
  * comment bolted on. Same shape as `share.granted` (ADR-CONTRACTS-106); the call
  * to action stays in place either way, since approval always resolves to a doc
  * the requester can now open.
@@ -17,7 +17,8 @@ export const accessApprovedDefinition: NotificationDefinition<"companyMd.access_
   {
     kind: "companyMd.access_request_approved",
     compose: (payload, context) => {
-      const { approverName, docTitle, accessLevel, docUrl, message } = payload;
+      const { approverName, docTitle, accessLevel, docUrl, docId, message } =
+        payload;
 
       return {
         metadata: {
@@ -42,9 +43,15 @@ export const accessApprovedDefinition: NotificationDefinition<"companyMd.access_
                     : {
                         type: "message",
                         role: "assistant",
-                        text: "Open to view.",
+                        text: "The document is ready for you.",
                       },
-                  { type: "callToAction", label: "OPEN", href: docUrl },
+                  {
+                    type: "callToAction",
+                    // cta-grounded: companyMd.openDoc
+                    label: "OPEN",
+                    href: docUrl,
+                    affordance: { id: "companyMd.openDoc", args: { docId } },
+                  },
                 ],
               },
               {

package/src/notifications/kinds/share-granted.ts

@@ -52,7 +52,7 @@ export const shareGrantedDefinition: NotificationDefinition<"share.granted"> = {
                   : {
                       type: "message",
                       role: "assistant",
-                      text: "Open to view.",
+                      text: "It is ready for you.",
                     },
                 { type: "callToAction", label: "OPEN", href: ctaUrl },
               ],

package/src/notifications/kinds/unit-owner-granted.ts

@@ -28,6 +28,7 @@ export const unitOwnerGrantedDefinition: NotificationDefinition<"org.unit_owner_
         unitName,
         roleLabel,
         ctaUrl,
+        unitId,
         message,
         expiresAt,
       } = payload;
@@ -50,9 +51,15 @@ export const unitOwnerGrantedDefinition: NotificationDefinition<"org.unit_owner_
         {
           type: "message",
           role: "assistant",
-          text: "Open the team to get started.",
+          text: `${unitName} is ready for you.`,
+        },
+        {
+          type: "callToAction",
+          // cta-grounded: team.open
+          label: "MANAGE TEAM",
+          href: ctaUrl,
+          affordance: { id: "team.open", args: { unitId } },
         },
-        { type: "callToAction", label: "MANAGE TEAM", href: ctaUrl },
       ];
 
       const rows: KeyValueRow[] = [

package/src/notifications/payloads.ts

@@ -72,6 +72,8 @@ export interface NotificationPayloads {
     roleLabel: "Unit owner" | "Delegate";
     /** Full URL to view the org unit in the app */
     ctaUrl: string;
+    /** The org unit's id — the `team.open` affordance the link performs. */
+    unitId: string;
     /** Optional message from the granter, shown in the notification and recorded with the grant */
     message?: string;
     /** ISO timestamp when the grant expires. Absent = permanent (formal unit owners; delegations with no expiry). Rendered as the last key/value row ("Expires: Jun 13, 2026") when present. */
@@ -110,6 +112,8 @@ export interface NotificationPayloads {
     chatTitle: string;
     /** Full URL of the chat itself — the link that opens it in the recipient's app */
     chatUrl: string;
+    /** The chat's id — the `chat.open` affordance the link performs. */
+    chatId: string;
     /** What the share granted: Read only or Collaborate */
     access: "read" | "collaborate";
     /** First ~200 chars of chat content for preview. Generated server-side. */
@@ -158,6 +162,8 @@ export interface NotificationPayloads {
     accessLevel: "editor" | "commenter" | "viewer";
     /** Full URL to view the node */
     docUrl: string;
+    /** The company.md node's id — the `companyMd.openDoc` affordance the link performs. */
+    docId: string;
     /**
      * Optional note from the approver, included in the notification only (not
      * persisted) — the approval counterpart of the deny kind's `reason`

package/src/proactive/README.md

@@ -176,6 +176,21 @@ the three from another.
   time. The deliberate opposite of the durable-inbox rule, and both are
   correct: a transcript that changed under the reader would be a lie about the
   conversation.
+- **A pushed chat offers its next steps as affordance instances, never as
+  chips or prose** (control ADR `affordance-system`; contracts ADR
+  `affordance-catalog-wave-and-grounded-ctas`). `ProactiveChatMessage.affordances`
+  is REQUIRED on every composer — an empty list is an explicit decision — and
+  holds `OfferedAffordance` instances (ids and args, never labels or hrefs),
+  frozen with the message. The backend chat writer persists them as a
+  `data-affordance-offer` part (`../message-parts/affordance-offer.ts`) and the
+  app renders them as real controls, re-gated per viewer. A chip only sends a
+  chat prompt, so a next step is never a chip, and the prose states facts
+  rather than telling the reader where to go. A projected id (`review.open`)
+  is never offered: the five billing chats offer `billing.open`,
+  `orgBecameShared` offers `workspace.openOrgSettings`, and `morningBrief`,
+  `sourceSyncReviewReady` (opening its review is the projected `review.open`,
+  and its facts carry no request id) and
+  `workflowNeedsAttention` (its outcome carries its own offer) offer nothing.
 
 ## Public API
 
@@ -211,7 +226,7 @@ the three from another.
 | `SourceSyncReviewReadyFacts`       | `orgName` + `checkpoint`; no count, no document name, no source name          |
 | `ExplainedWorkflowOutcomeData`     | The settlement data part with an explained, fact-free outcome                 |
 | `WorkflowNeedsAttentionFacts`      | `narration` (backend settlement copy) + the fact-free `outcome` data part     |
-| `ProactiveChatMessage`             | `title`, `text`, 0..4 `replies` chips, and an optional settled `outcome`      |
+| `ProactiveChatMessage`             | `title`, `text`, 0..4 chips, the offered `affordances`, an optional `outcome` |
 | `ProactiveChatComposer`            | The composer port — `template` plus an arrow-property `compose(facts)`        |
 | `PROACTIVE_CHAT_MAX_REPLIES`       | At most this many chips (4); more is a menu, not a chip row                   |
 | `PROACTIVE_CHAT_COMPOSERS`         | The total template → composer registry (see `templates/README.md`)            |
@@ -222,7 +237,8 @@ Type-only imports of `UserNotificationKind` (`../user-notifications`),
 `NotificationKind` (`../notifications`) and `ActionItemKind`
 (`../action-items`) — the three vocabularies this one composes — and of
 `SuggestedReply` (`../message-parts`), the chip shape a composer's `replies`
-reuse rather than redeclare. Type-only imports of `WorkflowOutcomeData`
+reuse rather than redeclare, and of `OfferedAffordance` (`../affordances`),
+the instance shape a composer's `affordances` offer. Type-only imports of `WorkflowOutcomeData`
 (`../message-parts`), `ExplainedWorkflowOutcome` (`../workflows`) and
 `WorkflowType` for the workflow settlement chat; the dependency runs
 proactive → workflows, never the reverse. No `zod`, no runtime imports; pure vocabulary

package/src/proactive/__tests__/README.md

@@ -42,7 +42,8 @@ cannot.
   every template in `PROACTIVE_CHAT_TEMPLATES` has a composer whose `template`
   equals its key (the type proves totality; this proves no entry is an
   accidental `undefined`), the org-became-shared prose NAMES THE RELOCATION and
-  every one of the five sections that leave My settings for Org settings, the
+  every one of the five sections that moved to the workspace (offering
+  `workspace.openOrgSettings` as the destination), the
   morning brief PERSONALIZES THROUGH ITS FACTS (two recipients of one
   occurrence get different prose from one composer), chips stay within
   `PROACTIVE_CHAT_MAX_REPLIES`, and composers emit content — no markup, no
@@ -58,6 +59,15 @@ cannot.
   fact-free outcome (schema-valid, `facts: null`) and no chips, frames the
   backend narration verbatim, has a title per workflow type with no digit and
   no next-step wording; and both inbox rows supersede per workflow type.
+- `proactive-offers.test.ts` — pushed chats offer next steps as affordance
+  instances, never as chips or prose (control ADR `affordance-system`): every
+  composer returns an explicit `affordances` list, the billing chats offer
+  `billing.open` and carry no add-funds or resubscribe chip, org-became-shared
+  offers `workspace.openOrgSettings`, no composer offers a projected id, no
+  title, text, chip label or chip prompt carries call-to-action wording (the
+  cta-prose-ratchet regex; `workflowNeedsAttention` excepted, since it frames
+  the backend's narration verbatim), and `WireSurfaceBuilder.affordanceOffer`
+  carries the offered instances verbatim.
 - `workflow-attention-fixtures.ts` — explained, fact-free outcomes for those
   tests and the registry-wide fixtures. A COMPILED module, so each fixture is
   typechecked against `ExplainedWorkflowOutcome`.

package/src/proactive/__tests__/chat-templates.test.ts

@@ -82,7 +82,7 @@ describe("proactive chat templates", () => {
       orgName: "Acme",
       joinerDisplayName: "Ada",
     });
-    expect(msg.text).toContain("Org settings");
+    expect(msg.affordances).toEqual([{ id: "workspace.openOrgSettings" }]);
     expect(msg.text).toContain("relocation");
     expect(msg.replies.length).toBeLessThanOrEqual(PROACTIVE_CHAT_MAX_REPLIES);
   });
@@ -102,7 +102,6 @@ describe("proactive chat templates", () => {
       "AI usage",
       "Spending controls",
       "Billing",
-      "My settings",
     ]) {
       expect(msg.text, section).toContain(section);
     }
@@ -131,7 +130,9 @@ describe("proactive chat templates", () => {
       expect(msg.text, trigger).not.toContain("accepted your invite");
       // The half that does not vary: the relocation is the same either way.
       expect(msg.text, trigger).toContain("relocation, not an addition");
-      expect(msg.text, trigger).toContain("Org settings");
+      expect(msg.affordances, trigger).toEqual([
+        { id: "workspace.openOrgSettings" },
+      ]);
     }
   });
 
@@ -149,9 +150,9 @@ describe("proactive chat templates", () => {
       "Ada accepted your invite, so Acme moved from a personal workspace to a " +
         "shared one.\n\n" +
         "This is a relocation, not an addition: Integrations, Invite team " +
-        "members, AI usage, Spending controls and Billing have moved out of My " +
-        "settings and into Org settings. Nothing was removed — the five sections now " +
-        "belong to the workspace rather than to you.",
+        "members, AI usage, Spending controls and Billing have moved from your " +
+        "own area to the workspace's. Nothing was removed — the five sections " +
+        "now belong to the workspace rather than to you.",
     );
   });
 

package/src/proactive/__tests__/proactive-offers.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import { PROJECTED_AFFORDANCE_IDS } from "../../affordances/affordance";
+import { WireSurfaceBuilder } from "../../message-parts/wire";
+import type { ProactiveChatMessage } from "../composer";
+import type { ProactiveChatFacts } from "../facts";
+import {
+  PROACTIVE_CHAT_TEMPLATES,
+  type ProactiveChatTemplate,
+} from "../surfaces";
+import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+} from "./workflow-attention-fixtures";
+
+/**
+ * Pushed chats offer next steps as affordance instances, never as chips or
+ * prose (control ADR affordance-system; PRD-01137).
+ */
+const CALL_TO_ACTION =
+  /\byou can\b|\btry\b|\bagain\b|\bsettings\b|\breconnect\b|\badd funds\b|\bclick\b|\bgo to\b|\bopen\b/i;
+
+const FACTS: { readonly [T in ProactiveChatTemplate]: ProactiveChatFacts[T] } =
+  {
+    orgBecameShared: {
+      trigger: "member_added",
+      orgName: "Acme",
+      joinerDisplayName: "Ada",
+    },
+    morningBrief: {
+      recipientDisplayName: "Ada",
+      orgName: "Acme",
+      orgLocalDateLabel: "Tuesday 25 August",
+      pendingActionItemCount: 2,
+      unreadNotificationCount: 5,
+    },
+    billingBalanceExhausted: { orgName: "Acme", autoRechargeEnabled: false },
+    billingAutoRechargeFailed: { orgName: "Acme", paymentMethodPresent: true },
+    billingPaymentPastDue: { orgName: "Acme", paymentMethodPresent: false },
+    billingSuspended: { orgName: "Acme" },
+    billingSubscriptionCanceled: { orgName: "Acme" },
+    sourceSyncReviewReady: { orgName: "Acme", checkpoint: "synthesis" },
+    workflowNeedsAttention: {
+      narration: DRIVE_AUTH_NARRATION,
+      outcome: { workflowId: "wf-1", outcome: DRIVE_AUTH_OUTCOME },
+    },
+  };
+
+function compose(template: ProactiveChatTemplate): ProactiveChatMessage {
+  const fn = PROACTIVE_CHAT_COMPOSERS[template].compose as (
+    facts: ProactiveChatFacts[ProactiveChatTemplate],
+  ) => ProactiveChatMessage;
+  return fn(FACTS[template]);
+}
+
+const BILLING = [
+  "billingBalanceExhausted",
+  "billingAutoRechargeFailed",
+  "billingPaymentPastDue",
+  "billingSuspended",
+  "billingSubscriptionCanceled",
+] as const;
+
+describe("proactive chat offers", () => {
+  it("every composer returns an explicit affordance offer", () => {
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      expect(Array.isArray(compose(template).affordances), template).toBe(true);
+    }
+  });
+
+  it("billing chats offer billing.open and no add-funds chip", () => {
+    for (const template of BILLING) {
+      const msg = compose(template);
+      expect(msg.affordances, template).toEqual([{ id: "billing.open" }]);
+      expect(
+        msg.replies.map((r) => r.id),
+        template,
+      ).not.toContain("add-funds");
+      expect(
+        msg.replies.map((r) => r.id),
+        template,
+      ).not.toContain("resubscribe");
+    }
+  });
+
+  it("org became shared offers the org settings", () => {
+    expect(compose("orgBecameShared").affordances).toEqual([
+      { id: "workspace.openOrgSettings" },
+    ]);
+  });
+
+  it("no composer offers a projected affordance", () => {
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      for (const affordance of compose(template).affordances) {
+        expect(
+          PROJECTED_AFFORDANCE_IDS as readonly string[],
+          template,
+        ).not.toContain(affordance.id);
+      }
+    }
+  });
+
+  it("no composer text, chip label or chip prompt carries call-to-action wording", () => {
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      if (template === "workflowNeedsAttention") continue; // frames the backend's narration verbatim
+      const msg = compose(template);
+      expect(msg.title, template).not.toMatch(CALL_TO_ACTION);
+      expect(msg.text, template).not.toMatch(CALL_TO_ACTION);
+      for (const reply of msg.replies) {
+        expect(reply.label, template).not.toMatch(CALL_TO_ACTION);
+        expect(reply.prompt ?? "", template).not.toMatch(CALL_TO_ACTION);
+      }
+    }
+  });
+
+  it("the affordance offer part carries the offered instances verbatim", () => {
+    const affordances = compose("billingSuspended").affordances;
+    expect(WireSurfaceBuilder.affordanceOffer({ affordances })).toEqual({
+      type: "data-affordance-offer",
+      data: { affordances: [{ id: "billing.open" }] },
+    });
+  });
+});

package/src/proactive/__tests__/vocabulary.test.ts

@@ -490,7 +490,7 @@ describe("the kind registry", () => {
         expect(reply.label, checkpoint).not.toMatch(/[0-9]/);
         expect(reply.prompt ?? "", checkpoint).not.toMatch(/[0-9]/);
       }
-      expect(msg.replies, checkpoint).toHaveLength(3);
+      expect(msg.replies, checkpoint).toHaveLength(2);
     }
   });
 

package/src/proactive/composer.ts

@@ -34,6 +34,7 @@
  *   reader would be a lie about the conversation.
  */
 
+import type { OfferedAffordance } from "../affordances/affordance";
 import type { SuggestedReply } from "../message-parts/suggested-replies";
 import type { WorkflowOutcomeData } from "../message-parts/workflow-outcome";
 import type { ProactiveChatFacts } from "./facts";
@@ -66,6 +67,16 @@ export interface ProactiveChatMessage {
   readonly text: string;
   /** 0..`PROACTIVE_CHAT_MAX_REPLIES` chips. */
   readonly replies: readonly SuggestedReply[];
+  /**
+   * The next steps this chat OFFERS, frozen with it (control ADR
+   * affordance-system). A chip only sends a chat prompt, so a next step is
+   * never a chip: it is an affordance instance the chat writer persists as a
+   * `data-affordance-offer` part and the app renders as a control, re-gated per
+   * viewer. REQUIRED — an empty list is an explicit decision. A projected id
+   * (`review.open`) is never offered here. A template that reports a workflow
+   * outcome leaves this empty: the outcome carries its own offer.
+   */
+  readonly affordances: readonly OfferedAffordance[];
   /**
    * The settled workflow a template reports, when it reports one. The chat
    * writer persists it as a `data-workflow-outcome` part beside the prose, so

package/src/proactive/templates/README.md

@@ -31,9 +31,17 @@ chat. That is the precedent notify/'s README states for outbound notifications
 - At most `PROACTIVE_CHAT_MAX_REPLIES` chips. More is a menu, not a chip row.
 - A file per template, named after it in kebab-case. Templates do not share a
   module — the point is that a template is self-contained.
-- `org-became-shared.ts` NAMES THE RELOCATION: the five sections that leave My
-  settings for Org settings. Unannounced, that reads as things going missing
-  (the app ADR with slug `nav-posture-opens-on-invite-send`).
+- `org-became-shared.ts` NAMES THE RELOCATION: the five sections that moved
+  from the person's own area to the workspace's. Unannounced, that reads as
+  things going missing (the app ADR with slug
+  `nav-posture-opens-on-invite-send`). The destination is the
+  `workspace.openOrgSettings` affordance it offers, not prose.
+- **Every composer returns an explicit `affordances` offer** (control ADR
+  `affordance-system`): the five billing templates `[{ id: "billing.open" }]`,
+  `org-became-shared.ts` `[{ id: "workspace.openOrgSettings" }]`, the rest
+  `[]`. A next step is never a chip (a chip only sends a prompt) and never
+  prose telling the reader where to go; a projected id is never offered.
+  `../__tests__/proactive-offers.test.ts` pins all of it.
 - `morning-brief.ts` PERSONALIZES THROUGH THE FACTS, never the occurrence. One
   `brief.morning` occurrence per org per org-local day is shared by every
   recipient; two people's briefs differ only because the `MorningBriefFacts`

package/src/proactive/templates/billing-auto-recharge-failed.ts

@@ -49,5 +49,6 @@ export const billingAutoRechargeFailedComposer: ProactiveChatComposer<"billingAu
           prompt: "Can I add AI funds manually instead of waiting for a retry?",
         },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/billing-balance-exhausted.ts

@@ -29,7 +29,7 @@ export const billingBalanceExhaustedComposer: ProactiveChatComposer<"billingBala
       text:
         `${facts.orgName} has run out of AI balance, so AI work is paused. ` +
         `Nothing was lost — every chat, document and work item is exactly ` +
-        `where you left it, and the assistant starts answering again as soon ` +
+        `where you left it, and the assistant resumes answering as soon ` +
         `as the balance is topped up.\n\n` +
         (facts.autoRechargeEnabled
           ? `Automatic top-up is switched on, so this usually clears itself ` +
@@ -41,11 +41,6 @@ export const billingBalanceExhaustedComposer: ProactiveChatComposer<"billingBala
         `\n\nThe current balance is on the billing page, which is the only ` +
         `place it is guaranteed to be up to date.`,
       replies: [
-        {
-          id: "add-funds",
-          label: "How do I add funds?",
-          prompt: "How do I add AI funds to this workspace?",
-        },
         {
           id: "auto-top-up",
           label: "Explain automatic top-up",
@@ -59,5 +54,6 @@ export const billingBalanceExhaustedComposer: ProactiveChatComposer<"billingBala
             "What exactly stops working while AI is paused, and what keeps working?",
         },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/billing-payment-past-due.ts

@@ -53,5 +53,6 @@ export const billingPaymentPastDueComposer: ProactiveChatComposer<"billingPaymen
             "What happens to my workspace if this payment stays unresolved?",
         },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/billing-subscription-canceled.ts

@@ -47,11 +47,7 @@ export const billingSubscriptionCanceledComposer: ProactiveChatComposer<"billing
           prompt:
             "What happens to the AI funds already in my wallet after cancellation?",
         },
-        {
-          id: "resubscribe",
-          label: "How do I resubscribe?",
-          prompt: "How do I start the seat subscription again?",
-        },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/billing-suspended.ts

@@ -49,5 +49,6 @@ export const billingSuspendedComposer: ProactiveChatComposer<"billingSuspended">
             "Is any of my workspace data at risk while this is suspended?",
         },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/morning-brief.ts

@@ -73,5 +73,6 @@ export const morningBriefComposer: ProactiveChatComposer<"morningBrief"> = {
         prompt: "What needs a decision from me today?",
       },
     ],
+    affordances: [],
   }),
 };

package/src/proactive/templates/org-became-shared.ts

@@ -74,9 +74,9 @@ export const orgBecameSharedComposer: ProactiveChatComposer<"orgBecameShared"> =
       text:
         `${openingFor(facts)}\n\n` +
         `This is a relocation, not an addition: Integrations, Invite team ` +
-        `members, AI usage, Spending controls and Billing have moved out of My ` +
-        `settings and into Org settings. Nothing was removed — the five sections now ` +
-        `belong to the workspace rather than to you.`,
+        `members, AI usage, Spending controls and Billing have moved from your ` +
+        `own area to the workspace's. Nothing was removed — the five sections ` +
+        `now belong to the workspace rather than to you.`,
       replies: [
         {
           id: "plain-english",
@@ -96,5 +96,6 @@ export const orgBecameSharedComposer: ProactiveChatComposer<"orgBecameShared"> =
           prompt: "Who can see what in my workspace now that it is shared?",
         },
       ],
+      affordances: [{ id: "workspace.openOrgSettings" }],
     }),
   };

package/src/proactive/templates/source-sync-review-ready.ts

@@ -36,17 +36,11 @@ export const sourceSyncReviewReadyComposer: ProactiveChatComposer<"sourceSyncRev
             `strategy documents and have proposed changes for you to ` +
             `review.\n\n` +
             `Nothing has been changed. Each document is updated only when ` +
-            `you say so, as an ordinary version you can restore, and ` +
+            `you say so, as an ordinary version that can be restored, and ` +
             `anything a person has edited is left alone unless you choose ` +
             `otherwise.`) +
-        `\n\nOpen the review when you have a few minutes. If you leave it, ` +
-        `nothing happens.`,
+        `\n\nThe review waits for you. If you leave it, nothing happens.`,
       replies: [
-        {
-          id: "open-review",
-          label: "Open the review",
-          prompt: "Open the source review.",
-        },
         {
           id: "what-was-found",
           label: "What did you find?",
@@ -60,5 +54,6 @@ export const sourceSyncReviewReadyComposer: ProactiveChatComposer<"sourceSyncRev
             "If I attach a source to a document, who will be able to see it?",
         },
       ],
+      affordances: [],
     }),
   };

package/src/proactive/templates/workflow-needs-attention.ts

@@ -30,6 +30,7 @@ export const workflowNeedsAttentionComposer: ProactiveChatComposer<"workflowNeed
       title: TITLE_OF_WORKFLOW_TYPE[facts.outcome.outcome.workflowType],
       text: facts.narration,
       replies: [],
+      affordances: [],
       outcome: facts.outcome,
     }),
   };

package/src/rate-limit/README.md

@@ -35,6 +35,29 @@ interface RateLimitResult {
 }
 ```
 
+### RateLimitedErrorResponseSchema
+
+The 429 body every rate-limited response carries — exactly what backend's
+shared limiter sends, plus the reset fact:
+
+```typescript
+{
+  error: "RATE_LIMIT_EXCEEDED"; // RATE_LIMITED_ERROR_CODE
+  scope?: "email" | "ip" | "global";
+  message: string;
+  retryAfterSeconds: number | null; // whole seconds until the window resets
+}
+```
+
+The object is strict and `retryAfterSeconds` is REQUIRED: it mirrors the
+`Retry-After` header, or is null when the limiter cannot say.
+
+**Facts only.** `retryAfterSeconds` is a fact, so the message states it
+("Too many requests. Available in 30s.") and never tells the reader to retry.
+A retry control, if a surface has one, is that surface's own control label
+(control ADR affordance-system). Distinct from `ShedResponse` in
+`src/pressure.ts`, which is the load-shed body only.
+
 ## Semantic Convention
 
 This domain uses `allowed: boolean` where `true` means the request is permitted.
@@ -54,9 +77,12 @@ This is the canonical semantic across all Company Semantics repos.
 
 ## Public API
 
+- `RATE_LIMITED_ERROR_CODE`
 - `RateLimitConfig` _(type)_
 - `RateLimitResult` _(type)_
 - `RateLimitTier`
+- `RateLimitedErrorResponse` _(type)_
+- `RateLimitedErrorResponseSchema`
 
 <!-- END GENERATED: readme-public-api -->
 
@@ -70,6 +96,6 @@ _None._
 
 **External packages:**
 
-_None._
+- `zod`
 
 <!-- END GENERATED: readme-dependencies -->

package/src/rate-limit/__tests__/README.md

@@ -0,0 +1,23 @@
+# rate-limit/\_\_tests\_\_/
+
+## Purpose
+
+Locks the shape of the rate-limited error envelope.
+
+- `rate-limited-error.test.ts` — proves a rate-limited body carries
+  `retryAfterSeconds` as whole non-negative seconds or null and is refused
+  without it, refuses any code other than `RATE_LIMIT_EXCEEDED`, and that the
+  schema and code are reachable from the package root as the same binding.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never limiter behavior. Window sizes and
+  which routes are limited belong to backend.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest`, `../index` and the package root.