DOC: small user manual

docs/README.md

@@ -5,7 +5,7 @@
 
 ---
 
-Welcome to the internal documentation for BoredOS! This directory contains detailed guides on how the OS functions, how to build it, and how to develop applications for it.
+Welcome to the documentation for BoredOS! This directory contains detailed guides on how the OS functions, how to build it, and how to develop applications for it.
 
 ## 📚 Table of Contents
 
@@ -32,4 +32,12 @@ The SDK and toolchain guides for creating your own `.elf` userland binaries.
 -   [`Example Apps`](appdev/examples/README.md): A collection of sample C applications ranging from basic terminal output to advanced TCP networking.
 -   [`Grapher`](appdev/grapher.md): Full reference for the built-in mathematical graphing application — equation syntax, keyboard controls, architecture, and configuration.
 
+### 4. [Usage](usage/)
+General guides on how to interact with the OS.
+-   [`Booting`](usage/booting.md): How to use the Limine bootloader and toggle kernel boot flags like `-v`.
+-   [`Desktop`](usage/desktop.md): Window management, shortcuts, and desktop interaction.
+-   [`Lumos`](usage/lumos.md): Using the system-wide search (`Shift + Ctrl + Space`).
+-   [`Terminal`](usage/terminal.md): Command line interface, redirection, and common commands.
+-   [`Launching Apps`](usage/launching_apps.md): Ways to launch files and applications, plus a software overview.
+
 ---

docs/usage/booting.md

@@ -0,0 +1,33 @@
+# Booting BoredOS
+
+BoredOS uses the Limine bootloader, which provides a flexible way to configure the boot process and pass parameters to the kernel.
+
+## Boot Parameters
+
+You can modify system behavior at startup by passing specific boot flags.
+
+### Verbose Boot (`-v`)
+
+The `-v` flag enables the kernel console (`kconsole`) during the boot process. When enabled, the kernel will display detailed initialization logs on the screen. By default, this is often disabled in the included configuration for a cleaner "splash-only" boot experience.
+
+#### Toggling Verbose Boot at Runtime
+
+You can enable or disable the verbose boot log directly from the Limine boot menu without modifying the source files:
+
+1.  **Select Entry**: When the Limine boot menu appears, highlight the **BoredOS** entry.
+2.  **Edit**: Press `E` to enter the entry editor.
+3.  **Modify Flag**: Find the line containing `cmdline: -v`. 
+    -   To **Enable**: Remove the `#` character if the line is commented out (change `# cmdline: -v` to `cmdline: -v`).
+    -   To **Disable**: Add a `# ` at the start of the line.
+4.  **Boot**: Press `F10` to boot using the modified parameters.
+
+#### Persistent Configuration
+
+To change the default behavior permanently, modify the `limine.conf` file in the repository root before building the ISO:
+
+```conf
+/BoredOS
+    protocol: limine
+    path: boot():/boredos.elf
+    cmdline: -v
+```

docs/usage/desktop.md

@@ -0,0 +1,35 @@
+# Using the Desktop
+
+The BoredOS desktop environment is designed to be intuitive while providing powerful window management and icons for quick access to your files and applications.
+
+## Window Management
+
+BoredOS uses a stacking window manager (BoredWM) that allows you to overlap and organize multiple windows.
+
+### Basic Actions
+-   **Focus**: Click anywhere on a window to bring it to the front and make it the active window.
+-   **Move**: Click and drag the **title bar** (the top bar of the window) to reposition it on the screen.
+-   **Close**: Click the red traffic light close button in the top-left corner of the window.
+
+### System-wide Shortcuts
+BoredOS includes several global shortcuts to help you manage your workflow:
+-   **`Ctrl + P`**: Take a screenshot. The image will be saved to `/root/Desktop` as `screenshot.jpg`.
+-   **`Shift + Ctrl + Space`**: Toggle **Lumos** search (see the [Lumos guide](lumos.md)).
+
+## Desktop Icons
+
+Your desktop represents the contents of the `/root/Desktop` directory.
+
+-   **Launching**: Double-click an icon to open the file or launch the application.
+-   **Snapping**: Icons automatically snap to a grid for a clean look. You can toggle "Snap to Grid" and "Auto Align" in the [Settings app](../launching_apps.md).
+-   **Context Menu**: Right-click on the desktop background to create new files, folders, or refresh the layout.
+
+## The Bottom Dock
+
+The dock at the bottom of the screen provides quick shortcuts to your most-used applications, with for example:
+-   **Files**: Browse the entire filesystem.
+-   **Terminal**: Access the command-line interface.
+-   **Calculator / Notepad / Grapher**: Essential productivity tools.
+
+---
+[Return to Documentation Index](../README.md)

docs/usage/launching_apps.md

