rspress-plugin-api-extractor 0.2.2 → 0.3.0

package/index.d.ts

@@ -3,20 +3,31 @@ import { Schema } from "effect";
 import { RspressPlugin } from "@rspress/core";
 
 //#region src/schemas/config.d.ts
+/**
+ * Verbosity level for plugin build output.
+ *
+ * @public
+ */
 declare const LogLevel: Schema.Literal<["none", "info", "verbose", "debug", "warn", "error"]>;
+/** @public */
 type LogLevel = Schema.Schema.Type<typeof LogLevel>;
+/**
+ * Configuration for a single documentation category (e.g. Classes, Functions).
+ *
+ * @public
+ */
 declare const CategoryConfig: Schema.mutable<Schema.Struct<{
-  displayName: typeof Schema.String;
-  singularName: typeof Schema.String;
-  folderName: typeof Schema.String;
-  itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-  tsdocModifier: Schema.optional<typeof Schema.String>;
+  /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+  singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+  folderName: typeof Schema.String; /** API item kinds included in this category. */
+  itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+  tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
   collapsible: Schema.optionalWith<typeof Schema.Boolean, {
     default: () => true;
-  }>;
+  }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
   collapsed: Schema.optionalWith<typeof Schema.Boolean, {
     default: () => true;
-  }>;
+  }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
   overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
     default: () => number[];
   }>;
@@ -24,49 +35,65 @@ declare const CategoryConfig: Schema.mutable<Schema.Struct<{
 /**
  * Consumer-facing type uses Encoded (input shape with optional fields).
  * Schema.decode fills in defaults at runtime.
+ *
+ * @public
  */
 type CategoryConfig = Schema.Schema.Encoded<typeof CategoryConfig>;
+/**
+ * Source repository link configuration for an API.
+ *
+ * @public
+ */
 declare const SourceConfig: Schema.mutable<Schema.Struct<{
-  url: typeof Schema.String;
+  /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
   ref: Schema.optional<typeof Schema.String>;
 }>>;
+/** @public */
 type SourceConfig = Schema.Schema.Type<typeof SourceConfig>;
 /**
- * Built-in default categories
+ * Built-in default category definitions covering Classes, Interfaces, Functions,
+ * Types, Enums, Variables, and Namespaces.
+ *
+ * @public
  */
 declare const DEFAULT_CATEGORIES: Record<string, CategoryConfig>;
+/**
+ * Configuration for a single version of an API within a multi-version setup.
+ *
+ * @public
+ */
 declare const VersionConfig: Schema.mutable<Schema.Struct<{
-  model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>;
-  packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  /** Path or loader for the `.api.json` model file for this version. */model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>; /** Path or loader for the `package.json` for this version. */
+  packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Category overrides for this version. */
   categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-    displayName: typeof Schema.String;
-    singularName: typeof Schema.String;
-    folderName: typeof Schema.String;
-    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-    tsdocModifier: Schema.optional<typeof Schema.String>;
+    /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+    singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+    folderName: typeof Schema.String; /** API item kinds included in this category. */
+    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+    tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
     collapsible: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
     collapsed: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
     overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
       default: () => number[];
     }>;
-  }>>>>>;
+  }>>>>>; /** Source repository link configuration for this version. */
   source: Schema.optional<Schema.mutable<Schema.Struct<{
-    url: typeof Schema.String;
+    /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
     ref: Schema.optional<typeof Schema.String>;
-  }>>>;
+  }>>>; /** External npm packages whose types should be loaded for Twoslash. */
   externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
     name: typeof Schema.String;
     version: typeof Schema.String;
     tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
     compilerOptions: Schema.optional<typeof Schema.Unknown>;
-  }>>>>>;
+  }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
   autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
     dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-      default: () => false;
+      default: () => true;
     }>;
     devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => false;
@@ -77,7 +104,7 @@ declare const VersionConfig: Schema.mutable<Schema.Struct<{
     autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
     }>;
-  }>>>;
+  }>>>; /** Open Graph image configuration for this version. */
   ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
     url: typeof Schema.String;
     secureUrl: Schema.optional<typeof Schema.String>;
@@ -85,7 +112,7 @@ declare const VersionConfig: Schema.mutable<Schema.Struct<{
     width: Schema.optional<typeof Schema.Number>;
     height: Schema.optional<typeof Schema.Number>;
     alt: Schema.optional<typeof Schema.String>;
-  }>>]>>;
+  }>>]>>; /** LLMs integration options for this version. */
   llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
     enabled: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
@@ -108,50 +135,56 @@ declare const VersionConfig: Schema.mutable<Schema.Struct<{
     viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
       default: () => ["markdownLink", "chatgpt", "claude"];
     }>;
