@lukoweb/apitogo 0.2.60 → 0.2.64

package/docs/mcp/tools.md

@@ -1,57 +1,57 @@
----
-title: MCP tools
-description: Every tool of the APItoGo MCP server and the CLI command it runs.
-sidebar_icon: wrench
----
-
-Each tool runs one `apitogo` command with `--json` in the project folder and answers with its JSON.
-Every tool takes `directory`: the project folder, absolute or relative to where the server runs
-(default: that folder).
-
-## Make and shape a project
-
-| Tool             | Runs                       | What it does                                                            |
-| ---------------- | -------------------------- | ----------------------------------------------------------------------- |
-| `apitogo_create` | `apitogo create`           | A new project folder; `template` `full` or `blank`, optional `services` |
-| `apitogo_init`   | `apitogo init`             | Prepares an existing folder: `apitogo.config.json` and `apitogo/` only  |
-| `apitogo_add`    | `apitogo add <service>`    | Adds `portal`, `gateway`, `identity` or `plans`; settings in `options`  |
-| `apitogo_remove` | `apitogo remove <service>` | Takes a service out of the config; `deleteFiles` also deletes its files |
-| `apitogo_config` | `apitogo config`           | Portal name, OpenAPI, docs pages, plans, or a `patch` of the config     |
-
-`options` of `apitogo_add` and `apitogo_config` are the command's flags in camelCase, for example
-`{"planSku":"pro","planPrice":"19"}` for `--plan-sku pro --plan-price 19`. A flag the command does
-not have is refused before anything runs. `true` and `false` are `--flag` and `--no-flag`; a list
-repeats the flag.
-
-## Check, preview, deploy
-
-| Tool             | Runs             | What it does                                                 |
-| ---------------- | ---------------- | ------------------------------------------------------------ |
-| `apitogo_check`  | `apitogo check`  | Checks the config and its files; `offline`, `validateBuild`  |
-| `apitogo_plan`   | `apitogo plan`   | What a deploy would do for each service; changes nothing     |
-| `apitogo_deploy` | `apitogo deploy` | Deploys what changed; `only`, `force`, `confirmIrreversible` |
-| `apitogo_status` | `apitogo status` | Each service's state and addresses; `skipLive` is faster     |
-
-## Platform project
-
-| Tool                     | Runs                       | What it does                                                                                   |
-| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------- |
-| `apitogo_project_create` | `apitogo project create`   | Creates the project; `plan` free, starter or professional                                      |
-| `apitogo_project_use`    | `apitogo project use <id>` | Points the folder at another existing project                                                  |
-| `apitogo_secrets_list`   | `apitogo secrets list`     | The names of the project's secrets, never their values                                         |
-| `apitogo_secrets_remove` | `apitogo secrets rm`       | Removes a secret                                                                               |
-| `apitogo_teardown`       | `apitogo teardown`         | Deletes the project, or with `only` its gateway, identity or plans; needs `confirmProjectName` |
-
-## Not a tool, on purpose
-
-| Command               | Why                                                       |
-| --------------------- | --------------------------------------------------------- |
-| `apitogo login`       | Opens a browser to sign you in; run it once in a terminal |
-| `apitogo secrets set` | A secret's value must not pass through the agent          |
-| `apitogo run`         | The local preview keeps running; start it yourself        |
-
-## Safety hints
-
-Tools carry MCP hints so hosts can ask before running them: `apitogo_check`, `apitogo_plan`,
-`apitogo_status` and `apitogo_secrets_list` are read-only; `apitogo_remove`,
-`apitogo_secrets_remove` and `apitogo_teardown` are marked destructive.
+---
+title: MCP tools
+description: Every tool of the APItoGo MCP server and the CLI command it runs.
+sidebar_icon: wrench
+---
+
+Each tool runs one `apitogo` command with `--json` in the project folder and answers with its JSON.
+Every tool takes `directory`: the project folder, absolute or relative to where the server runs
+(default: that folder).
+
+## Make and shape a project
+
+| Tool             | Runs                       | What it does                                                            |
+| ---------------- | -------------------------- | ----------------------------------------------------------------------- |
+| `apitogo_create` | `apitogo create`           | A new project folder; `template` `full` or `blank`, optional `services` |
+| `apitogo_init`   | `apitogo init`             | Prepares an existing folder: `apitogo.config.json` and `apitogo/` only  |
+| `apitogo_add`    | `apitogo add <service>`    | Adds `portal`, `gateway`, `identity` or `plans`; settings in `options`  |
+| `apitogo_remove` | `apitogo remove <service>` | Takes a service out of the config; `deleteFiles` also deletes its files |
+| `apitogo_config` | `apitogo config`           | Portal name, OpenAPI, docs pages, plans, or a `patch` of the config     |
+
+`options` of `apitogo_add` and `apitogo_config` are the command's flags in camelCase, for example
+`{"planSku":"pro","planPrice":"19"}` for `--plan-sku pro --plan-price 19`. A flag the command does
+not have is refused before anything runs. `true` and `false` are `--flag` and `--no-flag`; a list
+repeats the flag.
+
+## Check, preview, deploy
+
+| Tool             | Runs             | What it does                                                 |
+| ---------------- | ---------------- | ------------------------------------------------------------ |
+| `apitogo_check`  | `apitogo check`  | Checks the config and its files; `offline`, `validateBuild`  |
+| `apitogo_plan`   | `apitogo plan`   | What a deploy would do for each service; changes nothing     |
+| `apitogo_deploy` | `apitogo deploy` | Deploys what changed; `only`, `force`, `confirmIrreversible` |
+| `apitogo_status` | `apitogo status` | Each service's state and addresses; `skipLive` is faster     |
+
+## Platform project
+
+| Tool                     | Runs                       | What it does                                                                                   |
+| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------- |
+| `apitogo_project_create` | `apitogo project create`   | Creates the project; `plan` free, starter or professional                                      |
+| `apitogo_project_use`    | `apitogo project use <id>` | Points the folder at another existing project                                                  |
+| `apitogo_secrets_list`   | `apitogo secrets list`     | The names of the project's secrets, never their values                                         |
+| `apitogo_secrets_remove` | `apitogo secrets rm`       | Removes a secret                                                                               |
+| `apitogo_teardown`       | `apitogo teardown`         | Deletes the project, or with `only` its gateway, identity or plans; needs `confirmProjectName` |
+
+## Not a tool, on purpose
+
+| Command               | Why                                                       |
+| --------------------- | --------------------------------------------------------- |
+| `apitogo login`       | Opens a browser to sign you in; run it once in a terminal |
+| `apitogo secrets set` | A secret's value must not pass through the agent          |
+| `apitogo run`         | The local preview keeps running; start it yourself        |
+
+## Safety hints
+
+Tools carry MCP hints so hosts can ask before running them: `apitogo_check`, `apitogo_plan`,
+`apitogo_status` and `apitogo_secrets_list` are read-only; `apitogo_remove`,
+`apitogo_secrets_remove` and `apitogo_teardown` are marked destructive.

