# AGENTS.md

Rules for anyone (human or tooling) contributing to this repository.

## Hard rules

1. **English only.** All documentation, code, comments, commit messages, and file names are written in English.
2. **No identifying references.** Never mention names of people, companies, organizations, or locations anywhere in this repository — not in docs, code, comments, or git history. This is a generic, self-contained design proposal for an on-prem data platform for autonomous drone swarms.
3. **Clean git history.** Commit messages must never reference AI assistants, code generation tools, or editors. No `Co-authored-by` trailers pointing to tools, no "Generated with ..." lines. Conventional commit format (`feat:`, `fix:`, `docs:`, `refactor:`).
4. **Push target.** The only remote is `origin` → `git.produktor.io`. Never mirror this repository anywhere else.

## Project layout

```
docs/           Design documentation (Markdown + Mermaid)
simulator/      Virtual drone fleet — Python data generator (Parquet/DuckDB pipeline)
prototype/      2D swarm visualization — React + TypeScript (Vite)
infra/          Ansible host prep, Terraform workloads, Flux GitOps overlays
var/t1/         Shared T1 live lake (gitignored runtime data)
var/t3/         Shared T3 warehouse (gitignored runtime data)
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and TDD requirements.

## Conventions

- Markdown: ATX headings, fenced code blocks with language tags, pipe tables.
- Python: PEP 8, type hints, pure functions where possible, no unnecessary classes.
- TypeScript: strict mode, functional components and hooks, no extra UI libraries.
- YAML: 2-space indent.
- Diagrams: Mermaid inside Markdown.

## Decision records

Significant architectural decisions are recorded chronologically as **ADRs** in
[`docs/adr/`](docs/adr/) — one immutable file per decision, in the
Status / Context / Options / Decision / Consequences format. Start from
[`docs/adr/README.md`](docs/adr/README.md).

- **ADR** = a point-in-time decision for *this* repo → `docs/adr/`.
- **ASR** = a standing, ecosystem-wide standard (Go-first, secrets, layout) →
  lives in the `inventar` repo, **not** here.

When a change alters a boundary, contract, or trade-off, add an ADR (copy
[`docs/adr/TEMPLATE.md`](docs/adr/TEMPLATE.md), take the next number, update the
index) and cross-link it from the affected design doc. A later reversal gets a
new ADR that supersedes the old one — never edit an Accepted record.

## Runtime & operations (sim environment)

The k3d ground miniature is `swarm-sim`. Services are exposed as NodePorts:

| Service | URL |
| --- | --- |
| Explorer (T1 live lake) | `http://localhost:30088` |
| Warehouse explorer (T3) | `http://localhost:30089` |
| Grafana (dashboards `swarm-fleet`, `swarm-platform`) | `http://localhost:30300` |
| Prometheus | `http://localhost:30990` |
| MinIO console | `http://localhost:30901` |
| Prototype dev server (`npm run dev`) | `http://localhost:5173` |

Rebuild the simulator image and roll it out:

```bash
cd simulator && docker build -t swarm-house/simulator:dev .
k3d image import swarm-house/simulator:dev -c swarm-sim
kubectl rollout restart -n swarm statefulset/drone deployment/explorer deployment/exporter
cd infra/terraform/sim-env && terraform apply
```

**CPU budget knobs** (see [ADR-0009](docs/adr/ADR-0009-bounded-lake-scans.md)):
`METRIC_FLIGHT_WINDOW` (scan only recent flights), `SCAN_INTERVAL_S`,
`VIEW_REFRESH_S`, `TREE_CACHE_S`, `KEEP_ALIVE=1` (drones idle after seal instead
of restarting), `IMU_HZ`. Never scan the full lake on a hot path — it grows with
pod churn. Long-horizon analysis is a T3 warehouse query, not an exporter job.

Runtime data lives under `var/t1` / `var/t3`, owned by uid **10001**
([ADR-0007](docs/adr/ADR-0007-non-root-image.md),
[ADR-0008](docs/adr/ADR-0008-runtime-data-paths.md)); both are gitignored.
Terraform state is local and never committed.