@lukoweb/apitogo 0.2.30 → 0.2.34

package/docs/cli/go-live.md

@@ -1,123 +1,135 @@
----
-title: Go live with CLI
-description:
-  Publish an APIToGo developer portal with npx apitogo deploy — platform plans, secrets, and status.
-sidebar_icon: rocket
----
-
-**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
-gateway plans, and verifies the live site. `npx apitogo deploy` is the source of truth; MCP
-`publish_dev_portal` spawns the same CLI.
-
-## Before you publish
-
-1. Confirm **gateway / API plans** in `apitogo.config.json`. Do not invent Free + Pro unless you
-   chose them.
-2. Save secrets in the site **`.env`** (never commit or paste into tickets):
-
-   ```sh
-   APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
-   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
-   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
-   # Only when you have paid project plans:
-   APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
-   APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
-   ```
-
-3. Export platform credentials and choose a **platform hosting** plan: **Free**, **Starter**, or
-   **Professional**. Starter and Professional use Stripe checkout on the platform.
-
-   **Free** cannot publish **paid gateway plans** (`priceAmount > 0`) or attach a **custom domain**.
-   If your manifest has paid API tiers, use Starter or Professional — see
-   [Gateway plans](../configuration/plans.md).
-
-   ```bash
-   export APITOGO_API_KEY_ID=apk_...
-   export APITOGO_API_SECRET=...
-   ```
-
-## Happy path
-
-```bash
-cd ./dev-portal
-npx apitogo deploy --platform-plan free
-npx apitogo status
-```
-
-`npx apitogo deploy`:
-
-- Creates or links the platform project
-- Provisions modules and syncs gateway plans
-- Deploys the API hub (when configured)
-- Updates the portal backend (including auth API URL in `.env`) and builds + deploys the portal
-  frontend
-
-If deploy is blocked, fix the reported checklist (missing secrets, plan, OpenAPI). Do not invent
-credentials.
-
-After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When Stripe is required for
-paid gateway plans, create a webhook at `manualSteps.stripeWebhookUrl` for the listed events.
-
-Do not treat warm-pool URLs as live until deploy and status succeed.
-
-## Target specific resources
-
-```bash
-npx apitogo deploy --only apihub
-npx apitogo deploy --only portal-backend
-npx apitogo deploy --only portal-frontend
-npx apitogo deploy --only apihub,portal-frontend
-npx apitogo deploy --only portal-frontend --force
-```
-
-| Resource          | What it updates                                  |
-| ----------------- | ------------------------------------------------ |
-| `apihub`          | Gateway plans/baseline, API hub package + deploy |
-| `portal-backend`  | Dev-portal module settings and plan catalog      |
-| `portal-frontend` | Site build + Static Web App deploy               |
-
-Omit `--only` to apply all three. Use `--force` to redeploy even when hashes match.
-
-## Other deploy flags
-
-| Flag              | Purpose                               |
-| ----------------- | ------------------------------------- |
-| `--project-id`    | Override project GUID                 |
-| `--project-name`  | Display name when creating a project  |
-| `--platform-plan` | `free` \| `starter` \| `professional` |
-| `--resume-from`   | Resume publish ledger from step id    |
-| `--no-wait`       | Do not wait for long-running jobs     |
-| `--json`          | Print raw JSON result only            |
-
-Resume state is stored in `.apitogo/publish-state.json`.
-
-## After publish
-
-```bash
-npx apitogo status              # account + project + live checks
-npx apitogo status --skip-live  # skip live health probes
-npx apitogo teardown --yes      # delete the platform project
-```
-
-## Platform plan vs API plans
-
-| Kind             | Meaning                                     | How                                                                |
-| ---------------- | ------------------------------------------- | ------------------------------------------------------------------ |
-| Platform hosting | Free / Starter / Professional on APItoGo    | `--platform-plan`                                                  |
-| Gateway / API    | End-user SKUs and rate limits on `/pricing` | `apitogo.config.json` — [Gateway plans](../configuration/plans.md) |
-
-## CLI deploy vs MCP publish
-
-| Path                     | Use when                                     |
-| ------------------------ | -------------------------------------------- |
-| `npx apitogo deploy`     | Terminal, CI, scripts — full product go-live |
-| MCP `publish_dev_portal` | Agent-driven go-live with the same engine    |
-
-## Related
-
-- [Shape](./shape.md)
-- [Commands](./commands.md)
-- [Authentication](../configuration/authentication.md)
-- [Manifest](../configuration/manifest.md)
-- [Gateway plans](../configuration/plans.md)
-- [MCP go live](../mcp/go-live.md)
+---
+title: Go live with CLI
+description:
+  Publish an APIToGo developer portal with npx apitogo deploy — platform plans, secrets, and status.
+sidebar_icon: rocket
+---
+
+**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
+gateway plans, and verifies the live site. `npx apitogo deploy` is the source of truth; MCP
+`publish_dev_portal` spawns the same CLI.
+
+:::note
+
+This page describes **config version 1** projects (the older `dev-portal` scaffold). A config
+version 2 project, which `npx @lukoweb/apitogo@latest init` creates by default, is published
+differently: run `npx apitogo project create`, then `npx apitogo deploy`. Its resources are
+`portal`, `gateway`, `identity` and `plans`, and the options `--platform-plan` and `--project-name`
+do not apply. See [Walkthrough: from an empty folder to a customer's first call](./walkthrough.md)
+and
+[Config version 2: create the project, then deploy](./commands.md#config-version-2-create-the-project-then-deploy).
+
+:::
+
+## Before you publish
+
+1. Confirm **gateway / API plans** in `apitogo.config.json`. Do not invent Free + Pro unless you
+   chose them.
+2. Save secrets in the site **`.env`** (never commit or paste into tickets):
+
+   ```sh
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
+   APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
+   # Only when you have paid project plans:
+   APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
+   APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
+   ```
+
+3. Export platform credentials and choose a **platform hosting** plan: **Free**, **Starter**, or
+   **Professional**. Starter and Professional use Stripe checkout on the platform.
+
+   **Free** cannot publish **paid gateway plans** (`priceAmount > 0`) or attach a **custom domain**.
+   If your manifest has paid API tiers, use Starter or Professional — see
+   [Gateway plans](../configuration/plans.md).
+
+   ```bash
+   export APITOGO_API_KEY_ID=apk_...
+   export APITOGO_API_SECRET=...
+   ```
+
+## Happy path
+
+```bash
+cd ./dev-portal
+npx apitogo deploy --platform-plan free
+npx apitogo status
+```
+
+`npx apitogo deploy`:
+
+- Creates or links the platform project
+- Provisions modules and syncs gateway plans
+- Deploys the API hub (when configured)
+- Updates the portal backend (including auth API URL in `.env`) and builds + deploys the portal
+  frontend
+
+If deploy is blocked, fix the reported checklist (missing secrets, plan, OpenAPI). Do not invent
+credentials.
+
+After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When Stripe is required for
+paid gateway plans, create a webhook at `manualSteps.stripeWebhookUrl` for the listed events.
+
+Do not treat warm-pool URLs as live until deploy and status succeed.
+
+## Target specific resources
+
+```bash
+npx apitogo deploy --only apihub
+npx apitogo deploy --only portal-backend
+npx apitogo deploy --only portal-frontend
+npx apitogo deploy --only apihub,portal-frontend
+npx apitogo deploy --only portal-frontend --force
+```
+
+| Resource          | What it updates                                  |
+| ----------------- | ------------------------------------------------ |
+| `apihub`          | Gateway plans/baseline, API hub package + deploy |
+| `portal-backend`  | Dev-portal module settings and plan catalog      |
+| `portal-frontend` | Site build + Static Web App deploy               |
+
+Omit `--only` to apply all three. Use `--force` to redeploy even when hashes match.
+
+## Other deploy flags
+
+| Flag              | Purpose                               |
+| ----------------- | ------------------------------------- |
+| `--project-id`    | Override project GUID                 |
+| `--project-name`  | Display name when creating a project  |
+| `--platform-plan` | `free` \| `starter` \| `professional` |
+| `--resume-from`   | Resume publish ledger from step id    |
+| `--no-wait`       | Do not wait for long-running jobs     |
+| `--json`          | Print raw JSON result only            |
+
+Resume state is stored in `.apitogo/publish-state.json`.
+
+## After publish
+
+```bash
+npx apitogo status              # account + project + live checks
+npx apitogo status --skip-live  # skip live health probes
+npx apitogo teardown --yes      # delete the platform project
+```
+
+## Platform plan vs API plans
+
+| Kind             | Meaning                                     | How                                                                |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------ |
+| Platform hosting | Free / Starter / Professional on APItoGo    | `--platform-plan`                                                  |
+| Gateway / API    | End-user SKUs and rate limits on `/pricing` | `apitogo.config.json` — [Gateway plans](../configuration/plans.md) |
+
+## CLI deploy vs MCP publish
+
+| Path                     | Use when                                     |
+| ------------------------ | -------------------------------------------- |
+| `npx apitogo deploy`     | Terminal, CI, scripts — full product go-live |
+| MCP `publish_dev_portal` | Agent-driven go-live with the same engine    |
+
+## Related
+
+- [Shape](./shape.md)
+- [Commands](./commands.md)
+- [Authentication](../configuration/authentication.md)
+- [Manifest](../configuration/manifest.md)
+- [Gateway plans](../configuration/plans.md)
+- [MCP go live](../mcp/go-live.md)

package/docs/cli/walkthrough.md

@@ -108,7 +108,46 @@ What the gateway answers:
 The customer sees their calls on the **Usage** page. See
 [Your customers' account pages](../guides/customer-account.md).
 
-## 5. Remove a test project
+## 5. Sell a paid plan (optional)
+
+Free plans need no payment. To charge your customers, the project needs two things: a Starter or
+Professional plan with APItoGo, and your own Stripe account. Your customers pay you, not APItoGo.
+
+1. Create the project on a paid platform plan: `npx apitogo project create --plan starter`. This
+   opens the platform's checkout for the hosting fee. A project that already exists on the Free plan
+   cannot be moved: create a new one. See
+   [Selling paid plans needs Starter or Professional](./commands.md#selling-paid-plans-needs-starter-or-professional).
+2. In your Stripe account, copy the secret key (it starts with `sk_test_` while you test). Store it
+   as a project secret. The command asks for the value, so it stays out of the config:
+
+   ```bash
+   npx apitogo secrets set STRIPE_KEY
+   ```
+
+3. Turn billing on in `apitogo.config.json`:
+
+   ```json
+   "plans": {
+     "billing": { "provider": "stripe", "apiKey": "secret:STRIPE_KEY" }
+   }
+   ```
+
+4. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
+   `"billingPeriod": "month"`. Its limits cannot be higher than your platform plan allows. A plan
+   with a price is refused while billing is off, so nobody is offered a plan they cannot pay for.
+5. Deploy: `npx apitogo deploy`. The output says whether Stripe is in test or live mode and prints
+   your portal's webhook address.
+6. In Stripe, add that address as a webhook endpoint with the events `checkout.session.completed`,
+   `customer.subscription.updated`, `customer.subscription.deleted` and `invoice.payment_failed`.
+   Copy the signing secret (it starts with `whsec_`), store it with
+   `npx apitogo secrets set STRIPE_WEBHOOK`, add `"webhookSecret": "secret:STRIPE_WEBHOOK"` next to
+   `apiKey`, and deploy again. Until then a payment does not activate the plan, because the portal
+   cannot confirm it came from Stripe.
+
+While you use a test key, pay with [Stripe's test cards](https://docs.stripe.com/testing). No real
+money moves. Never type a live key until you have tested the whole path.
+
+## 6. Remove a test project
 
 ```bash
 npx apitogo teardown --yes

package/docs/configuration/gateway.md

@@ -194,6 +194,53 @@ npx apitogo secrets set GATEWAY_SECRET
 The value is a reference, never the secret itself. The secret is stored encrypted and never shown
 again. Then make your API refuse any call without that header.
 
+## Run your API on the platform (`managed` origin)
+
+If you have no place to host your API, the platform can run your code. Set the origin mode to
+`managed` and point `source` at the folder with your code:
+
+```json
+"gateway": {
+  "origin": {
+    "mode": "managed",
+    "source": "backend",
+    "runtime": "nodejs",
+    "runtimeVersion": "NODE_22_LTS",
+    "healthPath": "/health",
+    "exclude": ["tests/"]
+  },
+  "specs": ["openapi.json"]
+}
+```
+
+| Field            | Meaning                                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `source`         | Folder with your code, relative to the config. Files in its `.gitignore` and in `exclude` are not uploaded. |
+| `runtime`        | `nodejs`, `python` or `dotnet`.                                                                             |
+| `runtimeVersion` | For example `NODE_22_LTS`. The platform lists the allowed values.                                           |
+| `healthPath`     | Path the platform probes to check that your API is up.                                                      |
+| `exclude`        | More paths to leave out, in `.gitignore` syntax.                                                            |
+
+`npx apitogo project create` prepares the hosting for your code. `npx apitogo deploy` then uploads
+the OpenAPI file and the config, uploads your code and waits until it runs, and the gateway starts
+sending calls to it. A deploy with the same code uploads nothing. A .NET project is published for
+you (this needs the .NET SDK on your machine), or you can point `source` at a folder that is already
+published.
+
+Your code can also be reached by its own address, so check that a call came through the gateway. The
+platform gives your code two settings for this: `APITOGO_ORIGIN_SECRET_HEADER` (the header name) and
+`APITOGO_ORIGIN_SECRET` (the value). The gateway sends that header with every call. Refuse any
+request without it, as in
+[Keep your API from being called directly](#keep-your-api-from-being-called-directly):
+
+```js
+const header = process.env.APITOGO_ORIGIN_SECRET_HEADER.toLowerCase();
+if (req.headers[header] !== process.env.APITOGO_ORIGIN_SECRET) {
+  res.writeHead(403).end();
+  return;
+}
+```
+
 ## 4. Try it and check it
 
 Run these before you deploy:
@@ -219,3 +266,8 @@ curl -i https://YOUR-GATEWAY-ADDRESS/orders
 | `404`                           | The path is not in your OpenAPI file.                         |
 | `429`                           | The rate limit was reached.                                   |
 | `502` or `504`                  | Your API did not answer. Check `origin.url` and `healthPath`. |
+
+A change is live a few seconds after `deploy` reports it ready: the gateway keeps answering with the
+previous rules for up to about ten seconds. If a test right after a deploy shows the old behavior,
+wait a moment and try again. The same delay applies when you remove a gateway: its keys stop working
+within seconds, not at the same instant.

package/docs/guides/customer-account.md

@@ -28,7 +28,37 @@ The plans come from `plans.json`. A plan has a name, limits, and optionally a pr
 subscribes to a plan and may hold more than one. Unsubscribing from a plan stops that plan's keys
 from working and keeps the customer's other plans.
 
-Free plans work without any payment. For paid plans see the `plans.billing` setting.
+Free plans work without any payment. For paid plans see
+[Sell a paid plan](../cli/walkthrough.md#5-sell-a-paid-plan-optional).
+
+### Paying for a plan
+
+A plan with a price sends the customer to Stripe's checkout page. The portal never sees the card
+details.
+
+1. The customer chooses the plan and pays on Stripe's page.
+2. Stripe returns the customer to **Billing**. The page says it is confirming the payment for a few
+   seconds, because Stripe tells the portal separately. Then the plan is active and the customer can
+   create a key for it.
+3. If the customer closes the checkout or goes back, the **Plans** page says checkout was cancelled
+   and nothing was charged.
+
+If a payment fails, Stripe retries it. The subscription shows as past due. When Stripe finally
+cancels it, the plan ends and its keys stop working with `401`. The customer is not moved to a free
+plan on their own. They can subscribe to one on the **Plans** page.
+
+## Cancelling and refunds
+
+- **The customer cancels** on the **Plans** page. The subscription ends in Stripe at once, the plan
+  ends and the customer's keys stop working with `401`.
+- **You cancel** a subscription in your Stripe dashboard. Stripe tells the portal, and the plan ends
+  the same way.
+- **A refund** is made in your Stripe dashboard. A refund alone does not end the plan: the customer
+  keeps the key until the subscription is cancelled. Cancel it as well if the customer should lose
+  access. The portal has no refund screen.
+
+What you see is in your own Stripe account: payments, customers and refunds. APItoGo does not take a
+share and does not issue refunds. Tax and trials are not handled by the portal.
 
 ## API keys
 
@@ -59,9 +89,10 @@ the customer calls, those calls show as errors in the usage page.
 
 | What the customer sees                        | What to check                                                                                     |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `401` with a key that should work             | The key was revoked, or the plan was cancelled. Check the key on the API keys page.               |
+| `401` with a key that should work             | The key was revoked, or the plan was cancelled or its payment ended. Check the API keys page.     |
 | `401` on a project you set up by hand         | `gateway.policies.access`: when it also requires a login token, a key alone is refused.           |
 | `429`                                         | The plan's limit was reached. The rate limit renews each period; the quota carries `Retry-After`. |
+| A customer paid but has no plan               | The webhook is missing or its signing secret is wrong. Check it in Stripe and in `plans.billing`. |
 | The usage page shows nothing after real calls | Calls only count when made with a key. Check that the gateway has been deployed with plans.       |
 | Calls from the portal's own pages are blocked | Run `npx apitogo deploy` again. The gateway lists the portal's address after the portal exists.   |
 

package/docs/mcp/tools.md

@@ -1,102 +1,101 @@
----
-title: MCP tools
-description: APItoGo MCP tool catalog by category and hand-edit exceptions.
-sidebar_icon: wrench
----
-
-Tools are exposed by the APItoGo MCP server. Prefer **`apply_product_intent`** for create / shape /
-go-live. Use granular tools for advanced edits, debugging, or CI.
-
-## Lifecycle (prefer these)
-
-| Tool                                 | Role                                           |
-| ------------------------------------ | ---------------------------------------------- |
-| `apply_product_intent`               | Shape or goLive from a product intent          |
-| `create_dev_portal`                  | Scaffold site (+ optional project bootstrap)   |
-| `check_dev_portal_publish_readiness` | Pre-publish checklist                          |
-| `publish_dev_portal`                 | Publish portal + plans (+ optional backend)    |
-| `verify_dev_portal_live`             | Post-publish verification                      |
-| `bootstrap_dev_portal`               | CI one-shot provision + deploy                 |
-| `bootstrap_project`                  | Create platform project only (plan unselected) |
-| `teardown_project`                   | Tear down a project                            |
-
-## Site shaping
-
-| Tool                               | Role                                                                      |
-| ---------------------------------- | ------------------------------------------------------------------------- |
-| `update_dev_portal_manifest`       | Plans, branding, backend, projectId                                       |
-| `set_dev_portal_openapi`           | OpenAPI / API reference                                                   |
-| `set_dev_portal_theme`             | Colors and fonts                                                          |
-| `add_dev_portal_page`              | Add a TSX docs page (site components; `template`: docs\|guide\|marketing) |
-| `update_dev_portal_page`           | Edit a docs page                                                          |
-| `scaffold_dev_portal_landing_page` | Scaffold missing landing file                                             |
-| `get_dev_portal_landing_guide`     | Landing component catalog                                                 |
-| `preview_dev_portal_site`          | Start / restart local preview                                             |
-| `build_dev_portal_site`            | Production build                                                          |
-
-Hosted page CRUD also exists (`list/create/delete/rename/reorder_dev_portal_pages`) for the platform
-API surface.
-
-## Projects and platform billing
-
-| Tool                                        | Role                                  |
-| ------------------------------------------- | ------------------------------------- |
-| `whoami`, `list_projects`, `get_project`, … | Tenant / project CRUD                 |
-| `list_platform_plans`                       | Free / Starter / Professional + quota |
-| `ensure_platform_plan`                      | Select or checkout platform plan      |
-| `wait_for_platform_plan`                    | Poll until active                     |
-| `get_subscription`                          | Current subscription                  |
-| `select_free_plan`                          | Free hosting                          |
-| `create_checkout_session`                   | Stripe checkout for paid hosting      |
-
-## Backend and OpenAPI
-
-| Tool                    | Role                     |
-| ----------------------- | ------------------------ |
-| `validate_openapi`      | Validate OpenAPI         |
-| `update_openapi`        | Update stored OpenAPI    |
-| `package_backend`       | Package backend artifact |
-| `deploy_backend`        | Deploy API hub           |
-| `get_backend_summary`   | Backend status           |
-| `get_deployment_status` | Deployment job status    |
-| `get_gateway_readiness` | Gateway readiness        |
-
-## Gateway
-
-| Tool                                                               | Role                     |
-| ------------------------------------------------------------------ | ------------------------ |
-| `list/get/create/update/patch_gateway_plan`                        | Plan CRUD                |
-| `add_actions_to_gateway_plan` / `remove_actions_from_gateway_plan` | Attach ops               |
-| `set_action_public`                                                | Public routes            |
-| `upsert_entitlement`                                               | Entitlements             |
-| `configure_gateway_baseline`                                       | Baseline policies        |
-| `get/update_gateway_settings`                                      | Settings                 |
-| `get/update_gateway_auth`                                          | Gateway auth             |
-| `sync_gateway_plans_from_manifest`                                 | Post-publish action sync |
-| `reorder_gateway_plans_from_manifest`                              | Plan order               |
-
-## Infrastructure and deploy
-
-| Tool                                                   | Role             |
-| ------------------------------------------------------ | ---------------- |
-| `activate_module`                                      | Activate modules |
-| `get_infrastructure_status` / Azure variants           | Infra status     |
-| `list_provisioning_jobs`, `wait_for_job`               | Jobs             |
-| `get_deployment_token`                                 | CLI deploy token |
-| `get/set/delete_custom_domain`                         | Custom domain    |
-| `get_dev_portal_deploy_config`, `deploy_dev_portal`, … | SWA deploy       |
-
-## Hand-edit exceptions
-
-| Change            | Where                                                    |
-| ----------------- | -------------------------------------------------------- |
-| Home page content | `landing/LandingPage.tsx`                                |
-| Site footer       | `apitogo.config.json` → `modules.landing.content.footer` |
-
-There is **no** `update_dev_portal_landing` tool for arbitrary home content.
-
-## Related
-
-- [Overview](./overview.md)
-- [Shape](./shape.md)
-- [Go live](./go-live.md)
+---
+title: MCP tools
+description: APItoGo MCP tool catalog by category and hand-edit exceptions.
+sidebar_icon: wrench
+---
+
+Tools are exposed by the APItoGo MCP server. Prefer **`apply_product_intent`** for create / shape /
+go-live. Use granular tools for advanced edits, debugging, or CI.
+
+## Lifecycle (prefer these)
+
+| Tool                                 | Role                                           |
+| ------------------------------------ | ---------------------------------------------- |
+| `apply_product_intent`               | Shape or goLive from a product intent          |
+| `create_dev_portal`                  | Scaffold site (+ optional project bootstrap)   |
+| `check_dev_portal_publish_readiness` | Pre-publish checklist                          |
+| `publish_dev_portal`                 | Publish portal + plans (+ optional backend)    |
+| `verify_dev_portal_live`             | Post-publish verification                      |
+| `bootstrap_dev_portal`               | CI one-shot provision + deploy                 |
+| `bootstrap_project`                  | Create platform project only (plan unselected) |
+| `teardown_project`                   | Tear down a project                            |
+
+## Site shaping
+
+| Tool                               | Role                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------- |
+| `update_dev_portal_manifest`       | Plans, branding, backend, projectId                                       |
+| `set_dev_portal_openapi`           | OpenAPI / API reference                                                   |
+| `set_dev_portal_theme`             | Colors and fonts                                                          |
+| `add_dev_portal_page`              | Add a TSX docs page (site components; `template`: docs\|guide\|marketing) |
+| `update_dev_portal_page`           | Edit a docs page                                                          |
+| `scaffold_dev_portal_landing_page` | Scaffold missing landing file                                             |
+| `get_dev_portal_landing_guide`     | Landing component catalog                                                 |
+| `preview_dev_portal_site`          | Start / restart local preview                                             |
+| `build_dev_portal_site`            | Production build                                                          |
+
+Hosted page CRUD also exists (`list/create/delete/rename/reorder_dev_portal_pages`) for the platform
+API surface.
+
+## Projects and platform billing
+
+| Tool                                        | Role                                  |
+| ------------------------------------------- | ------------------------------------- |
+| `whoami`, `list_projects`, `get_project`, … | Tenant / project CRUD                 |
+| `list_platform_plans`                       | Free / Starter / Professional + quota |
+| `ensure_platform_plan`                      | Select or checkout platform plan      |
+| `wait_for_platform_plan`                    | Poll until active                     |
+| `get_subscription`                          | Current subscription                  |
+| `select_free_plan`                          | Free hosting                          |
+| `create_checkout_session`                   | Stripe checkout for paid hosting      |
+
+## Backend and OpenAPI
+
+| Tool                    | Role                     |
+| ----------------------- | ------------------------ |
+| `validate_openapi`      | Validate OpenAPI         |
+| `update_openapi`        | Update stored OpenAPI    |
+| `package_backend`       | Package backend artifact |
+| `deploy_backend`        | Deploy API hub           |
+| `get_backend_summary`   | Backend status           |
+| `get_deployment_status` | Deployment job status    |
+| `get_gateway_readiness` | Gateway readiness        |
+
+## Gateway
+
+| Tool                                                               | Role                     |
+| ------------------------------------------------------------------ | ------------------------ |
+| `list/get/create/update/patch_gateway_plan`                        | Plan CRUD                |
+| `add_actions_to_gateway_plan` / `remove_actions_from_gateway_plan` | Attach ops               |
+| `set_action_public`                                                | Public routes            |
+| `upsert_entitlement`                                               | Entitlements             |
+| `configure_gateway_baseline`                                       | Baseline policies        |
+| `get/update_gateway_settings`                                      | Settings                 |
+| `get/update_gateway_auth`                                          | Gateway auth             |
+| `sync_gateway_plans_from_manifest`                                 | Post-publish action sync |
+| `reorder_gateway_plans_from_manifest`                              | Plan order               |
+
+## Infrastructure and deploy
+
+| Tool                                                   | Role             |
+| ------------------------------------------------------ | ---------------- |
+| `activate_module`                                      | Activate modules |
+| `get_infrastructure_status` / Azure variants           | Infra status     |
+| `list_provisioning_jobs`, `wait_for_job`               | Jobs             |
+| `get/set/delete_custom_domain`                         | Custom domain    |
+| `get_dev_portal_deploy_config`, `deploy_dev_portal`, … | SWA deploy       |
+
+## Hand-edit exceptions
+
+| Change            | Where                                                    |
+| ----------------- | -------------------------------------------------------- |
+| Home page content | `landing/LandingPage.tsx`                                |
+| Site footer       | `apitogo.config.json` → `modules.landing.content.footer` |
+
+There is **no** `update_dev_portal_landing` tool for arbitrary home content.
+
+## Related
+
+- [Overview](./overview.md)
+- [Shape](./shape.md)
+- [Go live](./go-live.md)