Update README.md

Author: hutaobo

README.md

@@ -4,118 +4,151 @@
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB.svg)](https://www.python.org/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-5B4B8A.svg)](LICENSE)
 
-Pathology RAG Workbench is a local-first retrieval and question-answering workspace for pathology PDFs. It combines PDF ingestion, chunking, pgvector-backed retrieval, a FastAPI service, a browser UI, and optional OpenClaw integration so you can build a citation-backed pathology assistant around your own licensed corpus.
+Pathology RAG Workbench is a local-first pathology PDF workspace. It helps you turn your own licensed pathology books or notes into a citation-backed retrieval system with a browser UI, a local API, and a CLI.
 
-This repository is public, but it is not open source in the OSI sense. The code is released under the PolyForm Noncommercial 1.0.0 license, so commercial use is not allowed.
+This repository is public, but it is not open source in the OSI sense. It is released under the [PolyForm Noncommercial 1.0.0](LICENSE) license, so commercial use is not allowed.
 
-## Important Notices
+## Start Here
 
-- Non-commercial use only. Read [LICENSE](LICENSE) before using, modifying, or redistributing the software.
-- No corpus is bundled. You must add your own lawfully obtained PDFs.
-- Do not commit copyrighted textbooks, extracted chunks, page previews, or PHI to Git.
-- This project is a research and workflow tool, not a medical device and not a substitute for expert pathology review.
+If you only read one section, read this one.
 
-## What It Does
+Clone the repo and run:
 
-- Builds a local manifest and chunk index from pathology PDFs.
-- Stores embeddings in PostgreSQL with `pgvector`.
-- Exposes `health`, `library`, `search`, `ask`, and browser UI routes through FastAPI.
-- Applies evidence guardrails so `/ask` refuses to answer when textbook grounding is missing or weak.
-- Supports filtering answers to selected documents.
-- Includes OpenClaw-facing docs and a local CLI client.
+```bash
+git clone https://github.com/hutaobo/pathology-rag-workbench.git
+cd pathology-rag-workbench
+bash scripts/deploy_portable.sh --allow-no-openai
+```
 
-## Stack
+Then open:
 
-- Python 3.11+
-- FastAPI
-- PostgreSQL + `pgvector`
-- Docker Compose
-- PyMuPDF / pdfplumber / pypdf
-- OpenAI API for embeddings and model-backed answers when enabled
+```text
+http://127.0.0.1:8000/ui
+```
+
+What you should have after that:
+
+- a working browser UI
+- a local FastAPI server
+- PostgreSQL with `pgvector`
+- a safe empty-library state if you have not added PDFs yet
+- local CLI commands such as `pathology-client health`
+
+This path is designed to work even when:
+
+- you have no pathology PDFs yet
+- you do not have an OpenAI API key yet
+- you are cloning the repo onto a new machine for the first time
 
-## Quick Start
+## Five-Minute Onboarding
 
-The fastest setup path uses the provided Bash scripts. On Windows, use Git Bash or WSL.
+### 1. Prerequisites
 
-1. Install prerequisites:
+You need:
+
+- Python 3.11+
+- Docker
+- Docker Compose
+
+Quick check:
 
 ```bash
 python3 --version
 docker --version
 docker compose version
 ```
 
-2. Copy environment defaults:
+On macOS, if Docker is installed but the daemon is not running, the deploy script will try to use Colima when available.
+
+### 2. Run the one-command setup
 
 ```bash
-cp .env.example .env
+bash scripts/deploy_portable.sh --allow-no-openai
 ```
 
-3. Add your optional OpenAI key to `.env` if you want embeddings and model-backed `/ask`.
+What this script does:
 
-4. Put your own PDFs under `pathologybook/` or plan to upload them through the browser UI later.
+- creates `.env` from `.env.example` if needed
+- bootstraps `.venv`
+- starts PostgreSQL and the API container
+- builds a local empty or populated library index
+- installs the local `pathology-client` command
+- installs optional OpenClaw integration
+- opens the browser UI unless you pass `--skip-browser`
 
-5. Run the portable bootstrap:
+### 3. Verify that it worked
 
-```bash
-bash scripts/deploy_portable.sh --allow-no-openai
-```
-
-6. Open the browser UI:
+Browser:
 
 ```text
 http://127.0.0.1:8000/ui
 ```
 
-Without an OpenAI key, the project still supports library management and retrieval previews, but model-backed answer synthesis is skipped.
-
-## Manual Setup
-
-If you prefer to set the project up step by step:
-
-1. Bootstrap the virtualenv:
+CLI:
 
 ```bash
-bash scripts/bootstrap.sh
+pathology-client health
 ```
 
-2. Start PostgreSQL and the API:
+Expected result:
 
-```bash
-docker compose up -d postgres api
+```json
+{
+  "ok": "true",
+  "status": "live"
+}
 ```
 
-3. Build or refresh the local library index:
+## What You Can Do Immediately
+
+Even without an OpenAI key, you can:
+
+- start the full local UI
+- upload PDFs
+- sync the local library
+- inspect library state
+- run retrieval previews instead of model-synthesized answers
+
+Useful commands:
 
 ```bash
-.venv/bin/python -m apps.ingest_worker.cli sync-library
+pathology-client health
+pathology-client ui
+pathology-client library
+pathology-client search --query "ductal carcinoma in situ"
+pathology-client sync-library
 ```
 
-On Windows PowerShell, the equivalent is:
+## Add Your Own PDFs
 
-```powershell
-.venv\Scripts\python.exe -m apps.ingest_worker.cli sync-library
-```
+No corpus is bundled with this repository.
+
+You must add your own lawfully obtained PDFs by one of these methods:
 
-4. Check health:
+### Option A: Copy PDFs into `pathologybook/`
 
 ```bash
-.venv/bin/python -m apps.pathology_client.cli health
+cp /path/to/your/*.pdf pathologybook/
+pathology-client sync-library
 ```
 
-## Adding Your Own PDFs
+### Option B: Upload from the browser UI
 
-The repository defaults to a local untracked library config at `config/library.local.yaml`. You can either:
+Open:
 
-- Copy PDFs into `pathologybook/` and run `sync-library`.
-- Upload PDFs from the browser UI.
-- Create a local config file manually from the example:
+```text
+http://127.0.0.1:8000/ui
+```
+
+Then use the library panel to upload PDFs and trigger a sync.
+
+### Option C: Use a local config file
 
 ```bash
 cp config/library.example.yaml config/library.local.yaml
 ```
 
-Example local config:
+Example:
 
 ```yaml
 library_name: my-pathology-library
@@ -127,30 +160,112 @@ documents:
     path: GU_Review.pdf
 ```
 
-## Common Commands
+## Enable Model-Backed Answers
+
+OpenAI-backed embeddings and `/ask` are optional.
+
+If you do nothing, the project still works in retrieval-preview mode.
+
+If you want model-backed answers:
+
+1. Set `OPENAI_API_KEY`
+2. restart the deployment or rerun the sync
+
+Simplest path:
+
+```bash
+export OPENAI_API_KEY=your_key_here
+bash scripts/deploy_portable.sh
+```
+
+If you already deployed without a key:
+
+```bash
+export OPENAI_API_KEY=your_key_here
+bash scripts/deploy_portable.sh --skip-browser
+```
+
+After that you can ask:
 
 ```bash
-pathology-client health
-pathology-client library
-pathology-client search --query "ductal carcinoma in situ"
 pathology-client ask --question "What are the key features of mucinous carcinoma of the prostate?"
-pathology-client sync-library
 ```
 
-## Docker Services
+## Common Commands
 
-The active runtime stack is intentionally small:
+```bash
+make doctor
+make test
+make ui
+make portable-up
+make portable-bundle
+```
 
-- `postgres`: PostgreSQL with `pgvector`
-- `api`: FastAPI application
-- `ingest`: one-shot ingestion container when explicitly invoked
+Direct script entrypoints:
 
-Start the default stack:
+```bash
+bash scripts/doctor.sh
+bash scripts/bootstrap.sh
+bash scripts/deploy_portable.sh --allow-no-openai
+bash scripts/package_portable.sh
+```
+
+## Troubleshooting
+
+### Check your environment
+
+```bash
+bash scripts/doctor.sh
+```
+
+### The browser UI does not open
+
+Open it manually:
+
+```text
+http://127.0.0.1:8000/ui
+```
+
+### `pathology-client` is not found
+
+Reinstall the local wrappers:
 
 ```bash
-docker compose up --build postgres api
+bash scripts/install_openclaw_integration.sh
 ```
 
+### No answers are generated
+
+That is expected when:
+
+- your library is empty
+- your retrieval hits are too weak
+- `OPENAI_API_KEY` is not configured
+
+In that case:
+
+- upload or copy more PDFs
+- run `pathology-client sync-library`
+- verify `OPENAI_API_KEY` if you want synthesized answers
+
+## What This Repository Contains
+
+- local PDF ingestion and chunking
+- `pgvector`-backed retrieval
+- a browser UI
+- a local CLI client
+- upload and sync flows for pathology PDFs
+- evidence guardrails for ungrounded medical answers
+- optional OpenClaw integration
+
+It does not contain:
+
+- pathology textbooks
+- patient data
+- PHI
+- a clinical-grade decision engine
+- commercial-use rights
+
 ## Project Layout
 
 ```text
@@ -172,13 +287,14 @@ tests/                Unit and API tests
 ## Safety and Intended Use
 
 - Review all outputs before using them in education, reporting, or research.
-- Treat citations as aids, not as a final authority.
-- Keep patient data and licensed materials out of version control and public issue trackers.
+- Treat citations as aids, not as final authority.
+- Do not use this as a substitute for expert pathology review.
+- Do not commit copyrighted textbooks, extracted page text, page previews, embeddings, PHI, or secrets.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and repo hygiene rules.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Security
 
-See [SECURITY.md](SECURITY.md) for reporting guidance and data-handling expectations.
+See [SECURITY.md](SECURITY.md).