-  }>>>;
-  tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  }>>>; /** Path to a `tsconfig.json` for this version. */
+  tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
   compilerOptions: Schema.optional<typeof Schema.Unknown>;
 }>>;
+/** @public */
 type VersionConfig = Schema.Schema.Type<typeof VersionConfig>;
+/**
+ * Configuration for a single-package API documentation site (the `api:` option).
+ *
+ * @public
+ */
 declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
-  packageName: typeof Schema.String;
-  name: Schema.optional<typeof Schema.String>;
-  baseRoute: Schema.optional<typeof Schema.String>;
-  apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>;
-  model: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
-  packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  /** npm package name of the documented package. */packageName: typeof Schema.String; /** Optional display name shown in the sidebar and page titles. */
+  name: Schema.optional<typeof Schema.String>; /** Base URL route for API pages (defaults to `/api`). */
+  baseRoute: Schema.optional<typeof Schema.String>; /** Subfolder name under `baseRoute` for API pages, or `null` to omit. */
+  apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>; /** Path or loader for the `.api.json` model file. */
+  model: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Path or loader for the `package.json`. */
+  packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Versioned models keyed by version label. */
   versions: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.Union<[Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>, Schema.mutable<Schema.Struct<{
-    model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>;
-    packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+    /** Path or loader for the `.api.json` model file for this version. */model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>; /** Path or loader for the `package.json` for this version. */
+    packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Category overrides for this version. */
     categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-      displayName: typeof Schema.String;
-      singularName: typeof Schema.String;
-      folderName: typeof Schema.String;
-      itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-      tsdocModifier: Schema.optional<typeof Schema.String>;
+      /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+      singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+      folderName: typeof Schema.String; /** API item kinds included in this category. */
+      itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+      tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
       collapsible: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
-      }>;
+      }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
       collapsed: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
-      }>;
+      }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
       overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
         default: () => number[];
       }>;
-    }>>>>>;
+    }>>>>>; /** Source repository link configuration for this version. */
     source: Schema.optional<Schema.mutable<Schema.Struct<{
-      url: typeof Schema.String;
+      /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
       ref: Schema.optional<typeof Schema.String>;
-    }>>>;
+    }>>>; /** External npm packages whose types should be loaded for Twoslash. */
     externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
       name: typeof Schema.String;
       version: typeof Schema.String;
       tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
       compilerOptions: Schema.optional<typeof Schema.Unknown>;
-    }>>>>>;
+    }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
     autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
       dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
+        default: () => true;
       }>;
       devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => false;
@@ -162,7 +195,7 @@ declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
       autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
       }>;
-    }>>>;
+    }>>>; /** Open Graph image configuration for this version. */
     ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
       url: typeof Schema.String;
       secureUrl: Schema.optional<typeof Schema.String>;
@@ -170,7 +203,7 @@ declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
       width: Schema.optional<typeof Schema.Number>;
       height: Schema.optional<typeof Schema.Number>;
       alt: Schema.optional<typeof Schema.String>;
-    }>>]>>;
+    }>>]>>; /** LLMs integration options for this version. */
     llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
       enabled: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
@@ -193,43 +226,43 @@ declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
       viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
         default: () => ["markdownLink", "chatgpt", "claude"];
       }>;
-    }>>>;
-    tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+    }>>>; /** Path to a `tsconfig.json` for this version. */
+    tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
     compilerOptions: Schema.optional<typeof Schema.Unknown>;
-  }>>]>>>>;
+  }>>]>>>>; /** Shiki syntax-highlighting theme. */
   theme: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
     light: typeof Schema.String;
     dark: typeof Schema.String;
-  }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>;
+  }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>; /** Category definitions (defaults to {@link DEFAULT_CATEGORIES}). */
   categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-    displayName: typeof Schema.String;
-    singularName: typeof Schema.String;
-    folderName: typeof Schema.String;
-    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-    tsdocModifier: Schema.optional<typeof Schema.String>;
+    /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+    singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+    folderName: typeof Schema.String; /** API item kinds included in this category. */
+    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+    tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
     collapsible: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
     collapsed: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
     overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
       default: () => number[];
     }>;
-  }>>>>>;
+  }>>>>>; /** Source repository link configuration. */
   source: Schema.optional<Schema.mutable<Schema.Struct<{
-    url: typeof Schema.String;
+    /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
     ref: Schema.optional<typeof Schema.String>;
-  }>>>;
+  }>>>; /** External npm packages whose types should be loaded for Twoslash. */
   externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
     name: typeof Schema.String;
     version: typeof Schema.String;
     tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
     compilerOptions: Schema.optional<typeof Schema.Unknown>;
-  }>>>>>;
+  }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
   autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
     dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-      default: () => false;
+      default: () => true;
     }>;
     devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => false;
