Updated project-context.md

project-context.md

@@ -417,6 +417,43 @@ admin / admin
 
 ---
 
+## Restart After Local Changes
+
+If the app is running manually in a terminal:
+
+1. Stop it with `Ctrl+C`.
+2. Make changes or pull changes from Git.
+3. Restart the app.
+
+Local restart command:
+
+```bash
+.venv/bin/python run.py
+```
+
+If dependencies changed:
+
+```bash
+.venv/bin/pip install -r requirements.txt
+```
+
+If database tables changed:
+
+```bash
+.venv/bin/python scripts/init_db.py
+```
+
+Typical local update flow:
+
+```bash
+git pull
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python scripts/init_db.py
+.venv/bin/python run.py
+```
+
+---
+
 ## Run Tests
 
 Run:
@@ -557,6 +594,61 @@ The active SQLite database is intentionally not committed.
 
 ---
 
+## What To Commit To Git
+
+Safe and expected to commit:
+
+```text
+app/
+scripts/
+tests/
+app.py
+run.py
+requirements.txt
+.gitignore
+project-context.md
+```
+
+Also commit deletions/moves when files are refactored.
+
+Current old paths that were replaced:
+
+```text
+init_db.py
+templates/
+static/
+```
+
+These old paths should remain deleted once the new `app/` package layout is committed.
+
+---
+
+## What Not To Commit
+
+Keep these local only:
+
+```text
+.venv/
+instance/
+instance/questions.db
+questions.db
+.env
+__pycache__/
+.vscode/
+.idea/
+```
+
+Reasons:
+
+* `.venv/` is machine-specific.
+* SQLite databases contain local runtime data.
+* `.env` may contain secrets.
+* cache/editor files are not project source.
+
+Even with a self-hosted private Git server, avoid committing secrets.
+
+---
+
 # Future Admin Features
 
 ## Dashboard Version 2
@@ -707,7 +799,119 @@ Potential providers:
 
 # Future Raspberry Pi Deployment
 
-Not currently being worked on.
+Local Raspberry Pi testing is currently done manually on the home network.
+
+The future goal is to run the app as a managed service with `systemd`, then later put it behind Gunicorn/Nginx for production.
+
+---
+
+## Raspberry Pi Local Network Test Setup
+
+Install system dependencies:
+
+```bash
+sudo apt update
+sudo apt install -y git python3 python3-venv
+```
+
+Clone the repo:
+
+```bash
+git clone <your-self-hosted-git-url> wyr
+cd wyr
+```
+
+Create and install into a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+Set local secrets and initialize the database:
+
+```bash
+export WYR_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
+export WYR_ADMIN_USERNAME="youradmin"
+export WYR_ADMIN_PASSWORD="yourstrongpassword"
+
+.venv/bin/python scripts/init_db.py
+```
+
+Run on the home LAN:
+
+```bash
+WYR_SECRET_KEY="$WYR_SECRET_KEY" .venv/bin/flask --app run run --host 0.0.0.0 --port 5000
+```
+
+Open from another device on the same network:
+
+```text
+http://<raspberry-pi-ip>:5000
+```
+
+Admin:
+
+```text
+http://<raspberry-pi-ip>:5000/admin/login
+```
+
+Do not port-forward this app to the public internet yet.
+
+---
+
+## Restart On The Pi During Manual Testing
+
+If running manually in a terminal:
+
+1. Press `Ctrl+C`.
+2. Pull changes.
+3. Install any dependency updates.
+4. Run database setup if needed.
+5. Start the app again.
+
+Command sequence:
+
+```bash
+git pull
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python scripts/init_db.py
+WYR_SECRET_KEY="$WYR_SECRET_KEY" .venv/bin/flask --app run run --host 0.0.0.0 --port 5000
+```
+
+If the Pi reboots, manually `cd` back into the project and run the Flask command again.
+
+This will become easier after adding `systemd`.
+
+---
+
+## Future Systemd Service
+
+Future goal:
+
+```bash
+sudo systemctl start wyr
+sudo systemctl stop wyr
+sudo systemctl restart wyr
+sudo systemctl status wyr
+```
+
+Benefits:
+
+* app can start automatically after Pi reboot
+* easier restart command
+* logs can be viewed with `journalctl`
+* app can run in the background without an open terminal
+
+Example future log command:
+
+```bash
+journalctl -u wyr -f
+```
+
+This is not implemented yet.
+
+---
 
 Planned deployment stack:
 
@@ -741,6 +945,15 @@ On Pi:
 
 ```bash
 git pull
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python scripts/init_db.py
+```
+
+Then manually restart the Flask command.
+
+Later, after the `systemd` service exists, the Pi restart step will become:
+
+```bash
 sudo systemctl restart wyr
 ```
 
@@ -756,12 +969,36 @@ Local refactor and Admin Dashboard V1 are implemented.
 
 ## Next Step
 
-Polish the admin flow and public UI:
+Add cooler layout and styling:
+
+* improve the public voting page design
+* improve the results page design
+* improve admin dashboard styling
+* make buttons, forms, and navigation feel more polished
+* add better spacing, typography, and responsive layout
+
+---
+
+## After Styling
+
+Polish the admin flow and public behavior:
 
 * improve layout
 * add clearer success messages
 * add better vote duplicate handling
 * improve the empty state when no question is scheduled for today
+* add CSRF protection before public internet exposure
+
+---
+
+## After Local Pi Testing
+
+Implement:
+
+* `systemd` service for easier Pi management
+* automatic start on reboot
+* clearer production environment variables
+* basic log inspection workflow with `journalctl`
 
 ---