Improve GitHub identity and SEO docs

Author: RossDmello2

CONTRIBUTING.md

@@ -21,6 +21,13 @@ python -m pytest
 
 These checks do not download or run GPU models. Real ColQwen2 and Qwen2.5-VL verification should be done separately on a CUDA machine and marked clearly in the pull request.
 
+## Behavior Changes
+
+- Edit the notebook when changing the authoritative workflow.
+- Edit `src/visorag/` when changing the maintainable package surface.
+- Update tests whenever public request validation, response contracts, supported file types, query types, or lazy-loading behavior changes.
+- If the package intentionally diverges from the notebook, document the migration in `docs/source-of-truth.md` and the pull request.
+
 ## Pull Request Checklist
 
 - Notebook JSON parses and code cells AST-parse without executing GPU models.

README.md

@@ -1,21 +1,51 @@
 # VisoRAG
 
-Vision-first document RAG with ColQwen2, Qwen2.5-VL, Qdrant, and FastAPI for PDF/image question answering and field extraction.
+**VisualDocQA Kit for local GPU document RAG.**
+
+Vision-first document RAG with ColQwen2, Qwen2.5-VL, Qdrant, and FastAPI for PDF, DOCX, and image question answering and field extraction.
 
 [![CI](https://github.com/RossDmello2/visorag/actions/workflows/ci.yml/badge.svg)](https://github.com/RossDmello2/visorag/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-VisoRAG is a notebook-originated visual retrieval system for PDFs, DOCX files, and images. It renders documents to page images, embeds them with ColQwen2, stores each request in an in-memory Qdrant MaxSim collection, retrieves relevant pages, and answers with local Qwen2.5-VL inference. It is for developers and researchers who want a small, source-readable baseline for visual document question answering, field extraction, and multimodal RAG experiments.
+VisoRAG is a notebook-originated visual document QA and extraction baseline. It renders documents as page images, embeds the pages with ColQwen2, retrieves relevant pages through an in-memory Qdrant MaxSim collection, and answers with local Qwen2.5-VL through a FastAPI API or CLI. It is meant for developers, students, and researchers who want a source-readable visual RAG reference rather than a hosted multi-user product.
 
-## Preview
+## Read This First
 
-![Conceptual VisoRAG document retrieval flow](docs/assets/brand/hero.png)
+| Area | Status | What it means |
+| --- | --- | --- |
+| Dev verification | Ready | `.[dev]` runs import, API, notebook, lint, and mocked tests without GPU model downloads. |
+| Real inference | Requires CUDA | `.[gpu]`, model downloads, and a CUDA GPU are required for ColQwen2 and Qwen2.5-VL. |
+| Production deployment | Not hardened | Use a gateway, TLS, restricted CORS, strong token, private logs, and GPU capacity planning first. |
 
-The banner above is generated conceptual artwork, not an application screenshot. It illustrates the repository's real workflow: document pages move through visual retrieval, vector search, and local vision-language answer generation.
+No custom web frontend is included in this clean release. The visible product surface is the FastAPI API, CLI, notebook, docs, and tests.
+
+## Preview
 
 ![Real FastAPI Swagger documentation for VisoRAG](docs/assets/screenshots/api-docs.png)
 
-The API screenshot is captured from the local FastAPI `/docs` route. See [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md) for capture details.
+This is a real screenshot from the local FastAPI `/docs` route. It shows the actual public API surface.
+
+![Conceptual VisoRAG social preview showing document pages flowing through retrieval into a JSON answer](docs/assets/brand/social-preview.png)
+
+This is generated conceptual artwork for repository sharing. It is not a product screenshot and does not show a real query result.
+
+## What It Solves
+
+Traditional document RAG often starts by extracting text, which can lose layout, tables, charts, figures, and scanned-page context. VisoRAG keeps the document as images first: pages are rendered visually, embedded as page images, retrieved by visual similarity, and passed to a local vision-language model for answering or field extraction.
+
+Good fits:
+
+- Exploring visual document RAG architecture.
+- Building a local GPU baseline for PDF/image QA.
+- Testing field extraction response contracts.
+- Learning how to package a notebook workflow as a FastAPI/CLI project.
+
+Not good fits yet:
+
+- CPU-only inference.
+- Hosted multi-user SaaS.
+- Production document ingestion without additional security controls.
+- Persistent vector search over a long-lived document corpus.
 
 ## Source of Truth
 
@@ -26,46 +56,24 @@ The Python package in `src/visorag/` is the contributor-friendly extraction of t
 ## Features
 
 - Vision-first document QA without OCR-first text extraction.
-- PDF, DOCX, PNG, JPG, and JPEG input support.
-- ColQwen2 page embedding and Qdrant in-memory multivector MaxSim retrieval.
+- PDF, DOCX, PNG, JPG, and JPEG input support in the real GPU runtime.
+- ColQwen2 page embeddings and Qdrant in-memory multivector MaxSim retrieval.
 - Local Qwen2.5-VL answer generation with deterministic generation settings.
 - Flat JSON responses for extraction mode.
 - FastAPI app factory and CLI for local serving and testing.
 - CI-friendly tests that mock heavy GPU/model work.
 
-## Tech Stack
-
-| Layer | Technology |
-| --- | --- |
-| Language | Python 3.10+ |
-| API | FastAPI, Uvicorn |
-| CLI | `argparse`, HTTPX |
-| Visual retrieval | ColQwen2 via `colpali-engine` |
-| Vector store | Qdrant in-memory multivector collection |
-| Answer generation | Local `Qwen/Qwen2.5-VL-3B-Instruct` |
-| Document rendering | PyMuPDF, Pillow, LibreOffice for DOCX conversion |
-| Tests and checks | Pytest, Ruff, notebook JSON/AST contract checks |
-
-## Architecture
-
-```mermaid
-flowchart LR
-    A["Upload PDF, DOCX, or image"] --> B["Validate request"]
-    B --> C["Render pages as images"]
-    C --> D["Embed pages with ColQwen2"]
-    D --> E["Index in per-request in-memory Qdrant"]
-    F["User query"] --> G["Embed query with ColQwen2"]
-    G --> H["Retrieve top visual pages"]
-    E --> H
-    H --> I["Generate answer with local Qwen2.5-VL"]
-    I --> J["Flat JSON extraction or answer response"]
-```
+## Install Modes
 
-Longer architecture notes live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+| Install | Use it for | Does not include |
+| --- | --- | --- |
+| `python -m pip install -e ".[dev]"` | Static checks, notebook contract, API tests, mocked pipeline tests | ColQwen2/Qwen2.5-VL runtime validation |
+| `python -m pip install -e ".[gpu]"` | Real visual retrieval and generation on CUDA | Production auth, hosting, monitoring |
+| DOCX support | Requires LibreOffice `soffice` on `PATH` | Not needed for PDF/image input |
 
 ## Quickstart
 
-Clone the repository and install the lightweight development dependencies. This path verifies the package, API wrapper, notebook contract, and mocked tests without downloading GPU models:
+Clone the repository and run the lightweight verification path:
 
 ```bash
 git clone https://github.com/RossDmello2/visorag.git
@@ -76,21 +84,23 @@ python scripts/smoke_import.py
 python -m pytest
 ```
 
+What this proves: the notebook still matches the expected contract, the package imports without loading GPU models, and API/pipeline behavior passes mocked tests. It does not prove real model inference.
+
 For real GPU inference, install the GPU extra in a CUDA environment:
 
 ```bash
 python -m pip install -e ".[gpu]"
 ```
 
-The notebook was designed around a CUDA GPU runtime such as Google Colab T4. The local Qwen2.5-VL generation path is not CPU-ready. DOCX input also requires LibreOffice's `soffice` executable on `PATH`; PDF and image inputs do not need LibreOffice.
+The notebook was designed around a CUDA GPU runtime such as Google Colab T4. The local Qwen2.5-VL generation path is not CPU-ready. No public sample document is bundled; use only synthetic or public documents when sharing screenshots or issues.
 
-## API
+## API Usage
 
 Start the local API:
 
 ```bash
 export VISORAG_API_TOKEN="change-me"
-visorag serve --host 127.0.0.1 --port 8000
+python -m visorag serve --host 127.0.0.1 --port 8000
 ```
 
 PowerShell:
@@ -100,22 +110,22 @@ $env:VISORAG_API_TOKEN = "change-me"
 python -m visorag serve --host 127.0.0.1 --port 8000
 ```
 
-On Windows or any environment where the console script is not on `PATH`, use `python -m visorag`.
+`change-me` and the built-in test token fallback are local-development placeholders, not deployment values. Always set a strong `VISORAG_API_TOKEN` before serving real documents.
 
 Health check:
 
 ```bash
-visorag health --url http://127.0.0.1:8000
+python -m visorag health --url http://127.0.0.1:8000
 ```
 
 Submit a document:
 
 ```bash
-visorag query \
+python -m visorag query \
   --url http://127.0.0.1:8000 \
   --token "$VISORAG_API_TOKEN" \
-  --file /path/to/invoice.pdf \
-  --query "Extract total due and sales tax and invoice number" \
+  --file /path/to/document.pdf \
+  --query "Extract total due and invoice number" \
   --query-type extraction \
   --top-k 5
 ```
@@ -126,7 +136,7 @@ FastAPI routes:
 - `GET /health` returns model-load flags and device info.
 - `POST /query` accepts multipart `file` plus `query`, `query_type`, `document_type`, and `top_k`.
 
-More request and response details are in [docs/API_REFERENCE.md](docs/API_REFERENCE.md).
+See [docs/API_REFERENCE.md](docs/API_REFERENCE.md) for status codes, request fields, and both API-layer and pipeline error shapes.
 
 ## Response Contract
 
@@ -147,38 +157,57 @@ Factual and summary modes return:
 }
 ```
 
-Errors return:
+Pipeline errors include `request_id`; API validation/auth errors may only include `error` and `detail` because the pipeline has not started yet.
 
-```json
-{
-  "request_id": "uuid",
-  "error": "invalid_top_k",
-  "detail": "top_k must be between 1 and 20."
-}
-```
+## Tech Stack
 
-## Configuration
+| Layer | Technology |
+| --- | --- |
+| Language | Python 3.10+ |
+| API | FastAPI, Uvicorn |
+| CLI | `argparse`, HTTPX |
+| Visual retrieval | ColQwen2 via `colpali-engine` |
+| Vector store | Qdrant in-memory multivector collection |
+| Answer generation | Local `Qwen/Qwen2.5-VL-3B-Instruct` |
+| Document rendering | PyMuPDF, Pillow, LibreOffice for DOCX conversion |
+| Tests and checks | Pytest, Ruff, notebook JSON/AST contract checks |
 
-Copy `.env.example` and set local values as needed. Important variables:
+## Architecture
 
-- `VISORAG_API_TOKEN`: bearer token for `POST /query`.
-- `VISORAG_DEVICE`: expected to be `cuda` for real Qwen2.5-VL inference.
-- `VISORAG_REQUESTS_DIR`: temporary per-request working directory.
-- `VISORAG_QWEN_MAX_PIXELS`: reduce this if a T4 runtime runs out of VRAM.
+```mermaid
+flowchart LR
+    A["Upload PDF, DOCX, or image"] --> B["Validate request"]
+    B --> C["Render pages as images"]
+    C --> D["Embed pages with ColQwen2"]
+    D --> E["Index in per-request in-memory Qdrant"]
+    F["User query"] --> G["Embed query with ColQwen2"]
+    G --> H["Retrieve top visual pages"]
+    E --> H
+    H --> I["Generate answer with local Qwen2.5-VL"]
+    I --> J["Flat JSON extraction or answer response"]
+```
 
-See [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) for a beginner setup path and [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common runtime failures.
+Runtime constraints:
 
-## Development
+- Requests are serialized through a process-level query lock.
+- Uploads default to 25 MB.
+- Rendered documents default to 200 pages maximum.
+- Qdrant state is per request and in memory.
+- Uploaded files and rendered pages are temporary by default.
 
-The package is organized by feature:
+Longer architecture notes live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
-- `src/visorag/features/document_ingestion.py`
-- `src/visorag/features/visual_retrieval.py`
-- `src/visorag/features/answer_generation.py`
-- `src/visorag/pipeline.py`
-- `src/visorag/api/app.py`
+## Documentation Map
 
-See [docs/feature-extension.md](docs/feature-extension.md) before adding new behavior.
+| Need | Start here |
+| --- | --- |
+| First setup | [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) |
+| API clients | [docs/API_REFERENCE.md](docs/API_REFERENCE.md) |
+| Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
+| Deployment | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) |
+| Troubleshooting | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
+| Contribution model | [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/feature-extension.md](docs/feature-extension.md) |
+| Naming and SEO rationale | [docs/NAMING_SEO_STRATEGY.md](docs/NAMING_SEO_STRATEGY.md) |
 
 ## Project Structure
 
@@ -203,15 +232,15 @@ python -m ruff check .
 python -m pytest
 ```
 
-Real model inference is intentionally outside the default CI path because it requires CUDA, model downloads, and enough GPU memory.
+Real model inference is intentionally outside the default CI path because it requires CUDA, model downloads, and enough GPU memory. CI proves package/import/API contracts, not production GPU throughput.
 
 ## Deployment
 
-VisoRAG is easiest to run as a long-running Python service on a GPU machine or notebook runtime. Do not expose the FastAPI server directly to the internet without a gateway, TLS, restricted CORS, and a strong bearer token. See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
+VisoRAG is easiest to run as a long-running Python service on a GPU machine or notebook runtime. Do not expose the FastAPI server directly to the internet without a gateway, TLS, restricted CORS, a strong bearer token, request-log controls, and dependency/model-license review. See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
 ## Security
 
-Do not upload private documents to public issues, logs, or CI artifacts. The local API uses bearer-token auth but enables permissive CORS for notebook compatibility. See [SECURITY.md](SECURITY.md) and [docs/security-model.md](docs/security-model.md).
+Do not upload private documents to public issues, logs, or CI artifacts. The local API uses bearer-token auth but enables permissive CORS for notebook compatibility. The runtime may log filenames and query snippets, so disable or restrict logs before processing sensitive documents. See [SECURITY.md](SECURITY.md) and [docs/security-model.md](docs/security-model.md).
 
 ## Support
 
@@ -229,7 +258,7 @@ See [docs/THIRD_PARTY_NOTICES.md](docs/THIRD_PARTY_NOTICES.md) for dependency no
 
 ## Current Status
 
-`READY WITH GAPS`: the source package, docs, CI checks, notebook contract, import smoke, mocked tests, local FastAPI health endpoint, and API docs rendering have been verified. Real GPU inference with ColQwen2 and Qwen2.5-VL is documented but not verified in CI, and internet-facing deployment requires additional hardening.
+`READY WITH GAPS`: the source package, docs, CI checks, notebook contract, import smoke, mocked tests, local FastAPI health endpoint, and API docs rendering have been verified. Real GPU inference with ColQwen2 and Qwen2.5-VL is documented but not verified in CI, internet-facing deployment requires additional hardening, and an actual repository rename would require owner approval.
 
 ## License
 

SECURITY.md

@@ -12,8 +12,9 @@ Do not open public issues containing private documents, API tokens, stack traces
 
 - The API is intended for local use unless it is deployed behind a hardened gateway.
 - `POST /query` requires a bearer token from `VISORAG_API_TOKEN`.
+- Built-in demo token defaults and `.env.example` placeholders are for local development only.
 - CORS is permissive to preserve the notebook API behavior; restrict it before internet deployment.
-- Uploaded documents may contain sensitive data and should not be logged or committed.
+- Uploaded documents, filenames, and query snippets may contain sensitive data and should not be logged or committed.
 - File parsing for PDFs, DOCX files, and images has supply-chain and malformed-file risk.
 - Prompt injection is possible when untrusted document content controls visible text.
 - GPU runtime dependencies and model weights inherit their own licenses and security posture.

docs/API_REFERENCE.md

@@ -42,6 +42,13 @@ Multipart form fields:
 | `document_type` | No | Defaults to the uploaded file extension in the API |
 | `top_k` | No | Integer from `1` to `20`; defaults to `5` |
 
+Runtime limits:
+
+- Uploads default to 25 MB.
+- Documents default to 200 rendered pages maximum.
+- Queries are serialized by a process-level lock.
+- Qdrant state is in memory and scoped to the request.
+
 Example:
 
 ```bash
@@ -70,10 +77,30 @@ Extraction responses are flat JSON:
 
 Errors:
 
+API validation and authentication errors can return only `error` and `detail` because the pipeline has not started:
+
+```json
+{"error": "unauthorized", "detail": "Missing Bearer token."}
+```
+
+Pipeline errors include a `request_id`:
+
 ```json
 {
   "request_id": "uuid",
   "error": "invalid_top_k",
   "detail": "top_k must be between 1 and 20."
 }
 ```
+
+## Status Codes
+
+| Code | Meaning |
+| --- | --- |
+| `200` | Successful health check, service metadata, factual/summary answer, or extraction JSON. |
+| `400` | Missing query/file, unsupported file type, invalid `top_k`, invalid document/query type, or document type mismatch. |
+| `401` | Missing or invalid bearer token. |
+| `413` | Upload exceeds `VISORAG_MAX_UPLOAD_BYTES`. |
+| `422` | Document rendering produced no pages or retrieval returned no pages. |
+| `500` | Embedding, Qdrant, or unexpected pipeline failure. |
+| `503` | Local Qwen2.5-VL inference failed or is unavailable. |

docs/DEPLOYMENT.md

@@ -16,6 +16,8 @@ VisoRAG is a GPU-backed Python API. Treat it as a long-running service, not a st
 - Public internet exposure of the raw Uvicorn server.
 - Serverless hosting that cannot provide persistent GPU runtime or large model downloads.
 - Multi-user production workloads without a real auth layer, quotas, audit logs, and request isolation.
+- Using the fallback demo token or placeholder `.env.example` values.
+- Processing sensitive documents while request logs include filenames or query snippets.
 
 ## Local Service Command
 
@@ -30,7 +32,7 @@ Use `127.0.0.1` for local-only testing.
 
 - Replace the example token with a high-entropy secret.
 - Restrict CORS in `api/app.py` or at the gateway.
-- Disable sensitive request/response logging.
+- Disable or restrict sensitive request/response logging. The current runtime may log filenames and query snippets.
 - Keep uploaded files and rendered page images out of source control and CI artifacts.
 - Patch dependencies and model runtime packages regularly.
 - Review upstream model and package licenses before redistribution.

docs/GETTING_STARTED.md

@@ -2,6 +2,8 @@
 
 This guide is for a fresh clone of VisoRAG.
 
+Dev-only checks do not need a `.env` file. Real serving should always set `VISORAG_API_TOKEN`; placeholder values such as `change-me` or `test_bearer_123` are not deployment values.
+
 ## What You Can Verify Without a GPU
 
 The default development install is lightweight. It verifies packaging, import safety, API contracts, notebook structure, and mocked tests. It does not download or run ColQwen2 or Qwen2.5-VL.
@@ -13,6 +15,8 @@ python scripts/smoke_import.py
 python -m pytest
 ```
 
+This proves the package and public contracts, not real model inference.
+
 ## Real Inference Requirements
 
 Real document question answering requires: