Related to #138

1 files changed, 57 insertions, 1 deletions

diff --git a/README.md b/README.md
index 87f95af..fc1aa27 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,7 @@ Join the discussion, share demos, ask questions, or report bugs in the official
         - [Named Constraints](#named-constraints)
     - [15. Build Directives](#15-build-directives)
     - [16. Keywords](#16-keywords)
+    - [17. C Interoperability](#17-c-interoperability)
 - [Standard Library](#standard-library)
 - [Tooling](#tooling)
     - [Language Server (LSP)](#language-server-lsp)
@@ -204,7 +205,11 @@ let y: const int = 10;  // Read-only (Type qualified)
 
 | Type | C Equivalent | Description |
 |:---|:---|:---|
-| `int`, `uint` | `int`, `unsigned int` | Platform standard integer |
+| `int`, `uint` | `int32_t`, `uint32_t` | 32-bit signed/unsigned integer |
+| `c_char`, `c_uchar` | `char`, `unsigned char` | C char / unsigned char (Interop) |
+| `c_short`, `c_ushort` | `short`, `unsigned short` | C short / unsigned short (Interop) |
+| `c_int`, `c_uint` | `int`, `unsigned int` | C int / unsigned int (Interop) |
+| `c_long`, `c_ulong` | `long`, `unsigned long` | C long / unsigned long (Interop) |
 | `I8` .. `I128` or `i8` .. `i128` | `int8_t` .. `__int128_t` | Signed fixed-width integers |
 | `U8` .. `U128` or `u8` .. `u128` | `uint8_t` .. `__uint128_t` | Unsigned fixed-width integers |
 | `isize`, `usize` | `ptrdiff_t`, `size_t` | Pointer-sized integers |
@@ -217,6 +222,12 @@ let y: const int = 10;  // Read-only (Type qualified)
 | `iN` (for example, `i256`) | `_BitInt(N)` | Arbitrary bit-width signed integer (C23) |
 | `uN` (for example, `u42`) | `unsigned _BitInt(N)` | Arbitrary bit-width unsigned integer (C23) |
 
+> **Best Practices for Portable Code**
+>
+> - Use **Portable Types** (`int`, `uint`, `i64`, `u8`, etc.) for all pure Zen C logic. `int` is guaranteed to be 32-bit signed on all architectures.
+> - Use **C Interop Types** (`c_int`, `c_char`, `c_long`) **only** when interacting with C libraries (FFI). Their size varies by platform and C compiler (e.g. `c_long` size differs between Windows and Linux).
+> - Use `isize` and `usize` for array indexing and memory pointer arithmetic.
+
 ### 3. Aggregate Types
 
 #### Arrays
@@ -1092,6 +1103,51 @@ The following identifiers are reserved because they are keywords in C11:
 #### Operators
 `and`, `or`
 
+### 17. C Interoperability
+
+Zen C offers two ways to interact with C code: **Trusted Imports** (Convenient) and **Explicit FFI** (Safe/Precise).
+
+#### Method 1: Trusted Imports (Convenient)
+
+You can import a C header directly using the `import` keyword with the `.h` extension. This treats the header as a module and assumes all symbols accessed through it exist.
+
+```zc
+//> link: -lm
+import "math.h" as c_math;
+
+fn main() {
+    // Compiler trusts correctness; emits 'cos(...)' directly
+    let x = c_math::cos(3.14159);
+}
+```
+
+> **Pros**: Zero boilerplate. Access everything in the header immediately.
+> **Cons**: No type safety from Zen C (errors caught by C compiler later).
+
+#### Method 2: Explicit FFI (Safe)
+
+For strict type checking or when you don't want to include the text of a header, use `extern fn`.
+
+```zc
+include <stdio.h> // Emits #include <stdio.h> in generated C
+
+// Define strict signature
+extern fn printf(fmt: char*, ...) -> c_int;
+
+fn main() {
+    printf("Hello FFI: %d\n", 42); // Type checked by Zen C
+}
+```
+
+> **Pros**: Zen C ensures types match.
+> **Cons**: Requires manual declaration of functions.
+
+#### `import` vs `include`
+
+- **`import "file.h"`**: Registers the header as a named module. Enables implicit access to symbols (for example, `file::function()`).
+- **`include <file.h>`**: Purely emits `#include <file.h>` in the generated C code. Does not introduce any symbols to the Zen C compiler; you must use `extern fn` to access them.
+
+
 ---
 
 ## Standard Library