step3/README.md

# RanaZe: Step 3 Trainer

Environment deployment, database migration, and UAT-to-PRD promotion procedures are documented in [ENVIRONMENTS.md](ENVIRONMENTS.md).

Godot-based USMLE Step 3 study trainer with a bundled ASP.NET Core Questions API.

The gated process for publishing the first Windows alpha through Steam is in
[docs/STEAM_ALPHA_RELEASE_CHECKLIST.md](docs/STEAM_ALPHA_RELEASE_CHECKLIST.md).
The free-access limits, earned-credit rules, paid tokens, and checkout setup are
documented in [docs/ACCESS_ECONOMY.md](docs/ACCESS_ECONOMY.md).

## Local API

Run the Questions API:

```powershell
dotnet run --project api/QuestionsApi/QuestionsApi.csproj
```

For deployed environments, set these as environment variables:

```text
MongoDB__ConnectionString
MongoDB__DatabaseName
Jwt__Key
Jwt__Issuer
Jwt__Audience
```

Default local endpoint:

```text
http://localhost:5008/api/questions/search
```

The Godot client reads this from `project.godot`:

```text
step3/questions_api_url
```

## Browser Pre-Alpha

The Web export is deployed at `https://doctor.ranaze.com` through the existing
Cloudflare, Traefik, and Kubernetes stack. See
[WEB_DEPLOYMENT.md](WEB_DEPLOYMENT.md) for DNS, routing, deployment, and
verification details.

## Question Bank PDF Imports

Use [QBANK_PDF_IMPORT_RUNBOOK.md](QBANK_PDF_IMPORT_RUNBOOK.md) for the complete
OCR, original-authoring, validation, independent-review, reference-review, bulk
insertion, production-verification, and cleanup workflow.

## Question Image Copyright Review

All questions containing images must receive a copyright and licensing review
before publication or distribution. This applies both to newly submitted images
and to every image already stored in the question bank.

For each image-bearing question, document:

- the original source and creator, when known;
- the applicable license or written permission;
- whether attribution is required and where it is displayed;
- whether the image was modified or generated;
- the reviewer and review date.

Do not publish an image when its source or reuse rights cannot be established.
Remove or replace images that fail review. Images added for development or
manual testing are not exempt from this requirement.

Outstanding action: audit every existing question with a non-empty `media`
field before treating the current question bank as cleared for release.

## Question Text Originality Review

Every question must also receive an originality and copyright review before
publication or distribution. Review the stem, lead-in, answer choices,
explanations, follow-up questions, teaching points, and distinctive combinations
of patient details for substantial overlap with copyrighted question banks,
books, articles, screenshots, or other source material.

Changing only names, ages, individual values, or a few words is not sufficient
when the structure, sequence, and expression remain recognizably derived from a
copyrighted source. Clinical facts and concepts may be used, but each question
must express them independently with original organization and wording.

For each reviewed question, document the reviewer, review date, any reference
materials consulted, and whether revisions were required. Do not publish a
question when substantial textual or structural overlap remains unresolved.

Outstanding action: perform this review for every existing question in the
question bank, not only newly submitted questions, before considering the bank
cleared for release.

## Question Verification References

Every question must provide direct reference links to authoritative sources
that allow reviewers to verify the clinical, scientific, statistical, or
ethical information used in the stem, answer key, and explanation. References
are required before publication, even when the tested fact is considered
standard knowledge.

Prefer current primary or authoritative sources, including professional society
guidelines, government health agencies, original research, and official drug or
product labeling. Use secondary sources only when a suitable primary or
authoritative source is unavailable. Link to the specific guideline, article,
or document rather than a search-results page or an organization's home page.

For each question, document:

- at least one direct reference URL;
- the title and publishing organization for each reference;
- which key claim or teaching point the reference supports;
- the date the source was accessed and the reviewer who verified it.

References must support the keyed answer and any management recommendations,
diagnostic thresholds, formulas, or numerical claims. A citation does not grant
permission to copy wording or media; the separate text-originality and image-
copyright requirements still apply. Store each verified source in the question
document's `references` array; published question writes require at least one
complete reference. Legacy questions with an empty array remain readable while
awaiting reference review.

## Variable Distractor Pools

Published questions may contain more than the five choices shown to a learner.
The player always presents the correct answer plus four randomly selected
distractors and keeps that set stable for the duration of the active session.
Choice IDs are stable content identifiers; the A-E labels shown in the player
are based on presentation order and must not be stored as answer analytics.

Add only distractors that are plausible for the exact vignette while remaining
unambiguously incorrect. Every added distractor requires its own explanation,
stem-anchored wrong-answer follow-up, independent accuracy review, and
authoritative reference coverage. There is no required number of additional
distractors: record an exception instead of forcing a weak or co-correct
answer. Do not expand production pools until the v2 exposure-statistics
backfill metric reports completion.

See [QBANK_DISTRACTOR_ENRICHMENT_RUNBOOK.md](QBANK_DISTRACTOR_ENRICHMENT_RUNBOOK.md)
for the repeatable authoring, independent-audit, merge, and production
verification procedure.

## Duplicate Question Review

Every question must be checked for duplicates before publication. This review
must detect both exact duplicates and near-duplicates that test the same concept
with substantially equivalent stems, decisive findings, lead-ins, answer sets,
or teaching objectives despite different wording or external IDs.

Repeated coverage of a learning objective is acceptable when the presentation,
reasoning path, or learner task is meaningfully different. Reject exact copies
and near-duplicates that merely change a patient age, reorder answers, or make
minor value and wording changes. When substantial duplication remains, retain
the stronger question, merge any useful unique teaching material, and remove or
substantially differentiate the other version.

Document the reviewer, review date, compared question IDs, and disposition of
each potential duplicate. Outstanding action: run this review across the entire
existing question bank before considering it cleared for release.

## Push Build

`.github/workflows/questions-api.yml` builds and publishes the Questions API Docker image to GitHub Container Registry on pushes to `main`.

Set deployment hosting to consume:

```text
ghcr.io/<owner>/<repo>/questions-api:latest
```