Docs: finish and expand why-chatlas.qmd

Problem

docs/why-chatlas.qmd ends mid-sentence:

Other frameworks like Pydantic AI and llm do a better

The page currently only compares chatlas against LangChain (via the conversation-history example), and the file is rendered by the site build (listed in docs/_quarto.yml's render: block) but is not linked from any sidebar — docs/_sidebar.yml only covers the API reference, and the get-started/tool-calling/misc sidebar defined in docs/_quarto.yml (lines ~81-121) doesn't include it either. The only inbound link found is docs/index.qmd's "## Why chatlas?" section header, which doesn't appear to hyperlink to why-chatlas.qmd itself. So today the page is essentially orphaned/unfinished content live on the site.

Proposed approach

1. Finish the cut-off sentence and complete the framework comparison using the July 2026 competitive review findings, with honest, specific positioning rather than generic "worse than us" claims:
   • llm: CLI-first, SQLite-backed logging, huge plugin ecosystem — owns shell-scripting and local-model tinkering; chatlas is a library for building the plumbing has to go in your app.
   • Pydantic AI: production agent framework with strong type-safety and structured-output validation baked deep into the agent loop; growing in surface area (graphs, dependency injection) as it matures.
   • LangChain: broad agent-platform/ecosystem (integrations, LangGraph, LangSmith); breadth comes with a steeper learning curve and more indirection for simple chat use cases (as the existing conversation-history example already demonstrates).
   • LiteLLM: gateway/proxy breadth — unify billing/routing across many providers' APIs; complementary to, not a substitute for, an SDK-level chat library like chatlas.
2. Add a short "what chatlas deliberately doesn't do" section: no agent graphs/orchestration, no RAG/vector-store primitives (see docs/misc/RAG.qmd's existing llama-index recommendation), no middleware layer, no multi-provider gateway/proxy.
3. Call out underexploited differentiators that don't get enough airtime elsewhere in the docs: stateful Chat ergonomics (turns retained automatically), batch_chat/batch_chat_text/batch_chat_structured provider-discount batch support (reference/batch_chat.qmd), first-class notebook/console streaming UX, and OpenTelemetry instrumentation out of the box (get-started/monitor.qmd).
4. Fix the orphaned-page problem: either add why-chatlas.qmd to the sidebar (e.g., under the index.qmd entry in docs/_quarto.yml's sidebar contents) or link to it directly from docs/index.qmd's "Why chatlas?" heading — confirm which with the maintainer before choosing.

This issue is a task description, not the content — the actual writing happens in the PR.

Alternatives / prior art

Related to #89 ("Add a why chatlas article", closed — the original article this issue would complete).

Open questions

• Sidebar placement vs. inline link from index.qmd — which is preferred?
• Should the LangChain example be kept as-is, trimmed, or replaced now that other frameworks are being added?

Drafted from a competitive review of llm / Pydantic AI / LangChain / LiteLLM (July 2026); filed via Claude Code on behalf of @cpsievert.

Start with docs/why-chatlas.qmd, then inspect the render and sidebar entries in docs/_quarto.yml, docs/_sidebar.yml, and the Why chatlas? section in docs/index.qmd. Confirm the preferred navigation with the maintainer, complete the comparison and differentiators described in the issue, and verify the finished page is rendered and reachable from the site.