Document the September 2026 release

docs/applications/01-overview.md

@@ -17,7 +17,7 @@ Additionally, applications have a few other characteristics:
 
 * IAM Roles (AWS) or Service Accounts (GCP / Azure) are automatically created for your app to manage IAM with principle of least privilege.
 * They are container-based ([VMs are on our roadmap](https://roadmap.massdriver.cloud/bundles/application-vm-support-cl7s8svuy3959141xipth2cwcbe)).
-* Ability to generate environment variables via the application [instance's](/concepts/components-instances-deployments) parameters or [connections](/concepts/connections).
+* Ability to generate environment variables via the application [instance's](/concepts/components-instances-deployments) parameters or [dependencies](/concepts/dependencies).
 * Ability to programmatically select IAM Policies & Permissions from infrastructure components.
 
 **Supported Runtimes**:

docs/applications/02-create-application.md

@@ -56,7 +56,7 @@ Application templates are cached locally the first time `mass bundle new` is run
 
 :::
 
-Then, [`connections`](/concepts/connections) (your application dependencies) will need to be selected.
+Then, [`connections`](/concepts/dependencies) (your application dependencies) will need to be selected.
 
 For this example we'll choose [`postgresql-authentication`](https://github.com/massdriver-cloud/artifact-definitions/blob/main/definitions/artifacts/postgresql-authentication.json).
 

docs/bundle-development/00-overview.md

@@ -11,7 +11,7 @@ This section covers everything you need to build, test, and publish Massdriver b
 
 - **[Bundle YAML Specification](./bundle-yaml-spec)** - Complete reference for the `massdriver.yaml` file format
 - **[Schema Design](./schema-design/overview)** - JSON Schema patterns and Massdriver annotations for building parameter forms
-- **[Connections & Resources](./connections-artifacts/overview)** - How bundles consume and produce resources for type-safe infrastructure composition
+- **[Dependencies & Resources](./dependencies-resources/overview)** - How bundles consume and produce resources for type-safe infrastructure composition
 - **[Provisioners](./provisioners/overview)** - Configure OpenTofu, Terraform, Helm, and Bicep provisioning steps
 - **[Publishing](./publishing/versioning)** - Version, template, and publish bundles to the registry
 
@@ -22,7 +22,7 @@ This section covers everything you need to build, test, and publish Massdriver b
    mass bundle new my-bundle
    ```
 
-2. **Define your schema** in `massdriver.yaml` with parameters, connections, and resources (under the legacy `artifacts:` key)
+2. **Define your schema** in `massdriver.yaml` with parameters, dependencies, and resources
 
 3. **Write your IaC** in the provisioner directory (e.g., `src/` for OpenTofu)
 

docs/bundle-development/01-bundle-yaml-spec.md

@@ -101,6 +101,10 @@ steps:
     #   - .params.<field>                    - Bundle parameters
     #   - .dependencies.<name>               - Dependency resources
     #   - .dependencies.<name>.<path>        - Dependency resource fields
+    #   - .resources.<name>                  - Resources this bundle produces
+    #
+    # .connections and .artifacts are deprecated aliases for .dependencies
+    # and .resources. They hold the same data and still work.
     config:
       # OpenTofu/Terraform config options:
       #   json: boolean              - Enable JSON output (default: false)

docs/bundle-development/dependencies-resources/00-overview.md

@@ -0,0 +1,39 @@
+---
+id: dependencies-resources-overview
+slug: /bundle-development/dependencies-resources/overview
+title: Dependencies & Resources
+sidebar_label: Overview
+---
+
+Dependencies and resources enable type-safe composition of infrastructure components in Massdriver.
+
+## Key concepts
+
+- **Resources** are what a bundle produces for other bundles to consume — database connection details, cluster credentials, network layouts. Bundles declare them under `resources:` in `massdriver.yaml`.
+- **Dependencies** are what a bundle consumes from other bundles' resources. Bundles declare them under `dependencies:` in `massdriver.yaml`.
+- **Resource types** are the versioned schemas that define the contract between bundles.
+
+Drawing a line between two components on the canvas fills one bundle's dependency with another bundle's resource.
+
+## How it works
+
+When you draw a dependency between bundles on the canvas, Massdriver validates that:
+
+1. The resource's type matches the type the dependency expects
+2. The resource data conforms to the resource type schema
+3. The bundle versions at each end fall inside the dependency's version ranges
+
+The first two checks happen when you draw the line, so incompatible infrastructure never reaches a deployment. The third is re-checked per environment, so one blueprint can serve environments running different bundle versions.
+
+## In this section
+
+- **[Resource Type Specification](./resource-type-spec)** - Authoring, versioning, and publishing a resource type
+- **[Version Resolution](./version-resolution)** - How a version range picks a resource at deploy time
+
+## Related documentation
+
+- [Concepts: Dependencies](/concepts/dependencies) - Version ranges on a dependency
+- [Concepts: Resources & Resource Types](/concepts/resources-and-types) - Conceptual overview
+- [Bundle YAML: dependencies](/bundle-development/bundle-yaml-spec#dependencies) - What a bundle consumes
+- [Bundle YAML: resources](/bundle-development/bundle-yaml-spec#resources) - What a bundle produces
+- [Resource Types Repository](https://github.com/massdriver-cloud/artifact-definitions) - Standard resource types (the GitHub repo URL retains the legacy name)

docs/bundle-development/connections-artifacts/01-artifact-definition-spec.md → docs/bundle-development/dependencies-resources/01-resource-type-spec.md

@@ -1,6 +1,6 @@
 ---
-id: artifact-definition-spec
-slug: /bundle-development/connections-artifacts/artifact-definition-spec
+id: resource-type-spec
+slug: /bundle-development/dependencies-resources/resource-type-spec
 title: Resource Type Specification
 sidebar_label: Resource Type Spec
 ---
@@ -10,7 +10,7 @@ sidebar_label: Resource Type Spec
 This document outlines the `massdriver.yaml` format for authoring resource types. This format provides a more ergonomic authoring experience compared to writing raw JSON Schema, with support for referencing external files for instructions and export templates.
 
 :::tip When to Use This Format
-Use the `massdriver.yaml` format when creating new resource types. It separates concerns by keeping markdown instructions and Liquid templates in their own files, making definitions easier to read and maintain.
+Use the `massdriver.yaml` format for every resource type. It is the format that supports versioning and publishing to your organization's catalog, and it keeps markdown instructions and Liquid templates in their own files. The raw JSON schema format it replaces is deprecated.
 :::
 
 ## File Structure
@@ -20,6 +20,9 @@ A resource type using this format consists of a directory containing:
 ```
 my-resource-type/
 ├── massdriver.yaml          # Main definition file
+├── README.md                # Published with the artifact
+├── CHANGELOG.md             # Published with the artifact
+├── icon.svg                 # Published with the artifact
 ├── instructions/            # Onboarding instruction markdown files
 │   ├── step1.md
 │   └── step2.md
@@ -40,6 +43,12 @@ my-resource-type/
 # reference path: <org>/<name> (e.g., "acme/aws-rds-postgres")
 name: my-resource-type-name
 
+# version (required to publish)
+# Semantic version of the resource type (MAJOR.MINOR.PATCH).
+# The CLI publishes this as the artifact's tag in your organization's catalog.
+# Publishing is immutable: a version that already exists cannot be republished.
+version: 2.1.0
+
 # label (required)
 # Human-readable display name shown in the Massdriver UI.
 # Used in dropdowns, connection labels, and the resource type selector.
@@ -69,6 +78,12 @@ ui:
   # only see it as an environment default.
   connectionOrientation: link
 
+  # environmentDefaultGroup (optional)
+  # Groups this resource type with others in an environment's defaults panel.
+  # The group named "credentials" holds cloud credential types, which the UI
+  # separates from the rest of an environment's defaults.
+  environmentDefaultGroup: credentials
+
   # instructions (optional)
   # Onboarding instructions shown to users when they create resources of this
   # type. Each instruction becomes a step in the onboarding wizard.
@@ -288,8 +303,7 @@ schema:
     token:
       title: API Token
       type: string
-      $md:
-        sensitive: true
+      $md.sensitive: true
 ```
 
 ## Complete Example with All Features
@@ -411,50 +425,82 @@ DATABASE_NAME={{ artifact.authentication.database }}
 
 ## Publishing
 
-Publish your resource type using the Massdriver CLI:
+A resource type publishes to your organization's catalog as an OCI artifact, the same way a bundle does.
+
+```bash
+# Create the repository in the catalog
+mass resource-type create aws-vpc
+
+# Publish the version in massdriver.yaml
+mass resource-type publish ./aws-vpc
+
+# Pull a published version back down
+mass resource-type pull aws-vpc@2.1.0
+```
+
+`mass resource-type publish` takes a directory containing a `massdriver.yaml`, or the `massdriver.yaml` itself, and defaults to the current directory.
+
+The published artifact carries the `massdriver.yaml`, the readme, the changelog, the icon, and the instruction and export template files the `massdriver.yaml` references. Nothing else in the directory is included.
+
+Publishing is immutable. Once a version exists it cannot be overwritten, so anything pinned to it keeps resolving to what it resolved to the first time.
+
+### Versions and release channels
+
+Resource types use the same version model as bundles: semantic versions, release channels, and per-environment pinning. A bundle names the versions it accepts in its `dependencies` and `resources` blocks, and Massdriver resolves the range at deploy time. See [Version Resolution](/bundle-development/dependencies-resources/version-resolution).
+
+Each resource type also gets a repository in the OCI catalog, with the same access grants and attribute filters as a bundle repository.
+
+### Referenced files must exist
+
+`ui.instructions[].path` and `exports[].templatePath` point at files rather than carrying their content inline. A path that does not exist, or that resolves outside the resource type's directory, fails the publish. An incomplete artifact is never shipped.
+
+### Publishing a raw JSON schema is deprecated
+
+`mass resource-type publish` still accepts a raw JSON or YAML schema file, the format that predates `massdriver.yaml`, and prints a deprecation warning. That path will be removed in a future release.
+
+A raw schema carries no version of its own. It is stored as the resource type's unversioned `0.0.0` document, cannot take part in versioning, and cannot be pulled back down.
+
+`mass resource-type convert` migrates one:
 
 ```bash
-mass definition publish ./path/to/massdriver.yaml
+mass resource-type convert ./my-resource-type.json
 ```
 
-The CLI will:
-1. Read and parse the `massdriver.yaml` file
-2. Inline the content from instruction and export template files
-3. Build the JSON Schema format expected by the API
-4. Validate against the resource type meta-schema
-5. Publish to your organization
+It writes a `massdriver.yaml` alongside the schema and pulls inlined instruction and export content back out into referenced files. A placeholder `version` is written into the output — set a real version before you publish.
+
+Resource types that existed before this format were migrated in place and keep working.
 
 ## Referencing in Bundles
 
-Once published, reference your resource type in bundle `massdriver.yaml` files:
+Once published, name the resource type and the versions you accept in a bundle's `massdriver.yaml`:
 
 ```yaml
-# In a bundle's massdriver.yaml
-artifacts:
-  required:
-    - database
-  properties:
-    database:
-      # Omit org prefix for definitions in your own organization
-      $ref: postgres-database
-      # Or use fully qualified name: acme/postgres-database
-
-connections:
-  required:
-    - database
-  properties:
-    database:
-      $ref: postgres-database
+# What the bundle consumes
+dependencies:
+  database:
+    # Omit the org prefix for resource types in your own organization
+    resource_type: postgres-database@~2
+    required: true
+
+# What the bundle produces for other bundles to consume
+resources:
+  database:
+    resource_type: postgres-database@2.1.0
+    required: true
 ```
 
+A dependency accepts a range. A resource pins the single version it produces. See [Version Resolution](/bundle-development/dependencies-resources/version-resolution) for the accepted range forms.
+
 ## Field Reference
 
 | Field | Required | Description |
 |-------|----------|-------------|
 | `name` | Yes | Unique identifier (lowercase, hyphens) |
+| `version` | To publish | Semantic version, published as the artifact's tag |
 | `label` | Yes | Display name in UI |
 | `icon` | No | URL to icon image |
 | `ui.connectionOrientation` | No | `"link"` or `"environmentDefault"` |
+| `ui.environmentDefaultGroup` | No | Groups the type in an environment's defaults panel; `"credentials"` marks cloud credential types |
 | `ui.instructions` | No | Array of onboarding steps |
 | `ui.instructions[].label` | Yes | Step title |
 | `ui.instructions[].path` | Yes | Path to markdown file |
@@ -468,5 +514,6 @@ connections:
 ## See Also
 
 - [Resource Types Concept](/concepts/resources-and-types) - Understanding resource types
-- [Custom Resource Type Guide](/guides/custom-artifact-definition) - JSON format and advanced customization
+- [Version Resolution](/bundle-development/dependencies-resources/version-resolution) - How a version range picks a resource at deploy time
+- [Custom Resource Type Guide](/guides/custom-resource-type) - JSON format and advanced customization
 - [Massdriver Annotations](/bundle-development/schema-design/massdriver-annotations) - Special `$md` annotations

docs/bundle-development/dependencies-resources/02-version-resolution.md

@@ -0,0 +1,79 @@
+---
+id: version-resolution
+slug: /bundle-development/dependencies-resources/version-resolution
+title: Version Resolution
+sidebar_label: Version Resolution
+---
+
+# Version Resolution
+
+A bundle names the resource types it consumes and produces, and the versions of those resource types it accepts. Massdriver resolves each range to one specific resource when the bundle deploys, using what is available in the target environment at that moment.
+
+## Declaring a range
+
+`dependencies` are the resource types a bundle consumes. `resources` are the resource types it produces for other bundles to consume. Both take a `resource_type` in the form `name@version`:
+
+```yaml
+dependencies:
+  network:
+    resource_type: aws-vpc@~1.2
+    required: true
+  database:
+    resource_type: postgres-authentication@2.1.0
+    required: false
+
+resources:
+  api:
+    resource_type: aws-ecs-service@~2
+    required: true
+```
+
+`required` means different things on each side. On a dependency it means the slot must be filled before the bundle can deploy. On a resource it means the bundle always creates it.
+
+A resource pins the single version it produces. A dependency accepts a range:
+
+| Form | Accepts |
+|------|---------|
+| `aws-vpc@1.2.3` | that exact version |
+| `aws-vpc@~1.2` | the newest `1.2.x` |
+| `aws-vpc@~1` | the newest `1.x` |
+| `aws-vpc@latest` | the newest stable version |
+| `aws-vpc@latest+dev` | the newest version, including development releases |
+
+The `+dev` suffix also applies to a tilde range. `~1+dev` accepts the newest `1.x` including development releases; `~1` on its own skips them.
+
+## What fills a slot
+
+At deploy time Massdriver looks for a resource of the right type whose version the range accepts. It checks three sources and takes the first match:
+
+<SlotResolution />
+
+1. **A remote reference** set on the instance. This is a hand-picked resource, so both its resource type and its version are checked. The check runs again on every deploy, which catches a reference that was assigned before the bundle moved to a narrower range.
+2. **A connection** drawn on the project blueprint. The resource type was matched when the connection was drawn, so only the version is re-checked here.
+3. **An environment default**. Among the environment's defaults of that resource type, Massdriver takes the highest version the range accepts.
+
+A source that does not match is skipped, and the next source is tried. If no source matches, a `required` dependency blocks the deploy.
+
+## One default per version
+
+An environment holds one default per version of a resource type. Two bundles asking for different ranges each draw the version they asked for, from the same environment, with no per-instance configuration.
+
+This is also how a dependency picks up a newer version without the consuming bundle being republished. Add a newer `aws-vpc` default to the environment, and a bundle declaring `aws-vpc@~1` resolves to it on its next deploy as long as the new version is still in the `1.x` line.
+
+## Remote references are checked when you assign them
+
+Choosing a remote reference for a slot validates the pick against the slot's resource type and version range. An out-of-range or wrong-type resource is rejected at that point rather than during a deployment.
+
+## The legacy format
+
+`connections` and `artifacts` are the previous names for `dependencies` and `resources`. They still work and publish with a warning.
+
+A slot declared in the legacy format carries no version range. It matches an environment default of its resource type at any version, and it trusts a blueprint connection without re-checking the version. Moving the slot to `dependencies` or `resources` is what turns the version checks on.
+
+The two forms are mutually exclusive. Setting both `connections` and `dependencies`, or both `artifacts` and `resources`, is an error, so migrate one block at a time.
+
+## Related documentation
+
+- [Bundle YAML: dependencies and resources](/bundle-development/bundle-yaml-spec#dependencies) — full field reference
+- [Connections](/concepts/dependencies) — version ranges on the blueprint connection itself
+- [Resource Type Spec](/bundle-development/dependencies-resources/resource-type-spec) — authoring and publishing a versioned resource type