interactive-story/plan/07-phase-public-repo.md

Phase 7 — Public repo & portability

Goal: make the repo public-worthy and runnable by anyone on any OS, so the GitHub link is immediately usable on a resume — before any hosted-deployment work.

Decisions (confirmed)

Question	Answer
License	MIT
README media (screenshots/GIF)	Skip for now — text-only README; visuals in a later pass

Repo name (decided): AI-DnD. Ask before publishing: whether the existing commit history/messages are fine to publish as-is.

Repo hygiene

• Add LICENSE (MIT, current year, Parth Thakkar).
• Verify no secrets or user data are tracked (openrouter_key.env, data.db — already gitignored and never committed; re-verify before push).
• Add backend/.env.example documenting every env var the app reads (grows in Phase 9). (Currently just AIDND_DB_PATH, added to database.py for Docker/hosted volumes.)
• Decide what to do with CODE_REVIEW_FINDINGS.md and plan/ — keep (shows process, good for a portfolio) — just give them a one-line mention in the README.

README rewrite (portfolio-grade, text-only)

• Pitch paragraph: what it is, what makes it interesting (AI Dungeon-compatible scripting, memory bank with embeddings, full prompt transparency/Insights, provider-agnostic).
• Feature list with pointers into the code (scripting engine, context builder, memory bank).
• Architecture diagram (reuse/refresh the one in plan/00-OVERVIEW.md).
• Setup instructions for Windows (start.ps1), macOS/Linux (manual), and Docker.
• "Bring your own model" section: Ollama / LM Studio / OpenRouter free models — emphasize it runs fully free.
• Placeholder section for screenshots/GIF (added in a later pass).

Docker (one-command run for non-Windows users)

• Dockerfile: multi-stage — build frontend (npm run build), then Python image serving FastAPI with the built SPA mounted (SPA fallback already exists in app/main.py). (3 stages: node build → pip wheel build with gcc for quickjs → slim runtime.)
• docker-compose.yml: single service, named volume mounted at /data (AIDND_DB_PATH=/data/data.db), port mapping.
• start.sh for macOS/Linux dev parity with start.ps1 (optional, nice-to-have).
• Test: docker compose up from a clean clone → app works at http://localhost:8000. Done 2026-07-06 in WSL2 Ubuntu (Docker Engine installed there for this): health + SPA + deep links 200, scenario created via API survives a full compose down/up (named volume). Two real bugs found and fixed: package-lock.json was missing top-level @emnapi/* entries (regenerated with npm 11.18) and the build image needed node 24 to match the npm-11 lockfile. Note: from Windows, reach a WSL-hosted container via the WSL IP (hostname -I) — localhost forwarding didn't apply; irrelevant on normal hosts.

Publish

• Create public GitHub repo (gh repo create), push main.
• Add repo description, topics (ai-dungeon, fastapi, react, llm, interactive-fiction).
• Confirm the GitHub rendering of README looks right.

Exit criteria

A stranger on macOS with Docker installed can clone the repo, run one command, open the app, paste an OpenRouter free-tier key, and play an adventure — without asking you anything.