sheet upload fix

README.md

@@ -117,10 +117,52 @@ curl -X POST localhost:8000/api/auth/login \
 
 Send it as `Authorization: Bearer <token>`, or use an `X-API-Key` from the
 `API_KEYS` setting for server-to-server callers. `admin` passes every
-permission check; `user` holds the product/store/inventory permissions.
+permission check; `user` holds the product/store/inventory permissions;
+`uploader` holds exactly one, `upload_catalog` (see below).
 `AUTH_ENABLED=false` disables all of it for local work — never in a deployment.
 See the Authentication section of `../DEPLOYMENT.md` for the full endpoint map.
 
+## Catalog ingestion for API clients
+
+An outside party can send spreadsheets straight into the catalog pipeline
+without an admin in the loop. Issue them an `uploader` key:
+
+```bash
+python scripts/make_auth_secrets.py --api-key catalog-drop:uploader
+# -> API_KEYS=catalog-drop:uploader:<secret>   (add to .env, redeploy)
+```
+
+Name the key for its function, not its holder: `/api/health` publicly reports
+every key's name, role and fingerprint (never the secret).
+
+They then POST files and poll the batch:
+
+```bash
+curl -X POST https://mcp.nearle.ai.in/api/uploads/catalog \
+  -H 'X-API-Key: <secret>' \
+  -F 'files=@store-catalog.xlsx' -F 'files=@second-store.xlsx'
+# -> 202 {"batch_id": "...", "status": "queued", "files": [...], "message": "..."}
+
+curl https://mcp.nearle.ai.in/api/uploads/catalog/<batch_id> -H 'X-API-Key: <secret>'
+# -> {"status": "running", "files_done": 1, "files": [{"stage_name": "...", ...}]}
+```
+
+`.xlsx`, `.xls` and `.csv` are accepted, up to 10MB / 2000 rows per file and
+`BATCH_MAX_FILES` files per request. Each file runs the same 11 stages as the
+admin route (`app/core/store_catalog_pipeline.py`). A sheet that cannot be
+parsed — or that has no product-name column — is rejected during the request
+with a 400 naming the problem, so the sender finds out while they can still fix
+it; a bad file alongside good ones comes back in `files` as `status: "failed"`
+while the rest still run.
+
+Two things this credential cannot do. It cannot see anything but its own
+submissions — every read is filtered by `submitted_by`, so it reaches neither
+the catalog nor another caller's batches — and it cannot multiply the work:
+all ingestion, from every source, goes through one worker thread behind a queue
+of `BATCH_QUEUE_MAX`, past which the endpoint answers 429. Cancel, resume and
+the full batch list stay on the admin router
+(`/api/admin/catalog-batch/...`, `require_admin`).
+
 ## MCP server
 
 The catalog is exposed to AI clients over the Model Context Protocol at `/mcp`,