Update docs for dual networking model and new packages

Documentation was out of date with the current codebase. Key updates:

- Document runner-side (default) vs hosted networking modes
- Add net/hosted and net/topology packages to all doc surfaces
- Document ImageFetcher interface and fetcher implementations
- Document Spawner/ProcessHandle runner interfaces
- Add missing options to README (WithRootFSPath, WithImageFetcher,
  WithSpawner, WithPreflightChecker)
- Update SECURITY.md trust boundary and blast radius for both modes
- Update net.Config docs to include FirewallRules/DefaultAction fields

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: JAORMX

CLAUDE.md

@@ -21,15 +21,17 @@ Run a single test: `go test -v -race -run TestName ./path/to/package`
 
 ## Architecture
 
-- `propolis.go` -- Entry point: `Run()` orchestrates a 7-step pipeline (pull, extract, hooks, config, net, spawn, boot)
+- `propolis.go` -- Entry point: `Run()` orchestrates the pipeline (preflight, pull, hooks, config, net, spawn, post-boot)
 - `options.go` -- All `With*` option constructors, `config` struct, `defaultConfig()`
 - `vm.go` -- `VM` type returned by `Run()` with `Stop`, `Status`, `Remove`
-- `image/` -- OCI pull via crane, layer flattening, content-addressable cache by manifest digest
-- `runner/` -- `Spawn()` launches detached propolis-runner subprocess via setsid
-- `runner/cmd/propolis-runner/` -- CGO binary: calls `krun.StartEnter`, never returns
+- `image/` -- OCI pull via `ImageFetcher` interface (daemon then remote fallback), layer flattening, content-addressable cache
+- `runner/` -- `Spawner`/`ProcessHandle` interfaces, launches detached propolis-runner subprocess via setsid
+- `runner/cmd/propolis-runner/` -- CGO binary: calls `krun.StartEnter`, never returns; creates in-process VirtualNetwork by default
 - `krun/` -- CGO bindings to libkrun C API
-- `net/` -- `Provider` interface; default in-process VirtualNetwork (gvisor-tap-vsock)
+- `net/` -- `Provider` interface for custom networking backends
 - `net/firewall/` -- Frame-level packet filtering, connection tracking, relay
+- `net/hosted/` -- Hosted `net.Provider` running VirtualNetwork in caller's process with HTTP services on gateway IP
+- `net/topology/` -- Shared network topology constants (subnet, gateway, guest IP, MTU)
 - `preflight/` -- `Checker` interface, platform-specific checks via build tags
 - `ssh/` -- ECDSA P-256 keygen and SSH client for guest communication
 - `state/` -- flock-based atomic JSON state persistence
@@ -80,6 +82,6 @@ When tests fail, fix the implementation, not the tests.
 
 - @docs/ARCHITECTURE.md -- Deep technical architecture
 - @docs/SECURITY.md -- Trust boundaries, guest escape analysis, hardening
-- @docs/NETWORKING.md -- In-process networking, firewall, wire protocol
+- @docs/NETWORKING.md -- Networking modes (runner-side, hosted), firewall, wire protocol
 - @docs/MACOS.md -- macOS support, code signing, Hypervisor.framework
 - @docs/TROUBLESHOOTING.md -- Common issues, log files, resource limits

README.md

