docs(memory): describe standard-library allocation and explicit imports

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

3 files changed, 14 insertions, 10 deletions

diff --git a/AGENTS/CONVENTIONS/CALLS.md b/AGENTS/CONVENTIONS/CALLS.md
index 3fc2daa..55b3647 100644
--- a/AGENTS/CONVENTIONS/CALLS.md
+++ b/AGENTS/CONVENTIONS/CALLS.md
@@ -32,9 +32,10 @@ bridge C void* and nominal pseudocode pointer types.
   An expression's expected result type filters overloads when present. Overload sets,
   visibility filtering and exact selection:
   [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution).
-- In all cases, `emitPrototype` rejects names that collide with runtime/libc symbols
-  (`isReservedRuntimeName`), builtins, or enum values. Signatures retain the first
-  declaration spelling for LLVM lookup, independently of call-site casing.
+- `emitPrototype` rejects builtin and enum names. Ordinary non-EXTERN, non-OVERLOAD
+  definitions also reject runtime/libc names (`isReservedRuntimeName`); OVERLOAD
+  definitions have signature-mangled symbols and cannot replace libc symbols.
+  Signatures retain the first declaration spelling for LLVM lookup, independently of call-site casing.
 - Methods use `Class.Method` names and a hidden leading receiver address; their
   FuncSig parameters contain only explicit source parameters.
 
@@ -52,11 +53,12 @@ callback CodeGen injects into FunctionGen). BYVAL arrays copy their buffer at ca
 entry and clone STRING-bearing elements; BYREF binds the caller's buffer.
 
 **Builtins are plain identifiers backed by one table.** Builtins
-(EOF/MALLOC/FREE/REALLOC) parse as ordinary calls — no lexer/parser support, and the
+(EOF/INT) parse as ordinary calls — no lexer/parser support, and the
 names are not reserved words. The inline constexpr `Builtins` table in the internal
 `lib/CodeGen/Builtins.h` ({Name, Arity, ReturnTypeName}) is the single source of
 truth: `emitCall` checks arity against it before dispatching to the per-builtin emit
 branches (still an if-chain, ahead of the user-function fallback), and
-`getExprTypeInfo` reads return types from it. EOF and the memory builtins consume the
-call source line for runtime diagnostics; they touch mutable runtime state and can
-throw.
+`getExprTypeInfo` reads return types from it. EOF and INT consume the call source
+line for runtime diagnostics and can throw.
+MALLOC/REALLOC/FREE are ordinary OVERLOAD functions in memory.cps, with no builtin
+dispatch or type rules in the compiler.
diff --git a/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md b/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md
index deed7ec..8ee97ec 100644
--- a/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md
+++ b/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md
@@ -41,8 +41,10 @@ it only on non-library to library calls. Runtime helper line arguments use
 RuntimeCheck::lineValue too. Compiler diagnostics retain the owning file location.
 
 **Default standard library.** The driver extracts embedded std.cps, its imported units
-and matching objects to a temporary directory that survives linking/execution. User
+and matching objects to a content-keyed cache (or temporary fallback) that survives
+linking/execution. User
 units implicitly import std.cps; normal transitive visibility applies. -no-std
-suppresses all default library inputs and objects. Explicit libraries retain the
+suppresses all default library inputs and objects. std.cps imports string.cps and
+memory.cps; keyword NEW/DELETE require the latter even with -no-std. Explicit libraries retain the
 ordinary INCLUDE/command-line rules. Source files and objects are embedded by a
 build-time Perl generator. Saved -S output remains IR only.
diff --git a/AGENTS/CONVENTIONS/STRINGS.md b/AGENTS/CONVENTIONS/STRINGS.md
index 9bb81cf..d07c217 100644
--- a/AGENTS/CONVENTIONS/STRINGS.md
+++ b/AGENTS/CONVENTIONS/STRINGS.md
@@ -26,5 +26,5 @@ handles. Records and BYVAL arrays containing STRING recursively copy their
 string-bearing fields/elements; RETURN and temporary cleanup preserve ownership.
 C_STRING casts borrow a STRING buffer or construct an owning STRING copy in the other
 direction. FileHandler owns copied open-file names and frees them on close; READFILE
-buffers are copied into STRING and released. Explicit MemoryHandler allocations remain
+buffers are copied into STRING and released. Explicit memory-library allocations remain
 separate from these internal objects.