docs: document library crate, exec and rootfs cache apis

README gains a Library section covering prepare, the exec options
(envp, bind targets, arch) and the provisioned-rootfs hot-cell flow.
SPEC documents the workspace layout, the library API, the cache
sidecars (.digest, .provisioned) and the updated execution flow.
AGENTS.md scope paths follow the new crates/ layout.

README.md

@@ -16,6 +16,56 @@ ecr fedora          # any Docker Hub image
 
 `ecr` pulls a root filesystem (Alpine/Ubuntu direct from their CDNs; everything else from Docker Hub), extracts it into a temporary directory, and execs a shell inside a user + mount + PID + UTS namespace. The process tree is isolated, the rootfs is discarded on exit, and your host is never touched.
 
+## Library
+
+`ecr` is a cargo workspace: `crates/ecr` is the library crate (package `ecr`), `crates/ecr-cli` the thin command-line front-end. Rust consumers can use the library directly — resolve an image, download it through the content cache, and run commands with a fully caller-controlled environment, bind targets and architecture:
+
+```toml
+[dependencies]
+ecr = { git = "https://github.com/…" } # or a path / registry source
+```
+
+```rust
+use ecr::{chroot, BindTarget, ExecOptions, PrepareRequest, RootfsCache};
+
+// Download alpine through the cache (~/.cache/ecr) and extract to a scratch dir
+let cache = RootfsCache::new(RootfsCache::default_dir()?);
+let rootfs = cache.prepare(&PrepareRequest::new("alpine:3.23"))?;
+
+// Caller-composed envp, explicit bind targets, target architecture
+let code = rootfs.exec(&ExecOptions {
+    arch: "amd64".into(),                                    // empty = host arch
+    binds: vec![BindTarget {                                 // host dir -> in-rootfs mount
+        source: "./data".into(),
+        target: "/mnt/data".into(),
+        read_only: false,                                    // true = overlay (ro)
+    }],
+    env: chroot::default_env(rootfs.dir()),                  // or your own envp
+    command: vec!["cat".into(), "/etc/os-release".into()],
+    ..ExecOptions::default()
+})?;
+
+rootfs.persist()?; // write the rootfs back into the cache (see below)
+```
+
+### Provisioned-rootfs caching (hot cells)
+
+Prepare once, provision once, amortize every later run — including runs from other processes sharing the same cache directory:
+
+```rust
+let rootfs = cache.prepare_provisioned(&PrepareRequest::new("alpine:3.23"), |rootfs| {
+    // runs at most once per cache entry
+    rootfs.exec(&ExecOptions {
+        command: vec!["apk".into(), "add".into(), "curl".into()],
+        env: chroot::default_env(rootfs.dir()),
+        ..ExecOptions::default()
+    })?;
+    Ok(())
+})?;
+```
+
+On the first call the pristine image is downloaded, the closure provisions it, and the result is persisted into the cache with a `.provisioned` marker. On every subsequent call the entry is hit directly: no download, no provisioning. Note a provisioned entry no longer tracks the upstream image; delete the entry (or pass `no_cache: true`) to re-provision.
+
 ## Usage
 
 ```
@@ -105,7 +155,7 @@ Requirements:
 
 ## Cache
 
-Downloaded images are cached in `~/.cache/ecr/`. For `latest` OCI tags the registry manifest digest is checked on each run — the image is only re-downloaded when it has actually changed. Use `--no-cache` to force a fresh pull regardless.
+Downloaded images are cached in `~/.cache/ecr/`. For `latest` OCI tags the registry manifest digest is checked on each run — the image is only re-downloaded when it has actually changed. Use `--no-cache` to force a fresh pull regardless. The library's `PreparedRootfs::persist` can replace a cache entry with a provisioned rootfs (see *Provisioned-rootfs caching* above).
 
 ## Requirements