# 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.
- `docker/guide_gateway.py`: restricted DNS plus HTTP/HTTPS User Guide redirect.
- `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 <kadinho@protonmail.com>` 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.
- `manuals.playstation.net` resolves to the configured gateway address;
- unrelated DNS names return NXDOMAIN;
- HTTP and HTTPS User Guide requests redirect to the local exploit URL.

Do not leave smoke-test containers running.

## Git and publishing

The primary branch is `main`. The normal push remote is:

```text
gitea@192.168.20.20: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.