TerrifiedBug · TerrifiedBug · Mar 27, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/docs/public/SUMMARY.md b/docs/public/SUMMARY.md
@@ -31,6 +31,7 @@
 * [Service Accounts](operations/service-accounts.md)
 * [Backup &amp; Restore](operations/backup-restore.md)
 * [GitOps](operations/gitops.md)
+* [Outbound Webhooks](operations/outbound-webhooks.md)
 * [Security](operations/security.md)
 * [Upgrading](operations/upgrading.md)
 

diff --git a/docs/public/operations/outbound-webhooks.md b/docs/public/operations/outbound-webhooks.md
@@ -0,0 +1,154 @@
+# Outbound Webhooks
+
+VectorFlow can send HMAC-signed HTTP notifications to external systems when key events occur. Use outbound webhooks to integrate with incident management tools, CI/CD pipelines, custom dashboards, or any service that accepts HTTP callbacks.
+
+## Overview
+
+Each **webhook endpoint** is a URL that receives POST requests when one or more subscribed events fire. Requests carry Standard-Webhooks-compliant signature headers so receivers can verify authenticity.
+
+Key properties of each endpoint:
+
+- **Name** — A descriptive label shown in the management UI.
+- **URL** — The HTTPS endpoint that receives event payloads.
+- **Event types** — One or more event types that trigger delivery.
+- **Signing secret** — Optional HMAC key. When set, every request includes a `webhook-signature` header.
+- **Enabled / Disabled** — Endpoints can be temporarily disabled without deleting them.
+
+## Supported events
+
+| Event | When it fires |
+|-------|---------------|
+| `deploy_completed` | A pipeline deployment completed successfully |
+| `deploy_rejected` | A deployment request was rejected |
+| `deploy_cancelled` | A pending deployment was cancelled |
+| `pipeline_crashed` | A running pipeline process exited unexpectedly |
+| `node_unreachable` | A fleet node stopped sending heartbeats |
+| `node_joined` | A new fleet node enrolled |
+| `node_left` | A fleet node was removed |
+| `promotion_completed` | A pipeline was promoted to another environment |
+
+## Creating a webhook endpoint
+
+{% stepper %}
+{% step %}
+### Open Webhook Settings
+Navigate to **Settings → Outbound Webhooks**.
+{% endstep %}
+{% step %}
+### Click New Endpoint
+Click the **New Endpoint** button in the top-right corner.
+{% endstep %}
+{% step %}
+### Fill in the form
+- **Name** — A descriptive label (e.g., "PagerDuty Pipeline Alerts").
+- **Endpoint URL** — The HTTPS URL that will receive events.
+- **Signing secret** — Optional. If provided, every request is signed and the secret is shown once — copy it before closing the dialog.
+- **Event types** — Select one or more events this endpoint should receive.
+{% endstep %}
+{% step %}
+### Create
+Click **Create**. If you provided a signing secret, the dialog shows it once — copy it to a secure location.
+{% endstep %}
+{% endstepper %}
+
+{% hint style="warning" %}
+The signing secret is displayed once at creation time and cannot be retrieved afterwards. Store it securely in your receiving application's configuration.
+{% endhint %}
+
+## Payload format
+
+All webhook deliveries use the same envelope format:
+
+```json
+{
+  "type": "deploy_completed",
+  "timestamp": "2026-03-27T12:00:00.000Z",
+  "data": {
+    // Event-specific fields
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `type` | The `AlertMetric` value that triggered this delivery |
+| `timestamp` | ISO-8601 UTC timestamp of the event |
+| `data` | Event-specific payload fields |
+
+## Verifying signatures
+
+When a signing secret is configured, every request includes three headers:
+
+| Header | Description |
+|--------|-------------|
+| `webhook-id` | Unique UUID for this delivery |
+| `webhook-timestamp` | Unix timestamp (integer seconds) |
+| `webhook-signature` | `v1,{base64(HMAC-SHA256)}` |
+
+To verify a request, compute:
+
+```
+signing_string = "{webhook-id}.{webhook-timestamp}.{raw_request_body}"
+expected_sig   = base64( HMAC-SHA256(signing_string, secret) )
+```
+
+The received signature header is `v1,{expected_sig}`. Compare the value after the `v1,` prefix.
+
+{% hint style="info" %}
+VectorFlow follows the [Standard Webhooks](https://www.standardwebhooks.com/) specification. Libraries are available for most languages.
+{% endhint %}
+
+## Delivery and retry
+
+VectorFlow attempts delivery immediately when an event fires. If the request fails, it retries with exponential backoff:
+
+| Attempt | Delay |
+|---------|-------|
+| 1 | Immediate |
+| 2 | 30 seconds |
+| 3 | 5 minutes |
+| 4 | 30 minutes |
+| 5+ | 2 hours |
+
+**Permanent failures** (HTTP 4xx excluding 429, DNS errors, connection refused) are moved to **dead-letter** immediately and are not retried.
+
+**Transient failures** (HTTP 5xx, HTTP 429, timeouts) are retried up to the schedule above.
+
+## Delivery history
+
+Each endpoint row in the settings UI can be expanded to show recent deliveries:
+
+- **Event type** — Which event triggered the delivery.
+- **Status** — `success`, `failed`, `dead_letter`, or `pending`.
+- **HTTP status** — The HTTP status code returned by the receiver.
+- **Attempt** — Which retry attempt this represents.
+- **Requested / Completed** — Relative timestamps.
+
+## Test delivery
+
+To send a test delivery to an endpoint without waiting for a real event, click the **Play** button (&#9654;) in the endpoint row. The test payload is:
+
+```json
+{
+  "type": "test",
+  "timestamp": "2026-03-27T12:00:00.000Z",
+  "data": {
+    "message": "Test delivery from VectorFlow",
+    "endpointId": "..."
+  }
+}
+```
+
+The UI shows a success or failure notification. Check delivery history for the HTTP status code and any error details.
+
+## Managing endpoints
+
+| Action | How |
+|--------|-----|
+| **Enable / Disable** | Click the toggle icon in the endpoint row |
+| **Edit** | Click the pencil icon to update name, URL, events, or rotate the secret |
+| **Delete** | Click the trash icon — all delivery history is also deleted |
+
+{% hint style="info" %}
+Disabling an endpoint stops deliveries immediately without deleting the endpoint or its history. Re-enable it when ready to receive events again.
+{% endhint %}
diff --git a/docs/public/reference/api.md b/docs/public/reference/api.md
@@ -479,6 +479,50 @@ Common error codes:
 
 ---
 
+## OpenAPI Specification
+
+VectorFlow provides a machine-readable [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) specification covering all REST v1 endpoints and key tRPC procedures.
+
+### Fetching the spec
+
+```bash
+curl -s https://vectorflow.example.com/api/v1/openapi.json | jq .info
+```
+
+The spec is served at `/api/v1/openapi.json` with CORS enabled — you can fetch it from any origin without credentials.
+
+### Importing into tools
+
+**Postman:** File > Import > paste URL `https://vectorflow.example.com/api/v1/openapi.json`
+
+**Swagger UI / Stoplight:** Point to the spec URL or paste the JSON content.
+
+### Client generation
+
+Generate a typed API client in any language using [openapi-generator](https://openapi-generator.tech/):
+
+```bash
+npx @openapitools/openapi-generator-cli generate \
+  -i https://vectorflow.example.com/api/v1/openapi.json \
+  -g python \
+  -o ./vectorflow-client
+```
+
+### What's included
+
+The spec documents two API surfaces:
+
+| Surface | Auth | Endpoints |
+|---------|------|-----------|
+| REST v1 (`/api/v1/*`) | Service account Bearer token | Pipeline CRUD, deploy, rollback, nodes, secrets, alerts, audit |
+| tRPC (`/api/trpc/*`) | Session cookie | Pipeline management, fleet, environments, secrets, deploy, alerts, service accounts |
+
+{% hint style="info" %}
+**tRPC encoding note:** tRPC endpoints use [SuperJSON](https://github.com/blitz-js/superjson) encoding. For queries, input is URL-encoded JSON in `?input=` (wrap as `{"json": <input>}`). For mutations, the body is `{"json": <input>}`. Using a tRPC client is recommended for full type safety; the OpenAPI spec is provided for discoverability and non-TypeScript integrations.
+{% endhint %}
+
+---
+
 ## REST API (v1)
 
 The REST API provides a standard HTTP interface for automation and CI/CD. All endpoints require a [Service Account](../operations/service-accounts.md) API key.

diff --git a/docs/public/user-guide/fleet.md b/docs/public/user-guide/fleet.md
@@ -166,6 +166,75 @@ The deploy dialog shows a live count of matching nodes (e.g., "3 of 5 nodes matc
 Changing a pipeline's node selector on a subsequent deploy updates the targeting. Nodes that no longer match will stop the pipeline on their next poll.
 {% endhint %}
 
+## Node groups
+
+Node groups let administrators segment their fleet into logical clusters based on node labels -- for example by datacenter, role, or region. Groups are managed from **Settings > Fleet**.
+
+Each node group has:
+
+| Field | Description |
+|-------|-------------|
+| **Name** | A unique display name for the group within the environment. |
+| **Criteria** | A label selector (key-value pairs) that determines which enrolling nodes match the group. An empty criteria matches all nodes. |
+| **Label template** | Key-value labels that are automatically merged into a node's labels when it enrolls and matches the group's criteria. |
+| **Required labels** | Label keys that every node should have. Nodes missing any required label are flagged as non-compliant in the fleet list. |
+
+{% hint style="info" %}
+Label templates are applied once at enrollment time. Changing a group's template does not retroactively update existing nodes.
+{% endhint %}
+
+## Label compliance
+
+When node groups define **required labels**, the fleet list displays a **Non-compliant** badge next to any node that is missing one or more of those labels. This is a warn-only indicator -- non-compliant nodes continue to receive heartbeats and deployments normally.
+
+To resolve a non-compliant node, add the missing labels via the node detail page or ensure the node enrolls with matching labels so that group templates apply automatically.
+
+## Fleet health dashboard
+
+The Health tab on the Fleet page provides an aggregated view of fleet status organized by node group. This is especially useful for large fleets where you want to see health at a glance before drilling into individual nodes.
+
+### Group summary cards
+
+Each node group is represented as a collapsible card showing three metrics:
+
+| Metric | Description |
+|--------|-------------|
+| **Online** | Count of HEALTHY nodes out of the group total (e.g. `4/5`). Shown in amber when any nodes are offline. |
+| **Alerts** | Count of nodes with at least one firing alert rule. Shown in red when greater than zero. |
+| **Compliance** | Percentage of nodes that have all required labels defined by the group. Shown in amber when below 100%. |
+
+### Drill-down
+
+Click any group card to expand it and see a per-node detail table with:
+
+- **Name** — the node name, linked to its detail page
+- **Status** — current health status badge (Healthy, Degraded, Unreachable, Unknown)
+- **CPU Load** — the 1-minute load average from the latest heartbeat, or `--` if no metrics are available
+- **Last Seen** — how long ago the node last sent a heartbeat
+- **Compliance** — whether the node has all required labels for the group
+
+Nodes are sorted by health status with the least healthy nodes shown first, then alphabetically by name.
+
+### Filtering
+
+The toolbar above the group cards supports three filter types:
+
+- **Group** — show only a specific group card
+- **Labels** — filter by label key/value pairs (applied to the per-node detail table inside expanded cards)
+- **Compliance** — toggle between All, Compliant (100% compliance rate), or Non-compliant (below 100%)
+
+{% hint style="info" %}
+Filter state is stored in the URL as query parameters, so you can copy and share the URL with filters applied.
+{% endhint %}
+
+### Ungrouped nodes
+
+Nodes that do not match the criteria of any defined group appear under an **Ungrouped** card. This card behaves the same as any other group card — you can expand it to see the per-node table.
+
+{% hint style="info" %}
+The Ungrouped card only appears when at least one node exists outside all group criteria. If all nodes belong to a group, no Ungrouped card is shown.
+{% endhint %}
+
 ## Maintenance mode
 
 Maintenance mode lets you temporarily stop all pipelines on a node without removing it from the fleet. This is useful for host upgrades, kernel patches, disk maintenance, or any situation where you need the node idle but still connected.

diff --git a/docs/public/user-guide/pipeline-editor.md b/docs/public/user-guide/pipeline-editor.md
@@ -258,6 +258,32 @@ Click the pipeline name in the top-left corner of the editor to rename it inline
 On Windows and Linux, use `Ctrl` instead of `Cmd` for all keyboard shortcuts.
 {% endhint %}
 
+## Cross-Environment Promotion
+
+Promote a pipeline from one environment to another (e.g., dev to staging, staging to production) with built-in validation and approval workflow.
+
+### Promoting a Pipeline
+
+1. From the pipeline list, click the **...** menu on any pipeline and select **Promote to...**
+2. Select the **target environment** and optionally rename the pipeline
+3. VectorFlow validates that all secret references in the pipeline exist in the target environment
+4. Review the **substitution diff** showing what will change between environments
+5. Click **Confirm Promotion** to submit
+
+### Approval Workflow
+
+If the target environment has **Require Deploy Approval** enabled, the promotion creates a request that must be approved by an administrator before the pipeline appears in the target environment.
+
+If approval is not required, the pipeline is promoted immediately.
+
+### Secret Pre-flight Validation
+
+Before promotion proceeds, VectorFlow checks that every `SECRET[name]` reference in the source pipeline has a corresponding secret defined in the target environment. If any secrets are missing, promotion is blocked with a clear list of which secrets need to be created.
+
+### Promotion History
+
+Each pipeline's detail page shows a promotion history log with source environment, target environment, who promoted, and the current status.
+
 ## AI-Powered Suggestions
 
 When AI is configured for your team (Settings → AI), two AI features become available:

diff --git a/package.json b/package.json
@@ -9,13 +9,15 @@
     "start": "next start",
     "lint": "eslint",
     "test": "vitest run",
-    "postinstall": "prisma generate"
+    "postinstall": "prisma generate",
+    "generate:openapi": "tsx scripts/generate-openapi.ts"
   },
   "dependencies": {
     "@auth/prisma-adapter": "^2.11.1",
     "@dagrejs/dagre": "^2.0.4",
     "@hookform/resolvers": "^5.2.2",
     "@monaco-editor/react": "^4.7.0",
+    "@octokit/rest": "^22.0.1",
     "@prisma/adapter-pg": "^7.4.2",
     "@prisma/client": "^7.4.2",
     "@prisma/client-runtime-utils": "^7.4.2",
@@ -68,6 +70,7 @@
     }
   },
   "devDependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.5.0",
     "@next/bundle-analyzer": "^16.2.1",
     "@tailwindcss/postcss": "^4",
     "@types/bcryptjs": "^3.0.0",