Update homepage

Home.md

@@ -1,138 +1,248 @@
 # Wizard Apprentice Standard Library
 
-The Wizard's Apprentice Standard Library (`wapp` for short) is a collection of C/C++ utilities intended to replace several parts of the standard libraries of both languages. It is primarily written as a C11 library, with some C++11 functionality used where necessary.
+**Wizard Apprentice Standard Library** (`wapp`) is a lightweight collection of reusable utilities for **C and C++** projects.
 
-## Usage
+It provides common data structures, memory utilities, OS abstractions, and testing tools in a **simple source-distribution format**.
 
-`wapp` is distributed as a source library, meaning it can be used directly in your codebase without building the library beforehand or relying on a specific build system. Each package exposes its interface through a single header file and a single source file, and the same approach applies to the library as a whole.
+The library is primarily written in **C11**, with some **C++11** functionality where necessary.
 
-To start using the library, download the latest [release](https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib/releases).
+The goal of `wapp` is to provide:
+- Practical utilities to replace the C/C++ standard libraries
+- A clean, minimal dependency structure
+- Easy integration without a build system
 
-There are three ways to use the library, listed from the simplest to the most advanced.
+------------------------------------------------------------------------
 
-### 1) Use the whole library
+# Features
 
-Include the `wapp.h` file wherever you want to use the library and add the `wapp.c` file to your build step.
+-   📦 **Header + source design** (drop directly into your project)
+-   ⚙️ **C11 first, C++ compatible**
+-   🧩 **Modular package system**
+-   🧠 **Internal dependency management**
+-   🧪 **Built-in testing framework**
+-   🖥️ **Cross-platform support (POSIX + Windows)**
 
-### 2) Use a single package from the library
+------------------------------------------------------------------------
 
-Each package provides its own header and source files. For example, the `base` package provides `wapp_base.h` and `wapp_base.c`. Including the header and adding the corresponding source file to your build step enables that package in your project.
+# Quick Start
 
-### 3) Using multiple packages
+Download the latest [release](https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib/releases).
 
-This approach is slightly more advanced. If you want to use multiple packages, consult the documentation for the packages you are interested in. Some packages depend on others, and those dependencies are already included internally.
+Add the library to your project.
 
-If you manually add multiple dependent source files to your build step, compilation may fail because it violates the [One Definition Rule](https://en.wikipedia.org/wiki/One_Definition_Rule).
+### Include
 
-Each package's documentation lists its dependencies so you can include them correctly.
+``` c
+#include "wapp.h"
+```
 
-### Build Macros
+### Build
 
-When using the library without the provided build scripts, you may want to define the following macros:
+Add the library source file to your build step:
-- `WAPP_DEBUG_ASSERT` → Enables additional debug checks. It is strongly recommended to define this during development to help catch mistakes early.
-- `WAPP_NO_RUNTIME_ASSERT` → Disables all runtime safety checks. This macro should ideally never be used. However, if you are absolutely confident and want to remove runtime safety checks for performance reasons, you may define it.
 
-## Packages
+```
+wapp.c
+```
 
-To learn more about the different packages in the library, refer to the packages documentation (`Packages.md`).
+You can now use the entire library.
 
-## Library Structure
+------------------------------------------------------------------------
 
-The `src` directory of the library has the following structure:
+# Installation Options
+
+`wapp` can be integrated in three different ways.
+
+## 1. Full Library (Recommended)
+
+Include:
+
+``` c
+#include "wapp.h"
+```
+
+Compile:
+
+```
+wapp.c
+```
+
+This enables **all packages**.
+
+------------------------------------------------------------------------
+
+## 2. Single Package
+
+Each package exposes its own interface.
+
+Example:
+
+```
+wapp_base.h
+wapp_base.c
+```
+
+Usage:
+
+``` c
+#include "wapp_base.h"
+```
+
+Compile:
+
+```
+wapp_base.c
+```
+
+------------------------------------------------------------------------
+
+## 3. Multiple Packages
+
+Some packages depend on others.
+
+When compiling multiple packages manually, avoid compiling dependency sources twice. Doing so violates the [One Definition Rule](https://en.wikipedia.org/wiki/One_Definition_Rule).
+
+Package documentation lists all dependencies.
+
+------------------------------------------------------------------------
+
+# Build Configuration
+
+Two optional macros control runtime checks.
+
+### `WAPP_DEBUG_ASSERT`
+
+Enables additional debug assertions.
+
+Recommended during development.
+
+------------------------------------------------------------------------
+
+### `WAPP_NO_RUNTIME_ASSERT`
+
+Disables all runtime safety checks.
+
+⚠️ Not recommended unless you are certain the library is used correctly.
+
+------------------------------------------------------------------------
+
+# Library Architecture
+
+The library source lives inside the `src` directory.
 
 ```
 src/
 ├── base
-│   ├── array
-│   ├── dbl_list
-│   ├── mem
-│   │   ├── allocator
-│   │   └── utils
-│   ├── queue
-│   └── strings
-│       └── str8
 ├── common
-│   ├── aliases
-│   ├── assert
-│   ├── misc
-│   └── platform
 ├── os
-│   ├── allocators
-│   │   └── arena
-│   ├── cpath
-│   ├── file
-│   │   ├── posix
-│   │   └── win
-│   ├── mem
-│   │   ├── posix
-│   │   └── win
-│   └── shell
-│       ├── commander
-│       │   ├── posix
-│       │   └── win
-│       ├── termcolour
-│       │   ├── posix
-│       │   └── win
-│       └── utils
 ├── prng
-│   └── xorshift
 ├── testing
-│   └── tester
 └── uuid
 ```
 
-Each subdirectory directly under `src` acts as a self-contained package. Some packages depend on others within the library, but these dependencies are handled internally through relative includes. As a result, users generally do not need to manage dependencies manually.
+Each directory represents a **self-contained package**.
 
-Each package provides a single header file and a single source file that include everything required for that package.
+Packages may depend on other packages internally. Dependencies are resolved automatically using **relative includes**, so users usually do not need to manage them manually.
+
+Each package exposes a single public interface:
+
+```
+wapp_<package>.h
+wapp_<package>.c
+```
+
+Example:
 
 ```
 src/
 ├── base
 │   ├── wapp_base.c
 │   └── wapp_base.h
-├── common
-│   └── wapp_common.h
 ├── os
 │   ├── wapp_os.c
 │   └── wapp_os.h
 ├── prng
 │   ├── wapp_prng.c
-│   ├── wapp_prng.h
+│   └── wapp_prng.h
-├── testing
-│   ├── wapp_testing.c
-│   └── wapp_testing.h
 ├── uuid
 │   ├── wapp_uuid.c
 │   └── wapp_uuid.h
+├── testing
+│   ├── wapp_testing.c
+│   └── wapp_testing.h
 ├── wapp.c
 └── wapp.h
 ```
 
-To use a package, simply include its header file and add the corresponding source file to your build step. The same principle applies to the full library: include `wapp.h` and add `wapp.c` to your build step to use the entire library.
+------------------------------------------------------------------------
 
-## Building
+# Packages
 
-This section is only relevant if you want to contribute to or develop the library itself. The build scripts both compile the library and run the C and C++ test suites.
+Package documentation is available in the [Packages](Packages.md) section.
 
-The library is primarily developed on Linux and macOS, so it uses `make` to build the code. However, it functions mostly as a task runner rather than a full build system.
+------------------------------------------------------------------------
 
-Clone the repository:
+# Building the Library
+
+This section is only required if you want to **develop or contribute to the library**.
+
+The build scripts compile the library and run both the **C and C++ test suites**.
+
+The project is primarily developed on **Linux and macOS**, using `make` as a task runner.
+
+------------------------------------------------------------------------
+
+## Clone the Repository
 
 ``` bash
 git clone https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib.git
 cd wizapp-stdlib
 ```
 
-To build the library and run the tests:
+------------------------------------------------------------------------
+
+## Build and Run Tests
 
 ``` bash
 ./build
 ```
 
-For more information about available variables and targets:
+------------------------------------------------------------------------
+
+## Available Build Targets
 
 ``` bash
 make help
 ```
 
-On Windows, you can run the `build.ps1` script in PowerShell. This script builds the library using Microsoft's `msvc` compiler and runs the tests. While it does not yet provide full feature parity with the `Makefile`, it performs the necessary steps (building and testing) to verify that the library works correctly on Windows.
+------------------------------------------------------------------------
+
+# Windows Support
+
+Windows builds are supported using PowerShell.
+
+Run:
+
+```
+build.ps1
+```
+
+The script builds the library using **MSVC** and runs the test suite.
+
+While it does not yet provide full feature parity with the `Makefile`, it performs the required build and validation steps.
+
+------------------------------------------------------------------------
+
+# Contributing
+
+Contributions are welcome.
+
+Please ensure that:
+- New code follows the existing package structure
+- Tests are added when appropriate
+- The project builds and tests pass on supported platforms
+
+------------------------------------------------------------------------
+
+# License
+
+`wapp` is distributed under the [Apache License 2.0](https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib/src/branch/main/LICENSE).