docs: rewrite README.md to reflect current codebase state

README.md

@@ -1,117 +1,218 @@
 # Portable Claude Code
 
-A portable Claude Code launcher you can copy to any Windows computer or flash drive and run without a system-wide install.
+A portable [Claude Code](https://docs.anthropic.com/en/docs/claude-code) launcher you can copy to any Windows, macOS, or Linux computer — or put on a flash drive — and run without a system-wide install.
 
 ## What it does
 
-- Launches [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI with your local filesystem accessible
-- Stores OAuth credentials portably inside the repo's `state/` folder (no registry or system config pollution)
-- On Windows: runs Claude Code inside a bundled QEMU Linux VM (no WSL required)
-- Supports API key mode if you prefer to skip OAuth
+- Launches Claude Code CLI with your project files accessible
+- Stores OAuth credentials portably inside `state/auth/` — no registry writes, no system config files
+- **Windows (default):** runs Claude Code inside a bundled QEMU Linux VM (no WSL required)
+- **Linux / macOS:** runs Claude Code directly on the host with isolated, portable auth state
+- Supports API key mode as an alternative to OAuth
 
 ## Requirements
 
-- **Node.js** — either bundled in `runtime/node/` or installed on the host
-- **Claude Code** — either installed globally (`npm install -g @anthropic-ai/claude-code`) or bundled in `runtime/`
-- **Windows VM mode only**: QEMU runtime (download with `pcoder runtime bootstrap`)
+| Requirement | Notes |
+|---|---|
+| **Node.js** | Bundled in `runtime/node/` or installed on the host |
+| **Claude Code** (`claude`) | Required for host-native mode. Install with `npm install -g @anthropic-ai/claude-code` |
+| **QEMU** *(Windows VM mode only)* | Downloaded automatically by `pcoder runtime bootstrap` |
 
 ## Quick Start
 
-### First time
+### 1 — Initialize (first time only)
 
+**Windows**
 ```bat
-REM 1. Initialize settings (creates state/settings.json)
+REM Create state/settings.json with defaults
 scripts\pcoder setup --init
 
-REM 2. Log in with your Anthropic account (OAuth - credentials stay portable)
+REM Log in with your Anthropic account (credentials stay in state/auth/)
 scripts\pcoder auth login
 
-REM 3. Check everything looks good
+REM Confirm everything is ready
 scripts\pcoder doctor
 ```
 
-### Launch Claude Code
+**Linux / macOS**
+```bash
+# Create state/settings.json with defaults
+scripts/pcoder setup --init
+
+# Log in with your Anthropic account (credentials stay in state/auth/)
+scripts/pcoder auth login
+
+# Confirm everything is ready
+scripts/pcoder doctor
+```
+
+### 2 — Launch Claude Code
 
+**Windows**
 ```bat
-REM Launch in current directory
+REM Launch in the current directory
 scripts\pcoder
 
-REM Launch in a specific project
+REM Launch in a specific project folder
 scripts\pcoder run --project C:\path\to\my-project
 
-REM Pass args directly to claude
+REM Pass extra arguments directly to claude
 scripts\pcoder -- --help
+scripts\pcoder -- --resume
 ```
 
-### API key mode (skip OAuth)
+**Linux / macOS**
+```bash
+# Launch in the current directory
+scripts/pcoder
 
-```bat
-REM Switch to API key mode
-scripts\pcoder setup --claude-auth api
+# Launch in a specific project folder
+scripts/pcoder run --project /path/to/my-project
 
-REM Set your key before launching
-set ANTHROPIC_API_KEY=sk-ant-...
-scripts\pcoder
+# Pass extra arguments directly to claude
+scripts/pcoder -- --help
 ```
 
-## Windows: VM vs Host-Native
+## Windows: VM Mode vs Host-Native Mode
+
+On Windows the default run mode is **`linux-portable`** — Claude Code runs inside a
+self-contained QEMU Linux VM so you do not need WSL or a Windows build of Claude Code.
+
+### VM mode (default on Windows)
 
-By default on Windows, Claude runs inside a bundled portable Linux VM (QEMU). This gives full Linux compatibility without requiring WSL or any host configuration.
+> **Note:** Claude Code runs *inside* the VM — you do not need it installed on the Windows host.
 
-**VM mode (default on Windows)**
 ```bat
-REM Bootstrap the VM runtime first (one-time download)
+REM One-time setup: download QEMU + Ubuntu image (~1 GB)
 scripts\pcoder runtime bootstrap
 
-REM Then just run normally
+REM Run normally after bootstrap
 scripts\pcoder
 ```
 
-**Host-native mode** (if claude is installed directly on Windows)
+### Host-native mode (optional — requires claude installed on Windows)
+
 ```bat
 scripts\pcoder setup --windows-mode host-native
 scripts\pcoder
 ```
 
-## Commands
+> On Linux and macOS, the launcher always uses **host-native** execution with isolated portable
+> auth state — no VM is required.
+
+## Authentication
+
+### OAuth (default)
+
+OAuth credentials are written to `state/auth/claude/host/` and travel with the folder.
+No credentials are stored in system directories.
+
+```bat
+REM Open browser for OAuth
+scripts\pcoder auth login
+REM Show current auth state
+scripts\pcoder auth status
+REM Remove stored credentials
+scripts\pcoder auth logout
+```
+
+### API key mode
+
+```bat
+REM Switch to API key mode
+scripts\pcoder setup --claude-auth api
+
+REM Set your key each session before launching
+set ANTHROPIC_API_KEY=sk-ant-...
+scripts\pcoder
+```
+
+On Linux / macOS:
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+scripts/pcoder
+```
+
+> `ANTHROPIC_AUTH_TOKEN` is also accepted as an alias for `ANTHROPIC_API_KEY`.
+
+## All Commands
 
 | Command | Description |
 |---|---|
-| `pcoder` | Launch Claude Code in current directory |
+| `pcoder` | Launch Claude Code in the current directory |
+| `pcoder [-- <claude args>]` | Launch and pass extra args directly to claude |
 | `pcoder doctor` | Check environment health |
-| `pcoder setup --init` | Initialize settings |
-| `pcoder setup --show` | Show current settings |
-| `pcoder setup --claude-auth <oauth|api>` | Change auth mode |
-| `pcoder setup --windows-mode <linux-portable|host-native>` | Change Windows run mode |
-| `pcoder auth status` | Show auth status |
+| `pcoder setup --init` | Initialize `state/settings.json` with defaults |
+| `pcoder setup --show` | Print current settings |
+| `pcoder setup --claude-auth <oauth\|api>` | Change authentication mode |
+| `pcoder setup --windows-mode <linux-portable\|host-native>` | Change Windows run mode |
+| `pcoder setup --sync-back <true\|false>` | Control whether VM files sync back after a run |
+| `pcoder auth status` | Show authentication status |
 | `pcoder auth login` | Log in via OAuth |
-| `pcoder auth logout` | Log out |
-| `pcoder runtime probe` | Show available runtimes |
-| `pcoder runtime bootstrap` | Download Windows VM runtime (QEMU + Ubuntu) |
-| `pcoder run [--project <path>] [--mode <mode>] [-- <claude args>]` | Run with options |
+| `pcoder auth logout` | Log out and clear stored credentials |
+| `pcoder runtime probe` | Show available runtime backends |
+| `pcoder runtime bootstrap [--force]` | Download Windows VM runtime (QEMU + Ubuntu) |
+| `pcoder run [--project <path>]` | Run in a specific project directory |
+| `pcoder run [--mode <linux-portable\|host-native>]` | Override run mode for one session |
+| `pcoder run [--no-sync-back]` | Skip syncing VM files back after this run |
+| `pcoder run [-- <claude args>]` | Pass extra arguments directly to claude |
 
 ## File Layout
 
 ```
 PortableCoder/
   scripts/
-    pcoder.cmd       <- Windows launcher (double-click or run from cmd)
-    pcoder           <- Linux/macOS launcher
-    pcoder.cjs       <- Main launcher logic (Node.js)
-    runtime/windows/ <- Windows VM helper scripts
-  runtime/
-    node/            <- (optional) bundled Node.js
-    linux/           <- VM image and SSH key (after bootstrap)
-    qemu/            <- QEMU binaries (after bootstrap)
-  state/
-    settings.json    <- Your settings (auto-created)
-    auth/            <- Portable OAuth credentials (stays with the drive)
-profiles/
-    profiles.json    <- Anthropic profile config
+    pcoder.cmd              <- Windows entry point (run from cmd.exe or double-click)
+    pcoder                  <- Linux / macOS entry point
+    pcoder.cjs              <- Main launcher logic (Node.js, cross-platform)
+    adapters/
+      catalog.json          <- Tool adapter definitions (claude, pwsh, …)
+    runtime/
+      windows/              <- Windows VM helper scripts (bootstrap, start, stop, smoke-check)
+      linux/
+        smoke-check.sh      <- Linux smoke test
+  runtime/                  <- Runtime binaries (large files, not committed to git)
+    node/                   <- (optional) bundled portable Node.js
+    qemu/                   <- QEMU binaries (populated by `runtime bootstrap`)
+    linux/
+      images/               <- Ubuntu VM image (populated by `runtime bootstrap`)
+      ssh/                  <- Generated SSH keypair for VM access
+      vm-manifest.json      <- VM configuration (backend, image path, acceleration policy)
+      cloud-init/           <- Cloud-init configuration for first-boot VM provisioning
+  state/                    <- Runtime state (gitignored, travels with the folder)
+    settings.json           <- Your settings (created by `setup --init`)
+    auth/
+      claude/host/          <- Portable OAuth credentials
+    vm/                     <- VM runtime state (PID, SSH port, logs)
+    tmp/                    <- Temporary working files
+  profiles/
+    profiles.json           <- Environment profile definitions
+    defaults/               <- Default secrets policy documentation
+    local/                  <- Local .env overrides (gitignored)
+  apps/                     <- (reserved) local app bundles
 ```
 
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | API key (api auth mode) |
+| `ANTHROPIC_AUTH_TOKEN` | Alias for `ANTHROPIC_API_KEY` |
+| `ANTHROPIC_BASE_URL` | Override the Anthropic API base URL |
+| `PCODER_CLAUDE_CMD` | Override the path/command used to run claude |
+| `PCODER_VM_SSH_TIMEOUT_SECONDS` | Max seconds to wait for VM SSH (default: 300) |
+| `PCODER_VM_HOST` | VM SSH hostname (default: `127.0.0.1`) |
+| `PCODER_VM_USER` | VM SSH username (default: `portable`) |
+| `PCODER_VM_SSH_KEY` | Path to VM SSH private key |
+| `PCODER_VM_PROJECTS_ROOT` | Remote path for synced projects (default: `/home/portable/projects`) |
+| `PCODER_SSH_CMD` | Override SSH client path |
+| `PCODER_SCP_CMD` | Override SCP client path |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Proxy settings forwarded into the VM |
+
 ## Portability Notes
 
-- Copy the entire `PortableCoder/` folder to a flash drive or another machine and it works
-- OAuth credentials are stored in `state/auth/` so they travel with the folder
-- No registry writes, no system PATH changes, no admin rights required (VM mode may need Hyper-V or software TCG fallback)
+- Copy the entire `PortableCoder/` folder to a flash drive or new machine and it works
+- OAuth credentials live in `state/auth/` and travel with the folder
+- No registry writes, no system PATH changes, no admin rights required
+- Windows VM mode may use Hyper-V hardware acceleration (WHPX) when available, and automatically falls back to software emulation (TCG) if not
+- Settings are stored in `state/settings.json` (gitignored so your personal config never gets committed)