docs+install: post-rename docs polish, install script, d2 architecture diagram (#26)

* docs: add sanderling bird artwork to README and docs index

* chore: add one-line install script for macOS and Linux

Detects os/arch, resolves latest (or pre-)release, verifies sha256,
and installs the binary into $HOME/.sanderling/bin.

* docs: use the one-line installer in getting-started

Replaces the broken `<version>` placeholder snippets with the
install.sh one-liner.

* docs: drop filler line under the install one-liner

* docs: rename index heading to Sanderling Manual

* docs(style): adopt JetBrains Mono and uppercase brand mark

* docs(getting-started): use justfile flow for folio sample

* docs(writing-specs): drop 'coming soon' notes for eventually and implies

* docs(inspect): rewrite layout for tabbed state panels and metrics chart

* docs(inspect): add UI screenshot

* docs: add Inspect to sidebar and index

* docs: restore mermaid bootstrap script in page template

* docs(style): constrain article images to content width

* docs(inspect): drop layout prose, keep what the screenshot doesn't show

* docs(architecture): add d2 source for architecture diagram

Replaces the in-page mermaid block with a d2-rendered SVG. Generated
outputs (svg/png) stay out of git; only the .d2 source is checked in.

* build(docs): render d2 diagrams into build/site/_assets/diagrams

* docs(architecture): swap mermaid block for rendered d2 svg

* ci(docs): install d2 before building the site

* docs(architecture): tighten layout and reroute label-crossing edges

Flip device/sidecar order so trace writer drops cleanly to runs/
without cutting through the JVM cell, right-align the inspect row
via a pad column, and tune grid gaps to keep gRPC and Unix socket
labels off the SANDERLING boundary.

docs/manual/getting-started.md

@@ -18,22 +18,10 @@ Run `sanderling doctor` to check the host environment.
 
 ### CLI
 
-macOS arm64:
-
 ```sh
-curl -L https://github.com/priyanshujain/sanderling/releases/latest/download/sanderling_<version>_darwin_arm64.tar.gz | tar xz
-./sanderling version
+curl -fsSL https://raw.githubusercontent.com/priyanshujain/sanderling/master/install.sh | bash
 ```
 
-Linux amd64:
-
-```sh
-curl -L https://github.com/priyanshujain/sanderling/releases/latest/download/sanderling_<version>_linux_amd64.tar.gz | tar xz
-./sanderling version
-```
-
-Pre-built for `darwin/arm64`, `darwin/amd64`, `linux/amd64`, `linux/arm64`.
-
 ### Spec package (npm)
 
 ```sh
@@ -50,21 +38,22 @@ dependencies {
 
 ## Your first run
 
-The repo ships a working sample at `examples/folio`. From that directory:
+The repo ships a working sample at `examples/folio`, a Kotlin Multiplatform app with a TypeScript spec under `sanderling/spec.ts`. Install `just`, then from `examples/folio`:
 
 ```sh
-npm install
-(cd android && ./gradlew installDebug)
-sanderling test \
-  --spec spec.ts \
-  --bundle-id app.folio \
-  --platform android \
-  --duration 2m
+just install   # build and install the folio APK on a booted emulator or device
+just test      # run the spec
 ```
 
-Pass `--avd <name>` only when no device is connected and you have multiple AVDs; otherwise sanderling uses the connected device or boots the single AVD it finds.
+With no device connected and multiple AVDs, pick one:
 
-When the run ends, the trace lands in `runs/<timestamp>/`:
+```sh
+AVD=Pixel_7 just test
+```
+
+Persistent settings can live in a `.env` alongside the justfile (`AVD=Pixel_7`, `DURATION=5m`, and so on).
+
+When the run ends, the trace lands in `sanderling/runs/<timestamp>/`:
 
 ```
 runs/2026-04-18T12-34-56/
@@ -73,6 +62,6 @@ runs/2026-04-18T12-34-56/
 └── meta.json
 ```
 
-Open the screenshots directory to scrub visually, or read `trace.jsonl` step by step.
+Browse it with `sanderling inspect` (see [inspect](./inspect.html)), or read `trace.jsonl` step by step.
 
 Next: [writing specs](./writing-specs.html).

docs/manual/inspect.md

@@ -4,24 +4,15 @@ title: sanderling inspect
 
 # sanderling inspect
 
-`sanderling inspect` is a local web UI for exploring runs produced by `sanderling test`. It reads `runs/<id>/meta.json` and `runs/<id>/trace.jsonl` and renders each step with its action, screenshot, snapshots, residual formulas, and exceptions.
+Local web UI for exploring runs produced by `sanderling test`. Reads `runs/<id>/meta.json` and `runs/<id>/trace.jsonl` from disk.
 
 ```
 sanderling inspect [run-or-runs-dir] [--port N] [--no-open] [--dev]
 ```
 
-The positional argument can be either a runs directory or a single run directory (auto-detected by the presence of `meta.json`). When omitted, it defaults to `./runs`.
+The positional argument can be a runs directory or a single run directory (auto-detected by `meta.json`). Defaults to `./runs`.
 
-## Layout
-
-The detail page uses a phone-dominant grid:
-
-- **Actions** (left): vertical step list. Steps with violations are marked with a red dot; steps with exceptions have a dashed-outline marker.
-- **Screenshot** (center): the device screenshot for the current step. The runner's resolved tap target is overlaid as a red rectangle, the tap point as an outlined circle. Swipes show an arrow from start to end.
-- **Snapshots** (top right): the current step's snapshots flattened into dotted-path rows. Values that changed since the previous step are highlighted; hover to see the previous value.
-- **Properties** (middle right): one row per property with status (violated / pending / holds) and an expandable residual formula.
-- **Exceptions** (bottom right): SDK-captured uncaught throwables. Stack traces expand inline.
-- **Timeline** (bottom): per-property swimlane across all steps; click a cell to seek.
+![sanderling inspect](../_assets/inspect-ui.png)
 
 ## Keyboard shortcuts
 
@@ -31,31 +22,28 @@ The detail page uses a phone-dominant grid:
 | `k`, `Left` | Previous step |
 | `Shift+j`, `Shift+Right` | Jump 10 forward |
 | `Shift+k`, `Shift+Left` | Jump 10 back |
-| `g` | First step |
-| `G` | Last step |
+| `g` / `G` | First / last step |
 | `.` | Next step with a violation |
 
-## URLs
+Arrow keys inside a tablist or listbox yield to those widgets. Use `j`/`k` when focus is on one.
 
-- `/` — run index (auto-refreshes via SSE when new runs land)
-- `/runs/:id` — redirects to step 1
-- `/runs/:id/steps/:n` — direct deep link
+## Deep links
 
-## Theme
+`/runs/:id/steps/:n` links to a specific step. Use it in issues or PRs when pointing at a violation.
 
-Defaults to the system color scheme via `prefers-color-scheme`. The `light`/`dark` button in the toolbar toggles a manual override stored in `localStorage`.
+The run index auto-refreshes over SSE as new runs land, so `sanderling inspect` and `sanderling test` can run side by side.
 
 ## Development
 
-Two-process loop:
+Two-process loop while iterating on the UI:
 
 ```
-make web-dev      # bun + vite, http://127.0.0.1:5173
+make web-dev      # bun + vite on http://127.0.0.1:5173
 make inspect-dev  # sanderling inspect --dev, proxies non-API to 5173
 ```
 
-For a single binary with embedded assets:
+Single binary with the bundle embedded:
 
 ```
-make sanderling         # builds web/dist, copies to internal/inspect/dist, then go build
+make sanderling
 ```

docs/manual/writing-specs.md

@@ -7,7 +7,7 @@ title: Writing specs
 A spec has three parts: extractors, properties, and actions.
 
 ```ts
-import { extract, always, actions, weighted, Tap, taps, swipes } from "@sanderling/spec";
+import { extract, always, now, actions, weighted, Tap, taps, swipes } from "@sanderling/spec";
 
 // 1. Extractors pull values from each observed state.
 const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
@@ -105,39 +105,29 @@ Session state (tokens, keychain, prefs) persists through the rest of the run. If
 
 ## Pattern: conditional properties
 
-Use gating extractors the same way inside properties. Express "only check X when Y holds":
+Use gating extractors the same way inside properties. Express "only check X when Y holds" with `now(...).implies(...)`:
 
 ```ts
 const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
 
 export const properties = {
-  cartPersistsWhenLoggedIn: always(() => {
-    if (!loggedIn.current) return true;
-    return state.snapshots.cart_count !== undefined;
-  }),
+  cartPersistsWhenLoggedIn: always(
+    now(() => loggedIn.current).implies(now(() => cartCount.current !== undefined)),
+  ),
 };
 ```
 
-When `implies` ships in v0.1.0, this becomes:
+`implies`, `and`, `or`, and `not` are methods on any formula. Combine them freely.
 
-```ts
-cartPersistsWhenLoggedIn: always(() =>
-  implies(loggedIn.current, () => cartCount.current !== undefined)
-),
-```
-
-## Pattern: eventually (once the operator lands)
+## Pattern: eventually
 
 `always` asserts something holds at every step. `eventually` asserts it holds at some step, usually with a time bound:
 
 ```ts
-// v0.1.0+
-loginSucceedsWithin30s: eventually(
-  () => loggedIn.current
-).within(30, "seconds"),
+loginSucceedsWithin30s: eventually(() => loggedIn.current).within(30, "seconds"),
 ```
 
-Useful for liveness checks: the loading spinner eventually goes away, the deep link eventually lands on `/home`.
+`within` takes `"milliseconds"`, `"seconds"`, or `"steps"`. Useful for liveness checks: the loading spinner eventually goes away, the deep link eventually lands on `/home`.
 
 ## Pattern: snapshot-backed properties