doc: adjust examples with ELF metadata

docs/appdev/examples/01_hello_cli.md

@@ -7,16 +7,18 @@
 
 This example demonstrates the bare minimum structure of a BoredOS application that outputs text to the standard output (usually the Terminal executing the binary).
 
-## 📝 Concepts Introduced
+## Concepts Introduced
 * Including `stdlib.h` for basic IO.
 * The `main()` entry point.
 * Using `printf()` for formatted output.
+* Declaring app metadata via source annotations.
 
 ---
 
-## 💻 The Code (`src/userland/cli/hello_world.c`)
+## The Code (`src/userland/cli/hello_world.c`)
 
 ```c
+// BOREDOS_APP_DESC: Hello World — a minimal CLI demo.
 #include <stdlib.h>
 
 int main(int argc, char **argv) {
@@ -34,14 +36,15 @@ int main(int argc, char **argv) {
 }
 ```
 
-## 🛠️ How it Works
+## How it Works
 
 1.  **`#include <stdlib.h>`**: We include the SDK's standard library header which gives us access to `printf`.
 2.  **`int main(...)`**: Every process begins execution here (managed transparently by `crt0.asm`).
 3.  **`printf(...)`**: The SDK routes this call internally directly to the `SYS_WRITE` system call, making it available on the terminal.
 4.  **`return 0`**: A successful exit code.
+5.  **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: These comment annotations are read by the build system (`gen_userland_note.sh`) and embedded as a `boredos_app_metadata_t` NOTE entry inside the compiled `.elf`. The File Explorer and Desktop use this to display the correct icon. See [`elf_metadata.md`](../elf_metadata.md) for full details.
 
-## 🚀 Running It
+## Running It
 
 If you build the project, you can open the Terminal and type:
 ```sh

docs/appdev/examples/02_basic_window.md

@@ -7,17 +7,19 @@
 
 This example demonstrates how to create an empty window that stays active on the screen until the user explicitly closes it by clicking the 'X' button.
 
-## 📝 Concepts Introduced
+## Concepts Introduced
 * Including `libui.h` and the event structure.
 * Creating a `ui_window_t` handle.
 * Creating an infinite event loop using `ui_get_event()`.
 * Yielding CPU time to the kernel via `sys_yield()`.
+* Declaring app metadata via source annotations.
 
 ---
 
-## 💻 The Code (`src/userland/gui/basic_window.c`)
+## The Code (`src/userland/gui/basic_window.c`)
 
 ```c
+// BOREDOS_APP_DESC: Basic Window — a minimal graphical window demo.
 #include <stdlib.h>
 #include <libui.h>
 #include <syscall.h>
