Add agent instructions and project handoff

AGENTS.md

@@ -0,0 +1,115 @@
+# AGENTS.md
+
+## Scope
+
+These instructions apply to the complete `relapse-exploit-docker` repository.
+Treat this repository as the primary workspace for all future work related to the
+Docker packaging, deployment, PS5 usage documentation, and operational support.
+
+Read `docs/HANDOFF.md` and `docs/PS5_SETUP.md` before making changes.
+
+## Purpose
+
+This repository packages the upstream PS5 Relapse Exploit as a small, hardened
+container. The upstream source is the `app` Git submodule. The wrapper must serve
+only the files required by the exploit and must verify the executable payloads
+before including them in an image.
+
+## Repository layout
+
+- `app/`: upstream Relapse Exploit submodule; do not edit it as ordinary wrapper code.
+- `Dockerfile`: runtime image and payload-integrity checks.
+- `compose.yaml`: hardened local deployment.
+- `docker/server.py`: static HTTP server and security headers.
+- `payloads.sha256`: approved payload digests for the pinned submodule commit.
+- `docs/PS5_SETUP.md`: user and operator guide.
+- `docs/HANDOFF.md`: current infrastructure state and durable session handoff.
+
+## Working rules
+
+1. Preserve the separation between this wrapper and the upstream `app` submodule.
+2. Do not update the submodule or payload hashes implicitly. An upstream update
+   requires explicit review of source changes and binary payloads.
+3. Never weaken or bypass a payload checksum failure merely to make a build pass.
+4. Keep `.git`, credentials, environment files, documentation, and development
+   metadata outside the runtime image.
+5. Preserve non-root execution, read-only runtime filesystem, dropped capabilities,
+   and `no-new-privileges` unless a documented requirement proves otherwise.
+6. Do not expose the service or PS5 payload ports to the public Internet.
+7. Do not add secrets to the repository. Use local environment/configuration for
+   any future credentials.
+8. Keep instructions in `docs/HANDOFF.md` current whenever deployment topology,
+   ports, remotes, submodule commit, or operational procedures change.
+9. Use `kadinho <[email protected]>` as the repository-local Git identity.
+   Do not change global Git configuration.
+
+## Required validation
+
+For documentation-only changes:
+
+```sh
+git diff --check
+docker compose config
+```
+
+For runtime, Dockerfile, Compose, server, submodule, or payload changes:
+
+```sh
+git submodule status
+(cd app && sha256sum -c ../payloads.sha256)
+docker compose config
+docker compose build
+```
+
+Then perform a disposable smoke test and verify:
+
+- `/` returns HTTP 200;
+- JavaScript is served as `text/javascript`;
+- `.elf` and `.bin` are served as `application/octet-stream`;
+- `/.git/config` returns 404;
+- the process runs as UID/GID `65532:65532`;
+- the configured security headers remain present.
+
+Do not leave smoke-test containers running.
+
+## Git and publishing
+
+The primary branch is `main`. The normal push remote is:
+
+```text
+[email protected]:TinyBacklog/relapse-exploit-docker.git
+```
+
+The public read-only clone URL used by deployment hosts is:
+
+```text
+http://192.168.20.20:3000/TinyBacklog/relapse-exploit-docker.git
+```
+
+Before committing, inspect the diff and confirm the worktree contains no generated
+files. After pushing, synchronize the deployment only when the requested change is
+intended for the live host.
+
+## Deployment
+
+The current deployment is documented in `docs/HANDOFF.md`. It runs on
+`net-utils01` from `/opt/relapse-exploit-docker` and is reachable on the LAN at
+`http://192.168.20.30:8000/`.
+
+Use fast-forward-only pulls:
+
+```sh
+ssh net-utils01
+cd /opt/relapse-exploit-docker
+git pull --ff-only
+git submodule update --init --recursive
+```
+
+Documentation-only changes do not require an image rebuild. Runtime changes require:
+
+```sh
+docker compose up -d --build
+docker compose ps
+```
+
+Verify health and HTTP access after every live deployment.