chore: template syncing

docs/docs/api/appkit/Class.Plugin.md

@@ -69,9 +69,13 @@ class MyPlugin extends Plugin<MyConfig> {
       resources.push({
         type: ResourceType.DATABASE,
         alias: 'cache',
+        resourceKey: 'database',
         description: 'Cache storage for query results',
         permission: 'CAN_CONNECT_AND_CREATE',
-        env: 'DATABRICKS_DATABASE_ID',
+        fields: {
+          instance_name: { env: 'DATABRICKS_CACHE_INSTANCE' },
+          database_name: { env: 'DATABRICKS_CACHE_DB' },
+        },
         required: true  // Mark as required at runtime
       });
     }

docs/docs/api/appkit/Class.ResourceRegistry.md

@@ -163,8 +163,8 @@ validate(): ValidationResult;
 
 Validates all registered resources against the environment.
 
-Checks each resource's environment variable to determine if it's resolved.
-Updates the `resolved` and `value` fields on each resource entry.
+Checks each resource's field environment variables to determine if it's resolved.
+Updates the `resolved` and `values` fields on each resource entry.
 
 Only required resources affect the `valid` status - optional resources
 are checked but don't cause validation failure.
@@ -182,7 +182,7 @@ const registry = ResourceRegistry.getInstance();
 const result = registry.validate();
 
 if (!result.valid) {
-  console.error("Missing resources:", result.missing.map(r => r.env));
+  console.error("Missing resources:", result.missing.map(r => Object.values(r.fields).map(f => f.env)));
 }
 ```
 

docs/docs/api/appkit/Function.getResourceRequirements.md

@@ -4,9 +4,10 @@
 function getResourceRequirements(plugin: PluginConstructor): {
   alias: string;
   description: string;
-  env?: string;
+  fields: Record<string, ResourceFieldEntry>;
   permission: ResourcePermission;
   required: boolean;
+  resourceKey: string;
   type: ResourceType;
 }[];
 ```

docs/docs/api/appkit/Interface.ResourceEntry.md

@@ -15,7 +15,7 @@ Extends ResourceRequirement with resolution state and plugin ownership.
 alias: string;
 ```
 
-Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets')
+Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display.
 
 #### Inherited from
 
@@ -37,18 +37,18 @@ Human-readable description of why this resource is needed
 
 ***
 
-### env?
+### fields
 
 ```ts
-optional env: string;
+fields: Record<string, ResourceFieldEntry>;
 ```
 
-Environment variable name where the resource ID/value should be provided
-Example: 'DATABRICKS_WAREHOUSE_ID', 'DATABRICKS_SECRET_SCOPE'
+Map of field name to env and optional description.
+Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.
 
 #### Inherited from
 
-[`ResourceRequirement`](Interface.ResourceRequirement.md).[`env`](Interface.ResourceRequirement.md#env)
+[`ResourceRequirement`](Interface.ResourceRequirement.md).[`fields`](Interface.ResourceRequirement.md#fields)
 
 ***
 
@@ -96,7 +96,21 @@ Whether this resource is required (true) or optional (false)
 resolved: boolean;
 ```
 
-Whether the resource has been resolved (environment variable found)
+Whether the resource has been resolved (all field env vars set)
+
+***
+
+### resourceKey
+
+```ts
+resourceKey: string;
+```
+
+Stable key for machine use (env naming, composite keys, app.yaml). Required.
+
+#### Inherited from
+
+[`ResourceRequirement`](Interface.ResourceRequirement.md).[`resourceKey`](Interface.ResourceRequirement.md#resourcekey)
 
 ***
 
@@ -114,10 +128,10 @@ Type of Databricks resource required
 
 ***
 
-### value?
+### values?
 
 ```ts
-optional value: string;
+optional values: Record<string, string>;
 ```
 
-The actual value of the resource (if resolved)
+Resolved value per field name. Populated by validate() when all field env vars are set.

docs/docs/api/appkit/Interface.ResourceFieldEntry.md

@@ -0,0 +1,24 @@
+# Interface: ResourceFieldEntry
+
+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).
+
+## Properties
+
+### description?
+
+```ts
+optional description: string;
+```
+
+Human-readable description for this field
+
+***
+
+### env
+
+```ts
+env: string;
+```
+
+Environment variable name for this field

