# 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.