@lukoweb/apitogo 0.2.61 → 0.2.64

package/dist/cli/cli.js

@@ -6794,9 +6794,10 @@ function homeRedirect(input5) {
       return void 0;
     const landing = pickLandingRoute(input5.docRoutes, input5.pageOrders);
     if (landing) return { from: "/", to: landing };
-    return input5.apiReferencePath ? { from: "/", to: input5.apiReferencePath } : void 0;
+    if (input5.apiReferencePath)
+      return { from: "/", to: input5.apiReferencePath };
   }
-  if (input5.externalDocsUrl && !input5.userPanel) {
+  if (!input5.hostsDocs && input5.externalDocsUrl && !input5.userPanel) {
     return { from: "/", to: input5.externalDocsUrl };
   }
   if (input5.userPanel) {
@@ -6805,6 +6806,54 @@ function homeRedirect(input5) {
   return void 0;
 }
 
+// src/config/v2/portal-profile.ts
+var NOT_BUILT = {
+  enabled: false,
+  docs: { enabled: false, provider: "apitogo", content: [] },
+  console: { enabled: false },
+  pipelines: { markdown: false, openapi: false, search: "none" },
+  modules: { docs: false, userPanel: false }
+};
+function portalOnlyLinksExternalDocs(resolved) {
+  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;
+}
+function portalProfile(resolved) {
+  const portal = resolved.portal;
+  if (!portal?.enabled) return NOT_BUILT;
+  const hostsDocs = portal.docs.enabled && portal.docs.provider === "apitogo";
+  const externalDocs = portal.docs.enabled && portal.docs.provider === "external";
+  const gatewayOn2 = resolved.gateway?.enabled === true;
+  return {
+    enabled: true,
+    docs: {
+      enabled: portal.docs.enabled,
+      provider: portal.docs.provider,
+      content: hostsDocs ? portal.docs.content : [],
+      url: externalDocs ? portal.docs.url : void 0
+    },
+    console: { enabled: portal.console.enabled },
+    pipelines: {
+      markdown: hostsDocs,
+      openapi: hostsDocs && gatewayOn2,
+      search: hostsDocs ? portal.search : "none"
+    },
+    modules: { docs: hostsDocs, userPanel: portal.console.enabled },
+    ...externalDocs ? {
+      externalDocs: {
+        url: portal.docs.url,
+        openapiExport: gatewayOn2,
+        cors: portal.console.enabled,
+        consoleLinksInManifest: portal.console.enabled,
+        whiteLabelConsole: portal.console.enabled
+      }
+    } : {}
+  };
+}
+
 // src/config/v2/tsx-pages.ts
 import { readFile as readFile4 } from "node:fs/promises";
 import path10 from "node:path";
@@ -6972,11 +7021,11 @@ function collectSecretRefs(config2) {
   return found;
 }
 function dependencyRules(config2, resolved, out) {
-  const gatewayOn = resolved.gateway?.enabled === true;
+  const gatewayOn2 = resolved.gateway?.enabled === true;
   const identityOn = resolved.identity?.enabled === true;
-  const oidcGateway = gatewayOn && resolved.gateway?.auth?.mode === "oidc";
+  const oidcGateway = gatewayOn2 && resolved.gateway?.auth?.mode === "oidc";
   const hasIdentitySource = identityOn || oidcGateway;
-  if (identityOn && resolved.portal?.enabled !== true && !gatewayOn && !resolved.project.id) {
+  if (identityOn && resolved.portal?.enabled !== true && !gatewayOn2 && !resolved.project.id) {
     out.error({
       code: "NOTHING_TO_HOST",
       path: "identity",
@@ -6993,7 +7042,7 @@ function dependencyRules(config2, resolved, out) {
     });
   }
   if (resolved.plans?.enabled) {
-    if (!gatewayOn) {
+    if (!gatewayOn2) {
       out.error({
         code: "PLANS_GATEWAY_REQUIRED",
         path: "plans",
@@ -7089,6 +7138,14 @@ async function portalRules(config2, resolved, out) {
       hint: "Enable identity or plans, or enable portal.docs."
     });
   }
+  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."
+    });
+  }
   if (portal.footer && !await isFile(portal.footer))
     out.error({
       code: "PORTAL_FILE_MISSING",
@@ -7142,6 +7199,15 @@ async function docsContentRule(config2, patterns, resolved, out) {
   const shown = config2.portal?.docs?.content ?? [
     path11.relative(resolved.configDir, patterns[0] ?? "")
   ];
+  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",
@@ -7149,6 +7215,13 @@ async function docsContentRule(config2, patterns, resolved, out) {
     hint: "Add .md, .mdx or .tsx pages, or point docs.content at your existing docs."
   });
 }
+function portalHasNothingToShow(resolved) {
+  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;
+}
 var RESERVED_HEADER_ROUTES = [
   "/",
   "/index",
@@ -7618,47 +7691,6 @@ async function checkConfigV2(config2, resolved, context = {}) {
   return { errors, warnings, skipped };
 }
 
-// src/config/v2/portal-profile.ts
-var NOT_BUILT = {
-  enabled: false,
-  docs: { enabled: false, provider: "apitogo", content: [] },
-  console: { enabled: false },
-  pipelines: { markdown: false, openapi: false, search: "none" },
-  modules: { docs: false, userPanel: false }
-};
-function portalProfile(resolved) {
-  const portal = resolved.portal;
-  if (!portal?.enabled) return NOT_BUILT;
-  const hostsDocs = portal.docs.enabled && portal.docs.provider === "apitogo";
-  const externalDocs = portal.docs.enabled && portal.docs.provider === "external";
-  const gatewayOn = resolved.gateway?.enabled === true;
-  return {
-    enabled: true,
-    docs: {
-      enabled: portal.docs.enabled,
-      provider: portal.docs.provider,
-      content: hostsDocs ? portal.docs.content : [],
-      url: externalDocs ? portal.docs.url : void 0
-    },
-    console: { enabled: portal.console.enabled },
-    pipelines: {
-      markdown: hostsDocs,
-      openapi: hostsDocs && gatewayOn,
-      search: hostsDocs ? portal.search : "none"
-    },
-    modules: { docs: hostsDocs, userPanel: portal.console.enabled },
-    ...externalDocs ? {
-      externalDocs: {
-        url: portal.docs.url,
-        openapiExport: gatewayOn,
-        cors: portal.console.enabled,
-        consoleLinksInManifest: portal.console.enabled,
-        whiteLabelConsole: portal.console.enabled
-      }
-    } : {}
-  };
-}
-
 // src/config/v2/manifest.ts
 import { mkdir as mkdir3, readFile as readFile6, rename, rm, writeFile as writeFile4 } from "node:fs/promises";
 import path12 from "node:path";
@@ -7777,10 +7809,10 @@ function requiredServices(resolved) {
   if (!portal?.enabled) return [];
   const needs = [];
   const consoleOn = portal.console.enabled;
-  const gatewayOn = resolved.gateway?.enabled === true;
+  const gatewayOn2 = resolved.gateway?.enabled === true;
   const identityOn = resolved.identity?.enabled === true;
   if (identityOn && (consoleOn || portal.requireAuth)) needs.push("identity");
-  if (gatewayOn && (consoleOn || portal.docs.enabled)) needs.push("gateway");
+  if (gatewayOn2 && (consoleOn || portal.docs.enabled)) needs.push("gateway");
   if (resolved.plans?.enabled === true && consoleOn) needs.push("plans");
   return needs;
 }
@@ -10261,6 +10293,17 @@ var PlatformApiError = class extends Error {
     this.problem = problem;
   }
 };
+var ProjectGoneError = class extends PlatformApiError {
+  constructor(projectId) {
+    super(
+      `The project ${projectId} no longer exists on the platform: it was deleted, or it is not in the account you are signed in to. Run \`apitogo project create\` to make a new project for this folder, or link another one with \`--project-id <id>\`.`,
+      410
+    );
+    this.projectId = projectId;
+    this.name = "ProjectGoneError";
+  }
+  code = "PROJECT_GONE";
+};
 function formatProblemDetails(problem) {
   const parts = [];
   if (problem.title) parts.push(problem.title);
@@ -10352,6 +10395,11 @@ async function fetchWithRetry(input5, init3, options) {
 }
 
 // src/cli/platform/client/platform-api.ts
+function projectIdOfPath(path100) {
+  return /^\/api\/v1\/projects\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:[/?#]|$)/i.exec(
+    path100
+  )?.[1];
+}
 var MAX_RETRIES = 3;
 var UPLOAD_TIMEOUT_MS = 10 * 60 * 1e3;
 var PlatformApiClient = class {
@@ -10387,13 +10435,39 @@ var PlatformApiClient = class {
       }
     );
     if (!response.ok) {
-      throw await parseErrorResponse(response);
+      throw await this.failure(response, path100);
     }
     if (response.status === 204) {
       return void 0;
     }
     return await response.json();
   }
+  /**
+   * The error for a failed answer. A 404 under a project may mean the project itself is gone; a bare "Not Found" hid
+   * that (API-133), so the project is asked once and a missing one becomes {@link ProjectGoneError}.
+   */
+  async failure(response, path100) {
+    const error = await parseErrorResponse(response);
+    const projectId = response.status === 404 ? projectIdOfPath(path100) : void 0;
+    if (projectId && await this.projectMissing(projectId, path100))
+      return new ProjectGoneError(projectId);
+    return error;
+  }
+  /** Whether the project answers 404 itself. A path that is the project needs no second call. */
+  async projectMissing(projectId, path100) {
+    const projectPath = `/api/v1/projects/${projectId}`;
+    if (path100.replace(/[?#].*$/, "").replace(/\/+$/, "") === projectPath)
+      return true;
+    try {
+      const response = await fetch(this.url(projectPath), {
+        method: "GET",
+        headers: this.headers()
+      });
+      return response.status === 404;
+    } catch {
+      return false;
+    }
+  }
   whoami() {
     return this.request("GET", "/api/v1/auth/me");
   }
@@ -10501,7 +10575,10 @@ var PlatformApiClient = class {
         { method: "POST", maxRetries: 0, retryMutatingOnServerError: false }
       );
       if (!response.ok) {
-        throw await parseErrorResponse(response);
+        throw await this.failure(
+          response,
+          `/api/v1/projects/${projectId}/infrastructure/static-web/deployments`
+        );
       }
       return await response.json();
     } catch (error) {
@@ -10577,7 +10654,10 @@ var PlatformApiClient = class {
       }
     );
     if (!response.ok) {
-      throw await parseErrorResponse(response);
+      throw await this.failure(
+        response,
+        `/api/v1/projects/${projectId}/backend/openapi`
+      );
     }
     return await response.json();
   }
@@ -10626,7 +10706,11 @@ var PlatformApiClient = class {
         maxRetries: MAX_RETRIES
       }
     );
-    if (!response.ok) throw await parseErrorResponse(response);
+    if (!response.ok)
+      throw await this.failure(
+        response,
+        `/api/v1/projects/${projectId}/gateway/openapi.json`
+      );
     return response.text();
   }
   getGatewayCapabilities(projectId) {
@@ -10938,7 +11022,10 @@ var PlatformApiClient = class {
       }
     );
     if (!response.ok) {
-      throw await parseErrorResponse(response);
+      throw await this.failure(
+        response,
+        `/api/v1/projects/${projectId}/backend/deployments`
+      );
     }
     return await response.json();
   }
@@ -11343,7 +11430,7 @@ import {
 // package.json
 var package_default = {
   name: "@lukoweb/apitogo",
-  version: "0.2.61",
+  version: "0.2.64",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -26955,11 +27042,22 @@ function assertConfigChecksOut(output4) {
     ].join("\n")
   );
 }
-var hostsAnything = (config2) => config2.portal && config2.portal.enabled !== false || config2.gateway && config2.gateway.enabled !== false;
+var gatewayOn = (config2) => config2.gateway !== void 0 && config2.gateway.enabled !== false;
+var hostsAnything = (config2) => config2.portal && config2.portal.enabled !== false || gatewayOn(config2);
 async function createProjectV2(options, deps) {
   const { config: config2, resolved } = loadConfigV2(options.dir);
   const linkedProjectId = resolved.project.id;
-  const modules = modulesForConfig(config2);
+  const externalDocsOnly = portalOnlyLinksExternalDocs(resolved);
+  const modules = modulesForConfig(config2).filter(
+    (module) => module !== "dev-portal" || !externalDocsOnly
+  );
+  if (externalDocsOnly && !gatewayOn(config2)) {
+    throw new ProjectCreateError(
+      "NOTHING_TO_HOST",
+      "No enabled service needs a project: the docs are on an external site and nothing feeds the portal console.",
+      "Enable identity or plans for a console next to your docs (`apitogo add identity`), or a gateway (`apitogo add gateway`)."
+    );
+  }
   if (!hostsAnything(config2)) {
     throw new ProjectCreateError(
       "NOTHING_TO_HOST",
@@ -28472,6 +28570,16 @@ var IdentityDeployError = class extends ApitogoError {
     this.name = "IdentityDeployError";
   }
 };
+var IDENTITY_NOT_ACTIVE = "IDENTITY_NOT_ACTIVE";
+async function identityLost(client, projectId) {
+  if (!client.listProjectIdentityConnections) return false;
+  try {
+    await client.listProjectIdentityConnections(projectId);
+    return false;
+  } catch (error) {
+    return error instanceof PlatformApiError && error.status === 409 && error.problem?.code === IDENTITY_NOT_ACTIVE;
+  }
+}
 var IDENTITY_STEPS = ["request", "activate"];
 var IDENTITY_CONNECTIONS_STEP = "connections";
 var SECRET_PREFIX = "secret:";
@@ -28671,10 +28779,13 @@ async function deployIdentity(resolved, projectId, deps, options = {}) {
         return rejected2(error);
       }
     },
-    // An identity that was removed, or that failed, is not a result worth keeping.
+    // An identity that was removed, or that failed, is not a result worth keeping. Neither is one the platform still
+    // lists as Active while the identity service lost it (API-132): asking again makes it again.
     stillValid: async () => {
       const found = await client.getProjectIdentity(projectId);
-      return found !== null && found.status !== "Failed" && found.status !== "Released" && found.status !== "Releasing";
+      if (found === null || found.status === "Failed" || found.status === "Released" || found.status === "Releasing")
+        return false;
+      return found.status !== "Active" || !await identityLost(client, projectId);
     }
   };
   const activateStep = {
@@ -29604,6 +29715,25 @@ async function statusV2(dir, only, options = {}) {
   const ledger = await readLedger(resolved.state);
   const manifest = await readManifest(resolved.state);
   const services = [];
+  const manifestSummary = {
+    present: manifest !== void 0,
+    schemaVersion: manifest?.schemaVersion,
+    generatedAt: manifest?.generatedAt
+  };
+  const projectId = resolved.project.id ?? manifest?.project.id;
+  if (options.projectRemote && projectId) {
+    try {
+      await options.projectRemote(projectId);
+    } catch (error) {
+      if (error instanceof ProjectGoneError)
+        return {
+          configPath: resolved.configPath,
+          manifest: manifestSummary,
+          project: { state: "gone", id: projectId, message: error.message },
+          services: []
+        };
+    }
+  }
   for (const service of chooseServices(only)) {
     const section = sectionOf(resolved, service);
     if (!section) {
@@ -29667,11 +29797,7 @@ async function statusV2(dir, only, options = {}) {
   }
   return {
     configPath: resolved.configPath,
-    manifest: {
-      present: manifest !== void 0,
-      schemaVersion: manifest?.schemaVersion,
-      generatedAt: manifest?.generatedAt
-    },
+    manifest: manifestSummary,
     services
   };
 }
@@ -29685,6 +29811,8 @@ function formatPlan(output4, options = {}) {
   ]);
 }
 function formatStatus(output4) {
+  if (output4.project?.state === "gone")
+    return [`project: gone`, `  ${output4.project.message}`];
   return [
     output4.manifest.present ? `services.json: version ${output4.manifest.schemaVersion}${output4.manifest.generatedAt ? `, written ${output4.manifest.generatedAt}` : ""}` : "services.json: none yet",
     ...output4.services.flatMap((svc) => [
@@ -29837,6 +29965,15 @@ async function deployV2(options, deps) {
       results.push(await deployPlansService(options, deps, projectId, named));
       continue;
     }
+    if (portalOnlyLinksExternalDocs(resolved)) {
+      results.push({
+        service: "portal",
+        status: "skipped",
+        reason: "docs are on an external site and no service feeds the console, so there is nothing to host",
+        steps: []
+      });
+      continue;
+    }
     results.push(await deployPortal(options, deps, projectId));
   }
   const gatewayAt = results.findIndex(
@@ -30609,6 +30746,14 @@ var plan = (argv) => run2(
   }),
   (output4) => formatPlan(output4, { verbose: argv.verbose === true })
 );
+function projectRemote() {
+  try {
+    const client = new PlatformApiClient(loadConfig());
+    return (projectId) => client.getProject(projectId);
+  } catch {
+    return void 0;
+  }
+}
 function gatewayRemote() {
   try {
     const client = new PlatformApiClient(loadConfig());
@@ -30666,6 +30811,7 @@ var statusOfProject = (argv) => run2(
   "status",
   argv,
   (dir, only) => statusV2(dir, only, {
+    projectRemote: projectRemote(),
     hostingRemote: hostingRemote(),
     gatewayRemote: gatewayRemote(),
     identityRemote: identityRemote(),
@@ -30787,7 +30933,7 @@ async function switchProject(options, deps) {
   try {
     project = await deps.getProject(projectId);
   } catch (error) {
-    if (error instanceof PlatformApiError && (error.status === 404 || error.status === 403))
+    if (error instanceof ProjectGoneError || error instanceof PlatformApiError && (error.status === 404 || error.status === 403))
       throw new ProjectUseError(
         "PROJECT_NOT_FOUND",
         `No project ${projectId} is yours.`,

package/dist/declarations/cli/platform/client/platform-api.d.ts

@@ -1,4 +1,5 @@
 import type { ApitogoConfig } from "../config.js";
+export declare function projectIdOfPath(path: string): string | undefined;
 export interface TenantDto {
     id: string;
     email: string;
@@ -545,6 +546,8 @@ export declare class PlatformApiClient {
     private url;
     private headers;
     private request;
+    private failure;
+    private projectMissing;
     whoami(): Promise<TenantDto>;
     listProjects(): Promise<ProjectDto[]>;
     getProject(projectId: string): Promise<ProjectDto>;

package/dist/declarations/cli/platform/errors.d.ts

@@ -11,6 +11,11 @@ export declare class PlatformApiError extends Error {
     readonly problem?: ProblemDetails;
     constructor(message: string, status: number, problem?: ProblemDetails);
 }
+export declare class ProjectGoneError extends PlatformApiError {
+    readonly projectId: string;
+    readonly code = "PROJECT_GONE";
+    constructor(projectId: string);
+}
 export declare function formatProblemDetails(problem: ProblemDetails): string;
 export declare function parseErrorResponse(response: Response): Promise<PlatformApiError>;
 export declare function toolErrorPayload(error: unknown): string;

package/docs/mcp/setup.md

@@ -22,9 +22,12 @@ Every host launches the same stdio process:
 | Field   | Value                                                |
 | ------- | ---------------------------------------------------- |
 | Command | `npx`                                                |
-| Args    | `-y`, `@lukoweb/apitogo-mcp`                         |
+| Args    | `-y`, `@lukoweb/apitogo-mcp@latest`                  |
 | Env     | Optional: `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET` |
 
+Keep `@latest` in the package name: without it npx can start an older copy it has kept from an
+earlier run, with tools that no longer match this guide.
+
 The tools run the `apitogo` CLI the project installed (`node_modules/@lukoweb/apitogo`), or the
 latest one through npx in a folder without it. Optional env: `APITOGO_API_KEY_ID` and
 `APITOGO_API_SECRET` instead of `apitogo login`, `APITOGO_API_URL`, and `APITOGO_CLI_PATH` (a local
@@ -44,7 +47,7 @@ Add to `~/.cursor/mcp.json` (user) or `.cursor/mcp.json` (project):
   "mcpServers": {
     "apitogo": {
       "command": "npx",
-      "args": ["-y", "@lukoweb/apitogo-mcp"],
+      "args": ["-y", "@lukoweb/apitogo-mcp@latest"],
       "env": {
         "APITOGO_API_KEY_ID": "apk_...",
         "APITOGO_API_SECRET": "..."
@@ -70,7 +73,7 @@ Edit the Claude Desktop MCP config (same `mcpServers` shape as Cursor):
   "mcpServers": {
     "apitogo": {
       "command": "npx",
-      "args": ["-y", "@lukoweb/apitogo-mcp"],
+      "args": ["-y", "@lukoweb/apitogo-mcp@latest"],
       "env": {
         "APITOGO_API_KEY_ID": "apk_...",
         "APITOGO_API_SECRET": "..."
@@ -88,7 +91,7 @@ Fully quit and reopen Claude Desktop after saving.
 
 ```bash
 claude mcp add --scope user --env APITOGO_API_KEY_ID=apk_... --env APITOGO_API_SECRET=... \
-  apitogo -- npx -y @lukoweb/apitogo-mcp
+  apitogo -- npx -y @lukoweb/apitogo-mcp@latest
 ```
 
 **Project scope** (committed `.mcp.json` — use `${VAR}` for secrets):
@@ -96,7 +99,7 @@ claude mcp add --scope user --env APITOGO_API_KEY_ID=apk_... --env APITOGO_API_S
 ```bash
 claude mcp add --scope project --env APITOGO_API_KEY_ID=${APITOGO_API_KEY_ID} \
   --env APITOGO_API_SECRET=${APITOGO_API_SECRET} \
-  apitogo -- npx -y @lukoweb/apitogo-mcp
+  apitogo -- npx -y @lukoweb/apitogo-mcp@latest
 ```
 
 Or hand-edit `.mcp.json` in the project root:
@@ -107,7 +110,7 @@ Or hand-edit `.mcp.json` in the project root:
     "apitogo": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@lukoweb/apitogo-mcp"],
+      "args": ["-y", "@lukoweb/apitogo-mcp@latest"],
       "env": {
         "APITOGO_API_KEY_ID": "${APITOGO_API_KEY_ID}",
         "APITOGO_API_SECRET": "${APITOGO_API_SECRET}"
@@ -128,7 +131,7 @@ Edit `~/.codex/config.toml` (or project `.codex/config.toml` in a trusted projec
 ```toml
 [mcp_servers.apitogo]
 command = "npx"
-args = ["-y", "@lukoweb/apitogo-mcp"]
+args = ["-y", "@lukoweb/apitogo-mcp@latest"]
 
 [mcp_servers.apitogo.env]
 APITOGO_API_KEY_ID = "apk_..."
@@ -142,7 +145,7 @@ Restart Codex / open a new session. See [Codex MCP docs](https://developers.open
 
 Any client that supports **stdio** MCP can run APItoGo:
 
-1. Set command `npx`, args `["-y", "@lukoweb/apitogo-mcp"]`
+1. Set command `npx`, args `["-y", "@lukoweb/apitogo-mcp@latest"]`
 2. Sign in with `apitogo login`, or pass `APITOGO_API_KEY_ID` and `APITOGO_API_SECRET` in the server
    env
 3. Restart the host and confirm tools load
@@ -158,9 +161,11 @@ In a new agent chat:
    `apitogo_create`, `apitogo_deploy` and `apitogo_status`.
 2. Ask it for the status of your project; it calls `apitogo_status`.
 
-If the server fails to start: confirm Node 20+ and that `npx -y @lukoweb/apitogo-mcp` works in a
-terminal. If a tool says you are not logged in, run `apitogo login` or check the API key id and
-secret.
+If the server fails to start: confirm Node 20+ and that `npx -y @lukoweb/apitogo-mcp@latest` works
+in a terminal. If the agent shows many more tools than the ones in [Tools](./tools.md), or asks for
+an API key although you are logged in, the host is running an old copy: add `@latest` as above and
+restart the host. If a tool says you are not logged in, run `apitogo login` or check the API key id
+and secret.
 
 ## Next
 

package/package.json

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

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/rules.ts

@@ -5,6 +5,7 @@ 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";
@@ -248,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({
@@ -317,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",
@@ -325,6 +347,20 @@ 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 = [
   "/",