@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/mcp/go-live.md

@@ -1,100 +1,100 @@
----
-title: Go live with MCP
-description:
-  Publish an APIToGo developer portal — platform plans, secrets, publish_dev_portal, and verify.
-sidebar_icon: rocket
----
-
-**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
-gateway plans, and verifies the live site.
-
-## Before you publish
-
-1. Confirm **gateway / API plans** in the manifest (or pass them in `apply_product_intent`). Do not
-   invent Free + Pro.
-2. Save secrets in the site **`.env`** (never in chat):
-
-   ```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. Choose a **platform hosting** plan: **Free**, **Starter**, or **Professional**. Agents should
-   call `list_platform_plans` / explain `freeProjectsQuota` before you pick. Starter and
-   Professional use Stripe checkout (`checkoutUrl`).
-
-## Happy path
-
-```text
-apply_product_intent({ mode: "goLive", siteDirectory, platformPlan?, ... })
-  → check_dev_portal_publish_readiness
-  → ensure_platform_plan (if needed)
-  → publish_dev_portal
-  → verify_dev_portal_live
-```
-
-If status is `blocked`, fix the readiness checklist (missing secrets, plan, OpenAPI). Do not invent
-credentials.
-
-After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When `stripeRequired` is
-true, create a Stripe webhook at `manualSteps.stripeWebhookUrl` for the listed events.
-
-Do not treat warm-pool URLs as live until publish / deploy / verify succeed.
-
-## Granular go-live paths
-
-### Portal-first
-
-Docs and billing before the API backend:
-
-```text
-shape → publish_dev_portal → deploy_backend → sync_gateway_plans_from_manifest(syncActionsOnly: true)
-```
-
-### Full-stack
-
-Backend already healthy:
-
-```text
-shape → deploy_backend → publish_dev_portal(skipBackendRedeploy: true)
-```
-
-### CI one-shot
-
-`bootstrap_dev_portal` provisions and deploys in one call (advanced).
-
-## Platform plan vs API plans
-
-| Kind             | Meaning                                     | How                       |
-| ---------------- | ------------------------------------------- | ------------------------- |
-| Platform hosting | Free / Starter / Professional on APItoGo    | `ensure_platform_plan`    |
-| Gateway / API    | End-user SKUs and rate limits on `/pricing` | Manifest / intent `plans` |
-
-## Publish behavior
-
-- Unchanged healthy backend/site artifacts are reused unless you force redeploy.
-- `publish_dev_portal` upserts gateway plans from the manifest; do **not** call
-  `sync_gateway_plans_from_manifest` before publish.
-- After a post-publish `deploy_backend`, sync actions with
-  `sync_gateway_plans_from_manifest({ syncActionsOnly: true })`.
-- Resume from `.apitogo/publish-state.json` or `resumeFromStep` if a previous publish stopped early.
-
-## CLI deploy vs MCP publish
-
-| Path                     | Use when                                            |
-| ------------------------ | --------------------------------------------------- |
-| MCP `publish_dev_portal` | Full product go-live (plans, auth, hosting, verify) |
-| CLI `npx apitogo deploy` | Publish config to platform (apihub + portal)        |
-
-See [Go live with CLI](../cli/go-live.md).
-
-## Related
-
-- [Shape](./shape.md)
-- [Tools](./tools.md)
-- [Authentication](../configuration/authentication.md)
-- [Manifest](../configuration/manifest.md)
+---
+title: Go live with MCP
+description:
+  Publish an APIToGo developer portal — platform plans, secrets, publish_dev_portal, and verify.
+sidebar_icon: rocket
+---
+
+**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
+gateway plans, and verifies the live site.
+
+## Before you publish
+
+1. Confirm **gateway / API plans** in the manifest (or pass them in `apply_product_intent`). Do not
+   invent Free + Pro.
+2. Save secrets in the site **`.env`** (never in chat):
+
+   ```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. Choose a **platform hosting** plan: **Free**, **Starter**, or **Professional**. Agents should
+   call `list_platform_plans` / explain `freeProjectsQuota` before you pick. Starter and
+   Professional use Stripe checkout (`checkoutUrl`).
+
+## Happy path
+
+```text
+apply_product_intent({ mode: "goLive", siteDirectory, platformPlan?, ... })
+  → check_dev_portal_publish_readiness
+  → ensure_platform_plan (if needed)
+  → publish_dev_portal
+  → verify_dev_portal_live
+```
+
+If status is `blocked`, fix the readiness checklist (missing secrets, plan, OpenAPI). Do not invent
+credentials.
+
+After success, register **`manualSteps.oidcRedirectUri`** in your IdP. When `stripeRequired` is
+true, create a Stripe webhook at `manualSteps.stripeWebhookUrl` for the listed events.
+
+Do not treat warm-pool URLs as live until publish / deploy / verify succeed.
+
+## Granular go-live paths
+
+### Portal-first
+
+Docs and billing before the API backend:
+
+```text
+shape → publish_dev_portal → deploy_backend → sync_gateway_plans_from_manifest(syncActionsOnly: true)
+```
+
+### Full-stack
+
+Backend already healthy:
+
+```text
+shape → deploy_backend → publish_dev_portal(skipBackendRedeploy: true)
+```
+
+### CI one-shot
+
+`bootstrap_dev_portal` provisions and deploys in one call (advanced).
+
+## Platform plan vs API plans
+
+| Kind             | Meaning                                     | How                       |
+| ---------------- | ------------------------------------------- | ------------------------- |
+| Platform hosting | Free / Starter / Professional on APItoGo    | `ensure_platform_plan`    |
+| Gateway / API    | End-user SKUs and rate limits on `/pricing` | Manifest / intent `plans` |
+
+## Publish behavior
+
+- Unchanged healthy backend/site artifacts are reused unless you force redeploy.
+- `publish_dev_portal` upserts gateway plans from the manifest; do **not** call
+  `sync_gateway_plans_from_manifest` before publish.
+- After a post-publish `deploy_backend`, sync actions with
+  `sync_gateway_plans_from_manifest({ syncActionsOnly: true })`.
+- Resume from `.apitogo/publish-state.json` or `resumeFromStep` if a previous publish stopped early.
+
+## CLI deploy vs MCP publish
+
+| Path                     | Use when                                            |
+| ------------------------ | --------------------------------------------------- |
+| MCP `publish_dev_portal` | Full product go-live (plans, auth, hosting, verify) |
+| CLI `npx apitogo deploy` | Publish config to platform (apihub + portal)        |
+
+See [Go live with CLI](../cli/go-live.md).
+
+## Related
+
+- [Shape](./shape.md)
+- [Tools](./tools.md)
+- [Authentication](../configuration/authentication.md)
+- [Manifest](../configuration/overview.md)

