Add a visual product tour and a documentation hub

README.md

@@ -10,17 +10,21 @@
 
 <p align="center">
   <strong><a href="https://berkebasbay.github.io/loopset/">Try Loopset →</a></strong> ·
-  <a href="docs/QUICKSTART.md">Quickstart</a> ·
+  <a href="docs/README.md">Documentation</a> ·
   <a href="CONTRIBUTING.md">Contribute</a>
 </p>
 
-Loopset lets you build a small factory, service team or event, then see how a different plan affects queues, waiting and cost. It runs in your browser, with no installation or account.
+**A simulation playground for process ideas.** Build a factory, a service team or an event. Change how work arrives, how long it takes or who is available, then see what happens to queues, waiting and cost.
+
+Loopset is free and runs in your browser. Your projects stay on your device, with no account or installation required.
 
 ## See it in action
 
+From a working template to a real comparison: explore the world, change the shared team and run the next plan.
+
 https://github.com/user-attachments/assets/42cf61e9-e756-4939-8fbe-9a2239fef163
 
-<sub>30-second tour · <a href="https://berkebasbay.github.io/loopset/watch/">Captions & downloads</a> · <a href="docs/media/README.md">Video credits</a></sub>
+<sub>30-second tour · <a href="https://berkebasbay.github.io/loopset/watch/">Captions & downloads</a> · <a href="docs/media/README.md">Media credits</a></sub>
 
 <details>
 <summary><strong>Watch the full walkthrough · 55 seconds</strong></summary>
@@ -29,23 +33,64 @@ https://github.com/user-attachments/assets/03fb5577-61f1-4ac8-a22f-95c133f78d10
 
 </details>
 
-## Build. Run. Compare.
+## A tour of the workspace
+
+### 01 · Start with a world you can change
+
+Choose from **12 editable templates**, each with a starting plan and two prepared alternatives, or start with an empty site. Arrange your facility with **1,141 ready-to-use 3D models**, then define the process that makes it work.
+
+<p align="center">
+  <img src="docs/media/loopset-service-workspace.png" alt="The real Service Studio workspace with the process scene, specialist properties, replay controls and recorded results" width="100%">
+</p>
+
+<sub>Service Studio: reception, specialists and resolution in one editable workspace. <a href="docs/FACILITY_GUIDE.md">Build your own facility →</a></sub>
+
+### 02 · Turn a question into an experiment
+
+Select a step and adjust processing time, parallel stations or the team it needs. Stations, people and shifts are separate decisions. In this example, the shared specialist team changes from **2 available units to 3**, while the station count and break plan stay the same.
+
+<p align="center">
+  <img src="docs/media/loopset-service-edit.png" alt="Actual Shared specialists control changed from two to three available units, with the unchanged installed limit and shift controls" width="100%">
+</p>
+
+<sub>The real editor, enlarged in the walkthrough. <a href="docs/QUICKSTART.md#reproduce-the-service-studio-demo">Try this experiment →</a></sub>
+
+### 03 · See the result and the trade-off
+
+Run the changed plan and compare it with the original. Here, completed requests rise from **66 to 86** and average waiting falls from **9.5 to 5.2 minutes**. The extra capacity also raises modeled resource cost from **$85 to $115**.
+
+<p align="center">
+  <img src="docs/media/loopset-service-compare.png" alt="Actual Service Studio comparison: completed requests 66 to 86, average wait 9.5 to 5.2 minutes, and resource cost 85 to 115 dollars" width="100%">
+</p>
+
+<sub>One synthetic example: 106 arrivals, one hour, seed 4207. Results depend on the model's assumptions; resource cost is not total business cost. <a href="docs/MODEL_GUIDE.md#measurement-and-interpretation">How to read a result →</a></sub>
 
