diff --git a/config.go b/config.go
index bb8013a..b11ddac 100644
--- a/config.go
+++ b/config.go
@@ -112,6 +112,13 @@ func DisableGlobalReassign() {
 // touch on the host. Policy layers use it to derive module sets instead of
 // maintaining hand-written name lists that silently rot as modules are
 // added.
+//
+// The bits model host *effects* (filesystem, network, process, log) only.
+// They deliberately say nothing about determinism or reproducibility: e.g.
+// random is CapPure (it has no host side effects) yet is non-deterministic
+// by design. A consumer that needs a "replayable / pure-function" set must
+// define it on its own side (excluding entropy/clock sources such as random
+// and time) rather than reading it off these capability bits.
 type ModuleCapability uint
 
 const (
diff --git a/lib/json/README.md b/lib/json/README.md
index 567fee4..d46ecb4 100644
--- a/lib/json/README.md
+++ b/lib/json/README.md
@@ -196,7 +196,7 @@ print(ok, err)
 
 ## Notes & boundaries
 
-- **Engines.** `encode`/`decode`/`indent` are go.starlark.net's stdlib `json`; `dumps` uses starlet's internal marshaler (handles host structs/modules); `path`/`eval` use [ajson](https://github.com/spyzhov/ajson) JSONPath; `repair` uses a vendored, frozen [jsonrepair](https://github.com/RealAlexandreAI/json-repair) (golden-locked); `validate` uses [santhosh-tekuri/jsonschema](https://github.com/santhosh-tekuri/jsonschema).
+- **Engines.** `encode`/`decode`/`indent` are go.starlark.net's stdlib `json`; `dumps` uses starlet's internal marshaler (handles host structs/modules); `path`/`eval` use [ajson](https://github.com/spyzhov/ajson) JSONPath; `repair` uses a vendored, frozen [jsonrepair](https://github.com/kaptinlin/jsonrepair) (golden-locked); `validate` uses [santhosh-tekuri/jsonschema](https://github.com/santhosh-tekuri/jsonschema).
 - **Purity.** No file or network access. JSON Schema `$ref` to external resources is blocked by design.
 - **Number shaping.** `path`/`eval` return integral numbers as `int` and non-integral as `float`; JSON `null` becomes `None`.
 - **`repair` vs `validate`.** `repair` fixes *text* and is idempotent on valid input; `validate` never mutates — it only reports conformance.