Fill gaps from assistant conversations: CLI, deploy, associations

src/cli/reference.mdx

@@ -1,3 +1,8 @@
+---
+title: "CLI reference"
+description: "Reference for Ampersand CLI commands, including login, deploy, delete, and listing your projects, integrations, installations, and destinations."
+---
+
 This section provides a detailed overview of the Ampersand CLI, including the available commands, their usage, and options.
 
 ## Usage
@@ -123,6 +128,7 @@ amp deploy <folder_with_amp.yaml> --project <id-or-name> [--key <api-key>] [--de
 - Requires a folder containing an `amp.yaml` file.
 - Use this command to deploy new integrations or update existing ones.
 - Use this command when you've made changes to your integration
+- Deploying creates a new [revision](/terminology#revision) of the integration. It does not change the saved configuration of existing installations. To add a newly deployed object to an existing installation, update its config with the [Update an installation](/reference/installation/update-an-installation) endpoint or have the customer update it through your install UI. Objects with `enabled: always` in the manifest are the exception: they apply to every installation as soon as you deploy. See the [manifest reference](/manifest-reference#read-object).
 
 **Example:**
 
@@ -205,6 +211,9 @@ Displays all current installations of a given integration in your project.
 amp list:installations <integration-id> --project <id-or-name> [--key <api-key>] [--debug]
 ```
 
+**Notes:**
+- The CLI does not filter this list by installation ID or customer. To fetch a single installation by its ID, use the [Get an installation](/reference/installation/get-an-installation) endpoint. To filter by customer, pass the `groupRef` query parameter to the [List installations for an integration](/reference/installation/list-installations-for-an-integration) or [List installations for a project](/reference/installation/list-installations-for-a-project) endpoints.
+
 **Example:**
 
 ```bash

src/manifest-reference.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Manifest schema reference"
 sidebarTitle: "Manifest schema"
+description: "Full schema reference for the amp.yaml manifest file, covering read, write, subscribe, and proxy actions, objects, fields, and mappings."
 ---
 
 ## Introduction
@@ -201,7 +202,7 @@ Each object in the `objects` array defines a specific data type to read from the
 | `objectName` | String | Yes | The [name of the object](#object-name) to read (e.g., `contact`, `lead`, `account`). This must match an object type supported by the provider's API (see note below). Case-sensitive. |
 | `destination` | String | Yes | The [webhook destination](#destination) for the read data. This determines where the data will be sent after it's read. Must match a webhook configured in your Ampersand account. See [Destinations](/destinations) for setup. |
 | `schedule` | String | Yes | A [cron schedule](#schedule) for reading the data. Defines how frequently the data should be read. Uses standard cron syntax. Examples: `*/10 * * * *` (every 10 minutes), `0 0 * * *` (daily at midnight). |
-| `enabled` | String | No | If set to `always`, Ampersand reads this object for every installation even if the customer never selects it (or it isn't present) in the installation config. |
+| `enabled` | String | No | If set to `always`, Ampersand reads this object for every installation even if the customer never selects it (or it isn't present) in the installation config. This includes existing installations: when you deploy a manifest that adds an object with `enabled: always`, Ampersand starts reading it for all installations without any installation config updates. |
 | `backfill` | Object | No | [Configuration for backfilling](#backfill) historical data. Defines how historical data should be loaded. See [backfill behavior](/read-actions#backfill-behavior) for details. |
 | `requiredFields` | Array | No | Fields that are always read for every customer. These fields will always be included in the data that's read. See [Field Configuration](#field) for more details. |
 | `optionalFields` | Array | No | Optional fields that can be included. Customers can choose which of these fields to include. See [Field Configuration](#field) for more details. |

src/provider-guides/hubspot.mdx

@@ -1,5 +1,6 @@
 ---
 title: "HubSpot"
+description: "How to integrate with HubSpot using Ampersand: supported actions and objects, creating a HubSpot app, and publishing to the HubSpot marketplace."
 ---
 
 ## What's Supported
@@ -106,6 +107,8 @@ To read users from your customer's HubSpot workspace, enable the `crm.objects.us
   HubSpot associations is a private preview feature where you can retrieve associated records when using Read Actions or Subscribe Actions. Please contact support@withampersand.com if you wish to use it.
 </Note>
 
+HubSpot is the only provider that supports subscribing to association change events. Use `associationChangeEvent` in your `amp.yaml` to receive an event when a record's associations change. In HubSpot, association changes do not trigger update events, so you must subscribe to them with `associationChangeEvent`. See [Association changes](/subscribe-actions#association-changes) for the manifest syntax and payload format.
+
 ### Example Integration
 
 For an example manifest file, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/hubspot/amp.yaml).