docs: sync wiki with the shipped system

[PhilippTheServer]

Closes #1

The wiki was last updated on 2025-12-07. This brings it back in line with what is actually
running, and adds a check so the next nine months of drift are noisy rather than silent.

What was wrong

Beyond being incomplete, several pages described a system that was never built:

Page	Claimed	Reality
home.md	MySQL	PostgreSQL 17
home.md	Elasticsearch / Logstash / Kibana, Nginx gateway	In no compose file
Database/Architecture.md	shops, categories, item_categories, item_media, attributes, item_attributes, item_events	None of these tables exist. 12 tables do, with item detail in JSONB
Getting-Started.md	git clone PhilippTheServer/opentaberna	Four repositories
Getting-Started.md	/api/v1/items	/v1/items/
Getting-Started.md	GET /health → {"status":"healthy","version":"0.1.0"}	{"status":"ok","timestamp":...}
Getting-Started.md	GET / returns the API version	404

Nothing documented the authorization model, the order lifecycle, payments, the outbox,
returns, inventory, object storage or the storefront.

What changed

Every page rewritten against the running stack. Two new pages — Authorization.md and
Orders-and-Fulfillment.md — cover subsystems the wiki had never mentioned.

The database page keeps the old normalised design under "The road not taken", labelled as
a proposal, with the trade-off it was rejected for. A proposal read as a description is how
this drift started.

Verification

tools/check_wiki.py fails when the wiki drifts from the API: an endpoint no page
mentions, a documented path the API does not serve, or an internal link to a page that
does not exist. It reads a committed openapi.snapshot.json, so CI needs nothing running.

Against the old wiki content — the state this issue is about:

$ python3 tools/check_wiki.py
Checked 6 pages against 26 API paths.

27 problem(s):

  FAIL  API serves `/health/ready`, but no wiki page mentions it
  FAIL  API serves `/health`, but no wiki page mentions it
  FAIL  API serves `/v1/admin/inventory/by-sku/{}`, but no wiki page mentions it
  FAIL  API serves `/v1/admin/orders/pick-list`, but no wiki page mentions it
  FAIL  API serves `/v1/admin/orders/{}/label`, but no wiki page mentions it
  FAIL  API serves `/v1/admin/returns/{}`, but no wiki page mentions it
  FAIL  API serves `/v1/customers/me/addresses/{}`, but no wiki page mentions it
  ... 20 more

Against this branch:

$ python3 tools/check_wiki.py
Checked 8 pages against 26 API paths.
OK — every endpoint is documented, and every documented path exists.

The snapshot was generated from a live instance of the current main of
OpenTaberna/fastapi (26 paths), with the full dev stack running. All facts in these pages
— endpoints, health payloads, table columns, constraints, config defaults, the token flow —
were read from that running system or from source, not from the previous pages.

All four Mermaid diagrams were checked to render:

$ mmdc -i <each>.mmd -o <each>.svg
Architecture_0.mmd               OK
Orders-and-Fulfillment_0.mmd     OK
home_0.mmd                       OK
home_1.mmd                       OK

CI runs the check on every push and PR (.github/workflows/check-wiki.yml). It has not run
on this branch yet — this is the first workflow in the repository.

Also here

tools/serve.py renders the wiki locally at http://localhost:8090 with Mermaid and
working internal links, so pages can be reviewed before publishing. Standard library only.

One thing left for a human

Database/database_diagram_layout.jpg is now unreferenced — it pictures the schema that was
never built. I have left it in place rather than delete it unasked. Worth removing in a
follow-up if nobody wants it.