Restructure example notebooks and add cross-table merge support

[Jamestth]

Summary

Three related changes to the examples and annotated-output feature:

1. Example notebook restructuring

The monolithic examples/vowl_usage_patterns_demo.ipynb (91 cells, ~357 KB) grew unwieldy. Split it into three focused, self-contained notebooks, each in its own folder:

Folder	Notebook	Covers
1_core_tutorial/	core_tutorial.ipynb	Setup, running a validation (pandas/Polars/adapters/filtering), understanding results (ValidationResult, annotated output)
2_multiple_sources/	multiple_sources.ipynb	Validating one contract across multiple sources
3_real_databases/	real_databases.ipynb	Server-side validation with Testcontainers (Postgres/MySQL/Spark/DuckDB ATTACH)

• Each notebook resolves the shared dataset paths on its own (repo-root walk-up) and imports what it needs, so it runs top-to-bottom independently.
• save() calls write to a per-notebook local outputs/ folder; pre-generated reference artifacts moved there via git mv (history preserved).
• Section numbering and titles are scoped per notebook (each starts at 1); removed leftover global "Part N"/section numbers and duplicate banners.
• Fixed relative doc links (../docs → ../../docs now that notebooks sit one level deeper) and repaired 3 corrupted source cells from the original notebook.
• Updated links in README.md, docs/usage-patterns.md, and rewrote examples/README.md.

2. Cross-table merge for annotated output

A subquery-projected referential check now merges onto its anchor table's check_info column instead of becoming a residue (src/vowl/validation/result.py), since its failed-rows query projects only the anchor table's columns. Bare-JOIN referential checks still correctly become residues. Includes expanded tests and expected outputs, and a clarifying docs/known-issues.md update.

3. Deprecate consolidated failed-rows output

get_consolidated_output_dfs() and the output_mode="failed_rows" / "both" save modes (the legacy consolidated failed-rows CSVs) are now deprecated in favour of annotated output (get_annotated_output() / output_mode="annotated").

• get_consolidated_output_dfs() emits a DeprecationWarning and delegates to a private _get_consolidated_output_dfs(), so internal callers (save() in failed_rows/both mode) reuse the grouping without warning.
• save() warns on the deprecated paths: the implicit default (which will flip to "annotated" in a future minor release), explicit "failed_rows", and the failed-rows half of "both". "annotated" stays silent. All warnings use stacklevel=2 so they point at the caller.
• ValidationConfig.output_mode docstring notes the upcoming default change. No behaviour changes yet — existing calls still work, they just warn.
• CHANGELOG.md gains a Deprecated entry; README.md, docs/getting-started.md, and docs/known-issues.md updated.

Test plan

• pytest tests/test_annotated_output.py tests/test_check_reference_variations.py tests/test_usage_patterns.py tests/test_readme_examples.py → 237 passed, 17 skipped (skips are Docker/Java-gated)
• Deprecation paths covered: tests assert the DeprecationWarning fires for each deprecated entry point and that the private _get_consolidated_output_dfs() helper stays silent
• Executed core_tutorial.ipynb and multiple_sources.ipynb end-to-end via nbconvert — no error cells; outputs regenerate into the correct outputs/ folders
• Verified all in-notebook anchor links resolve; no stale cross-notebook references
• Lint green (ruff check, ruff format --check, prettier --check "**/*.md")
• real_databases.ipynb requires Docker (not run in this environment)

🤖 Generated with Claude Code