docs: add readme and make tooling targets

AGENTS.md

@@ -14,9 +14,9 @@ Implement email/password authentication with secure password hashing, CSRF prote
 
 ## Build, Lint, and Test Commands
 
-- `go run ./cmd/server` starts the dev server on <http://localhost:8000>.
+- `make run` launches the server locally (defaults to <http://localhost:8000>), while `make dev` hot-reloads via Air.
-- `go build ./...` (and `go build -o tmp/auth ./cmd/server`) validates compilation before any formatting or linting step.
+- `make build` compiles to `bin/auth-server`; always execute it before formatting, linting, or testing to honor the compile-first rule.
-- After a successful build, run `gofmt -w ./...`, `go vet ./...`, `golangci-lint run` (if configured), and `go test ./...` to keep style, static checks, and regressions in check.
+- After a clean build, run `make fmt`, `make lint`, and `make test` so every change flows through the formatter, static analyzers, and `go test ./... -cover -count=1`.
 
 ## Coding Style & Naming Conventions
 

Makefile

@@ -0,0 +1,30 @@
+BIN_DIR := bin
+BIN_NAME := auth-server
+FMT_PATHS := $(shell go list -f '{{.Dir}}' ./...)
+
+.PHONY: run dev build test fmt lint tidy clean
+
+run:
+	go run ./cmd/server
+
+dev:
+	air
+
+build:
+	@mkdir -p $(BIN_DIR)
+	go build -o $(BIN_DIR)/$(BIN_NAME) ./cmd/server
+
+test:
+	go test ./... -cover -count=1
+
+fmt:
+	gofmt -w $(FMT_PATHS)
+
+lint:
+	golangci-lint run
+
+tidy:
+	go mod tidy
+
+clean:
+	rm -rf $(BIN_DIR)

README.md

@@ -0,0 +1,62 @@
+# Auth Demo
+
+Auth Demo showcases a fully server-rendered email/password authentication flow
+with secure session management, CSRF protection, structured logging, and embedded
+templates/assets for single-binary deployment.
+
+## Capabilities
+
+- Email/password signup and login backed by salted hashing and reusable auth services.
+- CSRF-protected session middleware with signed cookies and automatic token rotation.
+- Structured logging (text or JSON) and environment-driven configuration for
+  production parity.
+- Embedded templates styled with Pico.css and progressively enhanced with htmx
+  and Alpine.js.
+
+## Getting Started
+
+1. Review or adjust the defaults in [.env](./.env). To load them in POSIX shells,
+   run `set -a; . ./.env; set +a`.
+2. Use the targets in the [Makefile](./Makefile):
+
+   | Target       | Description                                                                             |
+   | ------------ | --------------------------------------------------------------------------------------- |
+   | `make run`   | Start the HTTP server with the current environment.                                     |
+   | `make dev`   | Launch [Air](https://github.com/cosmtrek/air) for live reload (requires `air` on PATH). |
+   | `make build` | Compile to `./bin/auth-server`.                                                         |
+   | `make test`  | Run `go test ./... -cover -count=1`.                                                    |
+
+3. Visit the login page (default <http://localhost:8000>) and authenticate with
+   the demo credentials displayed on screen.
+
+## Configuration
+
+Settings are sourced from environment variables (see [.env](./.env)).
+
+| Variable              | Required | Default       | Description                                           |
+| --------------------- | -------- | ------------- | ----------------------------------------------------- |
+| `AUTH_SESSION_SECRET` | Yes      | —             | Base64-encoded secret used to sign session cookies.   |
+| `AUTH_LISTEN_ADDR`    | No       | `:8000`       | Address the HTTP server binds to.                     |
+| `AUTH_ENV`            | No       | `development` | Environment label, controls logger source annotation. |
+| `AUTH_LOG_MODE`       | No       | `text`        | Structured log encoder (`text` or `json`).            |
+
+## Project Layout
+
+- `cmd/server` — application entrypoint.
+- `internal/config` — environment-backed configuration loader.
+- `internal/driver/logging` — `slog` helpers for text/JSON output.
+- `internal/service/auth` — authentication domain logic, hashing, validation.
+- `internal/server` — router, middleware, handlers, session store.
+- `web/templates` — embedded HTML templates.
+
+## Built With
+
+- [Go](https://go.dev/doc/) — standard library HTTP, templates, crypto, and `embed`.
+- [Chi](https://github.com/go-chi/chi) — lightweight router and middleware stack.
+- [htmx](https://htmx.org/) — progressive enhancement via HTML attributes.
+- [Alpine.js](https://alpinejs.dev/) — declarative client-side interactions.
+- [Pico.css](https://picocss.com/) — minimal, semantic-first styling.
+
+## License
+
+MIT

cmd/server/main.go

@@ -7,7 +7,7 @@ import (
 	"os"
 
 	"github.com/rjnemo/auth/internal/config"
-	"github.com/rjnemo/auth/internal/logging"
+	"github.com/rjnemo/auth/internal/driver/logging"
 	"github.com/rjnemo/auth/internal/server"
 )
 

go.mod

@@ -2,4 +2,4 @@ module github.com/rjnemo/auth
 
 go 1.25.1
 
-require github.com/go-chi/chi/v5 v5.2.3 // indirect
+require github.com/go-chi/chi/v5 v5.2.3

internal/config/config.go

@@ -7,7 +7,7 @@ import (
 	"os"
 	"strings"
 
-	"github.com/rjnemo/auth/internal/logging"
+	"github.com/rjnemo/auth/internal/driver/logging"
 )
 
 const (

internal/config/config_test.go

@@ -4,7 +4,7 @@ import (
 	"encoding/base64"
 	"testing"
 
-	"github.com/rjnemo/auth/internal/logging"
+	"github.com/rjnemo/auth/internal/driver/logging"
 )
 
 func TestNewDefaults(t *testing.T) {

internal/server/server.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	"github.com/rjnemo/auth/internal/config"
-	"github.com/rjnemo/auth/internal/logging"
+	"github.com/rjnemo/auth/internal/driver/logging"
 	"github.com/rjnemo/auth/internal/service/auth"
 	"github.com/rjnemo/auth/web"
 )