docs: standardize README and restructure docs/

docs/README.md

@@ -0,0 +1,50 @@
+# Maximum PC Builds Archive — Documentation
+
+An archive of the PC builds published in Maximum PC magazine, kept as part lists in three
+parallel forms, with a scraper that keeps current prices fresh.
+
+```
+Maximum-PC-Builds-Archive/
+├── docs/
+│   ├── README.md          this page
+│   ├── builds.md          the full build index
+│   ├── usage.md           the three representations
+│   ├── architecture.md    how the archive is organised
+│   ├── scraper.md         the daily price updater
+│   ├── faq.md             currencies, accuracy, coverage
+│   ├── troubleshooting.md stale or missing prices
+│   ├── roadmap.md         gaps and non-goals
+│   └── legal/             privacy policy and terms
+├── 2018/ … 2021/          one folder per year, then per month
+├── scraper.py             the price updater
+└── requirements.txt
+```
+
+## Pages
+
+- [Build index](./builds.md) — every build, with links to all three forms
+- [Usage](./usage.md) — which representation to use, and what each gives you
+- [Architecture](./architecture.md) — the folder scheme, the branches, the currencies
+- [Scraper](./scraper.md) — the daily price update
+- [FAQ](./faq.md) — currencies, price accuracy, coverage
+- [Troubleshooting](./troubleshooting.md) — prices not updating, missing builds
+- [Roadmap](./roadmap.md) — gaps and non-goals
+
+## Three representations, three currencies
+
+The same build exists three ways, and the currency differs by design:
+
+| Where                  | Currency         | Shows                   |
+| ---------------------- | ---------------- | ----------------------- |
+| PCPartPicker           | Any it supports  | Current price only      |
+| Markdown, in this repo | Canadian dollars | Printed **and** current |
+| Website, on `gh-pages` | US dollars       | Printed **and** current |
+
+Only the last two preserve the original printed price, which is the point of an archive — the
+interesting figure is the gap between what a build cost then and what it costs now.
+
+## The prices are moving targets
+
+`scraper.py` runs daily and rewrites the current prices in the Markdown files. So the
+repository's history is partly a price series, and any given file is accurate as of its last
+successful run rather than as of the magazine issue.

docs/architecture.md

@@ -0,0 +1,70 @@
+# Maximum PC Builds Archive — Architecture
+
+## Layout
+
+```
+2018/January/{Budget,Mid-Range,Turbo}.md
+2018/February/…
+…
+2021/October/{AMD Budget, AMD Mid-Range, AMD Turbo, Intel Budget, …}.md
+scraper.py
+requirements.txt
+.github/workflows/update-prices.yml
+```
+
+Year, then month, then one file per build tier. The AMD and Intel split appears only in the
+years the magazine used it, so the folder shape follows the source rather than imposing a
+uniform scheme.
+
+## Two branches, two artefacts
+
+| Branch     | Holds                                       |
+| ---------- | ------------------------------------------- |
+| `main`     | Markdown builds, the scraper, documentation |
+| `gh-pages` | The generated website                       |
+
+The website is a **derived artefact**. The Markdown files are the source of truth, and the
+published pages are one rendering of them — which is why the currency can differ between the
+two without either being wrong.
+
+## Three representations, deliberately
+
+| Form         | Currency      | Printed price | Current price             |
+| ------------ | ------------- | ------------- | ------------------------- |
+| PCPartPicker | Any supported | No            | Yes, live                 |
+| Markdown     | CAD           | Yes           | Yes, from the last scrape |
+| Website      | USD           | Yes           | Yes, from the last scrape |
+
+PCPartPicker is a live service and cannot carry a historical figure, which is why the archive
+keeps its own copies. Losing the printed price would leave nothing to compare against, and the
+comparison is the whole point.
+
+The CAD/USD split reflects where each is read rather than an inconsistency.
+
+## Prices are rewritten in place
+
+`scraper.py` runs daily under `update-prices.yml` and edits the current-price column of the
+Markdown files, committing the result.
+
+Two consequences:
+
+- **A build file is accurate as of the last successful run**, not as of the issue date.
+- **The git history is partly a price series.** Every daily commit records what those parts
+  cost that day, which is a more interesting dataset than the files themselves and is not
+  currently surfaced anywhere.
+
+The printed price column is never touched, which is what keeps the archive honest.
+
+## The scraper depends on someone else's markup
+
+Prices come from PCPartPicker, parsed with BeautifulSoup. PCPartPicker aggregates retailers —
+the scraper does not visit Newegg, Amazon, or Best Buy itself.
+
+That makes one site the single point of failure for the whole price-updating story, and a
+layout change there breaks parsing with no warning. See [Scraper](./scraper.md).
+
+## Provenance
+
+The component selections were published by Maximum PC magazine. This repository records which
+parts each build specified and tracks their prices; it does not reproduce the magazine's
+articles or reviews.