@company-semantics/contracts 92.0.0 → 93.1.0

package/src/notifications/__tests__/grounded-ctas.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+  CallToAction,
+  NotificationContent,
+  NotificationElement,
+} from "../content";
+import { createRenderContext } from "../context";
+import type { NotificationKind } from "../kinds";
+import { NOTIFICATION_DEFINITIONS } from "../registry";
+import { NOTIFICATION_FIXTURES } from "./fixtures";
+
+/**
+ * A notification link that does what a catalog id names carries that
+ * affordance, and no notification prose tells the reader what to do
+ * (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 CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
+
+function composeFixture(
+  kind: NotificationKind,
+  payload: unknown,
+): NotificationContent {
+  const compose = NOTIFICATION_DEFINITIONS[kind].compose as (
+    p: unknown,
+    c: typeof CONTEXT,
+  ) => NotificationContent;
+  return compose(payload, CONTEXT);
+}
+
+function elements(content: NotificationContent): NotificationElement[] {
+  const out: NotificationElement[] = [];
+  for (const section of content.sections) {
+    for (const element of section.elements) {
+      out.push(element);
+      if (element.type === "chatUnit")
+        out.push(...(element.items as unknown as NotificationElement[]));
+    }
+  }
+  return out;
+}
+
+const ctas = (content: NotificationContent) =>
+  elements(content).filter((e): e is CallToAction => e.type === "callToAction");
+
+const GROUNDED: Partial<
+  Record<NotificationKind, (payload: Record<string, unknown>) => unknown>
+> = {
+  "billing.auto_recharge_failed": () => ({ id: "billing.open" }),
+  "billing.payment_past_due": () => ({ id: "billing.open" }),
+  "billing.suspended": () => ({ id: "billing.open" }),
+  "chat.shared": (p) => ({ id: "chat.open", args: { chatId: p.chatId } }),
+  "companyMd.access_request_approved": (p) => ({
+    id: "companyMd.openDoc",
+    args: { docId: p.docId },
+  }),
+  "org.unit_owner_granted": (p) => ({
+    id: "team.open",
+    args: { unitId: p.unitId },
+  }),
+};
+
+describe("grounded notification calls to action", () => {
+  it("a linked call to action whose link a catalog id names carries that affordance, targeting the payload's own id", () => {
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      const expected = GROUNDED[fixture.kind];
+      if (!expected) continue;
+      const linked = ctas(composeFixture(fixture.kind, fixture.payload)).filter(
+        (c) => c.href !== undefined,
+      );
+      expect(linked, fixture.name).toHaveLength(1);
+      expect(
+        linked[0]?.affordance,
+        `${fixture.kind} · ${fixture.name}`,
+      ).toEqual(expected(fixture.payload as Record<string, unknown>));
+    }
+  });
+
+  it("a code to copy never carries an affordance", () => {
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      for (const cta of ctas(composeFixture(fixture.kind, fixture.payload))) {
+        if (cta.href === undefined)
+          expect(cta.affordance, fixture.name).toBeUndefined();
+      }
+    }
+  });
+
+  it("no grounded or share notification body tells the reader what to do", () => {
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      if (!GROUNDED[fixture.kind] && fixture.kind !== "share.granted") continue;
+      for (const element of elements(
+        composeFixture(fixture.kind, fixture.payload),
+      )) {
+        if (element.type === "body")
+          expect(element.text, fixture.name).not.toMatch(CALL_TO_ACTION);
+        if (element.type === "message")
+          expect(element.text, fixture.name).not.toMatch(CALL_TO_ACTION);
+      }
+    }
+  });
+});

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

@@ -220,7 +220,7 @@ add("companyMd.access_request_approved", "Editor", {
   accessLevel: "editor",
   docUrl: `${APP}/doc/handbook`,
 });
-// 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, across every channel.
 add("companyMd.access_request_approved", "Editor with message", {
   approverName: "Jordan Lee",

package/src/notifications/content.ts

@@ -23,6 +23,8 @@
  *   security notice", not "render a red box".
  */
 
+import type { OfferedAffordance } from "../affordances/affordance";
+
 // =============================================================================
 // Shared value types
 // =============================================================================
@@ -73,11 +75,18 @@ export interface KeyValueTable {
  * The one action the notification is asking for. `href` absent means the label
  * IS the payload (an OTP code), not a link — the renderer must not fabricate a
  * destination for it.
+ *
+ * `affordance` names the catalog affordance the link performs (control ADR
+ * affordance-system): present exactly when the link does what a catalog id
+ * names, so the label is that affordance's label (`// cta-grounded: <id>` at
+ * the composer). Absent for an OTP code and for a link no catalog id names (an
+ * invite acceptance, a comment). Renderers draw the link as before.
  */
 export interface CallToAction {
   type: "callToAction";
   label: string;
   href?: string;
+  affordance?: OfferedAffordance;
 }
 
 /** A sequence of items. `ordered` when the sequence itself carries meaning. */

package/src/notifications/kinds/billing-auto-recharge-failed.ts

@@ -52,13 +52,15 @@ export const billingAutoRechargeFailedDefinition: NotificationDefinition<"billin
                 text:
                   "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.",
+                  "system waits before charging the same card a second time — " +
+                  "so updating the payment method is what resolves this.",
               },
               {
                 type: "callToAction",
+                // cta-grounded: billing.open
                 label: "OPEN BILLING",
                 href: billingUrl,
+                affordance: { id: "billing.open" },
               },
               {
                 type: "notice",

package/src/notifications/kinds/billing-payment-past-due.ts

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

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" }],
     }),
   };