docs update with case study (#63)

* docs(manual): add introduction page

* docs(manual): rewrite getting started as guided first run

* docs(manual): rewrite writing specs as a folio tutorial

* docs(manual): document missing spec API in reference

* docs(manual): plain-language rewrite of runs page

* docs: real introductions on index pages and README

* fix(docs): sibling links from directory-style pages need ../

* fix(docs): correct sampling and restart-cost claims to match implementation

* docs: nav lists Introduction and Case study; roadmap points to milestone

* docs(manual): make getting started target the reader's own app, not Folio

* docs(manual): add Folio case study page

* docs: point manual navigation at the case study

* docs(readme): lead with the case study, fix roadmap link

* docs: roadmap links to milestone, sync clear-data default and cross-links

docs/manual/getting-started.md

@@ -4,109 +4,62 @@ title: Getting started
 
 # Getting started
 
-Install the CLI, run a spec.
-
-## Prerequisites
-
-**Android / iOS:**
-
-- An Android emulator with API level 30 or newer (or a connected device).
-- `adb` on your PATH.
-
-**Web:**
-
-- Chrome installed. sanderling drives it via CDP; no other setup required.
-
-Run `sanderling doctor` to check the host environment.
+Install sanderling, write a spec for your app, run it, and open the trace.
 
 ## Install
 
-### CLI
+The CLI:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/priyanshujain/sanderling/master/install.sh | bash
 ```
 
-### Spec package ([npm](https://www.npmjs.com/package/@sanderling/spec))
+The spec package, in your project:
 
 ```sh
 npm install --save-dev @sanderling/spec
 ```
 
-## Your first run
-
-The repo ships two sample apps. `examples/folio` is a Kotlin Multiplatform personal-ledger app that covers Android, iOS, and web (wasmJs) from one shared codebase. `examples/folio-web` is a smaller React + Vite app that covers only the web path. Both carry a TypeScript spec under `sanderling/spec.ts`. Install `just`, then pick a target below.
-
-### Android
-
-From `examples/folio`:
+## Check your environment
 
 ```sh
-just install   # build and install the folio APK on a booted emulator or device
-just test      # run the spec
+sanderling doctor
 ```
 
-With no device connected and multiple AVDs, pick one:
+`doctor` reports what the target platform needs and what is missing:
+
+- **Android**: `adb` on your PATH, and an emulator (API 30 or newer) or a connected device.
+- **iOS**: Xcode 16 or newer, with a simulator. For a connected iPhone, run `sanderling doctor --platform ios-device`.
+- **Web**: Chrome.
+
+## Write a spec
+
+A spec exports two things: `properties` that must always hold, and `actionsRoot`, the actions sanderling may take. The smallest spec that does something useful imports both from the defaults:
+
+```ts
+import { defaultActions } from "@sanderling/spec/defaults";
+import { noUncaughtExceptions } from "@sanderling/spec/defaults/properties";
+
+export const properties = { noUncaughtExceptions };
+export const actionsRoot = defaultActions;
+```
+
+This taps, types, scrolls, and swipes at random, and fails the moment your app throws an uncaught exception. From here you add extractors to read your screens, properties that state what your app guarantees, and actions that drive its real flows. The [case study](../case-study/) walks a complete spec, and the [spec language reference](../spec-language/) lists every primitive.
+
+## Run it
+
+Point sanderling at your app:
 
 ```sh
-AVD=Pixel_7 just test
+sanderling test --spec spec.ts --bundle-id com.example.app --platform android
 ```
 
-Persistent settings can live in a `.env` alongside the justfile (`AVD=Pixel_7`, `DURATION=5m`, and so on).
+Use `--platform ios` or `--platform web` for the other targets. By default a run lasts five minutes and starts from a fresh install; `--clear-data=false` resumes prior state, and `--duration 30m` runs longer. The [CLI reference](../cli/) lists every flag.
 
-### iOS
-
-From `examples/folio` (requires Xcode 16+ and `xcodegen`):
+## See what it found
 
 ```sh
-just test-ios                          # default simulator: iPhone 17 Pro
-IOS_DEVICE="iPhone 15" just test-ios   # pick a different simulator
+sanderling replay
 ```
 
-`just test-ios` boots the simulator if needed, builds and installs the app, then runs `sanderling test --platform ios`.
-
-#### Physical device
-
-A connected iPhone is driven over a usbmux tunnel by a runner the driver builds and signs at run time. The tunnel talks to macOS's own `usbmuxd`, so nothing extra is installed beyond Xcode. It needs App Store Connect signing credentials in the environment (a gitignored `.env` is loaded by `just`):
-
-```sh
-SANDERLING_IOS_TEAM=<10-char team id>
-ASC_API_KEY_ID=<key id>
-ASC_API_ISSUER_ID=<issuer id>
-ASC_API_KEY_PATH=<absolute path to AuthKey_*.p8>
-
-IOS_DEVICE="iPhone" just test-ios-device   # name, UDID, or CoreDevice id
-```
-
-Run `sanderling doctor --platform ios-device` to check `devicectl`, the `usbmuxd` socket, a connected and paired device, and the signing credentials before a run.
-
-### Web
-
-From either example. For the KMP wasmJs build, use `examples/folio`:
-
-```sh
-just web       # serve the wasmJs app on a webpack dev server
-```
-
-For the React + Vite build, use `examples/folio-web`:
-
-```sh
-just test      # starts the Vite dev server, then sanderling drives Chrome via CDP
-```
-
-No emulator or SDK setup needed for either web path.
-
-### Trace output
-
-When the run ends, the trace lands in `sanderling/runs/<timestamp>/`:
-
-```
-runs/2026-04-18T12-34-56/
-├── trace.jsonl
-├── screenshots/
-└── meta.json
-```
-
-Browse it with `sanderling replay` (see [replay](./replay/)), or read `trace.jsonl` step by step.
-
-Next: [writing specs](./writing-specs/).
+This opens the trace in a local web UI. Step through with `j` and `k`; press `.` to jump to a property violation and see the screenshot, the action, and the failed formula at that step. The [replay page](../replay/) covers the panels and shortcuts.