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

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

@@ -7,9 +7,22 @@
  * 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 = [
     {
@@ -27,6 +40,7 @@ This documentation is for the people who use, administer, integrate with or oper
 
 | You need to | Start here | You will find |
 | --- | --- | --- |
+| 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 |
@@ -34,7 +48,6 @@ This documentation is for the people who use, administer, integrate with or oper
 | Build in n8n, Zapier or Make | [Automation platforms](/integrations/automation-platforms) | The exact settings for each tool |
 | Connect an AI assistant such as Cursor, Codex or Claude Code | [AI coding tools](/integrations/ai-coding-tools) | The MCP connection and what the assistant may do |
 | Investigate who did what, or export security evidence | [Security and audit](/security-and-audit) | The audit trail, exports and delivery to your SIEM |
-| Understand a plan, an invoice or why access changed | [Billing and subscriptions](/billing-and-subscriptions) | How billing state turns into access, and how to reconcile a change |
 | Look up one operation, field or role | [API reference](/api) | The exact contract of every operation, generated from the application itself |
 
 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.
@@ -54,6 +67,45 @@ Sections appear in the navigation only when this application offers the capabili
 ## When you ask for help
 
 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
+
+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.
+
+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.
+
+## What it manages
+
+{{APPLICATION_DOMAIN:domainOverview}}
+
+## Each one in detail
+
+{{APPLICATION_DOMAIN:domainResourceDetails}}
+
+## Where to go next
+
+| 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',
@@ -1663,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
@@ -1739,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
@@ -3524,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
@@ -3599,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
@@ -3706,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
@@ -4455,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
@@ -5411,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',
@@ -5509,913 +5652,6 @@ change the application's authoritative audit retention.
 - remove temporary local copies and ticket attachments that are no longer
   required;
 - 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:
-
-- 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.
-
-| 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}}
-
-## Keep the four billing views separate
-
-| View | Question it answers | Do not use it as proof of |
-| --- | --- | --- |
-| 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.
-
-~~~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
-~~~
-
-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
-
-| 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
-
-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.
-
-| 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 |
-
-## Start from the work, not the plan name
-
-Write down the outcome before comparing offers—for example, “the Support
-organization needs ten additional automated runs this month.” Then ask:
-
-- 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?
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#productTypesMarkdown}}
-
-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.
-
-## Understand how quantity changes the amount
-
-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.
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#pricingModelsMarkdown}}
-
-### Worked example: 240 units
-
-The following numbers are illustrative, not an offer from this application.
-They show why the pricing model must be recorded with the amount:
-
-| Model | Illustrative terms | Result for 240 units |
-| --- | --- | --- |
-| 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
-
-~~~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"]
-~~~
-
-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
-
-{{CONSUMER_FACT:source:consumer-fact:billing-lifecycle#promotionVocabularyMarkdown}}
-
-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.
-
-## Approve with a reviewable record
-
-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.`,
-    },
-    {
-        managedPath: 'billing-and-subscriptions/start-subscription.md',
-        unitRef: 'technical-documentation:unit/start-billing-subscription',
-        sourceRefs: [
-            'saas-technical-doc:engine-content/start-billing-subscription',
-        ],
-        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.
-
-| 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 |
-
-> **One checkout attempt can complete even when the browser never returns.**
-> Keep its identifiers and reconcile the application state before opening a
-> replacement checkout.
-
-## Before checkout
-
-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.
-
-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.
-
-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.
-
-~~~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
-~~~
-
-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.
-
-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.
-
-## Confirm success
-
-Do not use the success URL as the success criterion. In the application, verify:
-
-- 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:
-
-The subscription states and what each one means for access are listed under
-[Reconcile access after a billing change](/billing-and-subscriptions/reconcile-access).
-
-If the state remains incomplete, past due, unpaid or absent, do not create a
-second checkout immediately. Use the troubleshooting and reconciliation pages
-to determine whether the first attempt is still being processed.
-
-### Example: the browser closes after payment
-
-Suppose an administrator approves a paid plan, completes the hosted
-payment, and the browser closes before returning. Reopen Billing in the same
-organization and read the current subscription. If the approved plan is Active
-and the expected limit works, record that result and close the task. If the
-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
-
-The figures below are illustrative; your own limits are shown in Billing.
-Suppose an organization's plan allows 50 automated runs and it needs 20 more
-immediately. Before confirming an add-on, record:
-
-- the current 50-run limit and current billing-period end;
-- the add-on price and whether the presented adjustment is immediate;
-- 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
-
-This page applies only if a plan or add-on you hold charges for a measured
-quantity. If everything you subscribe to is a flat recurring price, no usage is
-recorded and no usage line appears on an invoice — check
-[Understand plans, prices and access](/billing-and-subscriptions/plans-and-access)
-to see which of the two you have.
-
-A metered product charges for a measured quantity, such as processed documents,
-automated runs or storage consumed. The application records the activity first;
-the billing provider receives grouped usage later and uses its configured meter
-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',
-        ],
-        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:
-
-The full list of subscription states, and what each one means for access, is under
-[Reconcile access after a billing change](/billing-and-subscriptions/reconcile-access).
-
-## Start from the symptom
-
-| 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',
@@ -6564,6 +5800,7 @@ business effect occurred without blindly repeating it.`,
         unitRef: 'technical-documentation:unit/connect-n8n',
         sourceRefs: [
             'saas-technical-doc:engine-content/connect-n8n',
+            'source:companion-projection:application-connection',
             'source:consumer-fact:access-api-keys',
         ],
         markdown: `# Connect n8n
@@ -6613,7 +5850,7 @@ 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 |
@@ -6749,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
@@ -6809,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 |
@@ -6917,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
@@ -6968,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 |
@@ -7769,8 +7008,8 @@ 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
@@ -8024,7 +7263,7 @@ Give the request a name in your notes before you send it. "List the members of t
 The safest first call reads the organization the key belongs to. It needs no other identifier and changes nothing.
 
 ~~~bash
-BASE_URL="https://api.example.com"          # from the API reference's Servers list
+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
 
@@ -8034,7 +7273,7 @@ curl --fail-with-body \\
   --header "accept: application/json"
 ~~~
 
-Replace the three values with yours; leave the header exactly as shown. {{CONSUMER_FACT:source:consumer-fact:access-api-keys#markdown}}
+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}}
 
 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.
 
@@ -8264,7 +7503,7 @@ The application knows who is calling and refuses this operation in this scope.
 
 - Compare the roles on the key with the roles the operation lists in the API reference.
 - A collection under an organization the key is not a member of is refused with 403; confirm the organization identifier.
-- \`FEATURE_NOT_AVAILABLE\` and \`FEATURE_LIMIT_EXCEEDED\` are plan refusals, not role refusals; see [Plans and access](/billing-and-subscriptions/plans-and-access).
+- \`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.
 
 ## 404: the record is not visible here