Store original documents for download after ingestion

Persist uploaded files to {data_dir}/documents/{content_hash}{ext} after successful ingestion. Add GET /documents/{id}/file endpoint for retrieval, delete stored files on document deletion, and add `kb export` client command. Includes schema migration, tests, and spec updates. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 15:16:27 +00:00
parent 6a4bce4659
commit b04823e67b
19 changed files with 802 additions and 10 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-27
@@ -0,0 +1,84 @@
+## Context
+
+Currently, uploaded files pass through a staging directory and are deleted after the worker extracts chunks and embeddings. The `documents.source_path` column stores the (now-stale) staging path. Users who want the original file must re-source it externally. The data directory structure today is:
+
+```
+/data/
+  kb.db
+  hf_cache/
+  staging/      # temporary, cleaned after processing
+```
+
+## Goals / Non-Goals
+
+**Goals:**
+- Persist every successfully-ingested original file for the lifetime of the document
+- Serve the original file via API (`GET /api/v1/documents/{id}/file`)
+- Clean up stored files when a document is deleted
+- Work transparently with the existing Docker volume mount (`/data`)
+
+**Non-Goals:**
+- Serving transformed/converted versions of documents (e.g. PDF→HTML)
+- De-duplicating file storage (same content hash = same row, so 1:1 is fine)
+- Compression or archival of stored files
+- Retroactive storage of files ingested before this change (they're already gone)
+
+## Decisions
+
+### 1. Storage layout: content-hash-based flat directory
+
+Store files at `{data_dir}/documents/{content_hash}{ext}` (e.g. `documents/a1b2c3...d4.pdf`).
+
+**Why over document-ID naming:** Content hash is available at staging time before the DB row exists, avoids race conditions, and makes dedup trivially safe (same hash = same file, overwrite is harmless). The hash is already computed for dedup checks.
+
+**Why flat over nested:** The KB is a personal tool — expected scale is hundreds to low-thousands of documents. A flat directory is simpler and sufficient. If needed later, a `ab/cd/` prefix scheme is easy to add.
+
+**Alternatives considered:**
+- *Store in SQLite as BLOBs*: Bloats the DB, complicates backups, and degrades WAL performance for large files. Rejected.
+- *Keep the staging path as-is*: Staging uses UUID prefixes which are meaningless; content-hash naming is deterministic and self-deduplicating.
+
+### 2. Move file from staging to documents dir (not copy)
+
+Use `shutil.move()` from staging to documents dir after successful ingestion, before `staging.cleanup()`. This avoids doubling disk usage during processing.
+
+**Why not copy-then-delete:** Move is atomic on the same filesystem (which `/data/staging` and `/data/documents` share). Faster, no temporary disk spike.
+
+### 3. New columns `stored_path` and `original_filename` on `documents` table
+
+Add two nullable columns:
+- `stored_path TEXT` — permanent file location on disk
+- `original_filename TEXT` — the exact filename from the upload (e.g. `report.pdf`)
+
+Both are nullable because existing documents (ingested before this change) won't have values.
+
+**Why `original_filename` separate from `title`:** The `title` field can be user-overridden (e.g. "Engine Manual" instead of `report.pdf`). When serving the file for download, the `Content-Disposition` header should use the original filename so the downloaded file has the correct name and extension. The `original_filename` is sourced from `jobs.filename` which is already captured at upload time.
+
+Keep `source_path` as-is for backward compatibility (it records what the staging path was). `stored_path` is the permanent location.
+
+**Migration:** Two `ALTER TABLE` statements — safe additive migrations, no data rewrite needed.
+
+### 4. File download endpoint returns the file directly
+
+`GET /api/v1/documents/{id}/file` uses FastAPI's `FileResponse` with:
+- `media_type` derived from the file extension
+- `Content-Disposition: attachment; filename="{original_filename}"` (falls back to `{title}{ext}` if `original_filename` is NULL)
+- Returns 404 if `stored_path` is NULL or file is missing from disk
+
+### 5. Delete cascades to file removal
+
+When `DELETE /api/v1/documents/{id}` is called, delete the stored file from disk after the DB delete succeeds. If file removal fails (already gone, permissions), log a warning but don't fail the API call — the DB is the source of truth.
+
+## Risks / Trade-offs
+
+- **Disk usage increases** — every ingested file persists. For the personal-use scale this is expected and acceptable. Users manage this via document deletion.
+  → Mitigation: Document the storage behavior; `GET /api/v1/status` already shows DB size, could add documents-dir size later.
+
+- **Pre-existing documents have no stored file** — `stored_path` will be NULL for documents ingested before this change.
+  → Mitigation: The download endpoint returns 404 with a clear message ("original file not available — ingested before document storage was enabled"). No attempt to backfill.
+
+- **File-DB consistency** — crash between DB commit and file move could leave orphan staged files or missing stored files.
+  → Mitigation: Move file first, then commit DB. If DB commit fails, the file in documents dir is harmless (orphan cleanup can be added later). If move fails, the job fails and staged file remains for retry.
+
+## Open Questions
+
+None — the scope is straightforward enough to proceed.
@@ -0,0 +1,30 @@
+## Why
+
+The knowledge base currently discards original files after chunking and embedding. Once a document is ingested, only the extracted text chunks and vectors remain — the original PDF, markdown, or code file is deleted from staging. Users cannot retrieve the source document from the KB, which limits its usefulness as a document store and prevents use cases like re-processing with a different model or serving the original file to downstream tools.
+
+## What Changes
+
+- Add a persistent document storage directory (`{data_dir}/documents/`) alongside the SQLite database
+- After successful ingestion, copy the original file from staging to permanent storage instead of deleting it
+- Store the permanent file path in the `documents` table (`stored_path` column) and the original upload filename (`original_filename` column) so downloads use the correct name
+- Add an API endpoint to download the original file by document ID
+- Add a CLI command to export/retrieve the original document
+- **BREAKING**: Delete document now also removes the stored file from disk
+- Notes (text-only) are stored as `.note` files in the same directory for consistency
+
+## Capabilities
+
+### New Capabilities
+- `document-storage`: Persistent storage of original uploaded files on disk, lifecycle management (store on ingest, delete on document removal), and retrieval via API
+
+### Modified Capabilities
+- `engine-api`: New endpoint `GET /api/v1/documents/{id}/file` to download the original file; delete endpoint must also clean up stored files; ingestion worker stores files instead of discarding them
+
+## Impact
+
+- **Engine config**: New `documents_dir` property on Config, new directory created at startup via `ensure_dirs()`
+- **Worker**: After successful chunking, move/copy file from staging to documents dir; update `source_path` → `stored_path` with permanent location
+- **Database schema**: Add `stored_path` and `original_filename` columns to `documents` table (migration for existing DBs)
+- **Routes**: New file-download endpoint; update delete handler to remove stored file
+- **Go client**: New `export` / `get-file` subcommand to download original documents
+- **Docker**: `documents/` directory lives inside the existing `/data` volume — no new mounts needed
@@ -0,0 +1,83 @@
+## ADDED Requirements
+
+### Requirement: Persistent original file storage
+
+The engine SHALL persistently store the original uploaded file on disk after successful ingestion. Files SHALL be stored at `{data_dir}/documents/{content_hash}{extension}` where `content_hash` is the SHA-256 hex digest already computed for dedup and `extension` is preserved from the original filename. The `documents` table SHALL record the stored file path in a `stored_path` column and the original upload filename in an `original_filename` column.
+
+#### Scenario: File stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a PDF file
+- **THEN** the worker SHALL move the staged file to `{data_dir}/documents/{content_hash}.pdf`, store the permanent path in `documents.stored_path`, store the original filename in `documents.original_filename`, and delete the staging entry
+
+#### Scenario: Note stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a text note
+- **THEN** the worker SHALL move the staged `.note` file to `{data_dir}/documents/{content_hash}.note` and store the permanent path in `documents.stored_path`
+
+#### Scenario: Markdown file stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a markdown file
+- **THEN** the worker SHALL move the staged file to `{data_dir}/documents/{content_hash}.md` and store the permanent path in `documents.stored_path`
+
+#### Scenario: Code file stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a code file (e.g. `.py`, `.go`)
+- **THEN** the worker SHALL move the staged file to `{data_dir}/documents/{content_hash}{original_extension}` and store the permanent path in `documents.stored_path`
+
+#### Scenario: Documents directory created at startup
+- **WHEN** the engine starts up and calls `ensure_dirs()`
+- **THEN** the `{data_dir}/documents/` directory SHALL be created if it does not exist
+
+#### Scenario: Ingestion failure does not store file
+- **WHEN** the background worker fails to process an ingestion job
+- **THEN** the staged file SHALL be cleaned up as before and no file SHALL be written to the documents directory
+
+---
+
+### Requirement: File retrieval via API
+
+The engine SHALL serve the original stored file for any document that has a stored file on disk.
+
+#### Scenario: Download original file
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` for a document with a stored file
+- **THEN** the engine SHALL return the file with appropriate `Content-Type` based on file extension and `Content-Disposition: attachment; filename="{original_filename}"` header, falling back to `{title}{ext}` if `original_filename` is NULL
+
+#### Scenario: Download file for pre-existing document
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` for a document ingested before this feature was added (stored_path is NULL)
+- **THEN** the engine SHALL return HTTP 404 with `{"error": "Original file not available - ingested before document storage was enabled"}`
+
+#### Scenario: Download file when file missing from disk
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` for a document whose `stored_path` is set but the file no longer exists on disk
+- **THEN** the engine SHALL return HTTP 404 with `{"error": "Stored file not found on disk"}`
+
+#### Scenario: Download file for non-existent document
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` with a non-existent document ID
+- **THEN** the engine SHALL return HTTP 404 with `{"error": "Document not found"}`
+
+---
+
+### Requirement: File cleanup on document deletion
+
+The engine SHALL remove the stored original file from disk when a document is deleted.
+
+#### Scenario: Delete document with stored file
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` for a document with a stored file
+- **THEN** the engine SHALL delete the document from the database (cascading to chunks, embeddings, tags) AND delete the stored file from disk
+
+#### Scenario: Delete document when stored file already missing
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` for a document whose stored file has been manually removed from disk
+- **THEN** the engine SHALL delete the document from the database successfully and log a warning about the missing file
+
+#### Scenario: Delete document without stored file (pre-existing)
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` for a document with `stored_path` NULL
+- **THEN** the engine SHALL delete the document from the database without attempting file removal
+
+---
+
+### Requirement: Database schema migration for stored_path and original_filename
+
+The engine SHALL add `stored_path` and `original_filename` columns to the `documents` table for tracking permanent file locations and original upload filenames.
+
+#### Scenario: Fresh database initialization
+- **WHEN** the engine initializes a new database
+- **THEN** the `documents` table SHALL include `stored_path TEXT` and `original_filename TEXT` columns in its schema
+
+#### Scenario: Existing database migration
+- **WHEN** the engine starts with a database created before this feature
+- **THEN** the engine SHALL add `stored_path TEXT` and `original_filename TEXT` to the `documents` table via `ALTER TABLE` if the columns do not exist
@@ -0,0 +1,61 @@
+## MODIFIED Requirements
+
+### Requirement: Background ingestion worker
+
+The engine SHALL run a background worker that processes queued jobs. The worker SHALL process one job at a time. For each job, it SHALL: detect document type, run the appropriate chunking pipeline (Docling for PDFs, header-based for Markdown, AST-based for code, whole-text for notes), generate embeddings using the resident model, insert chunks and vectors into the database, and move the original file to persistent storage.
+
+#### Scenario: Successful PDF ingestion
+- **WHEN** the background worker picks up a queued PDF job
+- **THEN** it SHALL update the job status to `processing`, run Docling conversion and chunking, embed all chunks, insert document and chunks into the database, move the staged file to `{data_dir}/documents/{content_hash}.pdf`, update `documents.stored_path` with the permanent path, store the original filename in `documents.original_filename`, update the job status to `done` with the resulting document_id and chunk count, and clean up the staging entry
+
+#### Scenario: Ingestion failure
+- **WHEN** the background worker encounters an error during processing (e.g., corrupt PDF)
+- **THEN** it SHALL update the job status to `failed` with the error message, delete the staged file, and continue processing the next queued job
+
+#### Scenario: Search during active ingestion
+- **WHEN** a search request arrives while the background worker is processing a job
+- **THEN** the search SHALL execute without blocking (SQLite WAL mode) and return results from already-ingested documents
+
+---
+
+### Requirement: Document management
+
+The engine SHALL provide endpoints to list, inspect, remove, and download original files for ingested documents.
+
+#### Scenario: List documents
+- **WHEN** a client sends `GET /api/v1/documents`
+- **THEN** the engine SHALL return a JSON array of documents with id, title, doc_type, tags, chunk_count, and created_at
+
+#### Scenario: List documents with filters
+- **WHEN** a client sends `GET /api/v1/documents?type=pdf&tags=manual`
+- **THEN** the engine SHALL return only documents matching all specified filters
+
+#### Scenario: Get document details
+- **WHEN** a client sends `GET /api/v1/documents/{id}`
+- **THEN** the engine SHALL return the full document record including all chunks, their text content, and whether the original file is available (`has_file: true/false`)
+
+#### Scenario: Download original file
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file`
+- **THEN** the engine SHALL return the original file with appropriate Content-Type and `Content-Disposition: attachment; filename="{original_filename}"` headers, or HTTP 404 if the file is not available
+
+#### Scenario: Remove a document
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}`
+- **THEN** the engine SHALL delete the document, all its chunks, associated embeddings, tag associations, and the stored original file from disk, and return HTTP 200 with a confirmation
+
+#### Scenario: Remove non-existent document
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` with a non-existent ID
+- **THEN** the engine SHALL return HTTP 404
+
+---
+
+### Requirement: Engine configuration via environment variables
+
+The engine SHALL be configured via environment variables. No config file is read by the engine — all configuration comes from the environment (set via compose.yaml or Docker run).
+
+#### Scenario: Default configuration
+- **WHEN** the engine starts with no environment variables set
+- **THEN** it SHALL use defaults: data directory `/data`, model `all-MiniLM-L6-v2`, device `auto`, no API key required. It SHALL create `staging/` and `documents/` subdirectories under the data directory.
+
+#### Scenario: Custom model
+- **WHEN** `KB_MODEL` is set to `BAAI/bge-small-en-v1.5`
+- **THEN** the engine SHALL download and load that model instead of the default
@@ -0,0 +1,38 @@
+## 1. Config and Schema
+
+- [x] 1.1 Add `documents_dir` property to `Config` in `engine/kb/config.py` returning `{data_dir}/documents`
+- [x] 1.2 Add `documents_dir.mkdir()` to `Config.ensure_dirs()`
+- [x] 1.3 Add `stored_path TEXT` and `original_filename TEXT` columns to `documents` table in `init_schema()` (both CREATE TABLE and ALTER TABLE migration for existing DBs)
+
+## 2. Worker — File Persistence
+
+- [x] 2.1 In `worker._process_job()`, after successful DB commit, move staged file to `{documents_dir}/{content_hash}{ext}` using `shutil.move()`
+- [x] 2.2 Update `documents.stored_path` and `documents.original_filename` (from `jobs.filename`) after moving the file
+- [x] 2.3 Remove `staging.cleanup()` call for successful jobs (file is moved, not deleted); keep cleanup on failure path
+
+## 3. API — File Download Endpoint
+
+- [x] 3.1 Add `GET /api/v1/documents/{id}/file` route in `engine/kb/routes/documents.py` using FastAPI `FileResponse`
+- [x] 3.2 Return appropriate `Content-Type` from file extension and `Content-Disposition: attachment; filename="{original_filename}"` (fall back to `{title}{ext}` if NULL)
+- [x] 3.3 Handle 404 cases: document not found, `stored_path` is NULL, file missing from disk
+
+## 4. API — Delete Cleanup
+
+- [x] 4.1 Update `DELETE /api/v1/documents/{id}` in `engine/kb/routes/documents.py` to also delete the stored file from disk
+- [x] 4.2 Handle missing file gracefully (log warning, don't fail the request)
+
+## 5. Document Details Enhancement
+
+- [x] 5.1 Add `has_file` boolean to `GET /api/v1/documents/{id}` response based on `stored_path` presence and file existence on disk
+
+## 6. Go Client
+
+- [x] 6.1 Add `kb export <doc_id>` subcommand to the Go client that calls `GET /api/v1/documents/{id}/file` and writes to stdout or a specified output path
+
+## 7. Testing
+
+- [x] 7.1 Test successful ingestion stores file at expected path
+- [x] 7.2 Test failed ingestion does not leave file in documents dir
+- [x] 7.3 Test file download endpoint returns correct content and headers
+- [x] 7.4 Test document deletion removes stored file
+- [x] 7.5 Test download returns 404 for documents without stored files
@@ -0,0 +1,89 @@
+# Document Storage
+
+## Purpose
+
+Persistent storage, retrieval, and lifecycle management of original uploaded document files.
+
+## Requirements
+
+### Requirement: Persistent original file storage
+
+The engine SHALL persistently store the original uploaded file on disk after successful ingestion. Files SHALL be stored at `{data_dir}/documents/{content_hash}{extension}` where `content_hash` is the SHA-256 hex digest already computed for dedup and `extension` is preserved from the original filename. The `documents` table SHALL record the stored file path in a `stored_path` column and the original upload filename in an `original_filename` column.
+
+#### Scenario: File stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a PDF file
+- **THEN** the worker SHALL move the staged file to `{data_dir}/documents/{content_hash}.pdf`, store the permanent path in `documents.stored_path`, store the original filename in `documents.original_filename`, and delete the staging entry
+
+#### Scenario: Note stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a text note
+- **THEN** the worker SHALL move the staged `.note` file to `{data_dir}/documents/{content_hash}.note` and store the permanent path in `documents.stored_path`
+
+#### Scenario: Markdown file stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a markdown file
+- **THEN** the worker SHALL move the staged file to `{data_dir}/documents/{content_hash}.md` and store the permanent path in `documents.stored_path`
+
+#### Scenario: Code file stored after successful ingestion
+- **WHEN** the background worker successfully processes an ingestion job for a code file (e.g. `.py`, `.go`)
+- **THEN** the worker SHALL move the staged file to `{data_dir}/documents/{content_hash}{original_extension}` and store the permanent path in `documents.stored_path`
+
+#### Scenario: Documents directory created at startup
+- **WHEN** the engine starts up and calls `ensure_dirs()`
+- **THEN** the `{data_dir}/documents/` directory SHALL be created if it does not exist
+
+#### Scenario: Ingestion failure does not store file
+- **WHEN** the background worker fails to process an ingestion job
+- **THEN** the staged file SHALL be cleaned up as before and no file SHALL be written to the documents directory
+
+---
+
+### Requirement: File retrieval via API
+
+The engine SHALL serve the original stored file for any document that has a stored file on disk.
+
+#### Scenario: Download original file
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` for a document with a stored file
+- **THEN** the engine SHALL return the file with appropriate `Content-Type` based on file extension and `Content-Disposition: attachment; filename="{original_filename}"` header, falling back to `{title}{ext}` if `original_filename` is NULL
+
+#### Scenario: Download file for pre-existing document
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` for a document ingested before this feature was added (stored_path is NULL)
+- **THEN** the engine SHALL return HTTP 404 with `{"error": "Original file not available - ingested before document storage was enabled"}`
+
+#### Scenario: Download file when file missing from disk
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` for a document whose `stored_path` is set but the file no longer exists on disk
+- **THEN** the engine SHALL return HTTP 404 with `{"error": "Stored file not found on disk"}`
+
+#### Scenario: Download file for non-existent document
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file` with a non-existent document ID
+- **THEN** the engine SHALL return HTTP 404 with `{"error": "Document not found"}`
+
+---
+
+### Requirement: File cleanup on document deletion
+
+The engine SHALL remove the stored original file from disk when a document is deleted.
+
+#### Scenario: Delete document with stored file
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` for a document with a stored file
+- **THEN** the engine SHALL delete the document from the database (cascading to chunks, embeddings, tags) AND delete the stored file from disk
+
+#### Scenario: Delete document when stored file already missing
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` for a document whose stored file has been manually removed from disk
+- **THEN** the engine SHALL delete the document from the database successfully and log a warning about the missing file
+
+#### Scenario: Delete document without stored file (pre-existing)
+- **WHEN** a client sends `DELETE /api/v1/documents/{id}` for a document with `stored_path` NULL
+- **THEN** the engine SHALL delete the document from the database without attempting file removal
+
+---
+
+### Requirement: Database schema migration for stored_path and original_filename
+
+The engine SHALL add `stored_path` and `original_filename` columns to the `documents` table for tracking permanent file locations and original upload filenames.
+
+#### Scenario: Fresh database initialization
+- **WHEN** the engine initializes a new database
+- **THEN** the `documents` table SHALL include `stored_path TEXT` and `original_filename TEXT` columns in its schema
+
+#### Scenario: Existing database migration
+- **WHEN** the engine starts with a database created before this feature
+- **THEN** the engine SHALL add `stored_path TEXT` and `original_filename TEXT` to the `documents` table via `ALTER TABLE` if the columns do not exist
@@ -128,11 +128,11 @@ The engine SHALL maintain job records in SQLite with status tracking. Jobs SHALL

 ### Requirement: Background ingestion worker

-The engine SHALL run a background worker that processes queued jobs. The worker SHALL process one job at a time. For each job, it SHALL: detect document type, run the appropriate chunking pipeline (Docling for PDFs, header-based for Markdown, AST-based for code, whole-text for notes), generate embeddings using the resident model, and insert chunks and vectors into the database.
+The engine SHALL run a background worker that processes queued jobs. The worker SHALL process one job at a time. For each job, it SHALL: detect document type, run the appropriate chunking pipeline (Docling for PDFs, header-based for Markdown, AST-based for code, whole-text for notes), generate embeddings using the resident model, insert chunks and vectors into the database, and move the original file to persistent storage.

 #### Scenario: Successful PDF ingestion
 - **WHEN** the background worker picks up a queued PDF job
- **THEN** it SHALL update the job status to `processing`, run Docling conversion and chunking, embed all chunks, insert document and chunks into the database, update the job status to `done` with the resulting document_id and chunk count, and delete the staged file
+- **THEN** it SHALL update the job status to `processing`, run Docling conversion and chunking, embed all chunks, insert document and chunks into the database, move the staged file to `{data_dir}/documents/{content_hash}.pdf`, update `documents.stored_path` with the permanent path, store the original filename in `documents.original_filename`, update the job status to `done` with the resulting document_id and chunk count, and clean up the staging entry

 #### Scenario: Ingestion failure
 - **WHEN** the background worker encounters an error during processing (e.g., corrupt PDF)
@@ -146,7 +146,7 @@ The engine SHALL run a background worker that processes queued jobs. The worker

 ### Requirement: Document management

-The engine SHALL provide endpoints to list, inspect, and remove ingested documents.
+The engine SHALL provide endpoints to list, inspect, remove, and download original files for ingested documents.

 #### Scenario: List documents
 - **WHEN** a client sends `GET /api/v1/documents`
@@ -158,11 +158,15 @@ The engine SHALL provide endpoints to list, inspect, and remove ingested documen

 #### Scenario: Get document details
 - **WHEN** a client sends `GET /api/v1/documents/{id}`
- **THEN** the engine SHALL return the full document record including all chunks and their text content
+- **THEN** the engine SHALL return the full document record including all chunks, their text content, and whether the original file is available (`has_file: true/false`)
+
+#### Scenario: Download original file
+- **WHEN** a client sends `GET /api/v1/documents/{id}/file`
+- **THEN** the engine SHALL return the original file with appropriate Content-Type and `Content-Disposition: attachment; filename="{original_filename}"` headers, or HTTP 404 if the file is not available

 #### Scenario: Remove a document
 - **WHEN** a client sends `DELETE /api/v1/documents/{id}`
- **THEN** the engine SHALL delete the document, all its chunks, associated embeddings, and tag associations, and return HTTP 200 with a confirmation
+- **THEN** the engine SHALL delete the document, all its chunks, associated embeddings, tag associations, and the stored original file from disk, and return HTTP 200 with a confirmation

 #### Scenario: Remove non-existent document
 - **WHEN** a client sends `DELETE /api/v1/documents/{id}` with a non-existent ID
@@ -230,7 +234,7 @@ The engine SHALL be configured via environment variables. No config file is read

 #### Scenario: Default configuration
 - **WHEN** the engine starts with no environment variables set
- **THEN** it SHALL use defaults: data directory `/data`, model `all-MiniLM-L6-v2`, device `auto`, no API key required
+- **THEN** it SHALL use defaults: data directory `/data`, model `all-MiniLM-L6-v2`, device `auto`, no API key required. It SHALL create `staging/` and `documents/` subdirectories under the data directory.

 #### Scenario: Custom model
 - **WHEN** `KB_MODEL` is set to `BAAI/bge-small-en-v1.5`