chore: add docs

Author: pkosiec

CLAUDE.md

@@ -257,7 +257,7 @@ const result = await pool.query('SELECT * FROM users');
 ```
 
 **ORM Integration:**
-Works with Drizzle, Prisma, TypeORM - see [Lakebase Integration Docs](docs/docs/integrations/lakebase.md) for examples.
+Works with Drizzle, Prisma, TypeORM - see the [`@databricks/lakebase` README](https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md) for examples.
 
 **Architecture:**
 - Connector files: `packages/appkit/src/connectors/lakebase/`

docs/docs/api/appkit/TypeAlias.LakebasePluginExports.md

@@ -0,0 +1,5 @@
+# Type Alias: LakebasePluginExports
+
+```ts
+type LakebasePluginExports = ReturnType<LakebasePlugin["exports"]>;
+```

docs/docs/api/appkit/TypeAlias.ServerPluginExports.md

@@ -0,0 +1,5 @@
+# Type Alias: ServerPluginExports
+
+```ts
+type ServerPluginExports = ReturnType<ServerPlugin["exports"]>;
+```

docs/docs/api/appkit/index.md

@@ -52,7 +52,9 @@ plugin architecture, and React integration.
 | ------ | ------ |
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
+| [LakebasePluginExports](TypeAlias.LakebasePluginExports.md) | - |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
+| [ServerPluginExports](TypeAlias.ServerPluginExports.md) | - |
 
 ## Variables
 

docs/docs/api/appkit/typedoc-sidebar.ts

@@ -173,10 +173,20 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.IAppRouter",
           label: "IAppRouter"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.LakebasePluginExports",
+          label: "LakebasePluginExports"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ResourcePermission",
           label: "ResourcePermission"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.ServerPluginExports",
+          label: "ServerPluginExports"
         }
       ]
     },

docs/docs/plugins.md

@@ -143,19 +143,101 @@ The analytics plugin exposes these endpoints (mounted under `/api/analytics`):
 - `format: "JSON"` (default) returns JSON rows
 - `format: "ARROW"` returns an Arrow "statement_id" payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`
 
-### Execution context and `asUser(req)`
+
+### Lakebase plugin
+
+Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
+
+**Key features:**
+- Standard `pg.Pool` compatible with any PostgreSQL library or ORM
+- Automatic OAuth token refresh (1-hour tokens, 2-minute refresh buffer)
+- Token caching to minimize API calls
+- Built-in OpenTelemetry instrumentation (query duration, pool connections, token refresh)
+
+#### Basic usage
+
+```ts
+import { createApp, lakebase, server } from "@databricks/appkit";
+
+await createApp({
+  plugins: [server(), lakebase()],
+});
+```
+
+#### Environment variables
+
+The three required environment variables:
+
+| Variable | Description |
+|---|---|
+| `PGHOST` | Lakebase host |
+| `PGDATABASE` | Database name |
+| `LAKEBASE_ENDPOINT` | Endpoint resource path (e.g. `projects/.../branches/.../endpoints/...`) |
+
+When deploying as a Databricks App, `LAKEBASE_ENDPOINT` can be injected automatically via `valueFrom` in your app config:
+
+```yaml
+env:
+  - name: LAKEBASE_ENDPOINT
+    valueFrom: postgres
+```
+
+For the full configuration reference (SSL, pool size, timeouts, logging, ORM examples), see the [`@databricks/lakebase` README](https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md).
+
+#### Accessing the pool
+
+After initialization, access Lakebase through the `AppKit.lakebase` object:
+
+```ts
+const AppKit = await createApp({
+  plugins: [server(), lakebase()],
+});
+
+// Direct query (parameterized)
+const result = await AppKit.lakebase.query(
+  "SELECT * FROM orders WHERE user_id = $1",
+  [userId],
+);
+
+// Raw pg.Pool (for ORMs or advanced usage)
+const pool = AppKit.lakebase.pool;
+
+// ORM-ready config objects
+const ormConfig = AppKit.lakebase.getOrmConfig();  // { host, port, database, ... }
+const pgConfig = AppKit.lakebase.getPgConfig();    // pg.PoolConfig
+```
+
+#### Configuration options
+
+Pass a `pool` object to override any defaults:
+
+```ts
+await createApp({
+  plugins: [
+    lakebase({
+      pool: {
+        max: 10,                      // Max pool connections (default: 10)
+        connectionTimeoutMillis: 5000, // Connection timeout ms (default: 10000)
+        idleTimeoutMillis: 30000,      // Idle connection timeout ms (default: 30000)
+      },
+    }),
+  ],
+});
+```
+
+## Execution context and `asUser(req)`
 
 AppKit manages Databricks authentication via two contexts:
 
 - **ServiceContext** (singleton): Initialized at app startup with service principal credentials
 - **ExecutionContext**: Determined at runtime - either service principal or user context
 
-#### Headers for user context
+### Headers for user context
 
 - `x-forwarded-user`: required in production; identifies the user
 - `x-forwarded-access-token`: required for user token passthrough
 
-#### Using `asUser(req)` for user-scoped operations
+### Using `asUser(req)` for user-scoped operations
 
 The `asUser(req)` pattern allows plugins to execute operations using the requesting user's credentials:
 
