docs: organise by Diátaxis mode, and keep the old URLs working

[andremsouza]

Each docs page now commits to one Diátaxis mode, and every old URL still works.

The problem

Pages mixed modes. getting-started.md taught a path, offered alternatives, and explained
Kohonen's reasoning. training-modes.md was half reference, half explanation. Mixing modes in one
document is the failure mode Diátaxis exists to name.

The new shape

Tutorial	tutorial/first-map.md
How-to	save-and-load-a-map, reproduce-a-result, use-a-custom-strategy
Reference	options, neighborhood-functions, api, changelog
Explanation	why-isotropy-matters, batch-vs-stepwise, artifact-safety

Two pages are split rather than moved, which is the actual work:

• The separability argument and its measurements come out of the neighborhood reference into
  explanation/why-isotropy-matters.md. A table of constants and a 900-word argument about why an
  outer product of Ricker wavelets is wrong are not the same kind of document.
• The security section comes out of the save-and-load how-to into
  explanation/artifact-safety.md. Someone saving a map wants three lines; someone deciding whether
  to trust a file from a colleague wants the boundary spelled out.

Three how-to pages are new, for tasks 0.4.0 made possible.

Every URL changed, and two of them cannot afford to

mkdocs-redirects maps all seven old paths. Verified in the built site:

/getting-started/         -> ../tutorial/first-map/
/neighborhood-functions/  -> ../reference/neighborhood-functions/
/training-modes/          -> ../explanation/batch-vs-stepwise/
/options-and-types/       -> ../reference/options/
/save-and-load/           -> ../how-to/save-and-load-a-map/
/api/                     -> ../reference/api/
/changelog/               -> ../reference/changelog/

This matters more than it looks. 0.3.0's PyPI description contains /getting-started/ and
/neighborhood-functions/, and a PyPI description can never be edited. Without redirects those
two links 404 permanently, from an artifact nobody can correct.

A supply-chain finding on the plugin itself

I said I would confirm the plugin's provenance before adding it. Doing so turned up something, so
it is pinned to 1.2.2, not the latest 1.2.3:

	canonical mkdocs/mkdocs-redirects	ProperDocs/mkdocs-redirects
stars / created	245 / 2019-04-03	3 / 2026-03-14
archived?	no, still active	no
highest tag	v1.2.2	v1.2.3

PyPI's 1.2.3, published 2026-03-28, declares its source as the second repository — a version the
canonical project never tagged, released from a repo that appeared 14 days earlier, while the
original stayed active and un-archived. The declared source also moved across recent releases:
1.2.1 → datarobot/, 1.2.2 → mkdocs/, 1.2.3 → ProperDocs/.

1.2.2's declared source is the canonical repository and matches its own v1.2.2 tag, so that is the
last release whose provenance can be checked. pyproject.toml records this and says not to bump it
without re-checking who publishes it.

Writing quality

Scanned every page. The pre-existing pages were clean at zero; the two pages I added in #10 and
#11 carried 17 em dashes between them, along with bold used for mid-prose emphasis. That habit
was mine and it is now gone:

• 17 em dashes removed, each replaced by the punctuation its own sentence wanted (colon where the
  clause explains, comma where it continues, full stop where it was propping up two sentences) rather
  than substituted uniformly.
• Bold in [Unreleased] cut from 19 spans to the entry lead-ins. It had ~10× the density of the
  shipped 0.3.0 section.
• One genuine rhetorical triad rewritten. The other 14 flagged "rule-of-three" hits are real
  enumerations — "Gaussian, bubble and Mexican hat" is the actual list of three functions — and are
  left alone.

Severity-5 findings across all documentation: 0.

Also

Corrects the README, which still said the package was "built on NumPy, with scikit-learn for PCA and
standardization" — false since #8 removed scikit-learn.

Verification

• mkdocs build --strict exits 0. Worth stating precisely: my first check grepped stdout for
  ERROR and reported clean while the build was actually failing on a warning about a broken image
  path. --strict turns warnings into errors, so the exit code is the check.
• Redirect stubs confirmed present in the built site, and the new pages confirmed to exist.
• Content preservation checked by word frequency across the whole docs tree, before and after.
  Three words drop, all explained by the two renames (training-modes → batch-vs-stepwise, "Custom
  strategies" → "Use a custom strategy"). Vocabulary grew from 859 to 1015 distinct words.
• 369 tests, 100% coverage, ruff / ruff format / mypy --strict clean, bandit clean, pip-audit
  reports no known vulnerabilities, architecture profile --strict passes.