@@ -264,29 +264,35 @@ func main() {
 | `WithMemory(mib)` | RAM in MiB | `512` |
 | `WithPorts(...)` | TCP port forwards from host to guest | none |
 | `WithInitOverride(cmd...)` | Replace OCI ENTRYPOINT/CMD | OCI config |
+| `WithRootFSPath(path)` | Use pre-built rootfs directory, skip OCI image pull | none |
 | `WithRootFSHook(...)` | Modify rootfs before boot | none |
 | `WithPostBoot(...)` | Run logic after VM process starts | none |
-| `WithNetProvider(p)` | Replace default in-process networking | in-process vnet |
+| `WithNetProvider(p)` | Replace default runner-side networking with a custom provider | runner-side vnet |
 | `WithFirewallRules(...)` | Firewall rules for frame-level packet filtering | none |
 | `WithFirewallDefaultAction(action)` | Default firewall action when no rule matches | `Allow` |
+| `WithPreflightChecker(c)` | Replace entire preflight checker | platform defaults |
 | `WithPreflightChecks(...)` | Add custom pre-boot checks | KVM + resources |
 | `WithVirtioFS(...)` | Host directory mounts via virtio-fs | none |
 | `WithDataDir(p)` | State, cache, and log directory | `~/.config/propolis` |
 | `WithRunnerPath(p)` | Path to propolis-runner binary | auto-detect |
 | `WithLibDir(p)` | Directory for libkrun/libkrunfw shared libraries | system libs |
 | `WithImageCache(c)` | Custom image cache instance | `$dataDir/cache/` |
+| `WithImageFetcher(f)` | Custom image fetcher for OCI retrieval | local-then-remote |
+| `WithSpawner(s)` | Custom runner subprocess spawner | `DefaultSpawner` |
 
 ## Package Overview
 
 | Package | CGO? | Description |
 |---------|------|-------------|
 | `propolis` (root) | No | Top-level API: `Run()`, `VM` type, functional options, hook types |
-| `image` | No | OCI image pull via crane, layer flattening, rootfs extraction, `KrunConfig` |
+| `image` | No | OCI image pull via `ImageFetcher`, layer flattening, rootfs extraction, `KrunConfig` |
 | `krun` | **Yes** | CGO bindings to libkrun C API (context, VM config, `StartEnter`) |
 | `net` | No | `Provider` interface and `Config`/`PortForward` types |
 | `net/firewall` | No | Frame-level packet filtering with stateful connection tracking |
+| `net/hosted` | No | Hosted `net.Provider` running VirtualNetwork in caller's process with HTTP services |
+| `net/topology` | No | Shared network topology constants (subnet, gateway, IPs, MTU) |
 | `preflight` | No | `Checker` interface, `Check` struct, built-in KVM/HVF and port checks |
-| `runner` | No | `Spawn()` / `Process` for managing the propolis-runner subprocess |
+| `runner` | No | `Spawner` / `ProcessHandle` interfaces for managing the propolis-runner subprocess |
 | `runner/cmd/propolis-runner` | **Yes** | The runner binary (calls `krun.StartEnter`, never returns) |
 | `ssh` | No | ECDSA key generation and SSH client for guest communication |
 | `state` | No | flock-based state persistence with atomic JSON writes |
@@ -400,13 +406,14 @@ Go runtime.
 +-------------------+                      +-------------------+
 ```
 
-The in-process VirtualNetwork (gvisor-tap-vsock) provides a virtual network
-(192.168.127.0/24), DHCP, DNS, and TCP port forwarding between host and guest.
-It communicates with the VM over a Unix domain socket using the QEMU transport
-(SOCK_STREAM with 4-byte big-endian length-prefixed Ethernet frames). An
-optional frame-level firewall with stateful connection tracking can be enabled
-via `WithFirewallRules()`. See [docs/NETWORKING.md](docs/NETWORKING.md) for
-a deep dive.
+By default, the runner creates an in-process VirtualNetwork (gvisor-tap-vsock)
+providing a virtual network (192.168.127.0/24), DHCP, DNS, and TCP port
+forwarding. For advanced use cases, `WithNetProvider()` moves the network stack
+to the caller's process -- the `net/hosted` package provides a ready-made
+provider that also supports HTTP services on the gateway IP. An optional
+frame-level firewall with stateful connection tracking can be enabled via
+`WithFirewallRules()`. See [docs/NETWORKING.md](docs/NETWORKING.md) for a
+deep dive.
 
 ### Extension Points