-- **Build your world.** Choose one of 12 templates or start with an empty site. Drag in equipment, shelves and work areas from 1,141 ready-to-use 3D models.
-- **Try a different plan.** Change arrivals, processing time or staffing. Run it and compare completed work, waiting and resource cost.
-- **Make it yours.** Save your project, keep alternatives, or turn your setup into a reusable template.
+Save the plan, keep it as a reusable template, or download an editable project file. Repeated experiments and matched-input comparisons are available when you want to investigate uncertainty beyond a single run.
 
-### Pick a place to start
+## Find your starting point
 
 | Service Studio | Festival Gate | Little Factory |
 | :---: | :---: | :---: |
-| <img src="public/previews/templates/service.png" alt="Service Studio: a team sharing specialist capacity" width="260"> | <img src="public/previews/templates/festival.png" alt="Festival Gate: visitors moving through entrance queues" width="260"> | <img src="public/previews/templates/factory.png" alt="Little Factory: machining, inspection and packing" width="260"> |
+| <img src="public/previews/templates/service.png" alt="Service Studio: shared specialists and waiting requests" width="260"> | <img src="public/previews/templates/festival.png" alt="Festival Gate: arrival waves and entrance queues" width="260"> | <img src="public/previews/templates/factory.png" alt="Little Factory: machining, inspection and packing" width="260"> |
 | Teams & waiting | Arrivals & queues | Production & capacity |
 
-[Explore all templates →](docs/TEMPLATES.md)
+The collection also includes workshops, machining, rework, 3D printing, packing, fulfillment, returns, parcel handling and repairs. [Explore the templates and their experiments →](docs/TEMPLATES.md)
+
+## Documentation
+
+**[Browse all guides →](docs/README.md)**
+
+| I want to… | Start here |
+| --- | --- |
+| Run my first experiment | [Quickstart](docs/QUICKSTART.md) · [Starter templates](docs/TEMPLATES.md) |
+| Build a facility and edit its process | [Facility guide](docs/FACILITY_GUIDE.md) · [Workspace guide](docs/UX_GUIDE.md) |
+| Understand assumptions and results | [Model guide](docs/MODEL_GUIDE.md) · [Export and sharing](docs/SHARING.md) |
+| Use the engine in my own project | [Headless API](docs/API.md) · [Architecture](docs/ARCHITECTURE.md) |
+| Develop, test or host Loopset | [Contributing](CONTRIBUTING.md) · [Testing](docs/QUALITY.md) · [Static hosting](docs/DEPLOYMENT.md) |
+| Find artwork sources and licenses | [Asset catalogue](docs/CATALOGUE.md) · [Asset attribution](docs/NVIDIA_ASSETS.md) · [Media credits](docs/media/README.md) |
 
 <details>
-<summary><strong>Run locally & develop</strong></summary>
+<summary><strong>Run locally</strong></summary>
 
 Use Node.js 24 and npm:
 
@@ -54,15 +99,13 @@ npm ci
 npm run dev
 ```
 
-Open the local address printed by Vite. No API keys or backend setup.
-
-The engine also runs without the interface. See the [Engine API](docs/API.md), [model guide](docs/MODEL_GUIDE.md), and [contribution guide](CONTRIBUTING.md).
+Open the local address printed by Vite. No API keys or backend setup are required. The [contribution guide](CONTRIBUTING.md) covers checks and development conventions.
 
 </details>
 
 ## Help build Loopset
 
-New templates, clearer guides, accessible interactions and focused bug fixes are welcome. [Open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) or [send a pull request](CONTRIBUTING.md).
+New templates, clearer guides, accessible interactions and focused bug fixes are welcome. [Open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) or [send a pull request](CONTRIBUTING.md). For a larger change, discuss the problem and scope first.
 
 ---
 

docs/QUICKSTART.md

@@ -11,7 +11,7 @@ npm ci
 npm run dev
 ```
 
