@databricks/appkit-ui 0.36.0 → 0.38.0

package/docs/development/templates.md

@@ -47,19 +47,39 @@ The plugin manifest drives the CLI's behavior during `databricks apps init`:
 * **`app.yaml` generation** — resource fields produce `env` + `valueFrom` entries
 * **`databricks.yml` generation** — resource fields produce bundle variables and app resource entries
 
+The synced manifest is generated by `appkit plugin sync --write` from each plugin's `manifest.json` (see [Plugin manifest](./docs/plugins/manifest.md) for the authoring contract). The on-disk shape carries a `version` field that the CLI uses to negotiate features:
+
+* `"1.0"` / `"1.1"` — earlier shapes; still readable.
+* `"2.0"` — current shape. Adds `scaffolding` (required by the CLI when `version` is `"2.0"`; enforced at parse time, not via the published JSON Schema) and the `origin` field on every resource field entry. JSON Schema published at `https://databricks.github.io/appkit/schemas/template-plugins.schema.json`.
+
 ### Resource field properties[​](#resource-field-properties "Direct link to Resource field properties")
 
-Each resource field in the manifest can have these properties:
+Each resource field in the synced 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                                                                                                          |
+| `discovery`    | How the CLI lists candidate values for the field (see [Plugin manifest — Resource discovery](./docs/plugins/manifest.md#resource-discovery)). |
+| `origin`       | **v2.0** computed field. How the value is determined — see below.                                                                                   |
+
+### `origin` (v2.0)[​](#origin-v20 "Direct link to origin-v20")
 
-| 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                                          |
+`origin` is computed at sync time from the field's other properties — plugin authors do not write it. It tells scaffolding agents how each value reaches the running app:
+
+| Origin       | Trigger           | Meaning                                                                                                                        |
+| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `"platform"` | `localOnly: true` | Auto-injected by Databricks Apps at deploy time. Generated for local `.env` only; absent from `app.yaml` and bundle variables. |
+| `"static"`   | `value` set       | Hardcoded literal. CLI does not prompt.                                                                                        |
+| `"cli"`      | `resolve` set     | Resolved by the CLI from API calls (e.g. `postgres:host`).                                                                     |
+| `"user"`     | none of the above | User must provide the value at init time.                                                                                      |
+
+Precedence is in the order above (`localOnly` wins over `value`, which wins over `resolve`). The transform overwrites any hand-edited `origin` on the next sync — drift between the on-disk value and the field's actual shape is not possible by construction.
 
 ### Resolvers[​](#resolvers "Direct link to Resolvers")
 
@@ -87,7 +107,93 @@ Example field definition:
 
 ```
 
+After sync, the field carries `"origin": "platform"` (because `localOnly` takes precedence over `resolve` for local-only fields injected at deploy time).
+
+### `scaffolding.rules` propagation[​](#scaffoldingrules-propagation "Direct link to scaffoldingrules-propagation")
+
+Each plugin's `scaffolding.rules` block (see [Plugin manifest — Scaffolding rules](./docs/plugins/manifest.md#scaffolding-rules)) is propagated unchanged into its entry in `appkit.plugins.json`. The CLI hands the merged plugin-level rules — alongside the top-level template `scaffolding.rules` — to scaffolding agents that drive `databricks apps init`.
+
+Merge model:
+
+1. Gather rules from every selected plugin and from every plugin with `requiredByTemplate: true`.
+2. Apply the template-level `scaffolding.rules` on top.
+3. Plugin-level rules **override** skill-baked or template-level defaults at the same directive site.
+4. A plugin `must` that conflicts with a template `never` (or vice versa) stops the init flow — see the validation rules below.
+
+### `scaffolding` descriptor (v2.0)[​](#scaffolding-descriptor-v20 "Direct link to scaffolding-descriptor-v20")
+
+The `scaffolding` block at the top level of `appkit.plugins.json` describes the scaffolding command, its flags, and the cross-cutting rules every scaffolding agent must respect. It is required by the CLI when `version` is `"2.0"`. The requirement is enforced at parse time — the published JSON Schema marks only `version` and `plugins` as top-level required fields because it cannot express conditional requirements.
+
+```json
+{
+  "scaffolding": {
+    "command": "databricks apps init",
+    "flags": {
+      "--name": {
+        "description": "Project name — sets {{.projectName}} in package.json, databricks.yml, and .env. Required for non-interactive scaffolding.",
+        "required": true,
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "--features": {
+        "description": "Plugins to enable (comma-separated, no spaces; must match keys in this manifest's plugins map)",
+        "required": false,
+        "pattern": "^[a-zA-Z0-9_-]+(,[a-zA-Z0-9_-]+)*$"
+      },
+      "--profile": {
+        "description": "Databricks CLI profile to use for authentication (global flag)",
+        "required": false
+      }
+    },
+    "rules": {
+      "must": [
+        "Keep all secrets and credentials only in app.yaml, databricks.yml, and/or .env"
+      ],
+      "should": [
+        "ask user when in doubt of resource to use for plugin"
+      ],
+      "never": [
+        "guess resources when multiple or no options are available",
+        "embed secrets in files that will go to the client-bundle"
+      ]
+    }
+  }
+}
+
+```
+
+| Field          | Description                                                             |
+| -------------- | ----------------------------------------------------------------------- |
+| `command`      | Scaffolding command the agent should invoke.                            |
+| `flags`        | Map of flag name to `{ description, required?, pattern?, default? }`.   |
+| `rules.must`   | Actions the scaffolding agent must always perform.                      |
+| `rules.should` | Recommended actions — applied unless overridden by a plugin-level rule. |
+| `rules.never`  | Actions the scaffolding agent must never perform.                       |
+
+The example above shows three flags. The canonical flag set shipped with every synced template manifest is:
+
+| Flag             | Required | Description                                                                                                                    |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--name`         | yes      | Project name — sets `{{.projectName}}` in `package.json`, `databricks.yml`, and `.env`.                                        |
+| `--template`     | no       | Template path (local directory or GitHub URL).                                                                                 |
+| `--version`      | no       | AppKit version to use; defaults to auto-detected.                                                                              |
+| `--features`     | no       | Plugins to enable (comma-separated, no spaces; must match keys in the `plugins` map).                                          |
+| `--set`          | no       | Set resource values (format: `plugin.resourceKey.field=value`, repeatable).                                                    |
+| `--output-dir`   | no       | Directory to write the project to.                                                                                             |
+| `--description`  | no       | App description.                                                                                                               |
+| `--run`          | no       | Run the app after creation (`none`, `dev`, `dev-remote`).                                                                      |
+| `--auto-approve` | no       | Skip prompts for optional resources. Not recommended for agent-driven init — conflicts with the "ask user when in doubt" rule. |
+| `--profile`      | no       | Databricks CLI profile to use for authentication (global flag).                                                                |
+
+Each rule item is capped at **120 characters** by the schema. Long prose fails validation — split into discrete actionable directives.
+
+The descriptor is canonical: AppKit owns the values and ships them with every synced template manifest. Authors of consuming agents (LLM-driven scaffolders, custom CLI runners) should treat the rule lists as enforcement contracts, not suggestions.
+
+#### Substitutability gate (template rules)[​](#substitutability-gate-template-rules "Direct link to Substitutability gate (template rules)")
+
+The template-level rules survive the same substitutability gate that governs plugin-level rules: each entry must describe a **cross-cutting agent decision** the schema cannot already encode. Rules like "modify only files inside the template directory" or "list volumes after prompting for catalog/schema" are absent on purpose — the first is unreachable once you read the manifest as the source of truth, and the second is now encoded structurally as `parents: ["catalog", "schema"]` on the `volume` discovery kind (see [Plugin manifest — Transient prompts](./docs/plugins/manifest.md#transient-prompts-parents)).
+
 ## 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
+* [Plugin manifest](./docs/plugins/manifest.md) — the authoring side (`manifest.json`).
+* [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.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v1.0.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/plugins/agents.md

@@ -4,7 +4,7 @@ Beta plugin
 
 This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
 
-The `agents` plugin turns a Databricks AppKit app into an AI-agent host. It loads agent definitions from markdown on disk (one folder per agent: `config/agents/<id>/agent.md`), from TypeScript (`createAgent(def)`), or both, and exposes them at `POST /invocations` alongside routes for chat, thread management, and cancellation.
+The `agents` plugin turns a Databricks AppKit app into an AI-agent host. It loads agent definitions from markdown on disk (one folder per agent: `config/agents/<id>/agent.md`), from TypeScript (`createAgent(def)`), or both, and exposes them at `POST /invocations` and `POST /responses` (non-streaming, aliases) alongside `POST /chat` (streaming) and routes for thread management, cancellation, and HITL approval.
 
 This page covers the full lifecycle. For the hand-written primitives (`tool()`, `mcpServer()`), see [tools](./docs/plugins/server.md).
 
@@ -30,7 +30,7 @@ await createApp({
 
 ```
 
-That alone gives you a live HTTP server with `POST /invocations` wired to a markdown-driven agent.
+That alone gives you a live HTTP server with `POST /invocations` (and its alias `POST /responses`) wired to a markdown-driven agent. Use `POST /chat` instead when you want the streaming, HITL-capable surface.
 
 ## Level 1: drop a markdown agent package[​](#level-1-drop-a-markdown-agent-package "Direct link to Level 1: drop a markdown agent package")
 
@@ -66,7 +66,11 @@ On startup the plugin:
 
 The agent starts with **no tools**. Tools are opt-in — declare them in frontmatter (Level 2 below) or opt into auto-inherit explicitly with `agents({ autoInheritTools: { file: true } })`. See "Auto-inherit posture" further down for what that costs and why it's off by default.
 
-Requests land at `POST /invocations` with an OpenAI Responses-compatible body. Every tool call runs through `asUser(req)` so SQL executes as the requesting user, file access respects Unity Catalog ACLs, and telemetry spans are created automatically.
+Requests land at `POST /invocations` (or its alias `POST /responses`) with an OpenAI Responses-compatible body. These endpoints run the agent to completion and return a single JSON response — no SSE. Streaming clients should use `POST /chat`. Every tool call runs through `asUser(req)` so SQL executes as the requesting user, file access respects Unity Catalog ACLs, and telemetry spans are created automatically.
+
+No HITL on `/invocations` and `/responses`
+
+The non-streaming invoke surface has no way to surface a mid-call approval prompt back to the caller. When `approval.requireForDestructive` is enabled (default) and the resolved agent has any tool annotated with a mutating effect (`effect: "write" | "update" | "destructive"`, or the legacy `destructive: true`), `POST /invocations` and `POST /responses` reject the request with HTTP 400 before the adapter runs. Move HITL-capable agents to `POST /chat`, or disable approval via `agents({ approval: { requireForDestructive: false } })` for autonomous back-office agents.
 
 ## Level 2: scope tools in frontmatter[​](#level-2-scope-tools-in-frontmatter "Direct link to Level 2: scope tools in frontmatter")
 
@@ -386,7 +390,7 @@ The route enforces that the decider is the stream owner: an approve from a diffe
 
 The plugin enforces a handful of caps to protect a single-instance deployment from runaway prompts, misbehaving clients, or prompt-injected delegation cycles. Some are static (enforced by the request schema) and some are configurable via `agents({ limits: { ... } })`.
 
-**Static caps** (applied at `POST /chat` and `POST /invocations` request parsing):
+**Static caps** (applied at `POST /chat`, `POST /invocations`, and `POST /responses` request parsing):
 
 | Field                                | Cap               | Why                                                                           |
 | ------------------------------------ | ----------------- | ----------------------------------------------------------------------------- |

package/docs/plugins/custom-plugins.md

@@ -15,34 +15,42 @@ 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`](./docs/api/appkit/Class.Plugin.md) class and export with `toPlugin()`:
+Author the manifest as JSON, import it, and attach it to a [`Plugin`](./docs/api/appkit/Class.Plugin.md) subclass via `static manifest`. Export with `toPlugin()`:
+
+```json
+// my-plugin/manifest.json
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "my-plugin",
+  "displayName": "My Plugin",
+  "description": "A custom plugin",
+  "resources": {
+    "required": [
+      {
+        "type": "secret",
+        "alias": "apiKey",
+        "resourceKey": "api-key",
+        "description": "API key for external service",
+        "permission": "READ",
+        "fields": {
+          "scope": { "env": "MY_SECRET_SCOPE", "description": "Secret scope" },
+          "key": { "env": "MY_API_KEY", "description": "Secret key name" }
+        }
+      }
+    ],
+    "optional": []
+  }
+}
+
+```
 
 ```typescript
+// my-plugin/index.ts
 import { Plugin, toPlugin, type PluginManifest } from "@databricks/appkit";
-import type express from "express";
+import manifest from "./manifest.json";
 
 class MyPlugin extends Plugin {
-  static manifest = {
-    name: "myPlugin",
-    displayName: "My Plugin",
-    description: "A custom plugin",
-    resources: {
-      required: [
-        {
-          type: "secret",
-          alias: "apiKey",
-          resourceKey: "apiKey",
-          description: "API key for external service",
-          permission: "READ",
-          fields: {
-            scope: { env: "MY_SECRET_SCOPE", description: "Secret scope" },
-            key: { env: "MY_API_KEY", description: "Secret key name" }
-          }
-        }
-      ],
-      optional: []
-    }
-  } satisfies PluginManifest<"myPlugin">;
+  static manifest = manifest as PluginManifest<"my-plugin">;
 
   async setup() {
     // Initialize your plugin
@@ -67,6 +75,8 @@ export const myPlugin = toPlugin(MyPlugin);
 
 ```
 
+JSON is the canonical authoring surface — it is what `appkit plugin sync` reads when aggregating manifests for templates. For the full v2.0 manifest contract (resources, discovery descriptors, scaffolding rules), see [Plugin manifest](./docs/plugins/manifest.md).
+
 ## Config-dependent resources[​](#config-dependent-resources "Direct link to Config-dependent resources")
 
 The manifest defines resources as either `required` (always needed) or `optional` (may be needed). For resources that become required based on plugin configuration, implement a static `getResourceRequirements(config)` method:

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.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v1.0.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")

package/docs/plugins/manifest.md

@@ -0,0 +1,293 @@
+# Plugin manifest
+
+Every plugin ships a `manifest.json` next to its source code. The manifest declares plugin metadata, the Databricks resources the plugin needs, and any structured rules a scaffolding agent must honor when running `databricks apps init`. It is consumed at three stages:
+
+* **Authoring** — `import manifest from "./manifest.json"` and attach it to the `Plugin` subclass via `static manifest`.
+* **Sync** — `appkit plugin sync --write` aggregates manifests from installed packages and local plugins into `appkit.plugins.json`.
+* **Init** — `databricks apps init` reads `appkit.plugins.json` to drive plugin selection, resource prompts, and `.env` / `databricks.yml` / `app.yaml` generation.
+
+This page documents the **v2.0** manifest contract. JSON Schema is published at `https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json`; reference it via `$schema` for editor validation.
+
+## Recommended pattern[​](#recommended-pattern "Direct link to Recommended pattern")
+
+Author the manifest as JSON, import it into the plugin module, and assert the type:
+
+```typescript
+// packages/my-plugin/src/index.ts
+import { Plugin, toPlugin } from "@databricks/appkit";
+import type { PluginManifest } from "@databricks/appkit";
+import manifest from "./manifest.json";
+
+class MyPlugin extends Plugin {
+  static manifest = manifest as PluginManifest<"my-plugin">;
+  // ...
+}
+
+export const myPlugin = toPlugin(MyPlugin);
+
+```
+
+```json
+// packages/my-plugin/src/manifest.json
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "my-plugin",
+  "displayName": "My Plugin",
+  "description": "A custom plugin",
+  "resources": {
+    "required": [],
+    "optional": []
+  }
+}
+
+```
+
+JSON is the canonical authoring surface — it is what `appkit plugin sync` reads. JS manifests (`manifest.js` / `manifest.cjs`) are ignored by default and require `--allow-js-manifest` to opt in (executes plugin code; trust required). For end-to-end CLI behavior, see [Plugin management](./docs/plugins/plugin-management.md).
+
+## Required fields[​](#required-fields "Direct link to Required fields")
+
+| Field                | Type                    | Notes                                                                 |
+| -------------------- | ----------------------- | --------------------------------------------------------------------- |
+| `name`               | `string`                | Plugin identifier. Lowercase, starts with a letter, `[a-z0-9-]` only. |
+| `displayName`        | `string`                | Shown in UI and CLI prompts.                                          |
+| `description`        | `string`                | Brief summary.                                                        |
+| `resources.required` | `ResourceRequirement[]` | Resources the plugin cannot run without.                              |
+| `resources.optional` | `ResourceRequirement[]` | Resources that enhance behavior but are not mandatory.                |
+
+## Resources[​](#resources "Direct link to Resources")
+
+A resource requirement declares one Databricks resource the plugin depends on. The shape is keyed by `type`; each type fixes its valid `permission` values (validated by the schema as a discriminated union):
+
+| `type`                | Permissions                                     |
+| --------------------- | ----------------------------------------------- |
+| `secret`              | `READ`, `WRITE`, `MANAGE`                       |
+| `job`                 | `CAN_VIEW`, `CAN_MANAGE_RUN`, `CAN_MANAGE`      |
+| `sql_warehouse`       | `CAN_USE`, `CAN_MANAGE`                         |
+| `serving_endpoint`    | `CAN_VIEW`, `CAN_QUERY`, `CAN_MANAGE`           |
+| `volume`              | `READ_VOLUME`, `WRITE_VOLUME`                   |
+| `vector_search_index` | `SELECT`                                        |
+| `uc_function`         | `EXECUTE`                                       |
+| `uc_connection`       | `USE_CONNECTION`                                |
+| `database`            | `CAN_CONNECT_AND_CREATE`                        |
+| `postgres`            | `CAN_CONNECT_AND_CREATE`                        |
+| `genie_space`         | `CAN_VIEW`, `CAN_RUN`, `CAN_EDIT`, `CAN_MANAGE` |
+| `experiment`          | `CAN_READ`, `CAN_EDIT`, `CAN_MANAGE`            |
+| `app`                 | `CAN_USE`                                       |
+
+Every requirement has:
+
+* `alias` — human-readable label used in UI / CLI output.
+* `resourceKey` — stable machine key (`[a-z][a-z0-9-]*`). Used for deduplication, env naming, and references in `app.yaml`. **Identity is keyed on `resourceKey`, not `alias`.**
+* `description` — explains *why* this resource is needed; surfaces in interactive prompts.
+* `fields` — map of field name → field entry (see below). At least one entry when present.
+* `permission` — must match the type's allowed enum.
+
+Single-value resource types (e.g. `sql_warehouse`) typically declare one field (`id`). Multi-value types (e.g. `secret`, `database`) declare several (`scope` + `key`, `instance_name` + `database_name`).
+
+### Field entry[​](#field-entry "Direct link to Field entry")
+
+```json
+{
+  "id": {
+    "env": "DATABRICKS_WAREHOUSE_ID",
+    "description": "SQL Warehouse ID",
+    "examples": ["1234abcd5678efgh"],
+    "discovery": { "type": "kind", "resourceKind": "warehouse" }
+  }
+}
+
+```
+
+| Property       | Description                                                                                                                                                                      |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`          | Environment variable name written to `.env` and `app.yaml`. Must match `^[A-Z][A-Z0-9_]*$`.                                                                                      |
+| `description`  | Shown in interactive prompts and bundle variable descriptions.                                                                                                                   |
+| `examples`     | Sample values shown in field descriptions.                                                                                                                                       |
+| `localOnly`    | When `true`, the field is generated for local `.env` only — the Databricks Apps platform auto-injects it at deploy time, so it is excluded from `app.yaml` and `databricks.yml`. |
+| `bundleIgnore` | Excluded from `databricks.yml` variables (still written to `.env`).                                                                                                              |
+| `value`        | Static default value.                                                                                                                                                            |
+| `resolve`      | CLI-side resolver name, formatted `<resource_type>:<field>` (e.g. `postgres:host`). The CLI populates the value from API calls during init.                                      |
+| `discovery`    | Describes how the CLI lists candidate values — see below.                                                                                                                        |
+
+### Configuration-dependent resources[​](#configuration-dependent-resources "Direct link to Configuration-dependent resources")
+
+The manifest distinguishes `required` from `optional` for static analysis. When a resource only becomes required based on the plugin's runtime config, list it under `optional` in the manifest and override at runtime via a static `getResourceRequirements(config)` method on the plugin class. See [Creating custom plugins](./docs/plugins/custom-plugins.md#config-dependent-resources).
+
+## Resource discovery[​](#resource-discovery "Direct link to Resource discovery")
+
+Discovery describes how the CLI offers candidate values for a field during interactive init. There are two variants under `discovery`, discriminated by `type`:
+
+### `kind` variant (preferred)[​](#kind-variant-preferred "Direct link to kind-variant-preferred")
+
+```json
+{
+  "discovery": {
+    "type": "kind",
+    "resourceKind": "warehouse"
+  }
+}
+
+```
+
+The `kind` variant references a well-known Databricks resource kind for which AppKit owns the listing command and response shape. This is the preferred form for first-party Databricks resources — plugin authors declare *what* to list, and AppKit owns *how* to list it.
+
+Supported `resourceKind` values:
+
+| `resourceKind`      | Listed via                                    |
+| ------------------- | --------------------------------------------- |
+| `warehouse`         | `databricks warehouses list`                  |
+| `genie_space`       | `databricks genie list-spaces`                |
+| `volume`            | `databricks volumes list {catalog} {schema}`  |
+| `postgres_project`  | `databricks postgres list-projects`           |
+| `postgres_branch`   | `databricks postgres list-branches {project}` |
+| `postgres_database` | `databricks postgres list-databases {branch}` |
+
+Supported options on the `kind` variant:
+
+| Property    | Description                                                                                                                                         |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `select`    | Field name in the parsed CLI response used as the selected value (e.g. `"id"`, `"name"`, `"full_name"`). Defaults to the kind's natural identifier. |
+| `display`   | Field name shown to the user during selection. Defaults to `select`.                                                                                |
+| `dependsOn` | Name of a sibling field within the same resource that must resolve first (see [Field dependencies](#field-dependencies)).                           |
+| `shortcut`  | Single-value fast-path command that returns exactly one value, skipping interactive selection.                                                      |
+
+### `cli` variant (escape hatch)[​](#cli-variant-escape-hatch "Direct link to cli-variant-escape-hatch")
+
+For resources outside the `kind` map, fall back to the `cli` variant:
+
+```json
+{
+  "discovery": {
+    "type": "cli",
+    "cliCommand": "databricks custom-resource list --profile <PROFILE> --output json",
+    "selectField": ".id",
+    "displayField": ".name"
+  }
+}
+
+```
+
+| Property       | Description                                                                                                                                                                                                                                                                       |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cliCommand`   | Full Databricks CLI command. **Must include the literal `<PROFILE>` placeholder** — the runner substitutes the user's CLI profile. Shell metacharacters (`;`, `\|`, `&`, `` ` ``, `$`, newlines) are rejected — executors pass arguments via argv, never `shell-exec` the string. |
+| `selectField`  | jq-style path to the field used as the selected value (e.g. `.id`, `.name`).                                                                                                                                                                                                      |
+| `displayField` | jq-style path to the field shown to the user. Defaults to `selectField`.                                                                                                                                                                                                          |
+| `dependsOn`    | Sibling field that must resolve first.                                                                                                                                                                                                                                            |
+| `shortcut`     | Single-value fast-path command. Same metacharacter restriction as `cliCommand`.                                                                                                                                                                                                   |
+
+The `cli` variant is intentionally minimal and may tighten in future versions. **Prefer the `kind` variant** for any resource AppKit knows about; it gives you a single source of truth for command + unwrap rules and guarantees forward-compat as AppKit refines the discovery contract.
+
+### Field dependencies[​](#field-dependencies "Direct link to Field dependencies")
+
+When listing one resource depends on another (e.g. listing volumes requires a catalog and schema; listing Postgres branches requires a project), use `dependsOn` to declare ordering:
+
+```json
+{
+  "fields": {
+    "project": {
+      "discovery": { "type": "kind", "resourceKind": "postgres_project", "select": "name" }
+    },
+    "branch": {
+      "discovery": {
+        "type": "kind",
+        "resourceKind": "postgres_branch",
+        "select": "name",
+        "dependsOn": "project"
+      }
+    }
+  }
+}
+
+```
+
+`dependsOn` references a sibling field name within the same resource. The CLI prompts in dependency order and substitutes the resolved value into the parent command (e.g. `{project}` in `databricks postgres list-branches {project}`).
+
+The schema validates the dependency graph at parse time:
+
+* Dangling references (`dependsOn` pointing at a non-existent sibling) are rejected.
+* Cycles are rejected with the chain listed (`a → b → a`).
+
+### Transient prompts (`parents`)[​](#transient-prompts-parents "Direct link to transient-prompts-parents")
+
+Some `kind`-variant commands need values that are **not** sibling fields on the resource — they are query inputs the runner collects once and discards. AppKit declares these on the `kind` itself via a `parents` array on `RESOURCE_KIND_COMMANDS`.
+
+The only kind that uses `parents` today is `volume`:
+
+```text
+volume → parents: ["catalog", "schema"]
+
+```
+
+Before invoking `databricks volumes list {catalog} {schema} --profile <PROFILE> --output json`, the runner prompts the user for each `parents` entry as free text and substitutes the value into the matching `{name}` placeholder. Unlike `dependsOn`, the collected values are **not** persisted as resource fields — they exist only for the duration of the listing call.
+
+Plugin authors do not declare `parents` in their manifest; it is part of the AppKit-owned `kind` contract and surfaces in the published JSON Schema alongside each kind's command template.
+
+## Scaffolding rules[​](#scaffolding-rules "Direct link to Scaffolding rules")
+
+`scaffolding.rules` is the plugin-level handoff to scaffolding agents (LLM-driven runners, custom CLI workflows, the `databricks-apps` skill). It carries up to three short directive lists — `must`, `should`, `never` — that the agent honors when invoking `databricks apps init` with this plugin selected.
+
+```json
+{
+  "scaffolding": {
+    "rules": {
+      "should": [
+        "After init, run any database migrations for your chosen ORM before first request",
+        "After init, verify Lakebase connectivity with 'psql $PGHOST -c \"select 1\"'"
+      ]
+    }
+  }
+}
+
+```
+
+| Bucket   | Semantics                                             |
+| -------- | ----------------------------------------------------- |
+| `must`   | The agent must perform the action.                    |
+| `should` | Recommended action — agent applies unless overridden. |
+| `never`  | The agent must not perform the action.                |
+
+### Authoring contract[​](#authoring-contract "Direct link to Authoring contract")
+
+* Each entry is a single short directive, **capped at 120 characters** by the schema. Long prose fails validation; split it into discrete actionable items.
+* The schema enforces both **per-bucket dedup** (no two entries with the same text inside one of `must` / `should` / `never`) and **cross-bucket dedup** (one entry cannot belong to two buckets at once).
+* Use the `Before init` / `After init` prefix convention when ordering matters so consumers can sequence directives consistently.
+
+### Substitutability gate[​](#substitutability-gate "Direct link to Substitutability gate")
+
+A rule belongs in the manifest **only if it cannot be expressed as structured data** somewhere else — a resource permission, a `discovery` descriptor, a `dependsOn` chain, a `requiredByTemplate` flag, a config field, or the field's `env` / `value` / `resolve` slot.
+
+Examples of what **does** survive the gate:
+
+* `"After init, run any database migrations for your chosen ORM before first request"` — runtime sequencing, not derivable from any resource shape.
+* `"After init, configure the 'spaces' map in plugin config with alias-to-Space-ID mappings"` — config-population guidance the schema cannot encode.
+
+Examples of what does **not** survive (and should be modeled instead):
+
+* "Plugin X requires `READ_VOLUME` on its volume" → already encoded in the resource's `permission` field.
+* "The runner must list Postgres branches after a project is chosen" → already encoded via `dependsOn`.
+* "Prompt the user for catalog and schema before listing volumes" → already encoded via `RESOURCE_KIND_COMMANDS.volume.parents`.
+
+If you find yourself writing prose that the schema could capture, extend the schema instead.
+
+The rules block is propagated unchanged from the plugin manifest into the synced template manifest. See [Templates — `scaffolding.rules` propagation](./docs/development/templates.md#scaffoldingrules-propagation) for how the CLI merges plugin-level rules with the template-level rules block.
+
+## Optional fields[​](#optional-fields "Direct link to Optional fields")
+
+| Field            | Description                                                                                                                             |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `author`         | Author name or organization.                                                                                                            |
+| `version`        | Plugin version, semver format (`X.Y.Z` or `X.Y.Z-prerelease`).                                                                          |
+| `repository`     | URL to the plugin source.                                                                                                               |
+| `keywords`       | Discovery keywords.                                                                                                                     |
+| `license`        | SPDX identifier.                                                                                                                        |
+| `onSetupMessage` | One-shot message displayed after init. Use for short hints; prefer `scaffolding.rules` for actionable directives an agent must enforce. |
+| `hidden`         | When `true`, the plugin is excluded from the synced template manifest.                                                                  |
+| `stability`      | `"beta"` or `"ga"`. Beta plugins may break across minor releases — see [Plugin stability tiers](./docs/plugins/stability.md).     |
+| `config.schema`  | JSON Schema for the plugin's runtime config (used by the type generator and for validation).                                            |
+
+## See also[​](#see-also "Direct link to See also")
+
+* [Creating custom plugins](./docs/plugins/custom-plugins.md) — building a plugin from scratch.
+* [Plugin management](./docs/plugins/plugin-management.md) — `appkit plugin sync`, `create`, `validate`, `add-resource`.
+* [Templates](./docs/development/templates.md) — how the synced template manifest drives `databricks apps init`.
+* [`PluginManifest` API reference](./docs/api/appkit/Interface.PluginManifest.md) — TypeScript type.

package/docs.md

@@ -19,7 +19,7 @@ AppKit simplifies building data applications on Databricks by providing:
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* 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).
+* Databricks CLI (v1.0.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
 ## Quick start options[​](#quick-start-options "Direct link to Quick start options")
 
@@ -37,7 +37,7 @@ Databricks AppKit is designed to work with AI coding assistants through Agent Sk
 Install Agent Skills and configure it for use with your preferred AI assistant:
 
 ```bash
-databricks experimental aitools install
+databricks aitools install
 
 ```