AGENTS.md

@@ -50,6 +50,15 @@ Backend (`cd backend`):
 
 Local stack: `docker compose up` (bookmark-api + postgres only; `postgres-data` named volume, `restart: unless-stopped`). No browser — without `BROWSER_WS_URL` the poller logs and skips kagane and comix. To run one: `cd chrome && BROWSER_BIND_ADDR=172.17.0.1 docker compose up -d --build`, then `BROWSER_WS_URL=ws://172.17.0.1:9222` in the root `.env` (bridge gateway, so the API container can name it by IP).
 
+**Clean up Docker after testing.** Storage on the dev machine is scarce, so
+anything you started for a test you also tear down before calling the work
+done: `docker compose down -v` for a stack you brought up, `docker rm -f -v`
+for a container you ran by hand (`-v`, or the image's anonymous data volume
+survives). Then check `docker volume ls` and `docker system df` for leftovers
+and reclaim them — a dangling volume nobody notices is the leak that fills the
+disk. Never remove the `postgres-data` volume of a stack the user is actually
+running, and never blanket-`docker system prune` their images or build cache.
+
 Live CDP proof (needs that browser and network, skipped otherwise):
 `SMOKE_BROWSER_WS_URL=ws://<ip>:<port> go test -run 'TestSmokeKagane|TestSmokeComix' ./internal/latest`
 — fetches a real kagane and comix cover and chapter list. A red run means the challenge is

backend/internal/pgtest/pgtest.go

@@ -40,7 +40,9 @@ func Main(m *testing.M) int {
 		fmt.Println("pgtest:", err)
 		return 1
 	}
-	defer exec.Command("docker", "rm", "-f", id).Run()
+	// -v: the postgres image declares a VOLUME, so an explicit rm without it
+	// leaves the anonymous data volume behind on every test run.
+	defer exec.Command("docker", "rm", "-f", "-v", id).Run()
 
 	adminURL = url
 	return m.Run()
@@ -85,7 +87,7 @@ func start() (id, url string, err error) {
 
 	port, err := exec.Command("docker", "port", id, "5432/tcp").Output()
 	if err != nil {
-		exec.Command("docker", "rm", "-f", id).Run()
+		exec.Command("docker", "rm", "-f", "-v", id).Run()
 		return "", "", fmt.Errorf("docker port: %w", err)
 	}
 	// "0.0.0.0:32768" (and possibly a second, IPv6 line); the port is all we want.
@@ -94,7 +96,7 @@ func start() (id, url string, err error) {
 		first[strings.LastIndex(first, ":")+1:])
 
 	if err := waitReady(url); err != nil {
-		exec.Command("docker", "rm", "-f", id).Run()
+		exec.Command("docker", "rm", "-f", "-v", id).Run()
 		return "", "", err
 	}
 	return id, url, nil