package/docs/quickstart.md

@@ -13,6 +13,8 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 ## Prerequisites
 
 - **Node.js 20+**
+- **The `apitogo` CLI, installed globally:** `npm install -g @lukoweb/apitogo` (see
+  [Install the CLI](./cli/setup.md))
 - An account on [apitogo.com](https://apitogo.com) (needed to deploy, not to try it locally)
 
 ## Get started
@@ -22,7 +24,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 1. **Create the project**
 
    ```bash
-   npx @lukoweb/apitogo@latest create --template full
+   apitogo create --template full
    ```
 
    It asks for a name, makes a folder for it and writes everything a working product needs:
@@ -37,7 +39,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 
    ```bash
    cd <your project folder>
-   npx apitogo run
+   apitogo run
    ```
 
    Open `http://localhost:3000`. The console signs in with a demo account (`demo@apitogo.local` /
@@ -47,7 +49,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 1. **Sign in to APItoGo**
 
    ```bash
-   npx apitogo login
+   apitogo login
    ```
 
    A browser window opens; sign in there.
@@ -55,7 +57,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 1. **Deploy**
 
    ```bash
-   npx apitogo deploy
+   apitogo deploy
    ```
 
    The first deploy creates the project (it asks which hosting plan: Free, Starter or Professional),

package/docs/writing.mdx

@@ -1,68 +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 `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
+---
+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

package/package.json

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

package/src/config/apitogo-config-core.ts

@@ -558,8 +558,18 @@ function syncAuthentication(normalized: ApitogoJsonConfig): void {
     return;
   }
 
+  // `authentication.enabled: false` turns sign-in off: no provider at all, so the header shows no "Log in" and
+  // "Get started". Without this the block below gave it a dev-portal type, and the auth plugin loads a provider for
+  // any type. The user panel needs sign-in, so with the panel on it still wins.
+  if (!userPanelEnabled && authentication?.enabled === false) {
+    delete normalized.authentication;
+    return;
+  }
+
   const auth = authentication ?? {};
-  auth.enabled = userPanelEnabled;
+  // Only the panel sets `enabled`: writing `false` here would read as "turned off" when the config is normalized
+  // again, and drop an OpenID provider that a portal without the panel still signs in with. Readers check `=== true`.
+  if (userPanelEnabled) auth.enabled = true;
   // A portal that signs in with an OpenID provider (the project's identity, with no plans backend) keeps it: the
   // dev-portal defaults below (native sign-up, an empty provider list, the demo sign-in form) belong to the
   // dev-portal provider only.

package/src/config/v2/home-redirect.ts

@@ -117,7 +117,7 @@ export type HomeRedirectInput = {
  * "Page not found".
  *
  * - Hosted docs without an index page: the first page, so the team's own docs never need an extra file.
- * - Hosted docs without any page: the API reference, when there is one.
+ * - Hosted docs without any page: the API reference, when there is one, else the console pages as below (API-116).
  * - External docs and no console: the external docs site, as the portal has nothing else to show.
  * - No hosted docs but a console: the pricing page when there is one, else the account pages, which lead a signed-out
  *   visitor to sign in. The console has no page of its own at `/`, so the address `deploy` prints showed "Page not
@@ -131,11 +131,11 @@ export function homeRedirect(
       return undefined;
     const landing = pickLandingRoute(input.docRoutes, input.pageOrders);
     if (landing) return { from: "/", to: landing };
-    return input.apiReferencePath
-      ? { from: "/", to: input.apiReferencePath }
-      : undefined;
+    if (input.apiReferencePath)
+      return { from: "/", to: input.apiReferencePath };
+    // No pages and no reference yet: the console pages, when there are any, rather than "Page not found" (API-116).
   }
-  if (input.externalDocsUrl && !input.userPanel) {
+  if (!input.hostsDocs && input.externalDocsUrl && !input.userPanel) {
     return { from: "/", to: input.externalDocsUrl };
   }
   if (input.userPanel) {

package/src/config/v2/index.ts

@@ -54,7 +54,11 @@ export {
   ConfigV2Schema,
   type Layout,
 } from "./schema.js";
-export { type PortalProfile, portalProfile } from "./portal-profile.js";
+export {
+  type PortalProfile,
+  portalOnlyLinksExternalDocs,
+  portalProfile,
+} from "./portal-profile.js";
 export {
   hasCapability,
   type ManifestServiceName,

package/src/config/v2/portal-profile.ts

@@ -49,6 +49,23 @@ const NOT_BUILT: PortalProfile = {
   modules: { docs: false, userPanel: false },
 };
 
+/**
+ * The portal's docs are on an external site and no service (identity or plans) feeds its console, so the portal would be
+ * an empty site. `project create` takes no website hosting for it and `deploy` does not build or publish it (API-101: such
+ * a portal waited on hosting it never needed, and deploy exited 1).
+ */
+export function portalOnlyLinksExternalDocs(
+  resolved: Pick<ResolvedConfigV2, "portal" | "identity" | "plans">,
+): boolean {
+  const portal = resolved.portal;
+  if (!portal?.enabled) return false;
+  if (!portal.docs.enabled || portal.docs.provider !== "external") return false;
+  const consoleFed =
+    portal.console.enabled &&
+    (resolved.identity?.enabled === true || resolved.plans?.enabled === true);
+  return !consoleFed;
+}
+
 export function portalProfile(resolved: ResolvedConfigV2): PortalProfile {
   const portal = resolved.portal;
   if (!portal?.enabled) return NOT_BUILT;

package/src/config/v2/resolve.ts

@@ -19,6 +19,16 @@ function fromConfig(configDir: string, value: string): string {
     : toGlobPath(path.resolve(configDir, value));
 }
 
+/**
+ * A header link. `to` is where it goes. A page link also has `page`, the absolute path of its file (a React page or a
+ * Markdown page), which the portal serves at `/<file name>` (so `to` is that address) and keeps out of the docs sidebar.
+ */
+export type ResolvedHeaderLink = { label: string; to: string; page?: string };
+
+/** The address of a header page: its file name without the extension, `about.tsx` is `/about`. */
+export const headerPageRoute = (file: string): string =>
+  `/${path.basename(file).replace(/\.(mdx?|tsx)$/i, "")}`;
+
 export type ResolvedPortal = {
   enabled: boolean;
   dir: string;
@@ -36,6 +46,8 @@ export type ResolvedPortal = {
   landing?: string;
   /** Absolute path of the footer component, when the portal has one (API-129). */
   footer?: string;
+  /** Links of the header's top menu (`portal.header.links`), in their order. Empty when there are none. */
+  headerLinks: ResolvedHeaderLink[];
   /** The header logo, when the portal has one: absolute paths (inside the portal's `public/`) or https URLs (API-129). */
   logo?: { light: string; dark: string; alt?: string };
   requireAuth: boolean | { exclude: string[] };
@@ -159,6 +171,13 @@ export function resolveConfigV2(
       ...(portal.footer
         ? { footer: path.resolve(configDir, portal.footer) }
         : {}),
+      headerLinks: (portal.header?.links ?? []).map(
+        (link): ResolvedHeaderLink => {
+          if ("to" in link) return { label: link.label, to: link.to };
+          const page = path.resolve(configDir, link.page);
+          return { label: link.label, to: headerPageRoute(page), page };
+        },
+      ),
       ...(portal.logo
         ? {
             logo:

package/src/config/v2/rules.ts

@@ -4,6 +4,8 @@ import { glob } from "glob";
 import { parse as parseYaml } from "yaml";
 import { billingNeeded, stripeKeySecretName } from "./billing.js";
 import type { ConfigIssue } from "./errors.js";
+import { docRoutes } from "./home-redirect.js";
+import { portalOnlyLinksExternalDocs } from "./portal-profile.js";
 import { isLogoUrl, type ResolvedConfigV2, toGlobPath } from "./resolve.js";
 import type { ConfigV2 } from "./schema.js";
 import { findTsxPages } from "./tsx-pages.js";
@@ -247,6 +249,17 @@ async function portalRules(
     });
   }
 
+  // Docs on an external site and nothing for the console: the portal would be an empty site (API-101).
+  if (portalOnlyLinksExternalDocs(resolved)) {
+    out.warn({
+      code: "PORTAL_NOTHING_TO_HOST",
+      path: "portal",
+      message:
+        "docs are on an external site and no service feeds the console, so there is no portal to host: `project create` takes no website hosting for it and `deploy` skips it.",
+      hint: "Enable identity or plans for a console next to your docs, or remove the portal section.",
+    });
+  }
+
   // A missing footer or logo file would fail the build, so check says so first (API-129).
   if (portal.footer && !(await isFile(portal.footer)))
     out.error({
@@ -255,6 +268,7 @@ async function portalRules(
       message: `the file ${path.relative(resolved.configDir, portal.footer)} does not exist.`,
       hint: "Create it, or remove portal.footer.",
     });
+  await headerLinksRule(portal, resolved, out);
   const publicDir = path.join(portal.dir, "public");
   for (const file of new Set(
     [portal.logo?.light, portal.logo?.dark].filter(
@@ -315,6 +329,16 @@ async function docsContentRule(
   const shown = config.portal?.docs?.content ?? [
     path.relative(resolved.configDir, patterns[0] ?? ""),
   ];
+  // No pages and nothing else for `/` either: the deployed home page would say "Page not found" (API-116).
+  if (portalHasNothingToShow(resolved)) {
+    out.error({
+      code: "PORTAL_HOME_EMPTY",
+      path: "portal.docs",
+      message: `portal.docs matched 0 files (${shown.join(", ")}), and the portal has no API reference, console pages or home page of its own, so its home page would say "Page not found".`,
+      hint: "Add a .md or .mdx page there (for example introduction.mdx), point docs.content at your existing docs, or enable the gateway with an OpenAPI file for an API reference.",
+    });
+    return;
+  }
   out.warn({
     code: "PORTAL_DOCS_EMPTY",
     path: "portal.docs",
@@ -323,6 +347,106 @@ async function docsContentRule(
   });
 }
 
+/**
+ * A portal that hosts docs but has nothing else to show at `/`: no home page of its own, no gateway for an API reference,
+ * and no service (identity or plans) for console pages.
+ */
+function portalHasNothingToShow(resolved: ResolvedConfigV2): boolean {
+  const portal = resolved.portal;
+  if (!portal?.enabled || portal.landing) return false;
+  if (resolved.gateway?.enabled === true) return false;
+  const consoleFed =
+    portal.console.enabled &&
+    (resolved.identity?.enabled === true || resolved.plans?.enabled === true);
+  return !consoleFed;
+}
+
+/** Addresses the portal itself uses, so a header page cannot take them. */
+const RESERVED_HEADER_ROUTES = [
+  "/",
+  "/index",
+  "/api",
+  "/pricing",
+  "/account",
+  "/login",
+  "/signup",
+];
+
+/**
+ * Header pages (`portal.header.links[].page`) are React or Markdown files the portal serves at `/<file name>`, outside
+ * the sidebar. A wrong one would fail the build or quietly take another page's address, so check says so first.
+ */
+async function headerLinksRule(
+  portal: NonNullable<ResolvedConfigV2["portal"]>,
+  resolved: ResolvedConfigV2,
+  out: Collector,
+) {
+  const pages = portal.headerLinks
+    .map((link, index) => ({ link, index }))
+    .filter(({ link }) => link.page !== undefined);
+  if (pages.length === 0) return;
+  const hostsDocs = portal.docs.enabled && portal.docs.provider === "apitogo";
+  const docs = hostsDocs
+    ? [
+        ...(await docRoutes(portal.docs.content, { includeDrafts: true })),
+        ...(await findTsxPages(portal.docs.content)).map((page) => page.route),
+      ]
+    : [];
+  const seen = new Set<string>();
+  for (const { link, index } of pages) {
+    const file = link.page as string;
+    const at = `portal.header.links[${index}].page`;
+    const shown = path.relative(resolved.configDir, file);
+    if (!hostsDocs) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_NO_DOCS",
+        path: at,
+        message: `the header page ${shown} needs hosted docs, which this portal does not have.`,
+        hint: 'Header pages are served with the docs pages: set portal.docs.provider to "apitogo", or link an address with "to" instead.',
+      });
+      continue;
+    }
+    if (!/\.(mdx?|tsx)$/i.test(file)) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_INVALID",
+        path: at,
+        message: `the header page ${shown} is neither a React page nor a Markdown page.`,
+        hint: "Use a .tsx file (its default export is the page) or a .md / .mdx file.",
+      });
+      continue;
+    }
+    if (!(await isFile(file))) {
+      out.error({
+        code: "PORTAL_FILE_MISSING",
+        path: at,
+        message: `the file ${shown} does not exist.`,
+        hint: "Create it (`apitogo config --page-slug <name> --page-title <title> --page-header`), or remove the link.",
+      });
+      continue;
+    }
+    const route = link.to;
+    if (RESERVED_HEADER_ROUTES.includes(route.toLowerCase())) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_ROUTE_TAKEN",
+        path: at,
+        message: `the header page ${shown} would be served at ${route}, which the portal uses itself.`,
+        hint: "Rename the file: its name is the page's address.",
+      });
+      continue;
+    }
+    if (docs.includes(route) || seen.has(route)) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_ROUTE_TAKEN",
+        path: at,
+        message: `the header page ${shown} would be served at ${route}, which another page already has.`,
+        hint: 'Rename the file: its name is the page\'s address. A docs page that should be in the header too can be linked with "to" instead.',
+      });
+      continue;
+    }
+    seen.add(route);
+  }
+}
+
 // --- gateway (2.4) --------------------------------------------------------------------------------------------------
 
 function isIpLiteral(hostname: string): boolean {

package/src/config/v2/schema.ts

@@ -31,6 +31,32 @@ const pathList = z.array(nonEmpty);
 
 const enabled = z.boolean().optional();
 
+const headerLabel = z
+  .string()
+  .trim()
+  .min(1, { error: "must not be empty" })
+  .max(40, { error: "must be 40 characters or fewer" });
+
+/**
+ * A link in the portal header's top menu: a page of its own (a React `.tsx` or Markdown file, served at `/<file name>`
+ * and kept out of the docs sidebar) or an address (`/path` on the portal, or `https://` elsewhere).
+ */
+const HeaderLinkSchema = z.union(
+  [
+    z.strictObject({ label: headerLabel, page: path }),
+    z.strictObject({
+      label: headerLabel,
+      to: z.string().regex(/^(\/(?!\/)|https:\/\/)/, {
+        error: 'must start with "/" or "https://"',
+      }),
+    }),
+  ],
+  {
+    error:
+      'must be { "label": "...", "page": "path/to/page.tsx" } or { "label": "...", "to": "/path or https://..." }',
+  },
+);
+
 export const PortalSchema = z.strictObject({
   enabled,
   dir: path.optional(),
@@ -49,6 +75,8 @@ export const PortalSchema = z.strictObject({
   landing: path.optional(),
   /** The footer: a React component file shown under every page except the console's (API-129). */
   footer: path.optional(),
+  /** Links of the header's top menu, after the built-in ones (Documentation, API Reference; the plans add Pricing). */
+  header: z.strictObject({ links: z.array(HeaderLinkSchema) }).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.