# Sophia OS — install on a real PC

Contents
- `boot.asm` / `boot.bin` — the 512-byte boot sector (stage 1)
- `kernel.asm` / `kernel.bin` — Sophia's 32-bit kernel and drivers
  (VGA text console, GDT/IDT, 8259 PIC, 8254 timer at 100 Hz,
  PS/2 keyboard, ATA PIO disk driver, persistent store at LBA 64-66)
- `sophia-os.img` — 8 MiB raw disk image (dd this to a USB stick)
- `sophia-os.iso` — bootable CD/USB image (El Torito, no emulation)
- `SHA256SUMS.txt` — checksums for everything above

## 1. Find your USB stick (do this carefully)

Linux / WSL:

    lsblk -dpno NAME,SIZE,MODEL

macOS:

    diskutil list

Pick the device that matches the size and model of your stick. Writing to the
wrong device destroys that drive. The device is the whole disk (`/dev/sdb`,
`/dev/nvme0n1`, `/dev/disk4`), never a partition (`/dev/sdb1`).

## 2. Write it (exact command)

Linux — replace `/dev/sdX` with your stick:

    sudo umount /dev/sdX* 2>/dev/null
    sudo dd if=sophia-os.img of=/dev/sdX bs=4M conv=fsync status=progress
    sync

Or write the ISO instead:

    sudo dd if=sophia-os.iso of=/dev/sdX bs=4M conv=fsync status=progress

macOS (note the `r` in `rdiskN` — it is much faster):

    diskutil unmountDisk /dev/diskN
    sudo dd if=sophia-os.img of=/dev/rdiskN bs=4m conv=sync
    diskutil eject /dev/diskN

Windows: use Rufus in **DD image** mode (not ISO mode) and select
`sophia-os.img`.

## 3. Boot it

1. Reboot and open the firmware menu (F12 / F11 / F2 / Del, varies by maker).
2. Turn **Secure Boot off** and enable **Legacy boot / CSM**. This is a
   16-bit BIOS boot sector, so pure UEFI-only machines will not boot it.
3. Choose the USB stick.

You should see: `Sophia OS loading kernel...` then her shell:

    sophia>

## 4. Her commands

    help                  list commands
    ver                   version
    mem                   low memory report
    uptime                ticks since boot
    who                   her identity
    say <text>            append a chat line
    chat                  show the chat log
    remember <text>       append a memory
    memory                show memories
    connect <name>        add a connection
    links                 show connections
    save                  flush chat, memory and links to the drive
    wipe                  clear the stored regions
    clear / halt

Anything you `save` survives a reboot: it is written to sectors 64-66 of the
same drive she booted from.

## 5. Carry chat and memory between the app and the stick

In the Sophia app open **Kernel bridge**:
- *Export* writes `sophia-store.bin` (1536 bytes) from the app's chat, memory
  and connections. Put it on the drive:

      sudo dd if=sophia-store.bin of=/dev/sdX bs=512 seek=64 conv=fsync

- To bring the machine's own lines back into the app, read them off first:

      sudo dd if=/dev/sdX of=sophia-store.bin bs=512 skip=64 count=3

  then *Import* that file in the Kernel bridge page.

The bridge also mirrors the store through her cloud sync, so a stick written
from one computer can be rebuilt on another — sign in on both, and the merged
store carries every device's chat, memory and connections.

## 6. Try it without hardware first

    qemu-system-x86_64 -drive file=sophia-os.img,format=raw -m 64 -display curses
    qemu-system-x86_64 -cdrom sophia-os.iso -m 64 -display curses

## Honest limits

This is Sophia's own kernel written from scratch: real bootloader, real
drivers, real persistence. It is not Linux — no networking, no filesystem, no
graphics stack, and the on-disk store is 500 bytes per region. The full Sophia
(chat, memory lattice, court record, cloud sync) runs in the app; the kernel is
her bare-metal foothold that survives a reboot with no operating system under
her.