feat: bootstrap repo — enforcement layer + #685 perf capture

Enforcement (check-rules/hooks/shellcheck) per ADOPTING pattern; perf/ SoR from the #685 session (memcensus, pg role-caps SQL, applied sysctl, planned daemon.json); questions-v1 (API token + dockerd window asks). Meat + verification: https://projects.knownelement.com/issues/727#note-3913
2026-09-02 18:42:46 -05:00
parent 4d5c504534
commit 0e67f17112
18 changed files with 1049 additions and 2 deletions
@@ -0,0 +1,50 @@
+# 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.