docs: overhaul documentation for external readers

[SkyeAv]

Documentation-only overhaul aimed at external readers evaluating the project cold: an explicit statement of need, a support pathway, experimental labels on the agent/distill surfaces, runnable tutorial prerequisites, less duplication, and plain-ASCII prose. No code, tests, or config behavior changes; the diff touches only .md files and llms.txt (18 files, +343/-308).

Statement of need and audience

• README ## Statement of need: the problem (per-source Python ingests plus hosted name resolution for tabular biomedical sources), the audience (Translator ingest authors, KG data engineers, bioinformatics groups), and the relation to NCATSTranslator/translator-ingests practice including RIG emission.
• docs/index.md ## Who this is for: the same framing in its own words (the nav-parity guard requires the page lists stay intact, so this is additive prose only).

Support pathway

• README ## Getting help: issues for questions (with the question label) and bugs, CONTRIBUTING.md for development, CLI/configuration references for flag lookup.
• CONTRIBUTING.md ## Getting help: replaces the thinner "Reporting issues" section; covers usage questions, bug/feature templates with the details to include, documentation drift (source files named as the authority), and private security reports via the maintainer emails in CITATION.cff. The repo has GitHub private vulnerability reporting disabled, so the email path is the only private channel today.

Experimental labeling

• All seven surfaces a reader meets the agent/optimize/distill features on now say experimental and that the API may change without notice or a deprecation cycle: README feature bullet + extras table, docs/index.md, docs/installation.md intro + extras table, docs/cli.md command index + per-command admonitions (agent, distill-export, distill-weigh), docs/agent.md title + top warning, examples/agent/README.md, llms.txt.
• Stable surface named: each admonition states the core pipeline (build-kg, validate, validate-kgx, build-fullmap, quick-map) is unaffected.

Runnable prerequisites

• Tutorial: Prerequisites previously said only "Required database: fullmap". They now carry the actual tablassert build-fullmap --output ./fullmap/data/fullmap.redb command, the fullmap: value the graph config expects, a link to the fullmap guide, and an honest time note that obtaining the database is a separate multi-GB step (a reader following the tutorial literally previously failed at Step 4 with no path forward). Step 3's replacement note names the same path.
• README quick start: fullmap: /path/to/fullmap becomes fullmap: ./fullmap with the build step called out and linked.

Concision

• README: the extras prose stops repeating the per-extra install matrix docs/installation.md owns; the missing-extra paragraph compresses to the failure contract plus a pointer.
• docs/installation.md (-57 net lines): four install methods become three in user-first order (PyPI, GitHub main, development from source); the per-extra command block becomes one generic pattern plus a combine example; Development Setup/Upgrading collapse into pointers at docs/development.md and CONTRIBUTING.md; wheels (Linux/macOS) vs sdist (Rust toolchain) coverage is stated where the methods are.
• llms.txt: the Installation Guide entry drops per-extra glosses the installation guide already owns and names the experimental extras.

Plain ASCII prose

• Glyph normalization: every em dash, en dash, ellipsis character, arrow, smart quote, and math glyph in live documentation prose is replaced with ASCII (->, =>, <->, ..., -, <=, >=, x). Appositive em-dash pairs become parentheses, colons, or semicolons as the sentence requires; no comma splices left behind. Code blocks keep their alignment (only glyphs inside them change).
• Deliberate exceptions: the quoted ✓ Stage N · NAME · elapsed progress line in docs/cli.md (verbatim program output from src/tablassert/progress.py) and author-name accents in the README.
• Guard-safe: all replacements verified against the doc-guard suite; no guarded token, table row shape, section anchor, or nav-parity entry changed.

Deferred

• CODE_OF_CONDUCT.md: not added; it is a policy decision needing an enforcement contact.
• ORCIDs in CITATION.cff: not added; the identifiers are the authors' to supply.
• pyproject.toml summary/description wording: untouched to keep the diff docs-only.

Testing

• make check -> exit 0: ruff check all passed, ruff format --check clean, pyright 0 errors, 0 warnings, 0 informations, uv run pytest -n auto -> 1674 passed, 52 skipped, cargo fmt --check clean, cargo test -> 127 passed + 11 passed, 1 ignored + 17 passed + 1 passed, cargo clippy --all-targets -- -D warnings clean
• uv run pytest -q --no-cov tests/test_docs_source_of_truth.py tests/test_docs_examples.py tests/test_docs_cli_coverage.py tests/test_agent_docs.py -> 233 passed (run at every commit)
• uv run mkdocs build --strict -q -> exit 0 (run at every commit)
• git diff --name-only f5b717f..HEAD | rg -v '\.md$|^llms\.txt$' -> empty (docs-only scope confirmed)

Co-authored-by: Gwenlyn Glusman 3977332+gglusman@users.noreply.github.com

[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: da6d6240-d3ed-47f4-ba07-a98480431ca2

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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.}