@@ -240,7 +273,7 @@ declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
     autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
     }>;
-  }>>>;
+  }>>>; /** Open Graph image configuration. */
   ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
     url: typeof Schema.String;
     secureUrl: Schema.optional<typeof Schema.String>;
@@ -248,7 +281,7 @@ declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
     width: Schema.optional<typeof Schema.Number>;
     height: Schema.optional<typeof Schema.Number>;
     alt: Schema.optional<typeof Schema.String>;
-  }>>]>>;
+  }>>]>>; /** LLMs integration options. */
   llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
     enabled: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
@@ -271,51 +304,57 @@ declare const SingleApiConfig: Schema.mutable<Schema.Struct<{
     viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
       default: () => ["markdownLink", "chatgpt", "claude"];
     }>;
-  }>>>;
-  tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  }>>>; /** Path to a `tsconfig.json` for Twoslash. */
+  tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
   compilerOptions: Schema.optional<typeof Schema.Unknown>;
 }>>;
+/** @public */
 type SingleApiConfig = Schema.Schema.Type<typeof SingleApiConfig>;
+/**
+ * Configuration for one package in a multi-API portal (each element of the `apis:` array).
+ *
+ * @public
+ */
 declare const MultiApiConfig: Schema.mutable<Schema.Struct<{
-  packageName: typeof Schema.String;
-  name: Schema.optional<typeof Schema.String>;
-  baseRoute: Schema.optional<typeof Schema.String>;
-  apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>;
-  model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>;
-  packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  /** npm package name of the documented package. */packageName: typeof Schema.String; /** Optional display name shown in the sidebar and page titles. */
+  name: Schema.optional<typeof Schema.String>; /** Base URL route for this package's API pages. */
+  baseRoute: Schema.optional<typeof Schema.String>; /** Subfolder name under `baseRoute` for API pages, or `null` to omit. */
+  apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>; /** Path or loader for the `.api.json` model file (required). */
+  model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>; /** Path or loader for the `package.json`. */
+  packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Shiki syntax-highlighting theme. */
   theme: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
     light: typeof Schema.String;
     dark: typeof Schema.String;
-  }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>;
+  }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>; /** Category definitions (defaults to {@link DEFAULT_CATEGORIES}). */
   categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-    displayName: typeof Schema.String;
-    singularName: typeof Schema.String;
-    folderName: typeof Schema.String;
-    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-    tsdocModifier: Schema.optional<typeof Schema.String>;
+    /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+    singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+    folderName: typeof Schema.String; /** API item kinds included in this category. */
+    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+    tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
     collapsible: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
     collapsed: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
     overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
       default: () => number[];
     }>;
-  }>>>>>;
+  }>>>>>; /** Source repository link configuration. */
   source: Schema.optional<Schema.mutable<Schema.Struct<{
-    url: typeof Schema.String;
+    /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
     ref: Schema.optional<typeof Schema.String>;
-  }>>>;
+  }>>>; /** External npm packages whose types should be loaded for Twoslash. */
   externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
     name: typeof Schema.String;
     version: typeof Schema.String;
     tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
     compilerOptions: Schema.optional<typeof Schema.Unknown>;
-  }>>>>>;
+  }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
   autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
     dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-      default: () => false;
+      default: () => true;
     }>;
     devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => false;
@@ -326,7 +365,7 @@ declare const MultiApiConfig: Schema.mutable<Schema.Struct<{
     autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
     }>;
-  }>>>;
+  }>>>; /** Open Graph image configuration. */
   ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
     url: typeof Schema.String;
     secureUrl: Schema.optional<typeof Schema.String>;
@@ -334,7 +373,7 @@ declare const MultiApiConfig: Schema.mutable<Schema.Struct<{
     width: Schema.optional<typeof Schema.Number>;
     height: Schema.optional<typeof Schema.Number>;
     alt: Schema.optional<typeof Schema.String>;
-  }>>]>>;
+  }>>]>>; /** LLMs integration options. */
   llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
     enabled: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
@@ -357,51 +396,57 @@ declare const MultiApiConfig: Schema.mutable<Schema.Struct<{
     viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
       default: () => ["markdownLink", "chatgpt", "claude"];
     }>;
-  }>>>;
-  tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  }>>>; /** Path to a `tsconfig.json` for Twoslash. */
+  tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
   compilerOptions: Schema.optional<typeof Schema.Unknown>;
 }>>;
+/** @public */
 type MultiApiConfig = Schema.Schema.Type<typeof MultiApiConfig>;
+/**
+ * Top-level options passed to {@link ApiExtractorPlugin}.
+ *
+ * @public
+ */
 declare const PluginOptions: Schema.mutable<Schema.Struct<{
-  api: Schema.optional<Schema.mutable<Schema.Struct<{
-    packageName: typeof Schema.String;
-    name: Schema.optional<typeof Schema.String>;
-    baseRoute: Schema.optional<typeof Schema.String>;
-    apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>;
-    model: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
-    packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+  /** Single-API configuration (mutually exclusive with `apis`). */api: Schema.optional<Schema.mutable<Schema.Struct<{
+    /** npm package name of the documented package. */packageName: typeof Schema.String; /** Optional display name shown in the sidebar and page titles. */
+    name: Schema.optional<typeof Schema.String>; /** Base URL route for API pages (defaults to `/api`). */
+    baseRoute: Schema.optional<typeof Schema.String>; /** Subfolder name under `baseRoute` for API pages, or `null` to omit. */
+    apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>; /** Path or loader for the `.api.json` model file. */
+    model: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Path or loader for the `package.json`. */
+    packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Versioned models keyed by version label. */
     versions: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.Union<[Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>, Schema.mutable<Schema.Struct<{
-      model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>;
-      packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+      /** Path or loader for the `.api.json` model file for this version. */model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>; /** Path or loader for the `package.json` for this version. */
+      packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Category overrides for this version. */
       categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-        displayName: typeof Schema.String;
-        singularName: typeof Schema.String;
-        folderName: typeof Schema.String;
-        itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-        tsdocModifier: Schema.optional<typeof Schema.String>;
+        /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+        singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+        folderName: typeof Schema.String; /** API item kinds included in this category. */
+        itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+        tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
         collapsible: Schema.optionalWith<typeof Schema.Boolean, {
           default: () => true;
-        }>;
+        }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
         collapsed: Schema.optionalWith<typeof Schema.Boolean, {
           default: () => true;
-        }>;
+        }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
         overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
           default: () => number[];
         }>;
-      }>>>>>;
+      }>>>>>; /** Source repository link configuration for this version. */
       source: Schema.optional<Schema.mutable<Schema.Struct<{
-        url: typeof Schema.String;
+        /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
         ref: Schema.optional<typeof Schema.String>;
-      }>>>;
+      }>>>; /** External npm packages whose types should be loaded for Twoslash. */
       externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
         name: typeof Schema.String;
         version: typeof Schema.String;
         tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
         compilerOptions: Schema.optional<typeof Schema.Unknown>;
-      }>>>>>;
+      }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
       autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
         dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-          default: () => false;
+          default: () => true;
         }>;
         devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
           default: () => false;
@@ -412,7 +457,7 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
         autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
           default: () => true;
         }>;
-      }>>>;
+      }>>>; /** Open Graph image configuration for this version. */
       ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
         url: typeof Schema.String;
         secureUrl: Schema.optional<typeof Schema.String>;
@@ -420,7 +465,7 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
         width: Schema.optional<typeof Schema.Number>;
         height: Schema.optional<typeof Schema.Number>;
         alt: Schema.optional<typeof Schema.String>;
-      }>>]>>;
+      }>>]>>; /** LLMs integration options for this version. */
       llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
         enabled: Schema.optionalWith<typeof Schema.Boolean, {
           default: () => true;
@@ -443,43 +488,43 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
         viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
           default: () => ["markdownLink", "chatgpt", "claude"];
         }>;
-      }>>>;
-      tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+      }>>>; /** Path to a `tsconfig.json` for this version. */
+      tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
       compilerOptions: Schema.optional<typeof Schema.Unknown>;
-    }>>]>>>>;
+    }>>]>>>>; /** Shiki syntax-highlighting theme. */
     theme: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
       light: typeof Schema.String;
       dark: typeof Schema.String;
-    }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>;
+    }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>; /** Category definitions (defaults to {@link DEFAULT_CATEGORIES}). */
     categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-      displayName: typeof Schema.String;
-      singularName: typeof Schema.String;
-      folderName: typeof Schema.String;
-      itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-      tsdocModifier: Schema.optional<typeof Schema.String>;
+      /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+      singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+      folderName: typeof Schema.String; /** API item kinds included in this category. */
+      itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+      tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
       collapsible: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
-      }>;
+      }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
       collapsed: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
-      }>;
+      }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
       overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
         default: () => number[];
       }>;
-    }>>>>>;
+    }>>>>>; /** Source repository link configuration. */
     source: Schema.optional<Schema.mutable<Schema.Struct<{
-      url: typeof Schema.String;
+      /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
       ref: Schema.optional<typeof Schema.String>;
-    }>>>;
+    }>>>; /** External npm packages whose types should be loaded for Twoslash. */
     externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
       name: typeof Schema.String;
       version: typeof Schema.String;
       tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
       compilerOptions: Schema.optional<typeof Schema.Unknown>;
-    }>>>>>;
+    }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
     autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
       dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
+        default: () => true;
       }>;
       devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => false;
@@ -490,7 +535,7 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
       autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
       }>;
-    }>>>;
+    }>>>; /** Open Graph image configuration. */
     ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
       url: typeof Schema.String;
       secureUrl: Schema.optional<typeof Schema.String>;
@@ -498,7 +543,7 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
       width: Schema.optional<typeof Schema.Number>;
       height: Schema.optional<typeof Schema.Number>;
       alt: Schema.optional<typeof Schema.String>;
-    }>>]>>;
+    }>>]>>; /** LLMs integration options. */
     llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
       enabled: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
@@ -521,50 +566,50 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
       viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
         default: () => ["markdownLink", "chatgpt", "claude"];
       }>;
-    }>>>;
-    tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+    }>>>; /** Path to a `tsconfig.json` for Twoslash. */
+    tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
     compilerOptions: Schema.optional<typeof Schema.Unknown>;
-  }>>>;
+  }>>>; /** Multi-API portal configuration (mutually exclusive with `api`). */
   apis: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
-    packageName: typeof Schema.String;
-    name: Schema.optional<typeof Schema.String>;
-    baseRoute: Schema.optional<typeof Schema.String>;
-    apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>;
-    model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>;
-    packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+    /** npm package name of the documented package. */packageName: typeof Schema.String; /** Optional display name shown in the sidebar and page titles. */
+    name: Schema.optional<typeof Schema.String>; /** Base URL route for this package's API pages. */
+    baseRoute: Schema.optional<typeof Schema.String>; /** Subfolder name under `baseRoute` for API pages, or `null` to omit. */
+    apiFolder: Schema.optional<Schema.Union<[typeof Schema.String, typeof Schema.Null]>>; /** Path or loader for the `.api.json` model file (required). */
+    model: Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>; /** Path or loader for the `package.json`. */
+    packageJson: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** Shiki syntax-highlighting theme. */
     theme: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
       light: typeof Schema.String;
       dark: typeof Schema.String;
-    }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>;
+    }>>, Schema.mutable<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>]>>; /** Category definitions (defaults to {@link DEFAULT_CATEGORIES}). */
     categories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-      displayName: typeof Schema.String;
-      singularName: typeof Schema.String;
-      folderName: typeof Schema.String;
-      itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-      tsdocModifier: Schema.optional<typeof Schema.String>;
+      /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+      singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+      folderName: typeof Schema.String; /** API item kinds included in this category. */
+      itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+      tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
       collapsible: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
-      }>;
+      }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
       collapsed: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
-      }>;
+      }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
       overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
         default: () => number[];
       }>;
-    }>>>>>;
+    }>>>>>; /** Source repository link configuration. */
     source: Schema.optional<Schema.mutable<Schema.Struct<{
-      url: typeof Schema.String;
+      /** Base URL of the source repository (e.g. `"https://github.com/org/repo/blob/main/src"`). */url: typeof Schema.String; /** Optional git ref (branch, tag, or commit SHA) appended to source links. */
       ref: Schema.optional<typeof Schema.String>;
-    }>>>;
+    }>>>; /** External npm packages whose types should be loaded for Twoslash. */
     externalPackages: Schema.optional<Schema.mutable<Schema.Array$<Schema.mutable<Schema.Struct<{
       name: typeof Schema.String;
       version: typeof Schema.String;
       tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
       compilerOptions: Schema.optional<typeof Schema.Unknown>;
-    }>>>>>;
+    }>>>>>; /** Auto-detect external packages from `package.json` dependency fields. */
     autoDetectDependencies: Schema.optional<Schema.mutable<Schema.Struct<{
       dependencies: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
+        default: () => true;
       }>;
       devDependencies: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => false;
@@ -575,7 +620,7 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
       autoDependencies: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
       }>;
-    }>>>;
+    }>>>; /** Open Graph image configuration. */
     ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
       url: typeof Schema.String;
       secureUrl: Schema.optional<typeof Schema.String>;
@@ -583,7 +628,7 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
       width: Schema.optional<typeof Schema.Number>;
       height: Schema.optional<typeof Schema.Number>;
       alt: Schema.optional<typeof Schema.String>;
-    }>>]>>;
+    }>>]>>; /** LLMs integration options. */
     llmsPlugin: Schema.optional<Schema.mutable<Schema.Struct<{
       enabled: Schema.optionalWith<typeof Schema.Boolean, {
         default: () => true;
@@ -606,11 +651,11 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
       viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
         default: () => ["markdownLink", "chatgpt", "claude"];
       }>;
-    }>>>;
-    tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>;
+    }>>>; /** Path to a `tsconfig.json` for Twoslash. */
+    tsconfig: Schema.optional<Schema.declare<string | ((...args: Array<unknown>) => unknown) | URL, string | ((...args: Array<unknown>) => unknown) | URL, readonly [], never>>; /** TypeScript compiler options for Twoslash. */
     compilerOptions: Schema.optional<typeof Schema.Unknown>;
