[kovtcharov]

Fixes #728.

What was broken

Drag-and-drop document upload failed with "Indexing error: Not found. The file or folder may have been moved or deleted." in any browser, and in the packaged Electron desktop app (Electron 40).

Root cause: src/gaia/apps/webui/src/components/DocumentLibrary.tsx:265 relied on (file as any).path, an Electron-only augmentation that's undefined in every browser and was removed in Electron 32+. The fallback file.name (bare filename, no directory) was POSTed to /api/documents/upload-path, which couldn't resolve it → HTTP 404 → misleading frontend error.

Fix

New POST /api/documents/upload endpoint that accepts the file content as multipart form data, streams it to ~/.gaia/documents/<shortid>_<original_name>.<ext> with a 20 MB cap, dedupes by SHA-256 hash, and indexes via the standard RAG pipeline. Drag-and-drop in both DocumentLibrary and ChatView now use this endpoint. Delete cleans up server-owned files; user-owned files from upload-path are left alone.

Also fixes getFriendlyError() in api.ts to prefer the backend's detail over the canned 404 string, so future upload errors surface meaningful messages.

Details worth knowing

• On-disk filename embeds the original stem (<12-hex-id>_<sanitized_name>.<ext>) so the agent LLM and RAG tools can recognize the file by its human-readable name. A pure-UUID filename caused the LLM to hallucinate paths (e.g. C:\Users\14255\.gaia\documents\<uuid>.pdf → /Users/14255/Documents/<uuid>.pdf) and fail tool lookups.
• Filename sanitizer strips Windows-illegal chars (<>:"/\|?*), control chars, leading/trailing whitespace and dots, and caps length at 80 chars — keeps total path well under Windows MAX_PATH.
• 12-hex-char ID instead of full UUID. We dedup by SHA-256 first, so identical-content collisions are impossible; the only theoretical collision is concurrent uploads of different content drawing the same ID, with probability ~1 in 1.4e14 even at 1M concurrent uploads. Saves 24 chars per filename.
• Reliability: streaming write with abort-on-overflow, try/finally partial cleanup (survives ClientDisconnect), atomic os.replace, orphan cleanup on indexing/db/race failures.
• Chat-view drop UX: dropping onto the chat area indexes quietly without forcing the Document Library side panel open. Dropping onto the library panel itself still opens it (correct for users intentionally managing their library).

Bundled cleanup

This PR also includes a doc-consistency pass auto-applied by util/lint.py --all --fix (step 8) that aligns the supported-extension allowlist across backend (utils.py, files.py), frontend (UnsupportedFeature.tsx), and tests.

What's NOT changed

• POST /api/documents/upload-path is untouched — still used by the server-side file browser in FileBrowser.tsx, where the user explicitly picks a real filesystem path.
• The Electron preload — deliberately not adding webUtils.getPathForFile since it's broken for drag-drop in Electron 30-33+ and the blob path works everywhere.

Known limitation / follow-up

The agent LLM still occasionally cites the on-disk filename (e.g. 9c59c981f8e7_report.pdf) when answering questions about a document, instead of the user's display name (report.pdf). This is because src/gaia/agents/chat/tools/rag_tools.py returns chunk metadata using raw filepaths from self.rag.indexed_files rather than translating them to the display name stored in documents.filename. This is a separate, pre-existing concern in the RAG tool layer and fixing it requires a focused refactor of rag_tools.py (~1800 lines, touches query_documents, query_specific_file, summarize_document, search_indexed_chunks, list_indexed_documents). Tracking it as a follow-up rather than expanding this PR's scope.

Conflict notes for reviewers

• fix: surface document indexing failures instead of silent 0-chunk success #723 (surface indexing failures) also touches src/gaia/ui/routers/documents.py, but edits the body of upload_by_path — this PR only adds new top-of-file constants, helpers, and a new upload_document_blob function inserted after upload_by_path. Three-way merge should be clean. Semantically, fix: surface document indexing failures instead of silent 0-chunk success #723's "raise on failure" change is more correct under my new endpoint than the previous silent-0-chunk behavior.
• fix: Ask Agent indexes and attaches files before sending to chat #725 (Ask Agent file indexing) touches ChatView.tsx in a disjoint line range. No conflict.

---

Steps to reproduce the bug (before this fix)

One-time setup

git checkout main
uv venv
uv pip install -e ".[dev,ui]"
cd src/gaia/apps/webui && npm install && npm run build && cd -

Windows PowerShell users: quote the extras → uv pip install -e ".[ui]". Without quotes PowerShell silently strips them.

Start the services

# Terminal 1
lemonade-server serve

# Terminal 2
gaia chat --ui

Reproduce

1. Open the UI in Firefox (most reliable repro; the bug also reproduces in Chrome and the packaged Electron 40 desktop app).
2. Open DevTools → Network tab, filter on documents.
3. Open or create a chat session.
4. Drag any .pdf/.txt/.md/.docx from your file manager onto the Document Library drop zone or the chat area.
5. Observe:
   • UI: "Indexing error: Not found. The file or folder may have been moved or deleted."
   • Network: POST /api/documents/upload-path → HTTP 404
   • Request body: {"filepath":"report.pdf"} (bare filename — the smoking gun)
   • Backend log: HTTPException: File not found: report.pdf

Verify the fix

git checkout kalin/fix-728-document-upload
cd src/gaia/apps/webui && npm run build && cd -
# Restart `gaia chat --ui`

Repeat the drop. Expected:

• Network: POST /api/documents/upload (multipart, not upload-path) → HTTP 200
• File persisted at ~/.gaia/documents/<shortid>_report.pdf with the original name embedded
• Backend log: Blob upload indexed: report.pdf (<N> bytes, <M> chunks)
• Drop the same file twice → Blob upload dedup: report.pdf matches existing doc <id> (no second file on disk)
• Ask the agent about the doc → answers correctly using the indexed content

Test plan

• 10 new integration tests (tests/integration/test_documents_router.py): happy path, dedup, empty/oversized/bad-extension/illegal-chars rejection, indexing failure cleanup, delete unlinks server-owned, delete preserves user-owned, 404 on delete
• Adjacent regression sweep: 186 tests pass (files router, folder indexing, database, server unit tests)
• python util/lint.py --all --fix clean
• tsc --noEmit clean (no new errors in changed files)
• End-to-end smoke test via TestClient (upload → list → delete → file unlinked)
• Manual (Windows + Firefox): drag-and-drop indexes successfully → ✅ validated
• Manual: dropped doc auto-attaches to chat session → ✅ validated
• Manual: dedup short-circuit verified → ✅ validated
• Manual: delete cleanup verified for both server-owned and user-owned files → ✅ validated
• Manual: agent answers questions correctly using the indexed document → ✅ validated (display-name citation polish tracked as follow-up; see "Known limitation" above)