docs/docs/api/appkit/Interface.ResourceRequirement.md

@@ -15,7 +15,7 @@ Can be defined statically in a manifest or dynamically via getResourceRequiremen
 alias: string;
 ```
 
-Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets')
+Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display.
 
 ***
 
@@ -29,14 +29,14 @@ Human-readable description of why this resource is needed
 
 ***
 
-### env?
+### fields
 
 ```ts
-optional env: string;
+fields: Record<string, ResourceFieldEntry>;
 ```
 
-Environment variable name where the resource ID/value should be provided
-Example: 'DATABRICKS_WAREHOUSE_ID', 'DATABRICKS_SECRET_SCOPE'
+Map of field name to env and optional description.
+Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.
 
 ***
 
@@ -60,6 +60,16 @@ Whether this resource is required (true) or optional (false)
 
 ***
 
+### resourceKey
+
+```ts
+resourceKey: string;
+```
+
+Stable key for machine use (env naming, composite keys, app.yaml). Required.
+
+***
+
 ### type
 
 ```ts

docs/docs/api/appkit/index.md

@@ -36,6 +36,7 @@ plugin architecture, and React integration.
 | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
 | [PluginManifest](Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. |
 | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
+| [ResourceFieldEntry](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](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). |
 | [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Configuration for streaming execution with default and user-scoped settings |
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |

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

@@ -112,6 +112,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.ResourceEntry",
           label: "ResourceEntry"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.ResourceFieldEntry",
+          label: "ResourceFieldEntry"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.ResourceRequirement",

docs/static/schemas/plugin-manifest.schema.json

@@ -186,18 +186,48 @@
         { "$ref": "#/$defs/appPermission" }
       ]
     },
+    "resourceFieldEntry": {
+      "type": "object",
+      "required": ["env"],
+      "properties": {
+        "env": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "description": "Environment variable name for this field",
+          "examples": ["DATABRICKS_CACHE_INSTANCE", "SECRET_SCOPE"]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description for this field"
+        }
+      },
+      "additionalProperties": false
+    },
     "resourceRequirement": {
       "type": "object",
-      "required": ["type", "alias", "description", "permission"],
+      "required": [
+        "type",
+        "alias",
+        "resourceKey",
+        "description",
+        "permission",
+        "fields"
+      ],
       "properties": {
         "type": {
           "$ref": "#/$defs/resourceType"
         },
         "alias": {
           "type": "string",
           "pattern": "^[a-z][a-zA-Z0-9_]*$",
-          "description": "Unique alias for this resource within the plugin",
-          "examples": ["warehouse", "secrets", "vectorIndex"]
+          "description": "Unique alias for this resource within the plugin (UI/display)",
+          "examples": ["SQL Warehouse", "Secret", "Vector search index"]
+        },
+        "resourceKey": {
+          "type": "string",
+          "pattern": "^[a-z][a-zA-Z0-9_]*$",
+          "description": "Stable key for machine use (env naming, composite keys, app.yaml).",
+          "examples": ["sql-warehouse", "database", "secret"]
         },
         "description": {
           "type": "string",
@@ -207,11 +237,13 @@
         "permission": {
           "$ref": "#/$defs/resourcePermission"
         },
-        "env": {
-          "type": "string",
-          "pattern": "^[A-Z][A-Z0-9_]*$",
-          "description": "Environment variable name where the resource ID should be provided",
-          "examples": ["DATABRICKS_WAREHOUSE_ID", "DATABRICKS_SECRET_SCOPE"]
+        "fields": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/resourceFieldEntry"
+          },
+          "minProperties": 1,
+          "description": "Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple (e.g. instance_name, database_name or scope, key)."
         }
       },
       "additionalProperties": false