Refresh README and docs for recent changes

README
- List the 213 syscalls, guest-internal FUSE, sysv-ipc, GDB stub, MAP_SHARED
  overlay, APFS fclonefileat CoW, case-fold sidecar).
- Tighten Limitations

usage.md
- Document --no-rosetta, --create-sysroot, and the --gdb rejection
  for x86_64 guests.
- Add worked examples (interactive bash via sysroot, jq against a
  host JSON file, sqlite3 against a host db, x86_64 binary).

testing.md
- Expand the make check description to its real stages (coverage
  check, TLBI encoder, proctitle, busybox, sysroot-procfs, FUSE,
  timeout=0, rosetta-cli, hot-syscall guardrail).

internals.md
- Add Lifecycle In Five Steps (load -> boot -> run -> translate ->
  return) so readers get a mental model before the deep dives.
- Rewrite MAP_SHARED notes. Previous text claimed MAP_SHARED is
  treated as MAP_PRIVATE; src/syscall/mem.c installs real host
  MAP_FIXED|MAP_SHARED overlays for aligned file-backed mappings and
  promotes MAP_SHARED|MAP_ANONYMOUS to memfd-style overlays across
  fork.
- Extend the TLBI wire encoding with X8 == 4 / TLBI_RANGE_LARGE
  (single-shot TLBI RVAE1IS for 17..64 pages via FEAT_TLBIRANGE) and
  the X11 icache-flush hint (set on W^X transitions to executable).
  Same updates in the HVC #5 row of the protocol table.
- Rewrite the X8 == 2 description as the generic drop-saved-frame
  marker. signal_deliver() also sets X8 = 2 on the syscall-return
  path (src/syscall/signal.c), not just execve / rt_sigreturn.
- Correct the stack-alignment arithmetic against
  src/core/stack.c . The 35 covers 30 base auxv words + AT_NULL +
  envp/argv nulls + argc; extra starts at 4 for the always-present
  AT_EXECFN + AT_BASE.
- Document the x86_64 path including both static and dynamic via
  --sysroot.
- Add a Guest-Internal FUSE section. Source map gains rosetta.c,
  sysroot.c, path.c, sidecar.c, fuse.c, inotify.c, sysvipc.c,
  shim-globals.c, vdso.c, proctitle.c, plus the split net files.
- Normalize memory-layout hex padding to 8-digit for within-32-bit
  values and 12-digit for above-32-bit values.

Author: jserv

README.md

@@ -1,24 +1,49 @@
 # elfuse
 
-`elfuse` runs aarch64-linux ELF binaries on macOS Apple Silicon through
-Apple's Hypervisor.framework. It is a process-scoped Linux user-space runtime:
-guest code executes on the CPU inside a lightweight VM, while Linux syscalls
-are intercepted and translated to macOS behavior in host-side handlers.
-
-This is not a container engine and not a general-purpose Linux kernel. It is a
-focused compatibility layer for running Linux user-space workloads directly from
-the macOS shell, with support for static binaries, dynamic loaders via
-`--sysroot`, guest threads, process management, signals, `/proc` emulation, and
-guest debugging through a built-in GDB RSP stub.
-
-## Highlights
-
+Run Linux ELF binaries directly from the macOS shell -- no Docker, no
+full VM image, no daemon. `elfuse` is a process-scoped Linux user-space
+runtime: each guest runs inside a lightweight Hypervisor.framework VM
+owned by the `elfuse` process itself, and Linux syscalls are translated
+to macOS behavior in host-side handlers rather than served by a real
+Linux kernel.
+
+Native aarch64-linux executes directly on the CPU. x86_64-linux
+executes through Apple's embedded Rosetta translator hosted inside the
+same VM; the architecture is auto-detected from the ELF header. Both
+static and dynamically linked guests are supported, with the dynamic
+linker resolved against an external sysroot via `--sysroot`.
+
+## Features
+
+- Single native macOS binary (~560 KiB signed), no daemon and no disk
+  image
+- Millisecond-scale VM startup; per-syscall overhead is microseconds
 - Native Apple Silicon execution through Hypervisor.framework
 - Static and dynamically linked `aarch64-linux` ELF binaries
-- Linux-style processes, threads, signals, timers, futexes, and polling
+- Static and dynamically linked `x86_64-linux` ELF binaries via Apple
+  Rosetta (auto-detected from the ELF header, opt out with
+  `--no-rosetta`)
+- Linux-style processes, threads (1:1 with HVF vCPUs, up to 64),
+  signals, timers, futexes (incl. PI ops), and polling
+- Guest reads and writes the macOS filesystem directly; no overlay or
+  volume mount layer
 - Synthetic `/proc` and selected `/dev` emulation for user-space probes
+- Guest-internal FUSE: `/dev/fuse` and `mount("fuse")` work without
+  macFUSE / FUSE-T / FSKit
 - Built-in GDB Remote Serial Protocol stub usable from `gdb` or `lldb`
 - Self-contained test matrix that cross-checks elfuse against QEMU
+  and exercises a separate Rosetta acceptance suite
+
+## Positioning
+
+`elfuse` is intentionally narrow. It runs single Linux binaries (and
+their `fork`/`exec` children) with minimal overhead; it does not host a
+Linux kernel, namespaces, cgroups, or kernel modules. For workloads
+that need full kernel features, container orchestration, or systemd,
+prefer a full VM tool (Lima, UTM, OrbStack) or Docker Desktop. For
+single-binary tooling, language runtimes, test harnesses, and
+debugger-driven workflows, `elfuse` removes the disk-image and
+boot-time overhead those tools impose.
 
 ## Requirements
 