@@ -174,7 +256,7 @@ router.post("/system/data", async (req, res) => {
 });
 ```
 
-#### Context helper functions
+### Context helper functions
 
 Exported from `@databricks/appkit`:
 
@@ -184,7 +266,7 @@ Exported from `@databricks/appkit`:
 - `getWorkspaceId()`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
 - `isInUserContext()`: Returns `true` if currently executing in user context
 
-#### Development mode behavior
+### Development mode behavior
 
 In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and falls back to the service principal.
 

packages/appkit/src/index.ts

@@ -47,6 +47,8 @@ export {
 // Plugin authoring
 export { Plugin, toPlugin } from "./plugin";
 export { analytics, lakebase, server } from "./plugins";
+export type { LakebasePluginExports } from "./plugins/lakebase";
+export type { ServerPluginExports } from "./plugins/server";
 // Registry types and utilities for plugin manifests
 export type {
   ConfigSchema,

packages/appkit/src/plugins/lakebase/lakebase.ts

@@ -11,9 +11,27 @@ import type { ILakebaseConfig } from "./types";
 
 const logger = createLogger("lakebase");
 
+/**
+ * AppKit plugin for Databricks Lakebase Autoscaling.
+ *
+ * Wraps `@databricks/lakebase` to provide a standard `pg.Pool` with automatic
+ * OAuth token refresh, integrated with AppKit's logger and OpenTelemetry setup.
+ *
+ * @example
+ * ```ts
+ * import { createApp, lakebase, server } from "@databricks/appkit";
+ *
+ * const AppKit = await createApp({
+ *   plugins: [server(), lakebase()],
+ * });
+ *
+ * const result = await AppKit.lakebase.query("SELECT * FROM users WHERE id = $1", [userId]);
+ * ```
+ */
 export class LakebasePlugin extends Plugin {
   name = "lakebase";
 
+  /** Plugin manifest declaring metadata and resource requirements */
   static manifest = lakebaseManifest;
 
   protected declare config: ILakebaseConfig;
@@ -24,11 +42,31 @@ export class LakebasePlugin extends Plugin {
     this.config = config;
   }
 
+  /**
+   * Initializes the Lakebase connection pool.
+   * Called automatically by AppKit during the plugin setup phase.
+   */
   async setup() {
     this.pool = createLakebasePool(this.config.pool);
     logger.info("Lakebase pool initialized");
   }
 
+  /**
+   * Executes a parameterized SQL query against the Lakebase pool.
+   *
+   * @param text - SQL query string, using `$1`, `$2`, ... placeholders
+   * @param values - Parameter values corresponding to placeholders
+   * @returns Query result with typed rows
+   * @throws If the pool has not been initialized (i.e. `setup()` was not called)
+   *
+   * @example
+   * ```ts
+   * const result = await AppKit.lakebase.query<{ id: number; name: string }>(
+   *   "SELECT id, name FROM users WHERE active = $1",
+   *   [true],
+   * );
+   * ```
+   */
   async query<T extends pg.QueryResultRow = any>(
     text: string,
     values?: unknown[],
@@ -39,6 +77,10 @@ export class LakebasePlugin extends Plugin {
     return this.pool.query<T>(text, values);
   }
 
+  /**
+   * Gracefully drains and closes the connection pool.
+   * Called automatically by AppKit during shutdown.
+   */
   abortActiveOperations(): void {
     super.abortActiveOperations();
     if (this.pool) {
@@ -50,6 +92,14 @@ export class LakebasePlugin extends Plugin {
     }
   }
 
+  /**
+   * Returns the plugin's public API, accessible via `AppKit.lakebase`.
+   *
+   * - `pool` — The raw `pg.Pool` instance, for use with ORMs or advanced scenarios
+   * - `query` — Convenience method for executing parameterized SQL queries
+   * - `getOrmConfig()` — Returns a config object compatible with Drizzle, TypeORM, Sequelize, etc.
+   * - `getPgConfig()` — Returns a `pg.PoolConfig` object for manual pool construction
+   */
   exports() {
     return {
       pool: this.pool!,
@@ -60,6 +110,8 @@ export class LakebasePlugin extends Plugin {
   }
 }
 
+export type LakebasePluginExports = ReturnType<LakebasePlugin["exports"]>;
+
 /**
  * @internal
  */

packages/appkit/src/plugins/lakebase/types.ts

@@ -1,6 +1,20 @@
 import type { BasePluginConfig } from "shared";
 import type { LakebasePoolConfig } from "../../connectors/lakebase";
 
+/**
+ * Configuration for the Lakebase plugin.
+ *
+ * The minimum required setup is via environment variables — no `pool` config
+ * is needed if `PGHOST`, `PGDATABASE`, and `LAKEBASE_ENDPOINT` are set.
+ *
+ * @see {@link https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md} for the full configuration reference.
+ */
 export interface ILakebaseConfig extends BasePluginConfig {
+  /**
+   * Optional overrides for the underlying `pg.Pool` configuration.
+   * All fields are optional and fall back to environment variables or defaults.
+   *
+   * Common overrides: `max` (pool size), `connectionTimeoutMillis`, `idleTimeoutMillis`.
+   */
   pool?: Partial<LakebasePoolConfig>;
 }

packages/appkit/src/plugins/server/index.ts

@@ -349,6 +349,8 @@ export class ServerPlugin extends Plugin {
   }
 }
 
+export type ServerPluginExports = ReturnType<ServerPlugin["exports"]>;
+
 const EXCLUDED_PLUGINS = [ServerPlugin.name];
 
 /**