@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/cli/setup.md

@@ -1,141 +1,130 @@
----
-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.
+
+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)   |
+| `--name <string>` | Project name (default: the folder's name)     |
+| `--yes`           | Do not ask for confirmation                   |
+| `--dry-run`       | Show what would be created, and write nothing |
+| `--force`         | Replace an existing `apitogo.config.json`     |
+| `--json`          | Print a JSON result payload on stdout         |
+
+`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. Secrets such as the Stripe key are project secrets: deploy asks for them, and
+`npx apitogo secrets set <NAME>` changes them. 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

@@ -13,13 +13,12 @@ Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed i
 
 ## 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`:
+`npx @lukoweb/apitogo@latest init` creates a project in the current folder: it writes
+`apitogo.config.json`, uses an existing `docs/` folder, and installs the CLI. Then shape it with
+`npx apitogo config`:
 
 ```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
 ```
@@ -52,8 +51,9 @@ Fonts and colors are **not** prompted. See [Colors & theme](../customization/col
 
 **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.
+contact-us plans need no key. [Set up Stripe for paid plans](../guides/stripe-setup.mdx) shows where
+to find the key and how to add the webhook, with pictures. 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)
@@ -88,12 +88,95 @@ 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/**/*.{md,mdx,tsx}` (`.tsx` files are React pages)
+- **Docs pages** — the files `portal.docs.content` names, by default
+  `apitogo/portal/pages/**/*.{md,mdx,tsx}` (`.tsx` files are React pages)
 - **Home page** — the file in `portal.landing` (for example
   `apitogo/portal/landing/LandingPage.tsx`)
+- **Footer** — the file in `portal.footer` (for example `apitogo/portal/footer/Footer.tsx`). It is
+  shown under every page except the console's (`/account`, `/login`, `/signup`). Remove
+  `portal.footer` to have none.
+- **Colors** — `apitogo/portal/theme.json` (or the file in `portal.theme`). See
+  [Colors & theme](../customization/colors-theme.mdx).
+- **Logo** — `portal.logo`, an image in `apitogo/portal/public/` or an `https://` address
+
+```json title=apitogo.config.json
+{
+  "portal": {
+    "landing": "apitogo/portal/landing/LandingPage.tsx",
+    "footer": "apitogo/portal/footer/Footer.tsx",
+    "logo": {
+      "light": "apitogo/portal/public/logo.svg",
+      "dark": "apitogo/portal/public/logo-dark.svg"
+    },
+    "docs": { "content": ["apitogo/portal/pages/**/*.{md,mdx}"] }
+  }
+}
+```
+
+`"logo": "apitogo/portal/public/logo.svg"` uses one image for both color schemes. Without a logo the
+header shows `portal.name`.
+
+### Order of the docs pages
+
+The sidebar lists a folder's `index` page first, then pages with an `order`, lowest first, then the
+rest (introduction, getting started and overview before the others, then by name). Set the order in
+the page itself:
+
+```md title=apitogo/portal/pages/authentication.md
+---
+title: Authentication
+order: 2
+---
+```
+
+In a React page: `export const order = 2;`.
+
+When the portal has a home page, `/` shows it, and an `index` page of the docs stays at `/index`.
+
+### What the pricing cards show
+
+Each card in `apitogo/plans.json` lists, in this order:
+
+1. The plan's limits: the rate limit (`limits.rateLimit`) and the quota (`limits.quota`)
+2. Its own lines, from `features`
+3. The endpoints the plan includes: the ones in `includedActions`, or every operation of the gateway
+   when the plan names none
+
+```json title=apitogo/plans.json
+{
+  "version": 1,
+  "plans": [
+    {
+      "sku": "pro",
+      "displayName": "Pro",
+      "priceAmount": 19,
+      "priceCurrency": "usd",
+      "billingInterval": "month",
+      "limits": { "rateLimit": { "calls": 600, "periodSeconds": 60 } },
+      "features": ["Email support", "Usage history"],
+      "includedActions": ["get:/api/makes", "get:/api/makes/{makeId}"]
+    }
+  ]
+}
+```
+
+`npx apitogo run` shows the same cards as the deployed portal.
+
+## Add a portal from scratch
+
+In a project that has no portal yet:
+
+```bash
+npx apitogo add portal
+```
+
+It adds `portal` to `apitogo.config.json` and writes the files above: `introduction.mdx` (the
+starter template adds a home page; `blank` writes an empty `pages/` folder), `theme.json` and the
+footer. Docs you already have (a `docs/` folder, for example) are used instead of a first page; pass
+`--docs <path>` to name them. Files that exist are never overwritten.
 
-Never put OIDC or Stripe secrets in `apitogo.config.json`. Use `.env` with
-`APITOGO_CONFIG_AUTHENTICATION__*` before publish.
+Never put secrets in `apitogo.config.json`: the config names a project secret (`secret:NAME`), and
+`npx apitogo secrets set NAME` stores the value.
 
 ## Preview locally
 
@@ -113,11 +196,11 @@ Shape-phase edits hot-reload when the dev server is running.
 
 ## Existing docs + OpenAPI folder
 
-If you already have `pages/` and an OpenAPI spec:
+In a folder that already has docs and an OpenAPI file, run `init` there: it uses the `docs/` folder
+in place, and `npx apitogo config` (openapi) adds the OpenAPI file:
 
 ```bash
 npx @lukoweb/apitogo@latest init
-cd dev-portal
 npx apitogo config
 npx apitogo run
 ```

package/docs/cli/walkthrough.md

@@ -49,7 +49,7 @@ npx apitogo add plans --template free
 `--create-spec` writes a small OpenAPI file with one `GET /health` operation, so the gateway has
 something to expose. For a real API, point `gateway.specs` at your own OpenAPI file instead.
 
-The Free template in `plans.json` allows 3 calls per minute and 1000 calls per 30 days. Change the
+The Free template in `plans.json` allows 60 calls per minute and 1000 calls per 30 days. Change the
 numbers in `plans.json` and deploy again to change the limits.
 
 With plans in the project, customers call the gateway with their API key alone. Their login token is

package/docs/components/slot.mdx

@@ -1,119 +1,116 @@
----
-title: Slot
-sidebar_icon: between-horizontal-start
-description:
-  Use the low-level Slot component for advanced slot management in custom pages and MDX content.
----
-
-The `Slot` component provides low-level access to APIToGo's slot system, allowing you to
-programmatically manage content injection in custom pages and React components.
-
-## Import
-
-```tsx
-import { Slot } from "@lukoweb/apitogo/components";
-```
-
-## Components
-
-The Slot system consists of two main components:
-
-### Slot.Target
-
-Renders content that has been injected into a specific slot.
-
-```tsx
-<Slot.Target name="my-slot" fallback={<div>No content</div>} />
-```
-
-**Props:**
-
-- `name` (required): The slot name to render content for
-- `fallback` (optional): Content to show when no slot content is available
-
-### Slot.Source
-
-Injects content into a specific slot. This component renders nothing but registers content to be
-displayed by `Slot.Target` components.
-
-```tsx
-<Slot.Source name="my-slot" type="append">
-  <div>Content to inject</div>
-</Slot.Source>
-```
-
-**Props:**
-
-- `name` (required): The slot name to inject content into
-- `type` (optional): How to handle multiple content sources
-  - `"replace"` (default): Replace existing content
-  - `"prepend"`: Add before existing content
-  - `"append"`: Add after existing content
-- `children`: The content to inject
-
-## Usage Example
-
-```tsx
-function MyCustomPage() {
-  return (
-    <div>
-      <h1>My Page</h1>
-
-      {/* Render slot content here */}
-      <Slot.Target name="custom-page-header" />
-
-      {/* Inject content into a slot */}
-      <Slot.Source name="custom-page-header">
-        <div className="bg-blue-100 p-4 rounded">Custom header content</div>
-      </Slot.Source>
-
-      <p>Page content here...</p>
-    </div>
-  );
-}
-```
-
-## Type Safety
-
-The Slot component is fully type-safe. All predefined slot names are available with autocomplete:
-
-```tsx
-// These will show autocomplete for available slot names
-<Slot.Target name="head-navigation-end" />
-<Slot.Source name="footer-before">Content</Slot.Source>
-```
-
-### Adding Custom Slot Names
-
-To add your own slot names with full type safety, augment the `CustomSlotNames` type:
-
-```tsx
-// types/slots.d.ts
-declare module "@lukoweb/apitogo" {
-  type CustomSlotNames = "my-custom-header" | "sidebar-extra";
-}
-```
-
-## Integration with Configuration
-
-The Slot component works with configuration-based slots. Content defined in your
-`apitogo.config.json` and content injected via `Slot.Source` components will be combined according
-to the `type` parameter.
-
-```tsx
-// In your site config
-slots: {
-  "page-header": <div>Config header</div>
-}
-
-// In your component
-<Slot.Source name="page-header" type="append">
-  <Button>Go Home</Button>
-</Slot.Source>
-
-// Renders both: Config header, then Component button
-<Slot.Target name="page-header" />
-```
-
-For basic configuration usage, see the [Slots Configuration](/docs/configuration/slots)
-documentation.
+---
+title: Slot
+sidebar_icon: between-horizontal-start
+description:
+  Use the low-level Slot component for advanced slot management in custom pages and MDX content.
+---
+
+The `Slot` component provides low-level access to APIToGo's slot system, allowing you to
+programmatically manage content injection in custom pages and React components.
+
+## Import
+
+```tsx
+import { Slot } from "@lukoweb/apitogo/components";
+```
+
+## Components
+
+The Slot system consists of two main components:
+
+### Slot.Target
+
+Renders content that has been injected into a specific slot.
+
+```tsx
+<Slot.Target name="my-slot" fallback={<div>No content</div>} />
+```
+
+**Props:**
+
+- `name` (required): The slot name to render content for
+- `fallback` (optional): Content to show when no slot content is available
+
+### Slot.Source
+
+Injects content into a specific slot. This component renders nothing but registers content to be
+displayed by `Slot.Target` components.
+
+```tsx
+<Slot.Source name="my-slot" type="append">
+  <div>Content to inject</div>
+</Slot.Source>
+```
+
+**Props:**
+
+- `name` (required): The slot name to inject content into
+- `type` (optional): How to handle multiple content sources
+  - `"replace"` (default): Replace existing content
+  - `"prepend"`: Add before existing content
+  - `"append"`: Add after existing content
+- `children`: The content to inject
+
+## Usage Example
+
+```tsx
+function MyCustomPage() {
+  return (
+    <div>
+      <h1>My Page</h1>
+
+      {/* Render slot content here */}
+      <Slot.Target name="custom-page-header" />
+
+      {/* Inject content into a slot */}
+      <Slot.Source name="custom-page-header">
+        <div className="bg-blue-100 p-4 rounded">Custom header content</div>
+      </Slot.Source>
+
+      <p>Page content here...</p>
+    </div>
+  );
+}
+```
+
+## Type Safety
+
+The Slot component is fully type-safe. All predefined slot names are available with autocomplete:
+
+```tsx
+// These will show autocomplete for available slot names
+<Slot.Target name="head-navigation-end" />
+<Slot.Source name="footer-before">Content</Slot.Source>
+```
+
+### Adding Custom Slot Names
+
+To add your own slot names with full type safety, augment the `CustomSlotNames` type:
+
+```tsx
+// types/slots.d.ts
+declare module "@lukoweb/apitogo" {
+  type CustomSlotNames = "my-custom-header" | "sidebar-extra";
+}
+```
+
+## Integration with Configuration
+
+The Slot component works with configuration-based slots. Content defined in your
+`apitogo.config.json` and content injected via `Slot.Source` components will be combined according
+to the `type` parameter.
+
+```tsx
+// In your site config
+slots: {
+  "page-header": <div>Config header</div>
+}
+
+// In your component
+<Slot.Source name="page-header" type="append">
+  <Button>Go Home</Button>
+</Slot.Source>
+
+// Renders both: Config header, then Component button
+<Slot.Target name="page-header" />
+```