Contributing & Ops Collaboration

Principles

• No secrets in the repo. Secrets live in ~/.secrets.d on hosts.
• Host config (non-secret) lives under ~/ops-state/host-config.
• Use small, atomic PRs with clear scopes: infra(...), ops(...), windows(...).

Branch & PR Flow

• Create feature branches from main.
• Commit small changes, push, open PR.
• Required review for infra/, windows/ops/, and ops-state/ changes.

Checks (CI)

• Repo sanity: no secrets, allowed paths, compose config validates.
• Non-destructive: CI must not start services.
• Fast feedback: run make lint-perf-plus typecheck test-affected before pushing; full make test-cov before merge.

Local Ops

• Use ops-state Makefile targets (host-status, up-dns, up-reverse-proxy, up-admin-landing).
• Use windows/ops toolkit from Windows 11 for DNS/TLS/deploy/control.
• Status automation lives in scripts/posix/status.sh; use ./scripts/posix/status.sh quick|weekly|tui for the same docs/tasks the agents trigger.

Ops Contributions (Quickstart)

• Before touching infra/ops, run preflight and skim Operator Quickstart:
  • make -C zenpower ops-preflight
  • docs/ops-quickstart.md
• Delegation model:
  • Monorepo exposes ops make targets in zenpower/ (and per-app) that call into ~/ops-state.
  • Keep host orchestration in ~/ops-state; do not add host scripts to the repo.
• Local defaults:
  • Named volumes for Redis/Postgres; avoid bind-permission issues
  • No local port binds by default (toggle with HOSTPORTS=1 in ~/ops-state/host-config/compose.env)
  • Minimal health (admin/api/postgres); EXPECT_REDIS2=1 to enforce dual-Redis
• CI
  • PRs touching infra/zenpower: ops-preflight runs, comments summary, and labels PR (ops, infra, needs-domain, needs-gh when relevant)