docs(agents): split PITFALLS.md into topic files under AGENTS/PITFALLS

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

1 files changed, 23 insertions, 0 deletions

diff --git a/AGENTS/PITFALLS/modules-and-stdlib.md b/AGENTS/PITFALLS/modules-and-stdlib.md
new file mode 100644
index 0000000..102e07a
--- /dev/null
+++ b/AGENTS/PITFALLS/modules-and-stdlib.md
@@ -0,0 +1,23 @@
+# Multi-file builds and the standard library
+
+Part of the [pitfalls index](../PITFALLS.md).
+
+- **Multi-file extensions.** INCLUDE imports symbols, never text; every included file
+  must also be an input.
+  - Duplicate exports across files fail even without visibility, except distinct
+    signatures whose definitions all specify OVERLOAD.
+  - Only one file may contain top-level code; top-level DECLARE is a main local, not
+    an export.
+  - Definitions-only builds now fail without FUNCTION MAIN returning INTEGER. MAIN
+    cannot coexist with top-level code.
+  - GLOBAL accepts only the five primitive scalar types and literal initializers;
+    arrays, user types and computed initializers are rejected.
+  - Own top-level constants remain positional, imported constants do not.
+- **Default standard library.** std.cps and its imported STRING library are embedded
+  and automatically linked.
+  - Use -no-std before explicitly supplying a replacement STRING class/library;
+    otherwise duplicate definitions fail.
+  - Ordinary literals require a visible STRING class with NEW(C_STRING).
+  - C_TYPE/INCLUDE/EXTERN syntax strings are parser metadata and do not construct
+    STRING.
+  - -S emits IR only; manual linking needs string.o and the C++ runtime.