# Japanese Word Trainer Deck Registry

This repository is the public word-deck data registry for the 0.3 package model.
It keeps JSON as the source of truth and publishes zip package artifacts that the
app can download and verify.

## Layout

- `registry.json` is the root registry file read by the app.
- `sources/official/<slug>/` contains editable official deck package JSON.
- `sources/custom/<slug>/` contains editable published custom deck package JSON.
- `packages/*.zip` contains generated app-installable package artifacts.
- `scripts/build_packages.py` builds packages and refreshes registry checksums.
- `scripts/validate_registry.py` validates source JSON, packages, and checksums.

Each package zip contains exactly:

```text
manifest.json
words.json
refs.json
```

## Build

Run from the repository root:

```bash
python3 scripts/build_packages.py
python3 scripts/validate_registry.py
```

`build_packages.py` fills each word `contentHash`, creates deterministic zip
files in `packages/`, and updates `registry.json` with `wordCount`, `packageUrl`,
and `sha256`.

By default, `generatedAt` is left unchanged to avoid noisy rebuild diffs. Use
`--update-generated-at` when intentionally publishing a freshly generated
registry:

```bash
python3 scripts/build_packages.py --update-generated-at
```

## Package Rules

- Stable deck keys use `{registryId}:deck:{slug}`.
- Stable word keys use `{registryId}:word:{slug-or-id}`.
- `versionCode` changes when package content changes.
- `contentHash` is computed from a word record excluding `contentHash`.
- `refs.json` owns deck membership and display order. A ref may point to a word
  supplied by the same package or to an already installed dependency such as an
  official deck word.
- The same package shape is used for official, registry custom, imported, and
  local-exported decks.

## Current Decks

- `official:deck:jlpt-n5` is a tiny official sample based lightly on the app
  seed vocabulary. It is not the full JLPT N5 set.
- `community:deck:japan-travel-essentials` is a cleaned custom deck generated
  from the user-provided Japan travel CSV, with example sentences added for
  app-side import and study testing.

This repository is still intentionally small so app migration, import, and
checksum handling can be tested before the full public deck corpus is populated.