@@ -65,7 +67,8 @@ int main(void) {
 2.  **The Event Loop**: Graphical programs run forever until closed. The `while (1)` loop serves this purpose.
 3.  **Polling**: `ui_get_event` asks the kernel, "Hey, did the user click my window or press a key since the last time I asked?". It is non-blocking, so it immediately returns `false` if nothing happened.
 4.  **CPU Yielding**: Since we are constantly polling in a tight loop, we call `sys_yield()` at the end of the loop frame. This politely tells the OS scheduler, "I'm done checking for events, go ahead and let another program run for a bit."
+5.  **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the `.elf` by the build system as a BoredOS NOTE section. The Window Manager reads this at runtime to render the app's icon on the Desktop and in the File Explorer. See [`elf_metadata.md`](../elf_metadata.md) for full details.
 
-## 🚀 Running It
+## Running It
 
 Launch the Terminal and type `basic_window`. You'll see an empty window appear that you can move around the screen!

docs/appdev/examples/03_bouncing_ball.md

@@ -7,17 +7,20 @@
 
 This example builds upon the `02_basic_window` guide. It demonstrates how to constantly update the screen to simulate a bouncing square moving freely inside the window bounds.
 
-## 📝 Concepts Introduced
+## Concepts Introduced
 * Maintaining application state across frames (Velocity/Position).
 * Drawing primitives (`ui_fill_rect`, `ui_draw_string`).
 * The importance of clearing the screen on a new frame.
 * Explicitly forcing standard visual updates via `ui_mark_dirty()`.
+* Declaring app metadata via source annotations.
 
 ---
 
-## 💻 The Code (`src/userland/gui/bounce.c`)
+## The Code (`src/userland/gui/bounce.c`)
 
 ```c
+// BOREDOS_APP_DESC: Bouncing ball animation demo.
+// BOREDOS_APP_ICONS: /Library/images/icons/colloid/applications-games.png
 #include <stdlib.h>
 #include <libui.h>
 #include <syscall.h>
@@ -81,12 +84,13 @@ int main(void) {
 }
 ```
 
-## 🛠️ How it Works
+## How it Works
 
 1.  **State Management**: We store `pos_x`, `pos_y`, `vel_x`, and `vel_y`. These variables represent the "physics" of our system. Notice that they update *outside* the event-checking logic so that the animation runs even if the user isn't clicking the mouse.
 2.  **Screen Clearing**: We *must* fill the screen with black (`ui_draw_rect(wid, 0, 0, W_WIDTH, W_HEIGHT, ...)`). If we don't clear the screen, the red square will leave a permanent trailing smear everywhere it goes!
 3.  **The Double Buffer**: `ui_draw_rect` and `ui_draw_string` do not immediately appear on your monitor. They just color a hidden buffer within the kernel.
 4.  **`ui_mark_dirty`**: This is the crucial command that tells the kernel Window Manager, "I'm done drawing my frame. Can you quickly copy my hidden buffer over to the real screen now?"
+5.  **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the compiled `.elf` as a BoredOS NOTE section. The Desktop and File Explorer read this to show the game's icon instead of the generic binary icon. See [`elf_metadata.md`](../elf_metadata.md) for full details.
 
 > [!WARNING]
 > Because `sys_yield()`'s pause duration depends heavily on CPU load and how many other processes are running (or QEMU emulation speed), tying physics/movement strictly to loops can make the game run faster on faster computers. Advanced developers will want to calculate delta time (time elapsed since the last frame) for smooth motion.

docs/appdev/examples/04_tcp_client.md

@@ -12,12 +12,15 @@ This advanced example demonstrates the steps required to use the raw network sys
 * Performing DNS lookups manually via `sys_dns_lookup`.
 * Managing strict TCP flow logic (`sys_tcp_connect`, send, block for receive).
 * Using the terminal `SYS_WRITE` output for debugging.
+* Declaring app metadata via source annotations.
 
 ---
 
-## 💻 The Code (`src/userland/cli/http_get.c`)
+## The Code (`src/userland/cli/http_get.c`)
 
 ```c
+// BOREDOS_APP_DESC: HTTP GET client — fetches a webpage over TCP.
+// BOREDOS_APP_ICONS: /Library/images/icons/colloid/network-wired.png
 #include <stdlib.h>
 #include <string.h>
 #include <syscall.h>
@@ -79,14 +82,15 @@ int main(void) {
 }
 ```
 
-## 🛠️ How it Works
+## How it Works
 
 1.  **Network Setup**: First, we must ensure the host machine or QEMU environment gave BoredOS a valid IP address via DHCP. The `sys_network_has_ip()` check prevents our app from hanging trying to route data to nowhere.
 2.  **DNS (`sys_dns_lookup`)**: Since we want to connect to a domain name, not a raw IP, we query the DNS server configured by the OS (which it received via DHCP).
 3.  **Connection (`sys_tcp_connect`)**: We block the application thread while the OS performs the 3-way TCP handshake over port 80.
 4.  **Payload (`sys_tcp_send`)**: We format a compliant HTTP/1.1 payload representing a simple GET request for the root directory `/`.
 5.  **Chunked Receiving (`sys_tcp_recv`)**: The server's response might be larger than our `recv_buf` (512 bytes). Therefore, we loop. `sys_tcp_recv` blocks execution until data arrives. If it returns `0`, the remote server cleanly closed the connection (which happens automatically because we specified `Connection: close` in our request payload!).
+6.  **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the compiled `.elf` as a BoredOS NOTE section. The Desktop and File Explorer read this to display the app's icon. See [`elf_metadata.md`](../elf_metadata.md) for full details.
 
-## 🚀 Running It
+## Running It
 
 Make sure QEMU is running with networking enabled. Launch the terminal and type `http_get`. You will see the raw headers and HTML source of the target webpage scroll down the CLI interface!

docs/architecture/core.md

@@ -34,7 +34,7 @@ BoredOS uses **Limine** as its primary bootloader.
 5.  **Driver Initialization**: PCI buses are scanned, finding the network card or disk controllers. The filesystem is mounted.
 6.  **Window Manager**: The UI is drawn on top of the Limine-provided framebuffer.
 
-## 🧵 Multi-Core & Scheduling
+## Multi-Core & Scheduling
 
 BoredOS utilizes Symmetric Multi-Processing (SMP) to distribute workloads across all available CPU cores.
 

docs/architecture/window_manager.md

@@ -16,7 +16,7 @@ BoredOS features a fully custom, graphical Window Manager built directly into th
 > [!TIP]
 > The performance of the window manager heavily depends on minimizing the "dirty regions" drawn in the compositing loop rather than sweeping the whole screen.
 
-## 🪟 Window System (`wm.c`)
+## Window System (`wm.c`)
 
 The windowing system is built around a linked list of `Window` structures.
 
@@ -34,7 +34,7 @@ The WM acts as the central hub for input routing.
 
 - **Event Polling**: The UI loop inside an app continuously calls `ui_poll_event()` to respond to mouse clicks and window movement dispatched by the kernel WM.
 
-## 🧵 Multi-Core Safety & Performance
+## Multi-Core Safety & Performance
 
 With the introduction of Symmetric Multi-Processing (SMP), the Window Manager (WM) was redesigned to ensure stability and high performance across multiple cores.