@lukoweb/apitogo 0.2.46 → 0.2.49

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 files (`gateway.specs`)   | `npx apitogo config` (openapi)                                   |
+| Custom docs pages                 | `npx apitogo config` (page) or add under `apitogo/portal/pages/` |
+| Gateway / API plans               | `npx apitogo config` (plan) or edit `apitogo/plans.json`         |
+| 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)

package/docs/cli/shape.md

@@ -1,127 +1,127 @@
----
-title: Shape with CLI
-description:
-  Scaffold and customize a developer portal locally with npx apitogo init, config, and run.
-sidebar_icon: pencil-ruler
----
-
-**Shape** means: create or update a local portal site (OpenAPI, plans, docs pages, auth) without
-publishing. You preview with `npx apitogo run`.
-
-Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed it yet, see
-[Install the CLI](./setup.md).
-
-## Happy path
-
-`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name or
-`--name` to override), installs dependencies, and wires nearby OpenAPI / docs. Then run config via
-`npx`:
-
-```bash
-npx @lukoweb/apitogo@latest init
-cd dev-portal
-npx apitogo config         # backend, OpenAPI, pages, plans (apply each immediately)
-npx apitogo run            # http://localhost:3000
-```
-
-Named folder:
-
-```bash
-npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
-cd ./my-portal
-npx apitogo config
-npx apitogo run
-```
-
-`npx @lukoweb/apitogo init` does **not** call the platform. Run `npx apitogo deploy` when you are
-ready to go live.
-
-## Interactive config (`npx apitogo config`)
-
-On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
-continues until you type `done`:
-
-| Choice    | What it does                                                            |
-| --------- | ----------------------------------------------------------------------- |
-| `backend` | Set `backend.sourceDirectory`, `runtime`, and platform `runtimeVersion` |
-| `openapi` | Link an OpenAPI file by **relative path** in `apitogo.config.json`      |
-| `page`    | Create `pages/<slug>.tsx` and wire it in navigation                     |
-| `plan`    | Add a gateway plan (title, price, rate limit, monthly quota)            |
-
-Authentication is **on by default** — the wizard does not ask for an auth API URL.
-`npx apitogo deploy` fills `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` after the portal backend
-exists.
-
-Fonts and colors are **not** prompted — edit `apitogo.config.json` or see
-[Colors & theme](../customization/colors-theme.mdx).
-
-**Paid plans:** if any plan has `priceAmount > 0`, you need **Starter** or **Professional** platform
-hosting on deploy. **Free** cannot publish paid gateway plans or custom domains.
-
-Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
-[Gateway plans](../configuration/plans.md)
-
-## Configure with flags
-
-Writes or updates **`apitogo.config.json`**. Can create `package.json`, `tsconfig.json`, and portal
-stubs when missing. Scans `pages/` for navigation and wires OpenAPI when a spec is found.
-
-```bash
-npx apitogo config
-npx apitogo config --title "Books API"
-npx apitogo config --theme '{"light":{"primary":"#111111"}}'
-npx apitogo config --no-interactive
-```
-
-Common flags:
-
-| Flag                                    | Purpose                                                    |
-| --------------------------------------- | ---------------------------------------------------------- |
-| `--interactive` / `-i`                  | Force wizard (default on TTY). `--no-interactive` skips it |
-| `--title`                               | Set `site.title`                                           |
-| `--theme`, `--site`, `--authentication` | Deep-merge JSON into config                                |
-| `--pages-dir`                           | Folder to scan (default: `pages`)                          |
-| `--force`                               | Rebuild Documentation nav from disk                        |
-
-## Shape by editing files
-
-After `npx apitogo config`, edit the manifest and site files directly:
-
-- **Plans, branding, backend, projectId** — `apitogo.config.json`
-- **Docs pages** — `pages/**/*.mdx` or `.tsx`
-- **Home page** — `landing/LandingPage.tsx`
-- **Footer** — `modules.landing.content.footer` in `apitogo.config.json`
-
-Never put OIDC or Stripe secrets in `apitogo.config.json`. Use `.env` with
-`APITOGO_CONFIG_AUTHENTICATION__*` before publish.
-
-## Preview locally
-
-```bash
-npx apitogo run
-npx apitogo run --port 4000 --open
-```
-
-Production build check:
-
-```bash
-npx apitogo build
-npx apitogo build --preview
-```
-
-Shape-phase edits hot-reload when the dev server is running.
-
-## Existing docs + OpenAPI folder
-
-If you already have `pages/` and an OpenAPI spec:
-
-```bash
-npx @lukoweb/apitogo@latest init
-cd dev-portal
-npx apitogo config
-npx apitogo run
-```
-
-## Next
-
-When the site looks right, [go live](./go-live.md) with `npx apitogo deploy`.
+---
+title: Shape with CLI
+description:
+  Scaffold and customize a developer portal locally with npx apitogo init, config, and run.
+sidebar_icon: pencil-ruler
+---
+
+**Shape** means: create or update a local portal site (OpenAPI, plans, docs pages, auth) without
+publishing. You preview with `npx apitogo run`.
+
+Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed it yet, see
+[Install the CLI](./setup.md).
+
+## Happy path
+
+`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name or
+`--name` to override), installs dependencies, and wires nearby OpenAPI / docs. Then run config via
+`npx`:
+
+```bash
+npx @lukoweb/apitogo@latest init
+cd dev-portal
+npx apitogo config         # backend, OpenAPI, pages, plans (apply each immediately)
+npx apitogo run            # http://localhost:3000
+```
+
+Named folder:
+
+```bash
+npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
+cd ./my-portal
+npx apitogo config
+npx apitogo run
+```
+
+`npx @lukoweb/apitogo init` does **not** call the platform. Run `npx apitogo deploy` when you are
+ready to go live.
+
+## Interactive config (`npx apitogo config`)
+
+On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
+continues until you type `done`:
+
+| Choice    | What it does                                                             |
+| --------- | ------------------------------------------------------------------------ |
+| `backend` | Set `gateway.origin`: API code folder, runtime and runtime version       |
+| `openapi` | Add an OpenAPI file to `gateway.specs`                                   |
+| `page`    | Create `apitogo/portal/pages/<slug>.mdx` (the sidebar follows the files) |
+| `plan`    | Add a plan to `apitogo/plans.json` (title, price, rate limit, quota)     |
+
+Fonts and colors are **not** prompted. See [Colors & theme](../customization/colors-theme.mdx).
+
+**Paid plans:** payments go through Stripe. Once a plan has a price, `npx apitogo deploy` asks for
+your Stripe secret key (if the project has none yet) and stores it as a project secret. Free and
+contact-us plans need no key. Paid plans also need **Starter** or **Professional** platform hosting;
+**Free** cannot publish paid gateway plans or custom domains.
+
+Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
+[Gateway plans](../configuration/plans.md)
+
+## Configure with flags
+
+Changes a config version 2 project. Every change to `apitogo.config.json` is checked before it is
+written. The command does not create a project: use `init` or `create` for that.
+
+```bash
+npx apitogo config --title "Books API"
+npx apitogo config --page-slug guides/quickstart --page-title "Quickstart"
+npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
+npx apitogo config --no-interactive
+```
+
+Common flags:
+
+| Flag                                         | Purpose                                                    |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| `--interactive` / `-i`                       | Force wizard (default on TTY). `--no-interactive` skips it |
+| `--title`                                    | Set `portal.name`                                          |
+| `--source`, `--runtime`, `--runtime-version` | Set `gateway.origin`                                       |
+| `--openapi`                                  | Add a file to `gateway.specs`                              |
+| `--page-slug`, `--page-title`                | Add a docs page                                            |
+| `--plan`                                     | Add or replace a plan in `plans.json`                      |
+| `--patch`                                    | Deep-merge JSON into `apitogo.config.json`                 |
+
+## Shape by editing files
+
+After `npx apitogo config`, edit the manifest and site files directly:
+
+- **Services, backend, OpenAPI files** — `apitogo.config.json`
+- **Plans** — `apitogo/plans.json`
+- **Docs pages** — `apitogo/portal/pages/**/*.mdx`
+- **Home page** — the file in `portal.landing` (for example
+  `apitogo/portal/landing/LandingPage.tsx`)
+
+Never put OIDC or Stripe secrets in `apitogo.config.json`. Use `.env` with
+`APITOGO_CONFIG_AUTHENTICATION__*` before publish.
+
+## Preview locally
+
+```bash
+npx apitogo run
+npx apitogo run --port 4000 --open
+```
+
+Production build check:
+
+```bash
+npx apitogo build
+npx apitogo build --preview
+```
+
+Shape-phase edits hot-reload when the dev server is running.
+
+## Existing docs + OpenAPI folder
+
+If you already have `pages/` and an OpenAPI spec:
+
+```bash
+npx @lukoweb/apitogo@latest init
+cd dev-portal
+npx apitogo config
+npx apitogo run
+```
+
+## Next
+
+When the site looks right, [go live](./go-live.md) with `npx apitogo deploy`.

