docs: the contributor guide asked for SQLite headers and a server you don't need

docs/contributing.md

@@ -3,9 +3,12 @@
 ## Prerequisites
 
 - Go 1.26+
-- SQLite3 development libraries (`brew install sqlite3` on macOS)
 - Docker (optional, for Lambda runtime and integration tests)
 - Python 3.10+ with pip (for compatibility tests)
+- `pre-commit` (optional but recommended — see [Code Style](#code-style))
+
+No C toolchain and no SQLite headers are needed. The SQLite driver is pure Go,
+which is why everything here builds with `CGO_ENABLED=0`.
 
 ## Development Setup
 
@@ -20,6 +23,26 @@ make build
 make run
 ```
 
+## Make Targets
+
+<!-- AUTO-GENERATED: from Makefile. Do not edit by hand. -->
+
+| Command | Description |
+|---------|-------------|
+| `make build` | Build both binaries into `dist/` — `devcloud` and `codegen` |
+| `make run` | Run the server from source (`go run ./cmd/devcloud`) |
+| `make test` | Run all Go tests with `CGO_ENABLED=0` and `-v` |
+| `make test-compat` | Install `tests/compatibility/requirements.txt` and run the boto3 suite |
+| `make codegen` | Regenerate `internal/generated/` from every model in `smithy-models/` |
+| `make codegen-s3` | Same, restricted to S3 — fast loop while editing templates |
+| `make docker-build` | Build the image from `docker/Dockerfile` as `devcloud/devcloud` |
+| `make docker-run` | Run that image on port 4747 with `./data` mounted |
+| `make clean` | Delete `dist/` and `data/` |
+| `make changelog VERSION=vX.Y.Z` | Batch and merge Changie fragments; `VERSION` is required |
+| `make stats` | Print registered service and operation counts |
+
+<!-- END AUTO-GENERATED -->
+
 ## Testing
 
 ### Go unit tests
@@ -28,15 +51,29 @@ make run
 make test
 ```
 
-Runs all Go tests with CGO enabled (required for SQLite).
+Runs all Go tests with `CGO_ENABLED=0` — the mode `.goreleaser.yaml` publishes
+in, so the tests exercise the same build the releases ship.
 
 ### Compatibility tests
 
 ```bash
 make test-compat
 ```
 
-Runs Python/boto3 tests in `tests/compatibility/` that verify DevCloud behaves like real AWS services. Requires a running DevCloud instance and Python dependencies:
+Runs the Python/boto3 tests in `tests/compatibility/` that verify DevCloud behaves like real AWS services.
+
+You do **not** need a server running first. The `devcloud_server` session
+fixture in [`conftest.py`](../tests/compatibility/conftest.py) starts one via
+`go run`, on a free port, against a temporary data directory it removes
+afterwards. Three environment variables change that:
+
+| Variable | Effect |
+|----------|--------|
+| `DEVCLOUD_EXTERNAL=1` | Do not start anything — connect to a server already running (e.g. in Docker) |
+| `DEVCLOUD_BIN=<path>` | Run a pre-built binary instead of `go run` (much faster) |
+| `DEVCLOUD_PORT=<port>` | Use a fixed port instead of an arbitrary free one |
+
+To run the suite directly:
 
 ```bash
 cd tests/compatibility
@@ -153,6 +190,32 @@ make docker-run
 - Use existing services as patterns for new ones
 - Error messages should follow AWS error format (Code, Message, StatusCode)
 
+### Pre-commit hooks
+
+Install once, and formatting and the fast checks run on every commit:
+
+```bash
+pre-commit install
+pre-commit run --all-files   # optional: check the whole tree now
+```
+
+[`.pre-commit-config.yaml`](../.pre-commit-config.yaml) runs, on Go files:
+`go-spdx-header` (adds the licence header), `gofmt -l -w`, `go vet`, and
+`go build` — the last two with `CGO_ENABLED=0`, so a contributor without a C
+toolchain still gets them. Python files under `tests/` and `scripts/` are
+linted and formatted by `ruff`. `internal/generated/` and `smithy-models/` are
+excluded throughout.
+
+### Linting
+
+`gofmt` and `go vet` run in pre-commit, but the full linter does not — CI runs
+`golangci-lint` separately ([`lint.yml`](../.github/workflows/lint.yml)). Run
+it yourself before opening a PR:
+
+```bash
+golangci-lint run --timeout=5m
+```
+
 ## License Header
 
 All new Go files must include the SPDX license identifier on the first line:

docs/getting-started.md

@@ -37,15 +37,18 @@ make run     # starts server on port 4747
 
 ## Docker Compose (Development)
 
-For development with hot-reload on the frontend:
-
 ```bash
 docker compose -f docker/docker-compose.yml up
 ```
 
-This starts:
-- **Backend** on port 4747 — Go server with all services
-- **Frontend** on port 3000 — Next.js dev server with hot-reload
+This builds the image from source and starts one service: the Go server on port
+4747, with `./data` mounted for persistence and the host Docker socket mounted
+so the Lambda runtime can start containers.
+
+It runs a subset, not everything —
+[`docker-compose.yml`](../docker/docker-compose.yml) sets
+`DEVCLOUD_SERVICES=s3,sqs,dynamodb,iam,sts,lambda`. Edit that line, or see
+[Configuration](configuration.md#devcloud_services), to run more.
 
 ## Verify Installation
 
@@ -95,6 +98,8 @@ is exposed under `/devcloud/api/*`:
 - `GET /devcloud/api/services` — service status overview
 - `GET /devcloud/api/services/{id}/resources` — resource browser (buckets, queues, tables, functions)
 - `GET /devcloud/api/logs` — recent API call logs (`?limit=`)
+- `GET /devcloud/api/fidelity` — per-operation fidelity tiers (`?service=` to filter); see [fidelity-manifest.md](fidelity-manifest.md)
+- `GET /devcloud/api/unrouted` — calls made to services this build does not register; see [coverage.md](coverage.md)
 
 The web dashboard UI that consumes this API lives in a separate repository.