From 2b038f13eb03e6f0c77d2b09e279889d161f8c7a Mon Sep 17 00:00:00 2001
From: David_MBravo <davidmunozbravo28@gmail.com>
Date: Wed, 29 Jul 2026 12:31:15 +0200
Subject: [PATCH] docs(demo): add seed-full target and update docs for complete
 DB setup

---
 CONTRIBUTING.md | 8 ++++++--
 Makefile        | 8 ++++++--
 README.md       | 8 ++++++--
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 42ee836..87f98a3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -50,8 +50,12 @@ python scripts/generate_keys.py
 # 6. Local database (Postgres + pgvector via Docker)
 docker compose up -d
 
-# 7. Seed the 3 demo authors
-python scripts/seed_corpus.py
+# 7. Seed the 3 demo authors (raw text + embeddings + style profiles)
+python scripts/seed_corpus.py --with-embeddings --with-profiles
+# ⚠️  This step is slow on first run. It downloads two large ML models:
+#     • all-mpnet-base-v2  (~420 MB, sentence-transformers)
+#     • en_core_web_lg     (~560 MB, spaCy)
+# Omit both flags for a fast seed (raw text only, no profiles/embeddings).
 ```
 
 Editor extensions (highly recommended — auto-format on save): **Ruff**, **Black Formatter**, **Prettier**, **Python**. See §8.4.
diff --git a/Makefile b/Makefile
index 0465170..1a763df 100644
--- a/Makefile
+++ b/Makefile
@@ -9,7 +9,7 @@
 # Usage: `make help` to list targets.
 
 .DEFAULT_GOAL := help
-.PHONY: help install install-py install-front keys db-up db-down seed seed-dry demo \
+.PHONY: help install install-py install-front keys db-up db-down seed seed-full seed-dry demo \
         dev back front lint format test clean
 
 # ---- Meta -------------------------------------------------------------------
@@ -58,10 +58,14 @@ db-down: ## Stop the local database
 	$(call need_file,docker-compose.yml,Sprint 1)
 	docker compose down
 
-seed: ## Seed the DB with the 3 preloaded authors (Austen, Dickens, Poe)
+seed: ## Seed the DB with raw text only — fast, no ML models required
 	$(call need_file,scripts/seed_corpus.py,Sprint 2)
 	python scripts/seed_corpus.py
 
+seed-full: ## Seed the DB + compute embeddings and style profiles (downloads ~980 MB of ML models on first run)
+	$(call need_file,scripts/seed_corpus.py,Sprint 2)
+	python scripts/seed_corpus.py --with-embeddings --with-profiles
+
 seed-dry: ## Validate corpus files and print manifest without touching the DB
 	$(call need_file,scripts/seed_corpus.py,Sprint 2)
 	python scripts/seed_corpus.py --dry-run
diff --git a/README.md b/README.md
index c6a48bf..6937e09 100644
--- a/README.md
+++ b/README.md
@@ -170,8 +170,12 @@ make keys
 # 5. Start local Postgres + pgvector
 make db-up
 
-# 6. Seed the database with the 3 preloaded authors
-make seed
+# 6. Seed the database: raw text + embeddings + style profiles
+make seed-full
+# ⚠️  This step is slow on first run. It downloads two large ML models:
+#     • all-mpnet-base-v2  (~420 MB, sentence-transformers)
+#     • en_core_web_lg     (~560 MB, spaCy)
+# If you only need raw text without profiles/embeddings, use `make seed` instead.
 
 # 7. Start backend + frontend (parallel)
 make dev