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

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

@@ -7,130 +7,113 @@
  * generated application may consume them.
  *
  * The fragments describe customer-facing product domains and integration
- * journeys, not a generic “technical guides” catalogue. Application-domain
- * use cases are deliberately absent until the app-creator flow owns their
- * authoring and acceptance.
+ * journeys, not a generic “technical guides” catalogue.
+ *
+ * This header used to say application-domain use cases were "deliberately absent until the
+ * app-creator flow owns their authoring and acceptance". That sentence is retired, and it is worth
+ * keeping the reason: stated as policy, the largest gap in the whole site read as a decision
+ * rather than a defect, and survived every review for exactly that long. A customer could learn
+ * how to verify a webhook signature before learning what the product manages.
+ *
+ * `what-this-application-manages.md` closes it WITHOUT anyone authoring per-application prose,
+ * which is what the original reservation was protecting: the page is engine-authored and every
+ * fact in it is projected from sources the application already accepted — its own resource
+ * registry, its declared API-reference categories, and each specification's purpose and lifecycle.
+ *
+ * What remains genuinely deferred is a page PER resource. Those need a variable unit set, and the
+ * renderer's route table is deliberately fixed (see `pathForUnit`), so an application-owned unit
+ * still fails closed rather than acquiring an implicit route.
  */
 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.
+| Understand what this application is for | [What {{APPLICATION_NAME}} manages](/what-this-application-manages) | The things it manages, in its own words, and who may act on each |
+| 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 |
+| Look up one operation, field or role | [API reference](/api) | The exact contract of every operation, generated from the application itself |
 
-## Before you change anything
+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.
 
-Confirm four things before an administrative or integration write:
+## Three things to know before you change anything
 
-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.
+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.
 
-## Three useful first journeys
+## How the documentation is organised
 
-### Help a person gain the right access
+- **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.
 
-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.
-
-### Connect another system safely
+## When you ask for help
 
-Start with [Integrations](/integrations). Choose the connection surface from
-the direction and shape of the work:
+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: 'what-this-application-manages.md',
+        unitRef: 'technical-documentation:unit/what-this-application-manages',
+        sourceRefs: [
+            'saas-technical-doc:engine-content/what-this-application-manages',
+            'source:companion-projection:application-connection',
+            'source:companion-projection:application-domain',
+        ],
+        markdown: `# What {{APPLICATION_NAME}} manages
 
-- 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.
+Every other page here explains how to reach this application, administer it, integrate with it or
+pay for it. This one says what it is FOR.
 
-Prove one read with a narrowly scoped credential before enabling a write. After
-any timeout or lost response, read the authoritative state before retrying.
+Everything below is the application's own: the things it stores, the words it uses for them, and
+who may act on each. None of it is written by the framework — it is read from the application's own
+resource definitions, so it says what this deployment actually publishes rather than what a product
+of this kind usually does.
 
-### Investigate an unexpected result
+## What it manages
 
-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.
+{{APPLICATION_DOMAIN:domainOverview}}
 
-## Guides and references have different jobs
+## Each one in detail
 
-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.
+{{APPLICATION_DOMAIN:domainResourceDetails}}
 
-## When you ask for help
+## Where to go next
 
-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.`,
+| You need to | Go to |
+| --- | --- |
+| Read or change any of this from your own code | [Send your first API request](/integrations/rest/send-request) |
+| Look up the exact fields, arguments and responses | [API reference](/api) |
+| Be notified when one of these changes | [Webhooks](/integrations/webhooks) |
+| Let an AI assistant work with them | [AI coding tools](/integrations/ai-coding-tools) |
+| Change who may act on them | [Roles in this application](/user-administration/roles-and-permissions) |
+
+The names above are the API's own, so a name you read here is the one you will send, the one an
+error message will quote back, and the one a webhook payload will carry.`,
     },
     {
         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 +156,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 +194,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 +234,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 +327,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 +362,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 +379,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 +529,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
@@ -1708,6 +1715,7 @@ value or a screenshot containing them.`,
         unitRef: 'technical-documentation:unit/oauth-provider',
         sourceRefs: [
             'saas-technical-doc:engine-content/oauth-provider',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-oauth-clients',
         ],
         markdown: `# OAuth provider and delegated access
@@ -1784,12 +1792,16 @@ token, key, user-information, revocation and logout endpoints belong to the API
 issuer. They are deliberately not all under one hand-constructed path.
 
 ~~~bash
-APPLICATION_OAUTH_ISSUER="https://api.example.invalid"
-
 curl --fail --silent --show-error \
-  "$APPLICATION_OAUTH_ISSUER/.well-known/oauth-authorization-server"
+  "{{APPLICATION_CONNECTION_VALUE:oauthMetadataUrl}}"
 ~~~
 
+That URL is not the issuer with the well-known segment appended, and the difference matters. RFC
+8414 inserts \`/.well-known/oauth-authorization-server\` **between the host and the issuer's path**,
+while OpenID Connect discovery appends its suffix to the issuer — the opposite construction. This
+application's issuer is \`{{APPLICATION_CONNECTION_VALUE:oauthIssuer}}\`, and it serves the same
+metadata document at both locations, so a client that derives either way finds it.
+
 Check the returned \`issuer\` exactly. Then read the advertised grants,
 \`code_challenge_methods_supported\`, token authentication methods, registration
 endpoint and resource-indicator support before configuring the client. A
@@ -2299,7 +2311,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 +2337,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 +2464,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 +2535,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 +2544,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 +2596,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 +2642,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 +2727,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 +2805,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 +2886,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 +2903,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 +3185,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 +3239,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 +3307,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 +3352,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
 
@@ -3558,6 +3581,7 @@ same membership or unit assignment.`,
         unitRef: 'technical-documentation:unit/scim-protocol-and-payloads',
         sourceRefs: [
             'saas-technical-doc:engine-content/scim-protocol-and-payloads',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:organization-scim-provisioning',
         ],
         markdown: `# SCIM protocol and payload reference
@@ -3633,11 +3657,10 @@ and does not prove that the person can complete SSO.
 
 ## Understand the base URL
 
-The configuration resource supplies the API-relative path
-\`/api/v1/scim/v2\`. A provider needs the complete public URL:
+This is the complete base URL a provider needs. Everything below hangs off it:
 
 ~~~text
-https://api.example.com/api/v1/scim/v2
+{{APPLICATION_CONNECTION_VALUE:scimBaseUrl}}
 ~~~
 
 The organization is not encoded in that URL. The bearer token identifies the
@@ -3712,9 +3735,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
@@ -3741,6 +3763,7 @@ application’s discovery response to understand the implemented profile.`,
         unitRef: 'technical-documentation:unit/scim-configure',
         sourceRefs: [
             'saas-technical-doc:engine-content/scim-configure',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:organization-scim-provisioning',
         ],
         markdown: `# Configure SCIM provisioning
@@ -3800,7 +3823,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",
@@ -4490,6 +4513,8 @@ is not misread as self-service.
   from retries and dead-letter state.
 - [Protect and retain audit evidence](/security-and-audit/protect-evidence)
   without turning a diagnostic copy into an uncontrolled data store.
+- [Respond to a leaked credential](/security-and-audit/respond-to-leaked-credential)
+  in the order an incident requires: contain, then assess, then recover.
 
 Close each task with the question, organization/environment, filters and time
 boundary, event and correlation identifiers, current-state comparison, reviewer
@@ -4499,7 +4524,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 +4535,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 +5376,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 +5405,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 |
@@ -5425,6 +5471,89 @@ Close the incident with source event ID, organization/environment, destination,
 filter decision, failure class, attempts, configuration correction, retry/purge
 decision, receiver lookup and correlation evidence. Exclude authentication
 secrets, raw Authorization headers and unnecessary event personal data.`,