@@ -0,0 +1,31 @@
+# Launching Applications
+
+BoredOS provides several ways to launch applications and files, depending on your preferred workflow.
+
+## 1. Using the File Explorer
+
+The File Explorer is the primary way to navigate the filesystem and launch any `.elf` binary or associated document.
+
+1.  Open the **Explorer** from the dock or desktop.
+2.  Navigate to `/bin` for system applications or your own user folders.
+3.  **Double-click** any executable (`.elf`) to run it.
+4.  Standard files (like `.jpg` or `.txt`) will automatically open in their default viewer.
+
+## 2. Desktop Shortcuts and Icons
+
+Commonly used applications are placed directly on the desktop.
+
+-   Simply **Double-click** any icon on the desktop to launch it.
+-   You can also create desktop shortcuts by right-clicking on a file and selecting **"Create Shortcut"**.
+
+## 3. Using Lumos (Global Search)
+
+For the fastest access, use **Lumos** to search and launch by name:
+
+1.  Press **`Shift + Ctrl + Space`**.
+2.  Type the name of the app (e.g., "DOOM.elf").
+3.  Press **Enter** to launch.
+
+
+---
+[Return to Documentation Index](../README.md)

docs/usage/lumos.md

@@ -0,0 +1,29 @@
+# Lumos: System Search
+
+**Lumos** is the powerful, system-wide search and launch assistant for BoredOS. It allows you to find applications, documents, and system files instantly without navigating through folders.
+
+## Opening Lumos
+
+To activate Lumos at any time, use the global keyboard shortcut:
+
+**`Shift + Ctrl + Space`**
+
+The Lumos search modal will appear in the center of your screen, ready for input.
+
+## Features
+
+-   **Fuzzy Searching**: You don't need to type the exact name. Lumos uses fuzzy matching to find the most relevant results as you type.
+-   **Deep Indexing**: Lumos indexes files across the entire system.
+-   **Quick Launch**: Once you find what you're looking for, launching it is as simple as pressing `Enter`.
+
+## Navigation
+
+When the Lumos window is open:
+-   **Type**: Just start typing to filter results.
+-   **Arrow Keys (Up/Down)**: Move the selection highlight through the list of results.
+-   **Enter**: Launch the selected file or application.
+-   **Backspace**: Delete characters in your search query.
+-   **Escape**: Close Lumos and return to the desktop.
+
+---
+[Return to Documentation Index](../README.md)

docs/usage/terminal.md

@@ -0,0 +1,33 @@
+# Terminal & Command Line
+
+The BoredOS Terminal provides a powerful command-line interface (CLI) for advanced users and developers. It supports standard Unix-like features and provides direct access to the kernel's system calls.
+
+## The Shell
+
+The default shell in BoredOS is a custom-built, lightweight command processor integrated into the Window Manager. It features:
+-   **ANSI Color Support**: Rich text output with colors and styles.
+-   **Command History**: Use the **Up** and **Down** arrow keys to navigate through your previous commands (up to 64 history entries).
+-   **Output Redirection**:
+    -   `command > file`: Write output to a new file (or overwrite existing).
+    -   `command >> file`: Append output to an existing file.
+-   **Piping**:
+    -   `command1 | command2`: Pass the output of the first command as input to the second.
+
+## Common Commands
+
+Below are some of the most used commands available in `/bin`:
+
+| Command | Description |
+| :--- | :--- |
+| `ls` | List files and directories in the current path. |
+| `cd` | Change the current working directory. |
+| `cat` | Display the contents of a file. |
+| `ls` | List directory contents. |
+| `rm` | Remove a file. |
+| `mkdir` | Create a new directory. |
+| `man` | View the manual for a specific command (e.g., `man ls`). |
+| `sysfetch` | Display system and hardware information. |
+
+
+---
+[Return to Documentation Index](../README.md)

limine.conf

@@ -13,3 +13,4 @@ backdrop: 000000
 /BoredOS
     protocol: limine
     path: boot():/boredos.elf
+    # cmdline: -v

src/core/kconsole.c

@@ -15,7 +15,7 @@ static uint32_t text_color = 0xFFFFFFFF; // White
 void kconsole_init(void) {
     cursor_x = 10;
     cursor_y = 10;
-    kconsole_active = true;
+    kconsole_active = false;
     
     // Initial clear screen during boot
     graphics_clear_back_buffer(0x00000000);

src/core/kutils.c

@@ -155,3 +155,17 @@ void k_beep_process(void) {
     }
 }
 
+char *k_strstr(const char *haystack, const char *needle) {
+    if (!*needle) return (char *)haystack;
+    for (; *haystack; haystack++) {
+        const char *h = haystack;
+        const char *n = needle;
+        while (*h && *n && *h == *n) {
+            h++;
+            n++;
+        }
+        if (!*n) return (char *)haystack;
+    }
+    return NULL;
+}
+

