UPdate.

manual_src/pages/contributing/async-patterns.html

@@ -0,0 +1,420 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Async Patterns" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Async Patterns"}] %}
+{% set prev_page = {"url": "contributing/foreign-classes.html", "title": "Foreign Classes"} %}
+{% set next_page = {"url": "contributing/testing.html", "title": "Writing Tests"} %}
+
+{% block article %}
+                <h1>Async Patterns</h1>
+
+                <p>Wren-CLI uses libuv for non-blocking I/O. Wren fibers suspend during I/O operations and resume when complete. This section explains how to implement async operations in C-backed modules.</p>
+
+                <h2>The Scheduler/Fiber Pattern</h2>
+
+                <p>The standard pattern for async operations involves:</p>
+
+                <ol>
+                    <li>A public Wren method that users call</li>
+                    <li>An internal foreign method (ending with <code>_</code>) that takes a fiber handle</li>
+                    <li>C code that stores the fiber handle and schedules async work</li>
+                    <li>A libuv callback that resumes the fiber with the result</li>
+                </ol>
+
+                <h2>Basic Example</h2>
+
+                <h3>Wren Interface</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "scheduler" for Scheduler
+
+class AsyncFile {
+    foreign static read_(path, fiber)
+
+    static read(path) {
+        return Scheduler.await_ { read_(path, Fiber.current) }
+    }
+}</code></pre>
+
+                <p>The public <code>read</code> method wraps the internal <code>read_</code> method. <code>Scheduler.await_</code> suspends the current fiber until the async operation completes.</p>
+
+                <h3>Naming Convention</h3>
+
+                <ul>
+                    <li>Internal methods end with <code>_</code> (e.g., <code>read_</code>, <code>write_</code>)</li>
+                    <li>Public methods have clean names (e.g., <code>read</code>, <code>write</code>)</li>
+                    <li>Internal methods take a fiber as the last argument</li>
+                </ul>
+
+                <h2>C Implementation Structure</h2>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include &lt;uv.h&gt;
+#include "asyncfile.h"
+#include "wren.h"
+#include "vm.h"
+
+typedef struct {
+    WrenVM* vm;
+    WrenHandle* fiber;
+    uv_fs_t req;
+    char* path;
+    uv_buf_t buffer;
+} ReadRequest;
+
+void asyncFileRead(WrenVM* vm) {
+    const char* path = wrenGetSlotString(vm, 1);
+    WrenHandle* fiber = wrenGetSlotHandle(vm, 2);
+
+    ReadRequest* request = (ReadRequest*)malloc(sizeof(ReadRequest));
+    request->vm = vm;
+    request->fiber = fiber;
+    request->path = strdup(path);
+    request->req.data = request;
+
+    uv_loop_t* loop = getLoop();
+    uv_fs_open(loop, &request->req, path, UV_FS_O_RDONLY, 0, onFileOpened);
+}
+
+void onFileOpened(uv_fs_t* req) {
+    ReadRequest* request = (ReadRequest*)req->data;
+    uv_fs_req_cleanup(req);
+
+    if (req->result < 0) {
+        resumeWithError(request, "Failed to open file.");
+        return;
+    }
+
+    int fd = (int)req->result;
+    uv_fs_fstat(getLoop(), &request->req, fd, onFileStat);
+}
+
+// ... additional callbacks for fstat, read, close ...</code></pre>
+
+                <h2>Fiber Handle Management</h2>
+
+                <h3>Capturing the Fiber</h3>
+
+                <pre><code>WrenHandle* fiber = wrenGetSlotHandle(vm, 2);</code></pre>
+
+                <p>The fiber handle is obtained from the slot where it was passed. This handle must be stored for later use.</p>
+
+                <h3>Resuming the Fiber</h3>
+
+                <p>Use the scheduler's resume mechanism:</p>
+
+                <pre><code>void resumeWithResult(ReadRequest* request, const char* result) {
+    WrenVM* vm = request->vm;
+
+    schedulerResume(request->fiber, true);
+    wrenReleaseHandle(vm, request->fiber);
+
+    wrenEnsureSlots(vm, 1);
+    wrenSetSlotString(vm, 0, result);
+
+    free(request->path);
+    free(request);
+}
+
+void resumeWithError(ReadRequest* request, const char* error) {
+    WrenVM* vm = request->vm;
+
+    schedulerResume(request->fiber, false);
+    wrenReleaseHandle(vm, request->fiber);
+
+    wrenEnsureSlots(vm, 1);
+    wrenSetSlotString(vm, 0, error);
+
+    free(request->path);
+    free(request);
+}</code></pre>
+
+                <h3>schedulerResume</h3>
+
+                <pre><code>void schedulerResume(WrenHandle* fiber, bool success);</code></pre>
+
+                <ul>
+                    <li><code>fiber</code>: The fiber handle to resume</li>
+                    <li><code>success</code>: true if the operation succeeded, false for error</li>
+                </ul>
+
+                <p>After calling <code>schedulerResume</code>, the value in slot 0 becomes the return value (for success) or error message (for failure).</p>
+
+                <h2>libuv Integration</h2>
+
+                <h3>Getting the Event Loop</h3>
+
+                <pre><code>uv_loop_t* loop = getLoop();</code></pre>
+
+                <p>The <code>getLoop()</code> function returns the global libuv event loop used by Wren-CLI.</p>
+
+                <h3>Common libuv Operations</h3>
+
+                <table>
+                    <tr>
+                        <th>Operation</th>
+                        <th>libuv Function</th>
+                    </tr>
+                    <tr>
+                        <td>File read</td>
+                        <td><code>uv_fs_read</code></td>
+                    </tr>
+                    <tr>
+                        <td>File write</td>
+                        <td><code>uv_fs_write</code></td>
+                    </tr>
+                    <tr>
+                        <td>TCP connect</td>
+                        <td><code>uv_tcp_connect</code></td>
+                    </tr>
+                    <tr>
+                        <td>DNS lookup</td>
+                        <td><code>uv_getaddrinfo</code></td>
+                    </tr>
+                    <tr>
+                        <td>Timer</td>
+                        <td><code>uv_timer_start</code></td>
+                    </tr>
+                    <tr>
+                        <td>Process spawn</td>
+                        <td><code>uv_spawn</code></td>
+                    </tr>
+                </table>
+
+                <h3>Request Data Pattern</h3>
+
+                <p>Store context in the <code>data</code> field of libuv requests:</p>
+
+                <pre><code>typedef struct {
+    WrenVM* vm;
+    WrenHandle* fiber;
+    // ... operation-specific data ...
+} MyRequest;
+
+MyRequest* req = malloc(sizeof(MyRequest));
+req->vm = vm;
+req->fiber = fiber;
+uvReq.data = req;</code></pre>
+
+                <p>In callbacks, retrieve the context:</p>
+
+                <pre><code>void onComplete(uv_xxx_t* uvReq) {
+    MyRequest* req = (MyRequest*)uvReq->data;
+    // ...
+}</code></pre>
+
+                <h2>Complete Async File Read Example</h2>
+
+                <h3>asyncfile.wren</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "scheduler" for Scheduler
+
+class AsyncFile {
+    foreign static read_(path, fiber)
+    foreign static write_(path, content, fiber)
+
+    static read(path) {
+        return Scheduler.await_ { read_(path, Fiber.current) }
+    }
+
+    static write(path, content) {
+        return Scheduler.await_ { write_(path, content, Fiber.current) }
+    }
+}</code></pre>
+
+                <h3>asyncfile.c (simplified)</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include &lt;uv.h&gt;
+#include "asyncfile.h"
+#include "wren.h"
+#include "vm.h"
+#include "scheduler.h"
+
+typedef struct {
+    WrenVM* vm;
+    WrenHandle* fiber;
+    uv_fs_t req;
+    uv_file fd;
+    char* buffer;
+    size_t size;
+} FileRequest;
+
+static void cleanupRequest(FileRequest* request) {
+    if (request->buffer) free(request->buffer);
+    wrenReleaseHandle(request->vm, request->fiber);
+    free(request);
+}
+
+static void onReadComplete(uv_fs_t* req) {
+    FileRequest* request = (FileRequest*)req->data;
+    uv_fs_req_cleanup(req);
+
+    if (req->result < 0) {
+        schedulerResume(request->fiber, false);
+        wrenEnsureSlots(request->vm, 1);
+        wrenSetSlotString(request->vm, 0, "Read failed.");
+    } else {
+        request->buffer[req->result] = '\0';
+        schedulerResume(request->fiber, true);
+        wrenEnsureSlots(request->vm, 1);
+        wrenSetSlotString(request->vm, 0, request->buffer);
+    }
+
+    uv_fs_close(getLoop(), req, request->fd, NULL);
+    cleanupRequest(request);
+}
+
+static void onFileStatComplete(uv_fs_t* req) {
+    FileRequest* request = (FileRequest*)req->data;
+    uv_fs_req_cleanup(req);
+
+    if (req->result < 0) {
+        schedulerResume(request->fiber, false);
+        wrenEnsureSlots(request->vm, 1);
+        wrenSetSlotString(request->vm, 0, "Stat failed.");
+        uv_fs_close(getLoop(), req, request->fd, NULL);
+        cleanupRequest(request);
+        return;
+    }
+
+    request->size = req->statbuf.st_size;
+    request->buffer = (char*)malloc(request->size + 1);
+
+    uv_buf_t buf = uv_buf_init(request->buffer, request->size);
+    uv_fs_read(getLoop(), &request->req, request->fd, &buf, 1, 0, onReadComplete);
+}
+
+static void onFileOpenComplete(uv_fs_t* req) {
+    FileRequest* request = (FileRequest*)req->data;
+    uv_fs_req_cleanup(req);
+
+    if (req->result < 0) {
+        schedulerResume(request->fiber, false);
+        wrenEnsureSlots(request->vm, 1);
+        wrenSetSlotString(request->vm, 0, "Open failed.");
+        cleanupRequest(request);
+        return;
+    }
+
+    request->fd = (uv_file)req->result;
+    uv_fs_fstat(getLoop(), &request->req, request->fd, onFileStatComplete);
+}
+
+void asyncFileRead(WrenVM* vm) {
+    const char* path = wrenGetSlotString(vm, 1);
+    WrenHandle* fiber = wrenGetSlotHandle(vm, 2);
+
+    FileRequest* request = (FileRequest*)malloc(sizeof(FileRequest));
+    request->vm = vm;
+    request->fiber = fiber;
+    request->buffer = NULL;
+    request->req.data = request;
+
+    uv_fs_open(getLoop(), &request->req, path, UV_FS_O_RDONLY, 0, onFileOpenComplete);
+}</code></pre>
+
+                <h2>Error Handling in Async Operations</h2>
+
+                <h3>libuv Errors</h3>
+
+                <p>Check <code>req->result</code> for negative values:</p>
+
+                <pre><code>if (req->result < 0) {
+    const char* msg = uv_strerror((int)req->result);
+    schedulerResume(request->fiber, false);
+    wrenSetSlotString(request->vm, 0, msg);
+    return;
+}</code></pre>
+
+                <h3>Propagating to Wren</h3>
+
+                <p>Use <code>schedulerResume(fiber, false)</code> for errors. The value in slot 0 becomes the error that <code>Scheduler.await_</code> throws as a runtime error.</p>
+
+                <h2>Timer Example</h2>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+typedef struct {
+    WrenVM* vm;
+    WrenHandle* fiber;
+    uv_timer_t timer;
+} TimerRequest;
+
+static void onTimerComplete(uv_timer_t* timer) {
+    TimerRequest* request = (TimerRequest*)timer->data;
+
+    schedulerResume(request->fiber, true);
+    wrenReleaseHandle(request->vm, request->fiber);
+    wrenEnsureSlots(request->vm, 1);
+    wrenSetSlotNull(request->vm, 0);
+
+    uv_close((uv_handle_t*)timer, NULL);
+    free(request);
+}
+
+void timerSleep(WrenVM* vm) {
+    double ms = wrenGetSlotDouble(vm, 1);
+    WrenHandle* fiber = wrenGetSlotHandle(vm, 2);
+
+    TimerRequest* request = (TimerRequest*)malloc(sizeof(TimerRequest));
+    request->vm = vm;
+    request->fiber = fiber;
+    request->timer.data = request;
+
+    uv_timer_init(getLoop(), &request->timer);
+    uv_timer_start(&request->timer, onTimerComplete, (uint64_t)ms, 0);
+}</code></pre>
+
+                <h2>Multiple Concurrent Operations</h2>
+
+                <p>Each async operation gets its own request structure and fiber. Multiple operations can run concurrently:</p>
+
+                <pre><code>import "asyncfile" for AsyncFile
+
+var fiber1 = Fiber.new {
+    var a = AsyncFile.read("a.txt")
+    System.print("A: %(a.count) bytes")
+}
+
+var fiber2 = Fiber.new {
+    var b = AsyncFile.read("b.txt")
+    System.print("B: %(b.count) bytes")
+}
+
+fiber1.call()
+fiber2.call()</code></pre>
+
+                <h2>Best Practices</h2>
+
+                <ul>
+                    <li><strong>Always release fiber handles</strong>: Call <code>wrenReleaseHandle</code> after resuming</li>
+                    <li><strong>Cleanup on all paths</strong>: Free resources in both success and error cases</li>
+                    <li><strong>Use uv_fs_req_cleanup</strong>: Required after filesystem operations</li>
+                    <li><strong>Close handles properly</strong>: Use <code>uv_close</code> for handles like timers and sockets</li>
+                    <li><strong>Check for VM validity</strong>: The VM pointer should remain valid during callbacks</li>
+                </ul>
+
+                <h2>Debugging Tips</h2>
+
+                <ul>
+                    <li>Add logging in callbacks to trace execution flow</li>
+                    <li>Verify libuv error codes with <code>uv_strerror</code></li>
+                    <li>Use <code>make debug</code> build for symbols</li>
+                    <li>Check for memory leaks with valgrind</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <p>See <a href="testing.html">Writing Tests</a> for testing async operations, including the <code>// skip:</code> annotation for tests that require network access.</p>
+{% endblock %}