+    },
+    {
+        managedPath: 'security-and-audit/respond-to-leaked-credential.md',
+        unitRef: 'technical-documentation:unit/respond-to-leaked-credential',
+        sourceRefs: ['saas-technical-doc:engine-content/respond-to-leaked-credential'],
+        markdown: `# Respond to a leaked credential
+
+A credential of this application has been exposed — an API key in a public repository, a token in a
+support ticket or a log, an OAuth client secret in a screenshot, or a person's password reused on a
+service that was breached.
+
+Every other page in this section explains ONE capability well. This one exists because an incident
+is not one capability: it is an ORDER. The costly mistakes here are not doing the wrong thing, they
+are doing the right things in the wrong sequence — investigating before containing, or revoking
+before you know what the credential reached.
+
+**Contain first. Assess second. Recover third.** Work down the page.
+
+## Before you start
+
+Write down the exposure time you will use as the window's lower bound — when the credential first
+became readable by someone who should not have it, NOT when you found out. If you cannot establish
+it, use the credential's creation time. Every step below is bounded by that instant, and widening it
+later means redoing the assessment.
+
+## 1 · Contain
+
+Do this before anything else, including before you finish reading the rest of this page. A credential
+you are still investigating is a credential still being used.
+
+| What leaked | Do this |
+| --- | --- |
+| An API key | Revoke it — see [API key lifecycle](/access-and-identity/api-keys-lifecycle). Revocation takes effect for new requests; it does not retract a request already in flight |
+| An OAuth client secret, or a token issued to a client | [Operate and revoke delegated access](/access-and-identity/oauth-operate-and-revoke), and revoke the client's outstanding grants, not only the secret |
+| A person's password | Suspend the account — see [Suspend or remove a user](/user-administration/suspend-or-remove-user). Suspending ends their sessions; a password reset alone does not tell you whether someone else is already signed in |
+| A SCIM or directory token | Rotate at the identity provider, then in [SCIM configuration](/user-administration/scim-configure). Until both sides carry the new value, provisioning is stopped — that is the correct trade during containment |
+
+**Do not delete anything yet.** Deleting the API key, the client or the user removes rows the next
+step reads. Revoke and suspend, which stop use while keeping the record.
+
+If you do not yet know which credential leaked, suspend the narrowest thing that certainly covers it
+and widen only if the assessment says so. An over-broad containment is recoverable in minutes; a
+missed one runs for as long as you are investigating.
+
+## 2 · Assess
+
+Only now, and only inside the window you wrote down.
+
+1. **What did it reach?** [Investigate an audit event](/security-and-audit/investigate-event),
+   filtered to the credential's own identifier rather than to a person — a leaked key acts under its
+   own identity, and filtering by the human who created it will not show you its requests.
+2. **Did it change access?** [Review access and privileged changes](/security-and-audit/review-access-changes).
+   This is the question that decides whether containment is finished: a credential that granted a
+   role, added a member or registered a client has left something behind that revoking it does not
+   remove.
+3. **Take the evidence out.** [Export a bounded audit window](/security-and-audit/export-audit-records)
+   for the window, before retention or an investigation of your own moves it. Handle the export as
+   the sensitive artefact it is — [Protect and retain audit evidence](/security-and-audit/protect-evidence).
+
+If step 2 found a change, treat every artefact it created as also compromised and return to
+**Contain** for each one. That loop is the point of the ordering: a leaked key that minted a second
+key is only half-contained when the first is revoked.
+
+## 3 · Recover
+
+- Issue the replacement credential and store it where the leaked one was not —
+  [Create and store an API key](/access-and-identity/api-keys-create-and-store) states where a
+  secret may and may not live.
+- Give the replacement the SMALLEST role that works. An incident is the cheapest moment to correct
+  an over-broad credential, because whatever breaks is being watched.
+- Lift the containment you widened, narrowest first, confirming after each one.
+- If the account is a person's, require a second factor before returning it to service —
+  [Multifactor enrollment and recovery](/access-and-identity/mfa-enrollment-and-recovery).
+
+## What this application cannot tell you
+
+The audit trail records what reached THIS application. A credential leaked in one place is usually
+leaked for others: if the same secret, or a password reused from it, opens anything else you run,
+this page's window is a lower bound on the incident, not its boundary.
+
+Nor can the trail prove absence. A window with no suspicious request means nothing suspicious
+**reached this application** during it — not that the credential was unused, and not that your lower
+bound was early enough.`,
     },
     {
         managedPath: 'security-and-audit/protect-evidence.md',
@@ -5525,1102 +5654,203 @@ change the application's authoritative audit retention.
 - keep credentials and unrelated personal data out of the evidence package.`,
     },
     {
-        managedPath: 'billing-and-subscriptions/billing.md',
-        unitRef: 'technical-documentation:unit/billing',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/billing',
-            'source:consumer-fact:billing-lifecycle',
-        ],
-        markdown: `# Billing and subscriptions
-
-Use this section when you are responsible for an organization's plan, invoices,
-usage or access after a billing change. You do not need to know which billing
-provider the application uses. You do need to distinguish three records:
+        managedPath: 'integrations.md',
+        unitRef: 'technical-documentation:unit/integrations',
+        sourceRefs: ['saas-technical-doc:engine-content/integrations'],
+        markdown: `# Integrations
 
-- the **product and price** describe what can be bought and on which terms;
-- the **subscription** records the current recurring relationship;
-- the application's **billing-derived access** records which features and limits
-  the current subscription actually grants.
+An integration connects this application to another system so that people do
+not have to copy information or repeat the same action by hand. Start with the
+outcome you need, then choose the smallest contract that can deliver it safely.
 
 | Before you begin | Successful result |
 | --- | --- |
-| Know the organization being billed, who approved the commercial decision, the current product and the application access expected afterwards | The intended billing record reaches a known state, the resulting access is verified in the same organization, and payment evidence remains protected |
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#markdown}}
+| Name one business outcome, the source of truth, the organization affected, the acting person or workload and who owns failures | The chosen connection proves one bounded allowed outcome, one expected refusal and a recovery path that does not expose credentials or repeat a business effect |
 
-## Keep the four billing views separate
+## Which integration should you choose?
 
-| View | Question it answers | Do not use it as proof of |
+| You need to… | Use | Why |
 | --- | --- | --- |
-| Product and price | What is offered, at what amount and interval, with which intended grants? | A purchase or active access |
-| Checkout or billing portal | Where are payment details, tax information and provider documents handled? | The final application subscription state |
-| Subscription and invoice summary | What recurring relationship and payment evidence did the application record? | Every feature currently available to the organization |
-| Resolved application access | Which features and limits can the organization actually use now? | Why that access exists without checking billing and other allowed sources |
-
-For organization billing, the standard management operations accept
-**Organization Owner** and **Organization Admin** authority. A custom role may
-inherit effective authority in an application-specific role graph; review
-[Roles and permissions](/user-administration/roles-and-permissions) and the
-exact operation contract rather than granting a broad role merely to expose the
-Billing area.
+| Read or change application data on demand | [REST API](/integrations/rest-api) | Your system sends a request and receives an immediate response |
+| Build a workflow in n8n, Zapier or Make | [Automation platforms](/integrations/automation-platforms) | The platform calls the REST API or receives a published event |
+| React when the application publishes an event | The Webhooks section, when available below | The application pushes a signed delivery to your receiver |
+| Connect Cursor, Codex or Claude Code | The AI coding tools section, when available below | The client discovers MCP tools available to its authenticated identity |
+| Give another AI client callable tools or exchange agent tasks | The Agent integrations section below | MCP covers tools; A2A covers messages and task lifecycles |
+
+Do not choose a protocol because its name is familiar. Choose it because its
+interaction model matches the business outcome. A scheduled REST poll is not a
+replacement for an event when timeliness matters; a webhook is not a command
+channel; an MCP tool call is not an A2A conversation.
 
 ~~~mermaid
-flowchart LR
-  accTitle: From a billing decision to usable application access
-  accDescr: An authorized administrator selects a product and price, completes hosted checkout, waits for verified billing state, then confirms the subscription and billing-derived access in the application. Invoice and usage records remain separate evidence.
-  choice["Choose product, price and billed scope"] --> checkout["Complete hosted checkout"]
-  checkout --> verify["Application verifies billing result"]
-  verify --> subscription["Subscription state is updated"]
-  subscription --> access["Features and limits are recomputed"]
-  verify --> invoice["Invoice and payment state is recorded"]
-  usage["Metered application usage"] --> invoice
+flowchart TD
+  accTitle: Choose an integration contract from the intended outcome
+  accDescr: Immediate request and response work uses REST. Event notification uses webhooks. Tool discovery and invocation uses MCP. Agent conversations and tasks use A2A.
+  outcome["What must the other system accomplish?"] --> immediate{"Immediate request and response?"}
+  immediate -->|Yes| rest["REST API"]
+  immediate -->|No| event{"React to an application event?"}
+  event -->|Yes| webhook["Webhook"]
+  event -->|No| agent{"AI or agent interaction?"}
+  agent -->|Call advertised tools| mcp["MCP"]
+  agent -->|Exchange messages and tasks| a2a["A2A"]
 ~~~
 
-The important boundary is after checkout: **returning to the application is not
-proof that access changed**. Read the current subscription and verify the feature
-or limit you expected before telling people the change is complete.
-
-The diagram has two evidence branches for a reason. Invoice/payment state
-explains the commercial event, while subscription state drives the billing
-access recomputation. A paid invoice and an unavailable feature can therefore
-both be true during a mismatch that still needs reconciliation.
-
-## Choose the task you need
+The diagram is a starting point, not a permission decision. The identity used
+by the integration still needs access to the intended organization, resources
+and operations.
 
-| Your task | Start here | You are finished when |
-| --- | --- | --- |
-| Decide what to buy | [Understand plans, prices and access](/billing-and-subscriptions/plans-and-access) | The billed scope, price terms and expected access are explicit before approval |
-| Create the recurring relationship | [Start a subscription](/billing-and-subscriptions/start-subscription) | The application records Active or Trialing state and the intended access works |
-| Upgrade, downgrade, add capacity or end access | [Change, resume or end a subscription](/billing-and-subscriptions/change-or-end-subscription) | Effective timing, charge/credit and access consequences match the approved decision |
-| Review a charge, payment state, document or measured quantity | [Billing records and usage](/billing-and-subscriptions/billing-records) | The question is routed to its owning record and matched to the correct scope and period |
-| Resolve a mismatch | [Reconcile billing and application access](/billing-and-subscriptions/reconcile-access) | Provider evidence, application records and the original application action agree |
-| Recover from an unclear result | [Troubleshoot a billing change](/billing-and-subscriptions/troubleshoot) | The failing layer is identified without a duplicate purchase or hidden access grant |
-
-## Close every billing task with evidence
-
-Retain the billed organization, product/price identity, subscription or invoice
-identifier, observed state, effective period, approval reference and correlation
-information needed for support. Do not retain card details, payment-method data,
-provider secrets, complete invoice documents or capability-style invoice URLs in
-ordinary logs and tickets.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/plans-and-access.md',
-        unitRef: 'technical-documentation:unit/understand-billing-plans-and-access',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/understand-billing-plans-and-access',
-            'source:consumer-fact:billing-lifecycle',
-        ],
-        markdown: `# Understand plans, prices and access
+## Keep the source of truth explicit
 
-Before approving a purchase, identify **what is being bought, who will be
-billed, when the charge repeats and which application access should change**.
-The current Billing area is authoritative for the products and prices offered by
-this application. The supported product-kind inventory is not proof that every
-kind is offered here.
+Decide which system owns the final fact before writing synchronization logic.
+REST can retrieve or change current application state; a webhook announces that
+an event occurred; MCP invokes an advertised operation; A2A carries a message or
+task. None of those contracts automatically makes the receiving copy
+authoritative.
 
-| Before you begin | Successful result |
-| --- | --- |
-| Have the intended organization, business owner, expected users or workload, required features/capacity and approved spending boundary | One current product and price satisfy the outcome without unnecessary capacity, and the expected access can be verified after purchase |
+After a timeout, duplicate or conflicting change, reconcile against the system
+that owns the fact. If ownership is shared or unclear, define a human decision
+path rather than letting the last retry silently win.
 
-## Start from the work, not the plan name
+## Before you connect anything
 
-Write down the outcome before comparing offers—for example, “the Support
-organization needs ten additional automated runs this month.” Then ask:
+- Name the business outcome and the system that owns the authoritative state.
+- Use a separate identity and credential for each deployed workload.
+- Begin in a non-production organization with the least privilege required.
+- Decide how you will reconcile timeouts, duplicates and partially completed work.
+- Record correlation information without copying credentials or restricted data.
 
-- Is the requirement a continuing base capability, optional recurring capacity,
-  measured use, a one-time item or prepaid credits?
-- Does the purchase belong to this organization, and will everybody who needs
-  it operate in that same scope?
-- Which exact feature or limit should change, and what current application
-  action will prove it?
-- When should the commercial and access change take effect?
-- Who owns renewal, usage review and cancellation?
+## Prove the boundary before production
 
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#productTypesMarkdown}}
+Start with a harmless action whose correct result a person can recognize. Prove
+the intended environment, identity, organization and response shape. Then prove
+one expected refusal: another organization, an unavailable operation, an
+invalid signature or insufficient authority must remain blocked.
 
-The table lists product kinds the application can support. Only products and
-prices shown in this application's current Billing area are purchasable offers.
-Do not ask support to create a missing kind from this list.
+Only after those checks should you add a mutation, automatic retry, schedule or
+production volume. For a state-changing path, deliberately simulate a lost
+response and show how authoritative state is read before another attempt.
 
-## Understand how quantity changes the amount
+Retain the integration owner, deployed workload, non-secret credential
+identifier, environment, organization, operation or event identity, outcome and
+correlation evidence. Define how the credential is rotated or revoked and who
+receives an alert when the business result cannot be reconciled.
 
-The product kind explains **what you are buying**. The pricing model explains
-**how the selected quantity becomes a charge**. Do not use the words “tiered”
-and “graduated” interchangeably: they produce different totals.
+If you are building a new connection, begin with [Create your own integration](/integrations/create-your-own-integration). The API reference supplies exact paths and schemas after you have chosen the correct journey.`,
+    },
+    {
+        managedPath: 'integrations/automation-platforms.md',
+        unitRef: 'technical-documentation:unit/automation-platforms',
+        sourceRefs: ['saas-technical-doc:engine-content/automation-platforms'],
+        markdown: `# Automation platforms
 
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#pricingModelsMarkdown}}
+Use an automation platform when a business process must move information or
+start work across systems without requiring a custom deployed service. This
+section covers **n8n**, **Zapier** and **Make**. The application does not need a
+platform-specific connector: each platform can call the published REST API,
+and it can receive application webhooks when a Webhooks section is available.
 
-### Worked example: 240 units
+## Start from the business event
 
-The following numbers are illustrative, not an offer from this application.
-They show why the pricing model must be recorded with the amount:
+Describe the automation in one sentence before opening the workflow editor:
+“When an approved record changes, create or update its counterpart in the
+reporting system.” That sentence identifies the trigger, the intended effect
+and the system that owns the final state.
 
-| Model | Illustrative terms | Result for 240 units |
+| The work starts when… | Begin with | Why |
 | --- | --- | --- |
-| Flat | €100 for the line item | €100 |
-| Per unit | €0.50 per unit | 240 × €0.50 = €120 |
-| Volume tiered | Up to 100 at €0.50; above 100 at €0.40 for all units | 240 × €0.40 = €96 |
-| Graduated | First 100 at €0.50; remaining units at €0.40 | (100 × €0.50) + (140 × €0.40) = €106 |
-| Package | €10 per block of 25, rounded up | 10 packages × €10 = €100 |
-
-For a tiered or package offer, keep the tier boundaries, flat additions and
-package size with the approval. A headline unit price is not enough to
-reconstruct the expected invoice.
-
-## Read a price as a complete offer
-
-Check the product name and description together with:
-
-- the billed scope—usually an organization, or a person only when the
-  application explicitly offers personal billing;
-- currency and amount;
-- monthly or yearly interval for recurring prices;
-- whether tax is included in the displayed amount or added at checkout;
-- trial duration and whether a payment method is required;
-- included features, capacity limits and any metered usage;
-- promotion eligibility and the date on which the offer expires.
-
-For a recurring price, read both the interval and its count. “Month” with an
-interval count of 3 means every three months, not monthly:
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#billingIntervalsMarkdown}}
-
-Currency codes should be interpreted using the maintained
-[ISO 4217 currency list](https://www.iso.org/iso-4217-currency-codes.html).
-The displayed currency does not determine whether tax is included:
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#taxDisplayModesMarkdown}}
-
-If the hosted billing screen is Stripe, its maintained
-[tax-behaviour guide](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior)
-explains the provider-side inclusive/exclusive distinction. The application
-offer and checkout total remain the evidence for this purchase.
-
-An **add-on** changes the same subscription without replacing its primary plan.
-A **credit pack** adds a consumable balance. Neither should be described as a
-plan upgrade unless that is what the product screen actually presents.
-
-## Trace an offer to application access
+| A schedule, form or another system produces input | An authenticated REST request | The workflow controls when the application is read or changed |
+| This application publishes a relevant event | A webhook receiver | The workflow starts from the event instead of repeatedly polling |
+| A person presses a workflow button | A safe read, followed by an explicit write | The person can confirm scope before a change is made |
 
 ~~~mermaid
-flowchart TD
-  accTitle: Evaluate a billing offer from commercial terms to application access
-  accDescr: The administrator starts with a required business outcome, chooses an offered product and price for one billed scope, reviews trial, timing and usage terms, identifies the promised feature or limit, then records how that access will be verified after purchase.
-  outcome["Name the required business outcome"] --> scope["Confirm billed organization or person"]
-  scope --> offer["Choose one currently offered product and price"]
-  offer --> terms["Review interval, tax, trial, quantity and promotion"]
-  terms --> grants["Identify expected features, limits or credits"]
-  grants --> proof["Define one application action that proves access"]
-  proof --> approval["Record approval and lifecycle owner"]
+flowchart LR
+  accTitle: Build an automation around one authoritative business outcome
+  accDescr: A schedule, human action, or application event starts the workflow. The workflow validates the input, reads current application state, applies one intended effect, and records enough evidence to reconcile failures.
+  trigger["Schedule, person or application event"] --> validate["Validate input and organization"]
+  validate --> read["Read authoritative state"]
+  read --> decide{"Change still required?"}
+  decide -->|No| finish["Record no change"]
+  decide -->|Yes| write["Apply one documented operation"]
+  write --> confirm["Confirm result and retain correlation"]
 ~~~
 
-The important handoff is from **grants** to **proof**. A product description can
-state what should be included; the original application action verifies what is
-actually usable after the billing state is processed.
-
-## Understand how access is assembled
-
-One active plan supplies the base features and limits. Active add-ons can add
-features or capacity. The application recomputes that billing-derived access
-from subscriptions in **Active** or **Trialing** state. Other subscription states
-do not contribute billing-derived access.
-
-Manual or broader-scope access can also exist. A feature remaining available
-after a downgrade therefore does not, by itself, prove that billing
-reconciliation failed. Compare the expected product grants with the resolved
-application access for the billed scope.
-
-Base-plan and add-on limits can combine according to the offered product policy:
-an add-on may add capacity or establish a higher limit. “Unlimited” capacity
-remains unlimited when combined. Do not calculate the final limit from marketing
-labels alone; read the resolved limit in the billed scope.
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#limitGrantModesMarkdown}}
-
-For example, a plan can establish 50 scheduled runs, while an add-on adds 20.
-The expected result is 70. If instead the add-on establishes a limit of 100,
-the expected result is 100—not 150. Verify the resolved value after purchase,
-because access can also come from a broader scope or an approved manual source.
-
-## Treat a promotion as conditional until checkout accepts it
+## Choose your platform
 
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#promotionVocabularyMarkdown}}
+- [Connect n8n](/integrations/automation/n8n) when you want a visual workflow
+  that can also be self-hosted and extended with technical nodes.
+- [Connect Zapier](/integrations/automation/zapier) when the business workflow
+  already lives in Zaps and should use an API or webhook step.
+- [Connect Make](/integrations/automation/make) when you want to map a scenario
+  visually and control HTTP request fields in a dedicated module.
 
-A promotion shown in Billing can still be refused for the selected purchase.
-Before relying on it, verify its validity dates, remaining redemptions, eligible
-products, discount currency when fixed, and duration. The checkout result is the
-positive proof; visibility in a list is only a reason to evaluate it.
+## Keep the first workflow deliberately small
 
-## Approve with a reviewable record
+Use a dedicated credential for one environment and one workflow. Prove one
+read operation, then one write only if the business outcome requires it. Store
+the credential in the platform's credential or connection store—not in a URL,
+ordinary field, workflow name, execution note or shared screenshot.
 
-Record the selected product and price, currency, interval, quantity, tax/trial
-terms, expected effective date, billed scope, expected grants and the person who
-approved them. Keep payment instruments and provider credentials out of that
-record. Continue to [Start a subscription](/billing-and-subscriptions/start-subscription)
-only after the expected application proof is clear.`,
+Before enabling unattended runs, test invalid input, expired or revoked access,
+insufficient permission, a timeout after a write and a duplicate trigger. The
+workflow is production-ready only when an operator can determine whether the
+business effect occurred without blindly repeating it.`,
     },
     {
-        managedPath: 'billing-and-subscriptions/start-subscription.md',
-        unitRef: 'technical-documentation:unit/start-billing-subscription',
+        managedPath: 'integrations/automation/n8n.md',
+        unitRef: 'technical-documentation:unit/connect-n8n',
         sourceRefs: [
-            'saas-technical-doc:engine-content/start-billing-subscription',
-            'source:consumer-fact:billing-lifecycle',
+            'saas-technical-doc:engine-content/connect-n8n',
+            'source:companion-projection:application-connection',
+            'source:consumer-fact:access-api-keys',
         ],
-        markdown: `# Start a subscription
-
-Start a subscription only when you can approve billing for the selected scope.
-For organization billing, organization owners and administrators are the
-standard authorized roles. Confirm your application exposes Billing and the
-intended product before beginning.
+        markdown: `# Connect n8n
 
-| Before you begin | Successful result |
-| --- | --- |
-| Have the approved organization, current product and price, expected access, spending approval, protected payment owner and a way to reconcile an unclear result | One checkout creates the intended subscription, the application records its current state and the expected feature or limit works in the billed scope |
+Use n8n when a visual workflow should read or change information in this
+application. There is no application-specific n8n node to install: the workflow
+uses n8n's standard **HTTP Request** node and the REST API published in this
+documentation.
 
-> **One checkout attempt can complete even when the browser never returns.**
-> Keep its identifiers and reconcile the application state before opening a
-> replacement checkout.
+This guide first builds a manual, read-only workflow. By the end, one click in
+n8n will call one authenticated operation and show recognizable application
+data in the node output. Only then will you connect a trigger or add a write.
 
-## Before checkout
+> **If the application should start the workflow when something happens,**
+> complete the read-only connection first, then follow **Start from an
+> application event** below. Do not poll repeatedly when a published webhook
+> already represents the event you need.
 
-1. Select the intended organization before opening Billing. Do not rely on the
-   organization that happened to be active in a previous browser session.
-2. Confirm the product, price, currency, interval, quantity, tax display, trial
-   terms and expected access against the approval.
-3. Check whether the displayed promotion applies to this exact product and
-   price. Visibility of a promotion does not guarantee that every item accepts it.
-4. Record the approver, expected effective date and application action that will
-   prove the resulting access.
-5. Continue once to the hosted checkout presented by the application.
+## What do you need before starting?
 
-Payment details, billing address and tax identifiers belong on that hosted
-billing surface. Do not send them through application support, an API metadata
-field or a screenshot.
+Ask the application administrator or integration owner for:
 
-When you enter a promotion code, stop if checkout refuses it. Do not compensate
-by changing quantity, selecting another organization or asking support to copy
-the discount manually. Recheck the product, validity period, redemption limit
-and discount currency against the approved offer.
+- the server origin shown in this application's API reference;
+- one authenticated **GET** operation and its complete path;
+- the non-production organization and known data you may use for the test;
+- a dedicated API key with only the role accepted by that operation; and
+- an owner who can revoke the key if the workflow is abandoned or exposed.
 
-~~~mermaid
-sequenceDiagram
-  accTitle: Start and verify a subscription
-  accDescr: The administrator opens checkout from the application, completes provider-hosted payment, returns to the application, then verifies the application subscription and resulting access instead of trusting the redirect alone.
-  participant A as Administrator
-  participant App as Application
-  participant B as Hosted billing
-  A->>App: Select product and price for the intended scope
-  App-->>A: Open authorized checkout
-  A->>B: Confirm payment and billing details
-  B-->>A: Return to application
-  App->>App: Verify billing result and update subscription
-  A->>App: Read subscription state and expected access
-~~~
+Use [Create and store an API key](/access-and-identity/api-keys-create-and-store)
+if the credential has not been prepared. Keep n8n and the application in the
+same environment throughout the test.
 
-The browser return is only navigation. The application updates its billing
-records from the verified provider result, then recomputes access. Closing the
-browser, losing the redirect or receiving a timeout does not establish whether
-the provider completed the checkout.
+## Build the first read-only workflow
 
-If the hosted screen identifies itself as Stripe, see Stripe's maintained
-[subscription Checkout journey](https://docs.stripe.com/billing/subscriptions/build-subscriptions)
-for the provider-side steps. That reference explains the hosted screen; the
-application subscription and resulting access remain the completion evidence.
+### 1. Create an explicit test trigger
 
-## Confirm success
+Create a new workflow and keep it inactive. Add a **Manual Trigger** so that the
+application is contacted only when you choose **Execute workflow**. Name the
+workflow after the business result and environment—for example, “Read approved
+records — test”—not after the credential.
 
-Do not use the success URL as the success criterion. In the application, verify:
+### 2. Add the application request
 
-- a subscription exists for the intended billing account;
-- its product, price and period are correct;
-- its state is **Active** or **Trialing**;
-- the expected feature or limit is available in the intended organization;
-- any first invoice has the expected total and state.
-
-Use the maintained subscription meanings when reading the result:
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#subscriptionStatusesMarkdown}}
-
-If the state remains incomplete, past due, unpaid or absent, do not create a
-second checkout immediately. Use the troubleshooting and reconciliation pages
-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
-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
-subscription is absent or Incomplete, preserve the first checkout identifier and
-reconcile it; **do not start another purchase merely to obtain a success page**.
-
-## Verify access, not only billing
-
-Repeat the application action identified before checkout. Confirm it in the
-same organization and with an ordinary intended user—not only with the billing
-administrator. Also verify one limit or unavailable action that should remain
-unchanged, so the proof does not hide an unexpectedly broad grant.
-
-## Retain safe completion evidence
-
-Keep the organization, product/price identity, checkout or subscription
-identifier, visible status, period dates, first-invoice summary, approver,
-correlation data and access-verification result. Do not retain card details,
-payment-method data, complete invoice documents, provider secrets or the full
-checkout URL.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/change-or-end-subscription.md',
-        unitRef: 'technical-documentation:unit/change-or-end-billing-subscription',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/change-or-end-billing-subscription',
-            'source:consumer-fact:billing-lifecycle',
-        ],
-        markdown: `# Change, resume or end a subscription
-
-A plan change is both a commercial decision and an access decision. Before
-confirming it, review the new price, effective date, prorated charge or credit,
-and the features or limits that will be added or removed.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Have the current subscription, approved target product/add-on, desired effective timing, expected charge or credit, and named access consequences | The application subscription reflects the approved change, access changes at the intended time, and no scheduled cancellation or stale item remains unexplained |
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#changeTimingMarkdown}}
-
-> **A requested policy is not proof of the applied charge or date.** Some billing
-> providers cannot schedule every change. Review any preview the application
-> presents, then verify the returned subscription, invoice or credit and the
-> resulting access. If those disagree with the approval, stop and reconcile the
-> change instead of applying another one.
-
-## Choose the lifecycle action
-
-~~~mermaid
-flowchart TD
-  accTitle: Choose how a subscription should change
-  accDescr: An administrator decides whether the organization needs a different base plan, an add-on change, end-of-period cancellation, immediate cancellation or reversal of a still-pending cancellation, then verifies the returned subscription and access consequence.
-  need{"What business decision was approved?"}
-  need -->|Replace base offer| plan["Change plan with product policy timing"]
-  need -->|Add or remove capacity| addon["Change subscription add-on"]
-  need -->|Stop at renewal| period["Schedule cancellation at period end"]
-  need -->|Stop now| immediate["Cancel immediately if policy permits"]
-  need -->|Undo pending cancellation| resume["Resume before the subscription ends"]
-  plan --> verify["Re-read subscription, charge evidence and access"]
-  addon --> verify
-  period --> verify
-  immediate --> verify
-  resume --> verify
-~~~
-
-Do not choose from the wording “upgrade” or “downgrade” alone. Determine which
-base product and add-ons will remain, when the provider applies the commercial
-change, and when users should gain or lose the corresponding application access.
-
-## Change the plan or its add-ons
-
-1. Read the current subscription, including its items, state and period end.
-2. Choose the new plan or add-on from the current application catalogue.
-3. Confirm that the selected price belongs to that product and applies to the
-   billed scope.
-4. Review the presented timing and proration before approving the change.
-5. After confirmation, re-read the subscription and verify the expected access.
-
-For an add-on change, verify the base plan remains present and the intended
-add-on appears or disappears exactly once. For a plan replacement, verify that
-the returned base item is the approved product and price. Do not infer the
-result from a checkout or portal confirmation message.
-
-Do not assume every billing connector can defer a downgrade. The **returned
-application subscription** is the source of truth for what was applied.
-
-If the hosted billing provider is Stripe, use its maintained
-[proration explanation](https://docs.stripe.com/billing/subscriptions/prorations)
-to interpret provider invoice lines. In particular, a credit line is not by
-itself proof that money was refunded, and a positive proration is not by itself
-proof that it was collected immediately. Match the application change, invoice
-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 current 50-run limit and current billing-period end;
-- the add-on price and whether the presented adjustment is immediate;
-- the expected resolved limit of 70;
-- the application operation that will prove the extra capacity.
-
-After confirmation, verify that the base plan is still present, the add-on
-appears once, any provider adjustment matches the presented currency and period,
-and the resolved limit is 70. If the request times out, re-read those records
-before trying to add the same item again.
-
-## End at period end or cancel immediately
-
-- **End at period end** keeps the subscription active through its current
-  period and marks it for cancellation. Access normally continues while the
-  subscription remains Active or Trialing.
-- **Cancel immediately** marks the subscription Cancelled now and removes its
-  contribution to billing-derived access when access is recomputed.
-
-Immediate cancellation is not always allowed by the product policy. Use it only
-when the business decision includes the immediate access consequence.
-
-Before immediate cancellation, identify workflows, exports or administrative
-actions that depend on billing-derived access. Do not use a temporary manual
-role or feature override to disguise the resulting loss; if continuity is
-required, approve the alternative access source explicitly.
-
-## Resume a scheduled cancellation
-
-A subscription can be resumed only while it is pending end-of-period
-cancellation. Resume clears that pending cancellation and returns the local
-subscription to Active. Verify both the next period date and the resulting
-access; a subscription that already ended needs a new approved purchase rather
-than resume.
-
-## Verify by action and by time
-
-1. Confirm the returned subscription items, state, period end and cancellation
-   flag in the billed scope.
-2. Match any immediate invoice or credit to the selected currency, quantity,
-   proration and period.
-3. Repeat the application action affected by the change.
-4. For a deferred change, record what stays active now and schedule a check at
-   the effective boundary.
-5. Verify an expected unaffected capability so the change did not alter a
-   broader scope.
-
-Retain the approval, old and new product/price identities, selected timing,
-visible proration evidence, subscription state and access proof. If the request
-times out, read the subscription before repeating it; an absent response is not
-evidence that the change failed.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/billing-records.md',
-        unitRef: 'technical-documentation:unit/billing-records-and-usage',
-        sourceRefs: ['saas-technical-doc:engine-content/billing-records-and-usage'],
-        markdown: `# Billing records and usage
-
-Use this journey when you need to explain **what was bought, what was charged,
-what was measured, or why application access differs from the commercial
-record**. Those questions use related records, but they do not have the same
-authority.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Know the environment, organization, product, billing period and the exact question being investigated | The question is answered from the record that owns it, then checked against the adjacent records without exposing payment data or duplicating a charge |
-
-## Choose the record that owns the answer
-
-| Question | Start with | Then compare |
-| --- | --- | --- |
-| Which recurring product is current? | Subscription items, status and period | Product/price offer and resolved access |
-| Was a charge created or paid? | Application invoice summary | Complete document in the authenticated provider portal |
-| Why is the invoice quantity different? | Local usage rows for the same period | Reported state and provider meter result |
-| Why is a feature unavailable after payment? | Current subscription and resolved access | Invoice/payment evidence only if the subscription state requires it |
-
-~~~mermaid
-flowchart LR
-  accTitle: Use each billing record for the question it owns
-  accDescr: The product and price describe the offer. The subscription records the recurring relationship and drives billing-derived access. Metered activity becomes local usage records and is reported to the provider. The provider creates the invoice; the application stores a safe summary while the complete document and payment methods remain in the authenticated provider portal.
-  offer["Product and price"] --> subscription["Subscription"]
-  subscription --> access["Billing-derived access"]
-  activity["Metered activity"] --> usage["Local usage records"]
-  usage --> provider["Provider meter"]
-  subscription --> invoice["Provider invoice"]
-  provider --> invoice
-  invoice --> summary["Application invoice summary"]
-  invoice --> portal["Authenticated provider portal"]
-~~~
-
-The useful boundary is between **operational summary** and **protected source
-document**. The application exposes enough invoice state and total information
-for reconciliation, but complete tax documents and payment methods stay behind
-the provider's authenticated portal. Usage remains separately traceable so a
-quantity can be explained before it becomes an invoice line.
-
-## Choose your task
-
-- [Manage invoices and payment details](/billing-and-subscriptions/invoices-and-payments)
-  when the question concerns payment state, currency, tax or the complete invoice.
-- [Understand metered usage](/billing-and-subscriptions/metered-usage) when the
-  question concerns measured quantity, reporting delay or a provider meter.
-- [Reconcile billing and application access](/billing-and-subscriptions/reconcile-access)
-  when the commercial record is correct but the application outcome is not.
-- [Troubleshoot a billing change](/billing-and-subscriptions/troubleshoot) when
-  the first durable record or failing boundary is still unclear.
-
-Retain identifiers, totals, states, periods and correlation evidence. Do not
-copy card data, payment-method details, complete invoice documents, temporary
-portal URLs or personal data from usage metadata into ordinary tickets.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/invoices-and-payments.md',
-        unitRef: 'technical-documentation:unit/manage-invoices-and-payments',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/manage-invoices-and-payments',
-            'source:consumer-fact:billing-lifecycle',
-        ],
-        markdown: `# Manage invoices and payment details
-
-An invoice is evidence of a charge, not the subscription itself. The application
-stores a small invoice summary—state, total and timestamps—while the billing
-provider keeps the complete tax document and payment methods behind its
-authenticated portal.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Know the billed organization, product, billing period and question being investigated; use an authorized billing administrator for provider documents | The application summary and provider document refer to the same charge, payment state and period without exposing payment data |
-
-## Know which record answers which question
-
-~~~mermaid
-flowchart LR
-  accTitle: Separate the application invoice summary from the protected provider document
-  accDescr: A subscription defines the recurring product and billing period. The provider creates an invoice and owns payment methods and the complete tax document. The application retains a safe status and total summary for operational review, while an authorized administrator opens the authenticated portal for the full document or payment change.
-  subscription["Subscription and billing period"] --> invoice["Provider invoice"]
-  invoice --> summary["Application invoice summary"]
-  invoice --> portal["Authenticated billing portal"]
-  portal --> document["Complete invoice or receipt"]
-  portal --> payment["Payment methods and billing details"]
-~~~
-
-The application summary is designed for status checks and reconciliation. It is
-not a replacement for the provider's full tax document.
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#invoiceStatusesMarkdown}}
-
-Open complete invoice documents through the authenticated billing portal. Direct
-provider document URLs are deliberately not exposed in the application API:
-they can act like bearer links to documents containing names and billing
-addresses.
-
-Use the provider portal only from the application's Billing area and return to
-the intended environment afterwards. Do not copy a complete invoice into an
-ordinary ticket when its identifier, total, currency, period and state are
-sufficient to investigate.
-
-If the portal identifies itself as Stripe, use Stripe's maintained
-[customer-portal guide](https://docs.stripe.com/customer-management/integrate-customer-portal)
-to understand the provider handoff and its
-[Hosted Invoice Page guide](https://docs.stripe.com/invoicing/hosted-invoice-page)
-to understand the complete document surface. Always open a fresh portal session
-from the application; do not preserve or redistribute its temporary URL.
-
-## Read payment and subscription state together
-
-- An **Open** or **Uncollectible** invoice explains a payment problem, but the
-  current subscription state determines whether billing-derived access remains.
-- A **Paid** invoice proves settlement of that invoice; still verify that the
-  corresponding subscription and access update reached the intended scope.
-- A **Void** invoice should not be treated as a successful payment or as a new
-  entitlement.
-
-An invoice can change after it is first created—for example from Draft to Open
-or Paid. Record the state and observation time when using it as evidence. The
-latest application summary is appropriate for operational review; the provider
-portal owns the complete document.
-
-## Interpret currency, tax and payment state separately
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#taxDisplayModesMarkdown}}
-
-Inclusive or exclusive describes the **displayed price**. It does not prove the
-tax rate, jurisdiction, payment success or final amount. Compare the invoice
-currency, subtotal, tax, total and period with the approved offer and the
-provider document. For an unfamiliar currency code, use the
-[ISO 4217 currency list](https://www.iso.org/iso-4217-currency-codes.html).
-
-When the invoice is Open or Uncollectible, an authorized administrator should
-open Billing, enter the authenticated provider portal and review the available
-payment action. Do not ask the person to send card numbers, bank details or a
-screenshot of the payment instrument to application support.
-
-### Example: a paid invoice but unchanged access
-
-A Paid invoice proves that **that invoice** was settled. It does not prove that
-the application processed the corresponding subscription update or recomputed
-access. Confirm the subscription is Active or Trialing, then repeat the
-application action that should now be available. If that action still fails,
-continue with [Reconcile billing and application access](/billing-and-subscriptions/reconcile-access).
-
-## Protect financial evidence
-
-Invoice summaries remain financial history even when the billed scope is later
-retired. Limit access to administrators who need it, keep exports in protected
-storage, and apply the organization's retention and legal-hold rules. Retain
-the invoice identifier, currency, total, state, period and observation time in
-ordinary support evidence—not the complete document or payment details.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/metered-usage.md',
-        unitRef: 'technical-documentation:unit/understand-metered-usage',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/understand-metered-usage',
-            'source:consumer-fact:billing-lifecycle',
-        ],
-        markdown: `# Understand metered usage
-
-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
-when preparing the invoice.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Know the organization, metered product, billing period, unit being counted and application action that produces it | Local records, reported state, provider quantity and invoice use the same product, scope, period and unit without duplicating usage |
-
-## Follow one quantity through the system
-
-~~~mermaid
-sequenceDiagram
-  accTitle: Follow metered usage from application activity to an invoice
-  accDescr: A successful application action creates a local usage row. The Billing area can show the local total while the row is pending. A scheduled flush groups pending rows by billing account and product, reports the quantity to the provider, then marks the local rows as reported. Provider processing is asynchronous, so the invoice can lag behind the newest local activity.
-  participant U as User or workload
-  participant App as Application
-  participant Store as Local usage records
-  participant Job as Billing reporter
-  participant P as Billing provider
-  U->>App: Complete a metered action
-  App->>Store: Record product, quantity and occurrence time
-  Note over Store: reportedToProvider = false
-  Job->>Store: Read pending rows by account + product
-  Job->>P: Report grouped quantity
-  P-->>Job: Accept report
-  Job->>Store: Mark included rows as reported
-  P->>P: Process meter and prepare invoice asynchronously
-~~~
-
-The two delays in the diagram are different:
-
-- **Pending locally** means the application has recorded the activity but has
-  not yet marked it as reported to the provider.
-- **Accepted by the provider** still does not mean an invoice or provider usage
-  summary has updated immediately. Provider meter processing is asynchronous.
-
-The application does not promise a universal flush interval. Record the last
-local occurrence time and the reported state instead of saying “billing updates
-every hour”.
-
-## Understand what created the record
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#usageSourceTypesMarkdown}}
-
-The source helps an administrator locate the business action that produced the
-quantity. It is not a reason to store a person's name, email or free-text notes
-in usage metadata. These records are retained as financial history.
-
-## Worked example: local usage is temporarily ahead
-
-Three application actions create quantities of 40, 25 and 10 for the same
-product and billing period. The local total is **75**. The first two rows have
-already been reported, while the last row remains pending, so the provider can
-temporarily show **65**.
-
-Do not manually send the missing 10 or recreate the application action. First
-wait for the normal reporting boundary and verify that the original row becomes
-reported. Re-sending a quantity that the normal flush later sends can create a
-duplicate charge.
-
-## Reconcile a usage difference
-
-| Check | What to compare | What it rules out |
-| --- | --- | --- |
-| Scope | Environment, organization and billing account | Usage from another tenant or test environment |
-| Product | Product key and the unit described by the offer | Comparing requests with storage, seats or another meter |
-| Period | Local occurrence timestamps and provider invoice period | Correct usage assigned to a different billing cycle |
-| Local total | Every row in the period, including pending rows | A dashboard total that omitted recent activity |
-| Reporting state | **Reported to provider** and **reported at** values | Treating pending activity as already invoiced |
-| Provider result | Meter quantity and invoice state after processing | A provider-side delay or rejected meter event |
-
-Close the investigation only when the same records explain both totals, or when
-a named correction owner has accepted the difference. Preserve the product,
-period, local total, reported total, pending row identifiers and correlation
-evidence. Do not retain provider credentials or personal data.
-
-If the hosted provider is Stripe, its maintained
-[usage-based billing overview](https://docs.stripe.com/billing/subscriptions/usage-based/how-it-works),
-[meter-event recording guide](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api)
-and [meter configuration guide](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure)
-explain the provider side. Use those references to interpret provider processing;
-use the application's local records to identify what was actually measured.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/reconcile-access.md',
-        unitRef: 'technical-documentation:unit/reconcile-billing-and-access',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/reconcile-billing-and-access',
-            'source:consumer-fact:billing-lifecycle',
-        ],
-        markdown: `# Reconcile billing and application access
-
-Use reconciliation when the provider, the application subscription and the
-person's visible access do not tell the same story. Keep those layers separate;
-changing a role to conceal a billing problem creates a second access problem.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Have the environment, billed organization, subscription and invoice identities, expected product grants, original application action and approximate change time | The first inconsistent layer is identified, repaired through its normal workflow and verified against current application state without a duplicate charge or unrelated access grant |
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#subscriptionStatusesMarkdown}}
-
-## Name the layer that disagrees
-
-| Layer | Evidence to read | Typical question |
-| --- | --- | --- |
-| Commercial offer | Current product, price, quantity and behavior policy shown by the application | Was the approved item actually offered for this scope? |
-| Provider transaction | Authenticated checkout/portal and invoice evidence | Did the provider complete, refuse or leave payment incomplete? |
-| Application billing state | Subscription items, status, period dates, invoice summary and usage reporting state | Did the verified result reach the intended billing account? |
-| Billing-derived access | Product grants and resolved feature/limit in the billed scope | Did the application recompute the access that this state should contribute? |
-| Original user action | The operation the person or workload tried to perform | Is the intended outcome now genuinely usable? |
-
-Move down the table in order. A role change at the final layer cannot repair an
-incomplete provider transaction, and a paid invoice does not by itself prove
-that the application's subscription or feature state was updated.
-
-~~~mermaid
-flowchart TD
-  accTitle: Reconcile a billing change from scope to entitlement
-  accDescr: The reviewer confirms the billed scope, reads the application subscription and invoice, checks whether the subscription state contributes billing access, compares product grants with resolved access, and then repairs the failing layer.
-  symptom["Expected access differs from visible access"] --> scope["Confirm billed organization or person"]
-  scope --> subscription["Read current application subscription"]
-  subscription --> state{"Active or Trialing?"}
-  state -->|No| payment["Inspect invoice and payment state"]
-  state -->|Yes| grants["Compare plan and add-on grants"]
-  grants --> resolved["Check resolved feature and limit"]
-  payment --> repair["Repair billing or wait for verified update"]
-  resolved --> repair
-  repair --> verify["Repeat the original application action"]
-~~~
-
-Notice that the flow checks **Active or Trialing** before comparing grants.
-Those are the only maintained subscription states that contribute billing-
-derived access. Payment repair belongs before feature repair when the
-subscription is in another state.
-
-## Reconciliation checklist
-
-1. Confirm the environment and billed scope.
-2. Read the current application subscription; do not rely on a provider email
-   or redirect.
-3. Verify its product items, status, period dates and cancellation flag.
-4. If payment is involved, match the invoice total, currency and state.
-5. Compare the plan and add-on grants with the resolved feature or limit.
-6. Repeat the original application operation to prove access, not merely the
-   Billing screen.
-7. Record the final subscription state and the evidence used to close the case.
-
-Where a change may still be processing, preserve the first attempt and allow a
-bounded observation window instead of opening a replacement checkout. Where a
-write returned no response, re-read current subscription state before deciding
-whether a retry is safe.
-
-Only Active and Trialing subscriptions contribute billing-derived access. A
-feature can still come from another allowed source, and a finite application
-limit can combine with plan and add-on limits. Explain the actual resolved
-result instead of assuming one plan label owns all access.
-
-## Choose the repair by the failing layer
-
-- **Wrong scope or offer:** return to the intended organization and select a
-  current product/price through the normal Billing journey.
-- **Incomplete or failed payment:** use the authenticated billing portal; do not
-  send payment details to application support.
-- **Stale application subscription:** preserve transaction and correlation
-  evidence for support rather than patching the subscription record.
-- **Correct subscription but wrong grants:** compare the product and add-on
-  definitions with the resolved feature/limit; do not add a broad role as a
-  substitute.
-- **Correct resolved access but failed action:** troubleshoot the operation's
-  organization, role, resource visibility and request separately from billing.
-
-Close with the organization, original symptom, responsible layer, correction,
-final subscription/invoice state and the repeated application action. Exclude
-card details, provider secrets and complete invoice documents.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/troubleshoot.md',
-        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
-
-Begin with what the administrator or user can observe. Repeating checkout,
-granting a broader role or manually changing access before identifying the
-failed layer can create duplicate charges or hide the original problem.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Preserve the environment, organization, first attempt, product/price, subscription or invoice identifier, approximate time, visible status and original application symptom | One failing boundary is identified and repaired without duplicating a purchase, exposing payment data or leaving unrelated access in place |
-
-## Diagnose from the first durable record
-
-~~~mermaid
-flowchart TD
-  accTitle: Troubleshoot a billing change without repeating it blindly
-  accDescr: The administrator starts from the first checkout or subscription evidence, confirms the billed scope, reads current subscription and invoice state, compares product grants with resolved access, then repeats the original application action after repairing only the failing layer.
-  symptom["Billing or access result is unexpected"] --> scope["Confirm environment and billed scope"]
-  scope --> attempt["Preserve first checkout or change evidence"]
-  attempt --> subscription{"Application subscription present?"}
-  subscription -->|No or incomplete| payment["Check invoice/provider evidence and processing state"]
-  subscription -->|Yes| status{"State contributes billing access?"}
-  status -->|No| payment
-  status -->|Yes| grants["Compare product/add-on grants with resolved access"]
-  grants --> action["Repeat original application action"]
-  payment --> repair["Repair payment or reconcile verified provider result"]
-  repair --> subscription
-~~~
-
-Do not begin from a success redirect, provider email or plan label. Begin from
-the application billing account and current subscription for the intended
-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}}
-
-## Start from the symptom
-
-| Symptom | First checks | Safe next step |
-| --- | --- | --- |
-| Returned from checkout but no subscription appears | Intended scope, existing incomplete subscription, processing delay and the first attempt's billing evidence | Reconcile the first attempt before opening checkout again |
-| Subscription is Active but feature is unavailable | Product and price, expected grants, current organization, resolved feature/limit and the original operation | Repair grant/access reconciliation; do not broaden the person's role |
-| Subscription is Past due, Unpaid or Paused | Current invoice state and the authenticated billing portal; these states do not contribute billing-derived access | Resolve payment in the portal, then wait for verified application state |
-| Downgrade or cancellation appears immediate | Returned subscription items, status, period end and cancellation flag; do not rely only on the requested timing | Compare the applied product policy and access consequence with the approval |
-| Cancellation was requested but access remains | End-of-period cancellation may intentionally keep an Active subscription until period end | Record the effective boundary and verify again when the period ends |
-| Invoice total differs from expectation | Currency, tax display, quantity, proration, promotion and billing period | Compare the selected offer and applied adjustment before disputing the charge |
-| Metered usage differs from provider | Local period total, last recorded time, reported state and aggregation delay | Wait for the bounded reporting window, then compare the same product and period |
-| Resume is refused | The subscription must still be pending end-of-period cancellation | If it already ended, use a newly approved purchase instead of resume |
-| Billing screen is correct but the application action fails | Resolved feature/limit, organization, role and exact operation | Troubleshoot authorization or resource scope separately from billing |
-
-## Recover without making the record harder to understand
-
-- Keep the first checkout or change identifiers and do not create a replacement
-  until its state is known.
-- Use the authenticated billing portal for payment methods and invoice documents.
-- Correct the product, price or scope through the normal billing operation; do
-  not patch subscription status directly.
-- After recovery, verify both the billing record and the application action that
-  depends on it.
-- Share invoice identifiers, status, timestamps and correlation evidence with
-  support—not card details, full invoice documents or provider secrets.
-
-If the application record and provider evidence still disagree, preserve both
-views and escalate the reconciliation. The application retains subscriptions,
-invoice references and usage records as financial history rather than deleting
-them when a scope is retired.
-
-## Escalate a reproducible case
-
-Provide the environment, billed organization, product/price identity, first
-attempt or subscription identifier, invoice summary, timestamps, current state,
-expected access, observed application action and correlation identifier. State
-whether payment, subscription state or access changed between observations.
-Never attach card data, payment-method details, complete invoice documents,
-hosted invoice URLs, provider secrets or unrestricted personal data.`,
-    },
-    {
-        managedPath: 'integrations.md',
-        unitRef: 'technical-documentation:unit/integrations',
-        sourceRefs: ['saas-technical-doc:engine-content/integrations'],
-        markdown: `# Integrations
-
-An integration connects this application to another system so that people do
-not have to copy information or repeat the same action by hand. Start with the
-outcome you need, then choose the smallest contract that can deliver it safely.
-
-| Before you begin | Successful result |
-| --- | --- |
-| Name one business outcome, the source of truth, the organization affected, the acting person or workload and who owns failures | The chosen connection proves one bounded allowed outcome, one expected refusal and a recovery path that does not expose credentials or repeat a business effect |
-
-## Which integration should you choose?
-
-| You need to… | Use | Why |
-| --- | --- | --- |
-| Read or change application data on demand | [REST API](/integrations/rest-api) | Your system sends a request and receives an immediate response |
-| Build a workflow in n8n, Zapier or Make | [Automation platforms](/integrations/automation-platforms) | The platform calls the REST API or receives a published event |
-| React when the application publishes an event | The Webhooks section, when available below | The application pushes a signed delivery to your receiver |
-| Connect Cursor, Codex or Claude Code | The AI coding tools section, when available below | The client discovers MCP tools available to its authenticated identity |
-| Give another AI client callable tools or exchange agent tasks | The Agent integrations section below | MCP covers tools; A2A covers messages and task lifecycles |
-
-Do not choose a protocol because its name is familiar. Choose it because its
-interaction model matches the business outcome. A scheduled REST poll is not a
-replacement for an event when timeliness matters; a webhook is not a command
-channel; an MCP tool call is not an A2A conversation.
-
-~~~mermaid
-flowchart TD
-  accTitle: Choose an integration contract from the intended outcome
-  accDescr: Immediate request and response work uses REST. Event notification uses webhooks. Tool discovery and invocation uses MCP. Agent conversations and tasks use A2A.
-  outcome["What must the other system accomplish?"] --> immediate{"Immediate request and response?"}
-  immediate -->|Yes| rest["REST API"]
-  immediate -->|No| event{"React to an application event?"}
-  event -->|Yes| webhook["Webhook"]
-  event -->|No| agent{"AI or agent interaction?"}
-  agent -->|Call advertised tools| mcp["MCP"]
-  agent -->|Exchange messages and tasks| a2a["A2A"]
-~~~
-
-The diagram is a starting point, not a permission decision. The identity used
-by the integration still needs access to the intended organization, resources
-and operations.
-
-## Keep the source of truth explicit
-
-Decide which system owns the final fact before writing synchronization logic.
-REST can retrieve or change current application state; a webhook announces that
-an event occurred; MCP invokes an advertised operation; A2A carries a message or
-task. None of those contracts automatically makes the receiving copy
-authoritative.
-
-After a timeout, duplicate or conflicting change, reconcile against the system
-that owns the fact. If ownership is shared or unclear, define a human decision
-path rather than letting the last retry silently win.
-
-## Before you connect anything
-
-- Name the business outcome and the system that owns the authoritative state.
-- Use a separate identity and credential for each deployed workload.
-- Begin in a non-production organization with the least privilege required.
-- Decide how you will reconcile timeouts, duplicates and partially completed work.
-- Record correlation information without copying credentials or restricted data.
-
-## Prove the boundary before production
-
-Start with a harmless action whose correct result a person can recognize. Prove
-the intended environment, identity, organization and response shape. Then prove
-one expected refusal: another organization, an unavailable operation, an
-invalid signature or insufficient authority must remain blocked.
-
-Only after those checks should you add a mutation, automatic retry, schedule or
-production volume. For a state-changing path, deliberately simulate a lost
-response and show how authoritative state is read before another attempt.
-
-Retain the integration owner, deployed workload, non-secret credential
-identifier, environment, organization, operation or event identity, outcome and
-correlation evidence. Define how the credential is rotated or revoked and who
-receives an alert when the business result cannot be reconciled.
-
-If you are building a new connection, begin with [Create your own integration](/integrations/create-your-own-integration). The API reference supplies exact paths and schemas after you have chosen the correct journey.`,
-    },
-    {
-        managedPath: 'integrations/automation-platforms.md',
-        unitRef: 'technical-documentation:unit/automation-platforms',
-        sourceRefs: ['saas-technical-doc:engine-content/automation-platforms'],
-        markdown: `# Automation platforms
-
-Use an automation platform when a business process must move information or
-start work across systems without requiring a custom deployed service. This
-section covers **n8n**, **Zapier** and **Make**. The application does not need a
-platform-specific connector: each platform can call the published REST API,
-and it can receive application webhooks when a Webhooks section is available.
-
-## Start from the business event
-
-Describe the automation in one sentence before opening the workflow editor:
-“When an approved record changes, create or update its counterpart in the
-reporting system.” That sentence identifies the trigger, the intended effect
-and the system that owns the final state.
-
-| The work starts when… | Begin with | Why |
-| --- | --- | --- |
-| A schedule, form or another system produces input | An authenticated REST request | The workflow controls when the application is read or changed |
-| This application publishes a relevant event | A webhook receiver | The workflow starts from the event instead of repeatedly polling |
-| A person presses a workflow button | A safe read, followed by an explicit write | The person can confirm scope before a change is made |
-
-~~~mermaid
-flowchart LR
-  accTitle: Build an automation around one authoritative business outcome
-  accDescr: A schedule, human action, or application event starts the workflow. The workflow validates the input, reads current application state, applies one intended effect, and records enough evidence to reconcile failures.
-  trigger["Schedule, person or application event"] --> validate["Validate input and organization"]
-  validate --> read["Read authoritative state"]
-  read --> decide{"Change still required?"}
-  decide -->|No| finish["Record no change"]
-  decide -->|Yes| write["Apply one documented operation"]
-  write --> confirm["Confirm result and retain correlation"]
-~~~
-
-## Choose your platform
-
-- [Connect n8n](/integrations/automation/n8n) when you want a visual workflow
-  that can also be self-hosted and extended with technical nodes.
-- [Connect Zapier](/integrations/automation/zapier) when the business workflow
-  already lives in Zaps and should use an API or webhook step.
-- [Connect Make](/integrations/automation/make) when you want to map a scenario
-  visually and control HTTP request fields in a dedicated module.
-
-## Keep the first workflow deliberately small
-
-Use a dedicated credential for one environment and one workflow. Prove one
-read operation, then one write only if the business outcome requires it. Store
-the credential in the platform's credential or connection store—not in a URL,
-ordinary field, workflow name, execution note or shared screenshot.
-
-Before enabling unattended runs, test invalid input, expired or revoked access,
-insufficient permission, a timeout after a write and a duplicate trigger. The
-workflow is production-ready only when an operator can determine whether the
-business effect occurred without blindly repeating it.`,
-    },
-    {
-        managedPath: 'integrations/automation/n8n.md',
-        unitRef: 'technical-documentation:unit/connect-n8n',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/connect-n8n',
-            'source:consumer-fact:access-api-keys',
-        ],
-        markdown: `# Connect n8n
-
-Use n8n when a visual workflow should read or change information in this
-application. There is no application-specific n8n node to install: the workflow
-uses n8n's standard **HTTP Request** node and the REST API published in this
-documentation.
-
-This guide first builds a manual, read-only workflow. By the end, one click in
-n8n will call one authenticated operation and show recognizable application
-data in the node output. Only then will you connect a trigger or add a write.
-
-> **If the application should start the workflow when something happens,**
-> complete the read-only connection first, then follow **Start from an
-> application event** below. Do not poll repeatedly when a published webhook
-> already represents the event you need.
-
-## What do you need before starting?
-
-Ask the application administrator or integration owner for:
-
-- the server origin shown in this application's API reference;
-- one authenticated **GET** operation and its complete path;
-- the non-production organization and known data you may use for the test;
-- a dedicated API key with only the role accepted by that operation; and
-- an owner who can revoke the key if the workflow is abandoned or exposed.
-
-Use [Create and store an API key](/access-and-identity/api-keys-create-and-store)
-if the credential has not been prepared. Keep n8n and the application in the
-same environment throughout the test.
-
-## Build the first read-only workflow
-
-### 1. Create an explicit test trigger
-
-Create a new workflow and keep it inactive. Add a **Manual Trigger** so that the
-application is contacted only when you choose **Execute workflow**. Name the
-workflow after the business result and environment—for example, “Read approved
-records — test”—not after the credential.
-
-### 2. Add the application request
-
-Add an **HTTP Request** node after the trigger, then complete these fields from
-the same API-reference operation:
+Add an **HTTP Request** node after the trigger, then complete these fields from
+the same API-reference operation:
 
 | n8n field | Value to use | How to verify it |
 | --- | --- | --- |
 | **Method** | The operation's documented HTTP method, initially **GET** | It matches the operation heading in the API reference |
-| **URL** | Server origin followed by the complete documented operation path | The origin appears once and the API path appears once |
+| **URL** | \`{{APPLICATION_CONNECTION_VALUE:baseUrl}}\` followed by the operation's documented path | The origin appears once and the API path appears once |
 | **Authentication** | **Generic Credential Type**, then **Header Auth** | The key is stored as an n8n credential, not in the URL or workflow data |
 | **Send Headers** | Add **Accept** with value **application/json** | The request asks for the documented JSON response |
 | Query/path values | Only values required by the selected operation | Organization and resource identifiers are in the locations defined by the reference |
@@ -6756,6 +5986,7 @@ HTTP response needs deeper diagnosis.
         unitRef: 'technical-documentation:unit/connect-zapier',
         sourceRefs: [
             'saas-technical-doc:engine-content/connect-zapier',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-api-keys',
         ],
         markdown: `# Connect Zapier
