berkebasbay · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026
diff --git a/.github/ISSUE_TEMPLATE/first_use_feedback.md b/.github/ISSUE_TEMPLATE/first_use_feedback.md
@@ -0,0 +1,23 @@
+---
+name: First-use feedback
+about: Tell us where you got stuck or what made an example easier to understand
+title: ''
+labels: ''
+assignees: ''
+---
+
+## What were you trying to do?
+
+Try a [first-use task](https://github.com/berkebasbay/loopset/blob/main/docs/FEEDBACK.md), or describe your own goal. You do not need to understand the code.
+
+## Where did you get stuck?
+
+Which step, words or control were confusing? What did you expect to happen?
+
+## How far did you get?
+
+Did you finish on your own, finish with help, or stop? What would have helped?
+
+## Environment (if known)
+
+Browser, device or screen size, and app version. A screenshot or a small invented example is optional. Do not share personal/customer data, credentials or browser files.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,11 @@
+## Problem and result
+
+What concrete problem does this solve? Describe what someone can do after this change.
+
+## Validation
+
+Which relevant checks or real user actions did you verify? For numerical changes, include an independent expectation or invariant. Explain any known limitation.
+
+## Reproduction
+
+For a fix, give the smallest steps or synthetic example that shows it. Keep customer data, credentials, personal information and raw local logs out of the PR and attachments.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,6 +1,5 @@
 name: Verify changes
 
-# Check every PR revision, including drafts; keep manual dispatch available.
 on:
   pull_request:
     branches: [main]
@@ -15,11 +14,10 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  verify:
+  checks:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      # Official release refs resolved through api.github.com on 2026-10-20.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
@@ -52,10 +50,47 @@ jobs:
       - run: npm run check:assets
       - run: npm run check:templates
       - run: npm run check:demos
+      - run: npm run check:docs
       - run: npm run typecheck
       - run: npm test
       - run: npm run build
       - run: npm run build:engine
       - run: node scripts/simulate.mjs --example factory --seed 4207
       - run: node scripts/simulate.mjs examples/service.json --seed 4207
       - run: node examples/verify.mjs
+  browser:
+    needs: checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        suite: [first-use, recovery-and-entry, templates, original-worlds]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: '24'
+          package-manager-cache: false
+      - run: npm ci
+      - run: npm run build
+      - run: npx playwright install --with-deps chromium
+      - name: Check browser journey
+        env:
+          QUEUELAB_BROWSER_SUITE: ${{ matrix.suite }}
+        run: npm run test:browser
+  verify:
+    if: ${{ always() }}
+    needs: [checks, browser]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require source checks and every browser journey
+        env:
+          QUALITY_RESULT: ${{ needs.checks.result }}
+          BROWSER_RESULT: ${{ needs.browser.result }}
+        run: |
+          test "$QUALITY_RESULT" = success
+          test "$BROWSER_RESULT" = success
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -14,6 +14,8 @@ concurrency:
 
 jobs:
   build:
+    outputs:
+      public_url: ${{ steps.pages.outputs.base_url }}/
     runs-on: ubuntu-latest
     timeout-minutes: 15
     permissions:
@@ -47,6 +49,7 @@ jobs:
       - run: npm run check:assets
       - run: npm run check:templates
       - run: npm run check:demos
+      - run: npm run check:docs
       - run: npm run typecheck
       - run: npm test
       - run: npm run test:headless
@@ -60,9 +63,34 @@ jobs:
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:
           path: dist
-  deploy:
+  browser:
     needs: build
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        suite: [first-use, recovery-and-entry, templates, original-worlds]
+    env:
+      QUEUELAB_PUBLIC_URL: ${{ needs.build.outputs.public_url }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: '24'
+          package-manager-cache: false
+      - run: npm ci
+      - run: npm run build
+      - run: npx playwright install --with-deps chromium
+      - name: Check built browser journey
+        env:
+          QUEUELAB_BROWSER_SUITE: ${{ matrix.suite }}
+        run: npm run test:browser
+  deploy:
+    needs: [build, browser]
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       pages: write

diff --git a/.gitignore b/.gitignore
@@ -21,5 +21,5 @@ dist-engine/
 # Private development notes and local automation state
 progress.md
 
-# Machine-local agent instructions
-/AGENTS.override.md
+# Local override documents
+*.override.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.0.0-rc.17
+
+- Add keyboard links that bypass navigation and reach the workspace or current lesson.
+- Defer the initial 3D world until the first-use welcome is dismissed and the current project is known.
+- Add a direct guided-example entry that opens the welcome without replacing saved work.
+- Keep process selection, calculations and template saves available when WebGL or the graphics module cannot load.
+- Encode static PNG result cards on a CPU-backed offscreen canvas when supported, with the original bounded HTML fallback.
+- Preserve the first digit typed immediately after opening a numeric field.
+- Keep the scene size stable while a numeric field is unfinished.
+- Keep private previews and generated engine files out of development reloads; block local private folders and override documents from dev-server delivery.
+- Run isolated browser journeys before accepting PRs and publishing the demo, alongside documentation link checks.
+- Add a first-use feedback guide and a focused first-contribution path.
+
+## Preview updates: rc.10–rc.16
+
+- Prepare an on-demand catalogue of 1,141 browser-ready models with source attribution and validation.
+- Introduce the facility/process/results workspace, empty sites, placed-object controls, process cells and reusable personal templates.
+- Expand to twelve curated starters, each with two alternatives and deterministic numerical references.
+- Publish English short/full walkthroughs and a visual README with a task-based documentation hub.
+- Add and simplify the first-use lesson into one real task at a time: select, change a team, calculate, compare and save.
+- Preserve original projects, results, history and local data through practice, failures, cancellation and refresh.
+
 ## 1.0.0-rc.9
 
 - Publish a browser demo with deployment-subpath-aware models, world previews, fonts and sharing metadata.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,8 +23,21 @@ npm run setup:hooks
 npm run dev
 ```
 
+The dev watcher ignores generated private previews, caches and the standalone engine output, so building or collecting local evidence does not reload a working app. The dev server also blocks local private folders and override documents; Git ignore rules alone do not control HTTP delivery.
+
 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.
 
+## Your first pull request
+
+Start with one small, reproducible problem. You can improve a confusing instruction, add a synthetic regression example, or make a control easier to use with a keyboard.
+
+1. Fork the repository, create a branch and run the app with the commands above.
+2. Make the smallest complete change. Product wording lives in `src/ui/messages`; guides live in `docs`; tests belong beside the relevant contract under `tests`.
+3. Check your change: `npm run check:docs` for guide/link edits, `npm run typecheck` and a focused unit test for code, and `npm run test:browser` for affected main workflows. The full required checks are below.
+4. Open a PR explaining the problem, result and actual validation. A screenshot or tiny synthetic model can help; customer files and local machine details do not belong in the PR.
+
+For a starter, follow the [template contribution path](docs/TEMPLATES.md) before editing generated files. For numerical behavior, use an independently reasoned expectation. If you prefer not to code, [first-use feedback](docs/FEEDBACK.md) is also useful.
+
 ## 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:
@@ -96,6 +109,7 @@ Match verification to the change. For prose-only changes, check the referenced c
 ```sh
 npm run typecheck
 npm run check:assets
+npm run check:docs
 npm test -- --maxWorkers=1
 npm run build
 npm run test:headless

diff --git a/README.md b/README.md
@@ -18,6 +18,8 @@
 
 Loopset is free and runs in your browser. Your projects stay on your device, with no account or installation required.
 
+**New to simulation? [Try the guided example →](https://berkebasbay.github.io/loopset/?learn=1)** Select a help desk, add one person, and see how waiting and cost change. Your current project is kept.
+
 ## See it in action
 
 From a working template to a real comparison: explore the world, change the shared team and run the next plan.
@@ -105,6 +107,8 @@ Open the local address printed by Vite. No API keys or backend setup are require
 
 ## Help build Loopset
 
+Try a [first-use task](docs/FEEDBACK.md), tell us where you got stuck, or make a [small first contribution](CONTRIBUTING.md#your-first-pull-request).
+
 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.
 
 ---

diff --git a/docs/FEEDBACK.md b/docs/FEEDBACK.md
@@ -0,0 +1,32 @@
+# Help improve first use
+
+You can contribute by trying Loopset and explaining where it becomes confusing. No coding or simulation experience is required.
+
+[Open the guided example →](https://berkebasbay.github.io/loopset/?learn=1) · [Send first-use feedback →](https://github.com/berkebasbay/loopset/issues/new?template=first_use_feedback.md)
+
+Use only made-up data. Your projects stay in this browser; downloading project JSON gives you a portable copy.
+
+## Try one task
+
+| Task | Goal | A useful observation |
+| --- | --- | --- |
+| First example | Complete the guided help-desk lesson and keep your example as a template. | Where did you need to reread, search or ask for help? Could you explain the result in your own words? |
+| Your own change | Open a starter, change one assumption and compare the result with its original plan. | Was it clear what changed, which calculation you were looking at, and what the result meant? |
+| Empty site | Start with Blank, place a model, choose Start a process, and save your setup. | Was the difference between arranging the space and changing how work happens clear? |
+
+Start without reading the detailed guides. If you need help, use the [Quickstart](QUICKSTART.md) and mention where you needed it. You can stop at any time; unfinished tasks are useful feedback too.
+
+## Tell us what happened
+
+1. State your goal and the actions you tried.
+2. Name the point where you paused, guessed, needed help or stopped.
+3. Say whether you finished on your own, with help, or did not finish.
+4. Describe what you expected to see instead. Include your browser/device if known.
+
+A short account of one confusing moment is more useful than a score alone. Timing is optional. Screenshots or recordings are optional; review them for private information before attaching them to a public issue.
+
+Use [first-use feedback](https://github.com/berkebasbay/loopset/issues/new?template=first_use_feedback.md) for clarity and discoverability, or a [bug report](https://github.com/berkebasbay/loopset/issues/new?template=bug_report.md) for reproducible wrong behavior. Report security concerns through [Security](../SECURITY.md).
+
+## Reading feedback
+
+Distinguish observed behavior from a suggested solution. Include the application revision and the task when comparing results across versions. Browser emulation and automated checks cannot replace accounts from people trying the product for the first time.
diff --git a/docs/QUALITY.md b/docs/QUALITY.md
@@ -7,6 +7,7 @@ npm ci
 npm run typecheck
 npm run check:assets
 npm run check:templates
+npm run check:docs
 npm test -- --maxWorkers=1
 npm run test:publication
 npm run build
@@ -17,6 +18,20 @@ The unit suite covers numerical references, conservation/capacity invariants, ev
 
 ## Browser smoke checks
 
+The required PR check and Pages workflow run `npm run test:browser` against the built app. Four isolated browser jobs run in parallel; the final required `verify` check needs the source checks and every browser job to succeed. Deployment also waits for all four jobs. Each browser job builds the same checked-out source with the same deployment base; no additional build-artifact storage is introduced. This starts its own loopback preview, checks first use, no-3D/module failures, safe guided entry, templates and the original worlds, then stops only its own processes. Linux CI uses software graphics and chooses the existing Low power view through the real UI in isolated Chromium contexts. The setup asserts that changing display detail leaves numerical identity unchanged. All interaction, result and persistence assertions remain active; these are correctness checks, not GPU performance measurements. Local detailed-renderer checks are separate.
+
+Install the browser matching the pinned Playwright dependency once with `npx playwright install chromium` (CI uses `npx playwright install --with-deps chromium`, as in the [Playwright CI guide](https://playwright.dev/docs/ci-intro)). Then run:
+
+```sh
+npm run build
+npm run test:browser
+```
+
+The runner fails if its preview port is occupied. Set `QUEUELAB_BROWSER_PORT` to a free port; it never stops an existing server. `QUEUELAB_BROWSER_DIST` selects an alternative build folder. `QUEUELAB_BROWSER_SUITE` can select `first-use`, `recovery-and-entry`, `templates` or `original-worlds` for a focused run; unknown names fail. Without it, every suite runs. `QUEUELAB_PUBLIC_URL` supplies the built deployment subpath, so the Pages build is checked under the same `/loopset/` base. Generated evidence remains ignored; no browser profiles or customer files are used.
+
+Documentation checks validate local file/image links and common Markdown heading anchors, excluding fenced code examples. They do not make external website availability a build requirement.
+
+
 Serve a production build on loopback and run:
 
 ```sh

diff --git a/docs/README.md b/docs/README.md
@@ -57,4 +57,6 @@ The supplied examples are learning models. Real decisions need appropriate input
 
 ## Get help
 
+New to the product? Try a [first-use task](FEEDBACK.md) and tell us where you got stuck. No code or private project is needed.
+
 [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.
diff --git a/index.html b/index.html
@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="/fonts/fonts.css" />
     <meta name="theme-color" content="#f4f3ee" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" sizes="any" />
     <link rel="icon" href="/favicon-32.png" type="image/png" sizes="32x32" />

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "queuelab",
-  "version": "1.0.0-rc.16",
+  "version": "1.0.0-rc.17",
   "private": true,
   "type": "module",
   "description": "A playable process and capacity simulation laboratory",
@@ -15,6 +15,8 @@
     "simulate": "node scripts/simulate.mjs",
     "examples:export": "npm run build:engine && node scripts/export-examples.mjs",
     "test:headless": "npm run build:engine && node examples/verify.mjs",
+    "check:docs": "node --test tests/docs.test.mjs && node scripts/check-docs.mjs",
+    "test:browser": "node --test tests/browser-runner.test.mjs tests/dev-boundaries.test.mjs && node scripts/browser-checks.mjs",
     "test:learning": "node scripts/learning-smoke.mjs",
     "test:ux": "node scripts/ux-smoke.mjs",
     "setup:hooks": "node scripts/setup-hooks.mjs",
Original file line number	Diff line number	Diff line change
Expand Up		@@ -57,4 +57,6 @@ The supplied examples are learning models. Real decisions need appropriate input

		## Get help

		New to the product? Try a [first-use task](FEEDBACK.md) and tell us where you got stuck. No code or private project is needed.

		[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.