@lukoweb/apitogo 0.2.57 → 0.2.59

package/dist/cli/cli.js

@@ -5931,11 +5931,23 @@ var PortalSchema = z.strictObject({
   landing: path3.optional(),
   /** The footer: a React component file shown under every page except the console's (API-129). */
   footer: path3.optional(),
-  /** The logo in the portal header: one image, or one per color scheme (API-129). */
-  logo: z.union([
-    path3,
-    z.strictObject({ light: path3, dark: path3, alt: z.string().optional() })
-  ]).optional(),
+  /**
+   * The logo in the portal header: one image, or one per color scheme (API-129). `dark` is optional; without it the
+   * light image is used in both.
+   */
+  logo: z.union(
+    [
+      path3,
+      z.strictObject({
+        light: path3,
+        dark: path3.optional(),
+        alt: z.string().optional()
+      })
+    ],
+    {
+      error: 'must be an image path or https address, or { "light": "...", "dark": "...", "alt": "..." } (dark and alt are optional)'
+    }
+  ).optional(),
   requireAuth: z.union([z.boolean(), z.strictObject({ exclude: pathList })], {
     error: 'must be true, false or { "exclude": ["/route", ...] }'
   }).optional(),
@@ -6507,7 +6519,11 @@ function resolveConfigV2(config2, configPath) {
           dark: logoSource(configDir, portal.logo)
         } : {
           light: logoSource(configDir, portal.logo.light),
-          dark: logoSource(configDir, portal.logo.dark),
+          // Without a dark image, the light one is used in both color schemes.
+          dark: logoSource(
+            configDir,
+            portal.logo.dark ?? portal.logo.light
+          ),
           ...portal.logo.alt ? { alt: portal.logo.alt } : {}
         }
       } : {},
@@ -7472,6 +7488,8 @@ var ServiceManifestSchema = z3.looseObject({
   services: z3.looseObject({
     portal: z3.looseObject({
       url: z3.string().optional(),
+      /** The portal's custom domain once it is ready, such as `https://docs.acme.com` (API-130). */
+      customDomain: z3.string().optional(),
       docs: z3.looseObject({ provider: z3.string(), url: z3.string().optional() }).optional(),
       console: z3.looseObject({ links: z3.record(z3.string(), z3.string()).optional() }).optional()
     }).optional(),
@@ -7643,6 +7661,20 @@ function withPortalEntry(existing, info) {
     }
   };
 }
+function withPortalCustomDomain(existing, customDomain) {
+  if (!existing) return void 0;
+  const portal = existing.services.portal;
+  if (portal?.customDomain === customDomain) return void 0;
+  if (!portal && customDomain === void 0) return void 0;
+  const { customDomain: _previous, ...rest } = portal ?? {};
+  return {
+    ...existing,
+    services: {
+      ...existing.services,
+      portal: customDomain === void 0 ? rest : { ...rest, customDomain }
+    }
+  };
+}
 function withGatewayEntry(existing, info) {
   const base = existing ?? parseManifest({
     schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
@@ -7922,7 +7954,8 @@ function derivedCorsSites(sites) {
   };
   const found = [
     { origin: originOf(sites.docsUrl), source: "docs" },
-    { origin: originOf(sites.portalUrl), source: "portal" }
+    { origin: originOf(sites.portalUrl), source: "portal" },
+    { origin: originOf(sites.portalCustomDomain), source: "portal" }
   ].flatMap((site) => site.origin ? [{ ...site, origin: site.origin }] : []);
   const seen = /* @__PURE__ */ new Set();
   return found.filter((site) => !seen.has(site.origin) && seen.add(site.origin)).sort((a, b) => a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0);
@@ -11166,7 +11199,7 @@ import {
 // package.json
 var package_default = {
   name: "@lukoweb/apitogo",
-  version: "0.2.57",
+  version: "0.2.59",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -15720,11 +15753,12 @@ var collectPaths = (resolved, parentPath) => resolved.flatMap((r) => [
   ...r.path !== parentPath ? [r.path] : [],
   ...collectPaths(r.children, r.path)
 ]);
+var prerenderFileFor = (urlPath) => urlPath === "/" ? "/index.html" : urlPath.endsWith("/index") ? `${urlPath}/index.html` : `${urlPath}.html`;
 var collectRewrites = (resolved) => resolved.flatMap((r) => [
   ...r.hasStrippedParams && r.path ? [
     {
       source: `${r.path}/(.+)`,
-      destination: r.path === "/" ? "/index.html" : `${r.path}.html`
+      destination: prerenderFileFor(r.path)
     }
   ] : [],
   ...collectRewrites(r.children)
@@ -16549,6 +16583,15 @@ async function isConfigV2(dir) {
     return false;
   }
 }
+async function isLegacyConfig(dir) {
+  let text2;
+  try {
+    text2 = await readFile18(path51.join(dir, APITOGO_CONFIG_FILENAME), "utf8");
+  } catch {
+    return false;
+  }
+  return !/"version"\s*:\s*2\b/.test(text2);
+}
 async function fetchSecretNames(config2, configuredProjectId, args, deps) {
   const projectId = configuredProjectId || deps.envProjectId?.trim();
   if (args.offline || !deps.listSecrets || !projectId) return {};
@@ -16579,6 +16622,7 @@ async function addGatewayOnlineRules(report, resolved, args, deps) {
     deps.gateway,
     derivedCorsSites({
       portalUrl: manifest?.services.portal?.url,
+      portalCustomDomain: manifest?.services.portal?.customDomain,
       docsUrl: resolved.portal?.docs.provider === "external" ? resolved.portal.docs.url : void 0
     })
   );
@@ -27162,6 +27206,22 @@ init_invariant();
 import { createHash as createHash4 } from "node:crypto";
 import { readFile as readFile28 } from "node:fs/promises";
 init_invariant();
+
+// src/cli/deploy/custom-domain.ts
+async function readyCustomDomainOrigin(client, projectId) {
+  if (!client.getCustomDomain) return void 0;
+  let domain;
+  try {
+    domain = await client.getCustomDomain(projectId);
+  } catch {
+    return void 0;
+  }
+  const hostname = domain.hostname?.trim().toLowerCase();
+  if (domain.status?.toLowerCase() !== "ready" || !hostname) return null;
+  return `https://${hostname}`;
+}
+
+// src/cli/deploy/gateway.ts
 var GatewayDeployError = class extends ApitogoError {
   constructor(code, message, developerHint) {
     super(message, { developerHint, title: "Cannot deploy the gateway" });
@@ -27207,6 +27267,15 @@ async function readSpec(gateway) {
     );
   }
 }
+async function recordPortalCustomDomain(resolved, projectId, client) {
+  const origin = await readyCustomDomainOrigin(client, projectId);
+  if (origin === void 0) return;
+  const updated = withPortalCustomDomain(
+    await readManifest(resolved.state),
+    origin ?? void 0
+  );
+  if (updated) await writeManifest(resolved.state, updated);
+}
 async function gatewayDeployInputs(resolved, projectId) {
   const gateway = resolved.gateway;
   if (!gateway) throw new Error("gateway is not configured");
@@ -27216,6 +27285,7 @@ async function gatewayDeployInputs(resolved, projectId) {
     gateway,
     derivedCorsSites({
       portalUrl: manifest?.services.portal?.url,
+      portalCustomDomain: manifest?.services.portal?.customDomain,
       docsUrl: resolved.portal?.docs.provider === "external" ? resolved.portal.docs.url : void 0
     })
   );
@@ -27304,6 +27374,7 @@ function rejected(what, error) {
   throw error;
 }
 async function deployGateway(resolved, projectId, deps, options = {}) {
+  await recordPortalCustomDomain(resolved, projectId, deps.client);
   const { gateway, spec, body, specHash, configHash } = await gatewayDeployInputs(resolved, projectId);
   assertDeployable(gateway);
   const backend = await backendDeployInputs(gateway, projectId);
@@ -28118,6 +28189,14 @@ function identityBrandingBody(resolved) {
   };
 }
 var IDENTITY_BRANDING_STEP = "branding";
+var IDENTITY_PORTAL_ADDRESS_STEP = "portal-address";
+async function customDomainCallbackOf(client, projectId, portalUrl) {
+  const origin = await readyCustomDomainOrigin(client, projectId);
+  if (!origin) return void 0;
+  const callback = `${origin}${PORTAL_CALLBACK_PATH}`;
+  const current = `${portalUrl.replace(/\/+$/, "")}${PORTAL_CALLBACK_PATH}`;
+  return callback.toLowerCase() === current.toLowerCase() ? void 0 : callback;
+}
 function identityInputsHash(projectId, body) {
   return stableJson({ projectId, body });
 }
@@ -28282,6 +28361,29 @@ async function deployIdentity(resolved, projectId, deps, options = {}) {
       }
     });
   }
+  const customCallback = await customDomainCallbackOf(
+    client,
+    projectId,
+    portalUrl
+  );
+  if (customCallback) {
+    const portalBody = {
+      ...body,
+      portalRedirectUris: [...body.portalRedirectUris, customCallback]
+    };
+    steps.push({
+      name: IDENTITY_PORTAL_ADDRESS_STEP,
+      hash: () => identityInputsHash(projectId, portalBody),
+      run: async () => {
+        try {
+          await client.putProjectIdentity(projectId, portalBody);
+        } catch (error) {
+          return rejected2(error);
+        }
+        return { redirectUri: customCallback };
+      }
+    });
+  }
   const wanted = normalizedConnections(resolved);
   if (wanted.length > 0 || (await recordedConnectionIds(resolved)).length > 0)
     steps.push(connectionsStep(resolved, projectId, client, wanted));
@@ -28317,8 +28419,11 @@ async function deployIdentity(resolved, projectId, deps, options = {}) {
   const brandingRan = outcomes.some(
     (outcome) => outcome.step === IDENTITY_BRANDING_STEP && !outcome.skipped
   );
+  const portalAddressRan = outcomes.some(
+    (outcome) => outcome.step === IDENTITY_PORTAL_ADDRESS_STEP && !outcome.skipped
+  );
   return {
-    status: ran || connectionsRan || brandingRan ? "deployed" : "unchanged",
+    status: ran || connectionsRan || brandingRan || portalAddressRan ? "deployed" : "unchanged",
     steps: outcomes.map((outcome) => ({
       step: outcome.step,
       skipped: outcome.skipped
@@ -29753,7 +29858,7 @@ var deploy_default = {
   }),
   handler: async (argv) => {
     await captureEvent({ argv, event: "apitogo deploy" });
-    if (await isConfigV2(path85.resolve(process.cwd(), argv.dir))) {
+    if (!await isLegacyConfig(path85.resolve(process.cwd(), argv.dir))) {
       await deployProject(argv);
       return;
     }
@@ -31579,7 +31684,7 @@ var teardown_default = {
   }),
   handler: async (argv) => {
     await captureEvent({ argv, event: "apitogo teardown" });
-    if (await isConfigV2(path95.resolve(process.cwd(), argv.dir))) {
+    if (!await isLegacyConfig(path95.resolve(process.cwd(), argv.dir))) {
       await teardownProject(argv);
       return;
     }

package/dist/cli/worker.js

@@ -113,6 +113,9 @@ var ProtectedRoutesSchema = z.pipe(
   z.transform(normalizeProtectedRoutes)
 );
 
+// src/vite/prerender/utils.ts
+var prerenderFileFor = (urlPath) => urlPath === "/" ? "/index.html" : urlPath.endsWith("/index") ? `${urlPath}/index.html` : `${urlPath}.html`;
+
 // src/vite/prerender/worker.ts
 var { template, distDir, serverConfigPath, entryServerPath, writeRedirects } = Piscina.workerData;
 var isStaticNavigateWarning = (args) => typeof args[0] === "string" && args[0].includes("<Navigate> must not be used on the initial render");
@@ -128,7 +131,7 @@ var config = await runPluginTransformConfig(rawConfig);
 var routes = server.getRoutesByConfig(config);
 var { basePath } = config;
 var renderPage = async ({ urlPath }) => {
-  const filename = urlPath === "/" ? "/index.html" : `${urlPath}.html`;
+  const filename = prerenderFileFor(urlPath);
   const pathname = joinUrl(basePath, urlPath);
   const url = joinUrl("http://localhost", pathname);
   const outputPath = path.join(distDir, filename);

package/docs/cli/overview.md

@@ -70,16 +70,15 @@ Secrets are project secrets (`npx apitogo secrets set`), never files. Details:
 
 ## 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` |
+Each MCP tool runs one CLI command in the project folder, so both give the same result.
+
+| Task              | CLI                                           | MCP (agent)                           |
+| ----------------- | --------------------------------------------- | ------------------------------------- |
+| Create            | `npx @lukoweb/apitogo@latest create`          | `apitogo_create`                      |
+| Shape config      | `npx apitogo config` + file edits             | `apitogo_config` + file edits         |
+| Preview           | `npx apitogo run`                             | `npx apitogo run` (you start it)      |
+| Deploy            | `npx apitogo plan` / `npx apitogo deploy`     | `apitogo_plan` / `apitogo_deploy`     |
+| Status / teardown | `npx apitogo status` / `npx apitogo teardown` | `apitogo_status` / `apitogo_teardown` |
 
 Prefer MCP when an agent should drive changes. Prefer CLI for CI, scripts, or terminal-only
 workflows.

package/docs/cli/setup.md

@@ -6,8 +6,8 @@ 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`.
+`apitogo.config.json`, preview with `npx apitogo run`, and publish with `npx apitogo deploy`. The
+[MCP tools](../mcp/tools.md) run these same commands for an agent.
 
 Examples in these docs use **`npx apitogo`** so they run the project-local CLI. A global install is
 optional and not required.

package/docs/configuration/portal.md

@@ -79,7 +79,8 @@ An image in the portal's `public/` folder, or an `https://` address:
 "logo": "apitogo/portal/public/logo.svg"
 ```
 
-One image per color scheme, with the text read out by screen readers:
+One image per color scheme, with the text read out by screen readers. `dark` and `alt` are optional;
+without `dark` the light image is shown in both:
 
 ```json
 "logo": {

package/docs/mcp/go-live.md

@@ -1,100 +1,72 @@
 ---
 title: Go live with MCP
 description:
-  Publish an APIToGo developer portal — platform plans, secrets, publish_dev_portal, and verify.
+  Create the platform project, preview the deploy, deploy and follow the result with the MCP tools.
 sidebar_icon: rocket
 ---
 
-**Go live** publishes your shaped portal to APItoGo hosting, optionally deploys the backend, upserts
-gateway plans, and verifies the live site.
+Going live puts the project on the APItoGo platform: the portal gets its address, the gateway starts
+protecting the API, and sign-in and plans work. It is the same as `apitogo deploy` in a terminal.
 
-## Before you publish
+## 1. Make the platform project
 
-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):
+> Put Books on APItoGo.
 
-   ```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_...
-   ```
+The agent calls **`apitogo_project_create`**. It creates the project and writes its id into
+`apitogo.config.json`.
 
-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`).
+| Plan                      | When                                                  |
+| ------------------------- | ----------------------------------------------------- |
+| `free`                    | The default; enough to try everything without payment |
+| `starter`, `professional` | Needed to sell paid API plans                         |
 
-## Happy path
+A paid plan answers with a checkout link: you open it and pay; the agent never pays. Already have a
+project? **`apitogo_project_use`** points the folder at it by its id.
 
-```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.
+## 2. Secrets
 
-## Granular go-live paths
+Paid plans need the project's Stripe key and webhook secret. Set them yourself in a terminal; a
+secret's value never goes through the agent:
 
-### Portal-first
-
-Docs and billing before the API backend:
-
-```text
-shape → publish_dev_portal → deploy_backend → sync_gateway_plans_from_manifest(syncActionsOnly: true)
+```bash
+npx apitogo secrets set STRIPE_API_KEY
 ```
 
-### Full-stack
-
-Backend already healthy:
-
-```text
-shape → deploy_backend → publish_dev_portal(skipBackendRedeploy: true)
+```bash
+npx apitogo secrets set STRIPE_WEBHOOK
 ```
 
-### CI one-shot
+**`apitogo_secrets_list`** shows which names are set. See the
+[Stripe guide](../guides/stripe-setup.mdx).
 
-`bootstrap_dev_portal` provisions and deploys in one call (advanced).
+## 3. Preview, then deploy
 
-## Platform plan vs API plans
+- **`apitogo_plan`** says, for each service, whether a deploy would change it and why. It changes
+  nothing.
+- **`apitogo_deploy`** deploys every service that changed: identity, gateway, plans, then the
+  portal. The first deploy takes several minutes; later ones skip what did not change. `only` limits
+  it to some services, `force` redeploys them anyway.
 
-| 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` |
+A change that cannot be undone, such as switching the identity provider, stops the deploy with an
+explanation. The agent asks you, and only then deploys again with `confirmIrreversible`.
 
-## Publish behavior
+## 4. See what is live
 
-- 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.
+**`apitogo_status`** shows each service's state and its addresses: the portal, the gateway's base
+URL and the sign-in issuer.
 
-## CLI deploy vs MCP publish
+## When something fails
 
-| 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)        |
+Every tool answers with the CLI's JSON. A failure carries `error` and usually a `hint` with the next
+step, for example to log in:
 
-See [Go live with CLI](../cli/go-live.md).
+| Message                  | What to do                                                                        |
+| ------------------------ | --------------------------------------------------------------------------------- |
+| Not logged in            | Run `npx apitogo login`, or give the server API credentials ([setup](./setup.md)) |
+| A secret is missing      | Set it with `npx apitogo secrets set NAME`                                        |
+| Hosting is not ready yet | Wait a few minutes, then deploy again                                             |
 
-## Related
+## Remove it
 
-- [Shape](./shape.md)
-- [Tools](./tools.md)
-- [Authentication](../configuration/authentication.md)
-- [Manifest](../configuration/overview.md)
+**`apitogo_teardown`** deletes the platform project (local files stay), or with `only` just its
+gateway, identity or plans. The agent must ask you and type the project's name back.

package/docs/mcp/overview.md

@@ -1,76 +1,58 @@
 ---
 title: MCP overview
 description:
-  Use the APItoGo MCP server to scaffold, shape, and publish API products from an AI agent.
+  Let an AI agent create, shape, check and deploy an APItoGo project through the APItoGo MCP server.
 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.
+The **APItoGo MCP** server (`@lukoweb/apitogo-mcp`) gives an AI agent the same commands you run in a
+terminal: create a project, add services, change plans and pages, check, preview and deploy. Each
+tool runs the [`apitogo` CLI](../cli/overview.md) in the project folder, so an agent and a person
+always get the same result.
 
-**First time?** Install and wire the server in your agent →
-**[Configure MCP in your agent](./setup.md)**. Then follow the [Quickstart](../quickstart.md).
+**First time?** Wire the server into your agent → **[Configure MCP in your agent](./setup.md)**.
 
-## What you get
+## How it fits together
 
-- 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
+```
+agent ──MCP tool──> apitogo-mcp ──runs──> apitogo <command> --json   (in the project folder)
+                                              │
+                                              ├── apitogo.config.json, apitogo/   (your files)
+                                              └── APItoGo platform               (deploy, status)
+```
 
-Prefer **`apply_product_intent`** for “create / shape / go live” prompts. See [Shape](./shape.md)
-and [Go live](./go-live.md).
+- Everything the project is lives in `apitogo.config.json` (config version 2) and the `apitogo/`
+  folder. See [Configuration](../configuration/overview.md).
+- The tools answer with the CLI's JSON, so the agent sees what changed, what a deploy would do, and
+  why something failed.
+- The agent can also edit the project's files directly (the landing page, docs pages, OpenAPI file,
+  `plans.json`) when no tool covers a change.
 
-## Prerequisites
+## The usual flow
 
-### MCP host environment
+| Step                      | Tool                                                       |
+| ------------------------- | ---------------------------------------------------------- |
+| Make the project folder   | `apitogo_create`, or `apitogo_init` + `apitogo_add`        |
+| Shape it                  | `apitogo_config` (name, OpenAPI, pages, plans), file edits |
+| Check it                  | `apitogo_check`                                            |
+| Make the platform project | `apitogo_project_create`                                   |
+| Preview the deploy        | `apitogo_plan`                                             |
+| Deploy                    | `apitogo_deploy`                                           |
+| See what is live          | `apitogo_status`                                           |
 
-| Variable             | Required | Purpose           |
-| -------------------- | -------- | ----------------- |
-| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
-| `APITOGO_API_SECRET` | Yes      | Platform API auth |
+Details: [Shape a project](./shape.md) · [Go live](./go-live.md) · [All tools](./tools.md).
 
-### Agent host
+## What the agent never does
 
-- 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).
+- **Handle secret values.** You set secrets such as the Stripe key yourself with
+  `apitogo secrets set NAME` in a terminal. The agent can list their names.
+- **Delete without you.** `apitogo_teardown` needs the project's name typed back, and the server
+  tells the agent to ask you first, as for removing a secret, choosing a paid plan, or a deploy
+  change that cannot be undone.
+- **Pay.** A paid project plan answers with a checkout link that you open and pay.
 
 ## 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)
+- [Shape a project](./shape.md) · [Go live](./go-live.md) · [Tools](./tools.md)
+- Without an agent: [CLI overview](../cli/overview.md)