-  }>>>>>;
-  siteUrl: Schema.optional<typeof Schema.String>;
+  }>>>>>; /** Canonical site URL used for Open Graph absolute URLs. */
+  siteUrl: Schema.optional<typeof Schema.String>; /** Global Open Graph image configuration (overridden per-API). */
   ogImage: Schema.optional<Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
     url: typeof Schema.String;
     secureUrl: Schema.optional<typeof Schema.String>;
@@ -618,26 +663,26 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
     width: Schema.optional<typeof Schema.Number>;
     height: Schema.optional<typeof Schema.Number>;
     alt: Schema.optional<typeof Schema.String>;
-  }>>]>>;
+  }>>]>>; /** Override the default category definitions for all APIs. */
   defaultCategories: Schema.optional<Schema.mutable<Schema.Record$<typeof Schema.String, Schema.mutable<Schema.Struct<{
-    displayName: typeof Schema.String;
-    singularName: typeof Schema.String;
-    folderName: typeof Schema.String;
-    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>;
-    tsdocModifier: Schema.optional<typeof Schema.String>;
+    /** Human-readable plural display name shown in the sidebar. */displayName: typeof Schema.String; /** Human-readable singular name used in page titles. */
+    singularName: typeof Schema.String; /** Folder name under the API base route (URL segment). */
+    folderName: typeof Schema.String; /** API item kinds included in this category. */
+    itemKinds: Schema.optional<Schema.mutable<Schema.Array$<Schema.declare<ApiItemKind, ApiItemKind, readonly [], never>>>>; /** TSDoc modifier tag that marks items for this category. */
+    tsdocModifier: Schema.optional<typeof Schema.String>; /** Whether the sidebar section is collapsible. Defaults to `true`. */
     collapsible: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Whether the sidebar section starts collapsed. Defaults to `true`. */
     collapsed: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
-    }>;
+    }>; /** Heading levels shown in the overview. Defaults to `[2]`. */
     overviewHeaders: Schema.optionalWith<Schema.mutable<Schema.Array$<typeof Schema.Number>>, {
       default: () => number[];
     }>;
-  }>>>>>;
+  }>>>>>; /** Error display options for code examples. */
   errors: Schema.optional<Schema.mutable<Schema.Struct<{
     example: Schema.optional<Schema.Literal<["suppress", "show"]>>;
-  }>>>;
+  }>>>; /** LLMs integration options, or `false` to disable. */
   llmsPlugin: Schema.optional<Schema.Union<[typeof Schema.Boolean, Schema.mutable<Schema.Struct<{
     enabled: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => true;
@@ -660,8 +705,8 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
     viewOptions: Schema.optionalWith<Schema.mutable<Schema.Array$<Schema.Literal<["markdownLink", "chatgpt", "claude"]>>>, {
       default: () => ["markdownLink", "chatgpt", "claude"];
     }>;
-  }>>]>>;
-  logLevel: Schema.optional<Schema.Literal<["none", "info", "verbose", "debug", "warn", "error"]>>;
+  }>>]>>; /** Verbosity level for plugin build output. @deprecated Use `observability.logLevel`. */
+  logLevel: Schema.optional<Schema.Literal<["none", "info", "verbose", "debug", "warn", "error"]>>; /** Performance tuning options. @deprecated Use `observability.thresholds`. */
   performance: Schema.optional<Schema.mutable<Schema.Struct<{
     thresholds: Schema.optional<Schema.mutable<Schema.Struct<{
       slowCodeBlock: Schema.optionalWith<typeof Schema.Number, {
@@ -689,51 +734,98 @@ declare const PluginOptions: Schema.mutable<Schema.Struct<{
     trackDetailedMetrics: Schema.optionalWith<typeof Schema.Boolean, {
       default: () => false;
     }>;
+  }>>>; /** Unified observability configuration (logLevel, trace artifact, thresholds). */
+  observability: Schema.optional<Schema.mutable<Schema.Struct<{
+    logLevel: Schema.optional<Schema.Literal<["none", "error", "warn", "info", "debug", "trace", "verbose"]>>;
+    trace: Schema.optional<Schema.Union<[typeof Schema.Boolean, typeof Schema.String]>>;
+    thresholds: Schema.optional<Schema.mutable<Schema.Struct<{
+      slowCodeBlock: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+      }>;
+      slowPageGeneration: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+      }>;
+      slowApiLoad: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+      }>;
+      slowFileOperation: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+      }>;
+      slowHttpRequest: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+      }>;
+      slowDbOperation: Schema.optionalWith<typeof Schema.Number, {
+        default: () => number;
+      }>;
+    }>>>;
   }>>>;
 }>>;
