docs: describe every data category and map the repository in the README

The Layout section listed five of the thirteen categories. It now has a
table with each category's real path pattern, file count and an example,
notes on the year, country, base-model and prefix folders, and what
data/_verify/ is. A short repository map names data/, app/, site/,
TechEngine/ and each workflow and script under .github/, and a new
section points at the related repositories.

Author: Seungpyo1007

README.md

@@ -21,15 +21,65 @@ static-dump generator live in
 
 ## Layout
 
+### Repository map
+
 ```text
-data/brand/<country>/<slug>.json                       # e.g. data/brand/kr/samsung.json
-data/soc/<manufacturer>/<year>/<slug>.json             # data/soc/qualcomm/2024/snapdragon-8-elite.json
-data/smartphone/<brand>/<year>/<slug>.json             # data/smartphone/samsung/2025/galaxy-s25.json
-data/gpu/<manufacturer>/<year>/<segment>/<slug>.json   # data/gpu/nvidia/2025/consumer/geforce-rtx-5090.json
-data/cpu/<manufacturer>/<year>/<segment>/<slug>.json   # data/cpu/intel/2023/consumer/core-i9-14900k.json
+data/         # the dataset: one JSON file per record (categories below)
+app/          # the bundled validator, standard library only (python -m app.validate)
+site/         # the Astro site that GitHub Pages serves, with the generated API
+TechEngine/   # the engine, a submodule pinned to one commit: full validator,
+              # integrity gate, API dump, collectors and verification
+.github/
+  workflows/
+    pr-checks.yml        # read-only checks on every PR into develop or main
+    final-check.yml      # full build and verification of a PR labelled final-check
+    collect.yml          # runs one engine collector by hand; uploads a patch
+    pages.yml            # builds the API and the site from main and deploys them
+  scripts/
+    build-api.sh         # validates, then generates site/public/v1 and openapi.json
+    check_dump.py        # compares the generated API with data/
+    open-collect-pr.sh   # opens the PR for one collect.yml run
 ```
 
-All paths use singular folder names. Slugs are kebab-case and unique within each category.
+### Data
+
+Every record is one JSON file named `<slug>.json`. Folder names are singular,
+slugs are kebab-case and unique within their category. Counts are as of
+November 2026.
+
+| Category | Path under `data/` | Files | Example |
+| --- | --- | ---: | --- |
+| `brand` | `brand/<country>/<slug>.json` | 3,022 | `brand/kr/samsung.json` |
+| `soc` | `soc/<manufacturer>/<year>/<slug>.json` | 2,117 | `soc/qualcomm/2024/snapdragon-8-elite.json` |
+| `cpu` | `cpu/<manufacturer>/<year>/<consumer\|enterprise>/<slug>.json` | 4,517 | `cpu/intel/2023/consumer/core-i9-14900k.json` |
+| `gpu` | `gpu/<manufacturer>/<year>/<consumer\|enterprise>/<slug>.json` | 2,076 | `gpu/nvidia/2025/consumer/geforce-rtx-5090.json` |
+| `smartphone` | `smartphone/<brand>/<year>/<slug>.json` or `smartphone/<brand>/<year>/<base_model>/<slug>.json` | 92,824 | `smartphone/samsung/2025/galaxy-s25.json` |
+| `tablet` | `tablet/<brand>/<year>/<base_model>/<slug>.json` | 3,305 | `tablet/huawei/2020/matepad-t8/matepad-t8.json` |
+| `watch` | `watch/<brand>/<year>/<base_model>/<slug>.json` | 418 | `watch/samsung/2024/galaxy-watch-fe/…` |
+| `pda` | `pda/<brand>/<year>/<base_model>/<slug>.json` | 112 | `pda/hp/2000/ipaq-h3600/ipaq-h3600-base.json` |
+| `laptop` | `laptop/<brand>/<year>/<base_model>/<slug>.json` | 1,966 | `laptop/dell/2017/dell-inspiron-5567/…` |
+| `monitor` | `monitor/<brand>/<year>/<base_model>/<slug>.json` | 231 | `monitor/samsung/2023/samsung-m50b/…` |
+| `device_catalog` | `device_catalog/<brand>/<slug>.json` | 20,366 | `device_catalog/kazam/kazam-thunder-345-lte.json` |
+| `software` | `software/<prefix>/<slug>.json` | 42,493 | `software/sw/sweble.json` |
+| `website` | `website/<prefix>/<slug>.json` | 39,930 | `website/pc/pc-gamer-uk.json` |
+
+- `<year>` is the release year, as in the record's `release_date`.
+- `<country>` is the brand's ISO 3166 country code in lower case. A brand with
+  no sourced country lives under `brand/unknown/`; that is most of them (2,815).
+- `<consumer|enterprise>` is a coarse folder split. A CPU record's own `segment`
+  field is finer: `desktop`, `laptop`, `hedt` or `server`.
+- `<base_model>` groups the variants of one model (memory, storage, region).
+  About a third of the smartphones (31,093) and 44 laptops sit directly in the
+  year folder instead.
+- `<prefix>` is the first two characters of the slug, or the whole slug when it
+  is one character long.
+- `device_catalog` lists device identities (model numbers, codenames) whose
+  release date is unknown, so it has no year folder.
+- `data/_verify/` is not a category. It holds the verification ledger
+  (`ledger.jsonl`), the status aggregate (`status.json`) and the caches under
+  `state/` that TechEngine's verify tools write. Don't edit it by hand.
+
+### Site
 
 The Astro site lives under `site/` and is the deploy target for GitHub Pages.
 [`pages.yml`](.github/workflows/pages.yml) generates the static JSON API from
@@ -101,6 +151,15 @@ A release is a PR from `develop` to `main`; merging it deploys the site.
 The TechEngine pin and the pinned action SHAs are bumped by hand, in a PR into
 `develop` that pr-checks validates like any other; Dependabot is not used.
 
+## Related repositories
+
+| Repository | What it holds |
+| --- | --- |
+| [TechEngine](https://github.com/GetTechAPI/TechEngine) | The engine pinned here as a submodule: validation, the static API generator, the collectors and the verification tiers. |
+| [game-catalog](https://github.com/GetTechAPI/game-catalog) | Video game records. They moved out of this repo in September 2026; `site/public/v1/games/index.json` points there. |
+| [cpu-engineering-samples](https://github.com/GetTechAPI/cpu-engineering-samples) | Engineering-sample CPUs, kept apart from the retail CPUs in `data/cpu/`. |
+| [TechMachine](https://github.com/GetTechAPI/TechMachine) | The organisation's repository health check and the scaffolder for new satellite data repos. |
+
 ## Contributing
 
 Open a PR **against `develop`** with the new/updated JSON file — that is also