# Pulse v5 Documentation Audit (pre-stable) This is a working audit of Pulse documentation as of `VERSION=5.0.0-rc.4`, focused on release readiness for a v5 stable cut. ## Status (updated 2025-12-18) Most of the issues identified in this audit have been addressed in-repo: - Updated install recommendation and bootstrap-token guidance across entrypoints (`README.md`, `docs/INSTALL.md`, `docs/FAQ.md`, `docs/TROUBLESHOOTING.md`, `docs/DOCKER.md`) - Rewritten AI and API docs to match the current v5 implementation (`docs/AI.md`, `docs/API.md`) - Rewritten metrics history docs to match SQLite store + tiered retention (`docs/METRICS_HISTORY.md`) - Fixed adaptive polling defaults and rollout paths (`docs/monitoring/ADAPTIVE_POLLING.md`, `docs/operations/ADAPTIVE_POLLING_ROLLOUT.md`) - Reduced temperature monitoring contradictions by making the agent the recommended path and scoping sensor-proxy as a legacy/alternative (`docs/TEMPERATURE_MONITORING.md`, `docs/security/TEMPERATURE_MONITORING.md`, `SECURITY.md`, sensor-proxy docs) - Updated Helm/Kubernetes docs to prefer OCI distribution and flag the legacy agent block (`docs/KUBERNETES.md`, `deploy/helm/pulse/README.md`, `deploy/helm/pulse/values.yaml`) - Added missing “operator clarity” docs (`docs/DEPLOYMENT_MODELS.md`, `docs/UPGRADE_v5.md`) - Link validation run: no broken relative `.md` links found at time of update ## Goals - Identify docs that are **stale**, **contradictory**, or **redundant** - Identify **missing docs** needed for a v5 stable release - Produce an actionable “what to change, where” checklist ## Highest-Priority Fixes (release-blockers) ### 1) Temperature monitoring guidance is contradictory There are multiple competing “truths” about how temperature monitoring works in v5: - `SECURITY.md` describes container deployments as requiring `pulse-sensor-proxy` and explicitly blocks SSH-based temps in containers. - Multiple docs under `docs/security/` and `cmd/pulse-sensor-proxy/README.md` claim `pulse-sensor-proxy` is deprecated in favor of the unified agent. - `docs/TEMPERATURE_MONITORING.md` is an extensive sensor-proxy-first guide and reads as “current”, but conflicts with the “deprecated” banner elsewhere. - The backend still has extensive support and UX flows for sensor proxy install/register (`/api/install/install-sensor-proxy.sh`, temperature proxy diagnostics, container SSH blocking guidance). Action: - Decide the **canonical** v5 story: - **Option A (agent-first)**: “Install `pulse-agent --enable-proxmox` on each Proxmox host for temperatures and management. `pulse-sensor-proxy` is legacy or edge-case only.” - **Option B (proxy-first for containers)**: “If Pulse runs in Docker/LXC, temperatures require `pulse-sensor-proxy` (socket/HTTPS). The agent is optional for other features.” - Update all docs to align with the chosen story, and ensure `SECURITY.md` reflects it unambiguously. Status: - Docs updated to be agent-first, with `pulse-sensor-proxy` treated as a legacy/alternative option. - Remaining work is primarily product positioning and long-term deprecation decisions, not broken documentation. Files involved: - `SECURITY.md` - `docs/TEMPERATURE_MONITORING.md` - `docs/security/TEMPERATURE_MONITORING.md` - `docs/security/SENSOR_PROXY_HARDENING.md` - `docs/security/SENSOR_PROXY_NETWORK.md` - `docs/security/SENSOR_PROXY_APPARMOR.md` - `docs/operations/SENSOR_PROXY_CONFIG.md` - `docs/operations/SENSOR_PROXY_LOGS.md` - `cmd/pulse-sensor-proxy/README.md` ### 2) AI docs do not match the actual v5 API and configuration model `docs/AI.md` and the AI section in `docs/API.md` appear written for an older/alternate API surface: - `docs/AI.md` documents `PULSE_AI_PROVIDER` and `PULSE_AI_API_KEY` env vars, but the current implementation persists encrypted AI config in `ai.enc` and supports multi-provider credentials (Anthropic/OpenAI/DeepSeek/Gemini/Ollama) plus Anthropic OAuth. - `docs/API.md` references endpoints like `POST /api/ai/chat` and `PUT /api/settings/ai` that do not match the router (current endpoints include `/api/ai/execute`, `/api/ai/models`, `/api/settings/ai/update`, OAuth endpoints, patrol stream, cost summary). Action: - Rewrite AI docs to match current behavior: - Providers actually supported - How keys/tokens are stored (encrypted) and what the UI exposes - Anthropic OAuth flow and security implications - Patrol and command execution (“autonomous mode”) safety controls - Correct API endpoints and auth requirements Files involved: - `docs/AI.md` - `docs/API.md` - `internal/config/ai.go` (source of truth for config fields) - `internal/api/router.go` (source of truth for endpoints) Status: - `docs/AI.md` rewritten to match multi-provider + encrypted config. - `docs/API.md` AI endpoints updated to match router. ### 3) Installation “recommended path” is inconsistent across docs - `README.md` recommends “Proxmox LXC (Recommended)” via GitHub `install.sh`. - `docs/INSTALL.md` and `docs/FAQ.md` currently present Docker as the easiest/recommended path. Action: - Pick one recommendation hierarchy and make it consistent: - If Proxmox LXC is the primary path, it should be the top section in `docs/INSTALL.md` and the FAQ answer should reflect it. Files involved: - `README.md` - `docs/INSTALL.md` - `docs/FAQ.md` Status: - Install docs now consistently present Proxmox VE LXC installer as the recommended path and include bootstrap-token retrieval. ### 4) Kubernetes/Helm docs and chart docs are out of date for v5 - `docs/KUBERNETES.md` references a chart repo URL and “Docker Agent sidecar”. - `deploy/helm/pulse/README.md` describes “optional Docker monitoring agent” and defaults to `ghcr.io/rcourtman/pulse-docker-agent`. Action: - Update Helm docs to match the v5 agent direction: - If `pulse-docker-agent` is deprecated, the chart should not reference it as primary. - Align chart distribution instructions (Helm repo vs OCI). Files involved: - `docs/KUBERNETES.md` - `deploy/helm/pulse/README.md` - `deploy/helm/pulse/values.yaml` - `deploy/helm/pulse/templates/*` Status: - `docs/KUBERNETES.md` updated to prefer OCI chart installs and flag the legacy agent block. - `deploy/helm/pulse/README.md` and `deploy/helm/pulse/values.yaml` now label the agent workload as legacy. ## Redundant / Duplicated Docs (needs consolidation) ### Auto-update docs: two competing sources - `docs/AUTO_UPDATE.md` describes “Settings → System Updates” and includes docker image instructions that differ from other docs. - `docs/operations/AUTO_UPDATE.md` documents systemd timers and edits `/var/lib/pulse/system.json` which appears stale for current config defaults (`/etc/pulse/system.json`). Action: - Choose one canonical page (likely `docs/AUTO_UPDATE.md`) and: - Move operational/timer details into it (or link to a clearly “advanced ops” page) - Fix stale paths and service names - Remove or clearly label the non-canonical duplicate Files involved: - `docs/AUTO_UPDATE.md` - `docs/operations/AUTO_UPDATE.md` Status: - Both documents updated to current UI naming and paths; optional future work is to consolidate into a single canonical page. ### Temperature monitoring docs: two sources with different “truth” - `docs/TEMPERATURE_MONITORING.md` (sensor proxy focused, extensive) - `docs/security/TEMPERATURE_MONITORING.md` (agent recommended, proxy “legacy”) Action: - Collapse into one canonical document with a clear decision tree, then: - Keep the other as a short redirect page, or delete it. Files involved: - `docs/TEMPERATURE_MONITORING.md` - `docs/security/TEMPERATURE_MONITORING.md` Status: - `docs/TEMPERATURE_MONITORING.md` is now the canonical deep-dive, and `docs/security/TEMPERATURE_MONITORING.md` is a security/overview page. ### Adaptive polling docs disagree with defaults and file paths - `docs/monitoring/ADAPTIVE_POLLING.md` claims adaptive polling is enabled by default and says env default is `true`. - Code defaults `AdaptivePollingEnabled=false` and `docs/operations/ADAPTIVE_POLLING_ROLLOUT.md` references `/var/lib/pulse/system.json`. Action: - Make one canonical doc, fix defaults and paths, and ensure UI path matches current navigation. Files involved: - `docs/monitoring/ADAPTIVE_POLLING.md` - `docs/operations/ADAPTIVE_POLLING_ROLLOUT.md` Status: - Defaults and paths updated to match current behavior. ## Stale / Incorrect Content (targeted findings) ### `docs/API.md` Issues: - AI endpoints mismatch current router paths (examples: `POST /api/ai/chat` vs current `/api/ai/execute`; settings update path differs). - “complete REST API documentation” claim is optimistic. It’s a curated subset plus a “check router.go” note. Action: - Update AI section to match `internal/api/router.go`. - Consider splitting into: - “Stable/public API” (guaranteed) - “Internal/subject to change” (documented but not stable) ### `docs/METRICS_HISTORY.md` Issues: - Documents `PULSE_METRICS_*_RETENTION_DAYS` env vars that do not appear to exist in the server config. - Claims metrics are stored under `/etc/pulse/data/metrics/`, but the metrics store is SQLite (`metrics.db`) under the configured data directory. Action: - Rewrite this doc to match the tiered retention model and actual storage format/location. ### `docs/FAQ.md` Issues: - Recommends Docker as easiest install, conflicts with repo README. - Password reset guidance does not mention the bootstrap token requirement that can appear after removing `.env`. - Mentions `METRICS_RETENTION_DAYS` which does not appear to be a current server config knob (v5 uses tiered retention settings). Action: - Align install recommendation with v5 positioning. - Update auth reset steps to include bootstrap token retrieval where applicable. - Replace metrics retention knob guidance with current retention model and UI location. ### `docs/TROUBLESHOOTING.md` and `docs/DOCKER.md` Issues: - “Forgot password” flow implies you can just rerun the setup wizard after deleting `.env`, but first-time setup can require the bootstrap token. Action: - Update password reset steps and link to the bootstrap token section in `docs/INSTALL.md`. ### `docs/RELEASE_NOTES.md` Issues: - Entire document is v4.x release notes. Action: - Replace with v5 release notes (or move to `docs/releases/` and add v5.0.0 as the top section). - For the v5 stable cut, include: breaking changes, migration notes, and versioned “what changed since v4”. ### `cmd/pulse-sensor-proxy/README.md` Issues: - Mentions downloading via `/download/pulse-sensor-proxy` but the server router does not expose this endpoint. - “Deprecated” banner conflicts with current server behavior and security guidance. Action: - Either bring it in line with the chosen v5 temperature story, or clearly scope it as legacy. ### Broken local link - `docs/TEMPERATURE_MONITORING.md` contains an absolute link to `/opt/pulse/cmd/pulse-sensor-proxy/README.md` which does not work in GitHub. Action: - Replace with a repo-relative link (or link to the canonical temperature doc). ### Widespread “runtime path” drift (`/opt/pulse/...`) Several user-facing docs mix: - repository paths (`/opt/pulse/...`) used in this dev workspace, and - runtime paths used in real installs (`/etc/pulse`, `/data`, `/var/log/pulse`, systemd units). This creates confusion and broken copy-paste commands. Examples to review: - `docs/ZFS_MONITORING.md` references `/opt/pulse/.env` and `/opt/pulse/pulse.log`. - `docs/operations/*` references `/var/lib/pulse/system.json` rather than `/etc/pulse/system.json`. Action: - Adopt a consistent convention across docs: - **Runtime**: `/etc/pulse` (systemd/LXC), `/data` (Docker/Helm) - **Repo/dev**: `/opt/pulse` only in development docs - **Logs**: `journalctl -u pulse` (systemd) and `docker logs` (Docker), plus `/var/log/pulse/*` only if actually used in production images. ## Missing Docs for a v5 Stable Release (recommended additions) ### v5 upgrade guide (v4 → v5) Add a single canonical page covering: - “What changes in v5” in operator terms - Any breaking changes and required actions - Post-upgrade verification checklist (health endpoint, scheduler health, agents connected, temps, notifications) - Rollback guidance for each deployment model (Docker, systemd/LXC, Helm) Suggested path: - `docs/UPGRADE_v5.md` (or `docs/MIGRATION_v5.md`) ### “Deployment model matrix” Many docs implicitly assume a deployment type. Add a short matrix page that answers: - What works on Docker vs Proxmox LXC vs systemd vs Helm - How updates work per model - Where config lives per model - What “recommended” means (and why) Suggested path: - `docs/DEPLOYMENT_MODELS.md` ### AI safety and permissions If v5 ships AI “execute/run-command” features: - Document default safety posture - What autonomous mode does - Required scopes/roles - Audit logging expectations - Clear warning section for production Suggested path: - Expand `docs/AI.md` with a “Safety” section, or add `docs/AI_SAFETY.md`. ## Quick “Status” Inventory (what to touch for v5) This is a fast triage list to help plan the doc refresh. Treat anything marked “Review” as “verify against current behavior”. - Rewrite: `docs/AI.md` - Rewrite: `docs/METRICS_HISTORY.md` - Rewrite: `docs/RELEASE_NOTES.md` (or replace with v5 release notes) - Update + align: `docs/INSTALL.md`, `docs/FAQ.md`, `docs/TROUBLESHOOTING.md` - Update: `docs/API.md` (especially AI endpoints) - Decide canonical + consolidate: - `docs/TEMPERATURE_MONITORING.md` vs `docs/security/TEMPERATURE_MONITORING.md` - `docs/AUTO_UPDATE.md` vs `docs/operations/AUTO_UPDATE.md` - `docs/monitoring/ADAPTIVE_POLLING.md` vs `docs/operations/ADAPTIVE_POLLING_ROLLOUT.md` - Review (Helm): `docs/KUBERNETES.md`, `deploy/helm/pulse/README.md` - Review (paths): `docs/ZFS_MONITORING.md` (and any other doc that uses `/opt/pulse/...` in user instructions) ## Suggested “Doc Refresh” Execution Order 1. Decide v5 canonical stories (agent vs proxy for temps, AI capabilities, Helm strategy). 2. Update the primary entrypoints: - `README.md` - `docs/README.md` - `docs/INSTALL.md` 3. Fix contradictions and remove duplicates (temperature, auto-update, adaptive polling). 4. Update `docs/API.md` to reflect current endpoints (especially AI). 5. Add v5 upgrade guide and deployment matrix. 6. Sweep FAQ + troubleshooting for the new canonical flows.