@@ -6816,7 +6047,7 @@ Complete the API Request action from one operation in the current reference:
 | Zapier field | Value to use | Verification |
 | --- | --- | --- |
 | Method | The documented method, initially **GET** | It matches the operation heading |
-| URL | Server origin plus the complete operation path | Origin and API prefix each appear once |
+| URL | \`{{APPLICATION_CONNECTION_VALUE:baseUrl}}\` plus the operation's documented path | Origin and API prefix each appear once |
 | Headers | **Accept: application/json** plus connection-managed authentication | No API key is visible in the Zap step |
 | Parameters | Only required query/path values | Organization and record values are in the documented locations |
 | Body | Empty for the selected read unless the operation explicitly documents one | No response field was copied back as an invented request field |
@@ -6924,6 +6155,7 @@ flowchart TD
         unitRef: 'technical-documentation:unit/connect-make',
         sourceRefs: [
             'saas-technical-doc:engine-content/connect-make',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-api-keys',
         ],
         markdown: `# Connect Make
@@ -6975,7 +6207,7 @@ Complete the remaining module fields from the same API-reference operation:
 
 | Make field | Value to use | Verification |
 | --- | --- | --- |
-| URL | Server origin plus the complete operation path | HTTPS, origin and API prefix each appear once |
+| URL | \`{{APPLICATION_CONNECTION_VALUE:baseUrl}}\` plus the operation's documented path | The scheme, origin and API prefix each appear once |
 | Method | The documented method, initially **GET** | It matches the operation heading |
 | Headers | Add **Accept: application/json** | Authentication remains in **Credentials**, not duplicated here |
 | Query parameters | Only parameters accepted by the operation | Organization and record values are in documented locations |
@@ -7087,7 +6319,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 +6334,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 +6383,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 +6420,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 +6524,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 +6558,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 +6663,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 +6695,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 +6920,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
@@ -7764,13 +7008,13 @@ unclear operation contract.
 
 ## Step 2: send the request once
 
-Replace the two angle-bracket placeholders with the server origin and operation
-path from the same API-reference environment. The generated authorization line
+The origin below is this application's own, so the only thing left to supply is
+the operation path from the API reference and your key. The authorization line
 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 +7104,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"
+~~~
+
+~~~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}}
 ~~~
 
-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.`,
+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="{{APPLICATION_CONNECTION_VALUE:baseUrl}}"          # this application's own origin
+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 organization id and the key with yours; the base URL above is already this application's. 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:
+
+~~~bash
+curl --include \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID" \\
+  --header "Authorization: sk_org_not_a_real_key" \\
+  --header "accept: application/json"
+~~~
 
