docs: real introductions on index pages and README

README.md

@@ -2,17 +2,36 @@
 
 Autonomous property-based testing for mobile and web apps.
 
+You write rules that must always hold about your app. sanderling explores the app on its own for minutes or hours, performing thousands of taps, swipes, and inputs, and records every step where a rule breaks. No scripted test paths. One TypeScript spec runs against Android, iOS, and web builds of the same app.
+
+```ts
+import { extract, always } from "@sanderling/spec";
+import { defaultActions } from "@sanderling/spec/defaults";
+import { noUncaughtExceptions } from "@sanderling/spec/defaults/properties";
+
+const balance = extract("balance", s =>
+  parseInt(s.ax.find({ testTag: "Balance" })?.text ?? "0", 10));
+
+export const properties = {
+  noUncaughtExceptions,
+  balanceNeverNegative: always(() => balance.current >= 0),
+};
+
+export const actionsRoot = defaultActions;
+```
+
+Every run produces a trace: one JSON line and one screenshot per step. `sanderling replay` opens it in a web UI for stepping through actions, screenshots, property timelines, and violations.
+
 > Alpha. Android, iOS, and web (Chrome driver only). Full scope in the [v0.1.0 roadmap](https://github.com/priyanshujain/sanderling/milestone/1).
 
 ## Docs
 
-- [Getting started](https://priyanshujain.github.io/sanderling/manual/getting-started.html)
-- [Writing specs](https://priyanshujain.github.io/sanderling/manual/writing-specs.html)
-- [`sanderling replay` UI](https://priyanshujain.github.io/sanderling/manual/replay.html)
+- [Introduction](https://priyanshujain.github.io/sanderling/manual/introduction/): what property-based testing is and how sanderling works
+- [Getting started](https://priyanshujain.github.io/sanderling/manual/getting-started/): install and run a first test
+- [Writing specs](https://priyanshujain.github.io/sanderling/manual/writing-specs/): build a real spec from scratch
+- [Spec language reference](https://priyanshujain.github.io/sanderling/manual/spec-language/)
 - Examples: [folio](https://github.com/priyanshujain/sanderling/tree/master/examples/folio) (KMP, Android/iOS/web), [folio-web](https://github.com/priyanshujain/sanderling/tree/master/examples/folio-web) (React + Vite)
-- [Architecture](https://priyanshujain.github.io/sanderling/development/architecture.html)
-
-After a `sanderling test` run, browse traces locally with `sanderling replay`. It opens a web UI for stepping through actions, screenshots, snapshots, residual formulas, and exceptions.
+- [Architecture](https://priyanshujain.github.io/sanderling/development/architecture/) for contributors
 
 ---
 

docs/index.md

@@ -4,16 +4,23 @@ title: Sanderling Manual
 
 # Sanderling Manual
 
-Autonomous property-based testing for mobile/web apps. Specs in TypeScript. Core in Go. Drives the app under test through UIAutomation/XCTest on Android/iOS and CDP on web.
+sanderling tests mobile and web apps by exploring them on its own and checking rules you write. You state properties that must always hold ("a new account starts at zero", "the app never throws"). sanderling drives the app for minutes or hours through thousands of taps, swipes, and inputs, and records every step where a property breaks. One TypeScript spec runs against Android, iOS, and web builds of the same app.
 
-Alpha: Scope of v0.1.0 is tracked in [issue #4](https://github.com/priyanshujain/sanderling/issues/4).
+Alpha: the scope of v0.1.0 is tracked in [issue #4](https://github.com/priyanshujain/sanderling/issues/4).
 
+## Manual
 
-- [Getting started](./manual/getting-started/)
-- [Writing specs](./manual/writing-specs/)
-- [Runs](./manual/runs/)
-- [Replay](./manual/replay/)
-- [CLI reference](./manual/cli/)
+- [Introduction](./manual/introduction/): what property-based testing is and how sanderling works.
+- [Getting started](./manual/getting-started/): install and run a first test against the example app.
+- [Writing specs](./manual/writing-specs/): build a real spec from scratch, one concept at a time.
+- [Spec language reference](./manual/spec-language/): every selector, operator, action, and sampler.
+- [Runs](./manual/runs/): what happens during a run and why runs are long.
+- [Replay](./manual/replay/): the trace browser.
+- [CLI reference](./manual/cli/): every command and flag.
+
+## Development
+
+- [Architecture](./development/architecture/) and [design principles](./development/design-principles/) for contributors.
 
 ---
 

docs/manual/index.md

@@ -4,8 +4,10 @@ title: Manual
 
 # Manual
 
-- [Getting started](./getting-started/)
-- [Writing specs](./writing-specs/)
-- [Spec language reference](./spec-language/)
-- [Runs](./runs/)
-- [CLI reference](./cli/)
+- [Introduction](./introduction/): what property-based testing is and how sanderling works.
+- [Getting started](./getting-started/): install and run a first test against the example app.
+- [Writing specs](./writing-specs/): build a real spec from scratch, one concept at a time.
+- [Spec language reference](./spec-language/): every selector, operator, action, and sampler.
+- [Runs](./runs/): what happens during a run and why runs are long.
+- [Replay](./replay/): the trace browser.
+- [CLI reference](./cli/): every command and flag.