docs: sandbox file injection — CLI, SANDBOXING, README

Author: jkyberneees

README.md

@@ -33,7 +33,7 @@ odek is not a framework. It's a **runtime** — the smallest possible surface ar
 ## Strategic Features
 
 ### 🔒 Sandboxed Execution
-`odek run --sandbox` — every session spawns an isolated Docker container. No network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. Full security model in [docs/SANDBOXING.md](docs/SANDBOXING.md).
+`odek run --sandbox` — every session spawns an isolated Docker container. No network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. `--ctx` files are automatically injected into the container at `/workspace/`. Full security model in [docs/SANDBOXING.md](docs/SANDBOXING.md).
 
 ### 🧩 Sub-Agent Delegation
 Parallel OS-process sub-agents via `delegate_tasks`. True isolation — each sub-agent is a fresh `odek subagent` process with its own config, tools, and termination timeout. Up to 8 concurrent workers. [docs/SUBAGENTS.md](docs/SUBAGENTS.md)

docs/CLI.md

@@ -87,6 +87,10 @@ In `odek serve`:
 
 Files are read client-side in the Web UI and server-side in the CLI through `enrichTask()` in the `cmd/odek/refs.go` package. The `resource` package handles resolution: file content is wrapped in `--- filename ---` / `--- end filename ---` markers and prepended to the task.
 
+### Sandbox file injection
+
+When `--sandbox` is active, `--ctx` files are automatically **copied into the sandbox container** via `docker cp`, placed at `/workspace/<relative-path>`. Files outside the working directory use their basename. This means the agent can use tools (`read_file`, `shell cat`, `patch`) on the same files it sees in context — no "content visible but file doesn't exist" gap. Directories and missing files are silently skipped.
+
 ## Shell tool schema
 
 ```json

docs/SANDBOXING.md

@@ -155,6 +155,17 @@ Build behavior:
 
 **Security note:** `bridge` gives the container internet access but isolates it from the host's network stack (no access to `localhost:port` on the host, no access to your LAN). `host` mode removes that isolation — use only when you need to connect to a service on the host.
 
+## File injection
+
+When running with `--sandbox --ctx <file>`, odek copies the ctx files into the container via `docker cp`:
+
+- Files within the working directory preserve their relative path (`--ctx subdir/file.txt` → `/workspace/subdir/file.txt`)
+- Files outside the working directory use their basename (`--ctx /etc/hosts` → `/workspace/hosts`)
+- Missing files and directories are silently skipped
+- In read-only mode, injection still works (docker cp writes to the container's overlay, not the volume bind-mount)
+
+This ensures the agent can both see the file content in its context **and** operate on the physical file using `read_file`, `patch`, `shell cat`, etc. without any "content visible but file doesn't exist" gap.
+
 ## Read-only mode
 
 When `sandbox_readonly` is `true`, the working directory is mounted **read-only** inside the container: