zudoku 0.74.3 → 0.75.1

package/dist/cli/cli.js

@@ -3813,7 +3813,7 @@ import {
 // package.json
 var package_default = {
   name: "zudoku",
-  version: "0.74.2",
+  version: "0.75.0",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -3891,6 +3891,7 @@ var package_default = {
   },
   dependencies: {
     "@apidevtools/json-schema-ref-parser": "15.3.1",
+    "@base-ui/react": "^1.4.0",
     "@envelop/core": "5.5.1",
     "@graphql-typed-document-node/core": "3.2.0",
     "@hono/node-server": "1.19.13",
@@ -3951,14 +3952,14 @@ var package_default = {
     "fast-equals": "6.0.0",
     glob: "13.0.6",
     "glob-parent": "6.0.2",
-    graphql: "16.13.1",
+    graphql: "16.13.2",
     "graphql-type-json": "0.3.2",
     "graphql-yoga": "5.18.0",
     "gray-matter": "4.0.3",
     "hast-util-heading-rank": "3.0.0",
     "hast-util-to-jsx-runtime": "2.3.6",
     "hast-util-to-string": "3.0.1",
-    hono: "4.12.12",
+    hono: "4.12.14",
     "http-terminator": "3.2.0",
     "javascript-stringify": "2.1.0",
     "json-schema-to-typescript-lite": "15.0.0",
@@ -3973,7 +3974,7 @@ var package_default = {
     "next-themes": "0.4.6",
     oauth4webapi: "3.8.5",
     "openapi-types": "12.1.3",
-    pagefind: "1.5.0-beta.1",
+    pagefind: "1.5.2",
     picocolors: "1.1.1",
     piscina: "5.1.4",
     "posthog-node": "5.26.0",
@@ -4010,9 +4011,9 @@ var package_default = {
     zustand: "5.0.12"
   },
   devDependencies: {
-    "@clerk/clerk-js": "^6.0.0",
-    "@graphql-codegen/cli": "6.1.2",
-    "@inkeep/cxkit-types": "0.5.116",
+    "@clerk/clerk-js": "^6.7.4",
+    "@graphql-codegen/cli": "6.3.0",
+    "@inkeep/cxkit-types": "0.5.117",
     "@testing-library/dom": "catalog:",
     "@testing-library/jest-dom": "catalog:",
     "@testing-library/react": "catalog:",
@@ -4030,7 +4031,7 @@ var package_default = {
     "@types/yargs": "17.0.35",
     "@vitest/coverage-v8": "4.0.18",
     "happy-dom": "catalog:",
-    "oxc-parser": "^0.119.0",
+    "oxc-parser": "^0.126.0",
     react: "catalog:",
     "react-dom": "catalog:",
     tsx: "4.21.0",
@@ -4730,6 +4731,9 @@ var handleCircularRefs = (obj, currentPath = /* @__PURE__ */ new WeakSet(), refs
   const result = Array.isArray(obj) ? obj.map((item, i) => recurse(item, i.toString())) : Object.fromEntries(
     Object.entries(obj).map(([k, v]) => [k, recurse(v, k)])
   );
+  if (!Array.isArray(result) && typeof refPath === "string" && !("__$ref" in result)) {
+    result.__$ref = refPath;
+  }
   refs.set(obj, result);
   currentPath.delete(obj);
   if (typeof refPath === "string") currentRefPaths.delete(refPath);
@@ -6224,15 +6228,37 @@ var viteApiPlugin = async () => {
         );
         const apis = ensureArray(config2.apis);
         const apiMetadata = [];
+        const httpMethods = /* @__PURE__ */ new Set([
+          "get",
+          "post",
+          "put",
+          "patch",
+          "delete",
+          "options",
+          "head",
+          "trace"
+        ]);
         for (const apiConfig of apis) {
           if (apiConfig.type === "file" && apiConfig.path) {
             const latestSchema = schemaManager.getLatestSchema(apiConfig.path);
             if (!latestSchema?.schema.info) continue;
+            const operationCount = Object.values(
+              latestSchema.schema.paths ?? {}
+            ).reduce((sum, pathItem) => {
+              if (!pathItem || typeof pathItem !== "object") return sum;
+              return sum + Object.keys(pathItem).filter(
+                (m) => httpMethods.has(m.toLowerCase())
+              ).length;
+            }, 0);
+            const rawVersion = latestSchema.schema.info.version;
+            const version = rawVersion ? rawVersion.startsWith("v") || rawVersion.startsWith("V") ? rawVersion : `v${rawVersion}` : void 0;
             apiMetadata.push({
               path: apiConfig.path,
               label: latestSchema.schema.info.title,
               description: latestSchema.schema.info.description ?? "",
-              categories: apiConfig.categories ?? []
+              categories: apiConfig.categories ?? [],
+              version,
+              operationCount
             });
           }
         }
@@ -7775,6 +7801,7 @@ async function writeOutput(dir, {
 // src/vite/prerender/prerender.ts
 init_logger();
 init_file_exists();
+import { readFileSync as readFileSync2 } from "node:fs";
 import { readFile as readFile2, rm } from "node:fs/promises";
 import os from "node:os";
 import path21 from "node:path";
@@ -7945,7 +7972,9 @@ var prerender = async ({
       paths.push(joinUrl(r.from));
     }
   }
-  const maxThreads = buildConfig?.prerender?.workers ?? Math.floor(os.cpus().length * 0.8);
+  const { maxThreads, maxOldGenerationSizeMb } = getWorkerScaling(
+    buildConfig?.prerender?.workers
+  );
   const start = performance.now();
   const LOG_INTERVAL_MS = 3e4;
   let lastLogTime = start;
@@ -7974,7 +8003,11 @@ var prerender = async ({
   const pool = new Piscina({
     filename: new URL("./worker.js", import.meta.url).href,
     idleTimeout: 5e3,
+    minThreads: 1,
     maxThreads,
+    resourceLimits: {
+      maxOldGenerationSizeMb
+    },
     workerData: {
       template: html,
       distDir,
@@ -7986,12 +8019,6 @@ var prerender = async ({
   const workerResults = await Promise.all(
     paths.map(async (urlPath) => {
       const result = await pool.run({ urlPath });
-      if (result.statusCode < 400) {
-        await pagefindIndex?.addHTMLFile({
-          url: urlPath,
-          content: result.html
-        });
-      }
       completedCount++;
       if (isTTY()) {
         writeProgress(completedCount, paths.length, urlPath);
@@ -8009,9 +8036,6 @@ var prerender = async ({
       return result;
     })
   );
-  const pagefindWriteResult = await pagefindIndex?.writeFiles({
-    outputPath: path21.join(distDir, "pagefind")
-  });
   const seconds = ((performance.now() - start) / 1e3).toFixed(1);
   const message = `\u2713 finished prerendering ${paths.length} routes in ${seconds} seconds using ${maxThreads} workers`;
   if (isTTY()) {
@@ -8020,10 +8044,38 @@ var prerender = async ({
   } else {
     logger.info(colors7.blue(message));
   }
-  if (pagefindWriteResult?.outputPath) {
-    logger.info(
-      colors7.blue(`\u2713 pagefind index built: ${pagefindWriteResult.outputPath}`)
+  if (pagefindIndex) {
+    const pagesToIndex = workerResults.flatMap(
+      ({ statusCode, html: html2 }, i) => statusCode < 400 ? { url: paths[i], html: html2 } : []
     );
+    const BATCH_SIZE = 40;
+    const pagefindStart = performance.now();
+    for (let offset = 0; offset < pagesToIndex.length; offset += BATCH_SIZE) {
+      const batch = pagesToIndex.slice(offset, offset + BATCH_SIZE);
+      await Promise.all(
+        batch.map(
+          ({ url, html: html2 }) => pagefindIndex.addHTMLFile({ url, content: html2 })
+        )
+      );
+      if (isTTY()) {
+        const done = offset + batch.length;
+        writeLine(
+          `pagefind indexing (${done}/${pagesToIndex.length}) ${colors7.dim(batch.at(-1)?.url ?? "")}`
+        );
+      }
+    }
+    if (isTTY()) writeLine("");
+    const { outputPath } = await pagefindIndex.writeFiles({
+      outputPath: path21.join(distDir, "pagefind")
+    });
+    if (outputPath) {
+      const duration = (performance.now() - pagefindStart) / 1e3;
+      logger.info(
+        colors7.blue(
+          `\u2713 pagefind index built in ${duration.toFixed(1)} seconds: ${outputPath}`
+        )
+      );
+    }
   }
   const redirectUrls = getRedirectUrls(workerResults, config2.basePath);
   await generateSitemap({
@@ -8074,6 +8126,52 @@ var prerender = async ({
   }
   return { workerResults, rewrites };
 };
+var getWorkerScaling = (workersOverride) => {
+  const PER_WORKER_HEAP_LIMIT_MB = 4096;
+  const MAX_WORKERS = 8;
+  const osTotalMb = Math.floor(os.totalmem() / (1024 * 1024));
+  const cgroupMemMb = getContainerMemoryLimitMb();
+  const totalMemMb = cgroupMemMb !== void 0 ? Math.min(cgroupMemMb, osTotalMb) : osTotalMb;
+  const reservedMb = Math.max(2048, Math.floor(totalMemMb * 0.25));
+  const availableForWorkersMb = totalMemMb - reservedMb;
+  const memBasedWorkers = Math.max(
+    1,
+    Math.floor(availableForWorkersMb / PER_WORKER_HEAP_LIMIT_MB)
+  );
+  const cpuBasedWorkers = Math.max(1, Math.floor(os.cpus().length * 0.5));
+  const defaultWorkers = Math.min(
+    memBasedWorkers,
+    cpuBasedWorkers,
+    MAX_WORKERS
+  );
+  const validOverride = workersOverride && workersOverride > 0 ? workersOverride : void 0;
+  const maxThreads = validOverride ?? defaultWorkers;
+  const maxOldGenerationSizeMb = Math.min(
+    PER_WORKER_HEAP_LIMIT_MB,
+    Math.max(512, Math.floor(availableForWorkersMb / maxThreads))
+  );
+  return { maxThreads, maxOldGenerationSizeMb };
+};
+var getContainerMemoryLimitMb = () => {
+  const CGROUP_PATHS = [
+    "/sys/fs/cgroup/memory.max",
+    // cgroup v2
+    "/sys/fs/cgroup/memory/memory.limit_in_bytes"
+    // cgroup v1
+  ];
+  for (const filePath of CGROUP_PATHS) {
+    try {
+      const raw = readFileSync2(filePath, "utf8").trim();
+      if (raw === "max") return void 0;
+      const bytes = Number(raw);
+      if (!Number.isFinite(bytes) || bytes > 2 ** 50) return void 0;
+      return Math.floor(bytes / (1024 * 1024));
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  return void 0;
+};
 
 // src/vite/build.ts
 var DIST_DIR = "dist";
@@ -8160,7 +8258,7 @@ var runPrerender = async (options) => {
       await writeFile5(indexHtml, html, "utf-8");
     }
     const statusPages = workerResults.flatMap(
-      (r) => /400|404|500\.html$/.test(r.outputPath) ? r.outputPath : []
+      (r) => /^(400|404|500)\.html$/.test(path22.basename(r.outputPath)) ? r.outputPath : []
     );
     for (const statusPage of statusPages) {
       await rename(

package/dist/declarations/lib/authentication/providers/openid.d.ts

@@ -43,6 +43,7 @@ export declare class OpenIDAuthenticationProvider extends CoreAuthenticationPlug
         replace?: boolean;
     }): Promise<void>;
     signIn(_: AuthActionContext, { redirectTo, replace }: AuthActionOptions): Promise<void>;
+    private buildUserProfile;
     refreshUserProfile(): Promise<boolean>;
     private authorize;
     getAccessToken(): Promise<string>;

package/dist/declarations/lib/authentication/state.d.ts

@@ -39,11 +39,16 @@ export declare const useAuthState: import("zustand").UseBoundStore<Omit<import("
         getOptions: () => Partial<import("zustand/middleware").PersistOptions<AuthState, unknown, unknown>>;
     };
 }>;
+export type CustomClaim = string | number | boolean | null | CustomClaimRecord | CustomClaimArray | undefined;
+export interface CustomClaimRecord {
+    [key: string]: CustomClaim;
+}
+export type CustomClaimArray = CustomClaim[];
 export interface UserProfile {
     sub: string;
     email: string | undefined;
     emailVerified: boolean;
     name: string | undefined;
     pictureUrl: string | undefined;
-    [key: string]: string | boolean | undefined;
+    [key: string]: CustomClaim;
 }

package/dist/declarations/lib/plugins/api-catalog/Catalog.d.ts

@@ -1,4 +1,2 @@
-import { type ApiCatalogPluginOptions } from "./index.js";
-export declare const Catalog: ({ items, filterCatalogItems, label, categoryLabel, }: Omit<ApiCatalogPluginOptions, "path"> & {
-    categoryLabel?: string;
-}) => import("react/jsx-runtime").JSX.Element;
+import type { ApiCatalogPluginOptions } from "./index.js";
+export declare const Catalog: ({ items, filterCatalogItems, label, }: Omit<ApiCatalogPluginOptions, "path">) => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/plugins/api-catalog/index.d.ts

@@ -1,11 +1,12 @@
 import type { AuthState } from "../../authentication/state.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
-export declare const getKey: (category: string, tag: string) => string;
 export type ApiCatalogItem = {
     path: string;
     label: string;
     description: string;
     categories: CatalogCategory[];
+    version?: string;
+    operationCount?: number;
 };
 export type CatalogCategory = {
     label: string;
@@ -22,10 +23,4 @@ export type CatalogContext = {
     auth: AuthState;
 };
 export type FilterCatalogItemsFn = (items: ApiCatalogItem[], { auth }: CatalogContext) => ApiCatalogItem[];
-export declare const apiCatalogPlugin: ({ path, items, label, categories, filterCatalogItems, }: {
-    path: string;
-    label: string;
-    categories?: CatalogCategory[];
-    items: ApiCatalogItem[];
-    filterCatalogItems?: FilterCatalogItemsFn;
-}) => ZudokuPlugin;
+export declare const apiCatalogPlugin: ({ path, items, label, categories, filterCatalogItems, }: ApiCatalogPluginOptions) => ZudokuPlugin;

package/dist/declarations/lib/plugins/openapi/MCPEndpoint.d.ts

@@ -1,6 +1,7 @@
+import { type McpServerData } from "./mcp-configs.js";
 export declare const MCPEndpoint: ({ serverUrl, operationPath, summary, data, }: {
     serverUrl?: string;
     operationPath?: string;
-    data?: boolean | Record<string, unknown>;
+    data?: McpServerData;
     summary?: string;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/plugins/openapi/mcp-configs.d.ts

@@ -0,0 +1,28 @@
+export type McpServerData = boolean | Record<string, unknown>;
+export interface AuthHeader {
+    headerName: string;
+    placeholder: string;
+}
+export type AuthType = "none" | "apiKey" | "oauth";
+export declare const getAuthType: (data?: McpServerData) => AuthType;
+export declare const getAuthHeader: (data?: McpServerData) => AuthHeader | undefined;
+export interface McpSubApp {
+    id: string;
+    label: string;
+    supportedAuth: AuthType[];
+}
+export interface McpApp {
+    id: string;
+    label: string;
+    subApps: McpSubApp[];
+}
+export declare const MCP_APPS: McpApp[];
+export declare const getVisibleApps: (authType: AuthType) => McpApp[];
+export declare const getMcpServerName: (data?: McpServerData, summary?: string) => string;
+export declare const getMcpUrl: (serverUrl?: string, operationPath?: string) => string;
+export declare const getClaudeCodeCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getCodexCliCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getCursorConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getVscodeConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getCodexConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getGenericConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;

package/dist/declarations/lib/plugins/openapi/schema/SchemaRefLink.d.ts

@@ -0,0 +1,5 @@
+export declare const SchemaRefLink: ({ name, suffix, className, }: {
+    name: string;
+    suffix?: string;
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/plugins/openapi/schema/SchemaView.d.ts

@@ -1,7 +1,8 @@
 import type { SchemaObject } from "../../../oas/parser/index.js";
-export declare const SchemaView: ({ schema, defaultOpen, cardHeader, embedded, }: {
+export declare const SchemaView: ({ schema, defaultOpen, cardHeader, embedded, hideRootRef, }: {
     schema?: SchemaObject | null;
     defaultOpen?: boolean;
     cardHeader?: React.ReactNode;
     embedded?: boolean;
+    hideRootRef?: boolean;
 }) => import("react/jsx-runtime").JSX.Element | undefined;

package/dist/declarations/lib/plugins/openapi/schema/utils.d.ts

@@ -6,4 +6,5 @@ export declare const isCircularRef: (schema: unknown) => schema is string;
 export declare const isArrayCircularRef: (schema: SchemaObject) => schema is SchemaObject & {
     items: SchemaObject;
 };
+export declare const getSchemaRefName: (schema?: SchemaObject | null) => string | undefined;
 export declare const extractCircularRefInfo: (ref?: string | SchemaObject) => string | undefined;

package/dist/declarations/lib/ui/HoverCard.d.ts

@@ -1,6 +1,6 @@
 import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
-import * as React from "react";
-declare const HoverCard: React.FC<HoverCardPrimitive.HoverCardProps>;
-declare const HoverCardTrigger: React.ForwardRefExoticComponent<HoverCardPrimitive.HoverCardTriggerProps & React.RefAttributes<HTMLAnchorElement>>;
-declare const HoverCardContent: React.ForwardRefExoticComponent<Omit<HoverCardPrimitive.HoverCardContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export { HoverCard, HoverCardContent, HoverCardTrigger };
+import type * as React from "react";
+declare function HoverCard({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function HoverCardTrigger({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+declare function HoverCardContent({ className, align, sideOffset, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+export { HoverCard, HoverCardTrigger, HoverCardContent };

package/dist/declarations/lib/ui/Toggle.d.ts

@@ -1,12 +1,8 @@
-import * as TogglePrimitive from "@radix-ui/react-toggle";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
 import { type VariantProps } from "class-variance-authority";
-import * as React from "react";
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | null | undefined;
     size?: "default" | "sm" | "lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare const Toggle: React.ForwardRefExoticComponent<Omit<TogglePrimitive.ToggleProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
-    variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "sm" | "lg" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string> & React.RefAttributes<HTMLButtonElement>>;
+declare function Toggle({ className, variant, size, ...props }: TogglePrimitive.Props & VariantProps<typeof toggleVariants>): import("react/jsx-runtime").JSX.Element;
 export { Toggle, toggleVariants };

package/dist/declarations/lib/ui/ToggleGroup.d.ts

@@ -1,12 +1,10 @@
-import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
 import type { VariantProps } from "class-variance-authority";
 import * as React from "react";
-declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref">) & VariantProps<(props?: ({
-    variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "sm" | "lg" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string>) & React.RefAttributes<HTMLDivElement>>;
-declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
-    variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "sm" | "lg" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string> & React.RefAttributes<HTMLButtonElement>>;
+import { Toggle, toggleVariants } from "./Toggle.js";
+declare function ToggleGroup({ className, variant, size, spacing, orientation, children, ...props }: ToggleGroupPrimitive.Props & VariantProps<typeof toggleVariants> & {
+    spacing?: number;
+    orientation?: "horizontal" | "vertical";
+}): import("react/jsx-runtime").JSX.Element;
+declare function ToggleGroupItem({ className, children, variant, size, ...props }: React.ComponentProps<typeof Toggle>): import("react/jsx-runtime").JSX.Element;
 export { ToggleGroup, ToggleGroupItem };

package/docs/configuration/authentication-auth0.md

@@ -34,7 +34,10 @@ If you don't have an Auth0 account, you can sign up for a
      - Production: `https://your-site.com/oauth/callback`
      - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
      - Local Development: `http://localhost:3000/oauth/callback`
-   - **Allowed Logout URLs**: Same as callback URLs above
+   - **Allowed Logout URLs**:
+     - Production: `https://your-site.com/oauth/logout-callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/logout-callback`
+     - Local Development: `http://localhost:3000/oauth/logout-callback`
 
    - **Allowed Web Origins**:
      - Production: `https://your-site.com`
@@ -112,8 +115,8 @@ To enable logout for your Auth0 application:
 
 1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
    [Configure Auth0 Application](#setup-steps) above)
-2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
-   production)
+2. The logout URL must use the `/oauth/logout-callback` path (e.g.,
+   `https://your-site.com/oauth/logout-callback` for production)
 
 For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
 [Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)

package/docs/configuration/authentication-openid.md

@@ -0,0 +1,110 @@
+---
+title: OpenID Connect (OIDC)
+sidebar_label: OpenID Connect
+description:
+  Configure any OpenID Connect compliant identity provider (Okta, Keycloak, Authentik, etc.) as the
+  authentication provider for Zudoku.
+---
+
+Zudoku supports any identity provider that implements the
+[OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) protocol via the generic
+`openid` provider type. This includes Okta, Keycloak, Authentik, Ory, ZITADEL, AWS Cognito, Google
+Identity, and most enterprise IdPs.
+
+## Configuration
+
+Add the `authentication` property to your [Zudoku configuration](./overview.md):
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "<the-issuer-url>",
+    scopes: ["openid", "profile", "email"], // Optional
+  },
+  // ...
+}
+```
+
+| Option     | Required | Description                                                                                  |
+| ---------- | -------- | -------------------------------------------------------------------------------------------- |
+| `clientId` | Yes      | The OAuth client ID issued by your provider.                                                 |
+| `issuer`   | Yes      | The issuer URL. Zudoku discovers endpoints from `<issuer>/.well-known/openid-configuration`. |
+| `scopes`   | No       | Scopes to request. Defaults to `["openid", "profile", "email"]`.                             |
+
+## Provider Setup
+
+Register Zudoku as a public SPA / single page application client in your identity provider and set:
+
+- Callback / Redirect URI to `https://your-site.com/oauth/callback`
+- For local development, add `http://localhost:3000/oauth/callback`
+- If your provider supports wildcards, add `https://*.your-domain.com/oauth/callback` for preview
+  environments
+- Add your site origin to the list of allowed CORS origins
+- Enable the `Authorization Code` grant with PKCE and the `Refresh Token` grant
+
+### Okta
+
+1. In the Okta admin console go to **Applications** → **Applications** → **Create App Integration**.
+2. Select **OIDC - OpenID Connect** and **Single Page Application**.
+3. Set **Sign-in redirect URIs** to `https://your-site.com/oauth/callback` (add
+   `http://localhost:3000/oauth/callback` for local development).
+4. Under **Assignments**, assign the users or groups that should have access.
+5. After creating the app, copy the **Client ID**. Your issuer is your Okta domain, for example
+   `https://your-tenant.okta.com` or a custom authorization server like
+   `https://your-tenant.okta.com/oauth2/default`.
+6. Under **Security** → **API** → **Trusted Origins**, add your site origin for both CORS and
+   Redirect.
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "<your-okta-client-id>",
+    issuer: "https://your-tenant.okta.com/oauth2/default",
+    scopes: ["openid", "profile", "email"],
+  },
+}
+```
+
+### Keycloak
+
+Use the realm issuer URL:
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "zudoku",
+    issuer: "https://keycloak.example.com/realms/<your-realm>",
+  },
+}
+```
+
+In the realm, create a client with **Client type** `OpenID Connect`, **Access type** `public`, and
+enable **Standard Flow** (Authorization Code).
+
+## Verifying the Issuer
+
+You can confirm your issuer URL is correct by opening `<issuer>/.well-known/openid-configuration` in
+a browser. It should return a JSON document listing `authorization_endpoint`, `token_endpoint`,
+`userinfo_endpoint`, and `jwks_uri`.
+
+## User Profile
+
+After sign-in Zudoku calls the provider's
+[UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) and reads
+`name`, `email`, `picture`, and `email_verified` from the response. Map these claims in your
+provider if they are not emitted by default.
+
+## Troubleshooting
+
+- **Discovery fails**: verify `<issuer>/.well-known/openid-configuration` resolves and matches the
+  `issuer` value in the document.
+- **CORS errors on token / userinfo**: add your site origin to the provider's allowed origins.
+- **Redirect URI mismatch**: the URI registered with the provider must match the Zudoku origin
+  exactly, including protocol and port.
+- **Missing profile fields**: ensure `profile` and `email` scopes are granted and that the provider
+  includes `name`, `email`, and `picture` claims in the UserInfo response.

package/docs/configuration/authentication.md

@@ -15,8 +15,8 @@ authentication provider you use.
 
 ## Authentication Providers
 
-Zudoku supports Clerk, Auth0, Supabase, Firebase, Azure B2C, and any OpenID provider that supports
-the OpenID Connect protocol (including PingFederate).
+Zudoku supports Clerk, Auth0, Supabase, Firebase, Azure B2C, and any OpenID Connect provider
+(including Okta, Keycloak, Authentik, and PingFederate).
 
 Not seeing your authentication provider? [Let us know](https://github.com/zuplo/zudoku/issues)
 
@@ -96,6 +96,9 @@ When configuring your OpenID provider, you will need to set the following:
 By default, the scopes "openid", "profile", and "email" are requested. You can customize these by
 providing your own array of scopes.
 
+For provider-specific guides (Okta, Keycloak, etc.), see the
+[OpenID Connect setup page](./authentication-openid.md).
+
 ### Firebase
 
 For Firebase authentication, you will need your Firebase project configuration. You can find this in

package/docs/deploy/github-pages.md

@@ -30,6 +30,18 @@ const config: ZudokuConfig = {
 };
 ```
 
+When `basePath` is set, Zudoku writes the site into `dist/<basePath>/`. Upload that nested directory
+as your Pages artifact, not `dist/` itself. For example in a GitHub Actions workflow:
+
+```yaml
+- uses: actions/upload-pages-artifact@v3
+  with:
+    path: dist/your-repo
+```
+
+Uploading the outer `dist/` would nest the site under `/your-repo/your-repo/` and every asset
+would 404.
+
 ## Accurate Last Modified Dates
 
 If you have enabled the [`showLastModified`](/docs/configuration/docs#showlastmodified) option,