docs: add retrieve app deployments based on last used data docs and product update

packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx

@@ -0,0 +1,65 @@
+---
+title: Find and Clean Up Stale App Deployments
+description: Query app deployments by last usage to identify candidates for retirement.
+date: 2025-12-09
+authors: [adam]
+---
+
+Hive now tracks when each app deployment was last used, helping you identify stale deployments that
+are candidates for retirement.
+
+## Query Stale Deployments
+
+Use the new `activeAppDeployments` query to find deployments based on usage:
+
+```graphql
+query FindStaleDeployments($target: TargetReferenceInput!) {
+  target(reference: $target) {
+    activeAppDeployments(
+      filter: {
+        # Deployments last used more than 30 days ago
+        lastUsedBefore: "2024-11-01T00:00:00Z"
+        # OR deployments never used and older than 30 days
+        neverUsedAndCreatedBefore: "2024-11-01T00:00:00Z"
+      }
+    ) {
+      edges {
+        node {
+          name
+          version
+          createdAt
+          lastUsed
+        }
+      }
+    }
+  }
+}
+```
+
+## Filter Options
+
+| Filter                      | Description                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| `name`                      | Filter by deployment name (case-insensitive partial match) |
+| `lastUsedBefore`            | Deployments last used before this timestamp                |
+| `neverUsedAndCreatedBefore` | Deployments never used and created before this timestamp   |
+
+The date filters use OR semantics—deployments matching either condition are returned.
+
+## Automated Cleanup
+
+For teams creating many deployments (e.g., one per PR), you can automate cleanup by combining the
+GraphQL API with the Hive CLI:
+
+```bash
+# Query stale deployments via GraphQL API, then retire each one:
+hive app:retire \
+  --registry.accessToken "<ACCESS_TOKEN>" \
+  --target "<ORG>/<PROJECT>/<TARGET>" \
+  --name "<app-name>" \
+  --version "<app-version>"
+```
+
+---
+
+- [Learn more about App Deployments](/docs/schema-registry/app-deployments)

packages/web/docs/src/content/schema-registry/app-deployments.mdx

@@ -258,6 +258,88 @@ change to **retired**.
 
 - [`app:retire` API Reference](https://github.com/graphql-hive/console/tree/main/packages/libraries/cli#hive-appretire)
 
+## Finding Stale App Deployments
+
+Hive tracks usage data for your app deployments. Each time a GraphQL request uses a persisted
+document from an app deployment, Hive records when it was last used. This data helps you identify
+app deployments that are candidates for retirement.
+
+### Usage Tracking
+
+When your GraphQL server or gateway reports usage to Hive, the `lastUsed` timestamp for the
+corresponding app deployment is updated. You can see this information in the Hive dashboard or query
+it via the GraphQL API.
+
+### Querying Stale Deployments via GraphQL API
+
+You can use the `activeAppDeployments` query to find app deployments that match specific criteria.
+The date filters (`lastUsedBefore`, `neverUsedAndCreatedBefore`) use OR semantics. deployments
+matching **either** date condition are returned. The `name` filter uses AND semantics to narrow down
+results.
+
+```graphql
+query FindStaleDeployments($target: TargetReferenceInput!) {
+  target(reference: $target) {
+    activeAppDeployments(
+      filter: {
+        # Optional: filter by app name (case-insensitive partial match)
+        name: "my-app"
+        # Deployments last used more than 30 days ago
+        lastUsedBefore: "2024-11-01T00:00:00Z"
+        # OR deployments that have never been used and are older than 30 days
+        neverUsedAndCreatedBefore: "2024-11-01T00:00:00Z"
+      }
+    ) {
+      edges {
+        node {
+          name
+          version
+          createdAt
+          lastUsed
+        }
+      }
+    }
+  }
+}
+```
+
+| Filter Parameter            | Description                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------ |
+| `name`                      | Filter by app deployment name (case-insensitive partial match). Uses AND semantics.              |
+| `lastUsedBefore`            | Return deployments that were last used before this timestamp. Uses OR with other date filter.    |
+| `neverUsedAndCreatedBefore` | Return deployments never used and created before this timestamp. Uses OR with other date filter. |
+
+### Retirement Workflow
+
+A typical workflow for retiring stale deployments:
+
+1. **Query stale deployments** using the `activeAppDeployments` query with appropriate filters
+2. **Review the results** to ensure you're not retiring deployments still in use
+3. **Retire deployments** using the `app:retire` CLI command or GraphQL mutation
+
+### Automated Cleanup
+
+For teams with many app deployments (e.g., one per PR or branch), you can automate cleanup by
+combining the GraphQL API with the Hive CLI.
+
+Example script pattern:
+
+```bash
+# Query stale deployments via GraphQL API
+# Parse the response to get app names and versions
+# Retire each deployment using the CLI:
+hive app:retire \
+  --registry.accessToken "<ACCESS_TOKEN>" \
+  --target "<ORGANIZATION>/<PROJECT>/<TARGET>" \
+  --name "<app-name>" \
+  --version "<app-version>"
+```
+
+<Callout type="warning">
+  Always review deployments before retiring them programmatically. Consider protecting your latest
+  production deployment to avoid accidentally retiring active versions.
+</Callout>
+
 ## Persisted Documents on GraphQL Server and Gateway
 
 Persisted documents can be used on your GraphQL server or Gateway to reduce the payload size of your