ops-jrz1/AGENTS.md

Beads Issue Tracking

Session start: Run bd ready to see available work.

Commands

• bd ready - Issues with no blockers
• bd show <id> - Issue details
• bd update <id> --status=in_progress - Claim work
• bd close <id> - Complete work
• bd create --title="..." --type=task|bug|feature - New issue
• bd dep add <issue> <depends-on> - Add dependency

Session End

Before finishing: git status, git add, git commit. This is an ephemeral branch - merge to main locally.

Repository Guidelines

Project Structure & Module Organization

• configuration.nix holds shared system defaults; adjust service toggles in host overlays instead of editing it directly.
• hosts/ops-jrz1.nix and hosts/ops-jrz1-vm.nix override environment-specific networking, secrets, and hardware details; mirror changes across both when possible.
• modules/ contains composable NixOS modules (matrix-continuwuity.nix, mautrix-*.nix, security/*); keep new modules kebab-cased and expose options via lib.mkOption.
• scripts/ provides sanitization utilities. Stage external imports under staging/, run ./scripts/sanitize-files.sh SRC staging/modules, then promote files into modules/ once validation passes.
• specs/ and docs/ capture design intent and runbooks; update the relevant spec when changing feature scope.

Build, Test, and Development Commands

• nix flake check validates module wiring, options, and formatting before review.
• nix build .#nixosConfigurations.ops-jrz1 produces the deployable system closure; use this to catch evaluation regressions.
• nixos-rebuild switch --flake .#ops-jrz1 --target-host root@ops-jrz1 deploys to the VPS; replace the target host when testing elsewhere.
• ./scripts/validate-sanitization.sh modules/ ensures redacted content before commit; rerun after manual edits to sanitized files.

Coding Style & Naming Conventions

• Prefer two-space indentation in Nix files; align attribute sets and option blocks for readability.
• Use lowerCamelCase for option names, kebab-case for file names, and leave explanatory comments above non-obvious logic paths only.
• Format Nix with nix fmt (nixpkgs-fmt) or equivalent before committing to keep diffs minimal.

Testing Guidelines

• Treat nix flake check as the minimum gate; add targeted VM tests in hosts/ops-jrz1-vm.nix when introducing new services.
• Name ad-hoc verification scripts under scripts/local-* and avoid committing transient debug helpers.
• Capture manual verification steps in docs/worklogs/ immediately after deploys for traceability.

Commit & Pull Request Guidelines

• Follow the existing Git log style: single-line, capitalized summaries in ~70 characters (e.g., Tighten bridge secret validation).
• Reference related specs or worklogs in the body, and list nix flake check (and any VM smoke tests) under a short "Validation" block.
• PRs should link the tracked task, summarize scope, highlight sanitization steps, and mention any secrets or infra touchpoints reviewers must provision.

Security & Secrets Handling

• Never commit decrypted material; use sops secrets/secrets.yaml for edits and confirm git status shows only encrypted blobs.
• Replace real domains, IPs, and tokens with repository-safe placeholders. When importing upstream configs, run the sanitize and validate scripts before staging changes.