Add business-framed Use Cases docs section

fern/docs.yml

@@ -38,6 +38,71 @@ navigation:
         contents:
           - page: Who Uses Schematic
             path: ./docs/pages/using_schematic/who-uses-schematic.mdx
+      - section: Use Cases
+        contents:
+          - page: Overview
+            path: ./docs/pages/use-cases/overview.mdx
+          - section: Product-Led Growth
+            contents:
+              - page: Convert and expand users self-serve
+                path: ./docs/pages/use-cases/self-serve-checkout.mdx
+              - page: Give customers a self-service portal
+                path: ./docs/pages/use-cases/customer-portal.mdx
+              - page: Run free trials
+                path: ./docs/pages/use-cases/free-trials.mdx
+              - page: Price by usage
+                path: ./docs/pages/use-cases/usage-based-pricing.mdx
+              - page: Bill for usage
+                path: ./docs/pages/use-cases/usage-billing.mdx
+              - page: Run credit-based billing
+                path: ./docs/pages/use-cases/credit-billing.mdx
+          - section: Sales-Led Growth
+            contents:
+              - page: Close custom deals
+                path: ./docs/pages/use-cases/custom-deals.mdx
+              - page: Run sales-assisted trials and POCs
+                path: ./docs/pages/use-cases/sales-assisted-trials.mdx
+              - page: Expand accounts with upsells and add-ons
+                path: ./docs/pages/use-cases/expand-accounts.mdx
+          - section: Customer Management
+            contents:
+              - page: Manage exceptions with overrides
+                path: ./docs/pages/use-cases/overrides.mdx
+              - page: Spot churn and expansion with usage signals
+                path: ./docs/pages/use-cases/usage-signals.mdx
+              - page: Stay ahead of renewals and expirations
+                path: ./docs/pages/use-cases/renewals.mdx
+          - section: Operations
+            contents:
+              - page: Reprice and repackage safely
+                path: ./docs/pages/use-cases/plan-versioning.mdx
+              - page: Keep Stripe in sync
+                path: ./docs/pages/use-cases/stripe-sync.mdx
+              - page: Automate with webhooks and AI
+                path: ./docs/pages/use-cases/automation.mdx
+      - section: Playbooks
+        contents:
+          - page: Overview
+            slug: overview
+            path: ./docs/pages/playbooks/overview.mdx
+          - page: Creating a metered feature
+            slug: metering
+            path: ./docs/pages/playbooks/metering.mdx
+          - page: Backfills and usage corrections
+            slug: backfill-and-corrections
+            path: ./docs/pages/playbooks/backfill-and-corrections.mdx
+          - page: Rolling out beta functionality with Flags
+            slug: rollout
+            path: ./docs/pages/playbooks/rollout.mdx
+          - page: Handling customer exceptions and feature trials
+            slug: exceptions
+            path: ./docs/pages/playbooks/exceptions.mdx
+          - page: Automatically provision customers using Stripe
+            slug: provisioning-stripe
+            path: ./docs/pages/playbooks/provisioning-stripe.mdx
+          - page: Build a slack webhook
+            slug: slack-webhook
+            path: ./docs/pages/playbooks/slack-webhook.mdx
       - section: Quickstart
         contents:
           - page: Quickstart
@@ -273,29 +338,6 @@ navigation:
                 path: ./docs/pages/integrations/webhooks-plan-changed.mdx
               - page: Entitlement & Credit Trigger Webhooks
                 path: ./docs/pages/integrations/webhooks-entitlement-triggers.mdx
-      - section: Playbooks
-        contents:
-          - page: Overview
-            slug: overview
-            path: ./docs/pages/playbooks/overview.mdx
-          - page: Creating a metered feature
-            slug: metering
-            path: ./docs/pages/playbooks/metering.mdx
-          - page: Backfills and usage corrections
-            slug: backfill-and-corrections
-            path: ./docs/pages/playbooks/backfill-and-corrections.mdx
-          - page: Rolling out beta functionality with Flags
-            slug: rollout
-            path: ./docs/pages/playbooks/rollout.mdx
-          - page: Handling customer exceptions and feature trials
-            slug: exceptions
-            path: ./docs/pages/playbooks/exceptions.mdx
-          - page: Automatically provision customers using Stripe
-            slug: provisioning-stripe
-            path: ./docs/pages/playbooks/provisioning-stripe.mdx
-          - page: Build a slack webhook
-            slug: slack-webhook
-            path: ./docs/pages/playbooks/slack-webhook.mdx
   - tab: api
     layout:
       - page: Resources

