docs: README restructure with quickstart, benchmarks, and a collapsed usage guide

README.md

@@ -31,9 +31,9 @@
 <details open>
 <summary><h2>Updates</h2></summary>
 
-- [2026/08] 🔥 [**PageIndex SDK**](#quickstart) — `pip install -U pageindex` now ships **local mode**: index, retrieve, and chat entirely on your machine with your own LLM key, or point the same client at PageIndex Cloud with an API key.
-- [2026/08] ⚡ [**PageIndex Flash**](#step-2-build-the-tree-index) — tree structure generation from PDFs in seconds, with structure extracted heuristically instead of by an LLM.
-- [PageIndex Chat](https://chat.pageindex.ai) — a human-like document analysis agent for long professional documents. Also available via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
+- [2026/08] 🔥 [**PageIndex SDK**](#quickstart): `pip install -U pageindex` now ships **local mode**: index, retrieve, and chat entirely on your machine with your own LLM key, or point the same client at PageIndex Cloud with an API key.
+- [2026/08] ⚡ [**PageIndex Flash**](#step-2-build-the-tree-index): tree structure generation from PDFs in seconds, with structure extracted heuristically instead of by an LLM.
+- [PageIndex Chat](https://chat.pageindex.ai): a human-like document analysis agent for long professional documents. Also available via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
 
 </details>
 
@@ -43,10 +43,10 @@
 
 Are you frustrated with vector database retrieval accuracy for long and complex documents? Vector-based RAG retrieves by semantic **similarity**. But **similarity ≠ relevance** — what retrieval actually needs is relevance, and relevance requires **reasoning**. On professional documents that demand contextual understanding, domain expertise, and multi-step reasoning, similarity search misses what is relevant but not similar, and returns what is similar but not relevant.
 
-Inspired by AlphaGo, **[PageIndex](https://vectify.ai/pageindex)** replaces the vector index with a **hierarchical tree index** and lets an LLM **reason** its way through it — the way a human expert flips to the right section of a long report. Retrieval happens in two steps:
+Inspired by AlphaGo, **[PageIndex](https://vectify.ai/pageindex)** replaces the vector index with a **hierarchical tree index** and lets an LLM **reason** its way through it, the way a human expert turns to and reads the right section of a long report. Retrieval happens in two steps:
 
-1. **Index** — generate a **tree-structure index** for each document
-2. **Retrieve** — retrieve information via LLM-based **tree search**
+1. **Index**: generate a **tree-structure index** for each document
+2. **Retrieve**: **search that tree** with LLM reasoning, agentically
 
 <div align="center">
   <a href="https://pageindex.ai/blog/pageindex-intro" target="_blank" title="The PageIndex Framework">
@@ -55,19 +55,23 @@ Inspired by AlphaGo, **[PageIndex](https://vectify.ai/pageindex)** replaces the
 </div>
 
 
+### Why it works
+
+> PageIndex is a vectorless, reasoning-based RAG engine that mirrors how humans read, delivering traceable, explainable, and context-aware retrieval, without vector databases or chunking.
+
 ### Compare with Vector RAG
 
 | | Vector RAG | **PageIndex** |
 |---|---|---|
 | **Index** | vector index | tree index |
 | **Unit** | fixed-size chunks | natural sections |
-| **Retrieval** | semantic similarity search | LLM-based relevance search |
+| **Retrieval** | semantic similarity search | LLM reasoning over the tree |
 | **Result** | opaque, “vibe retrieval” | traceable to explicit references |
-| **Context** | query embedding only | full context: conversation history, domain knowledge |
+| **Context** | query embedding only | full context: conversation history, domain knowledge, etc. |
 
-It is ideal for financial reports, legal documents, regulatory filings, technical manuals, medical literature, academic textbooks — any long, complex professional document.
+It is ideal for financial reports, legal documents, regulatory filings, technical manuals, medical literature, academic textbooks, and any other long, complex professional document.
 
-> PageIndex achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench (financial document QA benchmark), vastly outperforming vector-based RAG — see [Benchmarks](#benchmarks).
+> PageIndex achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench (financial document QA benchmark), vastly outperforming vector-based RAG (see [Benchmarks](#benchmarks)).
 
 
 
@@ -85,8 +89,8 @@ from pageindex import PageIndexClient
 os.environ["OPENAI_API_KEY"] = "your-openai-key"
 
 client = PageIndexClient(                     
-    index_model="gpt-5.6-luna",               # model to build the tree index
-    chat_model="gpt-5.6-sol",                 # model to search the tree
+    index="gpt-5.6-luna",               # model to build the tree index
+    chat="gpt-5.6-sol",                 # model to search the tree
 )
 doc_id = client.submit_document("report.pdf")["doc_id"]
 
@@ -95,31 +99,62 @@ answer = client.chat("What was the 2023 operating margin, and where is it stated
 print(answer)
 ```
 
-
 ### Model Recommendations
 
-- **`index_model` — a basic model is sufficient.** The index model generates the document's tree index. A basic model is sufficient to produce a good tree structure.
-- **`chat_model` — use the best model you can afford.** The chat model searches the tree to retrieve information. See [Query cost and accuracy](#query-cost-and-accuracy).
+- **`index=`: a basic model is sufficient.** The index model generates the document's tree index. A basic model is sufficient to produce a good tree structure.
+- **`chat=`: use the best model you can afford.** The chat model searches the tree to retrieve information. See [Query cost and accuracy](#query-cost-and-accuracy).
+
+See the [Detailed Usage Guide](#detailed-usage-guide) to configure other models, or [integrate PageIndex with your own agent](#integrate-with-your-own-agent).
+
+### Get Answers with Citations
+
+To request inline page-level citations, pass a system message together with the question:
+
+```python
+messages = [
+    {
+        "role": "system",
+        "content": (
+            'Cite only statements supported by tool outputs using '
+            '<cite doc="{docName}" page="{pageNumber}"/>'
+        ),
+    },
+    {"role": "user", "content": "Summarize the document."},
+]
+
+answer = client.chat(messages, doc_id=doc_id)
+```
 
-See the [Detailed Usage Guide](#detailed-usage-guide) to configure other models and integrate PageIndex with your own agent.
+The model fills in the document name and page number, for example:
+
+```text
+Revenue increased during the reporting period. <cite doc="report.pdf" page="12"/>
+```
 
 
 ## Benchmarks
 
-### Indexing cost
+### Indexing cost and time
 
-Building a tree locally runs **about $0.001 per page** with `index_model="gpt-5.6-luna"` — so a 1,000-page textbook costs a little over a dollar and a few minutes, once, and every later question reuses it. PageIndex is designed not to rely heavily on the model used at index time, so in our experiments a basic model does not hurt quality.
+Building a tree locally runs **about $0.001 per page** with `index_model="gpt-5.6-luna"`, so a 1,000-page textbook costs a little over a dollar and a few minutes, once, and every later question reuses it. PageIndex is designed not to rely heavily on the model used at index time, so in our experiments a basic model does not hurt quality.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="assets/index-cost-dark.png">
   <img src="assets/index-cost-light.png" alt="Indexing cost against document length, log-log, for nine PDFs from 9 to 1,098 pages. Points track a $0.0011-per-page reference line; the spread around it is text density, not length.">
 </picture>
 
+Indexing time also scales predictably with document length. In the same local setup, the benchmark documents (9 to 1,098 pages) finished in roughly **13 seconds to 4.5 minutes**.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/index-time-dark.png">
+  <img src="assets/index-time-light.png" alt="Indexing time against document length, log-log, for nine PDFs from 9 to 1,098 pages. The measured indexing times range from about 13 seconds to 4.5 minutes and increase predictably with document length.">
+</picture>
+
 
 
 ### Query cost and accuracy
 
-[**PageIndex-OSS-Benchmark**](https://github.com/VectifyAI/PageIndex-OSS-Benchmark) measures exactly the setup in the quickstart above — `PageIndexClient()` in local mode, flash indexing, no OCR — on 62 lookup questions over 34 PDFs (1,945 pages) drawn from [MMLongBench-Doc-V2](https://github.com/VectifyAI/MMLongBench-Doc-V2). Every question's answer is a fact stated in running text, so a wrong answer is a **retrieval or reading failure**, not a reasoning one.
+[**PageIndex-OSS-Benchmark**](https://github.com/VectifyAI/PageIndex-OSS-Benchmark) measures exactly the setup in the quickstart above (`PageIndexClient()` in local mode, flash indexing, no OCR) on 62 lookup questions over 34 PDFs (1,945 pages) drawn from [MMLongBench-Doc-V2](https://github.com/VectifyAI/MMLongBench-Doc-V2). Every question's answer is a fact stated in running text, so a wrong answer is a **retrieval or reading failure**, not a reasoning one.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="assets/results-dark.png">
@@ -163,25 +198,27 @@ client = PageIndexClient(
 
 - **`storage_path`** specifies where indexed documents are stored locally.
 
+`index_model=` / `chat_model=` are the flat spellings of the quickstart's `index=` / `chat=`; either spelling works.
+
 #### Model naming conventions
 
 Model names follow [LiteLLM's naming convention](https://docs.litellm.ai/docs/providers). Choose the format that matches your provider:
 
-**OpenAI** — use the model name directly and set `OPENAI_API_KEY`:
+**OpenAI**: use the model name directly and set `OPENAI_API_KEY`:
 
 ```python
 os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
 chat_model = "gpt-5.6-sol"
 ```
 
-**Anthropic** — prefix the model name with `anthropic/` and set `ANTHROPIC_API_KEY`:
+**Anthropic**: prefix the model name with `anthropic/` and set `ANTHROPIC_API_KEY`:
 
 ```python
 os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"
 chat_model = "anthropic/claude-sonnet-4-6"
 ```
 
-**OpenRouter** — prefix the provider and model name with `openrouter/` and set `OPENROUTER_API_KEY`:
+**OpenRouter**: prefix the provider and model name with `openrouter/` and set `OPENROUTER_API_KEY`:
 
 ```python
 os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key"
@@ -204,11 +241,11 @@ doc_id = client.submit_document("report.pdf")["doc_id"]
 Inspect what you got:
 
 ```python
-tree = client.get_document_structure(doc_id)    # titles, page ranges, summaries — no text
+tree = client.get_document_structure(doc_id)    # titles, page ranges, summaries; no text
 client.list_documents()                         # everything you have indexed
 ```
 
-A PageIndex tree looks like this — a table of contents optimized for LLMs and agents:
+A PageIndex tree looks like a table of contents optimized for LLMs and agents:
 
 ```jsonc
 {
@@ -287,7 +324,17 @@ Uses Anthropic's native Messages API and tool runner. Install it with `pip insta
 
 Pass a list of ids to `doc_id` to search several documents at once, and keep it identical across a conversation's calls.
 
-### 🤖 Integrate PageIndex with your own agent
+</details>
+
+<a id="integrate-with-your-own-agent"></a>
+<details>
+<summary>
+
+## Integrate PageIndex with your own agent
+
+</summary>
+
+<br>
 
 Instead of calling PageIndex's agent, hand PageIndex's tools to yours. One call fills every slot:
 
@@ -329,38 +376,56 @@ tools = client.agent_tools()
 
 `agent_tools()` returns plain Python functions that work with LangChain, PydanticAI, and other agent frameworks.
 
-Each `*_config` helper is sugar over the explicit pieces — `client.agent_instructions()` for the system prompt and `client.as_openai_tools()` / `as_anthropic_tools()` / `as_claude_mcp()` for the tools — so you can swap in your own prompt whenever you need to. Locally, `doc_id` is enforced at the tool layer, not just prompted: out-of-scope lookups return `NOT_FOUND`.
+Each `*_config` helper is sugar over the explicit pieces (`client.agent_instructions()` for the system prompt, `client.as_openai_tools()` / `as_anthropic_tools()` / `as_claude_mcp()` for the tools), so you can swap in your own prompt whenever you need to. Locally, `doc_id` is enforced at the tool layer, not just prompted: out-of-scope lookups return `NOT_FOUND`.
+
 </details>
 
 
 ## PageIndex Cloud
 
-The open-source version is designed for text-heavy PDFs. For scanned documents or PDFs with many images, use PageIndex Cloud.
+The open-source version is ideal for text-heavy PDFs and local workflows. With **PageIndex Cloud, document indexing and storage run in the cloud**: PageIndex handles parsing, OCR, image understanding, tree-index construction, and managed storage for you. The chat and retrieval layer remains **compatible with your model**, so you can search the cloud-hosted index using the model provider your application already uses.
 
-Same client, same methods — pass a [PageIndex API key](https://dash.pageindex.ai/api-keys) and the work happens on our servers, with the production OCR, tree-building, and retrieval pipeline behind it:
+Moving indexing and storage from Local to Cloud only requires a [PageIndex API key](https://developer.pageindex.ai/):
 
 ```python
-client = PageIndexClient(api_key="pi-...")
+import os
+from pageindex import PageIndexClient
+
+os.environ["PAGEINDEX_API_KEY"] = "your-pageindex-key"
+os.environ["OPENAI_API_KEY"] = "your-openai-key"
+
+
+client = PageIndexClient(
+    index="cloud",                       # build and store the index in PageIndex Cloud
+    chat="gpt-5.6-sol",                  # use your preferred compatible model for chat
+)
+
+# The rest of your code stays the same (wait=True: cloud indexing is asynchronous)
 doc_id = client.submit_document("report.pdf", wait=True)["doc_id"]
 print(client.chat("What was the 2023 operating margin?", doc_id=doc_id))
 ```
 
-| | **Local** (this repo) | **Cloud** ([API key](https://dash.pageindex.ai/api-keys)) |
+| Capability | **Local** (this repo) | **Cloud** ([get an API key](https://developer.pageindex.ai/)) |
 |---|---|---|
-| Parsing | text extraction | hosted OCR |
-| Data storage | local | cloud |
-| Citations & references | page-level | line-level |
-| Image retrieval & understanding | — | ✅ |
-| PageIndex File System | — | ✅ |
+| Best for | text-heavy PDFs and local workflows | scanned, image-heavy, and large document collections |
+| Indexing | runs locally | runs in PageIndex Cloud, with production OCR and image understanding |
+| Storage | local | managed in PageIndex Cloud |
+| Chat model | your model | your model, or the managed chat included with your key |
+| Citations | page-level | line-level |
+| Image understanding | — | ✅ |
+| Multi-document scale | manual | PageIndex File System |
 | MCP server | — | ✅ |
 
 ### More About PageIndex Cloud
 
-- [Scale PageIndex to Millions of Documents](https://pageindex.ai/blog/pageindex-filesystem) — **PageIndex File System** is a Cloud-only, file-level tree indexing layer that lets PageIndex reason over an entire corpus, not just a single document.
-- [Developer Dashboard](https://developer.pageindex.ai/) — manage your API keys and projects.
-- [PageIndex Cloud documentation](https://docs.pageindex.ai/) — explore API guides and reference documentation.
+- [Scale PageIndex to Millions of Documents](https://pageindex.ai/blog/pageindex-filesystem): **PageIndex File System** is a Cloud-only, file-level tree indexing layer that lets PageIndex reason over an entire corpus, not just a single document.
+
+### Ready to Try It?
+
+- [Get a PageIndex API Key](https://developer.pageindex.ai/)
+- [Read the PageIndex Cloud Documentation](https://docs.pageindex.ai/)
 
-For dedicated or private deployment (VPC, on-prem), [contact us](https://ii2abc2jejf.typeform.com/to/gVv7qkaN) or [book a demo](https://calendly.com/pageindex/meet).
+For dedicated deployment (VPC or on-premises), [contact us](https://ii2abc2jejf.typeform.com/to/gVv7qkaN) or [book a demo](https://calendly.com/pageindex/meet).