docs(language): document native C types and explicit casts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

5 files changed, 43 insertions, 3 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index 2551161..be98732 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -15,10 +15,20 @@ INTEGER = `i64`, REAL = `double`, BOOLEAN = `i1`, CHAR = `i8`, STRING = opaque `
 to a NUL-terminated buffer. User-defined types (§4): enum = `i64` (0-based ordinal),
 pointer = opaque `ptr`, record = named struct `%record.NAME`. Enum/pointer are
 LLVM-identical to INTEGER/STRING **by design** — their identity lives in the type
-*name*, enforced upstream (see CONVENTIONS.md). Byte sizes are never computed
-host-side: the module has no DataLayout string, so every size is a null-GEP
+*name*, enforced upstream (see CONVENTIONS.md). Allocation byte sizes are never computed
+host-side: the module has no DataLayout string, so every allocation size is a null-GEP
 `sizeof` constant (`TypeSystem::getSizeOfConstant`) folded by the backend.
 
+C_INT/C_CHAR/C_STRING/C_DOUBLE alias native int/char/char*/double. C_TYPE string
+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.
+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.
+
 ## Build & run
 
 The compiler emits textual IR. Initial configuration must explicitly select
@@ -167,6 +177,7 @@ untested.)
 | `lib/Parser/ParserType.cc` | TYPE/ENDTYPE and CLASS/ENDCLASS declarations, shared field parsing, SET/DEFINE reserved stubs |
 | `lib/CodeGen/CodeGen.cc` | Hub: dispatch, coercion, control flow, INPUT/OUTPUT, main() |
 | `lib/CodeGen/Designator.cc` | CodeGen methods for the TYPE system: type pre-pass, `emitLValue`/`loadFromLValue`, `emitCoercedExpr` gate, user-kind binary-op interception |
+| `lib/CodeGen/CTypeGen.cc` | CodeGen methods for native C scalar conversions, casts, arithmetic and input/output |
 | `lib/CodeGen/*Handler.cc`, `FunctionGen.cc`, `RuntimeCheck.cc`, `TypeSystem.cc` | Helpers owned by CodeGen (including exception emission) |
 | `CMakeLists.txt` | 3 static libs (CPSLexer, CPSParser, CPSCodeGen) + `cpsc`. **New .cc files must be added to the source lists here** |
 | `tools/driver/EmbeddedRunner.cc`, `cmake/EmbeddedLLVM.cmake` | EMBEDDED-only MCJIT runner and static support-library selection |
diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md
index b38b73c..01d4ab2 100644
--- a/AGENTS/CONVENTIONS.md
+++ b/AGENTS/CONVENTIONS.md
@@ -30,6 +30,18 @@ user-defined names) — never an enum. `TypeSystem` resolves the string to
 identifier as a type name except `VOID` (rejected outside a RETURNS clause via its
 `AllowVoid` flag); other unknown types only fail (softly) in CodeGen.
 
+**C aliases are structural within the C domain.** `CIdentity` retains the canonical
+C base type and pointer levels independently of the alias `Name`. Use `sameType`
+for storage compatibility (including BYREF and array arguments); never equate C
+types just because their LLVM types or widths match. CScalar/CPointer values are
+handled by CTypeGen, not the legacy representation coercions. Cross-domain
+assignments, arguments and operators require explicit casts, including literals.
+Plain C char uses native signedness; pseudocode CHAR stays unsigned. Numeric
+conversions use source signedness, and native floating formats use numeric_limits.
+Allocation sizes still use LLVM sizeof; native C type widths use build-compiler
+sizeof. C alias declarations precede casts using their names; the parser tracks
+declared type names to distinguish `(Type)operand` from `(expression)`.
+
 **User-kind typing is nominal, and checked upstream only.** Enum/Record/Pointer
 identity is name equality (`P1 = ^INTEGER` and `P2 = ^INTEGER` are incompatible;
 same-layout records too). Their LLVM representations are indistinguishable from
diff --git a/AGENTS/EXTENDING.md b/AGENTS/EXTENDING.md
index 43af5e0..ac9f50e 100644
--- a/AGENTS/EXTENDING.md
+++ b/AGENTS/EXTENDING.md
@@ -45,6 +45,14 @@ OUTPUT/INPUT/WRITEFILE/file-name operands, FOR variables, builtin args,
 `getExprTypeInfo` classification. Everything not explicitly admitted must be a
 compile error.
 
+**Native C types:** add representation/format metadata in TypeSystem's native
+registration, using compiler-derived facts rather than fixed widths. Preserve
+canonical CIdentity and alias compatibility. Update CTypeGen conversions,
+promotions and I/O together; never let native C operands fall through to the
+legacy ArithmeticHandler or representation-only coercions. C_TYPE parses a
+string import, not an ordinary function call. Casts are CastExprAST values;
+their type must be recognized by both emission and getExprTypeInfo.
+
 **New designator access form:** `AccessKind` case in `TypeAST.h` +
 `ParseDesignatorSuffix` + the walk in `CodeGen::emitLValue` **and** the static
 walk in `getExprTypeInfo`'s designator branch (they must agree) — plus the
diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md
index ce72de8..6e0202e 100644
--- a/AGENTS/PITFALLS.md
+++ b/AGENTS/PITFALLS.md
@@ -86,6 +86,15 @@ test programs.
   Unwinding does not free heap strings/arrays or close files. Linux LLVM 18 is
   verified; Windows and macOS exception execution is not.
 
+- **C type extensions.** C_STRING is a raw char pointer, not a STRING: explicitly
+  cast to STRING for printing or builtins. C aliases share canonical CIdentity;
+  do not use LLVM widths to recover signedness or nominal type identity. Plain
+  char's signedness is native, unlike pseudocode CHAR. C/pseudocode conversions
+  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 18; cross-target and EXTERN are unsupported.
+
 ## Not implemented (9618 features)
 
 CASE OF, CONSTANT, SET types (`SET`/`DEFINE` are reserved with dedicated errors),
diff --git a/AGENTS/SUBSYSTEMS.md b/AGENTS/SUBSYSTEMS.md
index 95e1abb..7d1ea5c 100644
--- a/AGENTS/SUBSYSTEMS.md
+++ b/AGENTS/SUBSYSTEMS.md
@@ -64,7 +64,7 @@ context or language-level inheritance yet.
 **Runtime checks** (`RuntimeCheck`): array bounds, file misuse, enum ranges, null
 dereferences and array-parameter bounds contracts are checked at their emit sites.
 `ArithmeticHandler` calls `emitDivZeroCheck` before `/`, DIV and MOD; the check accepts
-i64 and double divisors, including both floating-point signed zeros.
+integer and floating-point divisors, including both floating-point signed zeros.
 `emitCheck(Cond)` splits the block and calls `ExceptionHandler::emitThrow` on failure.
 No check prints an error; source-line parameters remain reserved for future diagnostics.