docs: add ttl, configurable labels doc

src/pages/docs/features/_meta.ts

@@ -18,6 +18,9 @@ export default {
   "auto-deployment": {
     "title": "Auto Deploy & Labels"
   },
+  "configurable-labels": {
+    "title": "Configurable Labels"
+  },
   "template-variables": {
     "title": "Template Variables"
   },
@@ -29,5 +32,11 @@ export default {
   },
   "native-helm-deployment": {
     "title": "Native Helm Deployment"
+  },
+  "secrets": {
+    "title": "Cloud Secrets"
+  },
+  "environment-ttl": {
+    "title": "Environment TTL"
   }
 };

src/pages/docs/features/configurable-labels.mdx

@@ -0,0 +1,84 @@
+---
+title: Configurable Labels
+tags:
+  - labels
+  - configuration
+  - deploy
+  - disabled
+  - keep
+  - status-comments
+  - global-config
+---
+
+import { Callout } from "nextra/components";
+
+Lifecycle allows you to customize the GitHub labels that control environment deployments, TTL behavior, and status comments through the `global_config.labels` configuration.
+
+## Configuration
+
+The labels configuration is stored in the `global_config` table with the key `labels`:
+
+```json
+{
+  "deploy": ["lifecycle-deploy!", "lfc-deploy"],
+  "disabled": ["lifecycle-disabled!", "lfc-skip"],
+  "keep": ["lifecycle-keep!", "lfc-keep"],
+  "statusComments": ["lifecycle-status-comments!"],
+  "defaultStatusComments": true,
+  "defaultControlComments": true
+}
+```
+
+### `deploy`
+
+Labels that trigger environment deployment. When any deploy label is added to a PR, Lifecycle creates an ephemeral environment. The first label in the array is used when adding labels programmatically. Supports multiple labels for different teams or naming conventions.
+
+**Default:** `["lifecycle-deploy!"]`
+
+### `disabled`
+
+Labels that prevent or teardown deployments. When any disabled label is added or deploy label is removed, the active environment will be torn down.
+
+**Default:** `["lifecycle-disabled!"]`
+
+### `keep`
+
+Labels that disable TTL cleanup for an environment. When present on a PR, prevents automatic teardown due to inactivity and sets `lfc/ttl-enable: false` on the Kubernetes namespace.
+
+**Default:** `["lifecycle-keep!"]`
+
+### `statusComments`
+
+Labels that control status comment visibility on a per-PR basis. Behavior depends on the `defaultStatusComments` setting.
+
+**Default:** `["lifecycle-status-comments!"]`
+
+### `defaultStatusComments`
+
+Controls whether status comments are enabled by default across all PRs. When `true`, status comments show for all PRs. When `false`, status comments only show when the status comment label is present.
+
+**Default:** `true`
+
+### `defaultControlComments`
+
+Enables or disables control-related comments system-wide.
+
+**Default:** `true`
+
+<Callout type="warning">
+  Changes to label configuration require refreshing the global config cache or
+  waiting for the automatic refresh cycle.
+</Callout>
+
+---
+
+## Summary
+
+| Property                 | Type     | Purpose                             |
+| ------------------------ | -------- | ----------------------------------- |
+| `deploy`                 | string[] | Trigger environment deployment      |
+| `disabled`               | string[] | Prevent or teardown deployments     |
+| `keep`                   | string[] | Disable TTL cleanup                 |
+| `statusComments`         | string[] | Control status comment visibility   |
+| `defaultStatusComments`  | boolean  | Enable status comments by default   |
+| `defaultControlComments` | boolean  | Enable control comments system-wide |

src/pages/docs/features/environment-ttl.mdx

@@ -0,0 +1,92 @@
+---
+title: Environment TTL
+tags:
+  - ttl
+  - cleanup
+  - lifecycle-keep
+  - inactivity
+  - global-config
+---
+
+import { Callout } from "nextra/components";
+
+Lifecycle automatically cleans up inactive ephemeral environments based on configurable TTL (Time To Live) settings. This helps reduce resource usage while allowing teams to keep environments alive when needed.
+
+## Configuration
+
+The TTL cleanup configuration is stored in the `global_config` table with the key `ttl_cleanup`:
+
+```json
+{
+  "enabled": true,
+  "dryRun": false,
+  "inactivityDays": 14,
+  "checkIntervalMinutes": 240,
+  "commentTemplate": "This environment has been inactive for {inactivityDays} days and will be automatically cleaned up.",
+  "excludedRepositories": []
+}
+```
+
+### `enabled`
+
+Enables or disables automatic cleanup of inactive environments.
+
+**Default:** `false`
+
+### `dryRun`
+
+Runs cleanup process without actually tearing down environments. Useful for testing.
+
+**Default:** `true`
+
+### `inactivityDays`
+
+Number of days of inactivity before an environment is eligible for cleanup.
+
+**Default:** `14`
+
+### `checkIntervalMinutes`
+
+How frequently the cleanup job runs to check for stale environments.
+
+**Default:** `240` (4 hours)
+
+### `commentTemplate`
+
+Custom message posted to the PR when cleaning up. Supports `{inactivityDays}` placeholder and dynamic label replacements.
+
+**Default:** `"Tearing down lifecycle env since no activity in the past {inactivityDays} days."`
+
+### `excludedRepositories`
+
+Repository names (format: `owner/repo`) to exclude from automatic cleanup.
+
+**Default:** `[]`
+
+<Callout type="warning">
+  Changes to TTL configuration require refreshing the global config cache or
+  waiting for the automatic refresh cycle.
+</Callout>
+
+---
+
+## How It Works
+
+Lifecycle tracks environment expiration using `lfc/ttl-expireAtUnix` labels on Kubernetes namespaces. The cleanup service runs periodically to scan for expired environments, validates eligibility (PR is open, not static, not excluded), and tears down environments by removing the deploy label and adding the disabled label.
+
+### Preventing Cleanup
+
+Add the `keep` label to a PR to prevent automatic cleanup. This disables TTL on the namespace and keeps the environment alive indefinitely. See [Configurable Labels](/docs/features/configurable-labels) to customize the keep label.
+
+---
+
+## Summary
+
+| Property               | Type     | Purpose                            |
+| ---------------------- | -------- | ---------------------------------- |
+| `enabled`              | boolean  | Enable/disable automatic cleanup   |
+| `dryRun`               | boolean  | Test mode without actual cleanup   |
+| `inactivityDays`       | number   | Days of inactivity before cleanup  |
+| `checkIntervalMinutes` | number   | Cleanup job frequency in minutes   |
+| `commentTemplate`      | string   | Custom cleanup message for PRs     |
+| `excludedRepositories` | string[] | Repositories excluded from cleanup |