Persist Qdrant to host: bind-mount ./data/qdrant; add data dir ignore; update docs

README.md

@@ -18,6 +18,19 @@ and a **Gateway API** that can call them individually or together.
 docker compose up -d --build
 ```
 
+If you use BLIP, create a `.env` file first.
+
+Required variables:
+
+```bash
+API_KEY=your_api_key_here
+HUGGINGFACE_TOKEN=your_huggingface_token_here
+```
+
+`HUGGINGFACE_TOKEN` is required when the configured BLIP model is private, gated, or otherwise requires Hugging Face authentication.
+
+Service startup now waits on container healthchecks, so first boot may take longer while models finish loading.
+
 ## Health
 
 ```bash
@@ -84,18 +97,31 @@ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/analyze/yo
 
 ## Vector DB (Qdrant) via gateway
 
+Qdrant point IDs must be either:
+
+- an unsigned integer
+- a UUID string
+
+If you send another string value, the wrapper may replace it with a generated UUID. In that case the original value is stored in the payload as `_original_id`.
+
+You can fetch a stored point by its preserved original application ID:
+
+```bash
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/points/by-original-id/img-001
+```
+
 ### Store image embedding by URL
 ```bash
 curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/upsert \
   -H "Content-Type: application/json" \
-  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","id":"img-001","metadata":{"category":"wallpaper"}}'
+  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","id":"550e8400-e29b-41d4-a716-446655440000","metadata":{"category":"wallpaper"}}'
 ```
 
 ### Store image embedding by file upload
 ```bash
 curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/upsert/file \
   -F "file=@/path/to/image.webp" \
-  -F 'id=img-002' \
+  -F 'id=550e8400-e29b-41d4-a716-446655440001' \
   -F 'metadata_json={"category":"photo"}'
 ```
 
@@ -127,12 +153,15 @@ curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collection
 ```bash
 curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/delete \
   -H "Content-Type: application/json" \
-  -d '{"ids":["img-001","img-002"]}'
+  -d '{"ids":["550e8400-e29b-41d4-a716-446655440000","550e8400-e29b-41d4-a716-446655440001"]}'
 ```
 
+If you let the wrapper generate a UUID, use the returned `id` value for later `get`, `search`, or `delete` operations.
+
 ## Notes
 
 - This is a **starter scaffold**. Models are loaded at service startup.
-- Qdrant data is persisted via a Docker volume (`qdrant_data`).
+- Qdrant data is persisted in the project folder at `./data/qdrant`, so it survives container restarts and recreates.
+- Remote image URLs are restricted to public `http`/`https` hosts. Localhost, private IP ranges, and non-image content types are rejected.
 - For production: add auth, rate limits, and restrict gateway exposure (private network).
 - GPU: you can add NVIDIA runtime later (compose profiles) if needed.