@databricks/appkit-ui 0.11.2 → 0.12.1

package/docs/api/appkit.md

@@ -0,0 +1,78 @@
+# @databricks/appkit
+
+Core library for building Databricks applications with type-safe SQL queries, plugin architecture, and React integration.
+
+## Enumerations[​](#enumerations "Direct link to Enumerations")
+
+| Enumeration                                                                                         | Description                                        |
+| --------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| [RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md) | Permission set for Unity Catalog table access      |
+| [ResourceType](./docs/api/appkit/Enumeration.ResourceType.md)                                 | Resource types from schema $defs.resourceType.enum |
+
+## Classes[​](#classes "Direct link to Classes")
+
+| Class                                                                       | Description                                                                                                                                    |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [AppKitError](./docs/api/appkit/Class.AppKitError.md)                 | Base error class for all AppKit errors. Provides a consistent structure for error handling across the framework.                               |
+| [AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md) | Error thrown when authentication fails. Use for missing tokens, invalid credentials, or authorization failures.                                |
+| [ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md)   | Error thrown when configuration is missing or invalid. Use for missing environment variables, invalid settings, or setup issues.               |
+| [ConnectionError](./docs/api/appkit/Class.ConnectionError.md)         | Error thrown when a connection or network operation fails. Use for database pool errors, API failures, timeouts, etc.                          |
+| [ExecutionError](./docs/api/appkit/Class.ExecutionError.md)           | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states.                         |
+| [InitializationError](./docs/api/appkit/Class.InitializationError.md) | Error thrown when a service or component is not properly initialized. Use when accessing services before they are ready.                       |
+| [Plugin](./docs/api/appkit/Class.Plugin.md)                           | Base abstract class for creating AppKit plugins.                                                                                               |
+| [ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md)       | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only. |
+| [ServerError](./docs/api/appkit/Class.ServerError.md)                 | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc.                            |
+| [TunnelError](./docs/api/appkit/Class.TunnelError.md)                 | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc.                              |
+| [ValidationError](./docs/api/appkit/Class.ValidationError.md)         | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches.                             |
+
+## 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 caching                                                                                                                                                                                                                                     |
+| [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.                                                                                                                                            |
+| [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().                                                                                                                           |
+| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Configuration for streaming execution with default and user-scoped settings                                                                                                                                                                                   |
+| [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. |
+| [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                 | Express router type for plugin route registration                                                           |
+| [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types.                                          |
+| [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md)                     | -                                                                                                           |
+
+## Variables[​](#variables "Direct link to Variables")
+
+| Variable                                       | Description          |
+| ---------------------------------------------- | -------------------- |
+| [sql](./docs/api/appkit/Variable.sql.md) | SQL helper namespace |
+
+## 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                                                                                             |

package/docs/{docs/api.md → api.md}

@@ -4,14 +4,14 @@ This section contains the API reference for the AppKit packages.
 
 ## Modules[​](#modules "Direct link to Modules")
 
-* [`appkit`](/appkit/docs/api/appkit.md) - Core library. Provides the core functionality for building Databricks applications.
-* [`appkit-ui`](/appkit/docs/api/appkit-ui.md) - UI components library. Provides a set of UI primitives for building Databricks apps in [React](https://react.dev/).
+* [`appkit`](./docs/api/appkit.md) - Core library. Provides the core functionality for building Databricks applications.
+* [`appkit-ui`](./docs/api/appkit-ui.md) - UI components library. Provides a set of UI primitives for building Databricks apps in [React](https://react.dev/).
 
-Learn more about the architecture of AppKit in the [architecture](/appkit/docs/architecture.md) document.
+Learn more about the architecture of AppKit in the [architecture](./docs/architecture.md) document.
 
 ## Getting started[​](#getting-started "Direct link to Getting started")
 
-To learn how to get started with AppKit, see the [getting started guide](/appkit/docs.md) for AI-assisted and manual quick start options.
+To learn how to get started with AppKit, see the [getting started guide](./docs.md) for AI-assisted and manual quick start options.
 
 ## Installation[​](#installation "Direct link to Installation")
 

package/docs/{docs/app-management.md → app-management.md}

@@ -9,11 +9,11 @@ Manage your AppKit application throughout its lifecycle using the Databricks CLI
 
 ## Create app[​](#create-app "Direct link to Create app")
 
-See the [Quick start](/appkit/docs.md#quick-start) section to create a new Databricks app with AppKit installed.
+See the [Quick start](./docs.md#quick-start) section to create a new Databricks app with AppKit installed.
 
 ## Configuration[​](#configuration "Direct link to Configuration")
 
-Before deploying your app, you need to configure it. See the [Configuration guide](/appkit/docs/configuration.md) for details on:
+Before deploying your app, you need to configure it. See the [Configuration guide](./docs/configuration.md) for details on:
 
 * `app.yaml` configuration and command specification
 * Environment variables and SQL warehouse binding

package/docs/{docs/architecture.md → architecture.md}

@@ -20,7 +20,7 @@ The backend SDK that provides the plugin architecture and core functionality. It
 * Cache management and streaming capabilities
 * Type generation for SQL queries
 
-See the [Plugins](/appkit/docs/plugins.md) and [API reference](/appkit/docs/api/appkit.md) documentation for detailed information.
+See the [Plugins](./docs/plugins.md) and [API reference](./docs/api/appkit.md) documentation for detailed information.
 
 ### @databricks/appkit-ui[​](#databricksappkit-ui "Direct link to @databricks/appkit-ui")
 
@@ -31,7 +31,7 @@ A React UI library with pre-built components optimized for data applications:
 * Data visualization components
 * Type-safe integration with backend queries
 
-See the [API reference](/appkit/docs/api/appkit-ui.md) for component documentation.
+See the [API reference](./docs/api/appkit-ui.md) for component documentation.
 
 ## Application layers[​](#application-layers "Direct link to Application layers")
 
@@ -63,7 +63,7 @@ Integration with Databricks services:
 
 ## See also[​](#see-also "Direct link to See also")
 
-* [Plugins](/appkit/docs/plugins.md): Deep dive into the plugin system
-* [API reference](/appkit/docs/api.md): Complete API documentation
-* [Development](/appkit/docs/development.md): Explore development workflows
-* [Core Principles](/appkit/docs/core-principles.md): Learn about AppKit's design philosophy
+* [Plugins](./docs/plugins.md): Deep dive into the plugin system
+* [API reference](./docs/api.md): Complete API documentation
+* [Development](./docs/development.md): Explore development workflows
+* [Core Principles](./docs/core-principles.md): Learn about AppKit's design philosophy

package/docs/{docs/configuration.md → configuration.md}

@@ -146,5 +146,5 @@ For advanced Databricks Apps configuration (authorization, networking, resource
 
 ## See also[​](#see-also "Direct link to See also")
 
-* [App management](/appkit/docs/app-management.md) - Deploying and managing apps
-* [Plugins](/appkit/docs/plugins.md) - Plugin configuration options
+* [App management](./docs/app-management.md) - Deploying and managing apps
+* [Plugins](./docs/plugins.md) - Plugin configuration options

package/docs/{docs/development → development}/ai-assisted-development.md

@@ -4,7 +4,7 @@
 
 * [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).
-* A new Databricks app with AppKit installed. See the [Quick start](/appkit/docs.md#quick-start) for more details.
+* A new Databricks app with AppKit installed. See the [Quick start](./docs.md#quick-start) for more details.
 
 AppKit-specific agent skills for AI coding assistants are coming soon. This documentation will be updated with instructions when available.
 
@@ -20,7 +20,9 @@ If you're building applications using AppKit packages, reference the `llms.txt`
 2. Use the `npx @databricks/appkit docs` command to view the documentation in the terminal.
 
 ```bash
-npx @databricks/appkit docs # returns the llms.txt file content with all available documentation pages
-npx @databricks/appkit docs <path> # for specific documentation file
+npx @databricks/appkit docs            # documentation index with section overview
+npx @databricks/appkit docs "appkit-ui API reference"  # view a specific section
+npx @databricks/appkit docs --full     # full index with all API entries
+npx @databricks/appkit docs ./docs.md  # view a specific documentation file
 
 ```

package/docs/{docs/development → development}/llm-guide.md

@@ -46,17 +46,18 @@ View API reference (docs only, NOT for scaffolding):
 
 ```bash
 # ONLY for viewing documentation - do NOT use for init/scaffold
-npx @databricks/appkit docs <path>
+npx @databricks/appkit docs <query>
 
 ```
 
-**IMPORTANT**: ALWAYS run `npx @databricks/appkit docs` (no path) FIRST to see available pages. DO NOT guess paths - use the index to find correct paths.
+**IMPORTANT**: ALWAYS run `npx @databricks/appkit docs` (no query) FIRST to see the documentation index. DO NOT guess paths - use the index to find correct paths.
 
-Examples of known paths:
+Examples:
 
-* Root index: `npx @databricks/appkit docs`
-* API reference: `npx @databricks/appkit docs ./docs/docs/api.md`
-* Component docs: `npx @databricks/appkit docs ./docs/docs/api/appkit-ui/components/Sidebar.md`
+* Documentation index: `npx @databricks/appkit docs`
+* View a section: `npx @databricks/appkit docs "appkit-ui API reference"`
+* Full index (all API entries): `npx @databricks/appkit docs --full`
+* View specific doc: `npx @databricks/appkit docs ./docs/plugins/analytics.md`
 
 ## LLM checklist (before finalizing code)[​](#llm-checklist-before-finalizing-code "Direct link to LLM checklist (before finalizing code)")
 

package/docs/{docs/development → development}/local-development.md

@@ -4,9 +4,9 @@
 
 * [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).
-* A new Databricks app with AppKit installed. See the [Quick start](/appkit/docs.md#quick-start) for more details.
+* A new Databricks app with AppKit installed. See the [Quick start](./docs.md#quick-start) for more details.
 
-Once your app is bootstrapped according to the [Quick start](/appkit/docs.md#quick-start) guide, you can start the development server with hot reload for both UI and backend code.
+Once your app is bootstrapped according to the [Quick start](./docs.md#quick-start) guide, you can start the development server with hot reload for both UI and backend code.
 
 In the application root directory, run the following command to start the development server:
 

package/docs/{docs/development → development}/project-setup.md

@@ -241,6 +241,6 @@ Then create `config/queries/` and add your `.sql` files.
 
 ## See also[​](#see-also "Direct link to See also")
 
-* [Local development](/appkit/docs/development/local-development.md) - Running the dev server
-* [Configuration](/appkit/docs/configuration.md) - Environment variables
-* [Plugins](/appkit/docs/plugins.md) - Plugin configuration
+* [Local development](./docs/development/local-development.md) - Running the dev server
+* [Configuration](./docs/configuration.md) - Environment variables
+* [Plugins](./docs/plugins.md) - Plugin configuration

package/docs/{docs/development → development}/remote-bridge.md

@@ -4,7 +4,7 @@
 
 * [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).
-* A new Databricks app with AppKit installed. See the [Quick start](/appkit/docs.md#quick-start) for more details.
+* A new Databricks app with AppKit installed. See the [Quick start](./docs.md#quick-start) 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/{docs/development → development}/type-generation.md

@@ -106,5 +106,5 @@ data?.forEach(row => {
 
 ## See also[​](#see-also "Direct link to See also")
 
-* [Plugins](/appkit/docs/plugins.md) - Analytics plugin configuration
-* [API Reference](/appkit/docs/api/appkit-ui.md) - Complete UI components API documentation
+* [Plugins](./docs/plugins.md) - Analytics plugin configuration
+* [API Reference](./docs/api/appkit-ui.md) - Complete UI components API documentation

package/docs/development.md

@@ -0,0 +1,22 @@
+# Development
+
+AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with MCP, and remote tunneling to deployed backends.
+
+## 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).
+* A new Databricks app with AppKit installed. See the [Quick start](./docs.md#quick-start) for more details.
+
+## Development flows[​](#development-flows "Direct link to Development flows")
+
+There are multiple supported development flows available with AppKit:
+
+1. **[Local development](./docs/development/local-development.md)**: Run the development server with hot reload for both UI and backend code. This is the default development flow and is suitable for most use cases.
+2. **[AI-assisted development](./docs/development/ai-assisted-development.md)**: Use an AI coding assistant to explore data, run CLI commands, and scaffold your app interactively.
+3. **[Remote Bridge](./docs/development/remote-bridge.md)**: Create a remote bridge to a deployed backend while keeping your queries and UI local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
+
+## See also[​](#see-also "Direct link to See also")
+
+* [App management](./docs/app-management.md): Manage your AppKit application throughout its lifecycle using the Databricks CLI
+* [Architecture](./docs/architecture.md): Learn about the architecture of AppKit

package/docs/{docs/plugins → plugins}/analytics.md

@@ -5,7 +5,7 @@ Enables SQL query execution against Databricks SQL Warehouses.
 **Key features:**
 
 * File-based SQL queries with automatic type generation
-* Parameterized queries with type-safe [SQL helpers](/appkit/docs/api/appkit/Variable.sql.md)
+* Parameterized queries with type-safe [SQL helpers](./docs/api/appkit/Variable.sql.md)
 * JSON and Arrow format support
 * Built-in caching and retry logic
 * Server-Sent Events (SSE) streaming

package/docs/{docs/plugins → plugins}/custom-plugins.md

@@ -11,7 +11,7 @@ For a deeper understanding of the plugin structure, read on.
 
 ## Basic plugin example[​](#basic-plugin-example "Direct link to Basic plugin example")
 
-Extend the [`Plugin`](/appkit/docs/api/appkit/Class.Plugin.md) class and export with `toPlugin()`:
+Extend the [`Plugin`](./docs/api/appkit/Class.Plugin.md) class and export with `toPlugin()`:
 
 ```typescript
 import { Plugin, toPlugin } from "@databricks/appkit";
@@ -128,7 +128,7 @@ This pattern allows:
 
 ## Key extension points[​](#key-extension-points "Direct link to Key extension points")
 
-* **Route injection**: Implement `injectRoutes()` to add custom endpoints using [`IAppRouter`](/appkit/docs/api/appkit/TypeAlias.IAppRouter.md)
+* **Route injection**: Implement `injectRoutes()` to add custom endpoints using [`IAppRouter`](./docs/api/appkit/TypeAlias.IAppRouter.md)
 
 * **Lifecycle hooks**: Override `setup()`, and `shutdown()` methods
 
@@ -136,10 +136,10 @@ This pattern allows:
 
   <!-- -->
 
-  * **Cache management**: Access the cache service via `this.cache`. See [`CacheConfig`](/appkit/docs/api/appkit/Interface.CacheConfig.md) for configuration.
-  * **Telemetry**: Instrument your plugin with traces and metrics via `this.telemetry`. See [`ITelemetry`](/appkit/docs/api/appkit/Interface.ITelemetry.md).
+  * **Cache management**: Access the cache service via `this.cache`. See [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md) for configuration.
+  * **Telemetry**: Instrument your plugin with traces and metrics via `this.telemetry`. See [`ITelemetry`](./docs/api/appkit/Interface.ITelemetry.md).
 
-* **Execution interceptors**: Use `execute()` and `executeStream()` with [`StreamExecutionSettings`](/appkit/docs/api/appkit/Interface.StreamExecutionSettings.md)
+* **Execution interceptors**: Use `execute()` and `executeStream()` with [`StreamExecutionSettings`](./docs/api/appkit/Interface.StreamExecutionSettings.md)
 
 **Consuming your plugin programmatically**
 
@@ -158,4 +158,4 @@ AppKit.myPlugin.myCustomMethod();
 
 ```
 
-See the [`Plugin`](/appkit/docs/api/appkit/Class.Plugin.md) API reference for complete documentation.
+See the [`Plugin`](./docs/api/appkit/Class.Plugin.md) API reference for complete documentation.

package/docs/{docs/plugins → plugins}/lakebase.md

@@ -58,33 +58,34 @@ Click the **Connect** button on your Lakebase branch and copy the `PGHOST` and `
 
 ### 5. Grant access to the service principal[​](#5-grant-access-to-the-service-principal "Direct link to 5. Grant access to the service principal")
 
-Navigate to the **SQL Editor** tab on your Lakebase branch. Run the following SQL against the `databricks_postgres` database, replacing `<DATABRICKS_CLIENT_ID>` with the value from step 1 everywhere it appears:
+Navigate to the **SQL Editor** tab on your Lakebase branch. Run the following SQL against the `databricks_postgres` database, replacing the service principal ID in the `DECLARE` block with the `DATABRICKS_CLIENT_ID` value from step 1:
 
 ```sql
--- 1. Create the extension and role
 CREATE EXTENSION IF NOT EXISTS databricks_auth;
-SELECT databricks_create_role('<DATABRICKS_CLIENT_ID>', 'SERVICE_PRINCIPAL');
-
--- 2. Basic connection & usage
-GRANT CONNECT ON DATABASE "databricks_postgres" TO "<DATABRICKS_CLIENT_ID>";
-GRANT ALL ON SCHEMA public TO "<DATABRICKS_CLIENT_ID>";
-
--- 3. Grant on existing objects
-GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO "<DATABRICKS_CLIENT_ID>";
-GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO "<DATABRICKS_CLIENT_ID>";
-GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO "<DATABRICKS_CLIENT_ID>";
-GRANT ALL PRIVILEGES ON ALL PROCEDURES IN SCHEMA public TO "<DATABRICKS_CLIENT_ID>";
-
--- 4. Grant on future objects
--- NOTE: This applies to objects created by the user running this script.
-ALTER DEFAULT PRIVILEGES IN SCHEMA public
-  GRANT ALL ON TABLES TO "<DATABRICKS_CLIENT_ID>";
-ALTER DEFAULT PRIVILEGES IN SCHEMA public
-  GRANT ALL ON SEQUENCES TO "<DATABRICKS_CLIENT_ID>";
-ALTER DEFAULT PRIVILEGES IN SCHEMA public
-  GRANT ALL ON FUNCTIONS TO "<DATABRICKS_CLIENT_ID>";
-ALTER DEFAULT PRIVILEGES IN SCHEMA public
-  GRANT ALL ON ROUTINES TO "<DATABRICKS_CLIENT_ID>";
+
+DO $$
+DECLARE
+  sp TEXT := 'your-service-principal-id';  -- Replace with DATABRICKS_CLIENT_ID from Step 1
+BEGIN
+  -- Create service principal role
+  PERFORM databricks_create_role(sp, 'SERVICE_PRINCIPAL');
+
+  -- Connection and schema access
+  EXECUTE format('GRANT CONNECT ON DATABASE "databricks_postgres" TO %I', sp);
+  EXECUTE format('GRANT ALL ON SCHEMA public TO %I', sp);
+
+  -- Privileges on existing objects
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO %I', sp);
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO %I', sp);
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO %I', sp);
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL PROCEDURES IN SCHEMA public TO %I', sp);
+
+  -- Default privileges on future objects you create
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO %I', sp);
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO %I', sp);
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON FUNCTIONS TO %I', sp);
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON ROUTINES TO %I', sp);
+END $$;
 
 ```
 

package/docs/{docs/plugins.md → plugins.md}

@@ -2,7 +2,7 @@
 
 Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming.
 
-For complete API documentation, see the [`Plugin`](/appkit/docs/api/appkit/Class.Plugin.md) class reference.
+For complete API documentation, see the [`Plugin`](./docs/api/appkit/Class.Plugin.md) class reference.
 
 ## Using plugins[​](#using-plugins "Direct link to Using plugins")
 
@@ -20,7 +20,7 @@ const AppKit = await createApp({
 
 ```
 
-For complete configuration options, see [`createApp`](/appkit/docs/api/appkit/Function.createApp.md).
+For complete configuration options, see [`createApp`](./docs/api/appkit/Function.createApp.md).
 
 ## Plugin phases[​](#plugin-phases "Direct link to Plugin phases")
 

package/{docs/docs.md → docs.md}

@@ -44,7 +44,7 @@ The command will guide you through the process of:
 * (optionally) deploying the app to Databricks
 * (optionally) running the app in development mode
 
-Learn more about the various [development flows](/appkit/docs/development.md) available with AppKit.
+Learn more about the various [development flows](./docs/development.md) available with AppKit.
 
 ### Deploy the app to Databricks[​](#deploy-the-app-to-databricks "Direct link to Deploy the app to Databricks")
 
@@ -59,6 +59,6 @@ This deploys the sample app to Databricks.
 
 ## Next steps[​](#next-steps "Direct link to Next steps")
 
-* **[App management](/appkit/docs/app-management.md)**: Manage your AppKit application throughout its lifecycle using the Databricks CLI
-* **[API reference](/appkit/docs/api/appkit.md)**: Explore the complete API documentation
-* **[Core concepts](/appkit/docs/core-principles.md)**: Learn about AppKit's design principles and architecture
+* **[App management](./docs/app-management.md)**: Manage your AppKit application throughout its lifecycle using the Databricks CLI
+* **[API reference](./docs/api/appkit.md)**: Explore the complete API documentation
+* **[Core concepts](./docs/core-principles.md)**: Learn about AppKit's design principles and architecture