@databricks/appkit 0.23.0 → 0.25.0

package/docs/api/appkit/Interface.FileResource.md

@@ -0,0 +1,36 @@
+# Interface: FileResource
+
+Describes the file or directory being acted upon.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### path[​](#path "Direct link to path")
+
+```ts
+path: string;
+
+```
+
+Relative path within the volume.
+
+***
+
+### size?[​](#size "Direct link to size?")
+
+```ts
+optional size: number;
+
+```
+
+Content length in bytes — only present for uploads.
+
+***
+
+### volume[​](#volume "Direct link to volume")
+
+```ts
+volume: string;
+
+```
+
+The volume key (e.g. `"uploads"`).

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

@@ -0,0 +1,18 @@
+# Type Alias: FileAction
+
+```ts
+type FileAction = 
+  | "list"
+  | "read"
+  | "download"
+  | "raw"
+  | "exists"
+  | "metadata"
+  | "preview"
+  | "upload"
+  | "mkdir"
+  | "delete";
+
+```
+
+Every action the files plugin can perform.

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

@@ -0,0 +1,20 @@
+# Type Alias: FilePolicy()
+
+```ts
+type FilePolicy = (action: FileAction, resource: FileResource, user: FilePolicyUser) => boolean | Promise<boolean>;
+
+```
+
+A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                                                                    |
+| ---------- | ----------------------------------------------------------------------- |
+| `action`   | [`FileAction`](./docs/api/appkit/TypeAlias.FileAction.md)         |
+| `resource` | [`FileResource`](./docs/api/appkit/Interface.FileResource.md)     |
+| `user`     | [`FilePolicyUser`](./docs/api/appkit/Interface.FilePolicyUser.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`boolean` | `Promise`<`boolean`>

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

@@ -1,15 +1,19 @@
 # Type Alias: ServingFactory
 
 ```ts
-type ServingFactory = keyof ServingEndpointRegistry extends never ? (alias?: string) => ServingEndpointHandle : <K>(alias: K) => ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]>;
+type ServingFactory = keyof ServingEndpointRegistry extends never ? (alias?: string) => ServingEndpointHandle : true extends IsUnion<keyof ServingEndpointRegistry> ? <K>(alias: K) => ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]> : {
+<K>  (alias: K): ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]>;
+  (): ServingEndpointHandle<never, never>;
+};
 
 ```
 
 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()`):
+Adapts based on the `ServingEndpointRegistry` state:
 
-* **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.
+* **Empty (default):** `(alias?: string) => ServingEndpointHandle` — any string, untyped.
+* **Single key:** alias optional — `serving()` returns the typed handle for the only endpoint.
+* **Multiple keys:** alias required — must specify which endpoint.
 
-Run `appKitServingTypesPlugin()` in your Vite config to generate the registry augmentation and enable full type safety.
+Run `npx appkit generate-types` or start the dev server to generate the registry.

package/docs/api/appkit/Variable.READ_ACTIONS.md

@@ -0,0 +1,8 @@
+# Variable: READ\_ACTIONS
+
+```ts
+const READ_ACTIONS: ReadonlySet<FileAction>;
+
+```
+
+Actions that only read data.

package/docs/api/appkit/Variable.WRITE_ACTIONS.md

@@ -0,0 +1,8 @@
+# Variable: WRITE\_ACTIONS
+
+```ts
+const WRITE_ACTIONS: ReadonlySet<FileAction>;
+
+```
+
+Actions that mutate data.

package/docs/api/appkit.md

@@ -20,6 +20,7 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 | [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.                                                                                               |
+| [PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md)     | Thrown when a policy denies an action.                                                                                                         |
 | [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.                              |
@@ -33,6 +34,8 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 | [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)                                       | -                                                                                                                                                                                                                                                               |
+| [FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md)                                       | Minimal user identity passed to the policy function.                                                                                                                                                                                                            |
+| [FileResource](./docs/api/appkit/Interface.FileResource.md)                                           | Describes the file or directory being acted upon.                                                                                                                                                                                                               |
 | [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                                                                                                                                                                                                           |
@@ -50,21 +53,25 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## 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.     |
+| 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.                                                                          |
+| [FileAction](./docs/api/appkit/TypeAlias.FileAction.md)                 | Every action the files plugin can perform.                                                                                 |
+| [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md)                 | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
+| [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")
 
-| Variable                                       | Description          |
-| ---------------------------------------------- | -------------------- |
-| [sql](./docs/api/appkit/Variable.sql.md) | SQL helper namespace |
+| Variable                                                            | Description                  |
+| ------------------------------------------------------------------- | ---------------------------- |
+| [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md)   | Actions that only read data. |
+| [sql](./docs/api/appkit/Variable.sql.md)                      | SQL helper namespace         |
+| [WRITE\_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md) | Actions that mutate data.    |
 
 ## Functions[​](#functions "Direct link to Functions")
 

package/docs/development/type-generation.md

@@ -4,7 +4,9 @@ AppKit can automatically generate TypeScript types for your SQL queries, providi
 
 ## Goal[​](#goal "Direct link to Goal")
 
-Generate `client/src/appKitTypes.d.ts` so query keys, parameters, and result rows are type-safe.
+Generate type-safe TypeScript declarations for query keys, parameters, and result rows.
+
+All generated files live in `shared/appkit-types/`, one per plugin (e.g. `analytics.d.ts`). They use [`declare module`](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to augment existing interfaces, so the types apply globally — you never need to import them. TypeScript auto-discovers them through `"include": ["shared/appkit-types"]` in your tsconfig.
 
 ## Vite plugin: `appKitTypesPlugin`[​](#vite-plugin-appkittypesplugin "Direct link to vite-plugin-appkittypesplugin")
 
@@ -12,7 +14,7 @@ The recommended approach is to use the Vite plugin, which watches your SQL files
 
 ### Configuration[​](#configuration "Direct link to Configuration")
 
-* `outFile?: string` - Output file path (default: `src/appKitTypes.d.ts`)
+* `outFile?: string` - Output file path (default: `shared/appkit-types/analytics.d.ts`)
 * `watchFolders?: string[]` - Folders to watch for SQL files (default: `["../config/queries"]`)
 
 ### Example[​](#example "Direct link to Example")
@@ -27,7 +29,6 @@ export default defineConfig({
   plugins: [
     react(),
     appKitTypesPlugin({
-      outFile: "src/appKitTypes.d.ts",
       watchFolders: ["../config/queries"],
     }),
   ],
@@ -54,14 +55,14 @@ npx @databricks/appkit generate-types [rootDir] [outFile] [warehouseId]
 * Generate types using warehouse ID from environment
 
   ```bash
-  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts
+  npx @databricks/appkit generate-types . shared/appkit-types/analytics.d.ts
 
   ```
 
 * Generate types using warehouse ID explicitly
 
   ```bash
-  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts abc123...
+  npx @databricks/appkit generate-types . shared/appkit-types/analytics.d.ts abc123...
 
   ```
 

package/docs/faq.md

@@ -6,14 +6,14 @@
 
 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 |
+| 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)            |
+| [Model Serving](./docs/plugins/model-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!
 

package/docs/plugins/analytics.md

@@ -139,7 +139,7 @@ function SpendTable() {
 Augment the `QueryRegistry` interface to get full type inference on parameters and results:
 
 ```ts
-// config/appKitTypes.d.ts
+// shared/appkit-types/analytics.d.ts
 declare module "@databricks/appkit-ui/react" {
   interface QueryRegistry {
     spend_summary: {

package/docs/plugins/custom-plugins.md

@@ -3,8 +3,12 @@
 If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
 
 ```bash
+# Interactive
 npx @databricks/appkit plugin create
 
+# Non-interactive
+npx @databricks/appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description "My plugin" --force
+
 ```
 
 For a deeper understanding of the plugin structure, read on.

package/docs/plugins/execution-context.md

@@ -38,7 +38,6 @@ Exported from `@databricks/appkit`:
 * `getWorkspaceClient()`: Returns the appropriate WorkspaceClient for current context
 * `getWarehouseId()`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID` or auto-selected in dev)
 * `getWorkspaceId()`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
-* `isInUserContext()`: Returns `true` if currently executing in user context
 
 ## Development mode behavior[​](#development-mode-behavior "Direct link to Development mode behavior")
 

package/docs/plugins/files.md

@@ -12,6 +12,7 @@ File operations against Databricks Unity Catalog Volumes. Supports listing, read
 * Automatic cache invalidation on write operations
 * Custom content type mappings
 * Per-user execution context (OBO)
+* **Access policies**: Per-volume policy functions that gate read and write operations
 
 ## Basic usage[​](#basic-usage "Direct link to Basic usage")
 
@@ -75,6 +76,8 @@ interface IFilesConfig {
 }
 
 interface VolumeConfig {
+  /** Access policy for this volume. */
+  policy?: FilePolicy;
   /** Maximum upload size in bytes for this volume. Overrides plugin-level default. */
   maxUploadSize?: number;
   /** Map of file extensions to MIME types for this volume. Overrides plugin-level default. */
@@ -99,6 +102,121 @@ files({
 
 ```
 
+### Permission model[​](#permission-model "Direct link to Permission model")
+
+There are three layers of access control in the files plugin. Understanding how they interact is critical for securing your app:
+
+```text
+┌─────────────────────────────────────────────────┐
+│  Unity Catalog grants                           │
+│  (WRITE_VOLUME on the SP — set at deploy time)  │
+├─────────────────────────────────────────────────┤
+│  Execution identity                             │
+│  HTTP routes → always service principal         │
+│  Programmatic → SP by default, asUser() for OBO │
+├─────────────────────────────────────────────────┤
+│  File policies                                  │
+│  Per-volume (action, resource, user) → boolean  │
+│  Only app-level gate for HTTP routes            │
+└─────────────────────────────────────────────────┘
+
+```
+
+* **UC grants** control what the service principal can do at the Databricks level. These are set at deploy time via `app.yaml` resource bindings. The SP needs `WRITE_VOLUME` — the plugin declares this via resource requirements.
+* **Execution identity** determines whose credentials are used for the actual API call. HTTP routes always use the SP. The programmatic API uses SP by default but supports `asUser(req)` for OBO.
+* **File policies** are application-level checks evaluated **before** the API call. They receive the requesting user's identity (from the `x-forwarded-user` header) and decide allow/deny. This is the only gate that distinguishes between users on HTTP routes.
+
+warning
+
+Since HTTP routes always execute as the service principal, removing a user's UC `WRITE_VOLUME` grant has **no effect** on HTTP access — the SP's grant is what's used. Policies are how you restrict what individual users can do through your app.
+
+New in v0.21.0
+
+File policies are new. Volumes without an explicit policy now default to `publicRead()`, which **denies all write operations** (`upload`, `mkdir`, `delete`). If your app relies on write access, set an explicit policy — for example `files.policy.allowAll()` — on each volume that needs it.
+
+#### Access policies[​](#access-policies "Direct link to Access policies")
+
+Attach a policy to a volume to control which actions are allowed:
+
+```ts
+import { files } from "@databricks/appkit";
+
+files({
+  volumes: {
+    uploads: { policy: files.policy.publicRead() },
+  },
+});
+
+```
+
+#### Actions[​](#actions "Direct link to Actions")
+
+Policies receive an action string. The full list, split by category:
+
+| Category | Actions                                                            |
+| -------- | ------------------------------------------------------------------ |
+| Read     | `list`, `read`, `download`, `raw`, `exists`, `metadata`, `preview` |
+| Write    | `upload`, `mkdir`, `delete`                                        |
+
+#### Built-in policies[​](#built-in-policies "Direct link to Built-in policies")
+
+| Helper                      | Allows           | Denies            |
+| --------------------------- | ---------------- | ----------------- |
+| `files.policy.publicRead()` | all read actions | all write actions |
+| `files.policy.allowAll()`   | everything       | nothing           |
+| `files.policy.denyAll()`    | nothing          | everything        |
+
+#### Composing policies[​](#composing-policies "Direct link to Composing policies")
+
+Combine built-in and custom policies with three combinators:
+
+* **`files.policy.all(a, b)`** — AND: all policies must allow. Short-circuits on first denial.
+* **`files.policy.any(a, b)`** — OR: at least one policy must allow. Short-circuits on first allow.
+* **`files.policy.not(p)`** — Inverts a policy. For example, `not(publicRead())` yields a write-only policy (useful for ingestion/drop-box volumes).
+
+```ts
+// Read-only for regular users, full access for the service principal
+files({
+  volumes: {
+    shared: {
+      policy: files.policy.any(
+        (_action, _resource, user) => !!user.isServicePrincipal,
+        files.policy.publicRead(),
+      ),
+    },
+  },
+});
+
+```
+
+#### Custom policies[​](#custom-policies "Direct link to Custom policies")
+
+`FilePolicy` is a function `(action, resource, user) → boolean | Promise<boolean>`, so you can inline arbitrary logic:
+
+```ts
+import { type FilePolicy, WRITE_ACTIONS } from "@databricks/appkit";
+
+const ADMIN_IDS = ["admin-sp-id", "lead-user-id"];
+
+const adminOnly: FilePolicy = (action, _resource, user) => {
+  if (WRITE_ACTIONS.has(action)) {
+    return ADMIN_IDS.includes(user.id);
+  }
+  return true; // reads allowed for everyone
+};
+
+files({
+  volumes: { reports: { policy: adminOnly } },
+});
+
+```
+
+#### Enforcement[​](#enforcement "Direct link to Enforcement")
+
+* **HTTP routes**: Policy checked before every operation. Denied → `403` JSON response with `Policy denied "{action}" on volume "{volumeKey}"`.
+* **Programmatic API**: Policy checked on both `appkit.files("vol").list()` (SP identity, `isServicePrincipal: true`) and `appkit.files("vol").asUser(req).list()` (user identity). Denied → throws `PolicyDeniedError`.
+* **No policy configured**: Defaults to `files.policy.publicRead()` — read actions are allowed, write actions are denied. A startup warning is logged encouraging you to set an explicit policy.
+
 ### Custom content types[​](#custom-content-types "Direct link to Custom content types")
 
 Override or extend the built-in extension → MIME map:
@@ -118,7 +236,7 @@ Dangerous MIME types (`text/html`, `text/javascript`, `application/javascript`,
 
 ## HTTP routes[​](#http-routes "Direct link to HTTP routes")
 
-Routes are mounted at `/api/files/*`. All routes except `/volumes` execute in user context via `asUser(req)`.
+Routes are mounted at `/api/files/*`. All routes execute as the service principal. Policy enforcement checks user identity (from the `x-forwarded-user` header) before allowing operations — see [Access policies](#access-policies).
 
 | Method | Path                   | Query / Body                 | Response                                                     |
 | ------ | ---------------------- | ---------------------------- | ------------------------------------------------------------ |
@@ -242,7 +360,36 @@ interface FilePreview extends FileMetadata {
   isImage: boolean;
 }
 
+type FileAction =
+  | "list" | "read" | "download" | "raw"
+  | "exists" | "metadata" | "preview"
+  | "upload" | "mkdir" | "delete";
+
+interface FileResource {
+  /** Relative path within the volume. */
+  path: string;
+  /** The volume key (e.g. `"uploads"`). */
+  volume: string;
+  /** Content length in bytes — only present for uploads. */
+  size?: number;
+}
+
+interface FilePolicyUser {
+  /** User ID from the `x-forwarded-user` header. */
+  id: string;
+  /** `true` when the caller is the service principal (direct SDK call, not `asUser`). */
+  isServicePrincipal?: boolean;
+}
+
+type FilePolicy = (
+  action: FileAction,
+  resource: FileResource,
+  user: FilePolicyUser,
+) => boolean | Promise<boolean>;
+
 interface VolumeConfig {
+  /** Access policy for this volume. */
+  policy?: FilePolicy;
   /** Maximum upload size in bytes for this volume. */
   maxUploadSize?: number;
   /** Map of file extensions to MIME types for this volume. */
@@ -280,7 +427,7 @@ Built-in extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.bmp`, `
 
 ## User context[​](#user-context "Direct link to User context")
 
-Routes use `this.asUser(req)` so operations execute with the requesting user's Databricks credentials (on-behalf-of / OBO). The `/volumes` route is the only exception since it only reads plugin config.
+HTTP routes always execute as the **service principal** — the SP's Databricks credentials are used for all API calls. User identity is extracted from the `x-forwarded-user` header and passed to the volume's [access policy](#access-policies) for authorization. This means UC grants on the SP (not individual users) determine what operations are possible, while policies control what each user is allowed to do through the app.
 
 The programmatic API returns a `VolumeHandle` that exposes all `VolumeAPI` methods directly (service principal) and an `asUser(req)` method for OBO access. Calling any method without `asUser()` logs a warning encouraging OBO usage but does not throw. OBO access is strongly recommended for production use.
 
@@ -305,6 +452,7 @@ All errors return JSON:
 | Status | Description                                                   |
 | ------ | ------------------------------------------------------------- |
 | 400    | Missing or invalid `path` parameter                           |
+| 403    | Policy denied "`{action}`" on volume "`{volumeKey}`"          |
 | 404    | Unknown volume key                                            |
 | 413    | Upload exceeds `maxUploadSize`                                |
 | 500    | Operation failed (SDK, network, upstream, or unhandled error) |

package/docs/plugins/{serving.md → model-serving.md}

@@ -1,4 +1,4 @@
-# Serving plugin
+# Model Serving plugin
 
 Provides an authenticated proxy to [Databricks Model Serving](https://docs.databricks.com/aws/en/machine-learning/model-serving) endpoints, with invoke and streaming support.
 

package/docs/plugins/plugin-management.md

@@ -6,19 +6,30 @@ AppKit includes a CLI for managing plugins. All commands are available under `np
 
 ## Create a plugin[​](#create-a-plugin "Direct link to Create a plugin")
 
-Scaffold a new plugin interactively:
+Scaffold a new plugin interactively or via flags:
 
 ```bash
+# Interactive mode (prompts for all options)
 npx @databricks/appkit plugin create
 
+# Non-interactive mode (all required flags provided)
+npx @databricks/appkit plugin create \
+  --placement in-repo \
+  --path plugins/my-plugin \
+  --name my-plugin \
+  --description "My custom plugin" \
+  --resources sql_warehouse \
+  --force
+
 ```
 
-The wizard walks you through:
+In interactive mode, the wizard walks you through:
 
 * **Placement**: In your repository (e.g. `plugins/my-plugin`) or as a standalone package
 * **Metadata**: Name, display name, description
 * **Resources**: Which Databricks resources the plugin needs (SQL Warehouse, Secret, etc.) and whether each is required or optional
-* **Optional fields**: Author, version, license
+
+In non-interactive mode, `--placement`, `--path`, `--name`, and `--description` are required. Resources can be specified as a comma-separated list (`--resources sql_warehouse,volume`) or as JSON for full control (`--resources-json '[{"type":"sql_warehouse","permission":"CAN_MANAGE"}]'`). For all available options, run `npx @databricks/appkit plugin create --help`.
 
 The command generates a complete plugin scaffold with `manifest.json` and a TypeScript plugin class that imports the manifest directly — ready to register in your app.
 
@@ -91,12 +102,17 @@ npx @databricks/appkit plugin list --json
 
 ## Add a resource to a plugin[​](#add-a-resource-to-a-plugin "Direct link to Add a resource to a plugin")
 
-Interactively add a new resource requirement to an existing plugin manifest. **Requires `manifest.json`** in the plugin directory (the command edits it in place; it does not modify `manifest.js`):
+Add a new resource requirement to an existing plugin manifest. **Requires `manifest.json`** in the plugin directory (the command edits it in place; it does not modify `manifest.js`):
 
 ```bash
+# Interactive mode
 npx @databricks/appkit plugin add-resource
-
-# Or specify the plugin directory
 npx @databricks/appkit plugin add-resource --path plugins/my-plugin
 
+# Non-interactive mode (--type triggers flag-based mode)
+npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse
+npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run
+
 ```
+
+In non-interactive mode, only `--type` is required — all other fields (permission, resource key, field env vars) default to sensible values from the schema. Use `--dry-run` to preview the updated manifest without writing. For all available options, run `npx @databricks/appkit plugin add-resource --help`.