docs: reconcile every user-facing surface with the source (17.0.0)

[SkyeAv]

Reconciles the user-facing documentation with the live Tablassert schemas, CLI, optional extras, workflows, and contributor tooling, while adding source-derived guards so the same drift fails tests instead of silently returning.

Documentation accuracy

• README quick start: Corrects the table configuration's scalar source.url to the list-valued form required by BaseSource.url, and brings the documentation links into parity with the published MkDocs navigation.
• Installation and extras: Documents all seven optional extras, including distill, its datasets>=3.0.0 requirement, preflight ordering, and the distinction between zero-dependency agent --distill recording and distill-export requiring [distill].
• Configuration reference: Documents NodeEncoding.exclude_prefixes and exclude_regex, including exact prefix behavior, case-sensitive regex filtering, validation of empty patterns, post-resolution filtering, and qualifier inheritance.
• API references: Synchronizes resolve(), fullmap_audit(), and resolve_many() documentation with their live signatures and behavior, including exclusion filters and the on_phase callback labels. Separates the .tablassert/log directory from the tablassert.log file.
• Machine-readable index: Rebuilds llms.txt's implementation and documentation index around the live Python modules, canonical Rust stub, Biolink vocabulary, Graph fields, six-command CLI, four workflows, and MkDocs navigation. Removes retired configuration labels and the nonexistent Docker workflow.
• Agent guide: Replaces stale exact-pin claims with the live lower-bound requirements for smolagents, litellm, and dspy, and adds --distill and --task-model to the compact flag reminder.
• Contributor guide: Removes stale test-count, Rust-count, coverage, and CI-sharding claims; synchronizes the CI dependency set and pre-commit installation rationale; and adds the missing examples/, .github/, and Makefile layout entries.
• Changelog: Adds a top Unreleased documentation section in CHANGELOG.md without modifying existing release history.

Drift guards

• Adds tests/test_docs_source_of_truth.py.
• Derives expectations from live Pydantic models, inspect.signature, Cyclopts metadata, pyproject.toml, MkDocs YAML, workflow files, the Makefile, AST call sites, and filesystem listings.
• Guards YAML snippets, configuration fields, API signatures, optional extras, workflow purposes, CLI commands, module indexing, navigation coverage, contributor-guide claims, and Makefile targets.
• Keeps the existing documentation guard suites unchanged in intent.

Design and scope

• No product source, Rust source, dependencies, lockfiles, workflows, or build configuration were changed.
• The branch retains one coherent conventional docs: commit per Ralph story rather than rewriting history into one commit. No reset, rebase, force-push, or other history mutation was performed.
• MkDocs emits the existing upstream Material-for-MkDocs advisory about future MkDocs 2.0 compatibility, but the strict build exits successfully.

Follow-ups

• src/tablassert/errors.py still points DOCS_URL at https://tablassert.readthedocs.io/errors/, although the project publishes at https://skyeav.github.io/Tablassert/ and has no corresponding errors page. Fixing this is a source decision outside this documentation-drift pass.
• 32 of the 38 TablassertErrorCodes values remain undocumented. An error-code reference should be added after the DOCS_URL decision.
• The historical sharding comment in .pre-commit-config.yaml remains unchanged because automation configuration was explicitly out of scope for this docs-only pass.

Testing

• uv run ruff check . → passed.
• uv run ruff format --check . → 85 files already formatted.
• uv run pyright → 0 errors, 0 warnings, 0 informations.
• uv run pytest → 1297 passed, 43 skipped, 87% coverage.
• cargo fmt --check --manifest-path rust/Cargo.toml → passed.
• cargo test --manifest-path rust/Cargo.toml → 131 passed, 1 ignored.
• cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings → passed.
• uv run mkdocs build --strict → passed.
• Independent whole-change audit → PASS.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ac8e8620-9bbb-4be5-9450-0463556781d8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}