Initial commit

.gitignore

@@ -0,0 +1,25 @@
+# Build output
+build/
+*.o
+*.a
+*.elf
+*.bin
+*.iso
+*.img
+
+# Toolchain / editor
+.cache/
+compile_commands.json
+.vscode/
+.idea/
+*~
+
+# QEMU / debug
+*.log
+qemu*.log
+*.core
+
+# For contributors using ai agents
+AGENTS.md
+.omo
+.codegraph

README.md

@@ -0,0 +1,75 @@
+# Nadir Kernel
+
+Nadir is an x86-64 kernel written from scratch. 
+The name Nadir comes from the Arabic word *naẓīr*. In astronomy it means the point of lowest elevation, in  opposition to the zenith. The documentation assumes general knowlege about how operating systems work.
+
+## Status of the project
+
+The project is in its foundation phase and is not yet usable. Only the bootloader is currently being written.
+
+## Getting started
+
+### Prerequisites
+
+You need two tools:
+
+- **nasm** to assemble `boot.asm` into a bootable image.
+- **qemu-system-x86_64**, the emulator used to run it.
+
+Install both from your package manager:
+
+**Debian / Ubuntu**
+```bash
+sudo apt install nasm qemu-system-x86
+```
+
+**Fedora**
+```bash
+sudo dnf install nasm qemu-system-x86
+```
+
+**Arch Linux**
+```bash
+sudo pacman -S nasm qemu-desktop
+```
+
+**macOS (Homebrew)**
+```bash
+brew install nasm qemu
+```
+
+**Windows**
+
+I can only recommend using Linux distribution, but the Windows Subsystem for Linux is a valid path if you are exclusively running Windows. Install Ubuntu from the Microsoft Store, then run the Debian command above inside its terminal (QEMU's window renders automatically through WSLg).
+
+### Running the kernel
+
+From the repository root:
+
+```bash
+nasm -f bin boot.asm -o boot.bin
+qemu-system-x86_64 -fda boot.bin
+```
+
+A QEMU window opens and you should see this:
+
+![Nadir booting in QEMU](docs/assets/boot.png)
+
+Notes:
+
+- `-fda` boots the image as a BIOS floppy. QEMU's default firmware loads it at address `0x7C00` and executes it in 16-bit real mode.
+- `boot.bin` is a generated artifact and is ignored by git, so you need to build it first. `rm boot.bin` cleans up and it will regenerates on the next `nasm` run.
+- There is no build script or Makefile yet. Those two commands are the whole toolchain.
+- Running over SSH or in a bare terminal? Add `-display curses` to render the boot screen as text instead of a window:
+  ```bash
+  qemu-system-x86_64 -fda boot.bin -display curses
+  ```
+  Quit with `Ctrl-A` then `X`.
+
+### Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `Boot failed: not a bootable disk` | `boot.bin` is not a valid boot sector: it must be exactly 512 bytes and end with the `0xAA55` boot signature. Re-run the `nasm` step and check it completes without errors. |
+| Black screen / blinking cursor | The boot sector only speaks legacy BIOS (`int 0x10` text mode). This works out of the box with QEMU's default SeaBIOS firmware but will not boot under UEFI-only firmware (or UEFI-only real hardware) unless legacy/CSM boot is enabled. |
+| No window appears under WSL2 | Use the `-display curses` variant above. It should work in any terminal. |

boot.asm

@@ -0,0 +1,22 @@
+bits 16 ; 16 bit mode
+org 0x7c00
+
+boot:
+    mov si, message     ; Point SI register to message
+    mov ah, 0x0e        ; Set higher bits to the display character command
+
+.loop:
+    lodsb               ; Load the character within the AL register, and increment SI
+    cmp al, 0           ; Is the AL register a null byte?
+    je halt             ; Jump to halt
+    int 0x10            ; Trigger video service interrupt
+    jmp .loop           ; Loop again
+
+halt:
+    hlt                 ; stop
+
+message:
+    db "Hello, World ! From Nadir Kernel", 0x0a, 0x0d, 0x00
+
+times 510-($-$$) db 0   ; 510 bytes of zeros
+dw 0xAA55               ; boot signature