+/** @public */
 type PluginOptions = Schema.Schema.Type<typeof PluginOptions>;
 //#endregion
 //#region src/schemas/opengraph.d.ts
+/**
+ * Structured Open Graph image metadata (alternative to a plain URL string).
+ *
+ * @public
+ */
 declare const OpenGraphImageMetadata: Schema.mutable<Schema.Struct<{
-  url: typeof Schema.String;
-  secureUrl: Schema.optional<typeof Schema.String>;
-  type: Schema.optional<typeof Schema.String>;
-  width: Schema.optional<typeof Schema.Number>;
-  height: Schema.optional<typeof Schema.Number>;
+  /** Absolute URL of the image. */url: typeof Schema.String; /** HTTPS URL of the image (for secure contexts). */
+  secureUrl: Schema.optional<typeof Schema.String>; /** MIME type of the image (e.g. `"image/png"`). */
+  type: Schema.optional<typeof Schema.String>; /** Image width in pixels. */
+  width: Schema.optional<typeof Schema.Number>; /** Image height in pixels. */
+  height: Schema.optional<typeof Schema.Number>; /** Alt text for the image. */
   alt: Schema.optional<typeof Schema.String>;
 }>>;
+/** @public */
 type OpenGraphImageMetadata = Schema.Schema.Type<typeof OpenGraphImageMetadata>;
+/**
+ * Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
+ *
+ * @public
+ */
 declare const OpenGraphImageConfig: Schema.Union<[typeof Schema.String, Schema.mutable<Schema.Struct<{
-  url: typeof Schema.String;
-  secureUrl: Schema.optional<typeof Schema.String>;
-  type: Schema.optional<typeof Schema.String>;
-  width: Schema.optional<typeof Schema.Number>;
-  height: Schema.optional<typeof Schema.Number>;
+  /** Absolute URL of the image. */url: typeof Schema.String; /** HTTPS URL of the image (for secure contexts). */
+  secureUrl: Schema.optional<typeof Schema.String>; /** MIME type of the image (e.g. `"image/png"`). */
+  type: Schema.optional<typeof Schema.String>; /** Image width in pixels. */
+  width: Schema.optional<typeof Schema.Number>; /** Image height in pixels. */
+  height: Schema.optional<typeof Schema.Number>; /** Alt text for the image. */
   alt: Schema.optional<typeof Schema.String>;
 }>>]>;
+/** @public */
 type OpenGraphImageConfig = Schema.Schema.Type<typeof OpenGraphImageConfig>;
+/**
+ * Resolved Open Graph metadata emitted into each generated page's frontmatter.
+ *
+ * @public
+ */
 declare const OpenGraphMetadata: Schema.mutable<Schema.Struct<{
-  siteUrl: typeof Schema.String;
-  pageRoute: typeof Schema.String;
-  description: typeof Schema.String;
-  publishedTime: typeof Schema.String;
-  modifiedTime: typeof Schema.String;
-  section: typeof Schema.String;
-  tags: Schema.mutable<Schema.Array$<typeof Schema.String>>;
+  /** Canonical site base URL. */siteUrl: typeof Schema.String; /** Page route path (e.g. `/api/classes/myclass`). */
+  pageRoute: typeof Schema.String; /** Page description for the `og:description` tag. */
+  description: typeof Schema.String; /** ISO 8601 date string for `article:published_time`. */
+  publishedTime: typeof Schema.String; /** ISO 8601 date string for `article:modified_time`. */
+  modifiedTime: typeof Schema.String; /** Article section label (e.g. `"API"`). */
+  section: typeof Schema.String; /** Article tag keywords. */
+  tags: Schema.mutable<Schema.Array$<typeof Schema.String>>; /** Optional structured image metadata. */
   ogImage: Schema.optional<Schema.mutable<Schema.Struct<{
-    url: typeof Schema.String;
-    secureUrl: Schema.optional<typeof Schema.String>;
-    type: Schema.optional<typeof Schema.String>;
-    width: Schema.optional<typeof Schema.Number>;
-    height: Schema.optional<typeof Schema.Number>;
+    /** Absolute URL of the image. */url: typeof Schema.String; /** HTTPS URL of the image (for secure contexts). */
+    secureUrl: Schema.optional<typeof Schema.String>; /** MIME type of the image (e.g. `"image/png"`). */
+    type: Schema.optional<typeof Schema.String>; /** Image width in pixels. */
+    width: Schema.optional<typeof Schema.Number>; /** Image height in pixels. */
+    height: Schema.optional<typeof Schema.Number>; /** Alt text for the image. */
     alt: Schema.optional<typeof Schema.String>;
-  }>>>;
+  }>>>; /** Open Graph object type (e.g. `"article"`). */
   ogType: typeof Schema.String;
 }>>;
