docs: update public docs for recent features

[TerrifiedBug]

Summary

Updates public documentation (synced to GitBook) to cover features shipped in PRs #19–#26:

• Fleet Management (fleet.md): New "Maintenance mode" section documenting per-node maintenance toggle, behavior (empty pipeline list → graceful stop), and ADMIN access requirement
• Security (security.md): Rewrote "How secrets are resolved" to reflect env var delivery model (SECRET[name] → ${VF_SECRET_NAME} placeholders), added secret name normalization rules, added "Sensitive fields" section for secret-picker-only enforcement
• Agent Reference (agent.md): Updated config response documentation (checksum now includes secrets dict, maintenance mode returns empty pipelines array), clarified environment injection behavior
• Database Schema (database.md): Added maintenanceMode/maintenanceModeAt fields to VectorNode table, added gitRepoUrl/gitBranch/gitToken fields to Environment table
• Pipeline Editor (pipeline-editor.md): Added secret picker note for sensitive fields in detail panel

Test plan

• Verify GitBook renders all pages without syntax errors
• Confirm internal cross-references resolve (fleet.md#maintenance-mode, security.md#sensitive-fields)
• Review each section against the actual UI behavior

[greptile-apps]

Greptile Summary

This PR updates five public documentation pages to reflect features shipped in PRs #19–#26, covering maintenance mode for fleet nodes, the revised secret env-var delivery model, agent config response details, database schema additions, and the pipeline editor's secret picker. The docs are well-aligned with the implementation, with one correctness gap in the agent.md checksum description.

Key changes:

• security.md: Rewrites secret resolution to accurately describe SECRET[name] → ${VF_SECRET_NAME} conversion, correctly documents collision behaviour as last-match-alphabetical (fixing the prior thread concern), and qualifies the hint box so it no longer implies secrets are "not in transit" — consistent with the code sending decrypted values in the config response.
• agent.md: Clarifies configYaml, secrets, and checksum field descriptions; adds maintenance-mode hint linking to fleet.md; adds env-injection paragraph. The checksum description overstates the automatic-restart guarantee — it applies only to the BUILTIN secret backend; external backends (Vault, AWS SM, EXEC) are not covered.
• database.md: Accurately documents maintenanceMode/maintenanceModeAt on VectorNode and gitRepoUrl/gitBranch/gitToken on Environment, both verified against prisma/schema.prisma.
• fleet.md: Accurate description of maintenance-mode toggle, per-node scope, empty-pipelines behaviour, and Admin role requirement.
• pipeline-editor.md: One-line addition for secret picker in the detail panel.

Confidence Score: 4/5

• Safe to merge with one minor doc fix — the checksum description in agent.md is misleading for external secret backend users.
• All schema and API behaviour claims were verified against the implementation. The only inaccuracy is a documentation omission (checksum does not include secrets for non-BUILTIN backends) that could mislead operators using Vault/AWS_SM into believing secret rotation auto-restarts pipelines when it does not. All other changes are accurate and the prior thread concerns have been properly addressed.
• docs/public/reference/agent.md — checksum field description needs a caveat for external secret backends.

Important Files Changed

Filename	Overview
docs/public/operations/security.md	Rewrote "How secrets are resolved" to accurately reflect env-var delivery model; fixed "not in transit" mislead from a prior thread; correctly documents collision behaviour as last-match-alphabetical; added sensitive-fields section. No inaccuracies found.
docs/public/reference/agent.md	Clarified configYaml/secrets/checksum field descriptions and maintenance-mode behaviour; checksum description overstates automatic restart for external secret backends — applies only to BUILTIN.
docs/public/reference/database.md	Accurately documents new maintenanceMode/maintenanceModeAt fields on VectorNode and gitRepoUrl/gitBranch/gitToken fields on Environment — consistent with prisma/schema.prisma.
docs/public/user-guide/fleet.md	New maintenance-mode section accurately describes the toggle locations, the empty-pipelines behaviour on next poll, heartbeat continuation, and Admin role requirement — all consistent with the implementation.
docs/public/user-guide/pipeline-editor.md	Minor one-line addition documenting the secret picker for sensitive fields; cross-reference to security.md#sensitive-fields is correct.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Server
    participant Vector

    Note over Agent,Server: Normal operation (BUILTIN backend)
    Agent->>Server: GET /api/agent/config
    Server-->>Agent: pipelines with configYaml (env var placeholders) and secrets dict
    Agent->>Vector: spawn with resolved env vars injected
    Note over Vector: interpolates placeholders at startup

    Note over Agent,Server: Node enters maintenance mode
    Agent->>Server: GET /api/agent/config
    Server-->>Agent: empty pipelines array
    Agent->>Vector: SIGTERM (graceful stop all pipelines)
    Agent->>Server: POST /api/agent/heartbeat (continues normally)

    Note over Agent,Server: Exit maintenance mode
    Agent->>Server: GET /api/agent/config
    Server-->>Agent: full pipeline configurations restored
    Agent->>Vector: restart all pipelines

Loading

_{Last reviewed commit: 0e9e6cc}

[greptile-apps]

Checksum-includes-secrets claim only holds for BUILTIN backend

The updated description says the 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." This is only true when secretBackend === "BUILTIN".

Looking at src/app/api/agent/config/route.ts (lines 77–90 and 124–128):

// secrets is only populated for BUILTIN
const secrets: Record<string, string> = {};
if (environment.secretBackend === "BUILTIN") {
  // ...populate secrets...
}

// checksum only includes secrets when secrets is non-empty (i.e., BUILTIN only)
const checksumInput = Object.keys(secrets).length > 0
  ? configYaml + JSON.stringify(secrets, Object.keys(secrets).sort())
  : configYaml;

For VAULT, AWS_SM, or EXEC backends the secrets map stays empty, the checksum equals the YAML alone, and rotating a secret in the external store will not trigger a pipeline restart via this mechanism. Operators using an external backend who rotate secrets will need to trigger a restart manually.

The description should qualify this behaviour:

Suggested change

	- **`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.
	- **`checksum`**: Includes both the YAML and the secrets dictionary (BUILTIN backend only), so rotating a secret triggers a pipeline restart even if the YAML itself hasn't changed. For external secret backends (Vault, AWS SM, EXEC), the checksum covers only the YAML; secret rotation in the external store does not automatically trigger a restart.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/public/reference/agent.md
Line: 166

Comment:
**Checksum-includes-secrets claim only holds for BUILTIN backend**

The updated description says the 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." This is only true when `secretBackend === "BUILTIN"`.

Looking at `src/app/api/agent/config/route.ts` (lines 77–90 and 124–128):

```typescript
// secrets is only populated for BUILTIN
const secrets: Record<string, string> = {};
if (environment.secretBackend === "BUILTIN") {
  // ...populate secrets...
}

// checksum only includes secrets when secrets is non-empty (i.e., BUILTIN only)
const checksumInput = Object.keys(secrets).length > 0
  ? configYaml + JSON.stringify(secrets, Object.keys(secrets).sort())
  : configYaml;
```

For `VAULT`, `AWS_SM`, or `EXEC` backends the `secrets` map stays empty, the checksum equals the YAML alone, and rotating a secret in the external store will **not** trigger a pipeline restart via this mechanism. Operators using an external backend who rotate secrets will need to trigger a restart manually.

The description should qualify this behaviour:

```suggestion
- **`checksum`**: Includes both the YAML and the secrets dictionary (BUILTIN backend only), so rotating a secret triggers a pipeline restart even if the YAML itself hasn't changed. For external secret backends (Vault, AWS SM, EXEC), the checksum covers only the YAML; secret rotation in the external store does not automatically trigger a restart.
```

How can I resolve this? If you propose a fix, please make it concise.