Phase 7: README, docs, final check

# tsh scripting language

The dynamic, tree-walking counterpart to the [tiny compiler](bytecode-isa.md).
Run with the shell's `run <file>` command; see `tests/hello.tsh` for a
worked example.

## Syntax

C-like statements, no semicolons after blocks:

```
x = 2 + 3 * 4;
print("x =", x);

func add(a, b) {
    return a + b;
}
print("add(3,4) =", add(3, 4));

i = 0;
while (i < 3) {
    print("loop", i);
    i = i + 1;
}
```

- Types: 32-bit integers and strings (`"..."`). No arrays, no booleans -
  `0`/empty-string are falsy, everything else truthy.
- Variables: no declarations: first assignment creates them. All
  variables in a script share one global scope, *except* inside a
  function body, which gets its own isolated local scope - functions
  cannot see the caller's variables or each other's (no closures).
- Control flow: `if (...) {...} else {...}` (including `else if` chains),
  `while (...) {...}`.
- Functions: `func name(params) {...}`, `return expr;` (or bare `return;`
  / falling off the end, both give `0`).
- Operators: `+ - * / %`, `== != < <= > >=`, `&& ||` (short-circuit),
  unary `- !`. `+` on any string operand concatenates (numbers are
  stringified).
- Comments: `# to end of line`.

## Builtins

| call | effect |
|---|---|
| `print(a, b, ...)` | writes args space-separated + newline to console and serial |
| `fread(name)` | returns a file's contents as a string, or `""` if missing |
| `fwrite(name, contents)` | creates/overwrites a tinyfs file, returns `1`/`0` |
| `flist()` | prints every file name (one per line), returns the count |

## Implementation

`kernel/lang/lexer.c` (shared with the compiler) tokenizes;
`kernel/lang/script/parser.c` builds an AST (`ast.h`) via recursive
descent; `kernel/lang/script/eval.c` tree-walks it directly - there is no
intermediate bytecode, unlike the compiled language. AST nodes and string
literals are allocated from the kernel heap and never freed; fine for a
single `run` of a short script, since the heap resets on reboot.

# boot-to-claude

A from-scratch, single-tasking x86 OS for QEMU/KVM: a custom two-stage
boot loader, a monolithic kernel with its own tiny filesystem (tinyfs), an
interactive shell, a dynamic scripting language, and a small C-like
compiler with its own bytecode VM.

Every line of OS/filesystem/language source in this repo is hand-written
for this project - `nasm`, `gcc`, `ld`, `objcopy`, and `qemu` are used
purely as build/run infrastructure, the same way any project uses a
compiler.

## Quickstart

```
make        # builds build/disk.img
make run    # boots it in QEMU (headless, serial on stdio)
```

`make run` boots into the shell:

```
tiny-os shell. type 'help' for commands.
> ls
hello.txt  15
hello.tsh  281
hello.tc   206
> cat hello.txt
Hello, tinyfs!
> run hello.tsh
hello from tinyfs script
x = 14
...
> build hello.tc hello.tbc
build: ok
> exec hello.tbc
14
7
55
10
```

That one session exercises every layer: tinyfs (`ls`/`cat`), the
scripting language (`run`, including its own `fread`/`fwrite` calls into
tinyfs), and the compiler + bytecode VM (`build` + `exec`, including a
recursive function call). `tools/run_tests.sh` automates exactly this
against a headless QEMU instance - see [Testing](#testing).

Requires `nasm`, `gcc` (with `-m32` support), `ld`, `objcopy`, `dd`, and
`qemu-system-i386` on the host. No cross-compiler needed.

## Architecture

```
BIOS -> boot/boot.S (MBR, 512B)         real mode
     -> boot/stage2.S                    real mode -> protected mode
     -> kernel/entry.S -> kmain.c        32-bit protected mode, flat, no paging
          gdt.c / idt.c                  kernel-owned GDT; IDT covers CPU
                                          exceptions only - no PIC/IRQs, ever
          console.c / serial.c           VGA text + COM1, dual-output throughout
          memory.c                       free-list kmalloc/kfree over a 1MB heap
          ata.c -> fs/tinyfs.c           polled ATA PIO -> tinyfs filesystem
          keyboard.c -> shell/shell.c    polled PS/2 -> command REPL
          lang/lexer.c (shared)
            -> lang/script/{parser,ast,eval}.c   scripting language (tree-walking)
            -> lang/compiler/{parser,codegen}.c  compiler -> lang/vm.c (bytecode VM)
```

Deliberately single-tasking: no scheduler, no preemption, no interrupts
enabled after boot, no process/syscall boundary. The shell and both
language runtimes execute directly in kernel context. This keeps the OS
layer small so the interesting work is in the filesystem and language
implementations - see [`docs/`](docs/) for their designs:

- [`docs/tinyfs.md`](docs/tinyfs.md) - on-disk filesystem format
- [`docs/scripting-language.md`](docs/scripting-language.md) - the `tsh` language
- [`docs/bytecode-isa.md`](docs/bytecode-isa.md) - the compiled language + VM ISA

## Repo layout

```
boot/            stage1 (MBR) + stage2 boot loaders
kernel/          the kernel itself (see architecture diagram above)
kernel/fs/       tinyfs (shared: freestanding in the kernel, native in mkfs_tinyfs)
kernel/lang/     shared lexer + the two language implementations
kernel/shell/    interactive command REPL
tools/           host-side build/test infrastructure (not OS code):
                   mkfs_tinyfs.c   formats + seeds build/disk.img at build time
                   run_tests.sh    headless QEMU test harness
                   qemu_type.py    scripts keystrokes into QEMU via its HMP monitor
tests/           fixtures (*.tsh, *.tc) + tests/expected/ serial-output fixtures
docs/            design docs, listed above
```

## Testing

There's no hardware and no display in CI, so the serial port is the test
oracle throughout: `kernel/selftest.c` runs a boot-time self-test (string
ops, the allocator including coalescing, and a tinyfs create/write/read/
delete roundtrip) and prints `SELFTEST PASS`/`FAIL`.

```
tools/run_tests.sh
```

boots `build/disk.img` headless (`-display none -serial file:...`), waits
for `SELFTEST PASS`, then drives the shell by scripting keystrokes into
QEMU's HMP monitor over a unix socket (`tools/qemu_type.py sendkey ...`)
- the only way to feed the kernel's polled PS/2 driver without real
hardware - and asserts on the resulting serial output for every shell
command, `run hello.tsh`, and `build`+`exec` on `hello.tc`.

## Boot budget

The kernel image is capped at a fixed number of disk sectors (`boot/
stage2.S`'s `KERNEL_SECTORS`, currently 512 = 256KB), read via BIOS
INT13h in bounded chunks (SeaBIOS silently misbehaves on very large
single extended-read requests). `kernel/fs/tinyfs.h`'s
`TINYFS_FS_START_LBA` reserves exactly that much room before the
filesystem region begins. The Makefile fails the build loudly if the
kernel image ever grows past its budget - if you hit that, bump
`KERNEL_SECTORS`, the Makefile's `KERNEL_MAX_SECTORS`, and
`TINYFS_FS_START_LBA` together.