docs: update public docs for recent features (#27)

* chore: add .worktrees/ to gitignore

* docs: update public docs for maintenance mode, env var secrets, and sensitive fields

- fleet.md: add maintenance mode section (toggle, behavior, access control)
- security.md: rewrite secret resolution to reflect env var delivery model,
  add secret name normalization rules, add sensitive fields section
- agent.md: update config response docs (checksum includes secrets,
  maintenance mode returns empty pipelines), clarify env injection
- database.md: add maintenanceMode fields to VectorNode, git fields to Environment
- pipeline-editor.md: add secret picker note for sensitive fields

* docs: fix secret collision tie-break description

The code overwrites on collision (last alphabetical match wins),
not first match.

* docs: clarify that secrets are still transmitted in config response

The hint incorrectly implied secrets are not sent over the wire.
They are — just separately from the YAML, in the config response
secrets dictionary.

Author: TerrifiedBug

.gitignore

@@ -56,4 +56,6 @@ next-env.d.ts
 # codeql
 .codeql/
 
-/scripts/*
+/scripts/*
+# worktrees
+.worktrees/

docs/public/operations/security.md

@@ -18,7 +18,7 @@ When you create or update a secret, the value is encrypted with **AES-256-GCM**
 
 ### How secrets are resolved
 
-When a pipeline is deployed, VectorFlow generates the Vector configuration file. During generation, it scans the configuration for **secret references** and replaces them with the actual decrypted values.
+When a pipeline is deployed, VectorFlow generates the Vector configuration file. During generation, it scans the configuration for **secret references** and converts them into environment variable placeholders. The actual secret values are delivered separately to the agent and injected as environment variables into the Vector process.
 
 Secret references use the syntax:
 
@@ -34,7 +34,38 @@ sasl:
   password: SECRET[KAFKA_PASSWORD]
 ```
 
-At deploy time, `SECRET[KAFKA_PASSWORD]` is resolved to the decrypted value of the `KAFKA_PASSWORD` secret in the pipeline's environment.
+At deploy time, VectorFlow converts this to:
+
+```yaml
+sasl:
+  username: "my-user"
+  password: "${VF_SECRET_KAFKA_PASSWORD}"
+```
+
+The actual decrypted value of `KAFKA_PASSWORD` is delivered to the agent in a separate `secrets` dictionary alongside the YAML. The agent sets `VF_SECRET_KAFKA_PASSWORD` as an environment variable when starting the Vector process, and Vector's built-in environment variable interpolation resolves the placeholder at runtime.
+
+{% hint style="info" %}
+Secret values never appear in pipeline YAML -- not in the database, not in config files on disk, and not in the YAML sent to agents. Only environment variable placeholders are embedded in the configuration. The actual values are delivered separately in the config response and injected as process environment variables.
+{% endhint %}
+
+#### Secret name normalization
+
+Secret names are converted to valid environment variable names using these rules:
+
+- Prefixed with `VF_SECRET_`
+- All non-alphanumeric characters replaced with underscores
+- Converted to uppercase
+
+For example, `my-api.key` becomes `VF_SECRET_MY_API_KEY`. If two secrets normalize to the same environment variable name (e.g., `db-password` and `db_password` both become `VF_SECRET_DB_PASSWORD`), VectorFlow logs a warning and the last match in alphabetical order takes precedence.
+
+### Sensitive fields
+
+Pipeline component fields that contain credentials -- passwords, API keys, tokens -- are restricted to **secret references only** in the pipeline editor. You cannot type a plaintext value into a sensitive field. Instead, the editor presents a secret picker that lets you select an existing secret or create a new one inline.
+
+Fields are treated as sensitive when:
+
+- The Vector component schema marks them as `sensitive: true`
+- The field name matches a pattern like `password`, `secret`, `token`, or `api_key`
 
 ### Certificate references
 
@@ -59,7 +90,7 @@ VectorFlow encrypts sensitive data before storing it in PostgreSQL:
 | Certificates | AES-256-GCM | SHA-256 hash of `NEXTAUTH_SECRET` |
 | OIDC client secret | AES-256-GCM | SHA-256 hash of `NEXTAUTH_SECRET` |
 | Sensitive node config fields | AES-256-GCM | SHA-256 hash of `NEXTAUTH_SECRET` |
-| Git access tokens | AES-256-GCM | SHA-256 hash of `NEXTAUTH_SECRET` |
+| Git access tokens (audit trail) | AES-256-GCM | SHA-256 hash of `NEXTAUTH_SECRET` |
 | User passwords | bcrypt (cost 12) | Built-in salt |
 | TOTP secrets | AES-256-GCM | SHA-256 hash of `NEXTAUTH_SECRET` |
 | 2FA backup codes | SHA-256 hash | -- |

docs/public/reference/agent.md

@@ -161,11 +161,16 @@ Called on every poll cycle. Returns all deployed pipeline configurations for thi
 ```
 
 Key fields:
-- **`secrets`**: Pre-resolved secret values with `VF_SECRET_` prefix. The agent injects these as environment variables into the Vector process.
+- **`configYaml`**: The generated Vector YAML. Secret references are converted to environment variable placeholders (e.g., `${VF_SECRET_AWS_KEY}`) rather than containing decrypted values.
+- **`secrets`**: Pre-resolved secret values keyed by their `VF_SECRET_` environment variable name. The agent injects these as environment variables into the Vector process, where Vector's interpolation resolves the placeholders.
+- **`checksum`**: Includes both the YAML and the secrets dictionary, so rotating a secret triggers a pipeline restart even if the YAML itself hasn't changed.
 - **`certFiles`**: Certificate data written to `<VF_DATA_DIR>/certs/` before starting the pipeline.
-- **`checksum`**: Used to detect config changes without re-parsing YAML.
 - **`pendingAction`**: Server-initiated action (currently only `self_update`).
 
+{% hint style="info" %}
+When a node is in **maintenance mode**, the config response returns an empty `pipelines` array. The agent stops all running pipelines but continues sending heartbeats. See [Fleet Management](../user-guide/fleet.md#maintenance-mode) for details.
+{% endhint %}
+
 ### `POST /api/agent/heartbeat`
 
 Called after every poll. Sends status and metrics for all managed pipelines.
@@ -228,6 +233,8 @@ Each Vector process receives:
 - `VECTOR_LOG=<logLevel>` -- controls Vector's log verbosity
 - All resolved secrets as environment variables with `VF_SECRET_` prefix (e.g., `VF_SECRET_AWS_KEY=value`)
 
+Pipeline YAML references secrets as `${VF_SECRET_NAME}` placeholders. Vector's built-in environment variable interpolation resolves these at startup, so secret values never appear in configuration files on disk.
+
 ### Metrics sidecar
 
 The agent automatically generates a sidecar config for each pipeline that adds:

docs/public/reference/database.md

@@ -125,6 +125,8 @@ Represents an enrolled agent node.
 | `vectorVersion` | `String?` | Reported Vector binary version |
 | `os` | `String?` | Operating system and architecture (e.g., `linux/amd64`) |
 | `deploymentMode` | `DeploymentMode` | `STANDALONE`, `DOCKER`, or `UNKNOWN` |
+| `maintenanceMode` | `Boolean` | Whether the node is in maintenance mode (pipelines are stopped) |
+| `maintenanceModeAt` | `DateTime?` | When the node entered maintenance mode (null if not in maintenance) |
 | `pendingAction` | `Json?` | Server-initiated action (e.g., self-update command) |
 | `createdAt` | `DateTime` | Registration timestamp |
 
@@ -142,6 +144,9 @@ Logical grouping that contains nodes, pipelines, secrets, and certificates.
 | `enrollmentTokenHint` | `String?` | First few characters of the token for display |
 | `secretBackend` | `SecretBackend` | Secret storage: `BUILTIN`, `VAULT`, `AWS_SM`, `EXEC` |
 | `secretBackendConfig` | `Json?` | Configuration for external secret backends |
+| `gitRepoUrl` | `String?` | HTTPS URL of the Git repository for pipeline audit trail |
+| `gitBranch` | `String?` | Git branch to commit pipeline YAML to (default: `main`) |
+| `gitToken` | `String?` | Encrypted access token for Git repository authentication |
 | `createdAt` | `DateTime` | Creation timestamp |
 
 ### PipelineVersion

docs/public/user-guide/fleet.md

@@ -104,6 +104,39 @@ Docker-based agents are updated by pulling the latest image. The **Update** butt
 
 Below the node list, the **Pipeline Deployment Matrix** shows a grid of all deployed pipelines across all nodes in the environment. This lets you see at a glance which pipelines are running on which nodes and their current status.
 
+## 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.
+
+### Entering maintenance mode
+
+You can toggle maintenance mode from two places:
+
+- **Fleet list** -- Click the **Maintenance** button in the node's row.
+- **Node detail page** -- Click the **Enter Maintenance** button in the header, or the **Exit Maintenance** button in the orange banner.
+
+Both locations show a confirmation dialog before entering maintenance mode. The dialog warns that all running pipelines on the node will be stopped.
+
+### What happens in maintenance mode
+
+When maintenance mode is enabled on a node:
+
+1. The node's status badge changes to an orange **Maintenance** indicator with a wrench icon.
+2. On the next poll, the agent receives an empty pipeline list from the server, causing all running pipelines to stop gracefully.
+3. The agent continues sending heartbeats, so the node remains visible and manageable in the fleet UI.
+
+{% hint style="info" %}
+Maintenance mode is per-node. Other nodes in the same environment continue running their pipelines normally.
+{% endhint %}
+
+### Exiting maintenance mode
+
+Click **Exit Maintenance** from the fleet list or the node detail page. No confirmation is required. On the next poll cycle, the agent receives its full pipeline configuration again and automatically restarts all pipelines.
+
+{% hint style="warning" %}
+Toggling maintenance mode requires the **Admin** role on the team.
+{% endhint %}
+
 ## Node management
 
 From the node detail page you can:

docs/public/user-guide/pipeline-editor.md

@@ -108,6 +108,7 @@ The panel shows:
 - **Enabled toggle** -- Disable a component to exclude it from the generated configuration without removing it from the canvas.
 - **Type** -- The Vector component type (read-only).
 - **Configuration form** -- Auto-generated form fields based on the component's configuration schema. Required fields are marked, and each field has contextual help.
+- **Secret picker** -- Sensitive fields (passwords, API keys, tokens) display a secret picker instead of a text input. You must select an existing secret or create a new one inline -- plaintext values cannot be entered directly into sensitive fields. See [Security](../operations/security.md#sensitive-fields) for details.
 
 ### VRL editor for transforms