Skip to content

docs: rewrite the bannered legacy operator guides for the Go stack#508

Merged
remyluslosius merged 2 commits into
mainfrom
docs/go-era-guides
Jun 10, 2026
Merged

docs: rewrite the bannered legacy operator guides for the Go stack#508
remyluslosius merged 2 commits into
mainfrom
docs/go-era-guides

Conversation

@remyluslosius

Copy link
Copy Markdown
Contributor

Replaces the 18 Python/Docker-Compose-era operator guides and runbooks that #505 bannered as legacy with accurate Go-era documentation for the current stack: one openwatch binary serving the API + embedded UI on :8443, PostgreSQL-only, systemd, native RPM/DEB, Kensa engine.

How (and the guardrail)

Authored by a multi-agent sweep under a hard anti-fabrication rule: each agent verified every command, endpoint, flag, and path against the code (cmd/, internal/, api/openapi.yaml, packaging/, the systemd unit, install_guide.md) before writing it. Anything the old guide covered that does not exist in the rc.5 binary is marked "not yet implemented", never invented.

(Run in batches of 4 — a single 16-wide agent burst was tripping the API's transient request-rate throttle.)

Files

  • Guides (12): API_GUIDE, BACKUP_RECOVERY, DATABASE_MIGRATIONS, ENVIRONMENT_REFERENCE, MONITORING_SETUP, PRODUCTION_DEPLOYMENT, QUICKSTART, SCALING_GUIDE, SECRET_ROTATION, SECURITY_HARDENING, UPGRADE_PROCEDURE, USER_ROLES
  • Runbooks (4): DISK_FULL, HIGH_CPU, SECURITY_INCIDENT, SERVICE_DOWN
  • Plus: .github/workflows/README.md, docs/architecture/KENSA_INTEGRATION.md

Honestly marked "not yet implemented" (verified absent)

Prometheus /metrics + bundled monitoring stack; horizontal API scaling + a packaged worker systemd unit; openwatch backup/restore subcommands (docs use pg_dump/pg_restore); migrate down; API-layer rate limiting; scan-execution endpoints; distributed tracing.

Review done before committing

I verified, not just trusted the agents:

  • Every /api/v1 path the docs mention exists in openapi.yaml, or is in a "not implemented" section (scans).
  • Only the real openwatch subcommands (serve/worker/migrate/create-admin/check-config) are used as commands; backup/restore are explicitly called out as non-existent.
  • USER_ROLES uses the 5 real roles from roles.gen.go (dropped the 6 fabricated Python roles).
  • No emojis; all legacy banners removed; .secrets.baseline refreshed for placeholder credentials (all CHANGE_ME-style, verified).

Separate, pre-existing (not in this PR)

docs/guides/SCANNING_AND_COMPLIANCE.md (active-fixed in #505, on main) presents /api/v1/scans/kensa/ as a live command, but that endpoint isn't in openapi.yaml yet — worth a follow-up fix.

Replace 18 Python/Docker-era operator guides + runbooks (bannered legacy in #505) with accurate Go-era docs for the single-binary + PostgreSQL + systemd + Kensa stack. Authored via a multi-agent sweep under a hard anti-fabrication rule: every command/endpoint/flag/path verified against the code; capabilities absent in rc.5 (Prometheus metrics, horizontal scaling, openwatch backup/restore, migrate down, API rate limiting, scan-execution endpoints) marked not-implemented rather than invented. Refresh .secrets.baseline for placeholder credentials in the rewritten docs.
@github-actions github-actions Bot added ci/cd documentation Improvements or additions to documentation size/XL labels Jun 10, 2026
@remyluslosius remyluslosius enabled auto-merge (squash) June 10, 2026 22:40
@remyluslosius remyluslosius merged commit 3500f85 into main Jun 10, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci/cd documentation Improvements or additions to documentation size/XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant