@wildo-ai/saas-technical-doc 1.1.1 → 1.1.2

package/dist/esm/content/application-consumer-documentation-content.techdoc.js

@@ -15,122 +15,53 @@ export const APPLICATION_CONSUMER_DOCUMENTATION_AUTHORED_CONTENT_V1 = [
     {
         managedPath: 'get-started.md',
         unitRef: 'technical-documentation:unit/application-orientation',
-        sourceRefs: ['saas-technical-doc:engine-content/application-orientation'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/application-orientation',
+            'source:companion-projection:application-connection',
+        ],
         markdown: `# Get started
 
-This documentation is for people who **use, administer, integrate or operate
-this application**. You do not need to know how the application was built, and
-you do not need to understand every technology before choosing a path. Start
-with the result you need.
+This documentation is for the people who use, administer, integrate with or operate {{APPLICATION_NAME}}. Pick the row that matches what you need to do; each leads to a page you can act on.
 
 ## What do you need to do?
 
-| Your goal | Begin here | You will learn |
+| You need to | Start here | You will find |
 | --- | --- | --- |
-| Sign in, complete a second factor or recover access | [Access and identity](/access-and-identity/overview) | Which sign-in method belongs to a person, a service or a delegated client—and how to distinguish authentication from permission problems |
-| Invite a person, change access or remove access | [User administration](/user-administration) | How manual membership, roles, organization units, single sign-on and SCIM work together |
-| Connect another system or automate a process | [Integrations](/integrations) | When to use REST, webhooks, an automation platform or an agent connection |
-| Build a workflow in n8n, Zapier or Make | [Automation platforms](/integrations/automation-platforms) | How to connect through the published API, protect the credential and verify the business result |
-| Investigate a change or export security evidence | [Security and audit](/security-and-audit) | How to read the authoritative audit trail, follow correlation and operate SIEM delivery safely |
-| Understand a subscription, invoice or access delay | Look for **Billing and subscriptions** in the navigation | How billing state becomes application access and how to reconcile an asynchronous change |
-| Implement an exact request | [API reference](/api) | The current operation, field, role, request and response contract |
-
-If **AI coding tools** appears under Integrations, the application has published
-the MCP connection required by the Cursor, Codex and Claude Code guides. If a
-section is absent, do not assume that its capability or administrative surface
-exists in this application.
-
-~~~mermaid
-flowchart TD
-  accTitle: Choose a documentation path from the outcome you need
-  accDescr: A reader starts from a human access task, an administration task, an integration task, or an operational investigation. Each path leads to a guide, then to an exact reference only when implementation details are needed.
-  need["What outcome do you need?"] --> person{"A person's access?"}
-  person -->|"Sign in or recover"| identity["Access and identity"]
-  person -->|"Invite, change or remove"| administration["User administration"]
-  person -->|"No"| system{"Connect or operate software?"}
-  system -->|"Connect or automate"| integrations["Integrations"]
-  system -->|"Investigate or export evidence"| security["Security and audit"]
-  identity --> contract["Use the exact reference when needed"]
-  administration --> contract
-  integrations --> contract
-  security --> contract
-~~~
-
-The diagram is a starting map, not an access model. Opening a guide does not
-grant a capability. The current application's navigation, visible controls and
-published operation contracts determine what is actually available to you.
-
-## Before you change anything
-
-Confirm four things before an administrative or integration write:
+| Sign in, set up a second factor, or get back into your account | [Access and identity](/access-and-identity/overview) | The sign-in methods, multifactor enrollment and recovery, and what a refusal means |
+| Invite someone, change what they may do, or remove them | [User administration](/user-administration) | Memberships, the roles available in this application, organization units, single sign-on and directory provisioning |
+| Call the API from your own code | [Send your first API request](/integrations/rest/send-request) | A working request in ten minutes, then the [conventions](/integrations/rest/conventions) every operation follows |
+| Be notified when something changes | [Webhooks](/integrations/webhooks) | Signed deliveries, a receiver you can run, retries and operations |
+| Build in n8n, Zapier or Make | [Automation platforms](/integrations/automation-platforms) | The exact settings for each tool |
+| Connect an AI assistant such as Cursor, Codex or Claude Code | [AI coding tools](/integrations/ai-coding-tools) | The MCP connection and what the assistant may do |
+| Investigate who did what, or export security evidence | [Security and audit](/security-and-audit) | The audit trail, exports and delivery to your SIEM |
+| Understand a plan, an invoice or why access changed | [Billing and subscriptions](/billing-and-subscriptions) | How billing state turns into access, and how to reconcile a change |
+| Look up one operation, field or role | [API reference](/api) | The exact contract of every operation, generated from the application itself |
 
-1. **Environment and organization** — verify that you are working in the
-   intended application environment and organization.
-2. **Identity and scope** — use your own sign-in for a human task, or a dedicated
-   workload credential for software. Do not borrow a broader administrator
-   credential simply to make a request succeed.
-3. **Expected result** — write down the state that should change and the state
-   that must remain unchanged.
-4. **Verification** — decide how you will confirm the result from the
-   application's authoritative state, especially if a request times out after a
-   write.
+Sections appear in the navigation only when this application offers the capability. If a section named above is missing, the application does not expose that capability, and no setting on your side adds it.
 
-## Three useful first journeys
+## Three things to know before you change anything
 
-### Help a person gain the right access
+1. **Organization.** Almost everything belongs to one organization. Check which organization you are working in before you invite, change or export; the same person can be a member of several.
+2. **Identity.** Use your own account for work you do yourself and a dedicated API key or OAuth client for software. Never lend an administrator's credential to an integration to make a request succeed; give the integration the smallest role that works.
+3. **Verification.** The application is the source of truth. After an administrative change, a payment or an API write, confirm the result in the application rather than trusting a green status alone.
 
-Start with [User administration](/user-administration). Choose manual
-administration for an individual membership, or the SCIM journey when an
-identity provider owns the user lifecycle. Single sign-on authenticates the
-person; it does not by itself create the intended organization membership or
-role.
+## How the documentation is organised
 
-### Connect another system safely
-
-Start with [Integrations](/integrations). Choose the connection surface from
-the direction and shape of the work:
-
-- use **REST** when your integration initiates a read or change;
-- use a **webhook** when the application should notify your receiver of a
-  published event;
-- use an **automation platform** when n8n, Zapier or Make should coordinate the
-  workflow;
-- use **MCP or A2A** only when the corresponding agent surface is present.
-
-Prove one read with a narrowly scoped credential before enabling a write. After
-any timeout or lost response, read the authoritative state before retrying.
-
-### Investigate an unexpected result
-
-Start with [Security and audit](/security-and-audit) when you need to establish
-who did what, in which organization, and whether the operation succeeded. Start
-with [Troubleshoot user access](/user-administration/troubleshoot-user-access)
-when the symptom is a sign-in, membership, role or visibility problem. Preserve
-correlation identifiers and timestamps; they make a support or audit review
-materially faster.
-
-## Guides and references have different jobs
-
-A **guide** explains the intended outcome, prerequisites, safe sequence,
-decisions and recovery path. The **API reference** defines exact operations,
-parameters, fields, role requirements and response schemas. Use the guide to
-choose and operate the right journey; use the reference while implementing a
-specific request. Do not turn an endpoint list into an operating procedure, and
-do not treat explanatory prose as a substitute for the current operation
-contract.
+- **Guides** explain a task from start to finish: what you need, what to click or send, what you should see, and what to do when it fails.
+- **Reference** pages hold exact values you look up rather than read: statuses, error codes, limits, field meanings. The [API reference](/api) is generated from the running application, so it is always the current contract.
+- Every guide links to the reference it relies on, and no guide repeats a value the reference owns.
 
 ## When you ask for help
 
-Provide the environment, organization, approximate time, operation or task,
-correlation identifier, expected result and observed result. **Never include a
-password, API key, OAuth secret, SCIM token or session value** in a ticket,
-message or screenshot.`,
+Give the organization, the page or operation you were using, the time, what you expected and what you saw. For an API call, add the HTTP status and the \`error.correlationId\` from the response; for a webhook, the delivery identifier and \`jti\`. Never include a password, an API key, a bearer token or another person's data.`,
     },
     {
         managedPath: 'access-and-identity/overview.md',
         unitRef: 'technical-documentation:unit/authentication',
         sourceRefs: [
             'saas-technical-doc:engine-content/authentication',
+            'source:companion-projection:application-authentication',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-authentication-methods',
         ],
         markdown: `# Access and identity
@@ -173,13 +104,13 @@ receive a refusal.
 | Run an unattended workload | [API keys](/access-and-identity/api-keys) | A person’s browser session |
 | Let another client act for a person | [OAuth provider and delegated access](/access-and-identity/oauth-provider) | The person’s password or an over-privileged machine key |
 
-## What a sign-in screen may offer
+## What {{APPLICATION_NAME}} accepts to sign in
 
-{{CONSUMER_FACT:source:consumer-fact:access-authentication-methods#markdown}}
+{{APPLICATION_AUTHENTICATION:enabledSignInMethods}}
 
-This inventory is not an availability promise. The sign-in screen and
-its available-method response are authoritative for the current person and
-organization.
+### The full catalogue, for comparison
+
+{{CONSUMER_FACT:source:consumer-fact:access-authentication-methods#markdown}}
 
 ## What happens after a credential is presented
 
@@ -211,6 +142,7 @@ Use the generated API reference for the exact operation-level contract.`,
         unitRef: 'technical-documentation:unit/sign-in-and-mfa',
         sourceRefs: [
             'saas-technical-doc:engine-content/sign-in-and-mfa',
+            'source:companion-projection:application-authentication',
             'source:consumer-fact:access-authentication-methods',
         ],
         markdown: `# Sign in and multifactor authentication
@@ -250,6 +182,22 @@ authorization are separate. A correct password, passkey or provider response
 can start a session while the selected organization or role still refuses the
 person's intended work.
 
+## What this application requires of you
+
+{{APPLICATION_AUTHENTICATION:enabledSignInMethods}}
+
+A second factor is a separate decision from the method that starts the sign-in:
+
+{{APPLICATION_AUTHENTICATION:multifactorPolicy}}
+
+If a password is one of the methods above, it must satisfy these rules:
+
+{{APPLICATION_AUTHENTICATION:passwordRules}}
+
+## How long a session lasts, and what failed attempts cost
+
+{{APPLICATION_AUTHENTICATION:sessionAndLockout}}
+
 ## Follow the sign-in journey
 
 | Your next task | Start here | Successful result |
@@ -327,7 +275,8 @@ follow the order presented for this attempt.
 1. Open the sign-in page for the intended environment and verify the expected
    application identity before entering a credential.
 2. Choose a method currently offered to this person and organization. A method
-   from the support inventory that is absent here is not available for this attempt.
+   from the catalogue that is absent from the sign-in screen is not available for
+   this attempt.
 3. Complete the first factor or organization SSO journey using the person's own
    credential and device.
 4. Complete a required second-factor challenge. If enrollment is requested,
@@ -361,7 +310,10 @@ recovery value, full provider response or session cookie in support evidence.`,
     {
         managedPath: 'access-and-identity/mfa-enrollment-and-recovery.md',
         unitRef: 'technical-documentation:unit/mfa-enrollment-and-recovery',
-        sourceRefs: ['saas-technical-doc:engine-content/mfa-enrollment-and-recovery'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/mfa-enrollment-and-recovery',
+            'source:companion-projection:application-authentication',
+        ],
         markdown: `# Enroll and recover multifactor authentication
 
 Use multifactor authentication with a factor controlled by the person signing
@@ -375,6 +327,10 @@ here.
 | --- | --- |
 | Use the person's own session, have the device or inbox needed by the offered method, and choose a protected place for recovery material | The new factor is verified, a fresh challenge succeeds and recovery material is stored separately from the primary credential |
 
+## What this application asks for, and what enrolment gives you
+
+{{APPLICATION_AUTHENTICATION:multifactorPolicy}}
+
 ~~~mermaid
 flowchart TD
   accTitle: Enroll a factor and preserve a safe recovery path
@@ -521,9 +477,8 @@ organization.
   organization-scope** problem.
 - A resource that appears missing can be genuinely absent or outside the
   person's visible scope. Do not confirm hidden data from the error alone.
-- A method listed in the application's support inventory is not necessarily
-  enabled for this person and organization. The current sign-in screen is the
-  availability evidence.
+- A method listed in the catalogue is not necessarily enabled for this person and
+  organization. The current sign-in screen is the availability evidence.
 
 Never use an administrator account, another person's session or a machine
 credential to make a user action succeed. That hides the real problem and
@@ -2299,7 +2254,6 @@ complete authorization response.`,
         unitRef: 'technical-documentation:unit/user-administration',
         sourceRefs: [
             'saas-technical-doc:engine-content/user-administration',
-            'source:consumer-fact:organization-membership-administration',
         ],
         markdown: `# User administration
 
@@ -2326,7 +2280,7 @@ flowchart LR
 
 ## Choose how your organization manages users
 
-{{CONSUMER_FACT:source:consumer-fact:organization-membership-administration#markdown}}
+Membership states, the roles available in this application and the last-owner rule are listed once, on [Roles and permissions](/user-administration/roles-and-permissions).
 
 Choose **manual management** when an administrator should invite people, choose
 their access, pause access, or remove them directly in the application. Each
@@ -2453,7 +2407,6 @@ credentials into tickets or audit notes.`,
         unitRef: 'technical-documentation:unit/invite-and-onboard-user',
         sourceRefs: [
             'saas-technical-doc:engine-content/invite-and-onboard-user',
-            'source:consumer-fact:organization-membership-administration',
         ],
         markdown: `# Invite and onboard a user
 
@@ -2525,7 +2478,7 @@ Then confirm all three choices with the person’s manager or access owner:
 
 ## Send and follow the invitation
 
-{{CONSUMER_FACT:source:consumer-fact:organization-membership-administration#markdown}}
+Membership states, the roles available in this application and the last-owner rule are listed once, on [Roles and permissions](/user-administration/roles-and-permissions).
 
 After you send it, find the person in the member list and check that the state
 is **Invited**. At this point, the person has not received active organization
@@ -2534,7 +2487,10 @@ email filtering rules, then use the published resend action for the pending
 invitation. Resending replaces the earlier acceptance link; do not create a
 second invitation for the same person just to send another email.
 
-The invitation link is valid for **seven days** and can be used once. If the
+The invitation link is valid for **seven days** and can be used once; resend
+it to issue a fresh link. An invitation that is neither accepted nor revoked
+is removed automatically after **30 days**, so a person who never responds
+does not stay listed as invited indefinitely. If the
 link is expired, revoked, already consumed, or no longer matches an invited
 membership, the acceptance must fail rather than activating a different state.
 
@@ -2583,6 +2539,7 @@ offer when the underlying access decision changes.`,
         unitRef: 'technical-documentation:unit/organization-roles',
         sourceRefs: [
             'saas-technical-doc:engine-content/organization-roles',
+            'source:companion-projection:application-administration',
             'source:companion-projection:organization-roles',
             'source:consumer-fact:organization-membership-administration',
         ],
@@ -2628,6 +2585,13 @@ The role descriptions below explain their intended use and boundary. A
 specific operation may impose a narrower rule, so the API reference remains
 authoritative when you need to know exactly who may call one operation.
 
+## Who may administer membership here
+
+The roles above say what each role is for. This says which of them may perform
+each membership action this application publishes:
+
+{{APPLICATION_ADMINISTRATION:memberActions}}
+
 ## Roles available in this application
 
 {{APPLICATION_ORGANIZATION_ROLES}}
@@ -2706,7 +2670,6 @@ different credential to bypass the refusal.`,
         unitRef: 'technical-documentation:unit/change-user-access',
         sourceRefs: [
             'saas-technical-doc:engine-content/change-user-access',
-            'source:consumer-fact:organization-membership-administration',
         ],
         markdown: `# Change a user's access
 
@@ -2785,7 +2748,7 @@ flowchart TD
 
 ## How membership state affects authority
 
-{{CONSUMER_FACT:source:consumer-fact:organization-membership-administration#markdown}}
+Membership states, the roles available in this application and the last-owner rule are listed once, on [Roles and permissions](/user-administration/roles-and-permissions).
 
 Only an **Active** membership contributes organization authority. A role is not
 a job title: it is a named permission set evaluated in the selected
@@ -2866,6 +2829,7 @@ credential to bypass the refusal.`,
         unitRef: 'technical-documentation:unit/manage-organization-units',
         sourceRefs: [
             'saas-technical-doc:engine-content/manage-organization-units',
+            'source:companion-projection:application-administration',
             'source:companion-projection:organization-unit-aware-resources',
             'source:consumer-fact:organization-units',
         ],
@@ -2882,6 +2846,10 @@ organization settings. If it does not, use the **Organization units API
 reference** linked from this page. This guide explains the business decisions;
 the reference supplies the exact operations the application publishes.
 
+## Who may administer organization units here
+
+{{APPLICATION_ADMINISTRATION:organizationUnitActions}}
+
 > **Start with the business decision.** Name the information or action that a
 > department must control before you build the hierarchy. If nothing in the
 > application is unit-aware, a unit is only a label and grants no useful access.
@@ -3160,7 +3128,6 @@ result with a representative member’s own account.`,
         unitRef: 'technical-documentation:unit/suspend-or-remove-user',
         sourceRefs: [
             'saas-technical-doc:engine-content/suspend-or-remove-user',
-            'source:consumer-fact:organization-membership-administration',
         ],
         markdown: `# Suspend or remove a user
 
@@ -3215,7 +3182,7 @@ flowchart LR
 | The person should temporarily lose access | Suspend the membership | Keep the membership record while access is on hold; reactivate only when the hold is cleared |
 | The person has left this organization or must permanently lose this organization access | Remove the membership | End this organization relationship and its roles |
 
-{{CONSUMER_FACT:source:consumer-fact:organization-membership-administration#markdown}}
+Membership states, the roles available in this application and the last-owner rule are listed once, on [Roles and permissions](/user-administration/roles-and-permissions).
 
 ## Protect organization administration first
 
@@ -3283,7 +3250,6 @@ transition is not valid from the current membership state.`,
         unitRef: 'technical-documentation:unit/review-users-and-access',
         sourceRefs: [
             'saas-technical-doc:engine-content/review-users-and-access',
-            'source:consumer-fact:organization-membership-administration',
         ],
         markdown: `# Review users and access
 
@@ -3329,7 +3295,7 @@ Start broad so an invited, suspended or inactive record is not omitted simply
 because it cannot currently authorize an operation. Then narrow the review to
 the access that carries the most business or administrative impact.
 
-{{CONSUMER_FACT:source:consumer-fact:organization-membership-administration#markdown}}
+Membership states, the roles available in this application and the last-owner rule are listed once, on [Roles and permissions](/user-administration/roles-and-permissions).
 
 ## Prepare the review
 
@@ -3712,9 +3678,8 @@ list—not a 404:
 }
 ~~~
 
-Errors use the SCIM error media type and may include a \`scimType\` such as
-\`invalidFilter\`, \`uniqueness\`, \`invalidSyntax\`, \`invalidPath\` or
-\`tooMany\`. Preserve the HTTP status, SCIM type, redacted detail, operation,
+Errors use the SCIM error media type and may include a \`scimType\` of
+\`invalidSyntax\`, \`invalidValue\`, \`uniqueness\` or \`tooMany\`. Preserve the HTTP status, SCIM type, redacted detail, operation,
 provider job identifier and time. Never preserve the bearer token.
 
 ## Standards used by this profile
@@ -3800,7 +3765,7 @@ using it for automatic provisioning.
   "autoCreateUsers": true,
   "autoVerifyEmail": true,
   "autoDeactivateUsers": false,
-  "defaultRole": "organization-member",
+  "defaultRole": "ORG_MEMBER",
   "attributeMapping": {
     "email": "emails[primary eq true].value",
     "firstName": "name.givenName",
@@ -4499,7 +4464,10 @@ unrestricted evidence export in an ordinary support ticket.`,
     {
         managedPath: 'security-and-audit/investigate-event.md',
         unitRef: 'technical-documentation:unit/investigate-audit-event',
-        sourceRefs: ['saas-technical-doc:engine-content/investigate-audit-event'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/investigate-audit-event',
+            'source:consumer-fact:organization-audit-trail',
+        ],
         markdown: `# Investigate an audit event
 
 Begin with a question, not with the entire event stream: “Why was this request
@@ -4507,6 +4475,17 @@ refused?”, “Who changed this person's role?” or “What happened after thi
 credential was used?” Choose the smallest time range and organization that can
 answer it.
 
+## What you can narrow the trail by
+
+{{CONSUMER_FACT:source:consumer-fact:organization-audit-trail#queryMarkdown}}
+
+Every event carries a category and a severity. Both are closed lists, so they are
+the two filters that reliably cut a broad question down:
+
+{{CONSUMER_FACT:source:consumer-fact:organization-audit-trail#categoriesMarkdown}}
+
+{{CONSUMER_FACT:source:consumer-fact:organization-audit-trail#severitiesMarkdown}}
+
 | Before you begin | Successful result |
 | --- | --- |
 | Have one reviewable question, the intended organization/environment, an approximate time and any event, correlation, resource or actor identifier already known | The relevant event chain and actor/outcome are explained, current resource state is reconciled, and any anomaly has an owner without changing the evidence |
@@ -5337,7 +5316,10 @@ delivery can coexist with a broken mapping or detection.`,
     {
         managedPath: 'security-and-audit/operate-siem.md',
         unitRef: 'technical-documentation:unit/operate-and-troubleshoot-siem-delivery',
-        sourceRefs: ['saas-technical-doc:engine-content/operate-and-troubleshoot-siem-delivery'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/operate-and-troubleshoot-siem-delivery',
+            'source:consumer-fact:organization-siem-export',
+        ],
         markdown: `# Operate and troubleshoot SIEM delivery
 
 The organization audit record and the SIEM copy have different health signals.
@@ -5363,6 +5345,10 @@ flowchart TD
   captured -->|Authorized purge| purge["Remove recovery row without retry"]
 ~~~
 
+## When a destination keeps failing
+
+{{CONSUMER_FACT:source:consumer-fact:organization-siem-export#deliveryReliabilityMarkdown}}
+
 ## Start from the failure boundary
 
 | Symptom | First checks |
@@ -5765,7 +5751,6 @@ only after the expected application proof is clear.`,
         unitRef: 'technical-documentation:unit/start-billing-subscription',
         sourceRefs: [
             'saas-technical-doc:engine-content/start-billing-subscription',
-            'source:consumer-fact:billing-lifecycle',
         ],
         markdown: `# Start a subscription
 
@@ -5840,7 +5825,8 @@ Do not use the success URL as the success criterion. In the application, verify:
 
 Use the maintained subscription meanings when reading the result:
 
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#subscriptionStatusesMarkdown}}
+The subscription states and what each one means for access are listed under
+[Reconcile access after a billing change](/billing-and-subscriptions/reconcile-access).
 
 If the state remains incomplete, past due, unpaid or absent, do not create a
 second checkout immediately. Use the troubleshooting and reconciliation pages
@@ -5848,7 +5834,7 @@ to determine whether the first attempt is still being processed.
 
 ### Example: the browser closes after payment
 
-Suppose an administrator approves the Business plan, completes the hosted
+Suppose an administrator approves a paid plan, completes the hosted
 payment, and the browser closes before returning. Reopen Billing in the same
 organization and read the current subscription. If the approved plan is Active
 and the expected limit works, record that result and close the task. If the
@@ -5944,8 +5930,9 @@ state and payment evidence.
 
 ### Worked example: increase capacity mid-period
 
-An organization has a 50-run plan and needs 20 additional runs immediately.
-Before confirming an add-on, record:
+The figures below are illustrative; your own limits are shown in Billing.
+Suppose an organization's plan allows 50 automated runs and it needs 20 more
+immediately. Before confirming an add-on, record:
 
 - the current 50-run limit and current billing-period end;
 - the add-on price and whether the presented adjustment is immediate;
@@ -6164,6 +6151,12 @@ ordinary support evidence—not the complete document or payment details.`,
         ],
         markdown: `# Understand metered usage
 
+This page applies only if a plan or add-on you hold charges for a measured
+quantity. If everything you subscribe to is a flat recurring price, no usage is
+recorded and no usage line appears on an invoice — check
+[Understand plans, prices and access](/billing-and-subscriptions/plans-and-access)
+to see which of the two you have.
+
 A metered product charges for a measured quantity, such as processed documents,
 automated runs or storage consumed. The application records the activity first;
 the billing provider receives grouped usage later and uses its configured meter
@@ -6346,7 +6339,6 @@ card details, provider secrets and complete invoice documents.`,
         unitRef: 'technical-documentation:unit/troubleshoot-billing-change',
         sourceRefs: [
             'saas-technical-doc:engine-content/troubleshoot-billing-change',
-            'source:consumer-fact:billing-lifecycle',
         ],
         markdown: `# Troubleshoot a billing change
 
@@ -6382,7 +6374,8 @@ scope, then correlate provider evidence only where the state requires it.
 
 Use these maintained state meanings while diagnosing:
 
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#subscriptionStatusesMarkdown}}
+The full list of subscription states, and what each one means for access, is under
+[Reconcile access after a billing change](/billing-and-subscriptions/reconcile-access).
 
 ## Start from the symptom
 
@@ -7087,7 +7080,10 @@ sequenceDiagram
     {
         managedPath: 'integrations/ai-coding-tools.md',
         unitRef: 'technical-documentation:unit/ai-coding-tools',
-        sourceRefs: ['saas-technical-doc:engine-content/ai-coding-tools'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/ai-coding-tools',
+            'source:companion-projection:application-connection',
+        ],
         markdown: `# AI coding tools
 
 This application publishes an **MCP tool server** that supported AI coding
@@ -7099,7 +7095,7 @@ access, and it does not turn every application action into an autonomous one.
 
 - the server origin for the intended application environment;
 - authorization to use the MCP audience at
-  **<server-origin>/api/v1/mcp**;
+  **{{APPLICATION_CONNECTION_VALUE:mcpEndpointUrl}}**;
 - membership and roles for the organization you intend to work in;
 - confirmation of which tools may run automatically and which require approval.
 
@@ -7148,7 +7144,10 @@ be pasted into either.`,
     {
         managedPath: 'integrations/ai-tools/cursor.md',
         unitRef: 'technical-documentation:unit/connect-cursor',
-        sourceRefs: ['saas-technical-doc:engine-content/connect-cursor'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/connect-cursor',
+            'source:companion-projection:application-connection',
+        ],
         markdown: `# Connect Cursor
 
 Use this guide when Cursor Agent should read or act on information in this
@@ -7182,14 +7181,13 @@ Create the selected **mcp.json** file and add:
 {
   "mcpServers": {
     "application": {
-      "url": "<server-origin>/api/v1/mcp"
+      "url": "{{APPLICATION_CONNECTION_VALUE:mcpEndpointUrl}}"
     }
   }
 }
 ~~~
 
-Replace **<server-origin>** with the server origin for the intended application
-environment. Keep **/api/v1/mcp** exactly once. Do not add an Authorization
+The URL above is this application’s MCP endpoint. Confirm it belongs to the environment you intend before connecting. Keep **/api/v1/mcp** exactly once. Do not add an Authorization
 header to the shared JSON when the server supports interactive OAuth.
 
 Cursor's [current MCP documentation](https://cursor.com/docs/mcp) owns the
@@ -7287,7 +7285,10 @@ sequenceDiagram
     {
         managedPath: 'integrations/ai-tools/codex.md',
         unitRef: 'technical-documentation:unit/connect-codex',
-        sourceRefs: ['saas-technical-doc:engine-content/connect-codex'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/connect-codex',
+            'source:companion-projection:application-connection',
+        ],
         markdown: `# Connect Codex
 
 Use this guide when Codex needs authorized information or operations from this
@@ -7318,12 +7319,12 @@ Add this table to the selected configuration file:
 
 ~~~toml
 [mcp_servers.application]
-url = "<server-origin>/api/v1/mcp"
+url = "{{APPLICATION_CONNECTION_VALUE:mcpEndpointUrl}}"
 default_tools_approval_mode = "prompt"
 ~~~
 
-Replace **<server-origin>** with the server origin of the intended application
-environment. Keep **/api/v1/mcp** exactly once. The prompt approval mode means
+The URL above is this application’s MCP endpoint. Confirm it belongs to the environment
+you intend before connecting. Keep **/api/v1/mcp** exactly once. The prompt approval mode means
 Codex asks before using tools from this server.
 
 The [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
@@ -7423,7 +7424,10 @@ connectivity. A working read does not justify automatic write approval.
     {
         managedPath: 'integrations/ai-tools/claude-code.md',
         unitRef: 'technical-documentation:unit/connect-claude-code',
-        sourceRefs: ['saas-technical-doc:engine-content/connect-claude-code'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/connect-claude-code',
+            'source:companion-projection:application-connection',
+        ],
         markdown: `# Connect Claude Code
 
 Use this guide when Claude Code should read or act on information in this
@@ -7452,11 +7456,11 @@ Start with local scope unless a reviewed team or personal-wide need exists.
 Run this from the intended project:
 
 ~~~bash
-claude mcp add --transport http application <server-origin>/api/v1/mcp
+claude mcp add --transport http application {{APPLICATION_CONNECTION_VALUE:mcpEndpointUrl}}
 ~~~
 
-Replace **<server-origin>** with the server origin for the intended application
-environment and keep **/api/v1/mcp** exactly once. Add **--scope project** or
+The URL above is this application’s MCP endpoint. Confirm it belongs to the environment
+you intend before connecting, and keep **/api/v1/mcp** exactly once. Add **--scope project** or
 **--scope user** only after making the scope decision above.
 
 The [current Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
@@ -7677,6 +7681,7 @@ evidence, but they do not replace the application's authoritative audit trail.
         unitRef: 'technical-documentation:unit/first-request',
         sourceRefs: [
             'saas-technical-doc:engine-content/first-request',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-api-keys',
         ],
         markdown: `# Create your own integration
@@ -7770,7 +7775,7 @@ is the application's maintained API-key transport contract.
 
 ~~~bash
 curl --fail-with-body \
-  --url "<server-origin><documented-operation-path>" \
+  --url "{{APPLICATION_CONNECTION_VALUE:baseUrl}}<documented-operation-path>" \
   {{CONSUMER_FACT:source:consumer-fact:access-api-keys#curlRequestHeader}} \
   --header "accept: application/json"
 ~~~
@@ -7860,1203 +7865,717 @@ including collections, controlled writes and troubleshooting.`,
     {
         managedPath: 'integrations/rest-api.md',
         unitRef: 'technical-documentation:unit/common-rest-api',
-        sourceRefs: ['saas-technical-doc:engine-content/common-rest-api'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/common-rest-api',
+        ],
         markdown: `# REST API
 
-Use the REST API when another system needs to read or change application data
-and needs an immediate response. This section explains the decisions shared by
-REST integrations. The generated API reference remains authoritative for exact
-paths, fields, roles, statuses and resource-specific limits.
+The REST API lets another system read and change this application's data with an immediate answer. Everything the application shows in its own screens is reachable the same way: each screen is backed by the operations listed in the [API reference](/api), and an integration calls those operations directly.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Name one business outcome, the system that owns it, the organization in scope and the identity that should perform it | A repeatable request reaches the intended environment, proves only the required access and can be reconciled safely after failure |
+## What you get
 
-## Decide whether REST matches the work
+- One JSON API under \`/api/v1\`, documented operation by operation in the API reference: path, method, request fields, response shape, accepted credentials, required roles and the failures each operation can return.
+- One set of conventions shared by every operation: how to authenticate, how collections page and sort, what an error looks like, how limits and optimistic locking work. They are on one page, [REST API conventions](/integrations/rest/conventions), so the reference does not have to repeat them.
+- Two credential kinds. An **API key** is a long-lived secret for software that acts on behalf of an organization or the whole application. A **bearer token** is what a signed-in person or an OAuth client holds. [API keys](/access-and-identity/api-keys) explains how to create one and what it may do.
 
-| Need | Use | Why |
+## Choose the right tool first
+
+| You need to | Use | Why |
 | --- | --- | --- |
-| Read current application state now | REST read operation | The caller receives an immediate representation of what it is allowed to see |
-| Ask the application to make a change now | REST write operation | The caller receives an immediate success, refusal or ambiguous transport outcome |
-| React when the application publishes an event | **Webhooks** (published under Integrations when the application exposes an outbound delivery surface) | The application initiates delivery after the event; polling is not required |
-| Let an AI tool discover and invoke approved tools | **MCP** (published under Integrations when the application exposes an MCP tool surface) | Tool discovery and invocation are different from a fixed REST integration |
+| Read or change data now, and know the result | REST | The application answers each request with the outcome |
+| React after something happens in the application | [Webhooks](/integrations/webhooks) | The application calls you; no polling |
+| Let an AI assistant work with the application | [MCP](/integrations/mcp) | Tools are discovered and invoked by the assistant, not scripted by you |
+| Build in n8n, Zapier or Make | [Automation platforms](/integrations/automation-platforms) | Those tools already speak REST; the guides show the exact settings |
 
-REST describes the request/response transport. It does not decide who should
-own a business workflow, which organization is implied or whether a write is
-safe to repeat. Those decisions belong to the integration design and the exact
-operation contract.
+## The four pages of this section
 
-## Follow the request lifecycle
+1. [Send your first API request](/integrations/rest/send-request): reach the right environment with the right credential and prove it in ten minutes.
+2. [Read collections](/integrations/rest/read-collections): page, sort, search and filter without skipping or duplicating records.
+3. [Write and reconcile changes](/integrations/rest/write-and-reconcile): make a change once, use optimistic locking, and recover from a lost response.
+4. [Troubleshoot an API request](/integrations/rest/troubleshoot): turn a status code and an error body into the one thing to fix.
 
-~~~mermaid
-flowchart LR
-  accTitle: Build and reconcile a REST API request
-  accDescr: The integration selects an environment and operation, authenticates a dedicated identity, validates the response, then either commits the result or reconciles an ambiguous outcome.
-  choose["Select environment and documented operation"] --> auth["Authenticate the intended identity"]
-  auth --> send["Send a schema-valid request"]
-  send --> result{"Unambiguous result?"}
-  result -->|Yes| commit["Record outcome and correlation"]
-  result -->|No| read["Read authoritative state"]
-  read --> reconcile["Reconcile before any retry"]
+Keep [REST API conventions](/integrations/rest/conventions) open beside the API reference while you work; it is the page these guides point at for exact names and values.`,
+    },
+    {
+        managedPath: 'integrations/rest/conventions.md',
+        unitRef: 'technical-documentation:unit/rest-api-conventions',
+        sourceRefs: [
+            'saas-technical-doc:engine-content/rest-api-conventions',
+            'source:companion-projection:application-connection',
+            'source:consumer-fact:access-api-keys',
+            'source:consumer-fact:rest-conventions',
+        ],
+        markdown: `# REST API conventions
+
+Every operation in the API reference follows the same rules for addressing, authentication, collections, writes, errors and limits. Read this page once. After that, an operation's entry in the reference only has to tell you what is specific to it: its path, its fields, the roles it accepts and the failures it can return.
+
+## Addressing
+
+- Every path in the API reference already starts with the \`/api/v1\` mount. Prepend the base URL of the environment you are calling:
+
+{{APPLICATION_CONNECTION:baseUrls}}
+
+- Organization data lives under \`/api/v1/organizations/{organizationId}/…\`. The organization identifier is the one shown in the application. A collection under an organization your credential is not a member of answers **403**; a single record that belongs to another organization answers **404**, so that the application never confirms what exists outside your scope.
+- The same resource is often reachable through more than one parent path (for example through the organization directly and through a related record). Those paths are aliases of one operation and answer with the same data; use whichever matches the identifiers you already hold.
+- Send and expect \`application/json\`. Identifiers are opaque strings: store them, compare them, never parse them.
+- Header names are case-insensitive; this documentation writes them the way the application emits them.
+
+## Authentication
+
+{{CONSUMER_FACT:source:consumer-fact:access-api-keys#markdown}}
+
+Signed-in people and OAuth clients use a bearer token instead: \`Authorization: Bearer <access token>\`. Each operation's **Security** entry in the reference lists which of the two it accepts. Send exactly one credential per request.
+
+## Collections
+
+List and search operations share one query vocabulary:
+
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#collectionQueryMarkdown}}
+
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#paginationResponseMarkdown}}
+
+A concrete request and its response, using the members of your own organization:
+
+~~~bash
+curl --fail-with-body \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?page=1&limit=20&sort=joinedAt:desc" \\
+  --header "Authorization: $ORGANIZATION_API_KEY" \\
+  --header "accept: application/json"
 ~~~
 
-The most important branch is the last one. A timeout means that **the client did
-not receive a result**; it does not prove that the server made no change.
-
-## Keep four boundaries visible
-
-1. **Environment:** the server origin identifies where the request goes. Never
-   infer production from a path copied from another deployment.
-2. **Identity:** the operation states which credential types it accepts. Use a
-   dedicated workload credential for unattended work.
-3. **Organization and visibility:** a valid identity can still be unable to see
-   a resource outside its organization or authorized unit scope.
-4. **Operation contract:** request fields, enum values, roles, response shape
-   and failure meanings are specific to the chosen operation.
-
-An HTTP success is transport evidence, not the final business proof. Verify the
-returned identity and scope for reads, and re-read authoritative state after a
-write when the business result matters.
-
-## Choose the next task
-
-- [Send your first API request](/integrations/rest/send-request) to establish
-  environment, authentication and scope.
-- [Read collections reliably](/integrations/rest/read-collections) to handle
-  pagination, filtering and visibility without losing or duplicating work.
-- [Write and reconcile changes](/integrations/rest/write-and-reconcile) before
-  adding automatic retries to mutations.
-- [Troubleshoot an API request](/integrations/rest/troubleshoot) using the
-  response class and correlation evidence.
-
-## Keep the guide and reference in their roles
-
-This guide explains **why and in what order** to act. The API reference tells
-you **what this application publishes**. Never copy an operation from another
-application or infer a writable field from a response example. Start with
-[one safe request](/integrations/rest/send-request), not with retries, bulk
-processing or a production mutation.`,
+~~~json
+{
+  "data": [
+    {
+      "_id": "0d3f2a9e-6c41-4b7a-8e15-5f9c2b7d4a10",
+      "userId": "b8e4c2f1-3a57-4d09-9f6e-1c2d3e4f5a6b",
+      "userEmail": "alex.morgan@example.com",
+      "organizationId": "7c1f6f0a-4b1e-4d8f-9a0c-2e5b3c9d1f42",
+      "roles": ["ORG_MEMBER"],
+      "status": "ACTIVE",
+      "createdAt": "2026-07-03T09:15:00.000Z",
+      "updatedAt": "2026-08-18T08:00:00.000Z",
+      "_version": 4
+    }
+  ],
+  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
+}
+~~~
+
+## Writes
+
+- The reference states each operation's success status and the fields it accepts. A field you see in a read response is not automatically writable; send only what the request schema lists.
+- Operations marked **idempotent** in the reference can be repeated safely. For any other write, a lost response is an ambiguous outcome: read the record back before sending the write again. [Write and reconcile changes](/integrations/rest/write-and-reconcile) shows the procedure.
+- Bulk variants (\`…/bulk\` paths) apply one change to several identifiers. Read the operation's response schema before assuming every identifier was applied, and reconcile each one with a read after a failure.
+
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#concurrencyMarkdown}}
+
+## Errors
+
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#errorEnvelopeMarkdown}}
+
+For example, removing the last owner of an organization is refused like this:
+
+~~~json
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#errorExampleJson}}
+~~~
+
+Branch on the HTTP status first, then on \`error.type\`, and on \`error.code\` only for refusals the operation documents by name:
+
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#errorStatusMarkdown}}
+
+## Rate limits
+
+The application enforces several windows at once and reports the tightest one:
+
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#rateLimitMarkdown}}
+
+Back off when \`x-ratelimit-remaining\` reaches zero rather than waiting for the **429**. Parallel workers share the same counters when they share a credential.
+
+## Support evidence
+
+When you ask for help, quote the operation path, the HTTP status, \`error.type\`, \`error.code\` when present, and \`error.correlationId\`. That identifier joins your request to the application's logs and audit trail and contains no personal data. Never paste a credential, a bearer token or a full response body into a ticket.`,
     },
     {
         managedPath: 'integrations/rest/send-request.md',
         unitRef: 'technical-documentation:unit/send-api-request',
         sourceRefs: [
             'saas-technical-doc:engine-content/send-api-request',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-api-keys',
         ],
         markdown: `# Send your first API request
 
-Your first request should prove four things and nothing more: you reached the
-correct environment, the credential is accepted, the identity can see the
-intended organization and the response matches the published schema. Choose a
-read operation that has no business side effect.
+Ten minutes from an API key to a verified connection. The first request proves four things and nothing else: you reached the right environment, the credential is accepted, it sees the organization you expect, and you can read the response. Use a read operation that changes nothing.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Have the environment's server origin, one documented read operation, a dedicated credential accepted by that operation and one expected visible resource | The request returns the documented result in the intended scope, an expected refusal remains refused, and the credential can be revoked independently |
+## What you need
 
-~~~mermaid
-flowchart TD
-  accTitle: Prove an API connection from environment to business scope
-  accDescr: The integration owner selects a harmless documented read, targets one environment, sends an accepted credential, validates the response schema and organization scope, then confirms an expected refusal before allowing any write.
-  operation["Choose one harmless documented read"] --> environment["Set the exact environment origin"]
-  environment --> credential["Send one accepted dedicated credential"]
-  credential --> response{"Documented success response?"}
-  response -->|No| diagnose["Diagnose transport, authentication, authority or visibility"]
-  response -->|Yes| schema["Validate schema and intended organization"]
-  schema --> refusal["Confirm one expected refusal"]
-  refusal --> ready["Record proof and prepare one controlled write"]
+- The **base URL** of the environment you are calling. {{APPLICATION_NAME}} publishes these:
+
+{{APPLICATION_CONNECTION:baseUrls}}
+
+- Your **organization identifier**, shown in the application's organization settings and present in the URL of most screens.
+- An **organization API key** created for this integration, following [Create and store an API key](/access-and-identity/api-keys-create-and-store). Keep it in a secret store or an environment variable, never in the request URL or a build log.
+
+Give the request a name in your notes before you send it. "List the members of the Support organization, expect Alex Morgan" is a result you can check; "the call returned JSON" is not.
+
+## Step 1: read your own organization
+
+The safest first call reads the organization the key belongs to. It needs no other identifier and changes nothing.
+
+~~~bash
+BASE_URL="https://api.example.com"          # from the API reference's Servers list
+ORGANIZATION_ID="7c1f6f0a-4b1e-4d8f-9a0c-2e5b3c9d1f42"  # from the application's organization settings
+ORGANIZATION_API_KEY="sk_org_…"               # the key you created
+
+curl --fail-with-body \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID" \\
+  {{CONSUMER_FACT:source:consumer-fact:access-api-keys#curlRequestHeader}} \\
+  --header "accept: application/json"
 ~~~
 
-## What you need
+Replace the three values with yours; leave the header exactly as shown. {{CONSUMER_FACT:source:consumer-fact:access-api-keys#markdown}}
 
-- the server origin from this application's API reference;
-- one documented read operation;
-- a dedicated API key or another credential explicitly accepted by that operation;
-- an organization and resource that the identity is expected to see.
+A successful answer is **200** with the organization record: its \`_id\` is the identifier you sent, and \`name\` is the organization you expected. Anything else, read the [failure table](#if-it-fails) below before changing more than one thing.
 
-Choose a request that is easy for a human to recognize afterwards. A list or
-single-resource read in a test organization is usually better than a broad
-export. Record the expected identifier or count before calling the API so that
-you can distinguish “valid JSON” from the correct business result.
+## Step 2: read a collection
 
-Copy the operation path and parameters from the API reference. For an API key,
-send the key in the standard authorization header:
+Now list the organization's members. This exercises the collection envelope you will meet on every list and search operation:
 
 ~~~bash
-curl --fail-with-body \
-  --url "<server-origin>/<documented-path>" \
-  {{CONSUMER_FACT:source:consumer-fact:access-api-keys#curlRequestHeader}} \
+curl --fail-with-body \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?limit=5&sort=joinedAt:desc" \\
+  --header "Authorization: $ORGANIZATION_API_KEY" \\
   --header "accept: application/json"
 ~~~
 
-Replace only the placeholders shown by the exact API reference. Do not add a
-\`Bearer\` prefix to an API key, put credentials in the URL, or print the fully
-expanded command into an ordinary build log. For a user or delegated OAuth
-journey, use the credential scheme documented by that operation instead of
-sending two credentials and relying on accidental precedence.
+The response is \`{ "data": [ … ], "pagination": { "page": 1, "limit": 5, "total": …, "totalPages": … } }\`. Check that \`total\` matches the member count you see in the application. [Read collections](/integrations/rest/read-collections) covers paging, sorting and filters in full.
 
-## Verify the result
+## Step 3: prove the boundary holds
 
-Do not stop at “the request returned JSON.” Confirm:
+A connection is only safe when a wrong credential is refused. Send the first request again with the key deliberately broken:
 
-1. the status is the documented success status;
-2. the response conforms to the operation schema;
-3. the returned organization and resource are the ones you intended;
-4. the credential can be identified and revoked without affecting another workload;
-5. logs contain correlation and outcome data but not the credential.
+~~~bash
+curl --include \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID" \\
+  --header "Authorization: sk_org_not_a_real_key" \\
+  --header "accept: application/json"
+~~~
 
-Then run one **negative proof**: request an operation this identity is
-deliberately not allowed to use, without probing another customer's known
-identifier. The documented refusal demonstrates that scope enforcement remains
-present; it is as important as the successful read.
+Expect **401** with \`"type": "AUTHENTICATION"\` in the error body. Then send the correct key against an organization it does not belong to and expect **404**: the application does not confirm that organizations outside your scope exist. Those two refusals are the negative proof; record them beside the successful read.
 
-If the request fails, use the status class before changing anything: 401 points
-to authentication, 403 to authority, and 404 to identity, scope or resource
-selection. Do not create a more privileged credential until you know which
-decision failed.
+## If it fails
+
+| You see | It means | Do this |
+| --- | --- | --- |
+| No response, or a TLS or DNS error | The base URL is wrong or unreachable from where you run | Compare the URL with the Servers list; test from the network the integration will run on |
+| **401** \`AUTHENTICATION\` | The key was not accepted | Check the header carries the full key with no \`Bearer\` prefix, that the key is \`active\`, and that it belongs to this environment |
+| **403** \`AUTHORIZATION\` | The key is valid but its roles do not allow this operation | Compare the roles on the key with the roles the operation lists in the reference |
+| **404** \`NOT_FOUND\` | The organization identifier is wrong, or this key cannot see it | Copy the identifier from the application again |
+| **429** \`RATE_LIMIT\` | Too many requests | Wait \`Retry-After\` seconds |
 
-## Before the first write
+Every error an operation produces carries \`error.correlationId\`. Quote it when you ask for help. [Troubleshoot an API request](/integrations/rest/troubleshoot) goes deeper.
 
-Repeat the read from the deployment environment, then revoke or rotate the test
-credential to prove the operating procedure. Only then choose one small write
-and define how you will detect whether it applied after a timeout.
+## Before your first write
 
-Record the environment, operation identity, credential's non-secret identifier,
-organization, expected business result, observed status and correlation value.
-That is enough to reproduce the connection proof without retaining the secret
-or an unrestricted response payload.`,
+Repeat Step 1 from the environment where the integration will actually run. Then rotate the key once ([API key lifecycle](/access-and-identity/api-keys-lifecycle)) to prove that the operating procedure works before you depend on it. Only then choose one small write and read [Write and reconcile changes](/integrations/rest/write-and-reconcile).`,
     },
     {
         managedPath: 'integrations/rest/read-collections.md',
         unitRef: 'technical-documentation:unit/work-with-api-collections',
-        sourceRefs: ['saas-technical-doc:engine-content/work-with-api-collections'],
-        markdown: `# Read collections reliably
+        sourceRefs: [
+            'saas-technical-doc:engine-content/work-with-api-collections',
+            'source:consumer-fact:rest-conventions',
+        ],
+        markdown: `# Read collections
 
-A collection is the set of records one operation lets the caller see **in its
-current organization and access scope**. It is not automatically every record
-in the application. A reliable integration reads that visible set in bounded
-pages, processes each record safely and can resume without silently skipping or
-duplicating business work.
+A collection is the set of records one list or search operation lets your credential see in one organization. Read it in pages, sort it deliberately, filter it on the fields the operation offers, and stop where the response says to stop. Every list and search operation in the API reference uses the vocabulary below.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Choose one documented list or search operation, the organization in scope, the filters that express the business question and a stable way to recognize processed records | Every returned page is validated and checkpointed, completion follows the returned pagination metadata, and a repeated or resumed scan does not create a duplicate business effect |
+## The query vocabulary
 
-## Begin with the business question
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#collectionQueryMarkdown}}
 
-Write down what the scan is meant to answer before choosing parameters. “Read
-all records” is usually too broad. Prefer a bounded outcome such as:
+Filter and sort fields are per operation. Each operation's entry in the API reference lists them as query parameters, so open the operation before writing the request; a filter accepted by one resource is not a convention for another.
 
-- reconcile records changed during a defined operating window;
-- find records in a documented state that need attention;
-- copy the minimum fields required for a downstream report;
-- verify that a previous write produced the intended current state.
+## The response envelope
 
-Then open the exact operation in the API reference. Confirm the response item,
-available filters and sort fields, pagination ceiling and required authority.
-**A parameter accepted by one collection is not a platform-wide convention.**
-Do not reuse a filter name, page size or sort order from another resource.
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#paginationResponseMarkdown}}
 
-## Read one page at a time
+An empty \`data\` array on page 1 is a valid answer. Confirm the organization and the filters before treating it as a failure.
 
-When the API reference declares page and limit parameters, the response carries
-the current page, limit, total count and total pages with the returned data.
-Process the current page successfully before advancing. Stop from returned
-pagination metadata; do not guess from a short page or copy a maximum size from
-another resource.
+## Walk every page
 
-~~~mermaid
-flowchart TD
-  accTitle: Consume a paginated collection without skipping work
-  accDescr: The integration requests one documented page, validates and processes it, records progress, and advances only while returned pagination metadata says another page exists.
-  request["Request documented page"] --> validate["Validate response and scope"]
-  validate --> process["Process page idempotently"]
-  process --> checkpoint["Persist progress"]
-  checkpoint --> more{"Returned metadata shows another page?"}
-  more -->|Yes| request
-  more -->|No| done["Collection pass complete"]
+~~~bash
+page=1
+while : ; do
+  response=$(curl --fail-with-body --silent \\
+    --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?page=$page&limit=100&sort=joinedAt:asc" \\
+    --header "Authorization: $ORGANIZATION_API_KEY" \\
+    --header "accept: application/json")
+  echo "$response" | jq -c '.data[]' >> members.ndjson
+  totalPages=$(echo "$response" | jq '.pagination.totalPages')
+  [ "$page" -ge "$totalPages" ] && break
+  page=$((page + 1))
+done
 ~~~
 
-Follow that lifecycle in order:
+Three rules keep a scan correct:
 
-1. Request the first documented page with an explicit, supported limit and only
-   the filters needed for the business question.
-2. Validate the response envelope and each item before using its fields. Check
-   that the result belongs to the intended environment and organization.
-3. Process each record **idempotently**. Reprocessing the same stable record
-   identifier must not create a second payment, message, account or other
-   business effect.
-4. Persist a checkpoint only after the page's work is safely recorded. Keep the
-   page number, filter and sort basis, stable identifiers or counts, and the
-   returned pagination metadata.
-5. Advance only while the response says another page exists. Do not stop merely
-   because a page contains fewer items than requested.
-
-An empty first page can be a correct result. Prove it by confirming the caller,
-organization, filters and expected visibility rather than treating emptiness as
-a transport failure.
-
-## Read the pagination metadata literally
-
-The standard collection envelope contains the returned data plus **page**,
-**limit**, **total** and **totalPages**. These values describe the server's
-answer to that request:
-
-- **page** identifies the page just returned;
-- **limit** is the page size applied by that operation;
-- **total** is the matching record count reported for the query;
-- **totalPages** tells the caller whether another numbered page remains.
-
-Do not manufacture a next page from the number of items alone. If the operation
-publishes a different paging model, follow that operation instead of translating
-it into this one.
-
-## Decide how changes during a scan are handled
-
-Records may be created or changed while a multi-page scan runs. If the exact
-operation does not publish snapshot or cursor semantics, do not claim a
-point-in-time view. Make downstream processing idempotent, retain stable record
-identifiers and schedule a reconciliation pass appropriate to the business risk.
-
-Choose the recovery posture before production:
-
-- For a low-risk report, a later complete pass may be sufficient.
-- For a state synchronization, persist stable identifiers and compare the final
-  downstream state with a fresh authoritative read.
-- For financial, access or other sensitive effects, use a documented stable
-  ordering or change marker when available and explicitly investigate gaps.
-- If the scan fails halfway through, resume from the last **completed**
-  checkpoint. Reprocessing the boundary page is safer than skipping uncertain
-  work when processing is idempotent.
-
-Never assume that page 2 still starts after the same record if concurrent
-changes can reorder the collection. The operation contract determines whether a
-stable scan is possible; the client cannot create that guarantee by remembering
-only a page number.
-
-## Verify completion
-
-Compare the processed count and checkpoints with the final returned metadata,
-then sample a small number of recognizable records in the intended organization.
-Run one controlled repeat and confirm it produces no duplicate downstream
-effect. If records can change during the pass, run the planned reconciliation
-and explain any difference rather than forcing the counts to appear equal.
-
-Retain the operation identity, environment, organization, filter and sort basis,
-start/end time, pages processed, final pagination metadata and non-sensitive
-checkpoint. Do not log full result sets merely to prove the scan ran; store the
-minimum identifiers and counts needed to investigate omissions or duplicates.
+1. **Sort by a field the reference lists as sortable, or a stable timestamp** such as \`joinedAt:asc\` for members, when you walk more than one page. A sort field the operation does not accept is ignored, not refused, and the default order applies; sorting by a field that changes during the scan (a status, a name being edited) can move a record between pages and make you skip or repeat it.
+2. **Stop on \`totalPages\`**, not on a short page. The last page is short by definition; an earlier page is short only when records were deleted while you scanned.
+3. **Process each record idempotently** and key your own records on \`_id\`. If the scan is interrupted, resume from the last page whose work you completed; repeating a page is safe when processing is idempotent, skipping one never is.
 
-## Continue safely
+## Search and filter
 
-- [Write and reconcile changes](/integrations/rest/write-and-reconcile) before
-  turning collection results into mutations.
-- [Troubleshoot an API request](/integrations/rest/troubleshoot) when one page
-  fails or visibility differs from the expected organization scope.
-- Return to [REST API](/integrations/rest-api) to review the request, identity,
-  organization and operation boundaries.`,
-    },
-    {
-        managedPath: 'integrations/rest/write-and-reconcile.md',
-        unitRef: 'technical-documentation:unit/write-and-reconcile-api-changes',
-        sourceRefs: ['saas-technical-doc:engine-content/write-and-reconcile-api-changes'],
-        markdown: `# Write and reconcile API changes
+Search operations (\`…/search\`) add \`q\` for free text. Combine it with filters and sorting:
 
-A write is complete only when the integration knows the authoritative outcome.
-An HTTP method does not by itself make a mutation safe to repeat, and a client
-timeout does not prove that nothing changed.
+~~~bash
+curl --fail-with-body \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members/search?q=morgan&status=ACTIVE&sort=joinedAt:desc" \\
+  --header "Authorization: $ORGANIZATION_API_KEY" \\
+  --header "accept: application/json"
+~~~
 
-| Before you begin | Successful result |
-| --- | --- |
-| Choose one documented write, a test organization, a least-privilege identity, the expected current state and a stable way to recognize the intended business change | One controlled change reaches the expected state, an unauthorized or invalid change remains refused, and a lost response can be reconciled without creating a duplicate effect |
+Date-range filters are objects and use bracket notation, one key per bound:
 
-## Define the business identity of the change
+~~~text
+?createdAt[startDate]=2026-09-01T00:00:00Z&createdAt[endDate]=2026-09-30T23:59:59Z
+~~~
 
-Before sending the request, decide which stable application or external
-identifier lets you recognize the same intended change later. Use a documented
-idempotency contract when the operation publishes one. Otherwise, prevent
-concurrent duplicate work in your own system and reconcile from authoritative
-state after uncertainty.
+Send instants in ISO 8601 with a timezone. An unparseable bound answers **400** with the field named in \`error.validationErrors\`.
 
-Separate three identifiers where the business process has them:
+## Counts and summaries
 
-- the **request attempt**, which can happen more than once;
-- the **intended business change**, which should happen once;
-- the **resulting application record**, which proves the current state.
+Beside the full list, most collections expose \`…/summary\`, which answers the fields the application uses for pickers and tables and is smaller and faster than the full record. Some also expose \`…/count\`, which answers only the total without loading records. The API reference shows which variants an operation has. Use them for dashboards and reconciliation counts; use the full list only when you need every field.
 
-Do not invent an idempotency header or client token unless the exact operation
-documents one. A locally generated identifier is still useful for your logs and
-work queue, but it does not make the server deduplicate the request.
+## Reconcile a long scan
 
-## Prepare one controlled write
+Records can change while a scan runs. When the scan feeds a report, a later complete pass corrects it. When it feeds a synchronization, keep the \`_id\` and \`_version\` of each record you processed and compare them with a fresh read before you overwrite anything downstream; \`_version\` increases on every write, so a changed value tells you the record moved.
 
-1. Read the target resource and record the fields that form the expected
-   pre-change state.
-2. Validate the request locally against the published schema. Send only fields
-   the write accepts; a field returned by a read is not automatically writable.
-3. Confirm the caller, organization and role immediately before the mutation.
-   Use a dedicated workload identity rather than a person's broad credential.
-4. Send the change once and retain the status, stable error code and correlation
-   identifier without retaining the credential or unrestricted payload.
-5. Read the authoritative resource again. Verify the intended state and scope,
-   not only the HTTP success response.
-6. Exercise one expected refusal—for example insufficient authority or an
-   invalid transition—and confirm that authoritative state did not change.
+## When a page fails
 
-~~~mermaid
-stateDiagram-v2
-  accTitle: Reconcile a state-changing API request
-  accDescr: A prepared change is sent once. A confirmed response records success or refusal. A timeout or lost response enters an ambiguous state that must be resolved by reading authoritative application state before retrying.
-  [*] --> Prepared
-  Prepared --> Sent
-  Sent --> Confirmed: documented success
-  Sent --> Refused: unambiguous failure
-  Sent --> Ambiguous: timeout or connection loss
-  Ambiguous --> Confirmed: authoritative state shows applied
-  Ambiguous --> SafeToRetry: authoritative state shows not applied
-  SafeToRetry --> Sent
-  Confirmed --> [*]
-  Refused --> [*]
-~~~
+A failed page answers with the same error envelope as any request; the status table in [REST API conventions](/integrations/rest/conventions#errors) says what each status means. A **429** carries \`Retry-After\`; wait that long before resuming from the same page. Do not resume from page 1.`,
+    },
+    {
+        managedPath: 'integrations/rest/write-and-reconcile.md',
+        unitRef: 'technical-documentation:unit/write-and-reconcile-api-changes',
+        sourceRefs: [
+            'saas-technical-doc:engine-content/write-and-reconcile-api-changes',
+            'source:consumer-fact:rest-conventions',
+        ],
+        markdown: `# Write and reconcile changes
 
-The **Ambiguous** state is operationally important. It means the client cannot
-yet classify the business outcome. It is not success, failure or permission to
-send the mutation again.
+A write is finished when you know what the application now contains, not when the HTTP call returns. This page shows how to make a change once, how to refuse to overwrite someone else's change, and what to do when the response never arrives.
 
-## Reconcile an ambiguous outcome
+## Send the change
 
-When the connection closes, times out or loses the response:
+1. Open the operation in the API reference and copy its request schema. Send only the fields it lists; a field you saw in a read is not necessarily writable.
+2. Read the record first and keep its \`_version\`.
+3. Send the write with the version in the \`if-match\` header.
+4. Read the record again and compare the fields you changed with what you intended. A **200** proves the application accepted the request; the second read proves the business result.
 
-1. Stop automatic retries for that business change.
-2. Read the target through the documented authoritative operation.
-3. Compare its current state with both the pre-change state and intended result.
-4. If the result is present, record the original attempt as applied even though
-   its response was lost.
-5. If the result is absent and the read is conclusive, allow one bounded retry
-   under the same business-change identity.
-6. If the state is conflicting or visibility is insufficient, route the item
-   for human reconciliation instead of guessing.
+Updating a member's roles, with optimistic locking:
 
-For create operations, reconcile using a documented stable business key or a
-search that can identify the new record. If no reliable lookup exists, the
-operation is not yet safe for unattended retries.
+~~~bash
+curl --fail-with-body \\
+  --request PUT \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members/$MEMBER_ID" \\
+  --header "Authorization: $ORGANIZATION_API_KEY" \\
+  --header "content-type: application/json" \\
+  --header "if-match: 4" \\
+  --data '{ "roles": ["ORG_MANAGER"] }'
+~~~
 
-## Treat failures by meaning
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#concurrencyMarkdown}}
 
-- **Validation failure:** correct the request; do not retry unchanged.
-- **401 or 403:** repair identity or authority; more retries cannot grant access.
-- **404:** check identifier and visible organization scope before assuming absence.
-- **409:** read current state and resolve the business conflict.
-- **429 or retryable server failure:** follow the documented delay and use
-  bounded backoff.
-- **Timeout or connection loss:** read authoritative state before deciding
-  whether another write is safe.
+Without \`if-match\` the write applies unconditionally, last writer wins. Use the header whenever a person or another integration can touch the same record.
 
-A successful write can still be the wrong business result—for example, it may
-target the wrong organization or apply a broader role than intended. Always
-compare the resulting resource with the approved change, not merely with the
-response schema.
+## Read the refusal
 
-## Protect concurrent work
+A write the application will not perform answers with the standard error envelope. Three cases matter for a writer:
 
-If people or other integrations can change the same record, read-modify-write
-logic needs a conflict strategy. Use the operation's documented version,
-precondition or conflict semantics when available. Otherwise minimize the
-fields written, re-read before overwriting, and route conflicting state for
-review. A blind retry after **409** can erase another actor's valid change.
+| Status | \`error.type\` | What happened | What to do |
+| --- | --- | --- | --- |
+| **400** | \`VALIDATION\` | The body breaks the schema; \`error.validationErrors\` names each field | Fix the request. Resending it unchanged fails again |
+| **409** | \`CONFLICT\` | A stale \`if-match\`, a uniqueness rule, or a state transition the record forbids | Read the record, then decide: merge and resend, or stop because the change no longer applies |
+| **422** | \`BUSINESS_RULE\` | The request is well-formed but a domain rule refuses it; \`error.customMessageReference\` names the rule | Only a different request, or a different state, can succeed |
 
-## Preserve useful evidence
+For example, removing the last owner of an organization answers **409** with \`error.code\` set to \`LAST_ORGANIZATION_OWNER\`: grant owner access to another member first, then retry. The [REST API conventions](/integrations/rest/conventions#errors) page lists every status and error type.
 
-Retain the intended change identity, operation, target scope, attempt number,
-status, stable error code and correlation identifier. Redact credentials,
-personal data and restricted request or response fields. Also retain the
-non-sensitive before/after proof needed to show whether the business change was
-applied, refused or reconciled.
+## Recover from a lost response
 
-The production workflow is ready only when operators can answer: **What did we
-intend, what did the application finally contain, and why was another attempt
-safe or refused?**
+A timeout, a dropped connection or a crash between sending and reading the answer leaves the outcome unknown. Do not resend on reflex; the application may already have applied the change.
 
-## Continue safely
+1. Stop automatic retries for this change.
+2. Read the target record. For a create, search for it by the business key you sent (an email, a reference number, a name).
+3. If the change is there, treat the original attempt as applied and continue.
+4. If it is absent, send it once more. Include the same \`if-match\` value you used the first time when the record existed before; a **409** now means something else changed in between.
+5. If the state is neither what you expected before nor after, hand the item to a person with the request you sent, the record you read and both timestamps.
+
+Operations marked **idempotent** in the API reference can be resent without this procedure. Everything else needs it.
+
+## Bulk changes
+
+Bulk variants (\`…/bulk\` paths) take a list of identifiers and apply one change to each. Read the operation's response schema in the API reference before assuming that every identifier was applied, and after a failure reconcile each identifier individually with a read. Do not resend the whole batch because one item failed.
 
-- [Read collections reliably](/integrations/rest/read-collections) when writes
-  are driven from a collection or need a later reconciliation pass.
-- [Troubleshoot an API request](/integrations/rest/troubleshoot) to classify a
-  refusal, conflict or transport failure without destroying evidence.
-- Return to [REST API](/integrations/rest-api) to review the shared authority and
-  scope boundaries.`,
+## Keep the right evidence
+
+For each change keep the operation path, the identifiers, the \`if-match\` value, the status, \`error.type\` and \`error.code\` when refused, and \`error.correlationId\`. That is enough to answer "what did we intend, what does the application contain, and why was a second attempt safe or refused". Never store the credential or the full request body next to it.`,
     },
     {
         managedPath: 'integrations/rest/troubleshoot.md',
         unitRef: 'technical-documentation:unit/troubleshoot-api-request',
-        sourceRefs: ['saas-technical-doc:engine-content/troubleshoot-api-request'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/troubleshoot-api-request',
+            'source:consumer-fact:access-api-keys',
+            'source:consumer-fact:rest-conventions',
+        ],
         markdown: `# Troubleshoot an API request
 
-Begin with what the application actually returned. Replacing credentials,
-changing organizations and retrying at the same time destroys the evidence that
-would distinguish an authentication problem from an authorization or data
-problem.
+Start from what the application returned: the HTTP status and the error body. Together they name the one boundary that failed. Change one thing, resend, and keep the first failure's evidence until the fix is proven.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Preserve one failed attempt's time, environment, operation, caller reference, organization, status and correlation evidence | The failure is assigned to one boundary, the smallest safe correction is tested, and any uncertain write is reconciled before another attempt |
+## Read the status and the error body
 
-## Keep the original failure intact
+Every failed request answers with the same envelope. The two fields to read first are \`error.type\` and, when present, \`error.code\`:
 
-First copy the non-secret evidence from the failed attempt. Do not rotate the
-credential, alter the request and change the target environment simultaneously.
-Confirm whether the request received an HTTP response at all, then classify the
-first failing boundary.
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#errorEnvelopeMarkdown}}
 
-~~~mermaid
-flowchart TD
-  accTitle: Diagnose an API request without hiding the original failure
-  accDescr: The operator preserves evidence, separates transport from HTTP response, then checks request contract, authentication, authority, visibility, conflict or server failure before applying one bounded correction and re-proving the business result.
-  failure["Preserve one failed attempt"] --> response{"HTTP response received?"}
-  response -->|No| transport["Check environment, DNS, TLS and timeout"]
-  response -->|Yes| class{"Which response class?"}
-  class -->|400| contract["Validate exact operation contract"]
-  class -->|401| identity["Validate credential and environment"]
-  class -->|403 or 404| scope["Validate authority, organization and visibility"]
-  class -->|409| conflict["Read and reconcile current state"]
-  class -->|429 or 5xx| retry["Follow documented delay and safety rule"]
-  transport --> prove["Apply one correction and repeat the proof"]
-  contract --> prove
-  identity --> prove
-  scope --> prove
-  conflict --> prove
-  retry --> prove
-~~~
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#errorStatusMarkdown}}
 
-## Diagnose one boundary at a time
+## No HTTP response at all
 
-| Symptom | Most likely boundary | First checks |
-| --- | --- | --- |
-| No HTTP response | Network, DNS, TLS or server availability | Target environment, resolved host, TLS result and timeout |
-| **400** or validation error | Request does not match the operation contract | Content type, required fields, enum values and parameter placement |
-| **401** | Credential was not accepted | Header transport, expiry, revocation, credential type and environment |
-| **403** | Identity lacks authority for the operation | Active organization, membership, role and operation requirements |
-| **404** | Resource is absent or invisible in this scope | Identifier, organization and resource visibility |
-| **409** | Current state conflicts with the requested transition | Read authoritative state and resolve the business conflict |
-| **429** | Caller exceeded an enforced limit | Stop immediate retries and follow the documented delay |
-| **5xx** | Server could not complete the request | Preserve correlation evidence; retry only when the operation is safe |
+A connection refusal, a DNS failure, a TLS error and a client timeout are different problems, and none of them is an application answer.
 
-## Check the boundaries in order
+- Compare the base URL with the **Servers** list in the API reference; a URL copied from another environment is the usual cause.
+- Test from the network the integration runs on, not only from a laptop.
+- A timeout on a read can be repeated. A timeout on a write is an ambiguous outcome: follow [Recover from a lost response](/integrations/rest/write-and-reconcile#recover-from-a-lost-response) before resending.
 
-### 1. Environment and transport
+## 401: the credential was not accepted
 
-Confirm the server origin belongs to the intended deployment. Preserve the DNS,
-TLS and timeout result. A connection refusal, certificate failure and client
-timeout are different observations even though none returns an application
-status. Do not switch to a different environment merely to obtain a response.
+- The \`Authorization\` header must carry the whole key, with no \`Bearer\` prefix in front of an API key and no key inside a URL or a cookie. {{CONSUMER_FACT:source:consumer-fact:access-api-keys#markdown}}
+- Check the key's status in the application: an \`inactive\` or \`expired\` key is refused. [API key lifecycle](/access-and-identity/api-keys-lifecycle) explains each status.
+- Check the environment: a key minted in one environment does not work in another.
 
-### 2. Request contract
+Do not fix a 401 by borrowing an administrator's key. That hides the defect and widens what the integration can do.
 
-Compare the method, content type, parameters, body and enum values with the
-exact operation in the API reference. Validate the request before sending it
-again. Do not remove unknown fields one at a time in production; build a minimal
-schema-valid reproduction in a safe organization.
+## 403: valid credential, refused operation
 
-### 3. Credential and identity
+The application knows who is calling and refuses this operation in this scope.
 
-For **401**, confirm the header scheme, credential type, expiry or revocation
-state, and that the credential belongs to this environment. Do not test by
-substituting an administrator's credential: that hides the workload identity
-defect and expands the blast radius.
+- Compare the roles on the key with the roles the operation lists in the API reference.
+- A collection under an organization the key is not a member of is refused with 403; confirm the organization identifier.
+- \`FEATURE_NOT_AVAILABLE\` and \`FEATURE_LIMIT_EXCEEDED\` are plan refusals, not role refusals; see [Plans and access](/billing-and-subscriptions/plans-and-access).
 
-### 4. Authority and visibility
+## 404: the record is not visible here
 
-For **403**, the identity is known but cannot perform this operation in this
-scope. Confirm active organization membership, role and operation authority.
-For **404**, confirm the identifier and organization visibility before deciding
-the record does not exist; an inaccessible record can intentionally be
-indistinguishable from a missing one.
+Either the identifier is wrong or the record belongs to an organization this key cannot see. The application does not distinguish the two on purpose. Copy the identifier from the application again and confirm the organization in the path.
 
-### 5. Current state and retry safety
+## 409 and 422: the current state refuses the change
 
-For **409**, read the resource and resolve the conflicting state. For **429**,
-honour the documented delay and stop parallel callers from immediately filling
-the same limit again. For **5xx** or transport loss, determine whether the
-operation is safe to repeat. A read can usually be repeated; a write first needs
-authoritative reconciliation.
+Read the record, then read \`error.code\` and \`error.customMessageReference\`. A stale \`if-match\` carries \`error.details.versionConflict\` with the current version. [Write and reconcile changes](/integrations/rest/write-and-reconcile) shows what to do for each case.
 
-## Build a safe investigation record
+## 429: too many requests
 
-Capture the time, environment, operation identity, caller identity reference,
-organization, status, stable error code and correlation identifier. Replace
-payload values with a minimal redacted reproduction. Never paste an API key,
-Bearer token or unrestricted personal data into a ticket.
+{{CONSUMER_FACT:source:consumer-fact:rest-conventions#rateLimitMarkdown}}
 
-For a write with no response, investigate the authoritative resource before
-repeating it. The absence of a client response is an **ambiguous outcome**, not
-an automatic retry instruction.
+Wait the full \`Retry-After\`, then resume where you stopped. If several workers share one key they share its counters; spread the load or use one key per worker.
 
-## Prove the repair
+## 5xx: the application failed
 
-Repeat the smallest safe request with one change only. Confirm the expected
-success and one expected refusal, then verify the business result in the
-intended organization. If the correction involved a credential or permission,
-also confirm that access outside the approved scope remains refused.
+Keep \`error.correlationId\`, the operation path and the time. Reads can be retried with a short back-off. For a write, read the record before resending.
 
-Escalate with the redacted investigation record, the exact operation reference,
-the correlation identifier and what authoritative state currently shows. State
-whether a write may already have applied. That gives support enough context to
-investigate without asking for credentials or a full personal-data payload.
+## Prove the fix
 
-## Continue safely
+Resend the smallest request with exactly one change. Then run the two negative checks from [Send your first API request](/integrations/rest/send-request#step-3-prove-the-boundary-holds) again: a wrong key is still refused, and another organization is still invisible. A fix that opened the boundary is not a fix.
 
-- [Send your first API request](/integrations/rest/send-request) to rebuild the
-  connection proof from a harmless read.
-- [Write and reconcile changes](/integrations/rest/write-and-reconcile) before
-  retrying a mutation with an uncertain outcome.
-- Return to [REST API](/integrations/rest-api) to review the four shared
-  integration boundaries.`,
+## Ask for help with the right evidence
+
+Quote the operation path, the HTTP status, \`error.type\`, \`error.code\`, \`error.correlationId\` and the timestamp. Say whether a write may already have applied. Never paste the key, a bearer token or a full response body.`,
     },
     {
         managedPath: 'integrations/webhooks.md',
         unitRef: 'technical-documentation:unit/webhooks',
-        sourceRefs: ['saas-technical-doc:engine-content/webhooks'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/webhooks',
+            'source:companion-projection:application-integration',
+            'source:consumer-fact:outbound-webhooks',
+        ],
         markdown: `# Webhooks
 
-Use a webhook when another system should react after this application publishes
-an event. The application sends a signed HTTP request to your receiver. Your
-receiver decides whether the request is authentic, applies the business effect
-once and returns an HTTP result.
+A webhook lets the application call your system when something happens, instead of your system polling for it. Each event becomes one signed \`POST\` to every enabled endpoint you configured. Your receiver verifies the signature, records the delivery once, answers quickly, and does the real work afterwards.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Know which published event starts the work, who owns the receiving system, where its public HTTPS endpoint runs and how duplicate work will be prevented | Authentic deliveries are accepted quickly, each event produces the business effect at most once, and failed or ambiguous work can be reconciled |
+## What the application sends
 
-## Decide whether an event should drive the work
+- **One \`POST\` per event per endpoint.** The body is the same JSON the operation that fired the event returns to an API caller, so the record you receive has the shape documented for that operation in the [API reference](/api).
+- **A signature in every request.** {{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#signatureMarkdown}}
+- **Retries on your behalf.** {{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#retryMarkdown}}
 
-| Situation | Better starting point | Reason |
-| --- | --- | --- |
-| Another system must react soon after a published event | Webhook | The application initiates a delivery instead of making the receiver poll |
-| Another system needs the current state now | [REST API](/integrations/rest-api) | A request retrieves authoritative state at the moment it is needed |
-| The receiver must recover after missing or delaying an event | Webhook plus REST reconciliation | The event starts the work; an authoritative read confirms the final state |
-| No published event represents the business change | REST or a different supported integration | A webhook endpoint cannot invent application events |
-
-A webhook is a **notification**, not a remote command and not a permanent copy
-of application state. Design the receiver so the event starts bounded work and
-the application remains the authority for facts that can change afterwards.
-
-## Understand the records involved
-
-- An **endpoint** identifies the receiver, its enabled state and the events it
-  is configured to receive.
-- An **event** is the notification payload produced by one application
-  operation. One notification can create a separate delivery for each matching
-  endpoint.
-- A **delivery** tracks that notification for one endpoint and carries the
-  signed identity the receiver uses for deduplication.
-- A **delivery attempt** records one HTTP exchange and its result. Retries are
-  additional attempts for the same delivery, not new business events.
-
-This distinction is why the receiver deduplicates with the signed delivery
-identity and why operators investigate delivery state separately from the
-downstream business effect.
+## The events this application publishes
 
-~~~mermaid
-sequenceDiagram
-  accTitle: Receive and apply a webhook delivery safely
-  accDescr: The application signs the raw body and sends it to the receiver. The receiver verifies the token and body hash, atomically deduplicates the delivery identifier, queues the business work, and returns a success response.
-  participant App as Application
-  participant Receiver as Your receiver
-  participant Store as Deduplication store
-  participant Worker as Your worker
-  App->>Receiver: POST raw body plus signature
-  Receiver->>Receiver: Verify ES256 token, claims, expiry and raw-body SHA-256
-  Receiver->>Store: Atomically claim signed delivery identifier jti
-  Store-->>Receiver: New or already processed
-  Receiver->>Worker: Queue new business work
-  Receiver-->>App: 2xx after safe acceptance
-~~~
+{{APPLICATION_INTEGRATION:webhookEvents}}
+
+## What you configure
 
-The receiver must verify before trusting or parsing the event. A success
-response means the application observed a 2xx response; it does not independently
-prove what checks your receiver performed.
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#endpointMarkdown}}
 
-## Split responsibilities deliberately
+Which operations fire an event is decided by the application, per resource and operation; the \`resourceIdentifier\` and \`operationIdentifier\` claims on each delivery tell you which one did. There is one configuration per organization, managed by organization administrators, and one for the application as a whole, managed by application administrators.
 
-| Application sends | Receiver must do |
+## What your receiver must do
+
+| Step | Why it cannot be skipped |
 | --- | --- |
-| Signed raw payload and delivery identity | Verify the signature and body hash before trusting fields |
-| Delivery attempts with bounded retry behavior | Atomically recognize a previously accepted delivery |
-| HTTP result and limited response evidence | Return quickly after durable acceptance and process longer work asynchronously |
-| Delivery status for operations | Reconcile the downstream business effect after ambiguous processing |
-
-Do not acknowledge before the delivery is durably safe to process. Do not keep
-the application connection open while performing a long external workflow.
-Durable queueing between those two moments makes fast acknowledgement and safe
-recovery compatible.
-
-## Follow the journey
-
-- [Configure and test an endpoint](/integrations/webhooks/configure-and-test)
-  before enabling production delivery.
-- [Verify a webhook delivery](/integrations/webhooks/verify-delivery) using the
-  raw bytes, public key and signed claims.
-- [Operate webhook deliveries](/integrations/webhooks/operate-deliveries) with
-  fast acknowledgement, durable work and reconciliation.
-- [Troubleshoot webhook deliveries](/integrations/webhooks/troubleshoot) from
-  delivery state and response meaning.
-
-The event and API references remain authoritative for the exact events,
-payloads and configuration operations exposed by this application. Before
-production, prove a valid delivery, an invalid signature, a duplicate delivery,
-a receiver timeout and recovery from a failed downstream effect.`,
+| Keep the raw request bytes | The signature covers the exact bytes; a JSON parser that reformats them breaks the check |
+| Verify the token and the body hash before reading the body | Anything before verification is an unauthenticated write into your system |
+| Claim \`jti\` atomically before doing work | Retries carry the same \`jti\`; two concurrent attempts must produce one effect |
+| Answer within the timeout, then do the work | A slow receiver is retried, then marked failed, while the work may have half-run |
+| Reconcile against the application for anything money- or access-related | A \`delivered\` row proves a 2xx, not that your worker finished |
+
+## The four pages of this section
+
+1. [Configure and test an endpoint](/integrations/webhooks/configure-and-test): register a receiver, run the built-in test, enable it.
+2. [Verify a webhook delivery](/integrations/webhooks/verify-delivery): the signature, the claims and a working receiver in Node.js.
+3. [Operate webhook deliveries](/integrations/webhooks/operate-deliveries): delivery statuses, the retry ladder, monitoring and manual retry.
+4. [Troubleshoot webhook deliveries](/integrations/webhooks/troubleshoot): from a failed or missing delivery to the boundary that broke.`,
     },
     {
         managedPath: 'integrations/webhooks/configure-and-test.md',
         unitRef: 'technical-documentation:unit/configure-and-test-webhook-endpoint',
-        sourceRefs: ['saas-technical-doc:engine-content/configure-and-test-webhook-endpoint'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/configure-and-test-webhook-endpoint',
+            'source:consumer-fact:outbound-webhooks',
+        ],
         markdown: `# Configure and test a webhook endpoint
 
-Create a receiver that is publicly reachable, preserves the raw request body
-and can return quickly. Use HTTPS for production. The endpoint URL must not
-contain embedded credentials, and the application does not follow redirects.
-
-This task is for the administrator who controls the application endpoint and
-the engineer who controls the receiving service. Complete it together: a green
-HTTP result proves reachability, while the receiver's own evidence proves that
-it verified the signed request before acknowledging it.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Choose one organization or application scope, one final HTTPS receiver URL, one published event and an owner for receiver incidents; prepare signature verification, deduplication and durable queueing | A disabled endpoint accepts a signed synthetic test, rejects an invalid request, then processes one controlled real event exactly once after staged enablement |
-
-## Choose the endpoint boundary
+Register the receiver disabled, prove it with the built-in test, then enable it. This page is shared by the administrator who owns the application's webhook settings and the engineer who owns the receiver; each has half of the evidence.
 
-Create a separate endpoint for each receiver lifecycle that needs independent
-enablement, ownership or recovery. Give it a description that identifies the
-receiving system and environment without putting credentials or personal data
-in the label. The stored endpoint identifier remains the correlation point for
-delivery history even if its URL changes later.
+## Before you register
 
-Keep test and production receivers separate. Confirm that the URL is the final
-route that handles the request: **3xx redirects are terminal failures**, so a
-login redirect, HTTP-to-HTTPS redirect or trailing-slash rewrite prevents a
-successful delivery.
+The receiver must:
 
-## Prepare the receiver
+- be reachable from the internet over HTTPS at its final URL. The application does not follow redirects, so an HTTP-to-HTTPS redirect, a login page or a trailing-slash rewrite ends every delivery as failed;
+- not carry credentials in the URL and not resolve to a private or loopback address; such URLs are refused with the \`not_sent\` outcome;
+- keep the raw request bytes, read the signature from the header and verify it before parsing. [Verify a webhook delivery](/integrations/webhooks/verify-delivery) has a complete receiver you can start from;
+- store the delivery identifier \`jti\` before doing any work, so a retry cannot repeat the work.
 
-Before adding the endpoint:
+## Register the endpoint
 
-- accept the documented POST content type and retain the exact body bytes;
-- read the signature from **x-wildo-webhook-signature**;
-- load the application's published webhook verification key through the
-  documented configuration surface;
-- implement atomic deduplication using the signed delivery identifier;
-- queue longer business work instead of performing it before responding;
-- return a small, non-sensitive response body.
+1. Open the webhook settings of the organization (or of the application, for application-wide events).
+2. Copy \`applicationPublicKeyPem\` from the configuration into your receiver's secret store. This is the key that verifies every signature.
+3. Add an endpoint with the final HTTPS URL and a description that names the receiving system and environment. Leave it **disabled**.
+4. Save. The endpoint's \`id\` is the identifier every delivery of it will carry; note it.
 
-~~~mermaid
-sequenceDiagram
-  accTitle: Prove a webhook endpoint before production traffic is enabled
-  accDescr: An administrator registers a disabled final URL and sends a synthetic signed test. The receiver verifies and deduplicates it, durably accepts the test, responds quickly, and exposes non-secret evidence that the administrator checks before enabling a controlled real event.
-  participant Admin as Application administrator
-  participant App as Application
-  participant Receiver as Your receiver
-  participant Queue as Durable queue
-  Admin->>App: Save disabled final HTTPS endpoint
-  Admin->>App: Send endpoint test
-  App->>Receiver: Signed synthetic request
-  Receiver->>Receiver: Verify raw bytes, signature and synthetic claim
-  Receiver->>Queue: Record safe acceptance
-  Receiver-->>App: 2xx with small response
-  App-->>Admin: Accepted plus correlation evidence
-  Admin->>Receiver: Confirm verification and queue evidence
-  Admin->>App: Enable and trigger one controlled real event
-~~~
-
-The important handoff is between the application outcome and the receiver
-evidence. **Accepted** means a 2xx was observed; it cannot prove which checks the
-receiver performed internally.
-
-## Register the endpoint safely
-
-1. Select the intended organization or application scope. Do not reuse an
-   endpoint configured for another tenant or environment.
-2. Save the final HTTPS URL, a recognizable description and the endpoint in a
-   disabled state. A disabled endpoint can still be tested deliberately.
-3. Read the published verification key through the documented application
-   configuration surface and pin the expected application environment in the
-   receiver.
-4. Confirm the receiver preserves the raw request bytes before any JSON parser,
-   proxy rewrite or middleware normalization.
-5. Prepare a durable deduplication record keyed by the signed delivery identity
-   and a queue for work that should continue after the response.
-
-## Test before enabling delivery
-
-The endpoint test uses the same signing and transport path as a real delivery.
-It can test a disabled endpoint with a synthetic signed payload and does not
-create a normal delivery-log row.
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#endpointMarkdown}}
 
-Interpret the test outcome precisely:
+The same operations are available to automation through the organization webhook configuration in the [API reference](/api); the endpoint test is its own operation there.
 
-| Outcome | Meaning | Next action |
-| --- | --- | --- |
-| **Accepted** | Receiver returned a 2xx response | Confirm receiver logs prove signature and body verification occurred before the response |
-| **Rejected** | Receiver returned a non-2xx HTTP response | Inspect receiver validation and response status |
-| **Unreachable** | No HTTP response was obtained | Check public reachability, DNS, TLS and receiver timeout |
-| **Not sent** | Local signing or configuration prevented the request | Correct application configuration before testing the receiver |
-
-Redirect responses are terminal configuration failures. Update the endpoint to
-the final receiver URL rather than relying on a 3xx hop.
-
-The synthetic request carries a signed indication that it is a test. Do not
-turn it into a real order, notification or account change. Retain its signed
-delivery identity long enough to prove that a duplicate test would not repeat
-the business effect.
+## Run the endpoint test
 
-Run four checks before enablement:
+The test sends one synthetic, signed request through the same signing and transport path as a real delivery, to the endpoint you choose, even while it is disabled. It does not create a delivery record. Read the outcome precisely:
 
-- a valid signed test is durably accepted and answered with 2xx;
-- a request with a missing or invalid signature is rejected before parsing or
-  business processing;
-- a repeated signed delivery identity does not enqueue a second effect;
-- a receiver delay or outage produces a non-success outcome that operators can
-  locate in both systems.
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#testOutcomesMarkdown}}
 
-## Enable in stages
+The synthetic request is recognisable from its signed claims: \`synthetic\` is \`true\` and \`operationIdentifier\` is \`testEndpoint\`. Your receiver must verify it like any other request and must not turn it into a business effect; branch on those claims, never on the body text.
 
-Enable one endpoint in a non-production organization, trigger one known event
-and verify the complete receiver path. Only then enable broader traffic. Retain
-the endpoint identity, test time and outcome without retaining the signature or
-synthetic payload unnecessarily.
+Before enabling, make the receiver pass four cases:
 
-For the first real event, confirm all of the following:
+- the test is \`accepted\`, and the receiver's own log shows verification ran before it answered;
+- a request with a missing or altered signature is refused before the body is parsed;
+- the same \`jti\` sent twice produces one effect;
+- a receiver that answers slowly produces \`unreachable\`, and both teams can find that attempt.
 
-1. the delivery belongs to the intended scope and published event;
-2. signature and raw-body integrity checks ran before the payload was trusted;
-3. the signed delivery identity was claimed exactly once;
-4. the application recorded a successful delivery attempt;
-5. the queued worker produced the intended downstream business result.
+## Enable and confirm the first real event
 
-If any check fails, disable the endpoint while preserving the test and delivery
-evidence. Correct the failed boundary, test again while disabled, and repeat one
-controlled event before restoring ordinary traffic.
+Enable the endpoint, trigger one event you can recognise (for example, invite a test member), and follow it end to end: the delivery row shows \`delivered\`, the receiver logged the \`jti\`, and the downstream result exists. Only then let ordinary traffic flow.
 
-## Retain safe operating evidence
+If any step fails, disable the endpoint, keep the delivery and test evidence, fix the one boundary that failed, and repeat the test before re-enabling.
 
-Keep the endpoint's non-secret identifier and description, scope, destination
-host, test time, outcome, HTTP status, duration and signed delivery identifier
-used for correlation. Do not retain the signature token, verification private
-material, unrestricted payload or sensitive receiver response in an ordinary
-ticket.
-
-## Continue safely
+## Change an endpoint later
 
-- [Verify a webhook delivery](/integrations/webhooks/verify-delivery) for the
-  complete receiver-side trust boundary.
-- [Operate webhook deliveries](/integrations/webhooks/operate-deliveries) before
-  enabling production volume or automatic recovery.
-- [Troubleshoot webhook deliveries](/integrations/webhooks/troubleshoot) when a
-  test or controlled event does not complete.`,
+Changing the URL affects future deliveries only; past delivery rows keep the URL they were sent to. After a URL or receiver deployment change, run the test again and follow one real event before trusting it. Disabling an endpoint stops new deliveries to it; it does not cancel work your receiver already accepted.`,
     },
     {
         managedPath: 'integrations/webhooks/verify-delivery.md',
         unitRef: 'technical-documentation:unit/verify-webhook-delivery',
-        sourceRefs: ['saas-technical-doc:engine-content/verify-webhook-delivery'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/verify-webhook-delivery',
+            'source:consumer-fact:outbound-webhooks',
+        ],
         markdown: `# Verify a webhook delivery
 
-Treat every incoming request as untrusted until both the signature token and
-the exact body bytes have been verified. Parse JSON only after this boundary.
-
-The signature answers **who signed these exact bytes, for which delivery and
-context, and for how long the claim is valid**. It does not decide whether your
-business process should act on the event. Keep cryptographic verification,
-deduplication, payload validation and business authorization as separate checks.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Load the verification key from the intended application environment, preserve the raw request bytes, define the expected audience and event route, and prepare an atomic store for signed delivery identities | A valid request is trusted and queued once; invalid signatures, changed bytes, unexpected claims, expired tokens and duplicate delivery identities cannot create a business effect |
-
-## Preserve the bytes before parsing
+Treat every incoming request as untrusted until the signature and the exact body bytes are verified, then deduplicate on the delivery identifier, and only then parse the body. This page gives the contract and a receiver you can run.
 
-Many web servers parse JSON automatically. Configure the webhook route to retain
-the exact byte sequence received on the wire before that parser runs. Changing
-whitespace, character encoding or field order and then serializing the object
-again produces different bytes and must fail the body-hash check.
+## The signature
 
-Read the signature only from **x-wildo-webhook-signature**. Reject a missing or
-duplicated value according to your HTTP framework's safe header handling; never
-accept a signature copied into the body or query string.
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#signatureMarkdown}}
 
-## Verification sequence
+A decoded token payload looks like this:
 
-1. Read **x-wildo-webhook-signature** and reject a missing or malformed value.
-2. Verify the token with the application's published webhook public key.
-3. Pin **ES256** and validate the expected issuer, audience, key identifier,
-   issued time and expiry. Allow only a small, deliberate clock tolerance.
-4. Compute SHA-256 over the **raw request bytes** and compare it with the signed
-   body hash using a constant-time comparison.
-5. Validate the signed event channel, resource and operation claims against the
-   receiver route you expected.
-6. Atomically claim the signed **jti** before applying a business effect.
-7. Parse and validate the JSON payload against the published event contract.
-
-~~~mermaid
-flowchart TD
-  accTitle: Reject a webhook until identity, integrity and replay checks pass
-  accDescr: The receiver validates the signature token, recomputes the raw-body hash, checks expected event claims, and atomically claims the jti before parsing and processing the payload.
-  request["Incoming request"] --> token{"Token valid and expected?"}
-  token -->|No| reject["Reject without processing"]
-  token -->|Yes| hash{"Raw-body SHA-256 matches?"}
-  hash -->|No| reject
-  hash -->|Yes| claims{"Event claims expected?"}
-  claims -->|No| reject
-  claims -->|Yes| dedup{"jti claimed atomically?"}
-  dedup -->|Already seen| acknowledge["Return the established duplicate outcome"]
-  dedup -->|New| parse["Parse, validate and queue work"]
+~~~json
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#claimsExampleJson}}
 ~~~
 
-## Know what each signed value proves
+The endpoint test adds \`"synthetic": true\` and sets \`operationIdentifier\` to \`testEndpoint\`; treat such a delivery as verified but never act on it.
 
-| Value | Receiver decision |
-| --- | --- |
-| Signature, algorithm and key identifier | The token was produced by the expected application signing key under the pinned **ES256** algorithm |
-| Issuer and audience | The token belongs to the expected application trust boundary and this receiver purpose |
-| Issued time and expiry | The attempt is within the deliberately accepted time window |
-| Body hash and hash algorithm | The raw bytes received are the bytes that were signed for this attempt |
-| Event channel, resource and operation | The notification belongs on the receiver route and handler selected for it |
-| **jti** | This delivery identity has or has not already been accepted by the receiver |
+## The verification sequence
+
+1. Read the signature header. No header, or more than one, is a refusal.
+2. Verify the token with \`applicationPublicKeyPem\` from the webhook configuration, pinning the algorithm, the issuer and the audience above. Let your JWT library check \`exp\` and \`iat\`; allow a few seconds of clock tolerance, not minutes.
+3. Hash the raw request bytes with the algorithm in \`bodyHashAlg\` and compare the hex digest with \`bodyHash\` using a constant-time comparison.
+4. Claim \`jti\` in your durable store atomically with recording the work. A second request with the same \`jti\` is a retry: answer 2xx and do nothing.
+5. Parse the body and hand it to a queue. Answer the application before the work runs.
 
-Validate all required claims as one policy. A correctly signed token for another
-environment, audience or event handler is still unacceptable here.
+Refuse with a plain non-2xx status and no explanation of which check failed. Log the time, the route, the reason category and the \`jti\`; never the token or the body.
 
-The body hash identifies bytes; it is not the delivery identity. The token
-string can also change across contexts. Use **jti** as the deduplication key for
-the same delivery and keep that claim stable for every retry of its delivery row.
+## A receiver in Node.js
 
-Claim **jti** atomically in the same acceptance boundary that records or queues
-the work. A separate “check then insert” sequence allows two concurrent attempts
-to pass before either writes the record. Retain the claim for at least as long
-as the delivery can be retried or manually replayed under your operating policy.
+Express and the \`jsonwebtoken\` package, with the raw body preserved:
 
-## Reject without creating a second vulnerability
+~~~javascript
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#verifierSampleNode}}
+~~~
 
-Return a generic non-2xx response for invalid signature, hash or claims. Do not
-explain which cryptographic comparison failed to an unauthenticated caller, and
-do not log the complete token or sensitive body. Retain the time, destination
-route, reason category and non-secret correlation evidence needed for support.
+\`claimDeliveryOnce\` must be an atomic insert keyed by \`jti\` in the store that also records the work, such as a unique index in a database table, so two concurrent attempts cannot both pass. \`enqueue\` hands the event to a worker; the response must not wait for the worker.
 
-For a duplicate **jti**, return the stable outcome your receiver design has
-chosen without applying the business effect again. If the first acceptance is
-still processing, the duplicate must not start parallel work.
+Any language works the same way: an ES256 JWT verifier with issuer and audience pinned, a SHA-256 over the raw bytes, and a unique key on \`jti\`.
 
-## Handle key and deployment changes deliberately
+## Route by claims, not by body
 
-When verification starts failing after a deployment or key change, compare the
-token's key identifier, issuer and audience with the verification key loaded
-from the same application environment. Refresh through the documented key
-surface; never fetch a key from an untrusted location supplied by the incoming
-request. Keep the previous accepted key only when the application's published
-rotation contract explicitly requires an overlap.
+Every enabled endpoint receives every event on its channel. Use the \`resourceIdentifier\` and \`operationIdentifier\` claims to decide which handler runs or whether to ignore the event, before you parse the body. The body is the operation's response document as described in the [API reference](/api) for that resource.
 
-Test verification with controlled cases:
+## Prove it before production
 
-- one valid signed delivery reaches the durable queue;
-- one changed raw byte is rejected;
-- one expired or wrong-audience token is rejected;
-- one unexpected event claim is rejected by the route;
-- the same **jti** received concurrently produces one accepted business effect.
+Run these five cases against the receiver and keep the results with the endpoint's \`id\`:
 
-Do not weaken algorithm checks, skip expiry or parse and reserialize JSON to
-repair a verification failure. Those changes remove the security boundary
-rather than diagnosing it.
+- a valid delivery reaches the queue and is answered 2xx within a second;
+- one changed byte in the body is refused;
+- a token with the wrong audience or an expired \`exp\` is refused;
+- the same \`jti\` delivered twice, concurrently, produces one queued job;
+- the endpoint test from the application is \`accepted\` and is not acted on.
 
-## Continue safely
+## When keys or deployments change
 
-- [Configure and test an endpoint](/integrations/webhooks/configure-and-test)
-  before enabling a receiver that has not passed the negative cases.
-- [Operate webhook deliveries](/integrations/webhooks/operate-deliveries) to
-  separate verified acceptance from longer business work.
-- [Troubleshoot webhook deliveries](/integrations/webhooks/troubleshoot) when
-  the application and receiver disagree about the result.`,
+The application's webhook key is the one on the configuration. The token header's \`kid\` is the thumbprint of that key, not a fixed name: a \`kid\` you have not seen means the key rotated, and the remedy is to reload \`applicationPublicKeyPem\` from the configuration. If verification still fails, confirm \`iss\` and \`aud\` match what your receiver pins. Never disable verification, accept every algorithm, or re-serialise the JSON to make a failing check pass.`,
     },
     {
         managedPath: 'integrations/webhooks/operate-deliveries.md',
         unitRef: 'technical-documentation:unit/operate-webhook-deliveries',
-        sourceRefs: ['saas-technical-doc:engine-content/operate-webhook-deliveries'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/operate-webhook-deliveries',
+            'source:consumer-fact:outbound-webhooks',
+        ],
         markdown: `# Operate webhook deliveries
 
-Webhook delivery is asynchronous. The application creates one durable delivery
-row for each enabled endpoint, attempts the request and records the outcome.
-Your receiver should likewise separate safe acceptance from longer business
-processing.
+Delivery is asynchronous. For every event the application creates one delivery row per enabled endpoint, attempts the request, and records what came back. Operating webhooks means reading those rows correctly and keeping your receiver's side honest.
 
-Operating webhooks therefore means reconciling **two lifecycles**: delivery from
-the application to your receiver, and the business work performed after your
-receiver accepts it. A green delivery does not automatically prove the second
-lifecycle completed.
+## Delivery statuses
 
-| Before you begin | Successful result |
-| --- | --- |
-| Assign an owner for the endpoint and receiver queue; define deduplication retention, alert thresholds, downstream reconciliation and the conditions for an explicit retry | Operators can distinguish waiting, active, delivered and terminally failed rows, recover without duplicate effects, and prove the downstream business result separately from HTTP delivery |
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#deliveryStatesMarkdown}}
 
-## Understand the delivery states
+The delivery log is a resource in the [API reference](/api): list it, search it by status, read one row, or retry a failed one. Each row carries the endpoint \`id\`, the \`httpUrl\` it was sent to, \`attemptCount\`, \`nextAttemptAt\`, the last \`responseStatus\`, the first kilobytes of the response body, a \`failureReason\` when terminal, and \`signatureJti\`, which is the \`jti\` your receiver stored.
 
-~~~mermaid
-stateDiagram-v2
-  accTitle: Webhook delivery lifecycle
-  accDescr: A pending delivery becomes in flight. A successful 2xx response marks it delivered. A transient failure schedules another pending attempt, while a terminal failure marks it failed. An administrator can explicitly retry a failed delivery.
-  [*] --> Pending
-  Pending --> InFlight
-  InFlight --> Delivered: 2xx response
-  InFlight --> Pending: transient failure and attempts remain
-  InFlight --> Failed: terminal failure or attempts exhausted
-  Failed --> Pending: explicit retry
-  Delivered --> [*]
-~~~
+## The retry ladder
 
-Read each state as an operating instruction:
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#retryMarkdown}}
 
-| State | What it means | What an operator should do |
-| --- | --- | --- |
-| **Pending** | The row is waiting for its first attempt or a scheduled retry | Compare the next-attempt time with the retry schedule; do not start a parallel manual sender |
-| **In flight** | One worker currently holds the delivery for an HTTP attempt | Allow the bounded request to complete; investigate only if the state remains inconsistent with worker health |
-| **Delivered** | The application observed a 2xx response | Confirm the receiver accepted this **jti** durably, then reconcile the downstream result |
-| **Failed** | A terminal response occurred or the attempt budget was exhausted | Correct the failed boundary, prove deduplication, then decide whether an explicit retry is safe |
-
-Transient failures include network failure, timeout, 408, 429 and 5xx. Delivery
-uses at most five attempts with delays of approximately one minute, five
-minutes, thirty minutes and two hours. Each request has a thirty-second timeout.
-Redirects and other terminal 4xx responses are not retried automatically.
-
-That schedule belongs to the application delivery row. Do not add an immediate
-parallel retry loop at the receiver or an external monitor: it defeats the
-bounded delay, increases load during an outage and can race the same business
-effect.
+The ladder belongs to the application. Do not add your own immediate retry loop on the receiver side or from a monitor: it defeats the back-off, multiplies load during an outage, and races the same \`jti\`.
 
 ## Design the receiver for retries
 
-- Claim the signed **jti** atomically before creating the business effect.
-- Return 2xx only after the request is verified and safely accepted.
-- Move slow work to a durable queue.
-- Make downstream processing idempotent as a second line of protection.
-- Reconcile the receiver's accepted deliveries with resulting business records.
+- Claim \`jti\` atomically before any effect; the same \`jti\` returns on every retry of one delivery.
+- Answer 2xx only after the request is verified and durably queued, and answer well inside the timeout.
+- Do the work in a worker, idempotently, as a second line of defence.
+- Return a short, non-sensitive body; it is recorded on the delivery row and read by operators.
 
-The application records only a bounded response body, currently up to 4 KiB.
-Return a short diagnostic that contains no credential, personal data or internal
-stack trace. A delivery marked **Delivered** means a 2xx was observed; it does
-not prove that your asynchronous business work later completed.
+A \`delivered\` row proves that your receiver answered 2xx. It cannot see whether your worker finished. For anything that moves money or access, reconcile your side against the application with a read.
 
-## Monitor both sides of acceptance
+## Monitor
 
-For the application delivery lifecycle, monitor:
+On the application side, watch:
 
-- pending age and whether the next-attempt time continues to advance;
-- terminal failures by endpoint and response class;
-- a sudden increase in 408, 429 or 5xx outcomes;
-- the attempt count approaching the five-attempt limit;
+- \`pending\` rows whose \`nextAttemptAt\` is in the past for longer than a minute: the worker is not draining;
+- \`failed\` rows by endpoint and \`responseStatus\`: a burst of one status names one broken boundary;
+- \`attemptCount\` reaching 4 on many rows: the receiver is slow or flapping;
 - endpoint changes around the first failure time.
 
-For the receiver lifecycle, monitor:
-
-- signature or body-integrity rejection by reason category;
-- duplicate **jti** claims and whether the existing work is complete;
-- queue age, failed worker jobs and downstream dependency health;
-- accepted deliveries that have no resulting business record;
-- repeated business records that indicate a broken atomic deduplication boundary.
-
-Use the delivery identifier, endpoint identifier, signed **jti**, event context
-and timestamps to join the two views. Do not use the payload body or signature
-token as a monitoring label.
-
-## Retry deliberately
-
-An explicit retry resets a failed delivery for a fresh attempt. Before using it,
-confirm that the receiver will recognize the same **jti** and that the earlier
-attempt did not already create the business effect.
-
-Use this decision sequence:
-
-1. Read the failed delivery's endpoint snapshot, event context, attempt count,
-   response status and failure reason.
-2. Check the receiver using **jti**. Determine whether it never received the
-   request, rejected it, accepted it without completing work, or completed the
-   business effect despite a lost response.
-3. Correct the actual cause. For a terminal 3xx or 4xx, test the final route or
-   verification repair before retrying real traffic.
-4. Confirm that deduplication retention still covers the original **jti** and
-   that downstream processing is safe to resume.
-5. Retry one row. Observe the resulting application state and receiver queue
-   before retrying a group of failures.
-6. Reconcile the authoritative downstream record and close the incident with
-   both delivery and business evidence.
+On the receiver side, watch signature rejections by reason, duplicate \`jti\` claims, queue age and jobs with no downstream record. Join the two views on the endpoint \`id\`, \`signatureJti\` and the timestamps; never on the body.
 
-If the receiver already completed the business effect, do not retry merely to
-turn the delivery row green. Record the mismatch and reconcile it through the
-appropriate operating process.
+## Retry a failed delivery
 
-## Treat endpoint changes as new operating risk
+The retry operation re-queues one \`failed\` row for a fresh attempt with the same \`jti\` and the same body. Before using it:
 
-Changing an endpoint URL affects future delivery attempts, while historical
-rows retain the destination snapshot used when they were created. After a URL
-or receiver deployment change, test the configured endpoint, trigger one
-controlled event and monitor both delivery and downstream completion before
-restoring ordinary volume.
+1. Read the row: \`httpUrl\`, \`attemptCount\`, \`responseStatus\`, \`failureReason\`.
+2. Search your receiver's store for the \`jti\`. Decide whether the receiver never saw it, refused it, accepted it without finishing, or finished the work despite a lost response.
+3. Fix the cause. For a **3xx** or a **4xx** other than 408 and 429, the same bytes would be refused again, so test the endpoint first.
+4. Retry one row and watch it become \`delivered\`, then retry the rest.
 
-Disable an endpoint when the receiver cannot safely accept traffic. Disabling
-stops new matching deliveries from being created for that destination; it is
-not proof that existing downstream work has been cancelled or reconciled.
+If the receiver already did the work, do not retry to turn the row green; record the mismatch and reconcile through your own process.
 
-## Retain evidence without retaining secrets
+## Endpoint changes and outages
 
-Keep the scope, endpoint and delivery identifiers, **jti**, event context,
-attempt count, state transitions, response status, bounded non-sensitive
-diagnostic and downstream reconciliation result. Apply the organization's
-retention and access policy to payloads because delivery records can contain
-business or personal data.
+A URL change affects future deliveries; existing rows keep the \`httpUrl\` they were created with. After any change to the URL or the receiver deployment, run the endpoint test and follow one real event. When the receiver cannot safely accept traffic, disable the endpoint: no new rows are created for it, and rows already \`pending\` keep retrying until they succeed or run out of attempts.
 
-## Continue safely
+## Retention
 
-- [Troubleshoot webhook deliveries](/integrations/webhooks/troubleshoot) to
-  locate the failed boundary before an explicit retry.
-- [Verify a webhook delivery](/integrations/webhooks/verify-delivery) when
-  signature, raw-body or duplicate handling is in doubt.
-- Return to [Webhooks](/integrations/webhooks) to review the complete event,
-  delivery, attempt and downstream-work model.`,
+A delivery row stores the full event body it sent, its hash, and the first kilobytes of your receiver's response. Both can contain personal data. Keep responses short, restrict who may read the delivery log, and apply your organization's retention policy to it; the purge operation in the API reference removes old rows.`,
     },
     {
         managedPath: 'integrations/webhooks/troubleshoot.md',
         unitRef: 'technical-documentation:unit/troubleshoot-webhook-deliveries',
-        sourceRefs: ['saas-technical-doc:engine-content/troubleshoot-webhook-deliveries'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/troubleshoot-webhook-deliveries',
+            'source:consumer-fact:outbound-webhooks',
+        ],
         markdown: `# Troubleshoot webhook deliveries
 
-Start from the recorded delivery state, attempt count and HTTP outcome. Do not
-disable verification or repeatedly change the endpoint while investigating;
-that removes the evidence needed to find the failed boundary.
+Start from the delivery row. Its status, \`attemptCount\`, \`responseStatus\`, \`failureReason\` and the recorded response body place the failure on one side of the wire. Fix that side, prove it with the endpoint test, then retry the row.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Preserve the delivery identifier, endpoint, signed delivery identity, event context, state, attempts, timestamps and HTTP evidence; locate the matching receiver record without copying secrets | The failure is assigned to application signing, transport, receiver verification, safe acceptance or downstream processing; one bounded repair is proven and recovery creates no duplicate effect |
+## Find the row
 
-## Locate the first failed boundary
+Open the delivery log for the organization (or the application) and filter by endpoint and time, or search it through the API. The \`signatureJti\` on the row is the \`jti\` your receiver logged; it is the key that joins the two systems.
 
-~~~mermaid
-flowchart TD
-  accTitle: Locate a webhook failure from application delivery to business result
-  accDescr: The operator starts from the delivery record, checks whether a request was sent and answered, then follows receiver verification, atomic acceptance, queued work and authoritative downstream state before deciding whether retry is safe.
-  row["Preserve delivery and attempt evidence"] --> sent{"Request sent?"}
-  sent -->|No| signing["Check signing and application configuration"]
-  sent -->|Yes| answered{"HTTP response received?"}
-  answered -->|No| transport["Check final URL, DNS, TLS, reachability and timeout"]
-  answered -->|Yes| success{"2xx observed?"}
-  success -->|No| receiver["Inspect receiver rejection or capacity"]
-  success -->|Yes| claimed{"jti durably claimed?"}
-  claimed -->|No| acceptance["Repair acknowledgement boundary"]
-  claimed -->|Yes| work{"Business work complete?"}
-  work -->|No| downstream["Recover queue or downstream dependency"]
-  work -->|Yes| reconcile["Close with delivery and business proof"]
-~~~
+## Diagnose by what the row shows
 
-Work from left to right. A later symptom does not erase an earlier failure. For
-example, manually creating the downstream record can repair the business state,
-but it does not explain why the receiver returned 2xx before durable acceptance.
+| Row shows | Where it broke | What to check |
+| --- | --- | --- |
+| No row at all | The event was not published, or webhooks are disabled | The master \`enabled\` switch, that the endpoint is enabled, and that the operation you performed is one the application publishes |
+| \`failed\`, \`failureReason\` mentions signing | The application could not sign | Application-side configuration; nothing on the receiver can help |
+| \`failed\`, no \`responseStatus\` | No HTTP answer within the timeout | Public reachability, DNS, TLS, and the receiver's own processing time |
+| \`responseStatus\` **3xx** | The URL is not the final receiver | Register the redirect target itself; redirects are never followed |
+| \`responseStatus\` **400** or **401** | Your receiver refused the signature, the body hash or the claims | Raw-body capture, the header name, the pinned algorithm, issuer and audience, the public key, and clock skew |
+| \`responseStatus\` **404** | Wrong path or wrong deployment | The exact route the receiver serves |
+| \`responseStatus\` **408**, **429** or **5xx** | The receiver is overloaded or failing | Capacity and errors on the receiver; the row keeps retrying on the ladder |
+| \`delivered\` but no downstream result | The receiver answered 2xx before durable acceptance, or the worker failed | The receiver's \`jti\` store, its queue and the worker's errors |
+| The effect happened twice | The receiver did not claim \`jti\` atomically | The uniqueness constraint on \`jti\` and the transaction around it |
 
-## Diagnose by symptom
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#retryMarkdown}}
 
-| Symptom | Likely boundary | What to inspect |
-| --- | --- | --- |
-| Test is **not sent** | Application configuration or signing | Enabled configuration, published key and local error evidence |
-| Test or delivery is **unreachable** | Network, DNS, TLS or receiver availability | Final public URL, certificate, resolved host and receiver timeout |
-| **3xx** response | Endpoint is not the final receiver URL | Configure the redirect destination directly |
-| **400** or **401** from receiver | Signature, claims, body bytes or payload validation | Raw-body capture, signature header, algorithm, key, clock and body hash |
-| **404** from receiver | Wrong route or deployment | Exact configured path and environment |
-| **408**, **429** or **5xx** | Transient receiver failure | Capacity, timeout and retry schedule; do not start a parallel retry loop |
-| Delivery is **Delivered**, but work is missing | Receiver acknowledged before durable acceptance or downstream work failed | Receiver queue, deduplication record and business reconciliation |
-| Repeated business effect | Receiver did not atomically deduplicate **jti** | Deduplication transaction and retention period |
-
-## Investigate without changing several variables
-
-### Nothing was sent
-
-For **Not sent** or a delivery that failed during signing, check the published
-verification-key configuration and signing evidence for the intended
-environment. The receiver cannot repair a request that never left the
-application. Correct the application-side configuration, then use the endpoint
-test before retrying real traffic.
-
-### The receiver did not answer
-
-Confirm the configured URL is the final public route. Check DNS, TLS, firewall
-or allow-list rules, deployment health and the receiver's thirty-second request
-window. A timeout does not prove the receiver saw nothing: search receiver logs
-and the deduplication store by **jti** before allowing another delivery.
-
-### The receiver answered with non-2xx
-
-Preserve the status and bounded response evidence. For 3xx, configure the final
-destination directly. For 400 or 401, inspect raw-body capture, the signature
-header, pinned algorithm, key identifier, clock, audience, event claims and body
-hash. For 404, compare the exact configured route and deployment. For 408, 429
-or 5xx, stabilize receiver capacity and let the scheduled retry proceed unless
-the delivery has already become terminal.
-
-### Delivery is green but business work is missing
-
-A **Delivered** row proves only that the receiver returned 2xx. Check whether
-the receiver atomically stored **jti** and durably queued the work before that
-response. Then inspect the worker, downstream dependency and authoritative
-business record. Recover the queued job or reconcile the business effect; do not
-retry the application delivery when the receiver already accepted it unless the
-receiver's deduplication contract makes that recovery deliberate and safe.
-
-### The business effect happened more than once
-
-Stop or disable the affected receiver path to contain further duplicates.
-Compare the repeated records with one signed **jti**. Repair the atomic claim and
-work-enqueue boundary, define how duplicate business records will be reconciled,
-and prove concurrent receipt of the same **jti** creates one effect before
-restoring traffic.
-
-## Preserve a minimal investigation record
-
-Keep the delivery identifier, endpoint identity, event channel, attempt count,
-state, response status, timestamps and correlation information. Redact the
-signature, sensitive payload fields and receiver response content before
-sharing evidence.
-
-If verification fails after a key or deployment change, compare the key
-identifier and expected application environment first. Never accept every
-algorithm or skip body-integrity verification as a fallback.
-
-## Prove and close the repair
-
-1. Test the endpoint while disabled and confirm both the application outcome and
-   receiver verification evidence.
-2. Exercise one negative case relevant to the incident—invalid signature,
-   changed bytes, duplicate **jti**, receiver timeout or failed downstream work.
-3. Trigger one controlled real event and follow it through delivery, durable
-   acceptance and authoritative business state.
-4. Retry one failed delivery only when the earlier effect is absent or safely
-   deduplicated.
-5. Record the cause, correction, affected scope, delivery identities and final
-   reconciliation without storing secrets or unrestricted payloads.
-
-Escalate with the delivery and endpoint identifiers, **jti**, event context,
-attempt timeline, response class and redacted receiver correlation. Say
-explicitly whether the receiver may already have accepted or completed the
-work. That prevents support from treating an ambiguous business outcome as a
-simple transport retry.
+## Signature failures after a change
 
-## Continue safely
+If deliveries began failing with **401** right after a deployment or a key change, reload \`applicationPublicKeyPem\` from the webhook configuration: the token header's \`kid\` is the thumbprint of the signing key, so a new \`kid\` means the key rotated. Then confirm \`iss\` and \`aud\` still match what the receiver pins. [Verify a webhook delivery](/integrations/webhooks/verify-delivery) lists every pinned value. Do not relax the verifier to make it pass.
+
+## Duplicates
+
+A retry of the same delivery carries the same \`jti\`; a different delivery of the same operation carries a different one, even when the body is identical. If your effect happened twice with one \`jti\`, the atomic claim is broken. If it happened twice with two \`jti\` values, two events really occurred; compare the bodies.
+
+## Prove the repair and retry
 
-- [Configure and test an endpoint](/integrations/webhooks/configure-and-test)
-  after changing a URL, deployment or signing configuration.
-- [Verify a webhook delivery](/integrations/webhooks/verify-delivery) to repair
-  the raw-byte, claim or deduplication boundary.
-- [Operate webhook deliveries](/integrations/webhooks/operate-deliveries) before
-  explicit retries or restoring ordinary traffic.`,
+1. Run the endpoint test and confirm it is \`accepted\` with verification logged on the receiver.
+2. Search the receiver's store for the failed row's \`jti\` to know whether the work already ran.
+3. Retry that one row from the delivery log and watch it become \`delivered\`.
+4. Retry the remaining failed rows for the same endpoint.
+
+## Ask for help with the right evidence
+
+Quote the endpoint \`id\`, the delivery row identifier, \`signatureJti\`, \`attemptCount\`, \`responseStatus\`, \`failureReason\` and the timestamps, and say whether the receiver may already have done the work. Never paste the token or the event body.`,
     },
     {
         managedPath: 'integrations/mcp.md',
         unitRef: 'technical-documentation:unit/mcp-integrations',
-        sourceRefs: ['saas-technical-doc:engine-content/mcp-integrations'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/mcp-integrations',
+            'source:companion-projection:application-connection',
+            'source:companion-projection:application-integration',
+        ],
         markdown: `# Connect an MCP client
 
 Use **Model Context Protocol (MCP)** when an AI client should discover a set of
@@ -9068,6 +8587,16 @@ result, not a universal list of everything the application can do.
 | --- | --- |
 | Choose the exact application environment, one MCP-capable client, a machine or delegated identity with the MCP audience, one non-production organization and one harmless expected tool | The client authenticates when challenged, receives only its caller-specific catalogue, completes one schema-valid read, refuses an unavailable or unauthorized call and can reconcile an uncertain mutation before retrying |
 
+## Connect to the endpoint
+
+{{APPLICATION_CONNECTION:mcpEndpoint}}
+
+Use it with the base URL of the environment you chose; the client configuration guides for [Cursor](/integrations/ai-tools/cursor), [Codex](/integrations/ai-tools/codex) and [Claude Code](/integrations/ai-tools/claude-code) show where each tool expects that address.
+
+## The tools this application publishes
+
+{{APPLICATION_INTEGRATION:mcpTools}}
+
 ## Decide who authorizes the client
 
 Use a dedicated machine identity when a service owns the work. Use delegated
@@ -9143,7 +8672,7 @@ catalogue request. In normal operation, let the MCP client or SDK create these
 headers and keep the credential in its protected store.
 
 ~~~http
-POST <MCP_SERVER_URL> HTTP/1.1
+POST {{APPLICATION_CONNECTION_VALUE:mcpEndpointUrl}} HTTP/1.1
 Authorization: Bearer <ACCESS_TOKEN_FOR_THIS_MCP_SERVER>
 Content-Type: application/json
 Accept: application/json, text/event-stream
@@ -9310,7 +8839,10 @@ operations the current identity can actually invoke.
     {
         managedPath: 'integrations/a2a.md',
         unitRef: 'technical-documentation:unit/a2a-integrations',
-        sourceRefs: ['saas-technical-doc:engine-content/a2a-integrations'],
+        sourceRefs: [
+            'saas-technical-doc:engine-content/a2a-integrations',
+            'source:companion-projection:application-connection',
+        ],
         markdown: `# Connect an A2A agent
 
 Use **Agent-to-Agent (A2A)** when another agent should exchange messages with
@@ -9325,6 +8857,8 @@ MCP catalogue.
 
 ## Read the agent card before sending work
 
+{{APPLICATION_CONNECTION:a2aAgentCard}}
+
 The public card describes the selected agent and the skills this application
 publishes for it. Confirm the card belongs to the intended environment and named
 agent instance. Treat it as discovery metadata: task and message operations
@@ -9379,8 +8913,8 @@ similar to this redacted example:
 {
   "protocolVersion": "0.2.5",
   "supportedInterfaces": [
-    { "url": "<APPLICATION_AGENT_URL>", "transport": "JSONRPC", "version": "1.0" },
-    { "url": "<APPLICATION_AGENT_URL>", "transport": "JSONRPC", "version": "0.2.5" }
+    { "url": "{{APPLICATION_CONNECTION_VALUE:agentCardUrl}}", "transport": "JSONRPC", "version": "1.0" },
+    { "url": "{{APPLICATION_CONNECTION_VALUE:agentCardUrl}}", "transport": "JSONRPC", "version": "0.2.5" }
   ],
   "name": "<APPLICATION_AGENT_NAME>",
   "capabilities": {