Touched up notebooks + webapp

webapp.md

@@ -0,0 +1,89 @@
+# Webapp Reference
+
+The web application is a focused Monte Carlo comparison built with FastAPI,
+vanilla JavaScript, and Plotly.js.
+
+## Purpose
+
+For each simulated price path, the backend constructs an adaptive schedule
+using the current distance to the nearer log-price barrier and the local
+symmetric-endpoint Brownian-bridge proxy. The fixed baseline has two modes:
+
+1. **Equal budget:** use exactly the adaptive schedule's sample count on each
+   path, distributed uniformly.
+2. **Fixed cadence:** sample at an independently selected interval in minutes,
+   with the start and end of the window included.
+
+Lower and upper barrier events are evaluated independently. A detection must
+occur within the configured number of simulation-grid steps and the sampled
+price must still be beyond the relevant barrier.
+
+## Routes
+
+### `GET /`
+
+Serves the single-page frontend and replaces static asset query strings with
+mtime/size cache-busting values.
+
+### `GET /api/health`
+
+Returns runtime readiness, package version, and default model parameters.
+
+### `POST /api/simulate`
+
+Validated request fields include:
+
+- initial price, annual drift, and annual volatility;
+- simulation horizon, number of paths, and grid resolution;
+- lower and upper barrier percentages;
+- local diffusion parameter `eps`;
+- hard maximum polling interval;
+- detection deadline in grid steps;
+- comparison mode and fixed cadence in minutes;
+- optional Merton jump parameters;
+- optional random seed.
+
+The response contains path data, both schedules, direction-specific breach and
+detection fields, exact sample totals, detection-lag summaries, and an explicit
+model-scope warning.
+
+## Important interpretation
+
+`eps` is **not** an unconditional probability guarantee. The exact Brownian
+bridge formula conditions on two endpoints, whereas an online scheduler does
+not know the future endpoint. The implementation substitutes the current
+barrier distance for both endpoint distances. Jumps are outside that diffusion
+calculation entirely.
+
+The demo therefore presents a controlled scheduling comparison, not a promise
+that adaptive sampling always outperforms fixed sampling.
+
+## Frontend
+
+The interface provides controls for all main simulation and detector parameters.
+It displays:
+
+- simulated paths and both barriers;
+- adaptive observations as open cyan circles;
+- equal-budget or fixed-cadence observations as grey dots;
+- first lower and upper breach markers;
+- direction-specific detection counts;
+- exact adaptive/fixed sample totals;
+- adaptive and fixed mean detection lags;
+- raw run statistics and model-scope warnings.
+
+Pure GBM is the default. Merton jump diffusion is an optional stress mode and
+triggers an on-screen warning about the limits of the Brownian proxy.
+
+## Local development
+
+```bash
+pip install -e ".[webapp]"
+uvicorn webapp.app:app --reload --host 127.0.0.1 --port 8055
+```
+
+## API smoke test
+
+```bash
+curl -s http://127.0.0.1:8055/api/health
+```