diff --git a/README b/README
new file mode 100644
index 0000000..11045ee
--- /dev/null
+++ b/README
@@ -0,0 +1,85 @@
+![Tarot Time Preview](https://code.glowers.club/goyimnose/tarot-time/raw/branch/master/asset/img/index.webp)
+
+# Tarot Time
+
+A web-based esoteric correspondence app for tarot, astrology, calendars, symbols, and related systems.
+
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Git](https://img.shields.io/badge/VCS-Git-F05032?logo=git&logoColor=white)](https://git-scm.com/)
+[![Forgejo Repo](https://img.shields.io/badge/Forgejo-tarot--time-0E9384?logo=forgejo&logoColor=white)](https://code.glowers.club/goyimnose/tarot-time)
+[![Deck Repository](https://img.shields.io/badge/Decks-tarot--deck-1D4ED8)](https://code.glowers.club/goyimnose/tarot-deck)
+
+## Features
+
+- Correspondence explorer for multiple occult/esoteric systems.
+- Tarot deck support via a generated deck registry.
+- Pluggable deck structure using per-deck `deck.json` manifests.
+- Fast local static serving with `http-server`.
+
+## Quick Start
+
+1. Install Node.js: https://nodejs.org/en/download
+2. Clone this repository.
+3. Install dependencies.
+4. Start the app.
+
+```powershell
+git clone https://code.glowers.club/goyimnose/tarot-time.git
+Set-Location .\tarot-time
+npm install
+npm run start
+```
+
+The app opens in your browser (typically at `http://127.0.0.1:8080`).
+
+## Deck Repository (Install Ready)
+
+Use this companion repository for downloadable decks:
+
+- https://code.glowers.club/goyimnose/tarot-deck
+
+Typical flow:
+
+1. Clone the deck repository somewhere local.
+2. Copy one or more deck folders into `asset/tarot deck/`.
+3. Validate and regenerate the deck registry.
+
+```powershell
+git clone https://code.glowers.club/goyimnose/tarot-deck.git
+# Copy selected deck folder(s) into Tarot Time deck directory.
+npm run validate:decks
+npm run start
+```
+
+## Deck Authoring and Validation
+
+Deck discovery is registry-driven and generated automatically.
+
+1. Copy `asset/tarot deck/_template/` to a new folder under `asset/tarot deck/`.
+2. Rename the new folder and update its `deck.json`.
+3. Add card image files matching the naming rules in the manifest.
+4. Run `npm run validate:decks` before publishing/testing.
+5. Run `npm run start` (or `npm run generate:decks`) to rebuild `asset/tarot deck/decks.json`.
+
+Rules and behavior:
+
+- Folders without `deck.json` are ignored.
+- Folders beginning with `_` or `.` are ignored (safe for `_template`).
+- `_template` includes `deck.canonical-map.example.json` for explicit major-card file mapping.
+- `_template/STRUCTURE.md` documents recommended `majors/` and `minors/` layouts.
+- Manifests may override labels with `nameOverrides` and `minorNameOverrides`.
+- Invalid manifests or missing mapped files are skipped with terminal warnings.
+
+## NPM Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run start` | Generate deck registry, then serve the app locally and open `index.html`. |
+| `npm run dev` | Alias of `npm run start`. |
+| `npm run generate:decks` | Rebuild `asset/tarot deck/decks.json`. |
+| `npm run validate:decks` | Strict validation only (no write), exits on manifest/file problems. |
+
+## Project Links
+
+- Main app: https://code.glowers.club/goyimnose/tarot-time
+- Deck repo: https://code.glowers.club/goyimnose/tarot-deck