package/docs/cli/walkthrough.md

@@ -37,7 +37,7 @@ below use the installed CLI through `npx apitogo`.
 ```bash
 npx apitogo add identity
 npx apitogo add gateway --origin proxy --url https://httpbin.org --auth identity --create-spec
-npx apitogo add plans --template free --billing none
+npx apitogo add plans --template free
 ```
 
 | Service  | What it gives you                                                                               |
@@ -117,32 +117,21 @@ Professional plan with APItoGo, and your own Stripe account. Your customers pay
    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`,
+2. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
+   `"billingInterval": "month"`. Its limits cannot be higher than your platform plan allows.
+   Payments go through Stripe; nothing else in the config changes.
+3. Deploy: `npx apitogo deploy`. Because a plan now has a price, deploy asks for your Stripe secret
+   key (it starts with `sk_test_` while you test) and stores it as the project secret
+   `STRIPE_API_KEY`, so it stays out of your files. You can also store it beforehand with
+   `npx apitogo secrets set STRIPE_API_KEY`. The output says whether Stripe is in test or live mode
+   and prints your portal's webhook address.
+4. 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.
+   `npx apitogo secrets set STRIPE_WEBHOOK`, add
+   `"plans": { "billing": { "webhookSecret": "secret:STRIPE_WEBHOOK" } }` to `apitogo.config.json`,
+   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.