@lukoweb/apitogo 0.1.78 → 0.1.80

package/docs/configuration/make-config.mdx

@@ -3,24 +3,34 @@ title: Make config (CLI)
 navigation_label: Make config
 sidebar_icon: file-cog
 description:
-  Create or update apitogo.config.json from your pages folder, OpenAPI, and optional site, theme, and
-  authentication settings.
+  Create or update apitogo.config.json from your pages folder, OpenAPI, gateway plans, and optional
+  site settings.
 ---
 
 The **`apitogo config`** (alias: `make-config`) command writes **`apitogo.config.json`**. It can scaffold a portal
 project (package.json, tsconfig, landing and user-panel stubs, thin `apitogo.config.tsx`) when those
-files are missing, merge **site / theme / authentication** from flags or an interactive wizard, scan
-`pages/` for navigation, and wire OpenAPI plus an **API Reference** link.
+files are missing, merge **site / theme / authentication** from flags, run an **interactive wizard**
+with `-i`, scan `pages/` for navigation, and wire OpenAPI plus an **API Reference** link.
 
-Landing and user panel are **always enabled** on new configs. The command does **not** change
-`modules` from the CLI and **never edits `redirects`**.
+Landing and user panel are **always enabled** on new configs. **Authentication is enabled by default**
+on new scaffolds. The command does **not** change `redirects`.
+
+## Prerequisites
+
+Install the CLI first — see [Install the CLI](../cli/setup.md). In short:
+
+- **New site:** `npm create @lukoweb/apitogo@latest` (installs `@lukoweb/apitogo` into the project)
+- **Existing folder:** `npx @lukoweb/apitogo init .` then `npm install`
+
+Run config from the project root with `npx apitogo config` (or `apitogo config` if
+`node_modules/.bin` is on your PATH).
 
 ## What it does
 
 1. **Ensures npm scripts** — Creates **`package.json`** (dev / build / preview) and **`tsconfig.json`**
    when missing, including `@lukoweb/apitogo`, landing, user-panel, and billing packages.
 2. **Creates `apitogo.config.json`** when missing, using the current portal template (`site`,
-   `theme`, `authentication`, `modules.docs`, **landing on**, **user panel on**). Creates a thin
+   `theme`, `authentication` **enabled**, `modules.docs`, **landing on**, **user panel on**). Creates a thin
    **`apitogo.config.tsx`** wrapper only if that file does not already exist (existing TSX is left
    alone).
 3. **Patches site, theme, and auth** from `--site`, `--theme`, `--authentication`, `--title`, or
@@ -30,16 +40,41 @@ Landing and user panel are **always enabled** on new configs. The command does *
    portal-only sites) — existing navigation is left alone. Other nav items are kept. Use
    **`--force`** to rebuild Documentation items from disk when pages are present (API Reference is
    still kept when OpenAPI is wired).
-5. **Wires OpenAPI** when a spec is found (or confirmed in interactive mode):
+5. **Wires OpenAPI** when a spec is found (non-interactive) or when you enter a path in `-i`:
    `apis: [{ type: "file", input, path: "api" }]` and a top-level **API Reference** link to `/api` if
-   that link is missing.
+   that link is missing. Interactive mode stores a **relative file path** in `apis[0].input` (for
+   example `./openapi.yaml` or `../api/openapi.yaml`).
+6. **Interactive only** — can scaffold **custom pages** under `pages/` and append **gateway plans**
+   to `modules.userPanel.plans.items`.
+
+## Interactive wizard (`-i`)
+
+```bash
+npx apitogo config -i
+```
+
+1. **Site title**
+2. **Loop** until you type `done`:
+   - **`openapi`** — path to your OpenAPI file (relative link in config; empty skips)
+   - **`page`** — page title + URL path (writes `pages/<slug>.tsx` and wires navigation)
+   - **`plan`** — plan title, price (USD/month), rate limit (calls/min), monthly quota
+3. **Wrap-up** — links to [docs.apitogo.com](https://docs.apitogo.com) for further configuration
+
+The wizard does **not** ask for fonts, colors, logo alt text, or the auth API base URL. Authentication
+stays **enabled**; `apitogo apply` writes `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` to `.env` after
+the portal backend is provisioned.
+
+If you add a **paid** plan (`priceAmount > 0`), the CLI warns that **Free platform hosting cannot
+publish paid gateway plans or custom domains** — use Starter or Professional on apply.
+
+See [Gateway plans](./plans.md) and [Shape with CLI](../cli/shape.md).
 
 ## Usage
 
 Run from your project root (where `apitogo.config.json` and `package.json` live):
 
 ```bash
-apitogo config
+npx apitogo config
 ```
 
 ### Options
@@ -48,7 +83,7 @@ apitogo config
 | ------------------------- | --------------------------------------------------------------------------- |
 | `--pages-dir <dir>`       | Folder to scan for `.md` / `.mdx` / `.tsx` (default: `pages`)               |
 | `--dir <path>`            | Project root (default: current directory)                                   |
-| `--interactive` / `-i`    | Prompt for title, logo alt, auth, fonts, primary colors, and OpenAPI        |
+| `--interactive` / `-i`    | Wizard: site title, OpenAPI path, custom pages, gateway plans                 |
 | `--title <string>`        | Set `site.title`                                                            |
 | `--site <json>`           | Deep-merge a JSON object into `site`                                        |
 | `--theme <json>`          | Deep-merge a JSON object into `theme`                                       |
@@ -58,20 +93,25 @@ apitogo config
 Examples:
 
 ```bash
-apitogo config --title "Books API"
-apitogo config --theme '{"light":{"primary":"#111111"}}'
-apitogo config --interactive
+npx apitogo config --title "Books API"
+npx apitogo config --theme '{"light":{"primary":"#111111"}}'
+npx apitogo config -i
 ```
 
-There is **no `--modules` flag**. Edit `modules` in `apitogo.config.json` if you need to change
-landing or user panel later.
+Theme and fonts are edited in `apitogo.config.json` or via MCP — not in the interactive wizard. See
+[Colors & theme](../customization/colors-theme.mdx) and [Fonts](../customization/fonts.md).
+
+There is **no `--modules` flag** for landing or user-panel toggles. Interactive mode **does** update
+`modules.userPanel.plans` when you add plans.
 
 ## When not to use it
 
 - You need a fully custom navigation order — skip `--force` or maintain navigation by hand.
-- You want to change landing or user-panel module options — edit JSON (or use MCP), not this command.
+- You want to change landing module home content — edit `landing/LandingPage.tsx`.
 
 ## See also
 
 - [Manifest (`apitogo.config.json`)](./manifest.md)
+- [Gateway plans](./plans.md)
 - [Navigation](./navigation.md)
+- [Shape with CLI](../cli/shape.md)

package/docs/configuration/manifest.md

@@ -57,8 +57,8 @@ metadata, with optional `.env` overrides for secrets and local tweaks.
 - **Site name / logo:** only `site.title` and `site.logo` (platform branding is derived at publish).
 - **OpenAPI path:** `backend.openApiPath` is derived from `apis[0].input`.
 - **Billing / account plans:** use `modules.userPanel.plans.enabled` and store the plan catalog in
-  `modules.userPanel.plans.items`. Legacy root `plans` is migrated on load. Legacy `pricing.enabled`
-  is migrated and stripped from site JSON; MCP/publish still receives derived `pricing.enabled`.
+  `modules.userPanel.plans.items`. Add plans with `apitogo config -i` or edit the manifest by hand.
+  See [Gateway plans](./plans.md). Legacy root `plans` is migrated on load.
 - **Docs / API keys:** configure under `modules.docs` and `modules.userPanel.apiKeys` only.
 
 ## Environment variables
@@ -90,6 +90,7 @@ APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
 
 ## Related
 
+- [Gateway plans](./plans.md)
 - [Authentication](./authentication.md)
 - [Overview](./overview.md)
 - [MCP overview](../mcp/overview.md)

package/docs/configuration/overview.md

@@ -160,6 +160,8 @@ Put navigation in `apitogo.config.json`, or keep large trees in a separate modul
 ## Related
 
 - [Manifest (`apitogo.config.json`)](./manifest.md)
-- [Make config (CLI)](./make-config.mdx)
+- [Make config (CLI)](./make-config.mdx) — interactive wizard (`apitogo config -i`)
+- [Gateway plans](./plans.md)
 - [Authentication](./authentication.md)
 - [MCP overview](../mcp/overview.md)
+- [Shape with CLI](../cli/shape.md)

package/docs/configuration/plans.md

@@ -0,0 +1,113 @@
+---
+title: Gateway plans
+sidebar_icon: tags
+description:
+  Configure end-user API plans in apitogo.config.json — pricing, rate limits, quotas, and publish
+  behavior.
+---
+
+**Gateway plans** (also called API plans) are what your **end users** subscribe to on `/pricing`.
+They are separate from **platform hosting** (Free / Starter / Professional on APItoGo), which you
+select with `apitogo apply --platform-plan`.
+
+Store the catalog under `modules.userPanel.plans.items` in `apitogo.config.json`.
+
+## Shape with the CLI
+
+`apitogo config -i` can add plans interactively (title, price, rate limit, monthly quota). You can
+also edit the manifest by hand or use MCP `update_dev_portal_manifest`.
+
+```bash
+npx apitogo config -i
+# loop: plan → enter title, price, policies → done
+```
+
+## Canonical shape
+
+```json
+{
+  "modules": {
+    "userPanel": {
+      "plans": {
+        "enabled": true,
+        "items": [
+          {
+            "sku": "free",
+            "displayName": "Free",
+            "priceAmount": 0,
+            "limitsJson": "{\"rateLimit\":{\"calls\":100,\"renewalPeriodSeconds\":60},\"quota\":{\"calls\":50000,\"renewalPeriodDays\":30}}"
+          },
+          {
+            "sku": "pro",
+            "displayName": "Pro",
+            "priceAmount": 29,
+            "priceCurrency": "usd",
+            "billingPeriod": "month",
+            "limitsJson": "{\"rateLimit\":{\"calls\":1000,\"renewalPeriodSeconds\":60},\"quota\":{\"calls\":500000,\"renewalPeriodDays\":30}}"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+- **`sku`** — stable identifier (used in checkout URLs and gateway sync).
+- **`displayName`** — label on `/pricing`.
+- **`priceAmount`** — `0` for free tiers; greater than zero for paid plans (USD by default).
+- **`limitsJson`** — JSON string with rate limit and quota policies (see below).
+
+Enable the catalog with `modules.userPanel.plans.enabled: true`. Legacy root `plans` is migrated on
+load.
+
+## limitsJson schema
+
+```json
+{
+  "rateLimit": { "calls": 100, "renewalPeriodSeconds": 60 },
+  "quota": { "calls": 50000, "renewalPeriodDays": 30 }
+}
+```
+
+- **rateLimit** — maximum calls per renewal window (per minute when `renewalPeriodSeconds` is 60).
+- **quota** — longer-window cap (per 30 days when `renewalPeriodDays` is 30).
+
+After OpenAPI is deployed, you can scope plans to specific API operations with
+`includedActionKeys` (for example `get:/orders/{id}`). Edit those fields in
+`apitogo.config.json` — see [Manifest](./manifest.md).
+
+## Publish
+
+Gateway plans are applied when you run:
+
+```bash
+apitogo apply
+```
+
+`apitogo apply` syncs plans from the manifest to the platform gateway. Paid plans require Stripe
+secrets in `.env` before publish — see [Go live with CLI](../cli/go-live.md).
+
+## Platform hosting vs gateway plans
+
+| Kind | What it is | How |
+| ---- | ---------- | --- |
+| **Platform hosting** | APItoGo bill for hosting your portal + API hub | `apitogo apply --platform-plan` |
+| **Gateway / API plans** | What your customers pay for API access | `modules.userPanel.plans.items` |
+
+### Free platform limitations
+
+The **Free** platform plan cannot:
+
+- Publish **paid** gateway plans (`priceAmount > 0`)
+- Attach a **custom domain** to the dev portal
+
+Use **Starter** or **Professional** for paid API tiers, Stripe checkout, and custom domains. If your
+manifest has paid plans and you try `apitogo apply --platform-plan free`, apply is blocked until you
+upgrade or zero/remove those paid plans.
+
+## Related
+
+- [Manifest](./manifest.md)
+- [Make config (CLI)](./make-config.mdx)
+- [Authentication](./authentication.md)
+- [Go live with CLI](../cli/go-live.md)

package/docs/deploy/apitogo.md

@@ -1,51 +1,17 @@
 # Deploy with APIToGo CLI
 
-Publish your local portal (and optional API hub) to the APItoGo platform with
-`apitogo apply`. This is the same engine as MCP `publish_dev_portal`.
+Platform publish is **`apitogo apply`** — the same engine as MCP `publish_dev_portal`.
 
-## Prerequisites
+Full walkthrough (prerequisites, secrets, `--only`, status, teardown):
 
-- `APITOGO_API_KEY_ID` and `APITOGO_API_SECRET` in the environment
-- A site directory with `apitogo.config.json` (use `apitogo init` / `apitogo config`)
-- Secrets such as OIDC (and Stripe when you have paid plans) in `.env` as
-  `APITOGO_CONFIG_AUTHENTICATION__*`
+→ **[Go live with CLI](../cli/go-live.md)**
 
-## Apply everything
+Quick reference:
 
 ```bash
-apitogo apply
+export APITOGO_API_KEY_ID=apk_...
+export APITOGO_API_SECRET=...
+cd ./my-portal
+apitogo apply --platform-plan free
+apitogo status
 ```
-
-Creates or links the platform project, provisions modules, syncs gateway plans,
-deploys the API hub (when configured), updates the portal backend, and builds +
-deploys the portal frontend.
-
-## Target specific resources
-
-```bash
-apitogo apply --only apihub
-apitogo apply --only portal-backend
-apitogo apply --only portal-frontend
-apitogo apply --only apihub,portal-frontend
-apitogo apply --only portal-frontend --force
-```
-
-| Resource | What it updates |
-| --- | --- |
-| `apihub` | Gateway plans/baseline, API hub package + deploy, public routes |
-| `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 useful commands
-
-```bash
-apitogo status          # account + project + live checks
-apitogo teardown --yes  # delete the platform project
-apitogo build           # local production build
-apitogo build --preview # preview the production build locally
-```
-
-Multi-environment SWA deploy (`apitogo deploy --env …`) and
-`apitogo configure-github-workflow` are removed. Use `apitogo apply` instead.

package/docs/deployment.md

@@ -2,7 +2,7 @@
 
 | Path | Docs |
 | --- | --- |
-| **CLI** (`apitogo apply`) | [Deploy with APIToGo CLI](./deploy/apitogo.md) |
+| **CLI** (`apitogo apply`) | [Go live with CLI](./cli/go-live.md) |
 | **MCP / agents** | [Go live](./mcp/go-live.md) |
 
 Local-only builds: `apitogo build` (optional `--preview`). Platform publish is always `apitogo apply`.

package/docs/guides/custom-pages.md

@@ -11,6 +11,14 @@ components that APIToGo already has such as buttons, links and headers.
 
 Start by creating the page you want to add.
 
+## CLI scaffold
+
+`apitogo config -i` can create a starter page under `pages/` and wire it into navigation. Choose
+`page` in the wizard loop, then edit the generated `.tsx` file.
+
+Predefined UI components (Callout, Card, Button, Heading, and more) are documented under
+[/docs/components](/docs/components).
+
 ## Setup a custom page
 
 Each custom page is a page component of its own and lives in a `src` directory at the root of your

package/docs/guides/environment-variables.md

@@ -21,7 +21,7 @@ APIToGo uses Vite’s [env and mode](https://vite.dev/guide/env-and-mode) model,
 Nested overrides use `__` path segments (SCREAMING_SNAKE). See [Manifest](../configuration/manifest.md).
 
 **Never commit** OIDC client secrets or Stripe keys. MCP never puts secrets in chat — you write them
-to `.env` before [go-live](../mcp/go-live.md).
+to `.env` before [go-live](../mcp/go-live.md) or `apitogo apply` ([CLI go-live](../cli/go-live.md)).
 
 Example:
 
@@ -85,7 +85,8 @@ interface ImportMeta {
 
 | Variable | Purpose |
 | -------- | ------- |
-| `APITOGO_API_KEY_ID` / `APITOGO_API_SECRET` | Required for MCP |
+| `APITOGO_API_KEY_ID` / `APITOGO_API_SECRET` | Required for MCP and CLI apply/status/teardown |
 | `APITOGO_DOC_TOOL_PATH` | Optional local doc-tool for scaffold |
+| `APITOGO_MCP_PATH` | Optional local MCP checkout for CLI apply/status/teardown |
 
-See [MCP overview](../mcp/overview.md).
+See [MCP overview](../mcp/overview.md) and [CLI overview](../cli/overview.md).

package/docs/mcp/go-live.md

@@ -90,7 +90,7 @@ shape → deploy_backend → publish_dev_portal(skipBackendRedeploy: true)
 | MCP `publish_dev_portal`     | Full product go-live (plans, auth, hosting, verify)   |
 | CLI `apitogo apply`          | Publish config to platform (apihub + portal)          |
 
-See [Deploy with APIToGo CLI](../deploy/apitogo.md).
+See [Go live with CLI](../cli/go-live.md).
 
 ## Related
 

package/docs/mcp/overview.md

@@ -73,4 +73,4 @@ Details: [Manifest](../configuration/manifest.md).
 - [Configure MCP](./setup.md)
 - [Quickstart](../quickstart.md)
 - [Shape](./shape.md) · [Go live](./go-live.md) · [Tools](./tools.md)
-- CLI without an agent: see the footnote on [Quickstart](../quickstart.md#without-an-agent-cli)
+- CLI without an agent: [CLI overview](../cli/overview.md)

package/docs/quickstart.md

@@ -68,14 +68,6 @@ Build an API product (developer portal, plans, gateway, backend) with an AI agen
 
 ## Without an agent (CLI)
 
-If you prefer not to use MCP:
+Prefer the terminal? Use the **`apitogo`** CLI for the same config-first workflow:
 
-```bash
-npm create @lukoweb/apitogo@latest
-cd your-project-name
-npm run dev
-```
-
-For an existing `pages/` + OpenAPI folder: `apitogo config` (see
-[Make config](./configuration/make-config.mdx)). That command writes `apitogo.config.json`. Site-only
-deploy with a token: [Deploy with APIToGo CLI](./deploy/apitogo.md).
+→ **[Install the CLI](./cli/setup.md)** · [Shape](./cli/shape.md) · [Go live](./cli/go-live.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "type": "module",
   "sideEffects": [
     "**/*.css",