@@ -48,33 +73,46 @@ make elfuse
 make test-busybox
 build/elfuse build/busybox
 ```
-Replace `build/busybox` with Arm64/Linux executable files.
+Replace `build/busybox` with an aarch64-linux or x86_64-linux executable.
+The guest architecture is auto-detected from the ELF header.
 
 For dynamically linked guests:
 
 ```sh
 build/elfuse --sysroot /path/to/sysroot ./path/to/program
 ```
 
+For x86_64-linux guests, Rosetta is on by default. To disable:
+
+```sh
+build/elfuse --no-rosetta ./path/to/aarch64-only-binary
+```
+
 For early debugging:
 
 ```sh
 build/elfuse --gdb 1234 --gdb-stop-on-entry ./path/to/program
 ```
 
+`--gdb` is rejected for x86_64 guests because the stub serves the
+aarch64 view Rosetta produces, not the original x86_64 architectural
+state.
+
 The build signs `build/elfuse` before use. Override the signing identity with
 `SIGN_IDENTITY="Developer ID ..."` when needed.
 
 ## Documentation
 
-- [docs/usage.md](docs/usage.md): command-line options, dynamic linking via
-  `--sysroot`, and attaching `gdb` / `lldb` to the built-in stub.
-- [docs/testing.md](docs/testing.md): build prerequisites, the `make check`
-  flow, the QEMU cross-check matrix, and fixture handling.
-- [docs/internals.md](docs/internals.md): canonical technical reference --
-  HVF constraints, EL1 shim and HVC protocol, page-table splitting, syscall
-  translation tables, threads/futex, fork/clone IPC, signals, ptrace, and
-  the GDB stub.
+- [docs/usage.md](docs/usage.md): command-line options, x86_64 via
+  Rosetta, dynamic linking via `--sysroot`, and attaching `gdb` /
+  `lldb` to the built-in stub.
+- [docs/testing.md](docs/testing.md): build prerequisites, the
+  `make check` flow, the QEMU and Rosetta cross-check matrices, and
+  fixture handling.
+- [docs/internals.md](docs/internals.md): canonical technical
+  reference -- runtime lifecycle, HVF constraints, EL1 shim and HVC
+  protocol, page-table splitting, syscall translation tables, threads
+  / futex, fork / clone IPC, signals, ptrace, and the GDB stub.
 
 ## Build And Validation
 
@@ -90,30 +128,35 @@ make lint          # clang-tidy
 
 `make check` is the recommended pre-commit gate. `make test-matrix` is the
 recommended gate for changes touching procfs, dynamic linking, networking,
-or process semantics. See [docs/testing.md](docs/testing.md) for the full
+or process semantics. `make test-rosetta-all` covers the x86_64 acceptance
+suites in isolation. See [docs/testing.md](docs/testing.md) for the full
 target list, fixture flow, and validation-by-change-type guidance.
 
-## Scope And Limitations
-
-`elfuse` targets pragmatic Linux user-space compatibility. Supported areas
-include ELF and dynamic-loader bootstrap, sysroot-aware path translation,
-Linux-style FD semantics, `fork` / `clone` / `execve` / `wait*` / ptrace,
-signals and timers, polling families (`epoll`, `eventfd`, `signalfd`,
-`timerfd`, `inotify`), sockets and netlink, and synthetic `/proc`, `/dev`,
-and `/proc/net/*` views sufficient for tools such as BusyBox `ps`, `uptime`,
-and `top`.
-
-Boundaries to be aware of:
-
-- The target is Linux user-space ABI compatibility, not kernel
-  virtualization. `/proc`, `/dev`, and mount data are compatibility views.
-- HVF allows one VM per host process, so Linux-style `fork` is implemented
-  via `posix_spawn` plus state transfer (a fast CoW path is used when
-  available -- see [docs/internals.md](docs/internals.md)).
-- `MAP_SHARED` is treated as `MAP_PRIVATE`; this matches single-process
-  guest semantics and unblocks tools that expect file-backed mappings.
-- Unsupported syscalls return Linux-style errors rather than silently
+## Limitations
+
+`elfuse` runs single Linux user-space processes (and their `fork` /
+`exec` children). It is not a Linux kernel.
+That framing shapes both what it does and what it explicitly will not
+do.
+- Linux kernel features that have no user-space-syscall analog:
+  namespaces, cgroups, kernel modules, eBPF, `io_uring`, KVM, perf
+  events.
+- Intel Macs. Apple Silicon only (M1 and later).
+- Hosting a VM from inside a guest. The guest cannot use HVF or KVM.
+- One guest process tree per `elfuse` host process. HVF allows one VM
+  per host process; Linux-style `fork` is implemented by
+  `posix_spawn`-ing a fresh `elfuse` host process and transferring
+  state (see [docs/internals.md](docs/internals.md)).
+- Up to 64 concurrent guest threads per VM (`MAX_THREADS = 64`).
+- Around 213 syscalls implemented; anything outside
+  `src/syscall/dispatch.tbl` returns `-ENOSYS` rather than silently
   succeeding.
+- `FUTEX_LOCK_PI` and friends behave as plain mutex acquire / release;
+  true priority-inheritance scheduling is not modeled.
+- `sched_setaffinity` is honored as a no-op (returns the all-CPUs
+  mask); the host scheduler picks the actual CPU.
+- `/proc`, `/dev`, and mount data are synthetic compatibility views,
+  not host pass-throughs.
 
 ## License