@lukoweb/apitogo 0.2.23 → 0.2.25

package/docs/cli/go-live.md

@@ -1,123 +1,123 @@
----
-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.
+
+## 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/overview.md

@@ -1,91 +1,91 @@
----
-title: CLI overview
-description:
-  Use the APItoGo CLI to scaffold, shape, preview, and publish API products without an AI agent.
-sidebar_icon: terminal
----
-
-The **`apitogo`** CLI lets you manage developer portals from the terminal. You scaffold and shape
-local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
-`npx apitogo deploy`.
-
-**First time?** Install and wire credentials → **[Install the CLI](./setup.md)**. Then follow
-[Shape](./shape.md) and [Go live](./go-live.md).
-
-## What you get
-
-- Scaffold a local portal site (`npx @lukoweb/apitogo@latest init`)
-- Shape backend, OpenAPI, plans, and docs pages via `npx apitogo config` and file edits
-- Preview locally (`npx apitogo run`)
-- Publish to APItoGo hosting (`npx apitogo deploy`) with platform plans **Free**, **Starter**, or
-  **Professional**
-- Check live status (`npx apitogo status`) and tear down (`npx apitogo teardown --yes`)
-
-## Prerequisites
-
-### Shell environment (for deploy / status / teardown)
-
-| Variable             | Required | Purpose           |
-| -------------------- | -------- | ----------------- |
-| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
-| `APITOGO_API_SECRET` | Yes      | Platform API auth |
-
-### Local machine
-
-- Node.js 20+ (scaffold, build, preview)
-- Network access to the npm registry during install/build
-- OIDC credentials at publish time (site `.env` only — never in shell history for sharing)
-- Stripe secrets at publish only when you have **paid** project plans
-
-## Changing your site
-
-| Approach                 | When it helps                                                                                                                     |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| **`npx apitogo config`** | Wire OpenAPI, custom pages, gateway plans, and site title from the terminal. See [Make config](../configuration/make-config.mdx). |
-| **Edit files directly**  | Full control — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc.                                                 |
-
-Common CLI shape tasks:
-
-| Change                            | How                                               |
-| --------------------------------- | ------------------------------------------------- |
-| Backend runtime                   | `npx apitogo config` (backend)                    |
-| OpenAPI + API Reference nav       | `npx apitogo config` (openapi)                    |
-| Custom docs pages                 | `npx apitogo config` (page) or add under `pages/` |
-| Gateway / API plans               | `npx apitogo config` (plan) or edit manifest      |
-| Site title                        | `--title` or edit `apitogo.config.json`           |
-| Theme, fonts, branding, projectId | Edit `apitogo.config.json`                        |
-
-Home page content often lives in `landing/LandingPage.tsx`. Site footer can live under
-`modules.landing.content.footer` in `apitogo.config.json`.
-
-## Config model (local site)
-
-| File                  | Role                                  |
-| --------------------- | ------------------------------------- |
-| `apitogo.config.json` | Site, modules, plans, auth type, apis |
-| `.env`                | `VITE_*` + `APITOGO_CONFIG_*` secrets |
-
-Details: [Manifest](../configuration/manifest.md).
-
-## CLI vs MCP
-
-Both paths use the same config-first model. `npx apitogo deploy` runs the same engine as MCP
-`publish_dev_portal`.
-
-| Task              | CLI                                           | MCP (agent)                                   |
-| ----------------- | --------------------------------------------- | --------------------------------------------- |
-| Scaffold          | `npx @lukoweb/apitogo@latest init`            | `create_dev_portal`                           |
-| Shape config      | `npx apitogo config` + file edits             | `apply_product_intent` (shape)                |
-| Preview           | `npx apitogo run`                             | `npm run dev` / preview tool                  |
-| Publish           | `npx apitogo deploy`                          | `publish_dev_portal`                          |
-| Status / teardown | `npx apitogo status` / `npx apitogo teardown` | `verify_dev_portal_live` / `teardown_project` |
-
-Prefer MCP when an agent should drive changes. Prefer CLI for CI, scripts, or terminal-only
-workflows.
-
-## Next
-
-- [Install the CLI](./setup.md)
-- [Shape](./shape.md) · [Go live](./go-live.md) · [Commands](./commands.md)
-- [MCP overview](../mcp/overview.md) — agent-driven workflow
-- [Manifest](../configuration/manifest.md)
+---
+title: CLI overview
+description:
+  Use the APItoGo CLI to scaffold, shape, preview, and publish API products without an AI agent.
+sidebar_icon: terminal
+---
+
+The **`apitogo`** CLI lets you manage developer portals from the terminal. You scaffold and shape
+local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
+`npx apitogo deploy`.
+
+**First time?** Install and wire credentials → **[Install the CLI](./setup.md)**. Then follow
+[Shape](./shape.md) and [Go live](./go-live.md).
+
+## What you get
+
+- Scaffold a local portal site (`npx @lukoweb/apitogo@latest init`)
+- Shape backend, OpenAPI, plans, and docs pages via `npx apitogo config` and file edits
+- Preview locally (`npx apitogo run`)
+- Publish to APItoGo hosting (`npx apitogo deploy`) with platform plans **Free**, **Starter**, or
+  **Professional**
+- Check live status (`npx apitogo status`) and tear down (`npx apitogo teardown --yes`)
+
+## Prerequisites
+
+### Shell environment (for deploy / status / teardown)
+
+| Variable             | Required | Purpose           |
+| -------------------- | -------- | ----------------- |
+| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
+| `APITOGO_API_SECRET` | Yes      | Platform API auth |
+
+### Local machine
+
+- Node.js 20+ (scaffold, build, preview)
+- Network access to the npm registry during install/build
+- OIDC credentials at publish time (site `.env` only — never in shell history for sharing)
+- Stripe secrets at publish only when you have **paid** project plans
+
+## Changing your site
+
+| Approach                 | When it helps                                                                                                                     |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| **`npx apitogo config`** | Wire OpenAPI, custom pages, gateway plans, and site title from the terminal. See [Make config](../configuration/make-config.mdx). |
+| **Edit files directly**  | Full control — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc.                                                 |
+
+Common CLI shape tasks:
+
+| Change                            | How                                               |
+| --------------------------------- | ------------------------------------------------- |
+| Backend runtime                   | `npx apitogo config` (backend)                    |
+| OpenAPI + API Reference nav       | `npx apitogo config` (openapi)                    |
+| Custom docs pages                 | `npx apitogo config` (page) or add under `pages/` |
+| Gateway / API plans               | `npx apitogo config` (plan) or edit manifest      |
+| Site title                        | `--title` or edit `apitogo.config.json`           |
+| Theme, fonts, branding, projectId | Edit `apitogo.config.json`                        |
+
+Home page content often lives in `landing/LandingPage.tsx`. Site footer can live under
+`modules.landing.content.footer` in `apitogo.config.json`.
+
+## Config model (local site)
+
+| File                  | Role                                  |
+| --------------------- | ------------------------------------- |
+| `apitogo.config.json` | Site, modules, plans, auth type, apis |
+| `.env`                | `VITE_*` + `APITOGO_CONFIG_*` secrets |
+
+Details: [Manifest](../configuration/manifest.md).
+
+## CLI vs MCP
+
+Both paths use the same config-first model. `npx apitogo deploy` runs the same engine as MCP
+`publish_dev_portal`.
+
+| Task              | CLI                                           | MCP (agent)                                   |
+| ----------------- | --------------------------------------------- | --------------------------------------------- |
+| Scaffold          | `npx @lukoweb/apitogo@latest init`            | `create_dev_portal`                           |
+| Shape config      | `npx apitogo config` + file edits             | `apply_product_intent` (shape)                |
+| Preview           | `npx apitogo run`                             | `npm run dev` / preview tool                  |
+| Publish           | `npx apitogo deploy`                          | `publish_dev_portal`                          |
+| Status / teardown | `npx apitogo status` / `npx apitogo teardown` | `verify_dev_portal_live` / `teardown_project` |
+
+Prefer MCP when an agent should drive changes. Prefer CLI for CI, scripts, or terminal-only
+workflows.
+
+## Next
+
+- [Install the CLI](./setup.md)
+- [Shape](./shape.md) · [Go live](./go-live.md) · [Commands](./commands.md)
+- [MCP overview](../mcp/overview.md) — agent-driven workflow
+- [Manifest](../configuration/manifest.md)