# How to use USDR

Do this first, before any other page:

**One example.** Open the [site](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#example). Click **Run this test**. That is the product. Everything else is optional.

Then pick **one** of the three doors on the [site](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#start). You do not need the rest of the docs first.

[![What you are looking at](figures/what-usdr-is.svg)](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/)

[Open questions](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#/search) · [Map](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#/map) · [Run this test](https://kr8zysho3.github.io/Universal-Science-Discovery/repro/p-b-habitat-percolation-ecology-fss/index.html)

[![Three ways in](figures/use-three-doors.svg)](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#start)

| | Who | What to do | Stop when |
|--|-----|------------|-----------|
| **1. Run the test** | Anyone, no account | Open the [site](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#start). Click **Run the test** (same as **Run this test**). | You have seen a live test. |
| **2. See how two fields connect** | Anyone, no account | On the same page, pick two fields. The map shows a real path through the catalog. | You have seen a path. |
| **3. Add an open question** | You have one gap from your field | Write **one** open question, hypothesis, *or* claimed link. Check it. Send it for review. | Detail: [first records guide](HAPPY_PATH_FIRST_RECORDS.md) |

If you **operate** this site, not visiting: [keep the catalog honest](#keep-the-catalog-honest). Night crew adds harvested open questions by itself.

## Run the test

No account. Open the [site](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#example) and click **Run this test**. That opens the habitat / percolation check in the browser. If it says INCONCLUSIVE, the demo is small — not that the idea is false.

## See how two fields connect

On the [site](https://kr8zysho3.github.io/Universal-Science-Discovery/dashboard/#/map), pick two fields (default physics → conservation). The path is from the catalog graph, not a guess. The top bar **Map** is the same place.

## Add an open question

On the site, click **Add an open question**. Records are short structured notes. Sending one for review means a person reads it before it joins the catalog.

## Keep the catalog honest

Only if you run this site. Follow the one list: [Operate this catalog](OPERATE.md). Adding a record: [catalog batch](CATALOG_BATCH.md). Longer appendix: [DEV_DASHBOARD.md](DEV_DASHBOARD.md). The night crew adds harvested open questions by itself — you do not run YAML.

## Words we avoid on the front door

| Instead of | We say |
|------------|--------|
| clone / fork / repo | get a copy of the catalog / this project |
| YAML | a record (the file format is a later detail) |
| PR / pull request | send it for review |
| CI is green | checks passed |
| git-native | the catalog files are the source |
| xref hygiene | fix a broken link |
| maintainer | someone who operates the site |

## Where the long docs sit

| Need | File |
|------|------|
| Why the developer is building this | [WHY.md](WHY.md) |
| What we build next | [ROADMAP.md](../ROADMAP.md) |
| First records (step-by-step) | [HAPPY_PATH_FIRST_RECORDS.md](HAPPY_PATH_FIRST_RECORDS.md) |
| How the tests work | [CROSSCHECK.md](CROSSCHECK.md) |
| Claims vs speculation | [METHODOLOGY.md](METHODOLOGY.md), [VISION_AND_SCOPE.md](VISION_AND_SCOPE.md) |
| Operator command list | [OPERATE.md](OPERATE.md) |
| Operator checklist (long) | [DEV_DASHBOARD.md](DEV_DASHBOARD.md) |
| Full contributor guide | [CONTRIBUTING.md](../CONTRIBUTING.md) |

This page is how a visitor should hear the project. GitHub words belong in the contributor guide, not on the first screen.