llm-friendly readme, name fix

example/.safeclaude/README.md

@@ -0,0 +1,35 @@
+# .safeclaude/ — this project's sandboxed environment
+
+This folder defines the container that `safeclaude` runs Claude in. The container
+is built from these files, so changing the environment means editing them on the
+host and rebuilding — not installing things inside the running container (which
+is a non-root sandbox and gets reset each run).
+
+## What's here
+
+- `Dockerfile` — the container image: system packages and pinned language
+  versions (one Ruby, one Node, etc.). Built once, then cached.
+- `hooks/*.sh` — scripts that run at every startup, with the project at `/code`.
+  Use these for setup that needs your code present or should run each launch
+  (installing dependencies, starting a service proxy). Keep them safe to re-run.
+- `cache/` — scratch space on the host, gitignored. A good home for installed
+  dependencies, downloads, or "already did this" markers; survives rebuilds and
+  `docker volume` resets.
+- `.env` — secrets passed into the container at runtime (gitignored; copy from
+  `.env.example`).
+- `version` — the safeclaude version this config was created with.
+
+## How to change the environment
+
+The container runs as a non-root user with no sudo, so you can't install system
+packages from inside it. Instead, edit these files on the host:
+
+- **Add a system package:** add it to `Dockerfile`, then run `safeclaude build`.
+- **Add a language or tool:** install a specific version in `Dockerfile` — pin
+  it, since a project only needs one. See the repo's `example/` for a worked
+  Ruby + Node setup.
+- **Run setup at startup:** add or edit a script in `hooks/` (no rebuild needed).
+- **Add a secret:** put it in `.env` (see `.env.example`).
+
+After editing the `Dockerfile`, run `safeclaude build` to rebuild. Hook, `.env`,
+and `cache/` changes take effect on the next launch with no rebuild.

example/README.md

@@ -21,6 +21,7 @@ reference you can copy from when setting up your own project.
 | `hooks/30-pg-proxy.sh` | each launch | lets the app reach the host's Postgres at the usual `127.0.0.1:5432` |
 | `.env.example` | — | copy to `.env` for a private gem token (kept out of git) |
 | `version` | — | the safeclaude version this config was created with |
+| `README.md` | — | how this environment works (also read by the sandboxed Claude) |
 
 A couple of things to take away: