Initial commit

README.md

@@ -0,0 +1,60 @@
+# Wordsmith — Puzzle Workshop
+
+A small self-hosted web app that generates printable word search PDFs from
+themed word lists. Single Python process, no database, no build step.
+
+## Stack
+
+- Python 3.14+
+- FastAPI + Jinja2 (server-rendered HTML)
+- reportlab (PDF)
+- A small piece of vanilla JS for the live theme-editor preview
+
+## Local development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+```
+
+`--reload` restarts on `.py` changes; Jinja templates reload without a restart.
+
+## Docker
+
+```bash
+docker compose up --build
+```
+
+Maps host port `3801` → container `8000`. The bind-mounts `./themes:/app/themes`,
+so any theme JSON files in the repo's `themes/` folder are picked up at boot
+and any UI-edited themes are written back to the same place.
+
+## Themes
+
+Each theme is a flat JSON file under `themes/<slug>.json`:
+
+```json
+{
+  "name": "Mr Men Characters",
+  "words": ["Mr Tickle", "Mr Happy", "Little Miss Sunshine"]
+}
+```
+
+Words can include leading honorific tokens (`Mr`, `Mrs`, `Miss`, `Dr`,
+`Captain`, etc.) — they're stripped from the grid form but kept on the PDF
+word list in parentheses, e.g. `TICKLE (Mr)`.
+
+## Deployment
+
+The repo is intended to be deployed via [Komodo](https://komo.do)'s git-stack
+mode: point a stack at this repo, set the compose path to `docker-compose.yml`,
+and redeploy. Themes added via the deployed UI live in Komodo's per-stack
+checkout — they survive normal redeploys but a Komodo "Destroy" wipes them.
+For lasting changes, edit themes locally and `git push`.
+
+## Generated PDFs
+
+Generated puzzles stream straight to the browser as a download
+(`<slug>_<YYYY-MM-DD_HH-MM-SS>.pdf`); the server keeps no copy on disk.