ci(lint markdown): Lint your markdown using rumdl

Also added getting started safety and why-nextstd stuff

Signed-off-by: Vaishnav Sabari Girish <vaishnav.sabari.girish@gmail.com>

Author: Vaishnav-Sabari-Girish

.github/workflows/markdown_lint.yml

@@ -0,0 +1,16 @@
+name: Markdown Lint
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  rumdl-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: rvben/rumdl@v0
+        with:
+          path: src

README.md

@@ -1,5 +1,38 @@
-# Documentation
+# Introduction to NextStd
 
-This is the Documentation repo for [NextStd](https://github.com/NextStd)
+Welcome to the official documentation for **NextStd**—the safer,
+modern alternative to the traditional C standard library.
+
+For decades, C developers have relied on `<stdio.h>`, `<string.h>`,
+and `<stdlib.h>`. While incredibly fast, these legacy libraries are
+fundamentally unsafe. A single mismatched `%d` in a `printf`, a missing
+`\0` in a string, or a silent `NULL` pointer can trigger catastrophic
+Segmentation Faults, buffer overflows, and security vulnerabilities.
+
+NextStd fixes this at the foundation.
+
+By combining the elegant simplicity of C11 macros on the
+frontend with the mathematically proven memory safety of Rust
+on the backend, NextStd delivers a zero-compromise development experience.
+
+## Core Pillars of NextStd
+
+* **Type-Safe I/O:** Never write a format specifier again. NextStd uses C11
+`_Generic` macros to automatically route data types at compile time.
+* **Crash-Proof Control Flow:** Replace silent failures and dangerous `goto`
+statements with Python-style `NS_TRY` and `NS_EXCEPT` macros.
+* **Immunity to NULL:** Every FFI boundary rigorously checks for `NULL`
+pointers. Passing bad memory to NextStd gracefully returns an error
+code instead of killing your program.
+* **Modern String Memory:** Strings are powered by Small String Optimization
+(SSO), meaning short text costs zero heap allocations, and massive text safely
+catches Out-Of-Memory (OOM) errors without panicking.
+
+### Who is this for?
+
+NextStd is built for C developers, systems programmers, and embedded engineers
+who want the safety guarantees of a modern language without actually having to
+rewrite their entire codebase in Rust. It compiles down to a standard static or
+dynamic C library (`.a`, `.so`, `.dylib`, or `.dll`) and links identically t
+o any standard C dependency.
 
-The documentation is created using `mdbook`

rumdl.toml

@@ -0,0 +1,3 @@
+[MD013]
+line-length = 80
+reflow = true

src/README.md

@@ -1 +1,45 @@
-# Introduction
+# Introduction to NextStd
+
+Welcome to the official documentation for **NextStd**—the safer,
+modern alternative to the traditional C standard library.
+
+For decades, C developers have relied on `<stdio.h>`, `<string.h>`,
+and `<stdlib.h>`. While incredibly fast, these legacy libraries are
+fundamentally unsafe. A single mismatched `%d` in a `printf`, a missing
+`\0` in a string, or a silent `NULL` pointer can trigger catastrophic
+Segmentation Faults, buffer overflows, and security vulnerabilities.
+
+NextStd fixes this at the foundation.
+
+By combining the elegant simplicity of C11 macros on the
+frontend with the mathematically proven memory safety of Rust
+on the backend, NextStd delivers a zero-compromise development experience.
+
+## Core Pillars of NextStd
+
+* **Type-Safe I/O:** Never write a format specifier again. NextStd uses C11
+`_Generic` macros to automatically route data types at compile time.
+* **Crash-Proof Control Flow:** Replace silent failures and dangerous `goto`
+statements with Python-style `NS_TRY` and `NS_EXCEPT` macros.
+* **Immunity to NULL:** Every FFI boundary rigorously checks for `NULL`
+pointers. Passing bad memory to NextStd gracefully returns an error
+code instead of killing your program.
+* **Modern String Memory:** Strings are powered by Small String Optimization
+(SSO), meaning short text costs zero heap allocations, and massive text safely
+catches Out-Of-Memory (OOM) errors without panicking.
+
+### Who is this for?
+
+NextStd is built for C developers, systems programmers, and embedded engineers
+who want the safety guarantees of a modern language without actually having to
+rewrite their entire codebase in Rust. It compiles down to a standard static or
+dynamic C library (`.a`, `.so`, `.dylib`, or `.dll`) and links identically t
+o any standard C dependency.
+
+### Ready to upgrade your C code?
+
+Navigate through this book using the sidebar to the left. We recommend starting
+with **[Why NextStd?](intro/why-nextstd.md)** for a deeper dive into the
+architectural philosophy, or jumping straight into
+**[Getting Started](getting-started/getting-started.md)** to write your first
+safe program!

src/SUMMARY.md

@@ -4,7 +4,7 @@
   - [Why NextStd?](intro/why-nextstd.md)
   - [Safety Guarantees](intro/safety.md)
 
-- [Getting Started](getting-started/README.md)
+- [Getting Started](getting-started/getting-started.md)
   - [Installation & Linking](getting-started/installation.md)
   - [Your First Program](getting-started/hello-world.md)
   - [Build System Integration](getting-started/build-systems.md)

src/getting-started/README.md

@@ -1 +1,62 @@
 # Safety Guarantees
+
+When we say NextStd is "safe," we aren't just talking about compiler warnings or
+best practices. We are talking about architectural guarantees enforced at the
+Foreign Function Interface (FFI) boundary between C and Rust.
+
+Here are the core vulnerability classes that NextStd entirely eliminates from
+your C codebase.
+
+## 1. Null Pointer Immunity (No More Segfaults)
+
+In standard C, passing a `NULL` pointer to `strlen()` or `strcpy()` results in
+immediate Undefined Behavior, typically manifesting as a fatal Segmentation
+Fault.
+
+NextStd actively intercepts bad memory. Every single FFI boundary function in
+the library checks for `NULL` before performing any operations. If a `NULL`
+pointer is detected, the operation is safely aborted, and an `NS_ERROR_ANY` code
+is returned for your `NS_TRY` block to catch gracefully.
+
+## 2. Out-of-Memory (OOM) Protection
+
+Standard C's `malloc` returns `NULL` when the heap is exhausted—a condition
+developers frequently forget to check. Standard Rust, on the other hand, will
+panic and instantly crash the program when an allocation fails.
+
+NextStd takes the safe middle path. It uses Rust's `try_reserve` API for all
+dynamic heap allocations. If the system runs out of memory (a critical threat in
+embedded and constrained environments), NextStd safely catches the failure and
+returns an `NS_ERROR_STRING_ALLOC` code without crashing your process.
+
+## 3. Buffer Overflow Prevention
+
+C strings are notoriously dangerous null-terminated (`\0`) arrays. If you forget
+the terminator, or use `strcat` into a buffer that is even one byte too small,
+you silently overwrite adjacent memory.
+
+NextStd uses a length-prefixed struct combined with Small String Optimization
+(SSO). The exact length of the string is always known. If a string needs to grow
+beyond its 24-byte inline capacity, NextStd automatically and safely requests
+exactly the right amount of heap memory. Buffer overflows are mathematically
+impossible by design.
+
+## 4. Format String Vulnerabilities
+
+Using `printf("%d", "text")` forces the C compiler to trust the developer
+blindly. If the format specifier doesn't match the variable type, the program
+reads garbage memory from the stack or crashes entirely.
+
+NextStd leverages C11 `_Generic` macros to completely eliminate this class of
+bugs by routing types at compile time:
+
+```c
+int age = 21;
+ns_string name; // Assume initialized
+
+ns_println(age);  // Automatically routes to ns_print_int
+ns_println(name); // Automatically routes to ns_print_string
+```
+
+Because there are no format strings, format string vulnerabilities simply cannot
+exist.

src/getting-started/getting-started.md

@@ -1 +1,66 @@
 # Why NextStd?
+
+C is the undisputed language of the physical and systems world.
+Whether you are building real-time camera processing pipelines,
+writing constrained firmware for microcontrollers like the ESP32
+and RP2040, or crafting lightning-fast terminal applications, C gives
+you the raw, uncompromised control you need.
+
+But that control comes with a massive, decades-old hidden cost:
+**The Standard Library.**
+
+## The Legacy C Trap
+
+Libraries like `<stdio.h>`, `<string.h>`, and `<stdlib.h>` were designed
+in an era before cybersecurity was a primary concern. Today, they are
+the root cause of the majority of software vulnerabilities.
+
+Consider a standard C input operation:
+
+```c
+int age;
+printf("Enter your age: ");
+scanf("%d", &age);
+```
+
+If a user types `"twenty"` instead of `20`, `scanf` silently fails,
+leaves the invalid text in the input buffer (corrupting future reads),
+and leaves `age` uninitialized. If you try to concatenate two strings using
+`strcat` and miscalculate the buffer size by a single byte, you trigger a
+buffer overflow. If you pass a `NULL` pointer into `strlen`, your entire
+system crashes with a Segmentation Fault.
+
+In mission-critical environments, a single uncaught `NULL` pointer can brick a
+device or crash a production system.
+
+### The Rewrite Dilemma
+
+The modern industry answer to C's unsafety is to rewrite everything in Rust.
+
+Rust is incredible. It mathematically proves memory safety at compile time.
+However, rewriting massive, established C codebases, or trying to interface
+Rust with highly specific hardware vendor SDKs, is often unrealistic, expensive,
+and time-consuming.
+
+Developers shouldn't have to abandon their C codebases just to get modern safety
+guarantees.
+
+## The NextStd Bridge
+
+**NextStd** was built to be the bridge. It is a drop-in systems library that
+brings the fearless safety of Rust directly into C, using standard Foreign
+Function Interface (FFI) boundaries.
+
+With NextStd, you don't rewrite your C code; you just upgrade your tools.
+
+* **You keep** your C compiler, your Makefiles, and your existing architecture.
+* **You replace** dangerous functions like `printf` and `scanf` with
+`ns_print` and `ns_read`.
+* **You gain** compile-time type routing, `NULL` pointer immunity,
+safe heap allocation, and Python-style `TRY/EXCEPT` error handling.
+
+By handling the most dangerous operations (I/O, string manipulation,
+and dynamic memory) in a memory-safe backend, NextStd allows you to write
+C code that is fundamentally immune to standard library footguns.
+
+You get the speed of C, with the peace of mind of Rust.