Archive docs markdown files

docs/archive/test-coverage-notes.md

@@ -0,0 +1,53 @@
+# Test Coverage Notes
+
+Current quick coverage command, excluding Cython line coverage:
+
+```bash
+uv run --with coverage coverage run --source=src/coolrl_lost_cities -m pytest tests/games/classic
+uv run --with coverage coverage report -m
+uv run --with coverage coverage html -d htmlcov
+```
+
+Latest snapshot:
+
+- `98 passed`
+- `69%` total coverage
+- The report is effectively Python-only because the existing `.pyx` extensions
+  were not built with Cython tracing.
+
+Deferred ideas:
+
+1. Add a tiny coverage helper script if this command becomes common.
+2. Keep normal coverage Python-only by default, so the existing Cython build
+   artifacts stay untouched.
+3. If `.pyx` line coverage becomes useful, run it in a separate `git worktree`
+   or fresh clone. Avoid `build_ext --inplace --force` in the main working tree,
+   because it can overwrite the normal `.so` files with tracing builds.
+4. Gate Cython tracing behind an environment variable such as
+   `CYTHON_COVERAGE=1`.
+5. For tracing builds, enable both Cython line tracing and coverage's Cython
+   plugin:
+
+```python
+compiler_directives={
+    "linetrace": True,
+    # existing directives...
+}
+define_macros=[("CYTHON_TRACE", "1")]
+```
+
+```ini
+[run]
+plugins = Cython.Coverage
+source = src/coolrl_lost_cities
+```
+
+Rough performance expectation:
+
+- Python-only coverage: usually modest overhead.
+- Cython tracing build without coverage: likely noticeable but manageable.
+- Cython tracing plus coverage: can be several times slower, and tight
+  traversal or encoding loops may be much worse.
+
+Practical default: keep the main tree fast and boring. Measure `.pyx` coverage
+only when there is a specific question about the Cython paths.