AWatch-rus/AGENTS.md

AGENTS for OpenCode

Keep this file minimal and high-signal: only include facts an agent would otherwise miss.

1. Repo purpose (one line)

• This repository bundles an ActivityWatch Server deployment, RU WebUI patch, Windows collectors (PowerShell), and Rust operational utilities for aggregation, monitoring, health checks, SLO, DLP helpers, and DetMir automation. Python is retained only for explicit exceptions: Telegram bot runtime, pfSense tooling, OCR/content-analysis, 1C AI/ETL, and detmir-mcp.

2. Highest-value entrypoints & commands

• Read README.md and docs/preparation.md first (they are the authoritative onboarding flow).
• Create a Proxmox CT: proxmox/create-ct.sh [ /path/to/deploy.secrets.env ] (reads secrets/deploy.secrets.env).
• Push server artifacts to an existing CT: proxmox/push-aw-artifacts.sh [ /path/to/deploy.secrets.env ].
• Install AW server on the CT (runs inside CT): aw-server/install_aw_server.sh (requires /etc/activitywatch/aw-server.env).
• Apply RU WebUI patch (must run on the CT and after webui is present): aw-server/apply_webui_ru_patch.sh.
• Run the Windows ensemble deploy from a Windows admin host: windows/deploy-ensemble.ps1 (see its parameters; it calls deploy-domain-users.ps1).
• Quick DLP aggregation (local): adk-rust/target/release/dlp-aggregator.

3. Exact env/secrets behavior agents often miss

• Secrets live in secrets/deploy.secrets.env (actual file is intentionally local-only). Many scripts default to that path if no arg provided. Never add real secrets to commits. Use .example files as templates.
• The CT bootstrap workflow expects /etc/activitywatch/aw-server.env on the CT (pushed by push-aw-artifacts when AW_SERVER_* variables are set). install_aw_server.sh sources that exact path.

4. CI / quality checks the repo enforces

• GitHub CI runs shellcheck for *.sh and PSScriptAnalyzer for PowerShell in windows/*.ps1 (see .github/workflows/ci.yml).
• Local quality gate: scripts/quality-gate.sh performs bash -n, (optional) shellcheck, pwsh parse checks, and ansible syntax checks. Run this before PRs.

5. File locations and toolchain quirks

• AW server binary is installed under /opt/activitywatch/releases and symlinked from /opt/activitywatch/bin/aw-server-rust by install_aw_server.sh.
• RU WebUI patching expects JS assets in $AW_SERVER_WEBUI_DIR (default /opt/activitywatch/webui-ru). The patch script writes js/ru-patch-v5.js and edits index.html in-place (it makes backups with .bak timestamps).
• proxmox/create-ct.sh and proxmox/push-aw-artifacts.sh source the same deploy.secrets.env and require many CT_* / AW_SERVER_* variables; missing vars cause immediate exit.

6. Monorepo boundaries / responsibilities

• aw-server/: server install & systemd unit + RU webui patching.
• proxmox/: create CT and push artifacts scripts (requires Proxmox pct CLI and CT preconditions).
• windows/: PowerShell collectors and deployment automation (Target: Windows admin hosts; validated via validate-deployment.ps1).
• grafana-1c/, pfsense/: monitoring stacks and pollers (separate deploys, not part of aw-server install).
• scripts/: small utilities and quality-gate.sh used by contributors.

7. Common gotchas

• Do NOT commit secrets (secrets/ are local-only; PRs must not contain real secrets).
• Many scripts assume they run on the target CT or on a Linux admin host with pct available. Don't try to run them on macOS without adapting dependencies.
• aw-server/install_aw_server.sh expects network access to download the AW release URL provided by AW_SERVER_DOWNLOAD_URL.
• aw-server/apply_webui_ru_patch.sh must run after AW webui files are present; it will fail if required bootstrap files under <CT_BOOTSTRAP_DIR> are missing.
• When pushing AW_SERVER env via push-aw-artifacts.sh the script will only write /etc/activitywatch/aw-server.env if all AW_SERVER_* variables are set; otherwise it warns and skips.

8. PR / commit checklist for agents

• Run scripts/quality-gate.sh locally (or ensure CI covers changed files).
• Ensure no secrets (.env with real values) are staged.
• If changing PowerShell, ensure PSScriptAnalyzer rules pass (CI enforces this).

9. Where to find more instructions (preserve these files)

• README.md, docs/preparation.md, docs/deployment.md, docs/runbook.md, docs/operations.md, docs/codebase-onboarding.md — read these when doing infra or deployment work.

If you need me to add step-by-step repros or automate one of the tasks above (create CT, push artifacts, run install on CT), say which one and I will implement the helper or run the checked commands.