src/core/kutils.h

@@ -26,5 +26,6 @@ void k_reboot(void);
 void k_shutdown(void);
 void k_beep(int freq, int ms);
 void k_beep_process(void);
+char *k_strstr(const char *haystack, const char *needle);
 
 #endif

src/core/main.c

@@ -70,6 +70,7 @@ static volatile struct limine_bootloader_info_request bootloader_info_request =
     .revision = 0
 };
 
+__attribute__((used, section(".requests")))
 static volatile struct limine_kernel_file_request kernel_file_request = {
     .id = LIMINE_KERNEL_FILE_REQUEST,
     .revision = 0
@@ -229,6 +230,15 @@ void kmain(void) {
     struct limine_framebuffer *fb = framebuffer_request.response->framebuffers[0];
     graphics_init(fb);
     kconsole_init();
+
+    // Check for verbose boot flag
+    if (kernel_file_request.response != NULL && kernel_file_request.response->kernel_file != NULL) {
+        const char *cmdline = kernel_file_request.response->kernel_file->cmdline;
+        if (cmdline != NULL && k_strstr(cmdline, "-v") != NULL) {
+            kconsole_set_active(true);
+        }
+    }
+
     log_ok("Graphics and Console ready");
 
     if (memmap_request.response != NULL) {

src/sys/idt.c

@@ -140,12 +140,12 @@ static void pic_remap(void) {
 static void pit_setup(void) {
     uint16_t divisor = 1193182 / 60;  // ~60Hz
     
-    // Send command byte
+    // Mode 2: Rate Generator (more appropriate for periodic interrupts)
-    outb(0x43, 0x36); // Channel 0, lobyte/hibyte, mode 3 (square wave), binary
+    outb(0x43, 0x34); io_wait(); // Channel 0, lobyte/hibyte, mode 2, binary
     
     // Send divisor
-    outb(0x40, divisor & 0xFF);
+    outb(0x40, divisor & 0xFF); io_wait();
-    outb(0x40, (divisor >> 8) & 0xFF);
+    outb(0x40, (divisor >> 8) & 0xFF); io_wait();
 }
 
 void idt_init(void) {

src/sys/smp.c

@@ -31,27 +31,24 @@ static inline void wrmsr(uint32_t msr, uint64_t value) {
 }
 
 static uint32_t read_lapic_id(void) {
-    uint32_t eax, ebx, ecx, edx;
+    extern uint64_t hhdm_offset;
-    asm volatile("cpuid" : "=a"(eax), "=b"(ebx), "=c"(ecx), "=d"(edx) : "a"(1));
+    volatile uint32_t *lapic = (volatile uint32_t *)(hhdm_offset + 0xFEE00000ULL);
-    return (ebx >> 24) & 0xFF;
+    return (lapic[0x020 / 4] >> 24) & 0xFF;
 }
 
 uint32_t smp_this_cpu_id(void) {
-    if (total_cpus <= 1 || !cpu_states) return 0;
+    if (!cpu_states || total_cpus == 0) return 0;
-    
-    // Use GS-based self-pointer to get the structure first
-    cpu_state_t *state = NULL;
-    // Safely check GS:0. If GS is not set or base is 0, this should be handled carefully.
-    // In BoredOS, if GS is not set, this might still fault depending on address space.
-    // However, the cpu_states check above covers the most likely early-boot failure.
-    asm volatile("movq %%gs:0, %0" : "=r"(state) : : "memory");
-    if (state) return state->cpu_id;
 
     uint32_t lapic = read_lapic_id();
+    if (lapic == bsp_lapic_id) return 0;
+    cpu_state_t *state = NULL;
+    asm volatile("movq %%gs:0, %0" : "=r"(state) : : "memory");
+    if (state && state->lapic_id == lapic) return state->cpu_id;
     for (uint32_t i = 0; i < total_cpus; i++) {
-        if (cpu_states[i].lapic_id == lapic) return i;
+        if (cpu_states[i].online && cpu_states[i].lapic_id == lapic) return i;
     }
-    return 0; // Fallback to BSP
+    
+    return 0; 
 }
 
 uint32_t smp_cpu_count(void) {
@@ -126,7 +123,8 @@ static void ap_entry(struct limine_smp_info *info) {
 void smp_init_bsp(void) {
     static cpu_state_t bsp_state_static = {0};
     bsp_state_static.cpu_id = 0;
-    bsp_state_static.lapic_id = read_lapic_id();
+    bsp_lapic_id = read_lapic_id();
+    bsp_state_static.lapic_id = bsp_lapic_id;
     bsp_state_static.self = &bsp_state_static;
     bsp_state_static.online = true;