-Open the address printed by Vite. Choose **Little Factory**, **Festival Gate** or **Service Studio**; examples calculate on opening. **New model** starts a valid arrival → waiting → processing → completion flow.
+Open the address printed by Vite. Use **Templates** to choose **Service Studio**, **Festival Gate**, **Little Factory** or another starter; examples calculate on opening. **Blank** starts an empty site, and **Start a process** adds a valid arrival → waiting → processing → completion flow when you are ready.
 
 The working surface has a world, a searchable **Steps** list, contextual **Properties**, and **Run simulation**. **Tools → Model editor** keeps the complete professional model available when you need it.
 
@@ -27,6 +27,23 @@ For a custom facility, choose **Build facility → Empty site**. This starts wit
 
 Use Undo/Redo or **Action history** to reverse model edits. Restoring a saved scenario changes the draft; calculate it to get a new result.
 
+## Reproduce the Service Studio demo
+
+1. Open **Templates → Service Studio** and let the original plan finish calculating.
+2. In **Define process**, select **Specialists** in the world or Steps list, then open **Properties**.
+3. Under **Team or equipment → Shared specialists**, change **Base available units** from **2** to **3** and apply the field with Enter. Leave **Parallel stations**, the installed limit and the shift/break plan unchanged.
+4. Choose **Run & compare**. The original remains the baseline for the comparison.
+
+With the starter's one-hour duration and seed 4207, the same 106 realized arrivals produce these rounded results:
+
+| Outcome | Original · 2 shared units | Changed · 3 shared units |
+| --- | ---: | ---: |
+| Completed requests | 66 | 86 |
+| Average waiting time | 9.5 min | 5.2 min |
+| Modeled resource cost | $85 | $115 |
+
+This is one synthetic example. The arrival estimate in Scenario settings is an expectation; the actual count comes from the recorded run. Cost is a modeled resource charge, not total business cost. The [model guide](MODEL_GUIDE.md#measurement-and-interpretation) explains which work contributes to each metric and how repeated experiments help examine uncertainty.
+
 ## Change duration or demand
 
 **Scenario settings**, beside Run, offers 30-minute, 1-hour, 8-hour and custom durations. Choose seconds, minutes, hours or days for display. Changing the unit alone leaves the model unchanged.

docs/README.md

@@ -0,0 +1,60 @@
+# Loopset documentation
+
+Build a process, test a plan and understand the result. These guides cover the browser workspace, modeling rules, experiments and the standalone engine.
+
+**[Open Loopset →](https://berkebasbay.github.io/loopset/)** · [Watch the demos](https://berkebasbay.github.io/loopset/watch/) · [Project overview](../README.md)
+
+## Choose a starting point
+
+| Your goal | Follow this path |
+| --- | --- |
+| Try Loopset for the first time | [Quickstart](QUICKSTART.md) → [Service Studio video experiment](QUICKSTART.md#reproduce-the-service-studio-demo) |
+| Build a layout from scratch | [Facility guide](FACILITY_GUIDE.md) → [Workspace controls](UX_GUIDE.md) |
+| Explore a ready-made process | [Starter templates](TEMPLATES.md) → [Read a result carefully](TEMPLATES.md#read-a-result-carefully) |
+| Understand results and uncertainty | [Read results in the workspace](UX_GUIDE.md#read-results-and-keep-alternatives) → [Measurement and interpretation](MODEL_GUIDE.md#measurement-and-interpretation) |
+| Integrate or extend the engine | [Headless API](API.md) → [Architecture](ARCHITECTURE.md) → [Contributing](../CONTRIBUTING.md) |
+
+## Use the application
+
+| Guide | What you will find |
+| --- | --- |
+| [Quickstart](QUICKSTART.md) | Open a template, try a capacity decision, reproduce the demo, calculate, save and reopen a project. |
+| [Workspace guide](UX_GUIDE.md) | Properties, demand and duration, teams and shifts, process editing, comparisons, replay, keyboard controls and smaller screens. |
+| [Build a facility](FACILITY_GUIDE.md) | Start empty, place and arrange objects, connect process cells, save templates and transfer the complete facility. |
+| [Starter templates](TEMPLATES.md) | All twelve starters, their process questions, two alternatives each, assumptions and personal templates. |
+| [Export and share](SHARING.md) | Choose project JSON, run JSON, CSV, PNG, HTML or print/PDF and keep the calculation context with the result. |
+
+## Understand the simulation
+
+The visual world and the numerical model have different roles. Artwork and walking make a process easier to follow; arrivals, durations, routing, queues and capacity determine its results.
+
+- [Model guide](MODEL_GUIDE.md): process steps, distributions, priorities, patience, resources, calendars, event ordering, measurement, reproducibility and CSV inputs.
+- [Measurement and interpretation](MODEL_GUIDE.md#measurement-and-interpretation): completed versus unfinished work, waiting samples, percentiles, warm-up, replay limits and uncertainty.
+- [Replications and paired comparisons](API.md#replications-and-paired-comparisons): run repeated experiments and compare compatible plans through the headless API.
+- [Bounded capacity search](API.md#bounded-capacity-search): search a finite set of shared-resource capacities and retain separate verification runs.
+- [Portable examples](../examples/README.md): synthetic reference projects and reproducible command-line runs.
+
+The supplied examples are learning models. Real decisions need appropriate inputs, validation and an understanding of uncertainty. A single run is not a general improvement guarantee.
+
+## Develop and deploy
+
+| Guide | What you will find |
+| --- | --- |
+| [Headless API](API.md) | Build/import commands, public exports, project validation, one run, replay statistics, experiments and the CLI contract. |
+| [Architecture](ARCHITECTURE.md) | Model, calculation, rendering and storage boundaries; immutable results; templates and empty layouts. |
+| [Contributing](../CONTRIBUTING.md) | Where to make a change, what evidence to include, template/demo exports and publication checks. |
+| [Testing](QUALITY.md) | Automated coverage and browser smoke-check commands. |
+| [Static hosting](DEPLOYMENT.md) | Build a static deployment, configure a subpath, serve media and verify the deployed source revision. |
+| [Security](../SECURITY.md) | Supported reporting and handling of vulnerabilities. |
+
+## Assets, media and licenses
+
+- [Prepared asset catalogue](CATALOGUE.md): the browser-ready inventory, source preparation and verification.
+- [World assets and attribution](NVIDIA_ASSETS.md): model, people, surroundings and lighting sources, plus browser adaptations.
+- [Demo media](media/README.md): videos, screenshots, repository artwork, recording scope and credits.
+- [Third-party notices](../THIRD_PARTY_NOTICES.md): the separate licenses for dependencies, artwork, fonts, music and effects.
+- [Code license](../LICENSE): MIT terms for original Loopset code.
+
+## Get help
+
+[Open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) with a small synthetic example, the actions you took and the result you expected. Keep personal or customer data out of public examples.

docs/media/README.md

@@ -20,6 +20,10 @@ Stock music and effects are incorporated into the films; their standalone source
 
 ## Interface screenshots
 
+`loopset-service-workspace.png` shows the actual Service Studio workspace before the recorded team change. It is taken from the same high-resolution native capture used in the current films. The full-run metrics and the replay's momentary scene counters describe different scopes.
+
+`loopset-service-edit.png` and `loopset-service-compare.png` are stills from the published English walkthrough, at 34.4 and 39.5 seconds. They retain the real editor/table and the film's larger editorial annotations. The field has been applied before the edit still; the comparison shows the same synthetic case described above. No interface control or numerical value was reconstructed for these images.
+
 The PNG screenshots in this directory document the RC14 workspace, template gallery and recorded-result surfaces. `loopset-facility.png` uses the enhanced Little Factory layout; its source is [`examples/facility.json`](../../examples/facility.json). `loopset-compare.png` shows that Factory's separate station/team experiment, 40 → 77 completed orders; it is not the Service Studio comparison in the current films.
 
 `public/previews/templates/` contains the twelve starter scene previews. All models and examples shown are synthetic. Original browser captures omit local-origin footers. NVIDIA CC BY 4.0 models, Quaternius/Poly Haven CC0 material and fonts retain the creator/source/license records linked above.