diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f6c7502
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+# Claude Code Docker Setup
+
+A Docker setup for running Claude Code. Note that the firewall is **not configured by just using this repo** — additional host-level setup is required to isolate the container from your LAN.
+
+## Firewall setup
+
+Firewall isolation requires three pieces working together:
+
+**1. Docker daemon config** — [etc_conf/daemon.json](https://gitea.efforting.tech/mikael-lovqvist/claude-docker/src/commit/94fd1de8ea3ef054ee5c45edc4988014dfbfd69c/etc_conf/daemon.json)
+
+Restricts the address pool Docker uses for automatic network assignment to `172.16.0.0/13`. This prevents Docker from accidentally assigning the `172.28.x.x` range used by the Claude container to other networks.
+
+Place at `/etc/docker/daemon.json` and restart Docker.
+
+**2. docker-compose.yml network** — the container is placed on `172.28.0.0/24`, which is outside the auto-assign pool above, giving it a known, stable subnet.
+
+**3. nftables rules** — [etc_conf/nftables.conf](https://gitea.efforting.tech/mikael-lovqvist/claude-docker/src/commit/94fd1de8ea3ef054ee5c45edc4988014dfbfd69c/etc_conf/nftables.conf)
+
+Drops forwarded traffic from the Docker address range (`172.16.0.0/12`, which covers `172.28.x.x`) destined for your LAN. The relevant rule is [line 31](https://gitea.efforting.tech/mikael-lovqvist/claude-docker/src/commit/94fd1de8ea3ef054ee5c45edc4988014dfbfd69c/etc_conf/nftables.conf#L31):
+
+```nft
+ip saddr 172.16.0.0/12 ip daddr 192.168.0.0/16 drop
+```
+
+**Make sure your LAN subnet is covered by the destination range here.** If your LAN uses a different range (e.g. `10.0.0.0/8`), you need to add a corresponding rule.
+
+Place at `/etc/nftables.conf` and enable/reload nftables.
diff --git a/todo.md b/todo.md
new file mode 100644
index 0000000..be7dfed
--- /dev/null
+++ b/todo.md
@@ -0,0 +1,15 @@
+# Documentation TODO
+
+## README additions
+
+- **File placement guide** — where each file goes on the host (`daemon.json` → `/etc/docker/daemon.json`, `nftables.conf` → `/etc/nftables.conf`, etc.)
+- **Setup order** — step-by-step: daemon config → restart Docker → nftables → build image → create workspace + `.env` → run
+- **Run instructions** — `docker compose run --rm claude-code`, mention `--build-arg UID/GID` for matching host user
+- **Security model** — explain the layered approach: Docker network subnet isolation + nftables forward chain blocking LAN access
+- **Partial load behaviour** — what happens if nftables isn't running, or only part of the config is loaded
+- **Granting LAN access opt-in** — how to punch a hole for a specific host/port (e.g. a local database), with priority ordering explanation
+- **Volume mounts** — explain `./workspace:/workspace` and `./claude-home:/home/claude` and their purpose (persistent home, bind-mounted project dir)
+
+## dockerfile.md
+
+- Update code block in user setup section to match current Dockerfile (shows old single-line version without the conditional deletions)