diff --git a/docs/reference/language/strings.md b/docs/reference/language/strings.md
index 8703ea2c..8db59bc7 100644
--- a/docs/reference/language/strings.md
+++ b/docs/reference/language/strings.md
@@ -8,6 +8,15 @@ Status: Design committed. This document defines how Nyash treats text vs bytes a
 - Bytes are not text. Byte operations live in a separate `ByteCursorBox` and byte‑level instructions.
 - Conversions are explicit.
 
+## Implementation Note (Current Runtime)
+
+The Rust runtime currently supports a legacy performance/compatibility switch:
+
+- Default: **byte** indexing for `length/indexOf/lastIndexOf/substring`
+- `NYASH_STR_CP=1`: **code point** indexing for the same APIs
+
+This applies to both primitive `String` and `StringBox` paths. Long-term, the language-level SSOT is CP semantics; the env toggle exists to keep migrations reversible while the VM/runner paths are being unified.
+
 ## Model
 - `StringBox`: immutable UTF‑8 string value. Public text APIs are CP‑indexed.
 - `Utf8CursorBox`: delegated implementation for scanning and slicing `StringBox` as CPs.