@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/cli/setup.md

@@ -1,141 +1,141 @@
----
-title: Install the CLI
-description:
-  Install and invoke the APItoGo CLI to scaffold, configure, preview, and publish developer portals.
-sidebar_icon: terminal
----
-
-Use the **`apitogo`** CLI (`@lukoweb/apitogo`) to scaffold a local portal, shape
-`apitogo.config.json`, preview with `npx apitogo run`, and publish with `npx apitogo deploy`.
-Platform commands (`deploy`, `status`, `teardown`) use the same engine as MCP `publish_dev_portal`.
-
-Examples in these docs use **`npx apitogo`** so they run the project-local CLI. A global install is
-optional and not required.
-
-## Prerequisites
-
-- **Node.js 20+**
-- Platform API credentials from [apitogo.com](https://apitogo.com) when you run `npx apitogo deploy`
-  (API key id + secret)
-
-## Install
-
-The CLI is the npm package **`@lukoweb/apitogo`**. It exposes the **`apitogo`** binary. Scaffold
-commands add it to your project and `npm install` puts it on `node_modules/.bin`. Invoke it with
-`npx apitogo`.
-
-### New project (recommended)
-
-`npx @lukoweb/apitogo@latest init` creates a config version 2 project in the current folder. It
-shows what it will create and asks first (pass `--yes` to skip the question), writes
-`apitogo.config.json`, uses an existing `docs/` folder in place, and, in a new folder, creates
-`package.json` and installs `@lukoweb/apitogo`, `react` and `react-dom`:
-
-```bash
-mkdir my-portal && cd my-portal
-npx @lukoweb/apitogo@latest init --name "Books API"
-npx apitogo run
-```
-
-In an existing project the tool never edits your `package.json`. It prints the install command to
-run instead.
-
-The older scaffold (a `dev-portal` folder with secrets artifacts and automatic OpenAPI wiring) is
-still available with `--no-v2`:
-
-```bash
-npx @lukoweb/apitogo@latest init --no-v2
-cd dev-portal
-npx apitogo run
-```
-
-Named folder or site name:
-
-```bash
-npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
-cd ./my-portal
-npx apitogo run
-```
-
-#### Scaffold options
-
-| Flag                      | Effect                                                                   |
-| ------------------------- | ------------------------------------------------------------------------ |
-| `[dir]`                   | Target folder (default: the current folder; `dev-portal` with `--no-v2`) |
-| `--name <string>`         | Site / package name (also used when `dir` is `.`)                        |
-| `--no-install`            | Skip `npm install` after scaffold                                        |
-| `--no-v2`                 | Use the older `dev-portal` scaffold instead of config version 2          |
-| `--yes`                   | Do not ask for confirmation (config version 2)                           |
-| `--overwrite`             | Replace an existing non-empty target directory                           |
-| `--json`                  | Print a JSON result payload on stdout                                    |
-| `--openapi-search <mode>` | Auto-discover OpenAPI: `nearby` (default), `site`, or `none`             |
-
-`npx @lukoweb/apitogo init` is local only — it does not call the platform. After `config`, run
-`npx apitogo run` to preview, then `npx apitogo deploy` when ready to go live.
-
-### How to run `apitogo`
-
-| Situation                                                 | Command                                             |
-| --------------------------------------------------------- | --------------------------------------------------- |
-| After `init` or `npm install` in the project              | `npx apitogo <command>` (e.g. `npx apitogo config`) |
-| One-off, no project yet                                   | `npx @lukoweb/apitogo <command>`                    |
-| After [optional global install](#optional-global-install) | `apitogo <command>` anywhere                        |
-
-`npm run dev` / `npm run build` use the project-local CLI via `package.json` scripts — no global
-install required.
-
-### Optional global install
-
-```bash
-npm install -g @lukoweb/apitogo
-```
-
-Then run `apitogo` from any directory:
-
-```bash
-apitogo --help
-```
-
-Upgrade later with `npm install -g @lukoweb/apitogo@latest`. Uninstall with
-`npm uninstall -g @lukoweb/apitogo`. Prefer `npx apitogo` in projects so each site uses the version
-in its `package.json`.
-
-## Platform credentials
-
-Export these before `npx apitogo deploy`, `npx apitogo status`, or `npx apitogo teardown`:
-
-| Variable             | Required | Purpose           |
-| -------------------- | -------- | ----------------- |
-| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
-| `APITOGO_API_SECRET` | Yes      | Platform API auth |
-
-Optional:
-
-| Variable           | Purpose                                                    |
-| ------------------ | ---------------------------------------------------------- |
-| `APITOGO_API_URL`  | Override platform API base URL                             |
-| `APITOGO_CLI_PATH` | Local `@lukoweb/apitogo` / doc-tool checkout for MCP spawn |
-
-Never commit secrets. Site auth secrets (OIDC, Stripe) belong in the portal **`.env`** as
-`APITOGO_CONFIG_AUTHENTICATION__*` — see [Go live](./go-live.md).
-
-## Verify
-
-```bash
-npx apitogo --help
-```
-
-You should see `init`, `config`, `run`, `build`, `deploy`, `status`, and `teardown`.
-
-With credentials set:
-
-```bash
-npx apitogo status
-```
-
-## Next
-
-- [CLI overview](./overview.md)
-- [Shape](./shape.md) — scaffold and local preview
-- [Go live](./go-live.md) — `npx apitogo deploy`
-- [Commands](./commands.md) — full catalog
+---
+title: Install the CLI
+description:
+  Install and invoke the APItoGo CLI to scaffold, configure, preview, and publish developer portals.
+sidebar_icon: terminal
+---
+
+Use the **`apitogo`** CLI (`@lukoweb/apitogo`) to scaffold a local portal, shape
+`apitogo.config.json`, preview with `npx apitogo run`, and publish with `npx apitogo deploy`.
+Platform commands (`deploy`, `status`, `teardown`) use the same engine as MCP `publish_dev_portal`.
+
+Examples in these docs use **`npx apitogo`** so they run the project-local CLI. A global install is
+optional and not required.
+
+## Prerequisites
+
+- **Node.js 20+**
+- Platform API credentials from [apitogo.com](https://apitogo.com) when you run `npx apitogo deploy`
+  (API key id + secret)
+
+## Install
+
+The CLI is the npm package **`@lukoweb/apitogo`**. It exposes the **`apitogo`** binary. Scaffold
+commands add it to your project and `npm install` puts it on `node_modules/.bin`. Invoke it with
+`npx apitogo`.
+
+### New project (recommended)
+
+`npx @lukoweb/apitogo@latest init` creates a config version 2 project in the current folder. It
+shows what it will create and asks first (pass `--yes` to skip the question), writes
+`apitogo.config.json`, uses an existing `docs/` folder in place, and, in a new folder, creates
+`package.json` and installs `@lukoweb/apitogo`, `react` and `react-dom`:
+
+```bash
+mkdir my-portal && cd my-portal
+npx @lukoweb/apitogo@latest init --name "Books API"
+npx apitogo run
+```
+
+In an existing project the tool never edits your `package.json`. It prints the install command to
+run instead.
+
+The older scaffold (a `dev-portal` folder with secrets artifacts and automatic OpenAPI wiring) is
+still available with `--no-v2`:
+
+```bash
+npx @lukoweb/apitogo@latest init --no-v2
+cd dev-portal
+npx apitogo run
+```
+
+Named folder or site name:
+
+```bash
+npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
+cd ./my-portal
+npx apitogo run
+```
+
+#### Scaffold options
+
+| Flag                      | Effect                                                                   |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `[dir]`                   | Target folder (default: the current folder; `dev-portal` with `--no-v2`) |
+| `--name <string>`         | Site / package name (also used when `dir` is `.`)                        |
+| `--no-install`            | Skip `npm install` after scaffold                                        |
+| `--no-v2`                 | Use the older `dev-portal` scaffold instead of config version 2          |
+| `--yes`                   | Do not ask for confirmation (config version 2)                           |
+| `--overwrite`             | Replace an existing non-empty target directory                           |
+| `--json`                  | Print a JSON result payload on stdout                                    |
+| `--openapi-search <mode>` | Auto-discover OpenAPI: `nearby` (default), `site`, or `none`             |
+
+`npx @lukoweb/apitogo init` is local only — it does not call the platform. After `config`, run
+`npx apitogo run` to preview, then `npx apitogo deploy` when ready to go live.
+
+### How to run `apitogo`
+
+| Situation                                                 | Command                                             |
+| --------------------------------------------------------- | --------------------------------------------------- |
+| After `init` or `npm install` in the project              | `npx apitogo <command>` (e.g. `npx apitogo config`) |
+| One-off, no project yet                                   | `npx @lukoweb/apitogo <command>`                    |
+| After [optional global install](#optional-global-install) | `apitogo <command>` anywhere                        |
+
+`npm run dev` / `npm run build` use the project-local CLI via `package.json` scripts — no global
+install required.
+
+### Optional global install
+
+```bash
+npm install -g @lukoweb/apitogo
+```
+
+Then run `apitogo` from any directory:
+
+```bash
+apitogo --help
+```
+
+Upgrade later with `npm install -g @lukoweb/apitogo@latest`. Uninstall with
+`npm uninstall -g @lukoweb/apitogo`. Prefer `npx apitogo` in projects so each site uses the version
+in its `package.json`.
+
+## Platform credentials
+
+Export these before `npx apitogo deploy`, `npx apitogo status`, or `npx apitogo teardown`:
+
+| Variable             | Required | Purpose           |
+| -------------------- | -------- | ----------------- |
+| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
+| `APITOGO_API_SECRET` | Yes      | Platform API auth |
+
+Optional:
+
+| Variable           | Purpose                                                    |
+| ------------------ | ---------------------------------------------------------- |
+| `APITOGO_API_URL`  | Override platform API base URL                             |
+| `APITOGO_CLI_PATH` | Local `@lukoweb/apitogo` / doc-tool checkout for MCP spawn |
+
+Never commit secrets. Site auth secrets (OIDC, Stripe) belong in the portal **`.env`** as
+`APITOGO_CONFIG_AUTHENTICATION__*` — see [Go live](./go-live.md).
+
+## Verify
+
+```bash
+npx apitogo --help
+```
+
+You should see `init`, `config`, `run`, `build`, `deploy`, `status`, and `teardown`.
+
+With credentials set:
+
+```bash
+npx apitogo status
+```
+
+## Next
+
+- [CLI overview](./overview.md)
+- [Shape](./shape.md) — scaffold and local preview
+- [Go live](./go-live.md) — `npx apitogo deploy`
+- [Commands](./commands.md) — full catalog

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 `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`.