# Copilot instructions for ActivityWatch-Russian

Purpose: help future Copilot sessions quickly understand how to build, validate, and modify this repo.

---

## Build / test / lint (how-to)

- Shell script checks (CI & local):
  - Full: ./scripts/quality-gate.sh
  - Single file (syntax): bash -n <script>. Example: bash -n scripts/install_aw_linux_client.sh
  - Run shellcheck locally (same checks as CI): install shellcheck then run:
    find . -type f -name "*.sh" -print0 | xargs -0 -r shellcheck -e SC1007,SC1090,SC2016

- PowerShell checks (Windows / CI):
  - Single-file analysis (locally in PowerShell):
    Invoke-ScriptAnalyzer -Path windows/deploy-ensemble.ps1
  - CI installs PSScriptAnalyzer and runs against windows/*.ps1, *.psm1, *.psd1

- Python scripts / utilities:
  - Run a single utility: python3 scripts/aggregate_dlp_events.py
  - Many scripts are helpers for operations; no test harness in repo.

- Monitoring stack (Docker Compose):
  - Start: cd grafana-1c && docker-compose up -d
  - Start a single service: docker-compose up -d grafana

- Server install / deploy helpers:
  - AW server install: aw-server/install_aw_server.sh
  - Apply RU WebUI patch: aw-server/apply_webui_ru_patch.sh
  - Windows deploy/validation: windows/deploy-ensemble.ps1 and windows/validate-deployment.ps1

Notes: there is no unified unit-test suite. Use the script checks and CI pipeline (.github/workflows/ci.yml) as the canonical validation steps.

---

## High-level architecture (short)

- Windows collectors (PowerShell) run on endpoints and POST events to the ActivityWatch Server HTTP API.
- ActivityWatch Server (deployed on Linux CT/LXC via Proxmox or Debian VM) stores events in PostgreSQL and serves WebUI.
- Integration layer: pollers and aggregators (Python) for pfSense, DLP aggregation, Prometheus exporter.
- Monitoring: Prometheus + Grafana (docker-compose in grafana-1c) and a SQL exporter for direct DB dashboards.

Key ports: AW API 5600/5666, PostgreSQL 5432, Prometheus 9090, Grafana 3000, exporter 9398.

---

## Key repository conventions

- Branching / commits:
  - Use feature branches. Commit style follows Conventional Commits (feat/fix/docs/chore).

- Secrets and envs:
  - Secrets live in secrets/*.env templates and must NOT be committed. Use secrets/deploy.secrets.env locally; CI and scripts expect templates (.example).

- Preflight / PR checks:
  - Run bash -n for shell scripts and Invoke-ScriptAnalyzer for PowerShell before opening PRs.
  - Update docs/runbook.md and related runbooks when behavior changes.

- RU patching:
  - WebUI localization is applied via aw-server/aw-ru-patch.js and aw-server/apply_webui_ru_patch.sh — treat these as idempotent patch steps during deploy.

- Systemd / deploy units:
  - activitywatch-server.service / aw-worktime-api.service / aw-worktime-ui-bridge.service are included in aw-server/ for production use.

- CI expectations:
  - .github/workflows/ci.yml runs shellcheck and PSScriptAnalyzer. Use scripts/quality-gate.sh locally to replicate preflight.

---

## Important files & quick references

- docs/ (onboarding, deployment, runbook) — start here for operational context.
- aw-server/ — server install script, env template, RU patch, systemd units.
- ansible/ — automated provisioning playbooks for CT/Proxmox and Windows deploys.
- windows/ — PowerShell collectors and orchestration; validation scripts are here.
- scripts/ — helpers (aggregate_dlp_events.py, installers, quality-gate.sh).
- grafana-1c/ — docker-compose monitoring stack and dashboards.

---

## AI assistant & other tool configs to check

- No Copilot-specific instruction file existed before this addition.
- No CLAUDE.md, .cursorrules, AGENTS.md, .windsurfrules, CONVENTIONS.md, or AIDER_CONVENTIONS.md detected at repo root. If adding automated assistant rules, place them in repo root or .github and document cross-references here.

---

If you need the Copilot instructions extended (e.g., adding run examples for specific scripts, more detailed CI breakdown, or mapping tests to files), say which area to expand.