yz4git · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026
diff --git a/README.md b/README.md
@@ -2,27 +2,31 @@
   <img src="public/worldseed-mark.svg" width="84" alt="WorldSeed mark" />
   <h1>WorldSeed</h1>
   <p><strong>Turn open geospatial data into playable, exportable 3D worlds.</strong></p>
-  <p>Three.js · terrain-aware roads · arcade driving · GLB + road graphs + colliders + spawn points + JSON Schema</p>
+  <p>Explore a city in the browser, then reuse its GLB geometry, road graph, colliders, spawn points and semantic JSON in your own project.</p>
   <p>
-    <a href="https://yz4git.github.io/next-gen/demo/"><strong>Live demo</strong></a>
+    <a href="https://yz4git.github.io/next-gen/demo/"><strong>▶ Explore the live demo</strong></a>
     ·
-    <a href="https://github.com/yz4git/next-gen/releases/latest"><strong>Latest release</strong></a>
+    <a href="docs/TRY_WORLDSEED.md"><strong>Try an export in 5 minutes</strong></a>
     ·
-    <a href="docs/TRY_WORLDSEED.md"><strong>Try it in 5 minutes</strong></a>
-    ·
-    <a href="docs/SCHEMA_VERSIONING.md"><strong>Schema v1</strong></a>
-    ·
-    <a href="https://github.com/yz4git/next-gen/issues/19"><strong>Early adopters wanted</strong></a>
+    <a href="docs/REUSE.md"><strong>Build with the export</strong></a>
   </p>
+  <p><sub>Three.js · OpenStreetMap / Overture Maps · GLB / glTF · JSON Schema v1 · MIT-licensed code</sub></p>
 </div>
 