manual_src/pages/contributing/c-backed-module.html

@@ -0,0 +1,412 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "C-Backed Modules" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "C-Backed Modules"}] %}
+{% set prev_page = {"url": "contributing/pure-wren-module.html", "title": "Pure-Wren Modules"} %}
+{% set next_page = {"url": "contributing/foreign-classes.html", "title": "Foreign Classes"} %}
+
+{% block article %}
+                <h1>C-Backed Modules</h1>
+
+                <p>C-backed modules implement foreign methods in C, providing access to system libraries, native performance, or functionality not available in pure Wren. Examples: json, io, net, crypto, tls, sqlite, base64.</p>
+
+                <h2>Step 1: Create the Wren Interface</h2>
+
+                <p>Create <code>src/module/&lt;name&gt;.wren</code> with foreign method declarations:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+class Counter {
+    foreign static create()
+    foreign static increment(handle)
+    foreign static getValue(handle)
+    foreign static destroy(handle)
+
+    static use(fn) {
+        var handle = Counter.create()
+        var result = fn.call(handle)
+        Counter.destroy(handle)
+        return result
+    }
+}</code></pre>
+
+                <p>The <code>foreign</code> keyword indicates the method is implemented in C. Non-foreign methods can provide higher-level Wren wrappers around the foreign primitives.</p>
+
+                <h2>Step 2: Generate the .wren.inc</h2>
+
+                <pre><code>python3 util/wren_to_c_string.py src/module/counter.wren.inc src/module/counter.wren</code></pre>
+
+                <h2>Step 3: Create the C Implementation</h2>
+
+                <p>Create <code>src/module/counter.c</code>:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#include &lt;stdlib.h&gt;
+#include "counter.h"
+#include "wren.h"
+
+typedef struct {
+    int value;
+} Counter;
+
+void counterCreate(WrenVM* vm) {
+    Counter* counter = (Counter*)malloc(sizeof(Counter));
+    if (!counter) {
+        wrenSetSlotNull(vm, 0);
+        return;
+    }
+    counter->value = 0;
+    wrenSetSlotDouble(vm, 0, (double)(uintptr_t)counter);
+}
+
+void counterIncrement(WrenVM* vm) {
+    double handle = wrenGetSlotDouble(vm, 1);
+    Counter* counter = (Counter*)(uintptr_t)handle;
+    counter->value++;
+}
+
+void counterGetValue(WrenVM* vm) {
+    double handle = wrenGetSlotDouble(vm, 1);
+    Counter* counter = (Counter*)(uintptr_t)handle;
+    wrenSetSlotDouble(vm, 0, counter->value);
+}
+
+void counterDestroy(WrenVM* vm) {
+    double handle = wrenGetSlotDouble(vm, 1);
+    Counter* counter = (Counter*)(uintptr_t)handle;
+    free(counter);
+}</code></pre>
+
+                <h2>Step 4: Create the C Header</h2>
+
+                <p>Create <code>src/module/counter.h</code>:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#ifndef counter_h
+#define counter_h
+
+#include "wren.h"
+
+void counterCreate(WrenVM* vm);
+void counterIncrement(WrenVM* vm);
+void counterGetValue(WrenVM* vm);
+void counterDestroy(WrenVM* vm);
+
+#endif</code></pre>
+
+                <h2>Step 5: Register in modules.c</h2>
+
+                <p>Edit <code>src/cli/modules.c</code>:</p>
+
+                <h3>Add the Include</h3>
+                <pre><code>#include "counter.wren.inc"</code></pre>
+
+                <h3>Add Extern Declarations</h3>
+                <pre><code>extern void counterCreate(WrenVM* vm);
+extern void counterIncrement(WrenVM* vm);
+extern void counterGetValue(WrenVM* vm);
+extern void counterDestroy(WrenVM* vm);</code></pre>
+
+                <h3>Add the Module Entry</h3>
+                <pre><code>MODULE(counter)
+  CLASS(Counter)
+    STATIC_METHOD("create()", counterCreate)
+    STATIC_METHOD("increment(_)", counterIncrement)
+    STATIC_METHOD("getValue(_)", counterGetValue)
+    STATIC_METHOD("destroy(_)", counterDestroy)
+  END_CLASS
+END_MODULE</code></pre>
+
+                <h2>Step 6: Update the Makefile</h2>
+
+                <p>Edit <code>projects/make/wren_cli.make</code>:</p>
+
+                <h3>Add to OBJECTS</h3>
+                <pre><code>OBJECTS += $(OBJDIR)/counter.o</code></pre>
+
+                <h3>Add Compilation Rule</h3>
+                <pre><code>$(OBJDIR)/counter.o: ../../src/module/counter.c
+	@echo $(notdir $&lt;)
+	$(SILENT) $(CC) $(ALL_CFLAGS) $(FORCE_INCLUDE) -o "$@" -MF "$(@:%.o=%.d)" -c "$&lt;"</code></pre>
+
+                <h2>Step 7: Build and Test</h2>
+
+                <pre><code>make clean && make build
+python3 util/test.py counter</code></pre>
+
+                <h2>Wren/C Data Exchange</h2>
+
+                <h3>Getting Values from Wren</h3>
+
+                <pre><code>const char* str = wrenGetSlotString(vm, 1);
+double num = wrenGetSlotDouble(vm, 1);
+bool b = wrenGetSlotBool(vm, 1);
+void* foreign = wrenGetSlotForeign(vm, 0);
+WrenHandle* handle = wrenGetSlotHandle(vm, 1);
+int count = wrenGetSlotCount(vm);
+WrenType type = wrenGetSlotType(vm, 1);</code></pre>
+
+                <h3>Setting Return Values</h3>
+
+                <pre><code>wrenSetSlotString(vm, 0, "result");
+wrenSetSlotDouble(vm, 0, 42.0);
+wrenSetSlotBool(vm, 0, true);
+wrenSetSlotNull(vm, 0);
+wrenSetSlotNewList(vm, 0);</code></pre>
+
+                <h3>Working with Lists</h3>
+
+                <pre><code>wrenSetSlotNewList(vm, 0);
+wrenSetSlotString(vm, 1, "item");
+wrenInsertInList(vm, 0, -1, 1);
+
+int count = wrenGetListCount(vm, 0);
+wrenGetListElement(vm, 0, index, 1);</code></pre>
+
+                <h3>Working with Maps</h3>
+
+                <pre><code>wrenSetSlotNewMap(vm, 0);
+wrenSetSlotString(vm, 1, "key");
+wrenSetSlotDouble(vm, 2, 123);
+wrenSetMapValue(vm, 0, 1, 2);</code></pre>
+
+                <h3>Ensuring Slots</h3>
+
+                <pre><code>wrenEnsureSlots(vm, 5);</code></pre>
+
+                <div class="admonition note">
+                    <div class="admonition-title">Note</div>
+                    <p>Slot 0 is used for the return value and (for instance methods) the receiver. Arguments start at slot 1.</p>
+                </div>
+
+                <h2>Error Handling</h2>
+
+                <p>Use <code>wrenAbortFiber</code> to report errors:</p>
+
+                <pre><code>void myMethod(WrenVM* vm) {
+    const char* path = wrenGetSlotString(vm, 1);
+
+    FILE* file = fopen(path, "r");
+    if (!file) {
+        wrenSetSlotString(vm, 0, "Failed to open file.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    // ... process file ...
+}</code></pre>
+
+                <p>The error message is set in slot 0, then <code>wrenAbortFiber</code> is called with the slot containing the message.</p>
+
+                <h2>Type Checking</h2>
+
+                <p>Verify argument types before using them:</p>
+
+                <pre><code>void myMethod(WrenVM* vm) {
+    if (wrenGetSlotType(vm, 1) != WREN_TYPE_STRING) {
+        wrenSetSlotString(vm, 0, "Argument must be a string.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    const char* str = wrenGetSlotString(vm, 1);
+    // ...
+}</code></pre>
+
+                <p>WrenType values: <code>WREN_TYPE_BOOL</code>, <code>WREN_TYPE_NUM</code>, <code>WREN_TYPE_FOREIGN</code>, <code>WREN_TYPE_LIST</code>, <code>WREN_TYPE_MAP</code>, <code>WREN_TYPE_NULL</code>, <code>WREN_TYPE_STRING</code>, <code>WREN_TYPE_UNKNOWN</code>.</p>
+
+                <h2>Method Signature Rules</h2>
+
+                <table>
+                    <tr>
+                        <th>Wren Declaration</th>
+                        <th>Signature String</th>
+                    </tr>
+                    <tr>
+                        <td><code>foreign static foo()</code></td>
+                        <td><code>"foo()"</code></td>
+                    </tr>
+                    <tr>
+                        <td><code>foreign static foo(a)</code></td>
+                        <td><code>"foo(_)"</code></td>
+                    </tr>
+                    <tr>
+                        <td><code>foreign static foo(a, b)</code></td>
+                        <td><code>"foo(_,_)"</code></td>
+                    </tr>
+                    <tr>
+                        <td><code>foreign foo()</code></td>
+                        <td><code>"foo()"</code> with <code>METHOD</code></td>
+                    </tr>
+                    <tr>
+                        <td><code>foreign name</code> (getter)</td>
+                        <td><code>"name"</code></td>
+                    </tr>
+                    <tr>
+                        <td><code>foreign name=(v)</code> (setter)</td>
+                        <td><code>"name=(_)"</code></td>
+                    </tr>
+                </table>
+
+                <h2>Complete Example</h2>
+
+                <p>A more realistic example parsing hexadecimal strings:</p>
+
+                <h3>hex.wren</h3>
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+class Hex {
+    foreign static encode(bytes)
+    foreign static decode(str)
+
+    static isValid(str) {
+        for (c in str) {
+            var code = c.bytes[0]
+            var valid = (code >= 48 && code <= 57) ||
+                       (code >= 65 && code <= 70) ||
+                       (code >= 97 && code <= 102)
+            if (!valid) return false
+        }
+        return str.count \% 2 == 0
+    }
+}</code></pre>
+
+                <h3>hex.c</h3>
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include "hex.h"
+#include "wren.h"
+
+static const char HEX_CHARS[] = "0123456789abcdef";
+
+void hexEncode(WrenVM* vm) {
+    const char* input = wrenGetSlotString(vm, 1);
+    size_t len = strlen(input);
+
+    char* output = (char*)malloc(len * 2 + 1);
+    if (!output) {
+        wrenSetSlotString(vm, 0, "Memory allocation failed.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    for (size_t i = 0; i < len; i++) {
+        unsigned char c = (unsigned char)input[i];
+        output[i * 2] = HEX_CHARS[(c >> 4) & 0xF];
+        output[i * 2 + 1] = HEX_CHARS[c & 0xF];
+    }
+    output[len * 2] = '\0';
+
+    wrenSetSlotString(vm, 0, output);
+    free(output);
+}
+
+static int hexCharToInt(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    return -1;
+}
+
+void hexDecode(WrenVM* vm) {
+    const char* input = wrenGetSlotString(vm, 1);
+    size_t len = strlen(input);
+
+    if (len \% 2 != 0) {
+        wrenSetSlotString(vm, 0, "Hex string must have even length.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    char* output = (char*)malloc(len / 2 + 1);
+    if (!output) {
+        wrenSetSlotString(vm, 0, "Memory allocation failed.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    for (size_t i = 0; i < len; i += 2) {
+        int high = hexCharToInt(input[i]);
+        int low = hexCharToInt(input[i + 1]);
+
+        if (high < 0 || low < 0) {
+            free(output);
+            wrenSetSlotString(vm, 0, "Invalid hex character.");
+            wrenAbortFiber(vm, 0);
+            return;
+        }
+
+        output[i / 2] = (char)((high << 4) | low);
+    }
+    output[len / 2] = '\0';
+
+    wrenSetSlotString(vm, 0, output);
+    free(output);
+}</code></pre>
+
+                <h3>hex.h</h3>
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#ifndef hex_h
+#define hex_h
+
+#include "wren.h"
+
+void hexEncode(WrenVM* vm);
+void hexDecode(WrenVM* vm);
+
+#endif</code></pre>
+
+                <h3>modules.c entries</h3>
+                <pre><code>#include "hex.wren.inc"
+
+extern void hexEncode(WrenVM* vm);
+extern void hexDecode(WrenVM* vm);
+
+MODULE(hex)
+  CLASS(Hex)
+    STATIC_METHOD("encode(_)", hexEncode)
+    STATIC_METHOD("decode(_)", hexDecode)
+  END_CLASS
+END_MODULE</code></pre>
+
+                <h2>Common Pitfalls</h2>
+
+                <ul>
+                    <li><strong>Stale .wren.inc</strong>: Always regenerate after editing the <code>.wren</code> file</li>
+                    <li><strong>Signature mismatch</strong>: The string in <code>STATIC_METHOD("name(_)", fn)</code> must exactly match the Wren declaration's arity</li>
+                    <li><strong>Slot management</strong>: Always call <code>wrenEnsureSlots(vm, n)</code> before using high-numbered slots</li>
+                    <li><strong>Memory leaks</strong>: Free allocated memory before returning</li>
+                    <li><strong>String lifetime</strong>: Strings from <code>wrenGetSlotString</code> are valid only until the next Wren API call</li>
+                    <li><strong>make clean</strong>: Required after adding new object files</li>
+                </ul>
+
+                <h2>Checklist</h2>
+
+                <ul>
+                    <li>Created <code>src/module/&lt;name&gt;.wren</code> with foreign declarations</li>
+                    <li>Generated <code>.wren.inc</code></li>
+                    <li>Created <code>src/module/&lt;name&gt;.c</code></li>
+                    <li>Created <code>src/module/&lt;name&gt;.h</code></li>
+                    <li>Added <code>#include</code> for <code>.wren.inc</code> in modules.c</li>
+                    <li>Added extern declarations in modules.c</li>
+                    <li>Added <code>MODULE</code>/<code>CLASS</code>/<code>METHOD</code> block in modules.c</li>
+                    <li>Added <code>OBJECTS</code> entry in Makefile</li>
+                    <li>Added compilation rule in Makefile</li>
+                    <li>Built with <code>make clean && make build</code></li>
+                    <li>Created tests and example</li>
+                    <li>Created documentation page</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <ul>
+                    <li><a href="foreign-classes.html">Foreign Classes</a> - for native resource management</li>
+                    <li><a href="async-patterns.html">Async Patterns</a> - for non-blocking I/O operations</li>
+                </ul>
+{% endblock %}

manual_src/pages/contributing/documentation.html

@@ -0,0 +1,370 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Documentation" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Documentation"}] %}
+{% set prev_page = {"url": "contributing/testing.html", "title": "Writing Tests"} %}
+{% set next_page = {"url": "api/index.html", "title": "API Reference"} %}
+
+{% block article %}
+                <h1>Documentation</h1>
+
+                <p>The Wren-CLI manual is hand-written HTML in <code>manual/</code>. There is no generation step. Every page is a standalone HTML file sharing common CSS and JavaScript.</p>
+
+                <h2>HTML Template</h2>
+
+                <p>Every page follows this structure:</p>
+
+                <pre><code>&lt;!DOCTYPE html&gt;
+&lt;!-- retoor &lt;retoor@molodetz.nl&gt; --&gt;
+&lt;html lang="en"&gt;
+&lt;head&gt;
+    &lt;meta charset="UTF-8"&gt;
+    &lt;meta name="viewport" content="width=device-width, initial-scale=1.0"&gt;
+    &lt;title&gt;[Page Title] - Wren-CLI Manual&lt;/title&gt;
+    &lt;link rel="stylesheet" href="../css/style.css"&gt;
+&lt;/head&gt;
+&lt;body&gt;
+    &lt;button class="mobile-menu-toggle"&gt;Menu&lt;/button&gt;
+    &lt;div class="container"&gt;
+        &lt;aside class="sidebar"&gt;
+            &lt;div class="sidebar-header"&gt;
+                &lt;h1&gt;&lt;a href="../index.html"&gt;Wren-CLI&lt;/a&gt;&lt;/h1&gt;
+                &lt;div class="version"&gt;v0.4.0&lt;/div&gt;
+            &lt;/div&gt;
+            &lt;nav class="sidebar-nav"&gt;
+                &lt;!-- Auto-generated by sync_sidebar.py --&gt;
+            &lt;/nav&gt;
+        &lt;/aside&gt;
+        &lt;main class="content"&gt;
+            &lt;nav class="breadcrumb"&gt;
+                &lt;a href="../index.html"&gt;Home&lt;/a&gt;
+                &lt;span class="separator"&gt;/&lt;/span&gt;
+                &lt;a href="index.html"&gt;API Reference&lt;/a&gt;
+                &lt;span class="separator"&gt;/&lt;/span&gt;
+                &lt;span&gt;[Current Page]&lt;/span&gt;
+            &lt;/nav&gt;
+            &lt;article&gt;
+                &lt;h1&gt;[Page Title]&lt;/h1&gt;
+                &lt;!-- Content --&gt;
+            &lt;/article&gt;
+            &lt;footer class="page-footer"&gt;
+                &lt;a href="[prev].html" class="prev"&gt;[Previous]&lt;/a&gt;
+                &lt;a href="[next].html" class="next"&gt;[Next]&lt;/a&gt;
+            &lt;/footer&gt;
+        &lt;/main&gt;
+    &lt;/div&gt;
+    &lt;script src="../js/main.js"&gt;&lt;/script&gt;
+&lt;/body&gt;
+&lt;/html&gt;</code></pre>
+
+                <h2>Sidebar Navigation</h2>
+
+                <p>The sidebar is automatically synchronized across all pages by <code>util/sync_sidebar.py</code>. Never edit the sidebar manually.</p>
+
+                <h3>Adding a New Module to the Sidebar</h3>
+
+                <ol>
+                    <li>Create the module's HTML page in <code>manual/api/</code></li>
+                    <li>Run <code>make sync-manual</code></li>
+                </ol>
+
+                <p>The sync script automatically discovers new API pages and adds them to the sidebar in alphabetical order.</p>
+
+                <h3>Adding a New Section</h3>
+
+                <p>To add a new top-level section (like "Contributing"), edit <code>util/sync_sidebar.py</code> and add an entry to the <code>SECTIONS</code> list:</p>
+
+                <pre><code>{
+    "title": "New Section",
+    "directory": "new-section",
+    "pages": [
+        ("index.html", "Overview"),
+        ("page1.html", "Page One"),
+        ("page2.html", "Page Two"),
+    ]
+},</code></pre>
+
+                <h2>API Page Structure</h2>
+
+                <p>API documentation pages follow a consistent structure:</p>
+
+                <pre><code>&lt;h1&gt;modulename&lt;/h1&gt;
+&lt;p&gt;Description paragraph.&lt;/p&gt;
+&lt;pre&gt;&lt;code&gt;import "modulename" for ClassName&lt;/code&gt;&lt;/pre&gt;
+
+&lt;div class="class-header"&gt;&lt;h2&gt;Class: ClassName&lt;/h2&gt;&lt;/div&gt;
+
+&lt;h3&gt;Static Methods&lt;/h3&gt;
+&lt;div class="method-signature"&gt;
+  &lt;span class="method-name"&gt;ClassName.methodName&lt;/span&gt;(&lt;span class="param"&gt;arg&lt;/span&gt;)
+  &amp;rarr; &lt;span class="type"&gt;ReturnType&lt;/span&gt;
+&lt;/div&gt;
+&lt;p&gt;Method description.&lt;/p&gt;
+
+&lt;h3&gt;Examples&lt;/h3&gt;
+&lt;pre&gt;&lt;code&gt;import "modulename" for ClassName
+var result = ClassName.methodName("hello")
+System.print(result)&lt;/code&gt;&lt;/pre&gt;</code></pre>
+
+                <h2>CSS Classes</h2>
+
+                <table>
+                    <tr>
+                        <th>Class</th>
+                        <th>Usage</th>
+                    </tr>
+                    <tr>
+                        <td><code>.method-signature</code></td>
+                        <td>Method signature box</td>
+                    </tr>
+                    <tr>
+                        <td><code>.method-name</code></td>
+                        <td>Method name within signature</td>
+                    </tr>
+                    <tr>
+                        <td><code>.param</code></td>
+                        <td>Parameter name</td>
+                    </tr>
+                    <tr>
+                        <td><code>.type</code></td>
+                        <td>Return type</td>
+                    </tr>
+                    <tr>
+                        <td><code>.class-header</code></td>
+                        <td>Class section header</td>
+                    </tr>
+                    <tr>
+                        <td><code>.param-list</code></td>
+                        <td>Parameter description list</td>
+                    </tr>
+                    <tr>
+                        <td><code>.toc</code></td>
+                        <td>Table of contents box</td>
+                    </tr>
+                    <tr>
+                        <td><code>.admonition</code></td>
+                        <td>Note/warning/tip box</td>
+                    </tr>
+                    <tr>
+                        <td><code>.example-output</code></td>
+                        <td>Expected output display</td>
+                    </tr>
+                </table>
+
+                <h2>Method Signature Format</h2>
+
+                <p>Static method:</p>
+                <pre><code>&lt;div class="method-signature"&gt;
+  &lt;span class="method-name"&gt;ClassName.methodName&lt;/span&gt;(&lt;span class="param"&gt;arg1&lt;/span&gt;, &lt;span class="param"&gt;arg2&lt;/span&gt;)
+  &amp;rarr; &lt;span class="type"&gt;String&lt;/span&gt;
+&lt;/div&gt;</code></pre>
+
+                <p>Instance method:</p>
+                <pre><code>&lt;div class="method-signature"&gt;
+  &lt;span class="method-name"&gt;instance.methodName&lt;/span&gt;(&lt;span class="param"&gt;arg&lt;/span&gt;)
+  &amp;rarr; &lt;span class="type"&gt;Bool&lt;/span&gt;
+&lt;/div&gt;</code></pre>
+
+                <p>Property (getter):</p>
+                <pre><code>&lt;div class="method-signature"&gt;
+  &lt;span class="method-name"&gt;instance.propertyName&lt;/span&gt;
+  &amp;rarr; &lt;span class="type"&gt;Num&lt;/span&gt;
+&lt;/div&gt;</code></pre>
+
+                <h2>Admonition Blocks</h2>
+
+                <p>Use admonitions for notes, warnings, and tips:</p>
+
+                <h3>Note</h3>
+                <pre><code>&lt;div class="admonition note"&gt;
+    &lt;div class="admonition-title"&gt;Note&lt;/div&gt;
+    &lt;p&gt;Additional information.&lt;/p&gt;
+&lt;/div&gt;</code></pre>
+
+                <div class="admonition note">
+                    <div class="admonition-title">Note</div>
+                    <p>Additional information.</p>
+                </div>
+
+                <h3>Warning</h3>
+                <pre><code>&lt;div class="admonition warning"&gt;
+    &lt;div class="admonition-title"&gt;Warning&lt;/div&gt;
+    &lt;p&gt;Important caution.&lt;/p&gt;
+&lt;/div&gt;</code></pre>
+
+                <div class="admonition warning">
+                    <div class="admonition-title">Warning</div>
+                    <p>Important caution.</p>
+                </div>
+
+                <h3>Tip</h3>
+                <pre><code>&lt;div class="admonition tip"&gt;
+    &lt;div class="admonition-title"&gt;Tip&lt;/div&gt;
+    &lt;p&gt;Helpful suggestion.&lt;/p&gt;
+&lt;/div&gt;</code></pre>
+
+                <h2>Parameter Lists</h2>
+
+                <p>For methods with complex parameters:</p>
+
+                <pre><code>&lt;div class="param-list"&gt;
+    &lt;div class="param-item"&gt;
+        &lt;span class="param-name"&gt;path&lt;/span&gt;
+        &lt;span class="param-type"&gt;String&lt;/span&gt;
+        &lt;p&gt;The file path to read.&lt;/p&gt;
+    &lt;/div&gt;
+    &lt;div class="param-item"&gt;
+        &lt;span class="param-name"&gt;encoding&lt;/span&gt;
+        &lt;span class="param-type"&gt;String&lt;/span&gt;
+        &lt;p&gt;The character encoding (default: "utf-8").&lt;/p&gt;
+    &lt;/div&gt;
+&lt;/div&gt;</code></pre>
+
+                <h2>Tables</h2>
+
+                <p>Use tables for options, type mappings, or comparisons:</p>
+
+                <pre><code>&lt;table&gt;
+    &lt;tr&gt;
+        &lt;th&gt;Option&lt;/th&gt;
+        &lt;th&gt;Description&lt;/th&gt;
+    &lt;/tr&gt;
+    &lt;tr&gt;
+        &lt;td&gt;&lt;code&gt;"r"&lt;/code&gt;&lt;/td&gt;
+        &lt;td&gt;Read mode&lt;/td&gt;
+    &lt;/tr&gt;
+    &lt;tr&gt;
+        &lt;td&gt;&lt;code&gt;"w"&lt;/code&gt;&lt;/td&gt;
+        &lt;td&gt;Write mode&lt;/td&gt;
+    &lt;/tr&gt;
+&lt;/table&gt;</code></pre>
+
+                <h2>Footer Navigation</h2>
+
+                <p>Every page has previous/next navigation:</p>
+
+                <pre><code>&lt;footer class="page-footer"&gt;
+    &lt;a href="previous.html" class="prev"&gt;Previous Page&lt;/a&gt;
+    &lt;a href="next.html" class="next"&gt;Next Page&lt;/a&gt;
+&lt;/footer&gt;</code></pre>
+
+                <p>Update the footer on adjacent pages when adding new pages.</p>
+
+                <h2>Breadcrumb Navigation</h2>
+
+                <p>Shows the page hierarchy:</p>
+
+                <pre><code>&lt;nav class="breadcrumb"&gt;
+    &lt;a href="../index.html"&gt;Home&lt;/a&gt;
+    &lt;span class="separator"&gt;/&lt;/span&gt;
+    &lt;a href="index.html"&gt;API Reference&lt;/a&gt;
+    &lt;span class="separator"&gt;/&lt;/span&gt;
+    &lt;span&gt;io&lt;/span&gt;
+&lt;/nav&gt;</code></pre>
+
+                <h2>Syncing the Sidebar</h2>
+
+                <pre><code>make sync-manual</code></pre>
+
+                <p>This runs <code>util/sync_sidebar.py</code> which:</p>
+
+                <ol>
+                    <li>Discovers all API module pages</li>
+                    <li>Builds the complete sidebar HTML</li>
+                    <li>Updates the <code>&lt;nav class="sidebar-nav"&gt;</code> in every HTML file</li>
+                    <li>Sets the <code>active</code> class on the current page's link</li>
+                </ol>
+
+                <p>The script is idempotent - running it twice produces the same result.</p>
+
+                <h2>Adding a New API Page</h2>
+
+                <ol>
+                    <li>Create <code>manual/api/&lt;name&gt;.html</code></li>
+                    <li>Use the template structure above</li>
+                    <li>Run <code>make sync-manual</code></li>
+                    <li>Update footer prev/next on adjacent pages</li>
+                    <li>Add entry to <code>manual/api/index.html</code></li>
+                </ol>
+
+                <h2>Example: Minimal API Page</h2>
+
+                <pre><code>&lt;!DOCTYPE html&gt;
+&lt;!-- retoor &lt;retoor@molodetz.nl&gt; --&gt;
+&lt;html lang="en"&gt;
+&lt;head&gt;
+    &lt;meta charset="UTF-8"&gt;
+    &lt;meta name="viewport" content="width=device-width, initial-scale=1.0"&gt;
+    &lt;title&gt;mymodule - Wren-CLI Manual&lt;/title&gt;
+    &lt;link rel="stylesheet" href="../css/style.css"&gt;
+&lt;/head&gt;
+&lt;body&gt;
+    &lt;button class="mobile-menu-toggle"&gt;Menu&lt;/button&gt;
+    &lt;div class="container"&gt;
+        &lt;aside class="sidebar"&gt;
+            &lt;div class="sidebar-header"&gt;
+                &lt;h1&gt;&lt;a href="../index.html"&gt;Wren-CLI&lt;/a&gt;&lt;/h1&gt;
+                &lt;div class="version"&gt;v0.4.0&lt;/div&gt;
+            &lt;/div&gt;
+            &lt;nav class="sidebar-nav"&gt;
+            &lt;/nav&gt;
+        &lt;/aside&gt;
+        &lt;main class="content"&gt;
+            &lt;nav class="breadcrumb"&gt;
+                &lt;a href="../index.html"&gt;Home&lt;/a&gt;
+                &lt;span class="separator"&gt;/&lt;/span&gt;
+                &lt;a href="index.html"&gt;API Reference&lt;/a&gt;
+                &lt;span class="separator"&gt;/&lt;/span&gt;
+                &lt;span&gt;mymodule&lt;/span&gt;
+            &lt;/nav&gt;
+
+            &lt;article&gt;
+                &lt;h1&gt;mymodule&lt;/h1&gt;
+
+                &lt;p&gt;The &lt;code&gt;mymodule&lt;/code&gt; module provides...&lt;/p&gt;
+
+                &lt;pre&gt;&lt;code&gt;import "mymodule" for MyClass&lt;/code&gt;&lt;/pre&gt;
+
+                &lt;h2&gt;MyClass&lt;/h2&gt;
+
+                &lt;h3&gt;Static Methods&lt;/h3&gt;
+
+                &lt;div class="method-signature"&gt;
+                    &lt;span class="method-name"&gt;MyClass.process&lt;/span&gt;(&lt;span class="param"&gt;input&lt;/span&gt;)
+                    &amp;rarr; &lt;span class="type"&gt;String&lt;/span&gt;
+                &lt;/div&gt;
+                &lt;p&gt;Processes the input and returns a result.&lt;/p&gt;
+
+                &lt;h3&gt;Examples&lt;/h3&gt;
+                &lt;pre&gt;&lt;code&gt;import "mymodule" for MyClass
+
+var result = MyClass.process("hello")
+System.print(result)&lt;/code&gt;&lt;/pre&gt;
+            &lt;/article&gt;
+
+            &lt;footer class="page-footer"&gt;
+                &lt;a href="math.html" class="prev"&gt;math&lt;/a&gt;
+                &lt;a href="net.html" class="next"&gt;net&lt;/a&gt;
+            &lt;/footer&gt;
+        &lt;/main&gt;
+    &lt;/div&gt;
+    &lt;script src="../js/main.js"&gt;&lt;/script&gt;
+&lt;/body&gt;
+&lt;/html&gt;</code></pre>
+
+                <h2>Checklist for New Documentation</h2>
+
+                <ul>
+                    <li>Author comment on line 2</li>
+                    <li>Correct title in <code>&lt;title&gt;</code> and <code>&lt;h1&gt;</code></li>
+                    <li>Proper breadcrumb navigation</li>
+                    <li>Import statement example</li>
+                    <li>All methods documented with signatures</li>
+                    <li>Working code examples</li>
+                    <li>Footer with prev/next links</li>
+                    <li>Ran <code>make sync-manual</code></li>
+                    <li>Updated adjacent page footers</li>
+                    <li>Added to index page if applicable</li>
+                </ul>
+{% endblock %}

manual_src/pages/contributing/foreign-classes.html

@@ -0,0 +1,383 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Foreign Classes" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Foreign Classes"}] %}
+{% set prev_page = {"url": "contributing/c-backed-module.html", "title": "C-Backed Modules"} %}
+{% set next_page = {"url": "contributing/async-patterns.html", "title": "Async Patterns"} %}
+
+{% block article %}
+                <h1>Foreign Classes</h1>
+
+                <p>Foreign classes allow Wren objects to hold native C data. This is used when a Wren object needs to manage resources like file handles, network sockets, database connections, or any native data structure.</p>
+
+                <h2>When to Use Foreign Classes</h2>
+
+                <ul>
+                    <li>Wrapping system resources (files, sockets, processes)</li>
+                    <li>Managing native library objects</li>
+                    <li>Storing data structures more complex than Wren's built-in types</li>
+                    <li>Resources requiring explicit cleanup</li>
+                </ul>
+
+                <h2>Architecture</h2>
+
+                <p>A foreign class has three components:</p>
+
+                <ol>
+                    <li><strong>Allocate function</strong>: Called when an instance is created via <code>construct new()</code></li>
+                    <li><strong>Finalize function</strong>: Called when the garbage collector frees the instance</li>
+                    <li><strong>Instance methods</strong>: Operate on the foreign data</li>
+                </ol>
+
+                <h2>Basic Pattern</h2>
+
+                <h3>Wren Interface</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+class Buffer {
+    foreign construct new(size)
+
+    foreign write(data)
+    foreign read()
+    foreign size
+    foreign clear()
+}</code></pre>
+
+                <p>The constructor uses <code>foreign construct</code> to trigger allocation.</p>
+
+                <h3>C Implementation</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include "buffer.h"
+#include "wren.h"
+
+typedef struct {
+    char* data;
+    size_t size;
+    size_t capacity;
+} Buffer;
+
+void bufferAllocate(WrenVM* vm) {
+    Buffer* buffer = (Buffer*)wrenSetSlotNewForeign(vm, 0, 0, sizeof(Buffer));
+
+    double capacity = wrenGetSlotDouble(vm, 1);
+    buffer->capacity = (size_t)capacity;
+    buffer->size = 0;
+    buffer->data = (char*)malloc(buffer->capacity);
+
+    if (!buffer->data) {
+        buffer->capacity = 0;
+    }
+}
+
+void bufferFinalize(void* data) {
+    Buffer* buffer = (Buffer*)data;
+    if (buffer->data) {
+        free(buffer->data);
+        buffer->data = NULL;
+    }
+}
+
+void bufferWrite(WrenVM* vm) {
+    Buffer* buffer = (Buffer*)wrenGetSlotForeign(vm, 0);
+    const char* str = wrenGetSlotString(vm, 1);
+    size_t len = strlen(str);
+
+    if (buffer->size + len > buffer->capacity) {
+        wrenSetSlotString(vm, 0, "Buffer overflow.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    memcpy(buffer->data + buffer->size, str, len);
+    buffer->size += len;
+}
+
+void bufferRead(WrenVM* vm) {
+    Buffer* buffer = (Buffer*)wrenGetSlotForeign(vm, 0);
+
+    char* copy = (char*)malloc(buffer->size + 1);
+    if (!copy) {
+        wrenSetSlotNull(vm, 0);
+        return;
+    }
+
+    memcpy(copy, buffer->data, buffer->size);
+    copy[buffer->size] = '\0';
+
+    wrenSetSlotString(vm, 0, copy);
+    free(copy);
+}
+
+void bufferSize(WrenVM* vm) {
+    Buffer* buffer = (Buffer*)wrenGetSlotForeign(vm, 0);
+    wrenSetSlotDouble(vm, 0, (double)buffer->size);
+}
+
+void bufferClear(WrenVM* vm) {
+    Buffer* buffer = (Buffer*)wrenGetSlotForeign(vm, 0);
+    buffer->size = 0;
+}</code></pre>
+
+                <h3>Registration</h3>
+
+                <pre><code>MODULE(buffer)
+  CLASS(Buffer)
+    ALLOCATE(bufferAllocate)
+    FINALIZE(bufferFinalize)
+    METHOD("write(_)", bufferWrite)
+    METHOD("read()", bufferRead)
+    METHOD("size", bufferSize)
+    METHOD("clear()", bufferClear)
+  END_CLASS
+END_MODULE</code></pre>
+
+                <h2>Memory Management</h2>
+
+                <h3>wrenSetSlotNewForeign</h3>
+
+                <pre><code>void* wrenSetSlotNewForeign(WrenVM* vm, int slot, int classSlot, size_t size);</code></pre>
+
+                <ul>
+                    <li><code>slot</code>: Where to place the new instance (usually 0)</li>
+                    <li><code>classSlot</code>: Slot containing the class (usually 0 for the current class)</li>
+                    <li><code>size</code>: Size of the native data structure</li>
+                </ul>
+
+                <p>Returns a pointer to the allocated memory. This memory is managed by Wren's garbage collector.</p>
+
+                <h3>Finalize Function Signature</h3>
+
+                <pre><code>void myFinalize(void* data);</code></pre>
+
+                <p>The finalize function receives only a pointer to the foreign data, not the VM. This means:</p>
+
+                <ul>
+                    <li>No Wren API calls in finalize</li>
+                    <li>Cannot throw errors</li>
+                    <li>Must be fast (GC is running)</li>
+                    <li>Free any resources allocated in allocate or methods</li>
+                </ul>
+
+                <h3>Accessing Foreign Data</h3>
+
+                <p>In instance methods, use <code>wrenGetSlotForeign</code> on slot 0:</p>
+
+                <pre><code>void bufferMethod(WrenVM* vm) {
+    Buffer* buffer = (Buffer*)wrenGetSlotForeign(vm, 0);
+    // buffer points to the struct created in bufferAllocate
+}</code></pre>
+
+                <h2>File Handle Example</h2>
+
+                <p>A practical example wrapping a file handle:</p>
+
+                <h3>filehandle.wren</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+class FileHandle {
+    foreign construct open(path, mode)
+
+    foreign read()
+    foreign write(data)
+    foreign close()
+    foreign isOpen
+}</code></pre>
+
+                <h3>filehandle.c</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include "filehandle.h"
+#include "wren.h"
+
+typedef struct {
+    FILE* file;
+    char* path;
+} FileHandle;
+
+void fileHandleAllocate(WrenVM* vm) {
+    FileHandle* handle = (FileHandle*)wrenSetSlotNewForeign(vm, 0, 0, sizeof(FileHandle));
+
+    const char* path = wrenGetSlotString(vm, 1);
+    const char* mode = wrenGetSlotString(vm, 2);
+
+    handle->path = strdup(path);
+    handle->file = fopen(path, mode);
+
+    if (!handle->file) {
+        wrenSetSlotString(vm, 0, "Failed to open file.");
+        wrenAbortFiber(vm, 0);
+    }
+}
+
+void fileHandleFinalize(void* data) {
+    FileHandle* handle = (FileHandle*)data;
+
+    if (handle->file) {
+        fclose(handle->file);
+        handle->file = NULL;
+    }
+
+    if (handle->path) {
+        free(handle->path);
+        handle->path = NULL;
+    }
+}
+
+void fileHandleRead(WrenVM* vm) {
+    FileHandle* handle = (FileHandle*)wrenGetSlotForeign(vm, 0);
+
+    if (!handle->file) {
+        wrenSetSlotString(vm, 0, "File not open.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    fseek(handle->file, 0, SEEK_END);
+    long size = ftell(handle->file);
+    fseek(handle->file, 0, SEEK_SET);
+
+    char* content = (char*)malloc(size + 1);
+    if (!content) {
+        wrenSetSlotString(vm, 0, "Memory allocation failed.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    fread(content, 1, size, handle->file);
+    content[size] = '\0';
+
+    wrenSetSlotString(vm, 0, content);
+    free(content);
+}
+
+void fileHandleWrite(WrenVM* vm) {
+    FileHandle* handle = (FileHandle*)wrenGetSlotForeign(vm, 0);
+    const char* data = wrenGetSlotString(vm, 1);
+
+    if (!handle->file) {
+        wrenSetSlotString(vm, 0, "File not open.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+
+    size_t written = fwrite(data, 1, strlen(data), handle->file);
+    wrenSetSlotDouble(vm, 0, (double)written);
+}
+
+void fileHandleClose(WrenVM* vm) {
+    FileHandle* handle = (FileHandle*)wrenGetSlotForeign(vm, 0);
+
+    if (handle->file) {
+        fclose(handle->file);
+        handle->file = NULL;
+    }
+}
+
+void fileHandleIsOpen(WrenVM* vm) {
+    FileHandle* handle = (FileHandle*)wrenGetSlotForeign(vm, 0);
+    wrenSetSlotBool(vm, 0, handle->file != NULL);
+}</code></pre>
+
+                <h3>Usage</h3>
+
+                <pre><code>import "filehandle" for FileHandle
+
+var file = FileHandle.open("test.txt", "w")
+file.write("Hello, World!")
+file.close()
+
+file = FileHandle.open("test.txt", "r")
+System.print(file.read())
+file.close()</code></pre>
+
+                <h2>Multiple Foreign Classes</h2>
+
+                <p>A module can have multiple foreign classes:</p>
+
+                <pre><code>MODULE(database)
+  CLASS(Connection)
+    ALLOCATE(connectionAllocate)
+    FINALIZE(connectionFinalize)
+    METHOD("query(_)", connectionQuery)
+    METHOD("close()", connectionClose)
+  END_CLASS
+  CLASS(Statement)
+    ALLOCATE(statementAllocate)
+    FINALIZE(statementFinalize)
+    METHOD("bind(_,_)", statementBind)
+    METHOD("execute()", statementExecute)
+  END_CLASS
+END_MODULE</code></pre>
+
+                <h2>Resource Safety Patterns</h2>
+
+                <h3>Early Close</h3>
+                <p>Always check if resource is still valid:</p>
+                <pre><code>void handleMethod(WrenVM* vm) {
+    Handle* h = (Handle*)wrenGetSlotForeign(vm, 0);
+    if (!h->resource) {
+        wrenSetSlotString(vm, 0, "Handle already closed.");
+        wrenAbortFiber(vm, 0);
+        return;
+    }
+    // ...
+}</code></pre>
+
+                <h3>Double-Free Prevention</h3>
+                <p>Set pointers to NULL after freeing:</p>
+                <pre><code>void handleClose(WrenVM* vm) {
+    Handle* h = (Handle*)wrenGetSlotForeign(vm, 0);
+    if (h->resource) {
+        resource_free(h->resource);
+        h->resource = NULL;
+    }
+}</code></pre>
+
+                <h3>Defensive Finalize</h3>
+                <p>Always handle partially constructed objects:</p>
+                <pre><code>void handleFinalize(void* data) {
+    Handle* h = (Handle*)data;
+    if (h->resource) {
+        resource_free(h->resource);
+    }
+    if (h->name) {
+        free(h->name);
+    }
+}</code></pre>
+
+                <h2>Common Pitfalls</h2>
+
+                <ul>
+                    <li><strong>Forgetting FINALIZE</strong>: Memory leaks for any allocated resources</li>
+                    <li><strong>Using VM in finalize</strong>: Causes undefined behavior</li>
+                    <li><strong>Wrong slot for foreign data</strong>: Instance methods get <code>this</code> in slot 0</li>
+                    <li><strong>Static methods on foreign class</strong>: Use <code>STATIC_METHOD</code> macro, but note that <code>wrenGetSlotForeign</code> is not available (no instance)</li>
+                </ul>
+
+                <h2>Checklist</h2>
+
+                <ul>
+                    <li><code>foreign construct</code> in Wren class</li>
+                    <li>Allocate function uses <code>wrenSetSlotNewForeign</code></li>
+                    <li>Finalize function frees all resources</li>
+                    <li><code>ALLOCATE</code> and <code>FINALIZE</code> in registration</li>
+                    <li>Instance methods use <code>METHOD</code> (not <code>STATIC_METHOD</code>)</li>
+                    <li>Methods access foreign data via slot 0</li>
+                    <li>All methods check resource validity</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <p>For I/O-bound foreign classes, see <a href="async-patterns.html">Async Patterns</a> to integrate with the libuv event loop.</p>
+{% endblock %}

manual_src/pages/contributing/index.html

@@ -0,0 +1,128 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Contributing" %}
+{% set breadcrumb = [{"title": "Contributing"}] %}
+{% set prev_page = {"url": "howto/error-handling.html", "title": "Error Handling"} %}
+{% set next_page = {"url": "contributing/module-overview.html", "title": "Module Architecture"} %}
+
+{% block article %}
+                <h1>Contributing</h1>
+
+                <p>This guide explains how to contribute new modules to Wren-CLI, write tests, and add documentation. Whether you are adding a pure-Wren module or implementing C-backed foreign methods, this section provides step-by-step instructions.</p>
+
+                <div class="toc">
+                    <h4>In This Section</h4>
+                    <ul>
+                        <li><a href="module-overview.html">Module Architecture</a> - Project structure and artifact matrix</li>
+                        <li><a href="pure-wren-module.html">Pure-Wren Modules</a> - Step-by-step for Wren-only modules</li>
+                        <li><a href="c-backed-module.html">C-Backed Modules</a> - Implementing foreign methods in C</li>
+                        <li><a href="foreign-classes.html">Foreign Classes</a> - Native resource management</li>
+                        <li><a href="async-patterns.html">Async Patterns</a> - Scheduler/Fiber and libuv integration</li>
+                        <li><a href="testing.html">Writing Tests</a> - Test structure and annotations</li>
+                        <li><a href="documentation.html">Documentation</a> - Writing manual pages</li>
+                    </ul>
+                </div>
+
+                <h2>Prerequisites</h2>
+
+                <p>Before contributing, ensure you have:</p>
+
+                <ul>
+                    <li>A working build environment (see <a href="../getting-started/installation.html">Installation</a>)</li>
+                    <li>Python 3 (for utility scripts)</li>
+                    <li>Basic understanding of <a href="../language/index.html">Wren syntax</a></li>
+                    <li>For C-backed modules: familiarity with C and the Wren embedding API</li>
+                </ul>
+
+                <h2>Module Types</h2>
+
+                <p>Wren-CLI supports two types of modules:</p>
+
+                <table>
+                    <tr>
+                        <th>Type</th>
+                        <th>Description</th>
+                        <th>Files Required</th>
+                    </tr>
+                    <tr>
+                        <td>Pure-Wren</td>
+                        <td>Modules written entirely in Wren. Examples: argparse, html, jinja, http, markdown, dataset, web, websocket, wdantic, uuid, tempfile</td>
+                        <td><code>.wren</code>, <code>.wren.inc</code>, modules.c entry</td>
+                    </tr>
+                    <tr>
+                        <td>C-Backed</td>
+                        <td>Modules with foreign methods implemented in C. Examples: json, io, net, crypto, tls, sqlite, base64</td>
+                        <td><code>.wren</code>, <code>.wren.inc</code>, <code>.c</code>, <code>.h</code>, modules.c entry, Makefile entry</td>
+                    </tr>
+                </table>
+
+                <h2>Workflow Checklist</h2>
+
+                <h3>Pure-Wren Module</h3>
+                <ol>
+                    <li>Create <code>src/module/&lt;name&gt;.wren</code></li>
+                    <li>Generate <code>.wren.inc</code> with <code>python3 util/wren_to_c_string.py</code></li>
+                    <li>Add <code>#include</code> and <code>MODULE</code> block in <code>src/cli/modules.c</code></li>
+                    <li>Build with <code>make clean && make build</code></li>
+                    <li>Create tests in <code>test/&lt;name&gt;/</code></li>
+                    <li>Create example in <code>example/&lt;name&gt;_demo.wren</code></li>
+                    <li>Create <code>manual/api/&lt;name&gt;.html</code></li>
+                    <li>Run <code>make sync-manual</code></li>
+                    <li>Verify with <code>python3 util/test.py &lt;name&gt;</code></li>
+                </ol>
+
+                <h3>C-Backed Module</h3>
+                <ol>
+                    <li>All pure-Wren steps, plus:</li>
+                    <li>Create <code>src/module/&lt;name&gt;.c</code> with foreign method implementations</li>
+                    <li>Create <code>src/module/&lt;name&gt;.h</code> with function declarations</li>
+                    <li>Add extern declarations in <code>modules.c</code></li>
+                    <li>Add <code>CLASS</code>/<code>METHOD</code> registrations with correct signatures</li>
+                    <li>Add <code>OBJECTS</code> and compilation rule to <code>projects/make/wren_cli.make</code></li>
+                </ol>
+
+                <h2>Build Commands</h2>
+
+                <pre><code>make build                  # Release build
+make debug                  # Debug build
+make clean                  # Clean artifacts
+make tests                  # Build and run all tests
+make sync-manual            # Sync sidebar across manual pages</code></pre>
+
+                <h2>Directory Structure</h2>
+
+                <pre><code>src/
+  cli/
+    modules.c              # Foreign function registry
+    vm.c                   # VM and module loading
+  module/
+    &lt;name&gt;.wren           # Wren interface source
+    &lt;name&gt;.wren.inc       # Generated C string literal
+    &lt;name&gt;.c              # C implementation (if foreign methods)
+    &lt;name&gt;.h              # C header (if foreign methods)
+
+test/
+  &lt;name&gt;/
+    &lt;feature&gt;.wren        # Test files with annotations
+
+example/
+  &lt;name&gt;_demo.wren        # Usage demonstrations
+
+manual/
+  api/&lt;name&gt;.html         # API documentation</code></pre>
+
+                <h2>Getting Help</h2>
+
+                <p>If you encounter issues while contributing:</p>
+
+                <ul>
+                    <li>Review existing modules as reference implementations</li>
+                    <li>Check the test files for expected behavior patterns</li>
+                    <li>Consult the <a href="module-overview.html">Module Architecture</a> section for detailed artifact requirements</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <p>Start with the <a href="module-overview.html">Module Architecture</a> section to understand the project structure, then proceed to the appropriate module guide based on your needs.</p>
+{% endblock %}

manual_src/pages/contributing/module-overview.html

@@ -0,0 +1,221 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Module Architecture" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Module Architecture"}] %}
+{% set prev_page = {"url": "contributing/index.html", "title": "Overview"} %}
+{% set next_page = {"url": "contributing/pure-wren-module.html", "title": "Pure-Wren Modules"} %}
+
+{% block article %}
+                <h1>Module Architecture</h1>
+
+                <p>This section explains how Wren-CLI modules are structured, what files each module type requires, and how the build system processes them.</p>
+
+                <h2>Project Structure</h2>
+
+                <pre><code>src/
+  cli/
+    main.c            # Entry point
+    vm.c              # VM initialization, libuv event loop, module loading
+    modules.c         # Foreign function registry, module registration
+    modules.h         # Public interface for module loading/binding
+    path.c            # Cross-platform path manipulation
+  module/
+    &lt;name&gt;.wren       # Wren interface source
+    &lt;name&gt;.wren.inc   # Generated C string literal (do not edit)
+    &lt;name&gt;.c          # C implementation (only for foreign methods)
+    &lt;name&gt;.h          # C header (only for foreign methods)
+
+test/
+  &lt;modulename&gt;/
+    &lt;testname&gt;.wren   # Test files with inline annotations
+
+example/
+  &lt;modulename&gt;_demo.wren  # Comprehensive usage demonstrations
+
+manual/
+  api/                # One HTML file per module
+
+deps/
+  wren/               # Wren language VM
+  libuv/              # Async I/O library
+  cjson/              # JSON parsing library
+  sqlite/             # SQLite database library</code></pre>
+
+                <h2>Module Artifact Matrix</h2>
+
+                <p>Every built-in module has up to six artifacts:</p>
+
+                <table>
+                    <tr>
+                        <th>Artifact</th>
+                        <th>Path</th>
+                        <th>Required?</th>
+                    </tr>
+                    <tr>
+                        <td>Wren source</td>
+                        <td><code>src/module/&lt;name&gt;.wren</code></td>
+                        <td>Always</td>
+                    </tr>
+                    <tr>
+                        <td>Generated C string</td>
+                        <td><code>src/module/&lt;name&gt;.wren.inc</code></td>
+                        <td>Always</td>
+                    </tr>
+                    <tr>
+                        <td>C implementation</td>
+                        <td><code>src/module/&lt;name&gt;.c</code></td>
+                        <td>Only if foreign methods</td>
+                    </tr>
+                    <tr>
+                        <td>C header</td>
+                        <td><code>src/module/&lt;name&gt;.h</code></td>
+                        <td>Only if .c exists</td>
+                    </tr>
+                    <tr>
+                        <td>Registration in modules.c</td>
+                        <td><code>src/cli/modules.c</code></td>
+                        <td>Always</td>
+                    </tr>
+                    <tr>
+                        <td>Makefile object entry</td>
+                        <td><code>projects/make/wren_cli.make</code></td>
+                        <td>Only if .c exists</td>
+                    </tr>
+                </table>
+
+                <div class="admonition note">
+                    <div class="admonition-title">Note</div>
+                    <p>Pure-Wren modules (argparse, html, jinja, http, markdown, dataset, web, websocket, wdantic, uuid, tempfile, repl) skip the C files and Makefile entry. C-backed modules (json, io, net, crypto, tls, sqlite, base64, etc.) need all six.</p>
+                </div>
+
+                <h2>The .wren to .wren.inc Pipeline</h2>
+
+                <p>Module source code is embedded directly into the compiled binary as C string literals. The script <code>util/wren_to_c_string.py</code> performs this conversion.</p>
+
+                <h3>What It Does</h3>
+                <ol>
+                    <li>Reads the <code>.wren</code> file line by line</li>
+                    <li>Escapes <code>\</code> to <code>\\</code> and <code>"</code> to <code>\"</code></li>
+                    <li>Wraps each line in C string literal quotes with <code>\n</code> appended</li>
+                    <li>Outputs a <code>.wren.inc</code> file with a <code>static const char*</code> variable</li>
+                </ol>
+
+                <h3>Variable Naming</h3>
+                <p>The variable name is derived from the filename: <code>foo.wren</code> becomes <code>fooModuleSource</code>. Prefixes <code>opt_</code> and <code>wren_</code> are stripped automatically.</p>
+
+                <h3>Usage</h3>
+                <pre><code>python3 util/wren_to_c_string.py src/module/foo.wren.inc src/module/foo.wren</code></pre>
+
+                <div class="admonition warning">
+                    <div class="admonition-title">Warning</div>
+                    <p>Every time a <code>.wren</code> file is edited, its <code>.wren.inc</code> must be regenerated. If forgotten, the binary will contain stale module source.</p>
+                </div>
+
+                <h2>Module Registration in modules.c</h2>
+
+                <p><code>src/cli/modules.c</code> has three sections to update:</p>
+
+                <h3>Section 1: Include the .wren.inc</h3>
+                <p>Add at the top of the file with other includes:</p>
+                <pre><code>#include "mymodule.wren.inc"</code></pre>
+
+                <h3>Section 2: Extern Declarations</h3>
+                <p>Only required for C-backed modules:</p>
+                <pre><code>extern void mymoduleDoSomething(WrenVM* vm);
+extern void mymoduleComplexOp(WrenVM* vm);</code></pre>
+
+                <h3>Section 3: Module Array Entry</h3>
+
+                <p>For pure-Wren modules:</p>
+                <pre><code>MODULE(mymodule)
+END_MODULE</code></pre>
+
+                <p>For C-backed modules with static methods:</p>
+                <pre><code>MODULE(mymodule)
+  CLASS(MyClass)
+    STATIC_METHOD("doSomething(_)", mymoduleDoSomething)
+    STATIC_METHOD("complexOp_(_,_,_)", mymoduleComplexOp)
+  END_CLASS
+END_MODULE</code></pre>
+
+                <p>For foreign classes with allocation/finalization:</p>
+                <pre><code>MODULE(mymodule)
+  CLASS(MyForeignClass)
+    ALLOCATE(myClassAllocate)
+    FINALIZE(myClassFinalize)
+    METHOD("doThing(_)", myClassDoThing)
+  END_CLASS
+END_MODULE</code></pre>
+
+                <h3>Registration Macros Reference</h3>
+
+                <table>
+                    <tr>
+                        <th>Macro</th>
+                        <th>Usage</th>
+                    </tr>
+                    <tr>
+                        <td><code>MODULE(name)</code> / <code>END_MODULE</code></td>
+                        <td>Module boundary, name must match import string</td>
+                    </tr>
+                    <tr>
+                        <td><code>CLASS(name)</code> / <code>END_CLASS</code></td>
+                        <td>Class boundary, name must match Wren class name</td>
+                    </tr>
+                    <tr>
+                        <td><code>STATIC_METHOD("sig", fn)</code></td>
+                        <td>Bind static foreign method</td>
+                    </tr>
+                    <tr>
+                        <td><code>METHOD("sig", fn)</code></td>
+                        <td>Bind instance foreign method</td>
+                    </tr>
+                    <tr>
+                        <td><code>ALLOCATE(fn)</code></td>
+                        <td>Foreign class constructor</td>
+                    </tr>
+                    <tr>
+                        <td><code>FINALIZE(fn)</code></td>
+                        <td>Foreign class destructor</td>
+                    </tr>
+                </table>
+
+                <h3>Method Signature Format</h3>
+
+                <p>The signature string must exactly match what Wren expects:</p>
+
+                <ul>
+                    <li><code>"methodName(_)"</code> - one argument</li>
+                    <li><code>"methodName(_,_)"</code> - two arguments</li>
+                    <li><code>"propertyName"</code> - getter (no parentheses)</li>
+                    <li><code>"propertyName=(_)"</code> - setter</li>
+                </ul>
+
+                <h2>Core Components</h2>
+
+                <h3>vm.c</h3>
+                <p>VM initialization, libuv event loop integration, module resolution. The <code>loadModule()</code> function first checks <code>wren_modules/</code> on disk, then falls back to <code>loadBuiltInModule()</code> which serves embedded <code>.wren.inc</code> strings. The <code>resolveModule()</code> function handles simple imports (bare names to built-in) and relative imports (<code>./</code>, <code>../</code> to file path resolution).</p>
+
+                <h3>modules.c</h3>
+                <p>Central registry of all built-in modules. Contains the <code>modules[]</code> array with module/class/method metadata, the <code>.wren.inc</code> includes, extern declarations for C functions, and lookup functions (<code>findModule</code>, <code>findClass</code>, <code>findMethod</code>).</p>
+
+                <h2>Event Loop</h2>
+
+                <p>All I/O is async via libuv. Wren fibers suspend during I/O operations and resume when complete. The event loop runs after script interpretation via <code>uv_run(loop, UV_RUN_DEFAULT)</code>.</p>
+
+                <h2>System Dependencies</h2>
+
+                <ul>
+                    <li>OpenSSL (<code>libssl</code>, <code>libcrypto</code>) - required for TLS/HTTPS support</li>
+                    <li>pthreads, dl, m - linked automatically</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <p>Now that you understand the architecture, proceed to:</p>
+                <ul>
+                    <li><a href="pure-wren-module.html">Pure-Wren Modules</a> - for modules without C code</li>
+                    <li><a href="c-backed-module.html">C-Backed Modules</a> - for modules with foreign methods</li>
+                </ul>
+{% endblock %}

manual_src/pages/contributing/pure-wren-module.html

@@ -0,0 +1,247 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Pure-Wren Modules" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Pure-Wren Modules"}] %}
+{% set prev_page = {"url": "contributing/module-overview.html", "title": "Module Architecture"} %}
+{% set next_page = {"url": "contributing/c-backed-module.html", "title": "C-Backed Modules"} %}
+
+{% block article %}
+                <h1>Pure-Wren Modules</h1>
+
+                <p>Pure-Wren modules are written entirely in Wren, with no C code required. They may depend on other modules (both pure-Wren and C-backed) but do not implement any foreign methods themselves.</p>
+
+                <p>Examples of pure-Wren modules: argparse, html, jinja, http, markdown, dataset, web, websocket, wdantic, uuid, tempfile.</p>
+
+                <h2>Step 1: Create the Wren Source</h2>
+
+                <p>Create <code>src/module/&lt;name&gt;.wren</code> with your module implementation:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+class Utils {
+    static capitalize(str) {
+        if (str.count == 0) return str
+        return str[0].upcase + str[1..-1]
+    }
+
+    static reverse(str) {
+        var result = ""
+        for (i in (str.count - 1)..0) {
+            result = result + str[i]
+        }
+        return result
+    }
+
+    static repeat(str, times) {
+        var result = ""
+        for (i in 0...times) {
+            result = result + str
+        }
+        return result
+    }
+
+    static words(str) {
+        return str.split(" ").where {|w| w.count > 0 }.toList
+    }
+}</code></pre>
+
+                <div class="admonition note">
+                    <div class="admonition-title">Note</div>
+                    <p>Always include the author comment on the first line. Class names should be capitalized and descriptive.</p>
+                </div>
+
+                <h2>Step 2: Generate the .wren.inc</h2>
+
+                <p>Convert the Wren source to a C string literal:</p>
+
+                <pre><code>python3 util/wren_to_c_string.py src/module/utils.wren.inc src/module/utils.wren</code></pre>
+
+                <p>This creates <code>src/module/utils.wren.inc</code> containing:</p>
+
+                <pre><code>static const char* utilsModuleSource =
+"// retoor &lt;retoor@molodetz.nl&gt;\n"
+"\n"
+"class Utils {\n"
+"    static capitalize(str) {\n"
+// ... rest of the source
+;</code></pre>
+
+                <div class="admonition warning">
+                    <div class="admonition-title">Warning</div>
+                    <p>Never edit <code>.wren.inc</code> files directly. Always edit the <code>.wren</code> source and regenerate.</p>
+                </div>
+
+                <h2>Step 3: Register in modules.c</h2>
+
+                <p>Edit <code>src/cli/modules.c</code> to register the new module.</p>
+
+                <h3>Add the Include</h3>
+                <p>Near the top of the file with other includes:</p>
+                <pre><code>#include "utils.wren.inc"</code></pre>
+
+                <h3>Add the Module Entry</h3>
+                <p>In the <code>modules[]</code> array:</p>
+                <pre><code>MODULE(utils)
+END_MODULE</code></pre>
+
+                <p>For pure-Wren modules, the block is empty. No class or method registrations are needed because there are no foreign bindings.</p>
+
+                <h2>Step 4: Build</h2>
+
+                <pre><code>make clean && make build</code></pre>
+
+                <p>The clean build ensures the new module is properly included.</p>
+
+                <h2>Step 5: Test</h2>
+
+                <p>Create the test directory:</p>
+                <pre><code>mkdir -p test/utils</code></pre>
+
+                <p>Create test files with inline annotations. For example, <code>test/utils/capitalize.wren</code>:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "utils" for Utils
+
+System.print(Utils.capitalize("hello")) // expect: Hello
+System.print(Utils.capitalize("WORLD")) // expect: WORLD
+System.print(Utils.capitalize(""))      // expect:</code></pre>
+
+                <p>Run the tests:</p>
+                <pre><code>python3 util/test.py utils</code></pre>
+
+                <h2>Step 6: Create Example</h2>
+
+                <p>Create <code>example/utils_demo.wren</code>:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "utils" for Utils
+
+System.print("=== Utils Demo ===\n")
+
+System.print("--- Capitalize ---")
+System.print(Utils.capitalize("hello"))
+System.print(Utils.capitalize("wren"))
+
+System.print("\n--- Reverse ---")
+System.print(Utils.reverse("hello"))
+System.print(Utils.reverse("12345"))
+
+System.print("\n--- Repeat ---")
+System.print(Utils.repeat("ab", 3))
+System.print(Utils.repeat("-", 10))
+
+System.print("\n--- Words ---")
+var sentence = "The quick brown fox"
+var wordList = Utils.words(sentence)
+for (word in wordList) {
+    System.print("  - %(word)")
+}</code></pre>
+
+                <h2>Step 7: Add Documentation</h2>
+
+                <p>Create <code>manual/api/utils.html</code> following the API page template. See the <a href="documentation.html">Documentation</a> section for details.</p>
+
+                <h2>Step 8: Sync the Sidebar</h2>
+
+                <pre><code>make sync-manual</code></pre>
+
+                <p>This updates the sidebar navigation across all manual pages to include the new module.</p>
+
+                <h2>Step 9: Verify</h2>
+
+                <pre><code>python3 util/test.py utils
+bin/wren_cli example/utils_demo.wren</code></pre>
+
+                <h2>Complete Example</h2>
+
+                <p>Here is a more realistic pure-Wren module that builds on existing modules:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "json" for Json
+import "io" for File
+
+class Config {
+    static load(path) {
+        var content = File.read(path)
+        return Json.parse(content)
+    }
+
+    static save(path, data) {
+        var content = Json.stringify(data, 2)
+        File.write(path, content)
+    }
+
+    static get(path, key) {
+        var config = Config.load(path)
+        return config[key]
+    }
+
+    static set(path, key, value) {
+        var config = {}
+        if (File.exists(path)) {
+            config = Config.load(path)
+        }
+        config[key] = value
+        Config.save(path, config)
+    }
+}</code></pre>
+
+                <p>This module depends on <code>json</code> and <code>io</code>, demonstrating how pure-Wren modules compose functionality from other modules.</p>
+
+                <h2>Common Patterns</h2>
+
+                <h3>Static Utility Classes</h3>
+                <p>Most pure-Wren modules use static methods for stateless utilities:</p>
+                <pre><code>class StringUtils {
+    static trim(s) { ... }
+    static pad(s, width) { ... }
+}</code></pre>
+
+                <h3>Factory Classes</h3>
+                <p>For stateful objects, use instance methods:</p>
+                <pre><code>class Builder {
+    construct new() {
+        _parts = []
+    }
+
+    add(part) {
+        _parts.add(part)
+        return this
+    }
+
+    build() { _parts.join("") }
+}</code></pre>
+
+                <h3>Wrapping Async Operations</h3>
+                <p>Pure-Wren modules can wrap async operations from C-backed modules:</p>
+                <pre><code>import "http" for Http
+
+class Api {
+    static get(endpoint) {
+        return Http.get("https://api.example.com" + endpoint)
+    }
+}</code></pre>
+
+                <h2>Checklist</h2>
+
+                <ul>
+                    <li>Created <code>src/module/&lt;name&gt;.wren</code> with author comment</li>
+                    <li>Generated <code>.wren.inc</code> with util script</li>
+                    <li>Added <code>#include</code> in modules.c</li>
+                    <li>Added <code>MODULE</code>/<code>END_MODULE</code> block in modules.c</li>
+                    <li>Built with <code>make clean && make build</code></li>
+                    <li>Created tests in <code>test/&lt;name&gt;/</code></li>
+                    <li>Created example in <code>example/&lt;name&gt;_demo.wren</code></li>
+                    <li>Created documentation page</li>
+                    <li>Ran <code>make sync-manual</code></li>
+                    <li>All tests pass</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <p>If your module requires native functionality not available through existing modules, see <a href="c-backed-module.html">C-Backed Modules</a>.</p>
+{% endblock %}

manual_src/pages/contributing/testing.html

@@ -0,0 +1,314 @@
+{# retoor <retoor@molodetz.nl> #}
+{% extends 'page.html' %}
+
+{% set page_title = "Writing Tests" %}
+{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Writing Tests"}] %}
+{% set prev_page = {"url": "contributing/async-patterns.html", "title": "Async Patterns"} %}
+{% set next_page = {"url": "contributing/documentation.html", "title": "Documentation"} %}
+
+{% block article %}
+                <h1>Writing Tests</h1>
+
+                <p>Wren-CLI uses inline annotations in test files to specify expected behavior. The test runner <code>util/test.py</code> parses these annotations and verifies the output.</p>
+
+                <h2>Test Directory Structure</h2>
+
+                <pre><code>test/
+  &lt;modulename&gt;/
+    &lt;feature&gt;.wren           # Functional tests
+    error_&lt;scenario&gt;.wren    # Error case tests (one runtime error each)</code></pre>
+
+                <p>Each module has its own directory under <code>test/</code>. Test files are named descriptively based on what they test.</p>
+
+                <h2>Running Tests</h2>
+
+                <pre><code># Build and run all tests
+make tests
+
+# Run tests for a specific module
+python3 util/test.py json
+
+# Run a specific test file (prefix match)
+python3 util/test.py json/parse
+
+# Run with debug binary
+python3 util/test.py --suffix=_d</code></pre>
+
+                <h2>Test Annotations</h2>
+
+                <table>
+                    <tr>
+                        <th>Annotation</th>
+                        <th>Purpose</th>
+                        <th>Expected Exit Code</th>
+                    </tr>
+                    <tr>
+                        <td><code>// expect: output</code></td>
+                        <td>Assert stdout line (matched in order)</td>
+                        <td>0</td>
+                    </tr>
+                    <tr>
+                        <td><code>// expect error</code></td>
+                        <td>Assert compile error on this line</td>
+                        <td>65</td>
+                    </tr>
+                    <tr>
+                        <td><code>// expect error line N</code></td>
+                        <td>Assert compile error on line N</td>
+                        <td>65</td>
+                    </tr>
+                    <tr>
+                        <td><code>// expect runtime error: msg</code></td>
+                        <td>Assert runtime error with exact message</td>
+                        <td>70</td>
+                    </tr>
+                    <tr>
+                        <td><code>// expect handled runtime error: msg</code></td>
+                        <td>Assert caught runtime error</td>
+                        <td>0</td>
+                    </tr>
+                    <tr>
+                        <td><code>// stdin: text</code></td>
+                        <td>Feed text to stdin (repeatable)</td>
+                        <td>-</td>
+                    </tr>
+                    <tr>
+                        <td><code>// skip: reason</code></td>
+                        <td>Skip this test file</td>
+                        <td>-</td>
+                    </tr>
+                    <tr>
+                        <td><code>// nontest</code></td>
+                        <td>Ignore this file</td>
+                        <td>-</td>
+                    </tr>
+                </table>
+
+                <h2>Basic Test Example</h2>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "json" for Json
+
+var obj = {"name": "test", "value": 42}
+var str = Json.stringify(obj)
+var parsed = Json.parse(str)
+
+System.print(parsed["name"])  // expect: test
+System.print(parsed["value"]) // expect: 42</code></pre>
+
+                <p>Each <code>// expect:</code> annotation asserts that the corresponding line of output matches exactly.</p>
+
+                <h2>Multiple Expect Annotations</h2>
+
+                <p>Multiple expectations are matched in order:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "utils" for Utils
+
+System.print(Utils.capitalize("hello")) // expect: Hello
+System.print(Utils.capitalize("world")) // expect: World
+System.print(Utils.capitalize("UPPER")) // expect: UPPER
+System.print(Utils.capitalize(""))      // expect:</code></pre>
+
+                <p>The empty <code>// expect:</code> matches an empty line.</p>
+
+                <h2>Runtime Error Tests</h2>
+
+                <p>For testing error conditions, create a separate file per error case:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "json" for Json
+
+Json.parse("invalid json") // expect runtime error: Invalid JSON.</code></pre>
+
+                <div class="admonition warning">
+                    <div class="admonition-title">Warning</div>
+                    <p>Only one runtime error per test file. The test runner tracks a single expected error. Split multiple error cases into separate files.</p>
+                </div>
+
+                <h3>Error Line Matching</h3>
+
+                <p>The runtime error annotation must be on the line that calls the aborting code. The runner checks the stack trace for a <code>test/...</code> path and matches the line number.</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "io" for File
+
+var content = File.read("/nonexistent/path") // expect runtime error: Cannot open file.</code></pre>
+
+                <h2>Compile Error Tests</h2>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+class Test {
+    foo( // expect error
+}</code></pre>
+
+                <p>Or specify a different line number:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+// This is valid
+var x = 1
+
+class Broken {
+    // expect error line 7
+    foo(</code></pre>
+
+                <h2>Stdin Input</h2>
+
+                <p>Use <code>// stdin:</code> to provide input:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "io" for Stdin
+
+// stdin: hello
+// stdin: world
+
+var line1 = Stdin.readLine()
+var line2 = Stdin.readLine()
+
+System.print(line1) // expect: hello
+System.print(line2) // expect: world</code></pre>
+
+                <p>Multiple <code>// stdin:</code> lines are concatenated with newlines.</p>
+
+                <h2>Skipping Tests</h2>
+
+                <p>Use <code>// skip:</code> for tests that cannot run in all environments:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+// skip: Requires network access
+
+import "http" for Http
+
+var response = Http.get("https://example.com")
+System.print(response.status) // expect: 200</code></pre>
+
+                <h2>Non-Test Files</h2>
+
+                <p>Use <code>// nontest</code> for helper files that should not be run as tests:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+// nontest
+
+class TestHelper {
+    static setup() { ... }
+}</code></pre>
+
+                <h2>Test File Organization</h2>
+
+                <h3>Feature Tests</h3>
+
+                <p>Test each feature in a dedicated file:</p>
+
+                <pre><code>test/json/
+  parse.wren           # Basic parsing
+  parse_nested.wren    # Nested objects/arrays
+  stringify.wren       # JSON serialization
+  stringify_pretty.wren # Pretty printing
+  types.wren           # Type handling</code></pre>
+
+                <h3>Error Tests</h3>
+
+                <p>One error per file, named with <code>error_</code> prefix:</p>
+
+                <pre><code>test/json/
+  error_invalid_syntax.wren
+  error_unexpected_eof.wren
+  error_invalid_escape.wren</code></pre>
+
+                <h2>Handled Runtime Error</h2>
+
+                <p>For testing error handling where errors are caught:</p>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "json" for Json
+
+var result = Fiber.new {
+    Json.parse("bad")
+}.try()
+
+if (result.error) {
+    System.print("Caught error") // expect: Caught error
+} // expect handled runtime error: Invalid JSON.</code></pre>
+
+                <h2>Test Timeout</h2>
+
+                <p>Each test file has a 15-second timeout. If a test hangs (e.g., waiting for input that never comes), it will be killed.</p>
+
+                <h2>Test Discovery</h2>
+
+                <p>The test runner discovers tests by:</p>
+
+                <ol>
+                    <li>Walking the <code>test/</code> directory recursively</li>
+                    <li>Filtering by <code>.wren</code> extension</li>
+                    <li>Converting paths to relative paths from <code>test/</code></li>
+                    <li>Checking if path starts with the filter argument</li>
+                </ol>
+
+                <p>This means:</p>
+                <ul>
+                    <li><code>python3 util/test.py json</code> runs everything in <code>test/json/</code></li>
+                    <li><code>python3 util/test.py io/file</code> runs everything in <code>test/io/file/</code></li>
+                    <li>Subdirectories are supported for organizing large test suites</li>
+                </ul>
+
+                <h2>Example Test Suite</h2>
+
+                <pre><code>test/mymodule/
+  basic.wren
+  advanced.wren
+  edge_cases.wren
+  error_null_input.wren
+  error_invalid_type.wren
+  error_overflow.wren</code></pre>
+
+                <h3>basic.wren</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "mymodule" for MyClass
+
+System.print(MyClass.process("hello"))  // expect: HELLO
+System.print(MyClass.process("world"))  // expect: WORLD
+System.print(MyClass.length("test"))    // expect: 4</code></pre>
+
+                <h3>error_null_input.wren</h3>
+
+                <pre><code>// retoor &lt;retoor@molodetz.nl&gt;
+
+import "mymodule" for MyClass
+
+MyClass.process(null) // expect runtime error: Input cannot be null.</code></pre>
+
+                <h2>Debugging Failing Tests</h2>
+
+                <ol>
+                    <li>Run the test manually: <code>bin/wren_cli test/mymodule/failing.wren</code></li>
+                    <li>Check the actual output versus expected</li>
+                    <li>Verify annotations are on correct lines</li>
+                    <li>For runtime errors, ensure annotation is on the calling line</li>
+                </ol>
+
+                <h2>Best Practices</h2>
+
+                <ul>
+                    <li>Test one concept per file when possible</li>
+                    <li>Use descriptive file names</li>
+                    <li>Always include the author comment</li>
+                    <li>Test edge cases (empty strings, null, large values)</li>
+                    <li>Test error conditions in separate files</li>
+                    <li>Keep tests simple and focused</li>
+                </ul>
+
+                <h2>Next Steps</h2>
+
+                <p>After writing tests, add documentation in <a href="documentation.html">Documentation</a>.</p>
+{% endblock %}