Add the runnable Gitea, PostgreSQL, and Hop control-plane foundation

Hop-State: A_06FN3QYA1N56NQYGZ81DWGR
Hop-Proposal: R_06FN3QXJRYPPEQZQA6S69QG
Hop-Task: T_06FN3MVGY3MT82ESQ89BND0
Hop-Attempt: AT_06FN3MVGY092BFA5MR9C7EG

docs/local-development.md

@@ -0,0 +1,64 @@
+# Local development
+
+## Start the foundation
+
+Requirements: Docker with Compose v2, Go 1.26 or newer for host-side tests, and
+ports 3000, 8080, and 2222 available.
+
+```sh
+cp .env.example .env
+make up
+```
+
+Open Gitea at <http://localhost:3000>. The Hop control plane exposes health at
+<http://localhost:8080/healthz> and readiness at
+<http://localhost:8080/readyz>.
+
+Gitea self-registration is enabled for this local stack. After creating the
+first account, create an access token in Gitea and set `GITEA_API_TOKEN` in
+`.env`, then restart the control plane:
+
+```sh
+docker compose up -d --force-recreate control-plane
+```
+
+## Link a repository
+
+Create a repository in Gitea, then ask Hop to verify it through the Gitea API
+and record the link:
+
+```sh
+set -a
+. ./.env
+set +a
+
+curl --fail-with-body \
+  -H "Authorization: Bearer $HOP_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"owner":"YOUR_USER","name":"YOUR_REPOSITORY"}' \
+  http://localhost:8080/api/v1/repositories/link
+```
+
+## Configure a webhook
+
+In the Gitea repository, create a Gitea webhook with:
+
+- target URL: `http://control-plane:8080/api/v1/gitea/webhooks`
+- content type: `application/json`
+- secret: the value of `HOP_GITEA_WEBHOOK_SECRET` in `.env`
+- events: all events
+
+The control plane verifies `X-Gitea-Signature` against the raw request body,
+records each delivery exactly once, and refreshes repository metadata from the
+signed payload.
+
+## Useful commands
+
+```sh
+make test
+make config
+make logs
+make down
+```
+
+To destroy local data as well as containers, run `docker compose down -v`.