# AGENTS.md — KNEL/cloudron (tsys-cloudron / my.knownelement.com)

Fleet-machine repo for the production Cloudron host. Layering: global
`~/.zcode/AGENTS.md` < `KNEL/PFVCluster/AGENTS.md` < this file. The global
rules (ticket-governed work, push-as-you-go, Discourse as doc SoR, secrets in
`~/.creds` only) all apply; this file adds host specifics only.

## Agent authority (non-negotiable)

- No work without an approved Redmine ticket (project 88, Cloudron).
  Ticket-first: `echo '#NNN' > .crush/active-ticket`.
- Propose, never implement — findings become Feedback sub-tickets.
- NEVER close a ticket; NEVER 100% done-ratio — founder UAT gates "done".
- Production mutations only when the ticket says so; rollback documented
  in the ticket BEFORE the change (see #685 notes for the pattern).

## Access (SSH-only, NON-NEGOTIABLE)

- SSH `root@my.knownelement.com` is the ONLY access path. No panel
  back-channels, no guest-agent (qemu guest exec is banned fleet-wide).
- ALL ssh/scp routes through the chokepoint (from a PFVCluster checkout):

  ```bash
  VM_IP=my.knownelement.com VM_USER=root bash tests/remote.sh vm '<cmd>'      # quick reads, timeout 30
  VM_IP=my.knownelement.com VM_USER=root bash tests/remote.sh vm-file <script> # deploy/run a script
  ```

- DNS names only — never IP literals.
- API-first goal: Cloudron API token pending (asks #685/#727). Once issued it
  lives as a ref in `~/.creds/cloudron.env`; prefer the panel API over shell
  once available. Cloudron CLI on the host (`cloudron machine/`?) — not set up.

## Applied-state SoR (details in perf/ + Discourse t/316)

- Postgres: max_connections=700, shared_buffers 2GB,
  idle_in_transaction_session_timeout=15min, role caps (default 20 / booking 10
  / penpot 15). Re-apply script: `perf/pg-role-caps.sql`.
- sysctl: `perf/sysctl/99-cloudron-tuning.conf` (vm.swappiness=10).
- docker daemon.json NOT yet applied — `perf/docker-daemon.json.planned`
  needs a human-chosen dockerd bounce window (restarts ALL containers;
  live-restore=false today). Postgres nofile bridge (prlimit 262144) is
  EPHEMERAL until then.

## Repo rules

- shellcheck zero-warning (incl. info): `bash tests/shellcheck.sh`
- Enforcement: `scripts/check-rules.sh`; install hooks: `bash scripts/setup-hooks.sh`
- Docs on Discourse (perf: t/316); `.md` files here are pointers, not SoR.
- Commits: conventional format, `[#NNN]` ref, short body with clickable
  Redmine comment URL. The meat goes in the ticket comment, same turn.

## Resource-adjustment policy (ratified 2026-09-02)

Agent-approvable: app memory increases only — justified (>80% utilization or
24h memcg OOM), sized ~2x usage, above manifest floor, exclusions respected
(bi.knownelement.com, platform services), verified + documented same-day.
Human-required: any decrease, platform/Postgres/mail tuning, CPU/disk classes,
repeat-OOM escalations. Full text: Discourse t/317 · Redmine #735.