@lukoweb/apitogo 0.2.26 → 0.2.29

package/dist/cli/cli.js

@@ -6617,6 +6617,12 @@ function resolveConfigV2(config2, configPath) {
       }
     };
   }
+  if (resolved.gateway && resolved.plans?.enabled && resolved.gateway.policies.access === void 0) {
+    resolved.gateway.policies = {
+      ...resolved.gateway.policies,
+      access: { jwt: false, apiKey: true }
+    };
+  }
   return resolved;
 }
 
@@ -7933,6 +7939,7 @@ function publishedManifest(manifest, plan2) {
   };
 }
 var DEFAULT_SCOPES = ["openid", "profile", "email"];
+var USER_PANEL_PLANS_PLACEHOLDER_PATH = "your-plan";
 function planPortal(profile, manifest) {
   const skipped = [];
   const skip = (piece, reason) => void skipped.push({ piece, reason });
@@ -8023,9 +8030,14 @@ function buildSiteConfig(resolved, plan2, theme, extras = {}) {
     modules: {
       docs: { enabled: plan2.docs },
       // The plans pages (pricing, choosing a plan) exist only when billing is on, and the plans service is what makes it so.
+      // Switching billing on also makes the user panel register its own placeholder plans page, at `/account/<path>`.
+      // Its default path is `plans`, which is where the billing plugin puts the real page (subscribe, switch, cancel),
+      // and the placeholder won: the "Change plan" link opened an empty page. So the placeholder gets its own path.
       userPanel: {
         enabled: plan2.userPanel,
-        ...plan2.plansPlugin ? { plans: { enabled: true } } : {}
+        ...plan2.plansPlugin ? {
+          plans: { enabled: true, path: USER_PANEL_PLANS_PLACEHOLDER_PATH }
+        } : {}
       }
     },
     ...plan2.docs ? {
@@ -9968,7 +9980,7 @@ import {
 // package.json
 var package_default = {
   name: "@lukoweb/apitogo",
-  version: "0.2.26",
+  version: "0.2.29",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -28944,6 +28956,26 @@ async function deployV2(options, deps) {
     }
     results.push(await deployPortal(options, deps, projectId));
   }
+  const gatewayAt = results.findIndex(
+    (result) => result.service === "gateway" && result.status !== "skipped"
+  );
+  const portalDeployed = results.some(
+    (result) => result.service === "portal" && result.url !== void 0
+  );
+  const gateway = results[gatewayAt];
+  if (gateway && portalDeployed) {
+    const again = await deployGatewayService(options, deps, projectId, false);
+    if (again.steps.some((step2) => !step2.skipped))
+      results[gatewayAt] = {
+        ...gateway,
+        status: "deployed",
+        url: again.url ?? gateway.url,
+        notes: [
+          ...gateway.notes ?? [],
+          "browser access updated for the portal address"
+        ]
+      };
+  }
   if (results.length === 0) {
     throw new DeployError(
       "NOTHING_TO_DEPLOY",

package/docs/cli/walkthrough.md

@@ -0,0 +1,133 @@
+---
+title: "Walkthrough: from an empty folder to a customer's first call"
+description:
+  Build a portal with sign-up, a protected API, and plans, deploy it, and follow one customer from
+  sign-up to an API key and a first call.
+sidebar_icon: route
+---
+
+This page follows one project from an empty folder to a customer calling the protected API with
+their own key. Every step is a command you run, or something your customer does in the portal.
+
+```text
+ you:       init ─► add identity ─► add gateway ─► add plans ─► project create ─► deploy
+ customer:  open the portal ─► create an account ─► confirm the email ─► sign in
+            ─► subscribe to the Free plan ─► create an API key ─► call the API with the key
+ you:       teardown (when it was a test)
+```
+
+## What you need
+
+- Node.js 20 or later
+- An APItoGo account, signed in for the CLI (see [Install the CLI](./setup.md))
+- An API that is reachable over HTTPS. This walkthrough uses `https://httpbin.org` as a stand-in.
+
+## 1. Create the project folder
+
+```bash
+npx @lukoweb/apitogo@latest init my-portal --yes --name my-portal
+cd my-portal
+```
+
+`init` creates a config version 2 project with a portal, and installs the CLI into it. The commands
+below use the installed CLI through `npx apitogo`.
+
+## 2. Add the services
+
+```bash
+npx apitogo add identity
+npx apitogo add gateway --origin proxy --url https://httpbin.org --auth identity --create-spec
+npx apitogo add plans --template free --billing none
+```
+
+| Service  | What it gives you                                                                               |
+| -------- | ----------------------------------------------------------------------------------------------- |
+| identity | Sign-up, sign-in, email confirmation and password reset for your customers                      |
+| gateway  | The address your customers call. It forwards to your API and applies the plan's limits          |
+| plans    | The plan catalog, subscriptions, API keys and usage. The Free template limits calls (see below) |
+
+`--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
+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
+not needed. To require both, set `gateway.policies.access` yourself. A value you set is never
+replaced.
+
+## 3. Create the platform project and deploy
+
+```bash
+npx apitogo project create
+npx apitogo deploy
+```
+
+`deploy` runs the services in a fixed order and prints what it did:
+
+```text
+identity: deployed (https://id.apitogo.com/<project>)
+gateway:  deployed (https://free-api.apitogo.com/p<project>/), 1 operation(s)
+  browser access updated for the portal address
+plans:    deployed (https://portal.<your-portal-address>)
+portal:   deployed to production (https://<your-portal-address>)
+```
+
+The portal's address is only known once the portal is published. The gateway only accepts browser
+calls from addresses it knows, so `deploy` sends the gateway its list again after the portal. One
+`deploy` is enough: you do not need to run it twice.
+
+Running `deploy` again changes only what changed. Use `npx apitogo status` to see each service and
+`npx apitogo plan` to see what the next deploy would do.
+
+## 4. The customer's side
+
+Open the portal address and follow the steps your customer follows:
+
+1. Choose **Log in**. The portal sends the customer to your project's sign-in page.
+2. Choose **Create an account**, enter an email address and a password, and confirm the email. The
+   link in the email works for 24 hours.
+3. Sign in. The customer lands back in your portal.
+4. Open **Plans** and subscribe to **Free**.
+5. Open **API keys**, create a key, and copy it.
+6. Call the API with the key in the `Ocp-Apim-Subscription-Key` header:
+
+   ```bash
+   curl -i -H "Ocp-Apim-Subscription-Key: <the key>" \
+     https://free-api.apitogo.com/p<project>/health
+   ```
+
+What the gateway answers:
+
+| Request                               | Answer                                               |
+| ------------------------------------- | ---------------------------------------------------- |
+| A valid key                           | The answer of your API                               |
+| No key, a wrong key, or a revoked key | `401`                                                |
+| More calls than the plan allows       | `429`. A quota answer carries a `Retry-After` header |
+
+The customer sees their calls on the **Usage** page. See
+[Your customers' account pages](../guides/customer-account.md).
+
+## 5. Remove a test project
+
+```bash
+npx apitogo teardown --yes
+```
+
+This deletes the platform project: the gateway, the identity and its users, the portal, its address
+and certificate, and the project's email domain. Your local files stay.
+
+## Things worth knowing
+
+- **One identity per project.** A customer who signs up on one project cannot sign in to another.
+- **Sign-up needs a real email address.** Confirmation and password-reset emails are sent to it. For
+  tests, an address with a suffix such as `you+test1@example.com` usually reaches your own mailbox.
+- **Secrets stay out of the config.** A value such as an origin key is written as `secret:NAME` and
+  set with `npx apitogo secrets`.
+
+## Related
+
+- [Install the CLI](./setup.md)
+- [CLI commands](./commands.md)
+- [Protect an API with the gateway](../configuration/gateway.md)
+- [Your customers' account pages](../guides/customer-account.md)

package/docs/guides/customer-account.md

@@ -0,0 +1,71 @@
+---
+title: Your customers' account pages
+description:
+  "What a customer sees in your portal once plans are on (plans, API keys and usage) and how each
+  page relates to the gateway."
+sidebar_icon: user-round
+---
+
+When a project has the plans service, the portal gets an account area for signed-in customers. It
+needs no code from you. This page describes what each part does, so you can support your customers
+and know what to check when something looks wrong.
+
+## The pages
+
+| Page         | What the customer does                                   |
+| ------------ | -------------------------------------------------------- |
+| **Plans**    | Compares the plans from your `plans.json` and subscribes |
+| **API keys** | Creates, lists and revokes keys                          |
+| **Usage**    | Sees the calls made with their keys                      |
+| **Settings** | Manages the account details                              |
+
+The pages appear when the plans service is part of the portal. A project with identity only has
+sign-in but no plans, keys or usage.
+
+## Plans
+
+The plans come from `plans.json`. A plan has a name, limits, and optionally a price. The customer
+subscribes to a plan and may hold more than one. Unsubscribing from a plan stops that plan's keys
+from working and keeps the customer's other plans.
+
+Free plans work without any payment. For paid plans see the `plans.billing` setting.
+
+## API keys
+
+A key is created on the API keys page. A customer who no longer has a key can create a new one and
+revoke the old one.
+
+- A key works for calls to your gateway address, in the `Ocp-Apim-Subscription-Key` header.
+- The limits of the plan the key belongs to apply to every call made with it.
+- A revoked key stops working at once, and the next call with it is answered with `401`.
+
+## Usage
+
+The usage page shows, for a period of 24 hours, 7, 30 or 90 days:
+
+- the number of requests
+- the average latency
+- the error rate
+- the requests by endpoint
+- the requests by status code
+
+A call is counted when it is made with a customer's key. A call without a key, or with a wrong key,
+is refused by the gateway and does not appear.
+
+Answers of `400` and above count as errors, whoever caused them. If your API answers `404` to a path
+the customer calls, those calls show as errors in the usage page.
+
+## When something looks wrong
+
+| What the customer sees                        | What to check                                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `401` with a key that should work             | The key was revoked, or the plan was cancelled. Check the key on the API keys page.               |
+| `401` on a project you set up by hand         | `gateway.policies.access`: when it also requires a login token, a key alone is refused.           |
+| `429`                                         | The plan's limit was reached. The rate limit renews each period; the quota carries `Retry-After`. |
+| The usage page shows nothing after real calls | Calls only count when made with a key. Check that the gateway has been deployed with plans.       |
+| Calls from the portal's own pages are blocked | Run `npx apitogo deploy` again. The gateway lists the portal's address after the portal exists.   |
+
+## Related
+
+- [Walkthrough: from an empty folder to a customer's first call](../cli/walkthrough.md)
+- [Protect an API with the gateway](../configuration/gateway.md)

package/package.json

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

package/src/config/v2/resolve.ts

@@ -1,188 +1,202 @@
-import path from "node:path";
-import { layoutRoot, type StatePaths, statePathsFor } from "./paths.js";
-import type { ConfigV2, Layout } from "./schema.js";
-
-export { layoutRoot };
-
-/** A path relative to the config file, made absolute. A leading `!` (negated glob) is preserved. */
-function fromConfig(configDir: string, value: string): string {
-  return value.startsWith("!")
-    ? `!${path.resolve(configDir, value.slice(1))}`
-    : path.resolve(configDir, value);
-}
-
-export type ResolvedPortal = {
-  enabled: boolean;
-  dir: string;
-  name: string;
-  docs: {
-    enabled: boolean;
-    provider: "apitogo" | "external";
-    /** Absolute globs. Empty for an external docs provider. */
-    content: string[];
-    url?: string;
-  };
-  console: { enabled: boolean };
-  theme: string;
-  requireAuth: boolean | { exclude: string[] };
-  search: "pagefind" | "inkeep" | "none";
-};
-
-export type ResolvedGateway = {
-  enabled: boolean;
-  provider: string;
-  origin: NonNullable<ConfigV2["gateway"]>["origin"];
-  /** Absolute paths. */
-  specs: string[];
-  auth?: NonNullable<ConfigV2["gateway"]>["auth"];
-  export?: NonNullable<ConfigV2["gateway"]>["export"];
-  policies: NonNullable<NonNullable<ConfigV2["gateway"]>["policies"]>;
-};
-
-export type ResolvedIdentity = {
-  enabled: boolean;
-  provider: "apitogo" | "oidc";
-  native: boolean;
-  connections: NonNullable<NonNullable<ConfigV2["identity"]>["connections"]>;
-  clients: NonNullable<NonNullable<ConfigV2["identity"]>["clients"]>;
-  issuer?: string;
-  clientId?: string;
-  providerOptions: NonNullable<
-    NonNullable<ConfigV2["identity"]>["providerOptions"]
-  >;
-};
-
-export type ResolvedPlans = {
-  enabled: boolean;
-  /** Absolute path of the plan catalog. */
-  file: string;
-  billing: {
-    provider: "stripe" | "none";
-    apiKey?: string;
-    webhookSecret?: string;
-    successUrl?: string;
-    cancelUrl?: string;
-  };
-};
-
-export type ResolvedConfigV2 = {
-  configPath: string;
-  configDir: string;
-  layout: Layout;
-  /** `<root>` of the layout: where `portal/`, `plans.json` and `apis/` live by default. */
-  root: string;
-  /** Default folder for OpenAPI files created by `init`. */
-  apisDir: string;
-  /** Generated and observed state (`state.json`, `generated/`, `build/`), ignored by git on its own. */
-  state: StatePaths;
-  project: { id?: string; name: string };
-  portal?: ResolvedPortal;
-  gateway?: ResolvedGateway;
-  identity?: ResolvedIdentity;
-  plans?: ResolvedPlans;
-};
-
-/**
- * Applies the documented defaults and makes every path absolute. Defaults for `portal.dir`, `plans.file`
- * and the spec folder derive from `<root>`, so a standalone config can omit them. A section that is present
- * without `enabled` is enabled.
- */
-export function resolveConfigV2(
-  config: ConfigV2,
-  configPath: string,
-): ResolvedConfigV2 {
-  const absoluteConfigPath = path.resolve(configPath);
-  const configDir = path.dirname(absoluteConfigPath);
-  const layout = config.layout ?? "standalone";
-  const root = layoutRoot(configDir, layout);
-  const projectName = config.project?.name ?? path.basename(configDir);
-
-  const resolved: ResolvedConfigV2 = {
-    configPath: absoluteConfigPath,
-    configDir,
-    layout,
-    root,
-    apisDir: path.join(root, "apis"),
-    state: statePathsFor(configDir, layout),
-    project: { id: config.project?.id, name: projectName },
-  };
-
-  const { portal, gateway, identity, plans } = config;
-
-  if (portal) {
-    const dir = portal.dir
-      ? path.resolve(configDir, portal.dir)
-      : path.join(root, "portal");
-    const provider = portal.docs?.provider ?? "apitogo";
-    resolved.portal = {
-      enabled: portal.enabled ?? true,
-      dir,
-      name: portal.name ?? projectName,
-      docs: {
-        enabled: portal.docs?.enabled ?? true,
-        provider,
-        content:
-          provider === "external"
-            ? []
-            : portal.docs?.content
-              ? portal.docs.content.map((glob) => fromConfig(configDir, glob))
-              : [path.join(dir, "pages", "**", "*.{md,mdx}")],
-        url: portal.docs?.url,
-      },
-      console: { enabled: portal.console?.enabled ?? true },
-      theme: portal.theme
-        ? path.resolve(configDir, portal.theme)
-        : path.join(dir, "theme.json"),
-      requireAuth: portal.requireAuth ?? false,
-      search: provider === "external" ? "none" : (portal.search ?? "pagefind"),
-    };
-  }
-
-  if (gateway) {
-    resolved.gateway = {
-      enabled: gateway.enabled ?? true,
-      provider: gateway.provider ?? "apitogo",
-      origin: {
-        ...gateway.origin,
-        source: gateway.origin.source
-          ? path.resolve(configDir, gateway.origin.source)
-          : undefined,
-      },
-      specs: gateway.specs.map((spec) => path.resolve(configDir, spec)),
-      auth: gateway.auth,
-      export: gateway.export,
-      policies: gateway.policies ?? {},
-    };
-  }
-
-  if (identity) {
-    resolved.identity = {
-      enabled: identity.enabled ?? true,
-      provider: identity.provider ?? "apitogo",
-      native: identity.native ?? true,
-      connections: identity.connections ?? [],
-      clients: identity.clients ?? [],
-      issuer: identity.issuer,
-      clientId: identity.clientId,
-      providerOptions: identity.providerOptions ?? {},
-    };
-  }
-
-  if (plans) {
-    resolved.plans = {
-      enabled: plans.enabled ?? true,
-      file: plans.file
-        ? path.resolve(configDir, plans.file)
-        : path.join(root, "plans.json"),
-      billing: {
-        provider: plans.billing?.provider ?? "stripe",
-        apiKey: plans.billing?.apiKey,
-        webhookSecret: plans.billing?.webhookSecret,
-        successUrl: plans.billing?.successUrl,
-        cancelUrl: plans.billing?.cancelUrl,
-      },
-    };
-  }
-
-  return resolved;
-}
+import path from "node:path";
+import { layoutRoot, type StatePaths, statePathsFor } from "./paths.js";
+import type { ConfigV2, Layout } from "./schema.js";
+
+export { layoutRoot };
+
+/** A path relative to the config file, made absolute. A leading `!` (negated glob) is preserved. */
+function fromConfig(configDir: string, value: string): string {
+  return value.startsWith("!")
+    ? `!${path.resolve(configDir, value.slice(1))}`
+    : path.resolve(configDir, value);
+}
+
+export type ResolvedPortal = {
+  enabled: boolean;
+  dir: string;
+  name: string;
+  docs: {
+    enabled: boolean;
+    provider: "apitogo" | "external";
+    /** Absolute globs. Empty for an external docs provider. */
+    content: string[];
+    url?: string;
+  };
+  console: { enabled: boolean };
+  theme: string;
+  requireAuth: boolean | { exclude: string[] };
+  search: "pagefind" | "inkeep" | "none";
+};
+
+export type ResolvedGateway = {
+  enabled: boolean;
+  provider: string;
+  origin: NonNullable<ConfigV2["gateway"]>["origin"];
+  /** Absolute paths. */
+  specs: string[];
+  auth?: NonNullable<ConfigV2["gateway"]>["auth"];
+  export?: NonNullable<ConfigV2["gateway"]>["export"];
+  policies: NonNullable<NonNullable<ConfigV2["gateway"]>["policies"]>;
+};
+
+export type ResolvedIdentity = {
+  enabled: boolean;
+  provider: "apitogo" | "oidc";
+  native: boolean;
+  connections: NonNullable<NonNullable<ConfigV2["identity"]>["connections"]>;
+  clients: NonNullable<NonNullable<ConfigV2["identity"]>["clients"]>;
+  issuer?: string;
+  clientId?: string;
+  providerOptions: NonNullable<
+    NonNullable<ConfigV2["identity"]>["providerOptions"]
+  >;
+};
+
+export type ResolvedPlans = {
+  enabled: boolean;
+  /** Absolute path of the plan catalog. */
+  file: string;
+  billing: {
+    provider: "stripe" | "none";
+    apiKey?: string;
+    webhookSecret?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+  };
+};
+
+export type ResolvedConfigV2 = {
+  configPath: string;
+  configDir: string;
+  layout: Layout;
+  /** `<root>` of the layout: where `portal/`, `plans.json` and `apis/` live by default. */
+  root: string;
+  /** Default folder for OpenAPI files created by `init`. */
+  apisDir: string;
+  /** Generated and observed state (`state.json`, `generated/`, `build/`), ignored by git on its own. */
+  state: StatePaths;
+  project: { id?: string; name: string };
+  portal?: ResolvedPortal;
+  gateway?: ResolvedGateway;
+  identity?: ResolvedIdentity;
+  plans?: ResolvedPlans;
+};
+
+/**
+ * Applies the documented defaults and makes every path absolute. Defaults for `portal.dir`, `plans.file`
+ * and the spec folder derive from `<root>`, so a standalone config can omit them. A section that is present
+ * without `enabled` is enabled.
+ */
+export function resolveConfigV2(
+  config: ConfigV2,
+  configPath: string,
+): ResolvedConfigV2 {
+  const absoluteConfigPath = path.resolve(configPath);
+  const configDir = path.dirname(absoluteConfigPath);
+  const layout = config.layout ?? "standalone";
+  const root = layoutRoot(configDir, layout);
+  const projectName = config.project?.name ?? path.basename(configDir);
+
+  const resolved: ResolvedConfigV2 = {
+    configPath: absoluteConfigPath,
+    configDir,
+    layout,
+    root,
+    apisDir: path.join(root, "apis"),
+    state: statePathsFor(configDir, layout),
+    project: { id: config.project?.id, name: projectName },
+  };
+
+  const { portal, gateway, identity, plans } = config;
+
+  if (portal) {
+    const dir = portal.dir
+      ? path.resolve(configDir, portal.dir)
+      : path.join(root, "portal");
+    const provider = portal.docs?.provider ?? "apitogo";
+    resolved.portal = {
+      enabled: portal.enabled ?? true,
+      dir,
+      name: portal.name ?? projectName,
+      docs: {
+        enabled: portal.docs?.enabled ?? true,
+        provider,
+        content:
+          provider === "external"
+            ? []
+            : portal.docs?.content
+              ? portal.docs.content.map((glob) => fromConfig(configDir, glob))
+              : [path.join(dir, "pages", "**", "*.{md,mdx}")],
+        url: portal.docs?.url,
+      },
+      console: { enabled: portal.console?.enabled ?? true },
+      theme: portal.theme
+        ? path.resolve(configDir, portal.theme)
+        : path.join(dir, "theme.json"),
+      requireAuth: portal.requireAuth ?? false,
+      search: provider === "external" ? "none" : (portal.search ?? "pagefind"),
+    };
+  }
+
+  if (gateway) {
+    resolved.gateway = {
+      enabled: gateway.enabled ?? true,
+      provider: gateway.provider ?? "apitogo",
+      origin: {
+        ...gateway.origin,
+        source: gateway.origin.source
+          ? path.resolve(configDir, gateway.origin.source)
+          : undefined,
+      },
+      specs: gateway.specs.map((spec) => path.resolve(configDir, spec)),
+      auth: gateway.auth,
+      export: gateway.export,
+      policies: gateway.policies ?? {},
+    };
+  }
+
+  if (identity) {
+    resolved.identity = {
+      enabled: identity.enabled ?? true,
+      provider: identity.provider ?? "apitogo",
+      native: identity.native ?? true,
+      connections: identity.connections ?? [],
+      clients: identity.clients ?? [],
+      issuer: identity.issuer,
+      clientId: identity.clientId,
+      providerOptions: identity.providerOptions ?? {},
+    };
+  }
+
+  if (plans) {
+    resolved.plans = {
+      enabled: plans.enabled ?? true,
+      file: plans.file
+        ? path.resolve(configDir, plans.file)
+        : path.join(root, "plans.json"),
+      billing: {
+        provider: plans.billing?.provider ?? "stripe",
+        apiKey: plans.billing?.apiKey,
+        webhookSecret: plans.billing?.webhookSecret,
+        successUrl: plans.billing?.successUrl,
+        cancelUrl: plans.billing?.cancelUrl,
+      },
+    };
+  }
+
+  // With plans, a customer calls the gateway with the API key its plan gave it, not with a login token. Without this
+  // default the gateway also demanded a token (the identity's `jwt` rule) and a key alone got 401. A config that sets
+  // `gateway.policies.access` itself is never changed.
+  if (
+    resolved.gateway &&
+    resolved.plans?.enabled &&
+    resolved.gateway.policies.access === undefined
+  ) {
+    resolved.gateway.policies = {
+      ...resolved.gateway.policies,
+      access: { jwt: false, apiKey: true },
+    };
+  }
+
+  return resolved;
+}

package/src/config/v2/wrapper.ts

@@ -142,6 +142,9 @@ export function publishedManifest(
 
 const DEFAULT_SCOPES = ["openid", "profile", "email"];
 
+/** Where the user panel's placeholder plans page lives, so that `/account/plans` stays with the billing plugin. */
+const USER_PANEL_PLANS_PLACEHOLDER_PATH = "your-plan";
+
 /**
  * Pure: decides which plugins and modules the portal registers. A service contributes only when it has a manifest
  * entry, is ready and declares the capability that the piece needs.
@@ -273,9 +276,16 @@ export function buildSiteConfig(
     modules: {
       docs: { enabled: plan.docs },
       // The plans pages (pricing, choosing a plan) exist only when billing is on, and the plans service is what makes it so.
+      // Switching billing on also makes the user panel register its own placeholder plans page, at `/account/<path>`.
+      // Its default path is `plans`, which is where the billing plugin puts the real page (subscribe, switch, cancel),
+      // and the placeholder won: the "Change plan" link opened an empty page. So the placeholder gets its own path.
       userPanel: {
         enabled: plan.userPanel,
-        ...(plan.plansPlugin ? { plans: { enabled: true } } : {}),
+        ...(plan.plansPlugin
+          ? {
+              plans: { enabled: true, path: USER_PANEL_PLANS_PLACEHOLDER_PATH },
+            }
+          : {}),
       },
     },
     ...(plan.docs