Skip to content

docs: rewrite README as a positioning-first pitch#20

Merged
kosminus merged 1 commit into
mainfrom
docs/readme-rewrite
Jun 10, 2026
Merged

docs: rewrite README as a positioning-first pitch#20
kosminus merged 1 commit into
mainfrom
docs/readme-rewrite

Conversation

@kosminus

Copy link
Copy Markdown
Owner

What

Rewrites the README as a positioning-first pitch (~200 lines, down from ~850) and relocates the deep documentation it displaced into docs/ — nothing is deleted, only moved.

Why

The old README was excellent documentation but a weak landing page: it opened with an implementation description instead of a value proposition, buried the differentiators (governance, self-hosted/BYO-LLM, MCP) in a 22-bullet feature wall, used none of the 9 screenshots in screenshots/, had a literal <repo-url> placeholder in the Quick Start, and overclaimed the model routing ("haiku → sonnet → opus") versus what the router actually does.

Changes

  • README.md — restructured top-to-bottom:
    • Tagline ("Governed, self-hosted text-to-SQL…") + three-sentence positioning naming the audience, problem, and wedge
    • Badges (CI, MIT, Python 3.12, React 19, connectors) and a hero screenshot (screenshots/query2.png) alongside the demo video
    • Four "Why QueryWise" differentiators replace the flat 22-bullet list; the full feature set survives as a grouped, compact section
    • Quick Start fixed with the real clone URL and an explicit "try everything before connecting your own DB" hook
    • Pipeline diagram corrected: routing now described as complexity classification + token budget (matches app/llm/router.py); roles corrected to viewer/editor/admin
    • Compact sections retained for MCP (teaser + 2 commands), production deployment, security, and the IFRS 9 sample; new Documentation index table
  • docs/mcp.md (new) — full MCP guide: all five client configs (Claude Code/Desktop, Cursor/Windsurf, Copilot, Codex), transports, and the network-reachability matrix
  • docs/configuration.md (new) — env-var table, LLM provider selection + Ollama setup + provider-switching notes, and the host-DB / BigQuery / Databricks connection guides
  • docs/api-reference.md (new) — the REST endpoint tables (plus health probes)
  • docs/development.md (new) — no-Docker setup, test/lint commands, the full project-structure tree, and the connector/LLM-provider extension guides

🤖 Generated with Claude Code

Lead with a tagline, three-sentence positioning, badges, and a hero
screenshot; collapse the 22-bullet feature wall into four
differentiators (semantic-layer accuracy, built-in governance,
self-hosted/BYO-LLM, MCP); fix the placeholder clone URL and the
model-routing overclaim.

Relocate the deep documentation (nothing deleted): MCP client setup to
docs/mcp.md, env vars + provider/connection guides to
docs/configuration.md, REST tables to docs/api-reference.md, and
no-Docker setup + project tree + extension guides to
docs/development.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kosminus kosminus merged commit dd171e5 into main Jun 10, 2026
2 checks passed
@kosminus kosminus deleted the docs/readme-rewrite branch June 10, 2026 04:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant