docs: document EXTERN and INCLUDE_OBJ

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

3 files changed, 22 insertions, 2 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index cb0bc20..0479641 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -25,7 +25,8 @@ imports cover standard C integer/real types, _Bool, void and object pointers.
 CScalar/CPointer identities are canonical C types, not pseudocode alias names;
 native widths and signedness come from sizeof/type traits, while floating formats
 come from numeric_limits (long double size alone is insufficient). Programs use
-the compiler's build ABI; cross-target emission and EXTERN are not implemented.
+the compiler's build ABI; cross-target emission is not implemented. EXTERN "C"
+declarations call C functions from INCLUDE_OBJ objects (see SUBSYSTEMS.md).
 CTypeGen handles typed numeric conversions, casts, native arithmetic and I/O.
 Crossing C/pseudocode domains requires a cast, including literals. C arithmetic
 uses C++ promotions, except that / always returns pseudocode REAL.
diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md
index 8f35c3d..551a64c 100644
--- a/AGENTS/PITFALLS.md
+++ b/AGENTS/PITFALLS.md
@@ -145,7 +145,13 @@ test programs.
   require casts even for literals. C scalar arithmetic uses native promotions,
   but / always returns REAL. Cast aliases must precede their use. long double
   may have padding; sizeof does not identify its floating-point format. Native
-  C support is verified on Linux LLVM 23; cross-target and EXTERN are unsupported.
+  C support is verified on Linux LLVM 23; cross-target is unsupported.
+- **EXTERN "C" extension.** Top-level, body-less; parameters/results are C types only,
+  no BYREF/OVERLOAD/structs. Variadic arguments must be C values (default promotions).
+  The driver checks every EXTERN symbol against INCLUDE_OBJ inputs before CodeGen;
+  `"__libc"` must be included explicitly even though the runtime always links libc.
+  Only `.o` user objects; INCLUDE_OBJ is global across inputs. `-S` does not link them.
+  Two EXTERNs differing only in case conflict (pseudocode names are case insensitive).
 
 ## Not implemented (9618 features)
 
diff --git a/AGENTS/SUBSYSTEMS.md b/AGENTS/SUBSYSTEMS.md
index dab3146..866d39e 100644
--- a/AGENTS/SUBSYSTEMS.md
+++ b/AGENTS/SUBSYSTEMS.md
@@ -43,6 +43,19 @@ compile error (no extern is fabricated). Functions inherit visible GLOBAL storag
 `StmtEmitter` callback, and must restore its own insert point (and the exchanged
 ArrayTable) afterwards.
 
+**EXTERN "C"** (`ExternDeclAST`, `IncludeObjStmtAST`): the parser builds a body-less
+`PrototypeAST` (IsExternal, IsVariadic, unnamed `argN` params). `FunctionGen::emitExternPrototype`
+validates C types, records a `FuncSig` with `IsExternal`, the declared `FunctionType` and
+sext/zext attributes for sub-32-bit integers, and `getOrInsertFunction`s the exact symbol.
+Calls go through `FunctionGen::emitCall(const FuncSig &, ...)` with that type, so a
+runtime declaration of the same libc symbol with another type is harmless.
+`CodeGen::emitVariadicArgument` applies C default promotions. The driver (`main.cc`)
+resolves INCLUDE_OBJ paths, reads defined global symbols with `llvm::object`
+(`collectObjectSymbols`; `"__libc"` uses `collectLibcSymbols` over the embedded runtime's
+libc/libm inputs, copied to aligned buffers), rejects missing symbols, and passes objects
+to `compileNative`, `runEmbedded` (`addObjectFile`) or lli (`-extra-object=`).
+Linux is verified; the Windows/macOS libc file-name rules and the lli path are not.
+
 **User types** (`TypeSystem` + `Designator.cc` + `TypeCheckGen.cc`):
 `Designator.cc` owns the type pre-pass and lvalue access; `TypeCheckGen.cc` owns
 type admission and user-kind binary operators. TYPE declarations are top-level only