@databricks/appkit-ui 0.21.0 → 0.23.0

package/docs/api/appkit/TypeAlias.ExecutionResult.md

@@ -0,0 +1,36 @@
+# Type Alias: ExecutionResult\<T>
+
+```ts
+type ExecutionResult<T> = 
+  | {
+  data: T;
+  ok: true;
+}
+  | {
+  message: string;
+  ok: false;
+  status: number;
+};
+
+```
+
+Discriminated union for plugin execution results.
+
+Replaces the previous `T | undefined` return type on `execute()`.
+
+On failure, the HTTP status code is preserved from:
+
+* `AppKitError` subclasses (via `statusCode`)
+* Any `Error` with a numeric `statusCode` property (e.g. `ApiError`)
+* All other errors default to status 500
+
+In production, error messages from non-AppKitError sources are handled as:
+
+* 4xx errors: original message is preserved (client-facing by design)
+* 5xx errors: replaced with "Server error" to prevent information leakage
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |

package/docs/api/appkit/TypeAlias.ServingFactory.md

@@ -0,0 +1,15 @@
+# Type Alias: ServingFactory
+
+```ts
+type ServingFactory = keyof ServingEndpointRegistry extends never ? (alias?: string) => ServingEndpointHandle : <K>(alias: K) => ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]>;
+
+```
+
+Factory function returned by `AppKit.serving`.
+
+This is a conditional type that adapts based on whether `ServingEndpointRegistry` has been populated via module augmentation (generated by `appKitServingTypesPlugin()`):
+
+* **Registry empty (default):** `(alias?: string) => ServingEndpointHandle` — accepts any alias string with untyped request/response.
+* **Registry populated:** `<K>(alias: K) => ServingEndpointHandle<...>` — restricts `alias` to known endpoint keys and infers typed request/response from the registry entry.
+
+Run `appKitServingTypesPlugin()` in your Vite config to generate the registry augmentation and enable full type safety.

package/docs/api/appkit.md

@@ -27,32 +27,37 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## Interfaces[​](#interfaces "Direct link to Interfaces")
 
-| Interface                                                                                                   | Description                                                                                                                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md)                                   | Base configuration interface for AppKit plugins                                                                                                                                                                                                               |
-| [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md)                                             | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.                                                                                                                                                |
-| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md)                               | Database credentials with OAuth token for Postgres connection                                                                                                                                                                                                 |
-| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                  |
-| [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                   |
-| [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                         |
-| [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md)                                       | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types.                                                                              |
-| [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md)                                     | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables                                                                                                               |
-| [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                          |
-| [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                |
-| [ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md)                               | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key). |
-| [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.                              |
-| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                    |
-| [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md)                                     | OpenTelemetry configuration for AppKit applications                                                                                                                                                                                                           |
-| [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                        |
+| Interface                                                                                                   | Description                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md)                                   | Base configuration interface for AppKit plugins                                                                                                                                                                                                                 |
+| [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md)                                             | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.                                                                                                                                                  |
+| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md)                               | Database credentials with OAuth token for Postgres connection                                                                                                                                                                                                   |
+| [EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md)                                       | -                                                                                                                                                                                                                                                               |
+| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                    |
+| [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                     |
+| [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                           |
+| [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md)                                       | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types.                                                                                |
+| [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md)                                     | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables                                                                                                                 |
+| [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                            |
+| [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                  |
+| [ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md)                               | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key).   |
+| [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.                                |
+| [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md)                           | Shape of a single registry entry.                                                                                                                                                                                                                               |
+| [ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md)                     | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint. |
+| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                      |
+| [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md)                                     | OpenTelemetry configuration for AppKit applications                                                                                                                                                                                                             |
+| [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                          |
 
 ## Type Aliases[​](#type-aliases "Direct link to Type Aliases")
 
 | Type Alias                                                                    | Description                                                                                                 |
 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md)             | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
+| [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md)       | Discriminated union for plugin execution results.                                                           |
 | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                 | Express router type for plugin route registration                                                           |
 | [PluginData](./docs/api/appkit/TypeAlias.PluginData.md)                 | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.               |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types.                                          |
+| [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)         | Factory function returned by `AppKit.serving`.                                                              |
 | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md)                     | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple.     |
 
 ## Variables[​](#variables "Direct link to Variables")
@@ -63,17 +68,20 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## Functions[​](#functions "Direct link to Functions")
 
-| Function                                                                                     | Description                                                                                                                                     |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                  |
-| [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                              |
-| [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry. |
-| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                      |
-| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                              |
-| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                              |
-| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                   |
-| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.        |
-| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                        |
-| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                     |
-| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                      |
-| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                             |
+| Function                                                                                     | Description                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [appKitServingTypesPlugin](./docs/api/appkit/Function.appKitServingTypesPlugin.md)     | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.                                        |
+| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                                                                                                |
+| [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                                                                                                            |
+| [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.                                                                               |
+| [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md)       | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings. |
+| [findServerFile](./docs/api/appkit/Function.findServerFile.md)                         | Find the server entry file by checking candidate paths in order.                                                                                                                                                              |
+| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                                                                                                    |
+| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                                                                                                            |
+| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                                                                                                            |
+| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                                                                                                 |
+| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.                                                                                      |
+| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                                                                                                      |
+| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                                                                                                   |
+| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                                                                                                    |
+| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                                                                                                           |

package/docs/app-management.md

@@ -5,7 +5,7 @@ Manage your AppKit application throughout its lifecycle using the Databricks CLI
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
 ## Create app[​](#create-app "Direct link to Create app")
 

package/docs/architecture.md

@@ -59,7 +59,7 @@ The Node.js backend layer built with `@databricks/appkit`:
 Integration with Databricks services:
 
 * **SQL Warehouses**: Execute analytical queries with Arrow or JSON format
-* **Lakebase V1 (Provisioned)**: Access data from Lakebase Provisioned. Support for Lakebase Autoscaling coming soon.
+* **Lakebase Autoscaling**: OLTP database access with automatic OAuth token refresh
 
 ## See also[​](#see-also "Direct link to See also")
 

package/docs/development/ai-assisted-development.md

@@ -3,7 +3,7 @@
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 AppKit integrates with AI coding assistants through the Agent Skills.
@@ -13,7 +13,7 @@ AppKit integrates with AI coding assistants through the Agent Skills.
 To install the Databricks Agent Skills for your preferred AI assistant, run:
 
 ```bash
-databricks experimental aitools skills install
+databricks experimental aitools install
 
 ```
 

package/docs/development/local-development.md

@@ -3,7 +3,7 @@
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 Once your app is bootstrapped according to the [Manual quick start](./docs.md#manual-quick-start) guide, you can start the development server with hot reload for both UI and backend code.

package/docs/development/remote-bridge.md

@@ -3,7 +3,7 @@
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.

package/docs/development/templates.md

@@ -0,0 +1,93 @@
+# Templates
+
+AppKit uses a template system powered by the Databricks CLI's `databricks apps init` command. Templates define the project structure, and `.tmpl` files are processed with Go's `text/template` engine to generate customized output.
+
+## How `.tmpl` files work[​](#how-tmpl-files-work "Direct link to how-tmpl-files-work")
+
+Any file ending in `.tmpl` is processed by the CLI during `databricks apps init`:
+
+1. The `.tmpl` suffix is stripped (e.g. `.env.tmpl` → `.env`)
+2. Go template expressions are evaluated and substituted
+3. The rendered file is written to the output directory
+
+Files named with a `_` prefix are renamed to `.` prefix (e.g. `_gitignore` → `.gitignore`).
+
+### Template variables[​](#template-variables "Direct link to Template variables")
+
+| Variable          | Description                                                                  |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `.projectName`    | Project name from `--name` or interactive prompt                             |
+| `.workspaceHost`  | Databricks workspace URL                                                     |
+| `.profile`        | Databricks CLI profile name (empty if using host-based auth)                 |
+| `.appDescription` | App description                                                              |
+| `.plugins.<name>` | Non-nil for each selected plugin, enabling conditionals                      |
+| `.dotEnv.content` | Generated `.env` content from plugin resources                               |
+| `.dotEnv.example` | Generated `.env.example` content with placeholders                           |
+| `.bundle.*`       | Generated `databricks.yml` sections (variables, resources, target variables) |
+| `.appEnv`         | Generated `app.yaml` env entries                                             |
+
+### Conditional content[​](#conditional-content "Direct link to Conditional content")
+
+Use Go template conditionals to include/exclude code based on selected plugins:
+
+```go
+{{- if .plugins.analytics}}
+import { analytics } from '@databricks/appkit';
+{{- end}}
+
+```
+
+## `appkit.plugins.json`[​](#appkitpluginsjson "Direct link to appkitpluginsjson")
+
+The plugin manifest drives the CLI's behavior during `databricks apps init`:
+
+* **Plugin selection UI** — selectable plugins shown in the interactive prompt
+* **Resource prompts** — required/optional resources prompt the user for values (e.g. SQL Warehouse ID)
+* **`.dotEnv` population** — resource fields with an `env` property are written to `.env`
+* **`app.yaml` generation** — resource fields produce `env` + `valueFrom` entries
+* **`databricks.yml` generation** — resource fields produce bundle variables and app resource entries
+
+### Resource field properties[​](#resource-field-properties "Direct link to Resource field properties")
+
+Each resource field in the manifest can have these properties:
+
+| Property       | Description                                                                         |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `env`          | Environment variable name written to `.env` and `app.yaml`                          |
+| `description`  | Shown in the interactive prompt and bundle variable description                     |
+| `localOnly`    | Only written to `.env` for local dev; excluded from `app.yaml` and bundle variables |
+| `bundleIgnore` | Excluded from `databricks.yml` variables (but still in `.env`)                      |
+| `value`        | Default value used when no user input is provided                                   |
+| `resolve`      | Auto-populated by CLI from API calls instead of prompting (see below)               |
+| `examples`     | Example values shown in field descriptions                                          |
+
+### Resolvers[​](#resolvers "Direct link to Resolvers")
+
+Fields with a `resolve` property are auto-populated by the CLI from API calls rather than user prompts. The format is `<type>:<field>`.
+
+Currently only the `postgres` resource type has a resolver. Given the user-provided `branch` and `database` resource names, it derives:
+
+| Resolve key             | Description                                                 |
+| ----------------------- | ----------------------------------------------------------- |
+| `postgres:host`         | Postgres host from the branch's read-write endpoint         |
+| `postgres:databaseName` | Postgres database name from the database resource           |
+| `postgres:endpointPath` | Lakebase endpoint resource name from the branch's endpoints |
+
+Example field definition:
+
+```json
+{
+  "host": {
+    "env": "PGHOST",
+    "localOnly": true,
+    "resolve": "postgres:host",
+    "description": "Postgres host for local development."
+  }
+}
+
+```
+
+## See also[​](#see-also "Direct link to See also")
+
+* [Plugin management](./docs/plugins/plugin-management.md) — `appkit plugin sync`, `appkit plugin create`
+* [Configuration](./docs/configuration.md) — environment variables

package/docs/development.md

@@ -5,7 +5,7 @@ AppKit provides multiple development workflows to suit different needs: local de
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 ## Development flows[​](#development-flows "Direct link to Development flows")

package/docs/faq.md

@@ -0,0 +1,66 @@
+# FAQ
+
+## Integrations[​](#integrations "Direct link to Integrations")
+
+### What Databricks services are available through AppKit?[​](#what-databricks-services-are-available-through-appkit "Direct link to What Databricks services are available through AppKit?")
+
+AppKit provides built-in integrations with the following Databricks services via its [plugin system](./docs/plugins.md):
+
+| Plugin                                         | Databricks Service                | What It Does                                                                            |
+| ---------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
+| [Analytics](./docs/plugins/analytics.md) | SQL Warehouses                    | Execute parameterized SQL queries with built-in caching, retry, and Arrow support       |
+| [Lakebase](./docs/plugins/lakebase.md)   | Lakebase Autoscaling (PostgreSQL) | Relational database access via standard pg.Pool with automatic OAuth token refresh      |
+| [Genie](./docs/plugins/genie.md)         | AI/BI Genie Spaces                | Natural language data queries with conversation management and streaming                |
+| [Files](./docs/plugins/files.md)         | Unity Catalog Volumes             | Multi-volume file operations (list, read, upload, download, delete, preview)            |
+| [Serving](./docs/plugins/serving.md)     | Model Serving                     | Authenticated proxy to Model Serving endpoints with invoke and streaming support        |
+| [Server](./docs/plugins/server.md)       | N/A                               | Express HTTP server with static file serving, Vite dev mode, and plugin route injection |
+
+Stay tuned for new plugins as we constantly expand integrations!
+
+### Can I add custom integrations?[​](#can-i-add-custom-integrations "Direct link to Can I add custom integrations?")
+
+Yes. AppKit's plugin architecture is extensible - you can create custom plugins using the CLI (`npx appkit plugin create`) or manually. See the [creating custom plugins guide](./docs/plugins/custom-plugins.md).
+
+## Authentication[​](#authentication "Direct link to Authentication")
+
+### How does authentication work in AppKit apps?[​](#how-does-authentication-work-in-appkit-apps "Direct link to How does authentication work in AppKit apps?")
+
+AppKit apps are designed to run on [Databricks Apps](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/), which handles user authentication and authorization. Databricks Apps forwards user identity to the app via request headers, and AppKit integrates with this through the `.asUser(req)` pattern for on-behalf-of (OBO) execution — allowing plugins to act on behalf of the authenticated user.
+
+For details on how authentication and authorization work in Databricks Apps, see the [official auth documentation](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/auth).
+
+## Databases[​](#databases "Direct link to Databases")
+
+*Also: Lakebase, PostgreSQL, OLTP*
+
+### How does AppKit handle databases?[​](#how-does-appkit-handle-databases "Direct link to How does AppKit handle databases?")
+
+AppKit is a TypeScript SDK (Express + React) and does not manage databases directly.
+
+To add database support, use the [Lakebase plugin](./docs/plugins/lakebase.md), which integrates with Lakebase Autoscaling.
+
+AppKit also uses Lakebase for caching when it is available (see the [caching](#does-appkit-support-caching) section below).
+
+You can manage Lakebase Autoscaling projects and branches using the dedicated agent skill from [Databricks Agent Skills](./docs/development/ai-assisted-development.md), installed with the Databricks CLI.
+
+### How does database setup and permission management work in AppKit?[​](#how-does-database-setup-and-permission-management-work-in-appkit "Direct link to How does database setup and permission management work in AppKit?")
+
+AppKit apps can have an attached Lakebase Autoscaling instance. No database is bundled by default - you add one by configuring the [Lakebase plugin](./docs/plugins/lakebase.md). When running `databricks apps init` and selecting the Lakebase plugin, the selected database is automatically attached as an app resource after deployment.
+
+With [AI-assisted development](./docs/development/ai-assisted-development.md), you can also ask the Agent to create a Lakebase project and branch for you.
+
+When deployed, a Databricks app uses its Service Principal for schema and table creation. If you configure the Lakebase Autoscaling project as an [app resource](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/resources), the necessary connect and create permissions are granted automatically to the app's Service Principal.
+
+### Does AppKit support Lakebase Provisioned?[​](#does-appkit-support-lakebase-provisioned "Direct link to Does AppKit support Lakebase Provisioned?")
+
+No. AppKit only supports Lakebase Autoscaling. Lakebase Provisioned databases are not supported by the [Lakebase plugin](./docs/plugins/lakebase.md) or Lakebase agent skill from [Databricks Agent Skills](./docs/development/ai-assisted-development.md).
+
+## Caching[​](#caching "Direct link to Caching")
+
+### Does AppKit support caching?[​](#does-appkit-support-caching "Direct link to Does AppKit support caching?")
+
+Yes. The [Analytics plugin](./docs/plugins/analytics.md) - used for executing SQL queries against Databricks SQL Warehouses - supports an optional cache layer.
+
+Caching is configured per plugin and can use either [Lakebase Autoscaling](https://docs.databricks.com/aws/en/oltp/) or an in-memory store, depending on the configuration.
+
+If the Lakebase Autoscaling connection is configured, the AppKit-based app creates an `appkit` schema in the configured database with internal tables required for caching.

package/docs/plugins/caching.md

@@ -16,7 +16,9 @@ await createApp({
 
 ```
 
-Storage auto-selects **Lakebase V1 (Provisioned) persistent cache when healthy**, otherwise falls back to in-memory. Support for Lakebase Autoscaling coming soon.
+Storage auto-selects **Lakebase Autoscaling persistent cache when healthy**, otherwise falls back to in-memory.
+
+The database-backed cache requires the same Lakebase environment variables as the [Lakebase plugin](./docs/plugins/lakebase.md#environment-variables) (`PGHOST`, `PGDATABASE`, `LAKEBASE_ENDPOINT`, `PGSSLMODE`).
 
 ## Plugin-level caching[​](#plugin-level-caching "Direct link to Plugin-level caching")
 

package/docs/plugins/execution-context.md

@@ -42,4 +42,4 @@ Exported from `@databricks/appkit`:
 
 ## Development mode behavior[​](#development-mode-behavior "Direct link to 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.
+In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and skips user impersonation — the operation runs with the default credentials configured for the app instead.

package/docs/plugins/lakebase.md

@@ -17,7 +17,7 @@ The easiest way to get started with the Lakebase plugin is to use the Databricks
 ### Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 ### Steps[​](#steps "Direct link to Steps")