+/** @public */
 type OpenGraphMetadata = Schema.Schema.Type<typeof OpenGraphMetadata>;
 //#endregion
 //#region src/config-helpers.d.ts
-/** Metadata discovered from a single rslib-builder localPaths package folder. */
+/**
+ * Metadata discovered from a single rslib-builder localPaths package folder.
+ *
+ * @public
+ */
 interface DirInfo {
   /** Absolute path to the package folder. */
   dir: string;
@@ -760,9 +852,15 @@ interface DirInfo {
  * package it yields the scope too (e.g. `@scope/bar`), which is rarely what you
  * want inside a URL path. Prefer `{dirname}` (the folder name, which is the
  * unscoped name in the rslib-builder layout) or the callback form.
+ *
+ * @public
  */
 type BaseRoute = string | ((info: DirInfo) => string);
-/** Overrides for `api.fromDir`. Any MultiApiConfig field wins over discovery. */
+/**
+ * Overrides for `api.fromDir`. Any `MultiApiConfig` field wins over discovery.
+ *
+ * @public
+ */
 type FromDirOptions = Omit<Partial<MultiApiConfig>, "baseRoute"> & {
   baseRoute?: BaseRoute; /** Base for resolving a relative `dir`. Defaults to process.cwd(). */
   cwd?: string;
@@ -789,7 +887,9 @@ declare function fromParentDir(parentDir: string, options?: FromDirOptions): Mul
 //#endregion
 //#region src/internal-types.d.ts
 /**
- * Result from a model loader function
+ * Result returned by a model loader function.
+ *
+ * @public
  */
 interface LoadedModel {
   /** The API model */
@@ -808,6 +908,8 @@ declare function ApiExtractorPluginImpl(rawOptions: PluginOptions): RspressPlugi
  * files. Config helpers are available under `ApiExtractorPlugin.api` (single
  * package → one config for the `api:` option) and `ApiExtractorPlugin.apis`
  * (parent directory → array for the `apis:` option).
+ *
+ * @public
  */
 declare const ApiExtractorPlugin: typeof ApiExtractorPluginImpl & {
   api: {
@@ -819,9 +921,17 @@ declare const ApiExtractorPlugin: typeof ApiExtractorPluginImpl & {
 };
 //#endregion
 //#region src/serve.d.ts
-/** Which RSPress server `serve` runs. */
+/**
+ * Which RSPress server {@link serve} runs.
+ *
+ * @public
+ */
 type ServeMode = "dev" | "preview";
-/** Options for {@link serve}. All fields are optional with sensible defaults. */
+/**
+ * Options for {@link serve}. All fields are optional with sensible defaults.
+ *
+ * @public
+ */
 interface ServeOptions {
   /** Which RSPress server to run. Defaults to `"dev"`. */
   mode?: ServeMode;
@@ -848,7 +958,11 @@ interface ServeOptions {
    */
   readyWhen?: (output: string) => boolean;
 }
-/** Fully resolved {@link ServeOptions} with defaults applied. */
+/**
+ * Fully resolved {@link ServeOptions} with defaults applied.
+ *
+ * @public
+ */
 interface ResolvedServeConfig {
   mode: ServeMode;
   port: number;
@@ -870,12 +984,21 @@ interface ResolvedServeConfig {
  * "ready ... built in" line, kept as a fallback in case the address-line format
  * changes. Pure and exported so it can be unit-tested and reused as a
  * {@link ServeOptions.readyWhen} building block.
+ *
+ * @param mode - the server mode (`"dev"` or `"preview"`)
+ * @param output - a chunk of combined stdout/stderr from the server process
+ * @returns `true` when the server appears to be listening
+ * @public
  */
 declare function isServerReady(mode: ServeMode, output: string): boolean;
 /**
  * Resolve {@link ServeOptions} into a concrete {@link ResolvedServeConfig},
  * applying all defaults. Pure (modulo reading `process.env`) and exported so
  * the resolution logic can be unit-tested without spawning a server.
+ *
+ * @param options - optional serve options; all fields have sensible defaults
+ * @returns a fully resolved config with all defaults applied
+ * @public
  */
 declare function resolveServeConfig(options?: ServeOptions): ResolvedServeConfig;
 /**
@@ -894,6 +1017,10 @@ declare function resolveServeConfig(options?: ServeOptions): ResolvedServeConfig
  * returned promise resolves once the server is ready and the browser has been
  * opened; it does not resolve when the server stops. Port-freeing and browser
  * opening are best-effort and never reject.
+ *
+ * @param options - optional serve options; all fields have sensible defaults
+ * @returns a promise that resolves once the server is ready and the browser has been opened
+ * @public
  */
 declare function serve(options?: ServeOptions): Promise<void>;
 //#endregion