docs: add deployment and technical documentation

README.md

@@ -2,6 +2,11 @@
 
 Monorepo for the Cogniro project.
 
+## Documentation
+
+- [Technical documentation](docs/TECHNICAL-DOCUMENTATION.md) - architecture, technology stack, security and authentication, and the persistence and concurrency model.
+- [Deployment guide](docs/DEPLOYMENT.md) - step-by-step setup and run instructions, with and without Docker, including all environment variables.
+
 ## Structure
 
 ```text
@@ -12,7 +17,7 @@ cogniro/
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/) (v20+)
+- [Node.js](https://nodejs.org/) 22
 - [pnpm](https://pnpm.io/) 10+
 - [Python](https://www.python.org/) (>=3.14)
 - [uv](https://docs.astral.sh/uv/) (for backend)

backend/.env.example

@@ -1,5 +1,11 @@
 # Copy to .env and fill in real values. Never commit .env.
 
+# Deployment stage. Accepts ENVIRONMENT or ENV; defaults to "development".
+# Any value other than development/dev/local/test is treated as production: the app then
+# refuses to start if ADMIN_PASSWORD_HASH or JWT_SECRET is missing (instead of only warning).
+# Set this to production for real deployments so misconfigured auth fails fast.
+# ENVIRONMENT=production
+
 # --- Admin auth (POST /admin/auth/login) ---
 # Generate a bcrypt hash locally, then paste only the hash here:
 #   uv run python scripts/hash_admin_password.py