docs: document modern development workflow

AGENTS.md

@@ -52,14 +52,18 @@ so review both paths when changing upload behavior.
 
 ## Local Setup and Commands
 
-Create a PostgreSQL database, then:
+Use Go 1.26. From the repository root, copy the development configuration,
+start the PostgreSQL 18 service, and run micrach on the host:
 
 ```sh
 cp .env.example .env
-# Edit POSTGRES_URL and normally set IS_DB_SEEDED=false.
+docker compose up -d db
 go run .
 ```
 
+The example `POSTGRES_URL` matches the Compose service. `make dev` provides
+automatic reload and requires `nodemon`.
+
 Common checks:
 
 ```sh
@@ -67,16 +71,12 @@ go fmt ./...
 go test ./...
 go vet ./...
 go build .
-GO111MODULE=on CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build .
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /tmp/micrach-linux-amd64 .
 ```
 
-`make dev` requires `nodemon`. `sh tests/load.sh` requires Vegeta and targets a
+`sh tests/load.sh` requires Vegeta and targets a historical public URL by
-historical public URL by default; change the target to a controlled environment
+default; change the target to a controlled environment before use. Do not run
-before use. Do not run the load test as routine verification.
+the load test as routine verification.
-
-The module declares Go 1.15 and CI installs Go 1.17. Avoid language or standard
-library features newer than Go 1.17 unless the task also upgrades the supported
-Go version and CI configuration.
 
 ## Configuration and Generated State
 
@@ -120,18 +120,21 @@ Go version and CI configuration.
   Check catalog, thread, error, empty, and pagination states as relevant.
 - Upload changes: inspect controller transaction flow, `utils/`, repository file
   records, original/thumbnail paths, validation limits, and cleanup behavior.
-- Config changes: update `config/config.go`, `.env.example`, README config table,
+- Config changes: update `config/config.go`, `.env.example`, and the README
-  and deployment environment forwarding together.
+  config table together.
-- Deployment changes: note that `Dockerfile` expects a prebuilt Linux binary and
+- Deployment changes:
-  `docker-compose.yml` assumes Swarm, Traefik, an external network, and a
+  - `Dockerfile` builds the application in a pinned Go builder stage and runs it
-  persistent host upload mount.
+    as a non-root user in a small runtime image.
+  - `docker-compose.yml` starts local PostgreSQL only; run micrach on the host.
+  - CI verifies the project and container build but does not publish or deploy.
 
 ## Testing Expectations
 
-There are currently no checked-in Go unit tests and no coverage threshold. Add
+Go unit tests are checked in across the application packages; there is no
-`*_test.go` files beside changed code, use `TestXxx`, and prefer table-driven
+coverage threshold. Add `*_test.go` files beside changed code, use `TestXxx`,
-cases when practical. Repository tests must use disposable test data or a
+and prefer table-driven cases when practical. Repository tests must use
-dedicated database, never a shared production database.
+disposable test data or a dedicated database, never a shared production
+database.
 
 Minimum verification for code changes:
 

README.md

@@ -21,45 +21,45 @@ provide; the source remains available for local use and development.
 
 ## Stack
 
-- Go (the module declares Go 1.15; CI builds with Go 1.17)
+- Go 1.26
-- [Fiber v2](https://github.com/gofiber/fiber)
+- Fiber v2
-- PostgreSQL via `pgx`
+- PostgreSQL 18 for local development
+- PostgreSQL access through [`pgx`](https://github.com/jackc/pgx)
 - Plain HTML templates and CSS
 
 ## Run locally
 
 ### Prerequisites
 
-- Go 1.17 or newer
+- Go 1.26
-- PostgreSQL
+- Docker with Docker Compose
-- A PostgreSQL database that the configured user can create tables in
+- `nodemon` when using automatic reload
 
 ### Setup
 
-1. Create the database. With standard local PostgreSQL tooling:
+From the repository root:
 
-   ```sh
+```sh
-   createdb micrach
+cp .env.example .env
-   ```
+docker compose up -d db
+go run .
+```
 
-2. Copy the example configuration:
+The example configuration matches the PostgreSQL 18 service started by
+Compose. Compose runs PostgreSQL only; the micrach application runs on the
+host. Edit `.env` when you need different local settings. For normal
+development, keep `IS_DB_SEEDED=false`; when true, sample rows are inserted
+every time the application starts.
 
-   ```sh
+For automatic reload, install `nodemon`, start PostgreSQL as shown above, and
-   cp .env.example .env
+run:
-   ```
 
-3. Edit `.env`. At minimum, make `POSTGRES_URL` match your local database.
+```sh
-   For normal development, set `IS_DB_SEEDED=false`; when true, sample rows are
+make dev
-   inserted every time the application starts.
+```
 
-4. Start the application from the repository root:
+Open [http://localhost:3000](http://localhost:3000), or the port configured by
-
+`PORT`.
-   ```sh
-   go run .
-   ```
-
-5. Open [http://localhost:3000](http://localhost:3000), or the port configured
-   by `PORT`.
 
 Startup connects to PostgreSQL, applies missing files from `migrations/`, and
 creates the ignored local `uploads/` directory. Uploaded originals and
@@ -91,9 +91,6 @@ See [.env.example](.env.example) for a complete example.
 ## Development commands
 
 ```sh
-# Run with automatic restart; requires nodemon.
-make dev
-
 # Format, test, vet, and build.
 go fmt ./...
 go test ./...
@@ -101,20 +98,25 @@ go vet ./...
 go build .
 
 # Reproduce the Linux CI build.
-GO111MODULE=on CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build .
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /tmp/micrach-linux-amd64 .
 ```
 
 `tests/load.sh` is an optional Vegeta load test. Its checked-in target is a
 historical public URL, so change it to an environment you own before running
 the script. Generated load-test files are ignored by Git.
 
-## Containers and deployment
+## Containers and CI
 
-The `Dockerfile` packages a prebuilt `micrach` binary together with templates,
+The multi-stage `Dockerfile` builds micrach in a pinned Go builder image and
-static assets, and migrations. Build the Linux binary before building the
+runs it as a non-root user in a small runtime image. Verify the image locally:
-image. The checked-in `docker-compose.yml` is production-oriented: it expects
+
-Docker Swarm, an existing `web` overlay network, Traefik, a published image,
+```sh
-and host-mounted upload storage. It is not a standalone local PostgreSQL setup.
+docker build -t micrach:local .
+```
+
+CI checks formatting, tests, vet, native and Linux builds, reachable
+vulnerabilities, and Docker image construction. It has read-only repository
+permissions and does not publish or deploy images.
 
 ## Project layout