heroku
diff --git a/‎docs/data-sources/app.md‎
Lines changed: 22 additions & 22 deletions b/‎docs/data-sources/app.md‎
Lines changed: 22 additions & 22 deletions
diff --git a/‎docs/resources/app.md‎
Lines changed: 68 additions & 71 deletions b/‎docs/resources/app.md‎
Lines changed: 68 additions & 71 deletions
diff --git a/‎docs/resources/app_release.md‎
Lines changed: 12 additions & 11 deletions b/‎docs/resources/app_release.md‎
Lines changed: 12 additions & 11 deletions
@@ -8,7 +8,9 @@ description: |-
 
 # Data Source: heroku_app
 
-Use this data source to get information about a Heroku App.
+Use this data source to get information about a Heroku app.
+
+~> **NOTE:** This resource is only supported for apps that use [classic buildpacks](https://devcenter.heroku.com/articles/buildpacks#classic-buildpacks).
 
 ## Example Usage
 
@@ -23,50 +25,48 @@ data "heroku_app" "default" {
 
 The following arguments are supported:
 
-* `name` - (Required) The name of the application. In Heroku, this is also the
+* `name`: (Required) The name of the application. In Heroku, it's a
    unique ID, so it must be unique and have a minimum of 3 characters.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `id` - The unique UUID of the Heroku app.
+* `id`: The unique UUID of the Heroku app.
 
-* `name` - The name of the application. In Heroku, this is also the
+* `name`: The name of the application. In Heroku, it's also the
    unique ID.
 
-* `stack` - The application stack is what platform to run the application
-   in.
+* `stack`: The application [stack](https://devcenter.heroku.com/articles/stack) is what platform to run the application in.
 
-* `buildpacks` - A list of buildpacks that this app uses.
+* `buildpacks`: A list of buildpacks that this app uses.
 
-* `space` - The private space in which the app runs. Not present if this is a common runtime app.
+* `space`: The [space](https://devcenter.heroku.com/articles/private-spaces) in which the app runs. Not present for [Common Runtime](https://devcenter.heroku.com/articles/dyno-runtime#common-runtime) apps.
 
-* `region` - The region in which the app is deployed.
+* `region`: The region in the app is deployed in.
 
-* `git_url` - The Git URL for the application. This is used for
+* `git_url`: The Git URL for the application, used for
    deploying new versions of the app.
 
-* `web_url` - The web (HTTP) URL that the application can be accessed
-   at by default.
+* `web_url`: The web (HTTP) URL to access the application at by default.
 
-* `heroku_hostname` - The hostname for the Heroku application, suitable
+* `heroku_hostname`: The hostname for the Heroku application, suitable
    for pointing DNS records.
 
-* `last_release_id` - The last successful Release ID for the app. May be empty.
+* `last_release_id`: The last successful Release ID for the app. May be empty.
 
-* `last_slug_id` - The Slug ID from the last successful release. May be empty.
+* `last_slug_id`: The slug ID from the last successful release. May be empty.
 
-* `config_vars` - A map of all configuration variables for the app.
+* `config_vars`: The map of all configuration variables for the app.
 
-* `acm` - True if Heroku ACM is enabled for this app, false otherwise.
+* `acm`: True if [Heroku Automated Certificate Management](https://devcenter.heroku.com/articles/automated-certificate-management) is enabled for this app, false otherwise.
 
-* `organization` - The Heroku Team that owns this app. 
+* `organization`: The Heroku team that owns this app. 
 
-  * `name` - The name of the Heroku Team (organization).
+  * `name`: The name of the Heroku team (organization).
 
-  * `locked` - True if the app access is locked
+  * `locked`: True if the app access is locked
 
-  * `personal`
+  * `personal`: True for personal apps
 
-* `uuid` - The unique UUID of the Heroku app.
+* `uuid`: The unique UUID of the Heroku app.
@@ -3,23 +3,22 @@ layout: "heroku"
 page_title: "Heroku: heroku_app"
 sidebar_current: "docs-heroku-resource-app-x"
 description: |-
-  Provides a Heroku App resource. This can be used to create and manage applications on Heroku.
+  Provides a Heroku App resource. Use this resource to create and manage applications on Heroku.
 ---
 
 # heroku\_app
 
-Provides a Heroku App resource. This can be used to create and manage applications on Heroku.
+Provides a [Heroku App](https://devcenter.heroku.com/articles/platform-api-reference#app) resource. Use this resource to create and manage applications on Heroku.
 
-The Heroku platform supports two generations:
-- **Cedar** (default): Traditional platform with support for buildpacks, stack configuration, and internal routing
-- **Fir**: Next-generation platform with Cloud Native Buildpacks (CNB), enhanced security, and modern containerization
+The Heroku platform supports two [generations](https://devcenter.heroku.com/articles/generations):
+- **Cedar** (default): Legacy platform with support for classic buildpacks, stack configuration, and internal routing
+- **Fir**: Next-generation platform with enhanced security, and modern containerization
 
--> **Always reference apps by ID (UUID) in Terraform configuration**
-Starting with v5.0 of this provider, all HCL app references are by ID. Read more details in [Upgrading](guides/upgrading.html).
+-> **Note:** Always reference apps by ID (UUID) in Terraform configuration. Starting with v5.0 of this provider, all HCL app references are by ID. Read more details in [Upgrading](guides/upgrading.html).
 
 ## Example Usage
 
-### Cedar Generation (Default)
+### Cedar Generation Using Classic Buildpacks (Default)
 ```hcl-terraform
 resource "heroku_app" "cedar_app" {
   name   = "my-cedar-app"
@@ -37,9 +36,9 @@ resource "heroku_app" "cedar_app" {
 }
 ```
 
-### Fir Generation (via Fir Space)
+### Fir Generation Using Cloud Native Buildpacks (via Fir Space)
 ```hcl-terraform
-# Create a Fir generation space first
+# Create a Fir-generation space first
 resource "heroku_space" "fir_space" {
   name         = "my-fir-space"
   organization = "my-org"
@@ -61,14 +60,14 @@ resource "heroku_app" "fir_app" {
     FOOBAR = "baz"
   }
   
-  # Note: buildpacks and stack are not supported for Fir generation
+  # Note: buildpacks and stack are not supported for Fir-generation apps as they use Cloud Native Buildpacks
   # Use project.toml in your application code instead
 }
 ```
 
 ## Example Usage for a Team
 
-A Heroku "team" was originally called an "organization", and that is still the identifier used in this resource.
+A Heroku "team" was originally called an "organization", and that's still the identifier used in this resource.
 
 ```hcl-terraform
 resource "heroku_app" "default" {
@@ -83,79 +82,76 @@ resource "heroku_app" "default" {
 
 ## Argument Reference
 
-The following arguments are supported:
-
-* `name` - (Required) The name of the application. In Heroku, this is also the
-   unique ID, so it must be unique and have a minimum of 3 characters.
-* `region` - (Required) The region that the app should be deployed in.
-* `generation` - (Computed) Generation of the app platform. Automatically determined based on the space the app is deployed to. Apps in Fir generation spaces will be `fir`, all other apps will be `cedar`.
-   - `cedar`: Traditional platform supporting buildpacks, stack configuration, and internal routing
-   - `fir`: Next-generation platform with Cloud Native Buildpacks (CNB). Does not support `buildpacks`, `stack`, or `internal_routing` fields
-* `stack` - (Optional) The application stack is what platform to run the application in. **Note**: Not supported for `fir` generation apps.
-* `buildpacks` - (Optional) Buildpack names or URLs for the application.
-  Buildpacks configured externally won't be altered if this is not present. **Note**: Not supported for `fir` generation apps. Use project.toml for Cloud Native Buildpacks configuration instead.
-* `config_vars`<sup>[1](#deleting-vars)</sup> - (Optional) Configuration variables for the application.
-     The config variables in this map are not the final set of configuration
-     variables, but rather variables you want present. That is, other
-     configuration variables set externally won't be removed by Terraform
+The resource supports the following arguments:
+
+* `name`: (Required) The name of the application. In Heroku, this argument is the unique ID, so it must be unique and have a minimum of 3 characters.
+* `region`: (Required) The region to deploy the app in.
+* `generation`: (Computed) Generation of the app platform. Automatically determined based on the space the app is deployed to. Apps in Fir-generation spaces are `fir`, all other apps are `cedar`.
+   - `cedar`: Legacy platform supporting classic buildpacks, stack configuration, and internal routing.
+   - `fir`: Next-generation platform with Cloud Native Buildpacks (CNB). No support for `buildpacks`, `stack`, or `internal_routing` fields.
+* `stack`: (Optional) The name of the [stack](https://devcenter.heroku.com/articles/stack) to run the application in. **Note**: Not supported for `fir` generation apps.
+* `buildpacks`: (Optional) Classic buildpack names or URLs for the application.
+  Buildpacks configured externally won't be altered if this isn't present. **Note**: Not supported for apps using Cloud Native Buildpacks, like Fir-generation apps. Use `project.toml` for configuration instead.
+* `config_vars`<sup>[1](#deleting-vars)</sup>: (Optional) Configuration variables for the application.
+     The config variables in this map aren't the final set of configuration
+     variables, but rather variables you want present. Terraform doesn't remove configuration variables set externally
      if they aren't present in this list.
-* `sensitive_config_vars`<sup>[1](#deleting-vars)</sup> - (Optional) This argument is the same as `config_vars`.
+* `sensitive_config_vars`<sup>[1](#deleting-vars)</sup>: (Optional) This argument is the same as `config_vars`.
      The main difference between the two is when `sensitive_config_vars` outputs
-     are displayed on-screen following a terraform apply or terraform refresh,
-     they are redacted, with <sensitive> displayed in place of their value.
-     It is recommended to put private keys, passwords, etc in this argument.
-* `space` - (Optional) The name of a private space to create the app in.
-* `internal_routing` - (Optional) If true, the application will be routable
-  only internally in a private space. This option is only available for apps
-  that also specify `space`. **Note**: Not supported for `fir` generation apps.
-* `organization` - (Optional) A block that can be specified once to define
+     are displayed on-screen following a `terraform apply` or `terraform refresh`,
+     they're redacted, with `<sensitive>` displayed in place of their value.
+     It's recommended to put sensitive information like private keys, and passwords in this argument.
+* `space`: (Optional) The name of the space to create the app in.
+* `internal_routing` - (Optional) If true, the application is routable
+  only internally in Heroku Private Spaces. This option is only available for apps
+  that also specify `space`. **Note**: Only supported for apps in Cedar-generation spaces.
+* `organization`: (Optional) Specify this block once to define
      Heroku Team settings for this app. The fields for this block are
      documented below.
-* `acm` - (Optional) The flag representing Automated Certificate Management for the app.
+* `acm`: (Optional) If Automated Certificate Management is enabled for the app.
 
 The `organization` block supports:
-* `name` (string) - The name of the Heroku Team.
-* `locked` (boolean) - Are other team members forbidden from joining this app.
-* `personal` (boolean) - Force creation of the app in the user account even if a default team is set.
+* `name` (string): The name of the Heroku Team.
+* `locked` (boolean): If other team members are forbidden from joining this app.
+* `personal` (boolean): Force creation of the app in the user's account, even if a default team is set.
 
-### Deleting vars
+### Deleting Vars
 
 Deleting an entire `config_vars` or `sensitive_config_vars` map from a `heroku_app`
-configuration will not actually remove the vars on the remote resource. To remove an existing variable,
-leave these attribute maps in-place and delete only its entries from the map. Once these attributes are
-empty, the map itself may be deleted from the configuration. Otherwise if one deletes the map with existing
-entries, the config vars will not be deleted from the remote resource.
+configuration doesn't remove the variables on the remote resource. To remove an existing variable,
+leave these attribute maps in-place and only delete its entries from the map. After these attributes are
+empty, you can delete the map itself from the configuration. Otherwise, if you delete the map with existing
+entries, the config vars don't get deleted from the remote resource.
 
-This is especially important if you are migrating all `config_vars` to `sensitive_config_vars` or migrating
-config vars to `heroku_app_config_association` resource.
+If you're migrating all `config_vars` to `sensitive_config_vars`, or migrating
+config vars to `heroku_app_config_association` resource, this behavior is especially important.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `id` - The ID (UUID) of the app.
-* `name` - The name of the app.
-* `generation` - Generation of the app platform (cedar or fir). Automatically determined from the space the app is deployed to.
-* `stack` - The application stack is what platform to run the application in.
-* `space` - The private space the app should run in.
-* `internal_routing` - Whether internal routing is enabled the private space app.
-* `region` - The region that the app should be deployed in.
-* `git_url` - The Git URL for the application. This is used for
+* `id`: The ID (UUID) of the app.
+* `name`: The name of the app.
+* `generation`: Generation of the app platform (`cedar` or `fir`). Automatically determined from the space the app is deployed to.
+* `stack`: The name of the [stack](https://devcenter.heroku.com/articles/stack) the application is run in.
+* `space`: The space the app is in.
+* `internal_routing`: If internal routing is enabled. Only for apps in Heroku Private Spaces.
+* `region`: The region that the app is deployed to.
+* `git_url`: The Git URL for the application, used for
    deploying new versions of the app.
-* `web_url` - The web (HTTP) URL that the application can be accessed
-   at by default.
-* `heroku_hostname` - A hostname for the Heroku application, suitable
+* `web_url`: The web (HTTP) URL for accessing the application by default.
+* `heroku_hostname`: The hostname for the Heroku application, suitable
    for pointing DNS records.
-* `all_config_vars` - A map of all configuration variables that
+* `all_config_vars`: The map of all configuration variables that
   exist for the app, containing both those set by Terraform and those
-  set externally. (These are treated as "sensitive" so that
-  their values are redacted in console output.) This attribute is not set in state if the `provider`
+  set externally. These variables are treated as "sensitive" so that
+  their values are redacted in console output. This attribute isn't set in state if the `provider`
   attribute `set_app_all_config_vars_in_state` is `false`.
-* `uuid` - The unique UUID of the Heroku app. **NOTE:** Use this for `null_resource` triggers.
+* `uuid`: The unique UUID of the Heroku app. **Note:** Use this attribute for `null_resource` triggers.
 
-## Cloud Native Buildpacks (Fir Generation)
+## Cloud Native Buildpacks
 
-When apps are deployed to Fir generation spaces, they automatically use Cloud Native Buildpacks (CNB) instead of traditional Heroku buildpacks. This requires different configuration approaches:
+When apps are deployed to Fir-generation spaces, they automatically use Cloud Native Buildpacks (CNB) instead of classic Heroku buildpacks. CNBs require different configuration approaches:
 
 ### project.toml Configuration
 
@@ -177,11 +173,11 @@ BP_NODE_VERSION = "18.*"
 
 When migrating from Cedar to Fir generation:
 
-1. **Create Fir space**: Create a new space with `generation = "fir"`
-2. **Remove incompatible fields**: Remove `buildpacks`, `stack`, and `internal_routing` from your Terraform configuration
-3. **Add project.toml**: Create a `project.toml` file in your application code with buildpack configuration
-4. **Update app space**: Change your app's `space` to use the Fir space
-5. **Redeploy**: Deploy your application with the new configuration
+1. **Create a Fir space**: Create a new space with `generation = "fir"`.
+2. **Remove unsupported fields**: Remove `buildpacks`, `stack`, and `internal_routing` from your Terraform configuration.
+3. **Add a `project.toml` file**: Create a `project.toml` file in your application code with Cloud Native Buildpacks configuration.
+4. **Update the `space`**: Change your app's `space` to use the Fir space.
+5. **Redeploy**: Deploy your application with the new configuration.
 
 ```hcl-terraform
 # Before (Cedar)
@@ -220,12 +216,13 @@ resource "heroku_app" "example" {
 
 ## Import
 
-Apps can be imported using an existing app's `UUID` or name.
+Import apps with an existing app's `UUID` or name.
 
 For example:
 ```
 $ terraform import heroku_app.foobar MyApp
 $ terraform import heroku_app.foobar e74ac056-7d00-4a7e-aa80-df4bc413a825
 ```
 
-Please note: `config_vars` & `sensitive_config_vars` will not be imported due to limitations of Terraform's import process (see [issue](https://github.com/heroku/terraform-provider-heroku/issues/247#issuecomment-602013774)). All vars will appear to be added on the next plan/apply. The diff may be manually reconciled using the outputs of `heroku config` & `terraform plan`.
+>[!NOTE]
+>`config_vars` & `sensitive_config_vars` aren't imported due to limitations of Terraform's import process (see [issue](https://github.com/heroku/terraform-provider-heroku/issues/247#issuecomment-602013774)). All vars appear to be added on the next plan/apply. Manually reconcile the diff using the outputs of `heroku config` & `terraform plan`.
@@ -3,19 +3,20 @@ layout: "heroku"
 page_title: "Heroku: heroku_app_release"
 sidebar_current: "docs-heroku-resource-app-release"
 description: |-
-  Provides the ability to deploy a heroku release to an application
+  Provides the ability to deploy a Heroku release to an application
 ---
 
 # heroku\_app\_release
 
 Provides a [Heroku App Release](https://devcenter.heroku.com/articles/platform-api-reference#release)
 resource.
 
-An app release represents a combination of code, config vars and add-ons for an app on Heroku.
+An app release represents a combination of code, config vars and add-ons for an app on Heroku. 
 
-~> **NOTE:**
-This resource requires the slug be uploaded to Heroku using [`heroku_slug`](slug.html)
-or with external tooling prior to running terraform.
+~> **NOTE:** To use this resource, you must have uploaded a slug to Heroku using [`heroku_slug`](slug.html)
+or with external tooling prior to running Terraform.
+
+~> **NOTE:** This resource is only supported for apps that use [classic buildpacks](https://devcenter.heroku.com/articles/buildpacks#classic-buildpacks).
 
 ## Example Usage
 ```hcl-terraform
@@ -36,20 +37,20 @@ resource "heroku_app_release" "foobar-release" {
 
 The following arguments are supported:
 
-* `app_id` - (Required) Heroku app ID (do not use app name)
-* `slug_id` - unique identifier of slug
-* `description` - description of changes in this release
+* `app_id`: (Required) The Heroku app ID (not name)
+* `slug_id`: The unique identifier of slug
+* `description`: The description of changes in this release
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `id` - The ID of the app release
+* `id`: The ID of the app release
 
 ## Import
-The most recent app release can be imported using the application name.
+Import the most recent app release using the application name.
 
 For example:
 ```
 $ terraform import heroku_app_release.foobar-release foobar
-```
+```