docs: record why the logo artwork exists twice and why overrides/ is a root folder

[shivamlalakiya]

Docs-and-packaging only. No source change, no behaviour change.

Why overrides/ is a separate root folder

It has to be. theme.custom_dir is the only mechanism Material offers for registering a custom icon namespace, and it resolves them from <custom_dir>/.icons/<namespace>/<name>.svg. That path is what icon.logo: philanthropy/heart-rise points at. custom_dir also cannot live inside docs/, because MkDocs copies every non-Markdown file under docs_dir verbatim into the built site, so nesting it would publish the icon at a stray URL.

Both halves verified against the current build rather than assumed:

• docs/assets/logo.svg is copied through to site/assets/logo.svg, which is the behaviour that rules out nesting.
• The icon is inlined into the page markup (its ph-cut mask id appears in index.html) and the string heart-rise appears nowhere in site/.

So the folder is the canonical Material layout and should stay where it is.

Why the artwork exists twice

The two SVGs are not redundant, they use different mechanisms:

• The icon is inlined, so it uses currentColor and follows the header. The palette flips primary between white and black, so a fixed-colour logo would be wrong in one of the two modes.
• The favicon is rendered by the browser outside the page, where currentColor has nothing to resolve against, so it bakes its colours in and carries its own prefers-color-scheme rule.

The actual defect this fixes

Nothing keeps the two copies in step. Changing the logo means editing both files, and no test or build step notices if only one changes. This adds the explanation to mkdocs.yml, which is the single place both assets are wired up, and not to the SVGs themselves, because a comment inside the icon would be inlined into every page.

One packaging gap

MANIFEST.in prunes tests, docs, site, scripts, .github and .hypothesis, but not overrides. It was already absent from the 0.7.1 sdist, but through setuptools' default behaviour rather than through the declaration that is supposed to express it. prune overrides closes the gap.

Verification

mkdocs build --strict          # exit 0, logo still inlined
python -m build --sdist        # 0 entries matching 'overrides'