package/docs/mcp/overview.md

@@ -1,76 +1,76 @@
----
-title: MCP overview
-description:
-  Use the APItoGo MCP server to scaffold, shape, and publish API products from an AI agent.
-sidebar_icon: bot
----
-
-The **APItoGo MCP** server lets AI agents manage projects, developer portals, gateway plans, backend
-deploy, and go-live. You can use MCP tools, edit site files yourself, or mix both.
-
-**First time?** Install and wire the server in your agent →
-**[Configure MCP in your agent](./setup.md)**. Then follow the [Quickstart](../quickstart.md).
-
-## What you get
-
-- Scaffold a local portal site (`create_dev_portal` / `apply_product_intent`)
-- Shape OpenAPI, plans, branding, theme, and docs pages
-- Publish to APItoGo hosting (`publish_dev_portal`) with platform plans **Free**, **Starter**, or
-  **Professional**
-- Deploy backends and sync gateway actions after publish
-
-Prefer **`apply_product_intent`** for “create / shape / go live” prompts. See [Shape](./shape.md)
-and [Go live](./go-live.md).
-
-## Prerequisites
-
-### MCP host environment
-
-| Variable             | Required | Purpose           |
-| -------------------- | -------- | ----------------- |
-| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
-| `APITOGO_API_SECRET` | Yes      | Platform API auth |
-
-### Agent host
-
-- 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 chat)
-- Stripe secrets at publish only when you have **paid** project plans
-
-## Changing your site
-
-You choose how to edit the portal:
-
-| Approach                | When it helps                                                                                       |
-| ----------------------- | --------------------------------------------------------------------------------------------------- |
-| **MCP tools**           | Agent-driven changes; tools can wire navigation/config and run validation. See [Tools](./tools.md). |
-| **Edit files directly** | Full control in your editor — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc.    |
-
-Useful MCP tools (optional — not required):
-
-| Change                              | Tool                                             |
-| ----------------------------------- | ------------------------------------------------ |
-| Add / edit a docs page              | `add_dev_portal_page` / `update_dev_portal_page` |
-| OpenAPI                             | `set_dev_portal_openapi`                         |
-| Plans, branding, backend, projectId | `update_dev_portal_manifest`                     |
-| Theme                               | `set_dev_portal_theme`                           |
-
-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).
-
-## Next
-
-- [Configure MCP](./setup.md)
-- [Quickstart](../quickstart.md)
-- [Shape](./shape.md) · [Go live](./go-live.md) · [Tools](./tools.md)
-- CLI without an agent: [CLI overview](../cli/overview.md)
+---
+title: MCP overview
+description:
+  Use the APItoGo MCP server to scaffold, shape, and publish API products from an AI agent.
+sidebar_icon: bot
+---
+
+The **APItoGo MCP** server lets AI agents manage projects, developer portals, gateway plans, backend
+deploy, and go-live. You can use MCP tools, edit site files yourself, or mix both.
+
+**First time?** Install and wire the server in your agent →
+**[Configure MCP in your agent](./setup.md)**. Then follow the [Quickstart](../quickstart.md).
+
+## What you get
+
+- Scaffold a local portal site (`create_dev_portal` / `apply_product_intent`)
+- Shape OpenAPI, plans, branding, theme, and docs pages
+- Publish to APItoGo hosting (`publish_dev_portal`) with platform plans **Free**, **Starter**, or
+  **Professional**
+- Deploy backends and sync gateway actions after publish
+
+Prefer **`apply_product_intent`** for “create / shape / go live” prompts. See [Shape](./shape.md)
+and [Go live](./go-live.md).
+
+## Prerequisites
+
+### MCP host environment
+
+| Variable             | Required | Purpose           |
+| -------------------- | -------- | ----------------- |
+| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
+| `APITOGO_API_SECRET` | Yes      | Platform API auth |
+
+### Agent host
+
+- 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 chat)
+- Stripe secrets at publish only when you have **paid** project plans
+
+## Changing your site
+
+You choose how to edit the portal:
+
+| Approach                | When it helps                                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------------------------- |
+| **MCP tools**           | Agent-driven changes; tools can wire navigation/config and run validation. See [Tools](./tools.md). |
+| **Edit files directly** | Full control in your editor — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc.    |
+
+Useful MCP tools (optional — not required):
+
+| Change                              | Tool                                             |
+| ----------------------------------- | ------------------------------------------------ |
+| Add / edit a docs page              | `add_dev_portal_page` / `update_dev_portal_page` |
+| OpenAPI                             | `set_dev_portal_openapi`                         |
+| Plans, branding, backend, projectId | `update_dev_portal_manifest`                     |
+| Theme                               | `set_dev_portal_theme`                           |
+
+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/overview.md).
+
+## Next
+
+- [Configure MCP](./setup.md)
+- [Quickstart](../quickstart.md)
+- [Shape](./shape.md) · [Go live](./go-live.md) · [Tools](./tools.md)
+- CLI without an agent: [CLI overview](../cli/overview.md)

