Refresh the product demo and contribution guide

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Report a reproducible problem with a synthetic example
+title: ''
+labels: ''
+assignees: ''
+---
+
+## What happened?
+
+Describe the expected behavior and what happened instead.
+
+## How can we reproduce it?
+
+1. Open a named starter or attach a minimal synthetic project JSON.
+2. List the edits and actions, including Run or Compare where relevant.
+3. Describe the observed result.
+
+For a numerical issue, include the run duration, seed, relevant input values and why you expect a different result.
+
+## Environment
+
+- Browser and version:
+- Operating system:
+- App version or commit, if known:
+- Public demo or local build:
+
+## Supporting evidence
+
+Add a screenshot, short recording or synthetic project only if it helps reproduce the problem. Include relevant keyboard or narrow-screen behavior for an interaction issue.
+
+Review attachments before posting. Do not include customer data, personal information, credentials, browser profiles or raw local logs. Report security vulnerabilities through [SECURITY.md](https://github.com/berkebasbay/loopset/blob/main/SECURITY.md).

.github/ISSUE_TEMPLATE/starter_proposal.md

@@ -0,0 +1,33 @@
+---
+name: Starter or experiment proposal
+about: Suggest a synthetic process question for the template collection
+title: ''
+labels: ''
+assignees: ''
+---
+
+## What should someone learn or explore?
+
+Describe one concrete process or capacity question. Explain how it differs from the [existing starters](https://github.com/berkebasbay/loopset/blob/main/docs/TEMPLATES.md).
+
+## Model and assumptions
+
+Outline the process steps, demand, timing, queues and shared resources. Use synthetic values and state important simplifications. If it needs behavior outside the current engine, identify that separately.
+
+## Plans to compare
+
+- Original plan:
+- First alternative and changed inputs:
+- Second alternative and changed inputs:
+
+For an improvement to an existing experiment, describe only the plans affected.
+
+## How could we verify it?
+
+Describe an analytical example, independent reference or invariant that could check the expected behavior. Avoid choosing inputs just to produce an attractive result.
+
+## Optional contribution
+
+If you would like to implement the proposal, note the part you can help with: model, layout, tests, preview or documentation. No implementation is required to suggest an idea.
+
+Use only synthetic data and appropriately licensed assets. See the [template guide](https://github.com/berkebasbay/loopset/blob/main/docs/TEMPLATES.md) for source files, generation and checks.

CONTRIBUTING.md

@@ -2,6 +2,17 @@
 
 Useful contributions make process questions easier to model, explain or reproduce. Small synthetic examples, independently reasoned engine tests, clearer editing, accessible interactions and focused bug fixes are welcome.
 
+## Choose a contribution
+
+| Contribution | Start here | Include in the proposal or pull request |
+| --- | --- | --- |
+| A starter or experiment | [Template guide](docs/TEMPLATES.md), `src/templates/definitions.ts`, `src/templates/presentation.ts`, `src/templates/catalogue.ts`, `src/ui/messages/starterTemplates.ts` | One process question, explicit synthetic assumptions, an original plan and two meaningful alternatives; explain which inputs change and why |
+| An engine test or fix | `src/engine`, `src/experiments`, [model contract](docs/MODEL_GUIDE.md), [engine API](docs/API.md) | A minimal model plus an analytical timeline, independent reference or invariant that establishes the expected result |
+| An editing or accessibility improvement | `src/features`, `src/lab`, `src/ui/messages`, [workspace guide](docs/UX_GUIDE.md) | Reproducible actions, expected behavior, and relevant keyboard, focus, Undo/Redo and narrow-screen checks |
+| A guide or example clarification | `docs`, `examples/README.md` | The confusing task or assumption, a concrete correction, and checked commands or UI labels |
+
+Search existing issues first. For a larger change or a new starter, open an [issue](https://github.com/berkebasbay/loopset/issues/new/choose) with the problem, proposed scope and expected evidence before writing substantial code. A focused fix can come directly as a pull request with reproduction steps. Proposals are reviewed for fit, correctness, accessibility and maintenance; opening a PR does not guarantee acceptance.
+
 ## Start locally
 
 Use Node.js 24 and the committed npm lockfile:
@@ -14,6 +25,21 @@ npm run dev
 
 No backend, account or API key is required. Use invented data in issues, tests, screenshots and examples. Keep customer files, personal information, credentials, browser profiles and raw local logs out of contributions.
 
+## Change a starter template
+
+The collection currently contains twelve starters, each with an original plan and two alternatives. Edit the source definitions and presentation, then regenerate the portable projects:
+
+```sh
+npm run templates:export
+npm run check:templates
+```
+
+The exporter validates all 36 plans and writes `public/templates/*.json`, `src/templates/inventory.json`, three reference seeds per plan in `public/templates/reference-results.json`, and the Factory fixture in `examples/facility.json`. Check mode compares these outputs with their definitions; CI runs it. Change generated files through the exporter, and review every resulting model and reference-result difference.
+
+Keep the original Factory, Festival and Service numerical examples unchanged unless the proposed change explicitly addresses their behavior. A new starter needs catalogue and message entries as well as its model, alternatives and presentation. Include an independent expectation for the behavior it teaches; a saved regression result alone does not establish correctness.
+
+Open the starter in the app, apply and calculate both alternatives, inspect the input differences and results, then exercise Undo and JSON download/reopen. When changing layout, capture and inspect the actual preview and alternative layouts. See the [template guide](docs/TEMPLATES.md) and [browser checks](docs/QUALITY.md) for the complete flow and `npm run test:templates` setup. Do not imply physical transport, inventory assembly or real-business calibration through the scenery or copy.
+
 ## Publication checks
 
 Set up the optional local hooks with `npm run setup:hooks`. They check staged files before a commit and outgoing commit/tag contents before a push. Existing custom hooks are preserved; integrate these checks into a custom setup when needed. Setup enables repository-local `user.useConfigOnly`, so configure your intended Git identity. A GitHub noreply address keeps your contact address private.
@@ -35,6 +61,7 @@ Repair rejected content before pushing. Removing a file in a later commit does n
 | `src/playback` / `src/scene` | Recorded-result replay and visual presentation |
 | `src/ui/messages` | Typed English product copy and accessible labels |
 | `src/examples` / `examples` | Synthetic factories and portable reference projects |
+| `src/templates` / `public/templates` | Curated starter definitions, layouts, catalogue and generated portable projects |
 | `src/public-api.ts` | Headless engine exports |
 
 The engine must remain independent of DOM, React, Three.js, browser storage, animation speed and network services. Visual movement is not modeled transport time. Drafts, recorded run snapshots, scenarios, experiments and playback state have separate identities and lifecycles.
@@ -53,7 +80,7 @@ Describe the concrete problem, resulting behavior and relevant validation. Keep
 - Keep visible copy, accessible names and recovery instructions in the relevant message catalog. User/model names and canonical file keys remain data, rather than translatable UI strings.
 - Verify dependency and asset licenses before adding or updating them. Retain attribution, source manifests and modification records.
 
-Run checks appropriate to the change, then the integration checks before requesting review:
+Match verification to the change. For prose-only changes, check the referenced commands, labels and links; do not rerun unrelated numerical or browser suites. For code or model changes, run the relevant focused checks and these integration checks before requesting review:
 
 ```sh
 npm run typecheck
@@ -63,7 +90,7 @@ npm run build
 npm run test:headless
 ```
 
-The last command builds and checks the standalone engine and portable examples. If an example definition changes, run `npm run examples:export` and review both its project JSON and reference-result differences. Do not edit expected results merely to make a story or a test look better.
+The last command builds and checks the standalone engine and portable examples. If an original example definition changes, run `npm run examples:export` and review both its project JSON and reference-result differences. For curated starters, use `npm run templates:export` and `npm run check:templates` as described above. Do not edit expected results merely to make a story or a test look better.
 
 Pull requests targeting `main` run the repository's automatic checks; manual workflow dispatch is also available. The Pages workflow checks, builds and publishes `main` to the browser demo. See [Testing](docs/QUALITY.md) for check coverage and browser smoke commands.
 

README.md

@@ -2,19 +2,17 @@
 
 **Build a little world. Test a better plan.**
 
-Loopset is a visual process and capacity simulator. Explore a factory, a festival entrance or a service studio; change demand, processing time and staffing, then compare what happens to queues, completed work and cost.
+Loopset is a visual process and capacity simulator for exploring why work queues up and what a different plan changes. Build a small facility, adjust demand, processing time, stations or team availability, then compare completed work, waiting and resource cost.
 
 Free, client-side and account-free. Simulations run in your browser without a paid API or simulation backend. Your models stay on your device.
 
-**[Try Loopset in your browser →](https://berkebasbay.github.io/loopset/)** · [Watch the demo](docs/media/loopset-demo.mp4)
+**[Try Loopset in your browser →](https://berkebasbay.github.io/loopset/)** · [Watch the 67-second demo](docs/media/loopset-demo.mp4) · [Contribute](CONTRIBUTING.md)
 
-Choose from **12 editable templates** across production, logistics, service and events, or start with **Blank**. Each ready-made facility includes an original plan and two experiments. Save your own starting points in **My templates**. No installation needed.
+Start with **12 editable templates** across production, logistics, service and events, or choose **Blank**. Each starter has an original plan and two alternatives: **24 prepared experiments** to explore. Save your own starting points in **My templates** or download a portable project JSON. No installation needed.
 
 [![Loopset facility workspace: searchable model library, editable workshop and recorded outcomes](docs/media/loopset-facility.png)](https://berkebasbay.github.io/loopset/)
 
-[Watch the capacity-comparison demo (RC9)](docs/media/loopset-demo.mp4) · [Facility guide](docs/FACILITY_GUIDE.md)
-
-[Quickstart](docs/QUICKSTART.md) · [Workspace guide](docs/UX_GUIDE.md) · [Model guide](docs/MODEL_GUIDE.md) · [Engine API](docs/API.md) · [Examples](examples/README.md)
+[Quickstart](docs/QUICKSTART.md) · [Templates](docs/TEMPLATES.md) · [Facility guide](docs/FACILITY_GUIDE.md) · [Workspace guide](docs/UX_GUIDE.md) · [Model guide](docs/MODEL_GUIDE.md) · [Engine API](docs/API.md) · [Examples](examples/README.md)
 
 ## One more station. The same output.
 
@@ -70,7 +68,9 @@ These original numerical examples remain unchanged. The [twelve-template collect
 
 ## Build your facility
 
-The workspace separates **Build facility**, **Define process** and **Review results**. The docked **Asset library → 3D models** lets you search and drag equipment, shelves, building parts and containers onto the site. **Empty site** starts with no objects or process steps. Add **Start a process** when ready to simulate. Layout objects have position, elevation, rotation and scale controls; process cells add connected waiting and processing stages with explicit team settings. Models load when used, and repeated instances share geometry.
+The workspace separates **Build facility**, **Define process** and **Review results**. The docked **Asset library → 3D models** contains **1,141 selected, browser-prepared models**: equipment, shelves, building parts, containers and other facility objects. Search and drag them onto the site. Models load when used, and repeated instances share geometry.
+
+**Empty site** starts with no objects or process steps. Add **Start a process** when ready to simulate. Layout objects have position, elevation, rotation and scale controls; process cells add connected waiting and processing stages with explicit team settings.
 
 **Save as template** keeps a reusable snapshot in this browser. Each use creates an independent project. Templates can be downloaded or imported as project JSON.
 
@@ -104,14 +104,18 @@ Projects save in browser storage at the current site address. Download JSON back
 
 ## Develop and contribute
 
+Contributions are welcome. A useful starting point can be a synthetic template with a clear process question, an independently reasoned engine test, a focused bug fix, an accessible editing improvement or a clearer guide. See [CONTRIBUTING](CONTRIBUTING.md) for the relevant files, evidence and checks.
+
+Try the app and [open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) with a reproducible example or proposed template. For a larger change, describe the problem and intended scope before implementing it. Pull requests propose changes for review; small, focused contributions are easier to discuss and verify.
+
 ```sh
 npm run typecheck
 npm test -- --maxWorkers=1
 npm run build
 npm run test:headless
 ```
 
-`npm run preview` serves a production build locally. See [CONTRIBUTING](CONTRIBUTING.md) for architecture boundaries, focused checks and synthetic examples, or [SECURITY](SECURITY.md) for vulnerability reporting.
+`npm run preview` serves a production build locally. Report vulnerabilities through [SECURITY](SECURITY.md).
 
 ## License and credits
 

THIRD_PARTY_NOTICES.md

@@ -8,6 +8,8 @@ The current miniature worlds use the sourced model adaptations listed below. Lin
 
 React, React DOM, scheduler and Three.js use the MIT license. Lucide uses ISC and retains MIT notices for icons derived from Feather. Their installed license texts are reproduced below. The headless engine bundle contains Loopset code and no third-party runtime dependency.
 
+The demonstration film is rendered with HyperFrames and GSAP; these production tools are not added to the application runtime. Its motion and synthesized score use [Cinetic](https://github.com/Leonxlnx/cinetic) (MIT, copyright 2026 Leonxlnx), and its generated effects and audio analysis use [Earshot](https://github.com/Leonxlnx/earshot) (MIT, copyright 2026 Leon Lin). Their reference-film footage and audio are not included. The film uses the same DM Sans font, Lucide-derived cube mark and attributed facility artwork as the product. See the [media notes](docs/media/README.md) for the recording and editing scope.
+
 ## Installed npm package inventory
 
 `Runtime` is the lockfile's non-dev dependency graph, which can include type-only packages. Development dependencies are not part of the headless bundle. The native Rolldown binding declares MIT in its installed package metadata; its package has no separate license file, so retain the parent Rolldown notices when redistributing that tooling.

docs/media/README.md

@@ -1,17 +1,19 @@
 # Loopset demonstration
 
-[Watch the 42-second demo](loopset-demo.mp4) · [Animated preview](loopset-demo.gif) · [English captions](loopset-demo.vtt)
+[Watch the 67-second demo](loopset-demo.mp4) · [Animated preview](loopset-demo.gif) · [English captions](loopset-demo.vtt)
 
-The film shows the actual RC9 interface and calculations. In the synthetic Factory, one extra packing station leaves output unchanged until its team capacity is increased deliberately: 40 → 40 → 77 completed orders, with modeled resource cost $74 → $74 → $96. Each plan uses the same 80 modeled arrivals and seed 4207. This is one modeled case, not a validated business forecast.
+The film uses the actual RC14 interface in one synthetic Little Factory project. It opens a template, places a shelf, changes packing stations and team capacity, runs comparisons, then saves and reuses the setup.
 
-The MP4 is 1920×1080 at 30 fps, silent with English captions. The lighter animated preview is derived from the same real footage. Camera closeups are editorial crops; controls, inputs and results are not invented.
+One extra packing station leaves output unchanged until its team capacity is increased deliberately: 40 → 40 → 77 completed orders, with modeled resource cost $74 → $74 → $96. Mean waiting changes from 14.5 to 1.4 minutes. Each plan uses the same 80 modeled arrivals, one-hour duration and seed 4207. This is one synthetic case, not a business forecast; resource cost is not total operating cost. Placing a shelf changes the layout, not the calculation.
 
-Produced locally with [Hyperframes](https://github.com/heygen-com/hyperframes), with motion-direction guidance from [Cinetic](https://github.com/Leonxlnx/cinetic). The underlying art and fonts retain their own licences: see [third-party notices](../../THIRD_PARTY_NOTICES.md) and [asset provenance](../NVIDIA_ASSETS.md).
+The MP4 is 1920×1080 at 60 fps with English screen text, music and effects. Native browser footage was captured at 25 fps; the camera and typography animate at 60 fps. Editorial crops, shortened pauses and held comparison frames make the real actions and results readable. No UI controls or intermediate numerical results are reconstructed. The animated preview is a silent excerpt from the same film.
 
-## Current interface screenshots
+Produced with [HyperFrames](https://github.com/heygen-com/hyperframes), [Cinetic](https://github.com/Leonxlnx/cinetic) and [Earshot](https://github.com/Leonxlnx/earshot). The soundtrack is an original synthesized arrangement with code-generated effects; it contains no sampled reference-film music or voiceover. DM Sans, GSAP and the underlying artwork retain their own licences: see [third-party notices](../../THIRD_PARTY_NOTICES.md) and [asset provenance](../NVIDIA_ASSETS.md).
 
-`loopset-facility.png` captures the actual RC12 interface rendering the synthetic Workshop and dispatch example: the unchanged Factory numerical process with 57 independently editable layout objects. The source project is [`examples/facility.json`](../../examples/facility.json). The local-origin footer is excluded from this capture.
+## Interface screenshots
+
+`loopset-facility.png` and `loopset-templates.png` capture the RC14 facility workspace and template gallery. The Little Factory layout uses the unchanged Factory numerical process with 57 independently editable objects. Its source project is [`examples/facility.json`](../../examples/facility.json). The video adds one shelf, keeping 58 layout objects through the experiment. Local-origin footers are excluded from the media.
 
 `loopset-insights.png` shows recorded outcomes from the same synthetic process. `loopset-compare.png` shows its deliberate station/team comparison, 40 → 77 completed orders. These are browser captures with real inputs and calculated values; the examples are not calibrated business forecasts.
 
-The PNG previews in `public/previews/` are captured from the three real rendered example worlds, with editor chrome excluded. NVIDIA CC BY 4.0 models, Quaternius/Poly Haven CC0 material and the existing font retain the creator/source/licence records linked above. The comparison video/GIF remains the RC9 recording; its numerical workflow is still supported.
+The PNG previews in `public/previews/` show real rendered example worlds, and `public/previews/templates/` contains the twelve current starter scenes. The social card uses the Little Factory starter preview in an editorial layout. NVIDIA CC BY 4.0 models, Quaternius/Poly Haven CC0 material and the fonts retain the creator/source/licence records linked above.