-![WorldSeed live Tokyo Tower world generated from open geospatial data](docs/worldseed-preview.png)
+[![WorldSeed live Tokyo Tower world generated from open geospatial data](docs/worldseed-preview.png)](https://yz4git.github.io/next-gen/demo/)
+
+*Actual WorldSeed WebGL render of a Tokyo Tower seed. Click the image to open the demo. Live map generation uses external open-data providers; the first-run synthetic demo does not need a geographic coordinate.*
 
-*Live Tokyo Tower seed rendered by the production WebGL build from open geospatial data.*
+### Choose your path
 
-WorldSeed turns a WGS84 latitude and longitude into a local-meter, browser-generated 3D world. Paste coordinates (or a Google Maps URL containing coordinates), choose a 100–1,000 m radius, and immediately orbit, walk, fly, or drive through the result.
+| I want to… | Start here | What I get |
+| --- | --- | --- |
+| **See what WorldSeed looks like** | [Explore the live demo](https://yz4git.github.io/next-gen/demo/) | Orbit, walk, fly or drive through a generated world |
+| **Test the export without installing WorldSeed** | [Five-minute ZIP trial](docs/TRY_WORLDSEED.md) | A synthetic city export opened in an independent consumer |
+| **Build a game or Three.js app** | [Game-development integration guide](docs/REUSE.md#choose-an-integration-path) | GLB meshes, collision geometry, spawn points and roads |
+| **Use GIS or simulation data** | [Semantic-data integration guide](docs/REUSE.md#choose-an-integration-path) | Local-meter semantic objects, provenance and versioned schemas |
 
-Google Maps is only treated as an optional coordinate-input format. WorldSeed does not request, scrape, trace, or derive geometry from Google Maps. World geometry comes from public open-data providers.
+**No account or API key is required for the synthetic export trial.** Running the standalone consumer requires a local HTTP server; the live demo is browser-based. [Download v0.9.1 assets](https://github.com/yz4git/next-gen/releases/tag/v0.9.1) · [Schema v1](docs/SCHEMA_VERSIONING.md) · [Report an integration](https://github.com/yz4git/next-gen/issues/19).
 
 ## Why WorldSeed
 

diff --git a/docs/REUSE.md b/docs/REUSE.md
@@ -2,6 +2,24 @@
 
 WorldSeed is intended to be useful outside the browser UI. A generated seed can be exported as geometry plus structured local-meter gameplay data so another project can treat the city as an input asset rather than a screenshot.
 
+## Choose an integration path
+
+| Developer | Start with | Next step |
+| --- | --- | --- |
+| **Game / Three.js** | `city.glb` + `colliders.glb` + `spawn-points.json` | Load the city mesh, place actors at spawn points, then add collisions |
+| **Simulation / routing** | `road-graph.json` + `worldseed-objects.json` | Build a road-network query or semantic-object overlay |
+| **GIS / DCC / other engines** | `city.glb` + `worldseed.json` + `ATTRIBUTION.md` | Import the geometry, inspect local-meter axes and retain source attribution |
+
+**Fastest reproducible example:** [download the v0.9.1 synthetic export and open it in the standalone consumer](TRY_WORLDSEED.md#option-a--prebuilt-zips-recommended). It requires no WorldSeed generator source, location input, or API key.
+
+**Integration checklist**
+
+1. Verify the export's schema version against [schema compatibility](SCHEMA_VERSIONING.md).
+2. Use local-meter axes: X east, Y up, Z south. Do not assume a globally georeferenced origin exists.
+3. Use `worldseed-objects.json` for semantic identity instead of guessing from GLB mesh names.
+4. Preserve `ATTRIBUTION.md` and check the source-data terms before redistributing exports.
+5. Share a reproducible public integration or report an interoperability issue; see [Issue #20](https://github.com/yz4git/next-gen/issues/20).
+
 ## Export bundle
 
 The starter-kit ZIP currently contains:

diff --git a/docs/TRY_WORLDSEED.md b/docs/TRY_WORLDSEED.md
@@ -1,58 +1,64 @@
 # Try WorldSeed in five minutes
 
-You can test the **schema v1 export contract without building WorldSeed itself**.
+**Goal:** open a real WorldSeed schema-v1 export in an independent viewer, without cloning or building the WorldSeed generator. No account, API key or precise location is needed.
 
-## Option A — use the published demo export
+## Before you start
 
-Download these two assets from the v0.9.1 release:
+You need a desktop browser, a ZIP extraction tool, and Node.js (for the one-command static HTTP server below). This is a *desktop-first* export validation flow; for a quick iPhone experience, use the [browser demo](https://yz4git.github.io/next-gen/demo/).
 
-- [Privacy-safe demo export](https://github.com/yz4git/next-gen/releases/download/v0.9.1/worldseed-demo-export-v0.9.1.zip)
-- [Prebuilt static export consumer](https://github.com/yz4git/next-gen/releases/download/v0.9.1/worldseed-export-consumer-static-v0.9.1.zip)
+## Option A — prebuilt ZIPs (recommended)
 
-The demo export is generated from WorldSeed's synthetic first-run world and intentionally omits the exact WGS84 origin.
+1. Download the [privacy-safe synthetic demo export](https://github.com/yz4git/next-gen/releases/download/v0.9.1/worldseed-demo-export-v0.9.1.zip). **Keep this ZIP compressed.**
+2. Download the [prebuilt standalone consumer](https://github.com/yz4git/next-gen/releases/download/v0.9.1/worldseed-export-consumer-static-v0.9.1.zip). **Extract only the consumer ZIP** into its own directory.
+3. Open a terminal in the *extracted consumer directory* and run:
 
-Unzip the static consumer and serve the directory with any local HTTP server, for example:
+   ```bash
+   npx serve .
+   ```
 
-```bash
-npx serve .
-```
+   If prompted to install `serve`, approve it. Open the local HTTP address printed in the terminal (often `http://localhost:3000`; use the actual printed address).
+4. Drag the **still-zipped** `worldseed-demo-export-v0.9.1.zip` onto the consumer page.
+
+### What success looks like
 
-Open the shown local URL, then drag `worldseed-demo-export-v0.9.1.zip` onto the page.
+- A 3D city appears in the standalone consumer.
+- Road graph lines and vehicle/pedestrian spawn markers can be inspected.
+- The drive route appears when present in the sample.
+- The UI shows metadata such as schema version and object/road counts.
 
-You should see:
+The consumer reads the public export ZIP contract, not WorldSeed's generator source. The sample is synthetic and intentionally omits the exact WGS84 origin.
 
-- the exported city GLB;
-- routable road-graph lines;
-- vehicle and pedestrian spawn markers;
-- the active drive route when present;
-- schema/generator/object/road counts from the exported JSON contract.
+### If it doesn't work
 
-## Option B — consume the source example
+| Symptom | Check |
+| --- | --- |
+| Blank page or assets fail to load | Use the HTTP address printed by `npx serve .`; do not open `index.html` with a `file://` URL. |
+| Consumer loads but nothing renders | Make sure you extracted the **consumer** ZIP, not the **demo export** ZIP. |
+| Drag/drop has no effect | Drop the entire original demo-export ZIP onto the consumer page, not individual files. |
+| Unexpected ZIP or schema error | Use the two assets from the **same v0.9.1 release**; avoid mixing with another export version. |
+| Port already in use | Follow the alternate localhost URL printed by the server or stop the conflicting server. |
 
-Download [worldseed-export-consumer-v0.9.1.zip](https://github.com/yz4git/next-gen/releases/download/v0.9.1/worldseed-export-consumer-v0.9.1.zip), then:
+If the problem persists, [open an issue](https://github.com/yz4git/next-gen/issues/new) with your browser, OS, steps to reproduce and any console error. Avoid sharing private coordinates.
+
+## Option B — source-based standalone consumer
+
+Download [worldseed-export-consumer-v0.9.1.zip](https://github.com/yz4git/next-gen/releases/download/v0.9.1/worldseed-export-consumer-v0.9.1.zip), extract it, and in the extracted project directory run:
 
 ```bash
 npm install
 npm run dev
 ```
 
-Drop either the published demo export or your own WorldSeed **Three.js kit** ZIP onto the page.
+Open the URL printed by Vite. Drop the published synthetic demo export or a WorldSeed **Three.js kit** ZIP onto the page.
 
 ## Build your own integration
 
-The public contract is intentionally independent of WorldSeed internals. A downstream project can consume any combination of:
-
-- `city.glb`, `terrain.glb`, `colliders.glb`;
-- `worldseed-objects.json`;
-- `road-graph.json`;
-- `spawn-points.json`;
-- `drive-route.json`;
-- `schemas/v1/*.schema.json`.
+The public contract is independent of WorldSeed internals. A downstream project can consume `city.glb`, `terrain.glb`, `colliders.glb`, `worldseed-objects.json`, `road-graph.json`, `spawn-points.json`, `drive-route.json`, and `schemas/v1/*.schema.json`.
 
-See [SCHEMA_VERSIONING.md](SCHEMA_VERSIONING.md) before depending on field semantics.
+Read [the integration guide](REUSE.md#choose-an-integration-path) and [schema compatibility rules](SCHEMA_VERSIONING.md) before depending on field semantics.
 
-If you publish a reproducible integration, submit an **Integration report** issue. Verified public integrations are listed in [../ADOPTERS.md](../ADOPTERS.md).
+**Tried it?** Share an independent reproducible example or a five-minute onboarding report in [Issue #23](https://github.com/yz4git/next-gen/issues/23). Public integrations may be listed in [ADOPTERS.md](../ADOPTERS.md) after verification.
 
 ## Privacy note
 
-The published demo export uses synthetic demonstration data and does not include an exact geographic origin. For your own real-world exports, leave **Include exact origin** disabled unless georeferencing is intentionally required.
+The published synthetic export omits an exact geographic origin. For real-world exports, leave **Include exact origin** disabled unless georeferencing is required. Generated data retains its original provider attribution and usage obligations.
diff --git a/index.html b/index.html
@@ -42,6 +42,14 @@
       <main class="workspace">
         <aside class="seed-panel" id="seed-panel">
           <div class="panel-scroll">
+            <section class="visitor-start" aria-label="Quick start">
+              <div class="visitor-start__head"><strong>NEW HERE? START WITH THE DEMO</strong><button id="visitor-start-dismiss" type="button" aria-label="Hide quick start">×</button></div>
+              <p>The sample world is ready to explore. No account, location permission or map download needed.</p>
+              <div class="visitor-start__actions">
+                <button id="visitor-start-explore" type="button">Explore demo →</button>
+                <a href="https://github.com/yz4git/next-gen/blob/main/docs/TRY_WORLDSEED.md" target="_blank" rel="noopener noreferrer">Try an export ↗</a>
+              </div>
+            </section>
             <div class="intro">
               <span class="eyebrow"><i></i> OPEN DATA → DRIVABLE WORLD</span>
               <h1>Drive any city<br />from one coordinate.</h1>

diff --git a/src/main.ts b/src/main.ts
@@ -218,7 +218,21 @@ async function renderData(nextData: WorldData, live: boolean): Promise<void> {
   setBusy(false);
 }
 
+function bindVisitorStart(): void {
+  const panel = document.querySelector<HTMLElement>(".visitor-start");
+  if (!panel) return;
+  document.querySelector<HTMLButtonElement>("#visitor-start-dismiss")?.addEventListener("click", () => {
+    panel.hidden = true;
+  });
+  document.querySelector<HTMLButtonElement>("#visitor-start-explore")?.addEventListener("click", () => {
+    panel.hidden = true;
+    setWorldPanelOpen(false);
+    setMode("orbit");
+  });
+}
+
 function bindUi(): void {
+  bindVisitorStart();
   required<HTMLFormElement>("#seed-form").addEventListener("submit", (event) => {
     event.preventDefault();
     void generateRealWorld();

diff --git a/src/styles.css b/src/styles.css
@@ -398,3 +398,15 @@ button:focus-visible, a:focus-visible, input:focus-visible { outline: 2px solid
 .mutation-actions button:last-child { flex: 0 0 74px; }
 .mutation-actions button:disabled { opacity: .4; cursor: default; }
 .mutation-status { margin: 7px 0 0; color: #98b07e; font-size: 9px; line-height: 1.45; min-height: 26px; }
+
+
+/* First-visit guidance: visible in the seed panel without blocking the WebGL canvas. */
+.visitor-start { margin: 18px 18px 0; padding: 15px; border: 1px solid rgba(184,243,75,.35); border-radius: 12px; background: linear-gradient(135deg, #20301b, #151c16); }
+.visitor-start__head { display: flex; align-items: center; justify-content: space-between; gap: 8px; color: #d4ff98; font-size: 11px; letter-spacing: .06em; }
+.visitor-start__head button { border: 0; background: transparent; color: #d4ff98; font-size: 22px; cursor: pointer; min-width: 32px; min-height: 32px; }
+.visitor-start p { font-size: 12px; line-height: 1.5; color: #dce5d9; margin: 8px 0 12px; }
+.visitor-start__actions { display: flex; gap: 8px; flex-wrap: wrap; }
+.visitor-start__actions button, .visitor-start__actions a { display: inline-flex; align-items: center; justify-content: center; min-height: 40px; padding: 8px 12px; border-radius: 8px; font-size: 12px; font-weight: 700; text-decoration: none; cursor: pointer; }
+.visitor-start__actions button { background: #b8f34b; color: #14200d; border: 1px solid #b8f34b; }
+.visitor-start__actions a { color: #e7f6d3; background: #293729; border: 1px solid #526c45; }
+@media (max-width: 700px) { .visitor-start { margin: 10px 12px 0; padding: 12px; } }