feat! breaking changes on kernel sources.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

1 files changed, 25 insertions, 0 deletions

diff --git a/src/libSystem/docs/SPECIFICATION_SYSCALLS.md b/src/libSystem/docs/SPECIFICATION_SYSCALLS.md
new file mode 100644
index 00000000..89f61498
--- /dev/null
+++ b/src/libSystem/docs/SPECIFICATION_SYSCALLS.md
@@ -0,0 +1,25 @@
+===================================
+# 0: General Information
+===================================
+
+- **Programming Language**: C / C++
+- **Build System**: Make / NeBuild 
+- **Purpose**: System Call Interface (SCI) for NeKernel
+
+===================================
+# 1: How It Works
+===================================
+
+- This header provides the raw API surface for accessing NeKernel's system calls.
+
+- It is **not** directly used by applications.
+    - Instead, it is abstracted by the **SystemSDK**, which presents a stable, high-level interface.
+
+- At runtime:
+    - System calls are routed from user-space code to the **kernel syscall manager**.
+    - The syscall manager executes the requested operation and returns control to `libSystem`.
+    - Finally, the result is delivered back to the originating process.
+
+- This separation ensures that:
+    - The SCI remains low-level and close to the ABI.
+    - `SystemSDK` provides portability and shielding from changes in syscall internals.
\ No newline at end of file