Adding specializing instructions

README.md

@@ -37,6 +37,76 @@ scripts/seed.py  bootstrap permissions, roles, first superuser
 tests/         pytest (auth + RBAC)
 ```
 
+## Starting a new project
+
+Fork or copy this repo, then update these six things before writing any code:
+
+### 1. Project package name — `pyproject.toml`
+
+```toml
+[project]
+name = "my-app"                         # used by uv/pip
+description = "What your app does."
+```
+
+### 2. Application display name — `.env` / environment
+
+The name shown in the browser title bar, nav bar, and `/docs` page title is
+driven by `APP_NAME` in your `.env` (or any environment variable override):
+
+```bash
+APP_NAME="My App"
+```
+
+This is the only runtime change needed — templates read `{{ app_name }}`
+from `settings.app_name`, which is sourced from this variable. No template
+edits required.
+
+### 3. Superuser credentials — `.env`
+
+```bash
+FIRST_SUPERUSER_EMAIL=admin@yourapp.com
+FIRST_SUPERUSER_PASSWORD=<strong-password>
+```
+
+### 4. Secret key — `.env`
+
+```bash
+SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
+```
+
+Never commit a real secret key. The placeholder in `.env.example` is intentionally weak.
+
+### 5. Docker / Postgres identifiers — `docker-compose.yml`
+
+The compose file uses `app` as the Postgres username, password, and database
+name. Rename them consistently:
+
+```yaml
+# db service
+POSTGRES_USER: myapp
+POSTGRES_PASSWORD: <strong-password>
+POSTGRES_DB: myapp
+
+# app service
+DATABASE_URL: postgresql+asyncpg://myapp:<strong-password>@db:5432/myapp
+```
+
+### 6. This README
+
+Replace the title and description with your project's own.
+
+---
+
+After these changes, run the normal setup:
+
+```bash
+uv sync --extra dev
+cp .env.example .env   # edit the values above
+uv run python -m scripts.seed
+uv run uvicorn app.main:app --reload
+```
+
 ## Quick start (local, SQLite)
 
 ```bash