-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.
+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.
 
-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.
+## If it fails
 
-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.
+| 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.
 
-- [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.`,
+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.
+
+## 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: the organization's subscription does not include the capability, or has reached its limit for it. Changing a role will not clear either one.
 
-### 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}}
 
-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.
+## What you configure
 
-## Split responsibilities deliberately
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#endpointMarkdown}}
 
-| Application sends | Receiver must do |
+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.
+
+## 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
-
-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.
-
-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.
-
-## Prepare the receiver
-
-Before adding 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.
-
-~~~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 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.
 
-## Register the endpoint safely
+## Before you register
 
-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.
+The receiver must:
 
-## Test before enabling delivery
+- 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.
 
-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.
+## Register the endpoint
 
-Interpret the test outcome precisely:
+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.
 
-| 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.
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#endpointMarkdown}}
 
-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.
+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.
 
-Run four checks before enablement:
+## Run the endpoint test
 
-- 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.
+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:
 
-## Enable in stages
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#testOutcomesMarkdown}}
 
-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.
+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.
 
-For the first real event, confirm all of the following:
+Before enabling, make the receiver pass four cases:
 
-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.
+- 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.
 
-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 and confirm the first real event
 
-## Retain safe operating evidence
+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.
 
-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.
+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.
 
-## 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 |
-
-## Understand the delivery states
-
-~~~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 --> [*]
-~~~
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#deliveryStatesMarkdown}}
 
-Read each state as an operating instruction:
+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.
 
-| 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 |
+## The retry ladder
 
-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.
+{{CONSUMER_FACT:source:consumer-fact:outbound-webhooks#retryMarkdown}}
 
-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:
+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.
 
-- 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.
+## Retry a failed delivery
 
-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.
+The retry operation re-queues one \`failed\` row for a fresh attempt with the same \`jti\` and the same body. Before using it:
 
-## Retry deliberately
+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.
 
-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.
+If the receiver already did the work, do not retry to turn the row green; record the mismatch and reconcile through your own process.
 
-Use this decision sequence:
+## Endpoint changes and outages
 
-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.
+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.
 
-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.
+## Retention
 
-## Treat endpoint changes as new operating risk
-
-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.
-
-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.
-
-## Retain evidence without retaining secrets
-
-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.
-
-## Continue safely
-
-- [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 +7826,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 +7911,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 +8078,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 +8096,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 +8152,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": {