package/docs/quickstart.md

@@ -1,72 +1,88 @@
----
-title: Quickstart
-description: Get started with APIToGo MCP — connect your agent, shape a portal, and preview locally.
-sidebar_icon: circle-play
----
-
-Build an API product (developer portal, plans, gateway, backend) with an AI agent and the **APItoGo
-MCP** server. Works with Cursor, Claude, Codex, and other MCP hosts.
-
-## Prerequisites
-
-- **Node.js 20+** on the agent machine
-- An MCP-capable agent (Cursor, Claude Desktop / Claude Code, Codex, …)
-- Platform API keys from [apitogo.com](https://apitogo.com)
-
-## Get started
-
-<Stepper>
-
-1. **Create API credentials**
-
-   In the [APItoGo dashboard](https://apitogo.com), create an API key and copy the **key id** and
-   **secret**.
-
-1. **Configure MCP in your agent**
-
-   Wire `@lukoweb/apitogo-mcp` with your keys. Paste-ready snippets for **Cursor**, **Claude
-   Desktop**, **Claude Code**, **Codex**, and other hosts:
-
-   → **[Configure MCP in your agent](./mcp/setup.md)**
-
-   Verify with `whoami` or by listing APItoGo tools.
-
-1. **Shape a product**
-
-   Ask your agent something like:
-
-   > Create a portal in `./dev-portal` for my API in `./api` with Free (100/min) and Pro (1000/min);
-   > make `/health` public.
-
-   The agent should call `apply_product_intent` with `mode: "shape"` (or `create_dev_portal` for a
-   default scaffold). See [Shape](./mcp/shape.md).
-
-1. **Preview locally**
-
-   ```bash
-   cd ./dev-portal
-   npx apitogo run
-   ```
-
-   Open `http://localhost:3000`. Iterate with MCP tools (pages, OpenAPI, theme, plans). Customize
-   the home page in `landing/LandingPage.tsx` when you have real copy.
-
-1. **Go live when ready**
-
-   Save OIDC (and Stripe if you have paid plans) in the site `.env`, then ask the agent to publish —
-   see [Go live](./mcp/go-live.md). Never paste secrets into chat.
-
-</Stepper>
-
-## What's next
-
-- [Configure MCP](./mcp/setup.md) — agent-specific install
-- [MCP overview](./mcp/overview.md) — what the server does
-- [Shape](./mcp/shape.md) · [Go live](./mcp/go-live.md) · [Tools](./mcp/tools.md)
-- [Manifest](./configuration/manifest.md) · [Authentication](./configuration/authentication.md)
-
-## Without an agent (CLI)
-
-Prefer the terminal? Use the **`apitogo`** CLI for the same config-first workflow:
-
-→ **[Install the CLI](./cli/setup.md)** · [Shape](./cli/shape.md) · [Go live](./cli/go-live.md)
+---
+title: Quickstart
+description: >-
+  From an empty folder to a live API product in a few commands: create the project, preview it
+  locally, then deploy the portal, gateway, sign-in and plans.
+sidebar_icon: circle-play
+---
+
+APItoGo turns your API into a product: a developer portal with docs and an API reference, a gateway
+that checks API keys and limits, sign-in for your users, and plans they pick. One file,
+`apitogo.config.json`, describes it all, and the `apitogo` CLI builds and deploys it.
+
+## Prerequisites
+
+- **Node.js 20+**
+- An account on [apitogo.com](https://apitogo.com) (needed to deploy, not to try it locally)
+
+## Get started
+
+<Stepper>
+
+1. **Create the project**
+
+   ```bash
+   npx @lukoweb/apitogo@latest create --template full
+   ```
+
+   It asks for a name, makes a folder for it and writes everything a working product needs:
+   - `apitogo.config.json` with a portal, a gateway, sign-in and plans
+   - a home page, a footer, a theme and a first docs page in `apitogo/portal/`
+   - a small Node.js API in `server/` with its OpenAPI file
+   - `apitogo/plans.json` with starter plans you can change
+
+   Run `create` without `--template` to pick the services one at a time instead.
+
+1. **Preview it locally**
+
+   ```bash
+   cd <your project folder>
+   npx apitogo run
+   ```
+
+   Open `http://localhost:3000`. The console signs in with a demo account (`demo@apitogo.local` /
+   `password`), so you can try the pricing, plans and API keys pages before anything is deployed.
+   Edit the pages in `apitogo/portal/` and the preview updates.
+
+1. **Sign in to APItoGo**
+
+   ```bash
+   npx apitogo login
+   ```
+
+   A browser window opens; sign in there.
+
+1. **Deploy**
+
+   ```bash
+   npx apitogo deploy
+   ```
+
+   The first deploy creates the project (it asks which hosting plan: Free, Starter or Professional),
+   then sets up each service and prints the addresses:
+
+   ```
+   portal: deployed to production (https://<name>.apitogo.com)
+   gateway: deployed (https://<name>.api.apitogo.com/)
+   ```
+
+1. **Try it as your users will**
+
+   Open the portal, create an account, pick the Free plan, create an API key on the **API keys**
+   page, and call your API through the gateway with it.
+
+</Stepper>
+
+## What's next
+
+- [Configuration overview](./configuration/overview.md): every section of `apitogo.config.json`
+- [Portal](./configuration/portal.md): docs, home page, footer, logo and theme
+- [Plans](./configuration/plans.md) and [Set up Stripe for paid plans](./guides/stripe-setup.mdx)
+- [Walkthrough](./cli/walkthrough.md): the same journey one service at a time, with a customer's
+  first call
+- [CLI commands](./cli/commands.md)
+
+## With an AI agent
+
+The **APItoGo MCP** server lets an agent such as Claude Code or Cursor run the same steps for you.
+See [Configure MCP in your agent](./mcp/setup.md).

package/docs/writing.mdx

@@ -1,72 +1,68 @@
----
-title: Writing
-sidebar_icon: book-open-text
-description: A guide to writing documentation in APIToGo using Markdown and MDX.
----
-
-Get started with creating rich documentation in APIToGo using Markdown and MDX. This guide covers
-the essentials to help you begin documenting your project.
-
-## Quick Start
-
-1. **Create a markdown file** in your `pages` directory
-2. **Add frontmatter** with title and metadata
-3. **Configure navigation** to make it discoverable
-4. **Write content** using Markdown or MDX
-
-### Basic Document Structure
-
-```md
----
-title: My Document
-sidebar_icon: file-text
----
-
-Your content goes here using standard Markdown syntax.
-```
-
-## Adding to Navigation
-
-To make your documentation discoverable, add it to the navigation configuration. Documents are
-referenced by their file path:
-
-```ts title="config"
-const config = {
-  navigation: [
-    {
-      type: "doc",
-      file: "my-document",
-      label: "My Document",
-    },
-  ],
-};
-```
-
-Learn more about configuring navigation at
-[Navigation → Documents](/docs/configuration/navigation#type-doc).
-
-## File Organization
-
-Organize your documentation files in logical directories:
-
-```
-pages/
-├── getting-started/
-│   ├── installation.md
-│   └── quick-start.md
-├── guides/
-│   ├── authentication.md
-│   └── deployment.md
-└── api/
-    └── reference.md
-```
-
-## What's Next?
-
-Explore the detailed guides to enhance your documentation:
-
-- **[Markdown Overview](/docs/markdown/overview)** - Complete markdown syntax reference
-- **[Frontmatter](/docs/markdown/frontmatter)** - Document metadata and configuration
-- **[MDX](/docs/markdown/mdx)** - Interactive components in markdown
-- **[Admonitions](/docs/markdown/admonitions)** - Callouts and alerts
-- **[Code Blocks](/docs/markdown/code-blocks)** - Syntax highlighting and features
+---
+title: Writing
+sidebar_icon: book-open-text
+description: A guide to writing documentation in APIToGo using Markdown and MDX.
+---
+
+Get started with creating rich documentation in APIToGo using Markdown and MDX. This guide covers
+the essentials to help you begin documenting your project.
+
+## Quick Start
+
+1. **Create a markdown file** in `apitogo/portal/pages/`
+2. **Add frontmatter** with title and metadata
+3. **Write content** using Markdown or MDX
+
+The page shows in the sidebar on its own.
+
+### Basic Document Structure
+
+```md
+---
+title: My Document
+sidebar_icon: file-text
+---
+
+Your content goes here using standard Markdown syntax.
+```
+
+## Adding to Navigation
+
+The sidebar is built from the files: every page in `apitogo/portal/pages/` (or the folders
+`portal.docs.content` names) is listed, and each folder becomes a section. A folder's `index` page
+comes first, then pages with an `order`, lowest first, then the rest by name:
+
+```md
+---
+title: Authentication
+order: 2
+---
+```
+
+A page with `draft: true` is left out of deployed portals.
+
+## File Organization
+
+Organize your documentation files in logical directories:
+
+```
+pages/
+├── getting-started/
+│   ├── installation.md
+│   └── quick-start.md
+├── guides/
+│   ├── authentication.md
+│   └── deployment.md
+└── api/
+    └── reference.md
+```
+
+## What's Next?
+
+Explore the detailed guides to enhance your documentation:
+
+- **[Markdown Overview](/docs/markdown/overview)** - Complete markdown syntax reference
+- **[Frontmatter](/docs/markdown/frontmatter)** - Document metadata and configuration
+- **[MDX](/docs/markdown/mdx)** - Interactive components in markdown
+- **[Admonitions](/docs/markdown/admonitions)** - Callouts and alerts
+- **[Code Blocks](/docs/markdown/code-blocks)** - Syntax highlighting and features