fern/docs/pages/use-cases/automation.mdx

@@ -0,0 +1,24 @@
+---
+title: Automate with webhooks and AI
+slug: use-cases/automation
+description: Drive Slack, CRM, and AI-assisted workflows off Schematic events.
+---
+
+Changes in Schematic often need to kick off work somewhere else. A new company should notify the team, a plan change should update the CRM, usage crossing a limit or credits running low should trigger an alert or an onboarding step.
+
+## Common approaches
+
+Teams usually reach for one of two patterns. Either they poll the API on a schedule, scanning for companies, plans, or usage that changed since the last run, or they bolt notification calls directly onto application code at each spot where something relevant happens, posting to Slack here and updating the CRM there.
+
+Neither holds up well. Polling is wasteful when nothing changed and laggy when something does, and it can't catch events that happen and resolve between runs. Inline notification calls scatter the same concern across the codebase, so it's easy to miss a code path, easy to double-send, and hard to keep consistent as the product grows. In both cases the automation logic is tangled into your application rather than driven cleanly off the events themselves.
+
+## How Schematic fits in
+
+Subscribe to Schematic webhooks for the events you care about, company and plan changes, entitlement and credit triggers, and route them to Slack, your CRM, or any endpoint. For ad-hoc and AI-assisted workflows, the Schematic MCP server lets your team query and manage entitlement data directly from AI tools like Claude, for example pulling a company's usage for a quarterly review.
+
+## Learn more
+
+- [Webhooks](/integrations/webhooks) — the available events and how to set up an endpoint.
+- [Entitlement & Credit Trigger Webhooks](/integrations/webhooks/entitlement-triggers) — fire on usage and limit thresholds.
+- [Build a Slack webhook](/playbooks/slack-webhook) — a worked example routing events to Slack.
+- [MCP Server](/for-developers#model-context-protocol-mcp) — manage entitlement data from AI tools.

fern/docs/pages/use-cases/credit-billing.mdx

@@ -0,0 +1,22 @@
+---
+title: Run credit-based billing
+slug: use-cases/credit-billing
+description: Sell a prepaid credit balance that burns down as customers use features.
+---
+
+Credit models, where customers buy a balance that burns down as they use features, have become a popular way to price AI and consumption products. They unify many features under a single metric, let customers prepay without billing surprises, and make it easy to top up for more.
+
+## Common approaches
+
+Teams typically track a credit balance in their own database, decrement it on every billable action, and build purchase flows so customers can top up when they run low. The core loop, grant some credits, subtract as they're used, block when the balance hits zero, is straightforward to prototype.
+
+The depth shows up in the details. Credits come from different sources, the monthly plan grant, purchased bundles, promotional credits, refunds, and each typically has its own expiration, which forces a decision about which credits burn first. On top of that you need per-feature consumption rates that can change over time, auto top-up so customers don't get cut off mid-task, refunds when an action fails, and a revenue-recognition story finance can trust. Building all of that, and keeping it correct as you add features, is a substantial project in its own right.
+
+## How Schematic fits in
+
+Create a credit type, grant credits on a plan each billing period, and set how many credits each feature consumes. Schematic burns down the balance as features are used, sells top-up bundles through checkout, supports auto top-up so customers don't get interrupted, and handles refunds via negative-quantity events. Customers see their balance in the customer portal, and the credit pricing you set drives revenue recognition.
+
+## Learn more
+
+- [Credit Burndown Billing Model](/billing/credit-burndown) — set up credit types, grants, consumption rates, and bundles.
+- [Usage Based Billing Models](/billing/usage-based-billing) — how credit burndown relates to the other usage models.

fern/docs/pages/use-cases/custom-deals.mdx

@@ -0,0 +1,23 @@
+---
+title: Close custom deals
+slug: use-cases/custom-deals
+description: Package bespoke pricing and entitlements for negotiated contracts without touching code.
+---
+
+Sales-led deals rarely fit neatly into the good-better-best plans on your pricing page. Negotiated contracts come with their own pricing and their own mix of entitlements, and you need to honor them without forking your application for every customer.
+
+## Common approaches
+
+When a deal closes on non-standard terms, the fastest path is usually to add a one-off flag or a special-case config in application code for that account, hard-coding the extra seats, the custom limit, or the feature that isn't in any standard plan. For the first few enterprise deals this feels reasonable and ships quickly.
+
+But each bespoke account adds another branch of logic that only applies to one customer, and there's no single place to see what a given company was actually sold. The terms live in code rather than in your catalog, so auditing what's been promised is hard, changing it at renewal is risky, and the person who negotiated the deal can't adjust it without an engineer. Multiply that across a growing book of custom contracts and it becomes a real maintenance and compliance burden.
+
+## How Schematic fits in
+
+Build a custom plan with the negotiated entitlements and pricing and assign it to the company, or layer per-company overrides on top of a standard plan. Custom plans can be kept off your public pricing table and shown instead with a "talk to us" message, and everything, the entitlements, the pricing, the assignment, is managed from Schematic rather than in code.
+
+## Learn more
+
+- [Configuring the Catalog](/catalog/configuration) — display custom plans and control where they appear.
+- [Managing Company Plans](/catalog/managing-company-plans) — assign a plan to a specific company.
+- [Company Overrides](/feature-management/overrides) — adjust individual entitlements on top of a plan.

fern/docs/pages/use-cases/customer-portal.mdx

@@ -0,0 +1,24 @@
+---
+title: Give customers a self-service portal
+slug: use-cases/customer-portal
+description: One branded place for customers to manage subscriptions, payment, invoices, and usage.
+---
+
+Once customers are paying, they still need to manage their subscription: change plans, update a card, pull an invoice, or check how much of their plan they've used. Every one of those that turns into a support ticket is cost for you and friction for them.
+
+## Common approaches
+
+A common setup sends customers to Stripe's billing portal for invoices and payment methods, then builds separate in-app screens for the things Stripe doesn't know about, like plan changes, add-ons, and usage against limits. Each surface handles part of the job, so the customer bounces between your product and a Stripe-branded page to manage one subscription.
+
+That split is also a maintenance burden. The in-app screens have to be kept consistent with billing, so a plan change made in your UI and a payment-method update made in Stripe's portal can momentarily disagree, and usage shown in-app may not match what's actually being invoiced. As you add plans, add-ons, and usage-based features, every one of these home-grown screens needs to keep up.
+
+## How Schematic fits in
+
+Schematic's customer portal gives customers one branded place to upgrade, downgrade, cancel, manage add-ons, view invoices and payment methods, and watch usage against their limits. Changes sync to Stripe and update entitlements immediately, so access always matches billing. You control which elements appear and how the portal looks in the component builder, no code deploy required.
+
+## Learn more
+
+- [Customer Portal and Checkout Flow](/components/customer-portal) — what the portal covers and how it works with Stripe.
+- [Create a Component](/components/create-component) — build and configure the portal in the component builder.
+- [Add to Your App](/components/set-up) — embed the portal in React, Vue, or plain JS.
+- [Building Your Own Portal](/components/headless-customer-portal) — go headless when you need full control of the UI.

fern/docs/pages/use-cases/expand-accounts.mdx

@@ -0,0 +1,24 @@
+---
+title: Expand accounts with upsells and add-ons
+slug: use-cases/expand-accounts
+description: Grow existing accounts with seats, add-ons, and tier upgrades.
+---
+
+Some of your best revenue comes from accounts you already have. Growing them means adding seats, selling add-ons, or moving a customer up a tier, ideally as a smooth motion rather than a custom project each time.
+
+## Common approaches
+
+Teams often handle expansion as a series of one-off changes: editing a subscription directly in Stripe, manually bumping a seat count, or adding a line item when a customer asks. For a handful of accounts this is perfectly workable, usually a quick task for sales or support.
+
+Handled by hand, though, expansion neither scales nor compounds. There's no consistent place for customers to add what they want themselves, changes made straight in billing can fall out of sync with the access your product actually grants, and every add-on or seat upgrade needs its own manual provisioning. The motion that should be your easiest revenue ends up gated on someone remembering to make the same change in two systems.
+
+## How Schematic fits in
+
+Model add-ons and seat-based entitlements in your catalog once, then let customers add them through the customer portal or have your team assign them to a company directly. Add-ons and seat counts map to Stripe products, so an expansion updates billing and entitlements together and the new access takes effect immediately. Pay-in-advance pricing lets customers buy seats or capacity in defined chunks as they grow.
+
+## Learn more
+
+- [Add Ons](/catalog/add-ons) — package extra features or capacity on top of a plan.
+- [Customer Portal and Checkout Flow](/components/customer-portal) — let customers add seats and add-ons themselves.
+- [Managing Company Plans](/catalog/managing-company-plans) — assign add-ons and plan changes to a specific company.
+- [Usage Based Billing Models](/billing/usage-based-billing) — sell seats and capacity with pay-in-advance pricing.

fern/docs/pages/use-cases/free-trials.mdx

@@ -0,0 +1,22 @@
+---
+title: Run free trials
+slug: use-cases/free-trials
+description: Grant time-limited access and convert trial users cleanly when the trial ends.
+---
+
+Letting prospects try a paid plan before they commit is one of the most reliable ways to convert them, but only if access is granted cleanly for the trial window and handled correctly the moment it ends.
+
+## Common approaches
+
+Teams often hard-code a trial flag with an expiry date, then write logic to grant premium access during the window and revoke it when the clock runs out. It looks simple at first: set a date, check it on each request, and turn the features off when the trial ends.
+
+The edge cases pile up quickly, though. Whether a card is required up front changes what should happen at expiry, convert to paid automatically, or drop to a free tier, and each path needs its own handling. You also have to decide which plan the customer lands on afterward, make sure a trial only applies the first time, and surface trial state in the product so users see how long they have left. Each of these is easy to get subtly wrong, and a missed revocation means customers keep paid access for free.
+
+## How Schematic fits in
+
+Turn on a trial when you create or edit a plan, and Schematic grants that plan's entitlements for the trial period automatically the first time a company is assigned it. In catalog configuration you decide whether payment is required up front, in which case the customer converts to the paid plan automatically, or not, in which case they downgrade to your default plan. The React and Vue SDKs expose trial status and end date, so you can render countdowns and post-trial conversion prompts without extra API calls.
+
+## Learn more
+
+- [Trials](/catalog/trials) — configure trials on a plan and render trial state in your app.
+- [Configuring the Catalog](/catalog/configuration) — set trial rules, including whether payment is required up front.

fern/docs/pages/use-cases/overrides.mdx

@@ -0,0 +1,22 @@
+---
+title: Manage exceptions with overrides
+slug: use-cases/overrides
+description: Adjust a single company's access for trials, goodwill, or in-flight deals.
+---
+
+Individual customers routinely need access that differs from their plan: a goodwill bump after an outage, a temporary trial of a premium feature, or an exception while a deal closes, all without changing the underlying plan.
+
+## Common approaches
+
+The usual fix is to special-case the customer in application code, or to quietly move them onto a different plan that happens to include what they need. Either one resolves the immediate request, so it's tempting to reach for them whenever a one-off comes up.
+
+Both approaches hide the reason the exception exists. A flag buried in code or an off-catalog plan assignment doesn't record that this was a 30-day goodwill grant or a trial tied to an open opportunity, so there's nothing to reverse it when the time is up and nothing to point to when someone asks why this account has access it shouldn't. Customer success can't see or adjust these exceptions without engineering, and over time the accumulated special cases make it genuinely hard to know who has what.
+
+## How Schematic fits in
+
+Apply a company override from the Schematic UI or API to grant or adjust a single company's access to a feature. Overrides can carry an expiration date for time-limited trials, are visible and auditable right on the company, and follow a most-generous policy, so an override never accidentally reduces what a customer's plan already grants. Customer success can manage exceptions without an engineering ticket.
+
+## Learn more
+
+- [Company Overrides](/feature-management/overrides) — apply and manage overrides in the UI and via the API.
+- [Handling customer exceptions and feature trials](/playbooks/exceptions) — a step-by-step playbook, including time-limited overrides.