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 four focused, self-contained notebooks, each in its own folder:

Folder	Notebook	Covers
1_basic_tutorial/	basic_tutorial.ipynb	Setup, running a validation (pandas/Polars), 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)
4_advanced_usage/	advanced_usage.ipynb	Explicitly defined adapters (incl. PooledAdapter) and filtering rows before validation

• The tutorial is named the Basic Tutorial (1_basic_tutorial/basic_tutorial.ipynb). Its two denser sections — explicit adapters (incl. PooledAdapter) and row filtering — moved into the new 4_advanced_usage/ notebook so the basic tutorial stays focused on the everyday workflow.
• 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). A clean delete-and-regenerate flushed one stale orphan CSV the current multi-source run no longer produces.
• 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.
• Replaced non-ASCII typographic symbols (em-dashes, arrows, ellipses) with ASCII equivalents in the two new/restructured notebooks.
• 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. The basic tutorial links out to the known-issues explanation rather than duplicating the mechanics.

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.
• Removed the "Consolidated Failed Rows (per table)" section from the basic tutorial and the get_consolidated_output_dfs() reference from README.md, since annotated output is the recommended per-table view. docs/getting-started.md and docs/known-issues.md keep their deprecation notices for users still on the legacy accessor.
• CHANGELOG.md gains a Deprecated entry.

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 basic_tutorial.ipynb, advanced_usage.ipynb, and multiple_sources.ipynb end-to-end via nbconvert — no error cells, contiguous execution counts; outputs regenerate into the correct outputs/ folders
• Verified all in-notebook anchor links and cross-notebook/doc references resolve; no stale 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

[zendenleong]

lgtm