Add project onboarding documentation

.env.example

@@ -0,0 +1,2 @@
+DATABASE_URL="postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
+NODE_ENV="development"

.nvmrc

@@ -0,0 +1 @@
+22

AGENTS.md

@@ -0,0 +1,80 @@
+# Agent Instructions
+
+These instructions apply to AI coding agents working in this repository.
+
+## Project context
+
+This is an educational full-stack project focused on backend development. The expected stack is Node.js, React, and a local PostgreSQL database on Ubuntu.
+
+The repository may start with only documentation and gradually grow into a structured application. Prefer small, understandable changes that are suitable for students learning backend engineering.
+
+## Communication
+
+- Reply to the user in Czech unless the user explicitly asks for another language.
+- Write documentation, code comments, commit messages, and generated project text in English.
+- Keep explanations practical and tied to the current codebase.
+
+## Engineering guidelines
+
+- Read the existing files before making assumptions about project structure.
+- Follow existing conventions once code is added.
+- Keep changes scoped to the requested task.
+- Prefer clear, boring solutions over clever abstractions.
+- Add comments only when they clarify non-obvious behavior.
+- Do not commit local secrets, `.env` files, database dumps, or generated dependency directories.
+
+## Expected local tools
+
+- Node.js 22 or newer
+- PostgreSQL installed locally
+- Git
+- npm unless the repository later standardizes on another package manager
+
+## Suggested application conventions
+
+When application code is introduced, prefer this layout unless the project chooses another structure:
+
+```text
+apps/backend
+apps/web
+packages/shared
+docs
+```
+
+For backend work, include:
+
+- Explicit environment variable validation.
+- Database migrations instead of manual schema changes.
+- Focused automated tests for controllers, services, and database behavior.
+- Clear separation between HTTP handlers, business logic, and persistence.
+
+For frontend work, include:
+
+- React components with clear responsibilities.
+- Typed API contracts shared with or generated from the backend when practical.
+- Accessible forms, loading states, and error states.
+
+## Database guidance
+
+- Use a dedicated local database user for the application.
+- Do not use the `postgres` superuser as the application user.
+- Store local connection strings in `.env`.
+- Keep schema changes in migrations once a migration tool is selected.
+
+Recommended local development database URL:
+
+```bash
+DATABASE_URL="postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
+```
+
+## Verification
+
+Before finishing code changes, run the relevant checks when they exist:
+
+```bash
+npm run lint
+npm run test
+npm run build
+```
+
+If a command is missing because the project has not been scaffolded yet, state that clearly in the final response.

README.md

@@ -1,2 +1,191 @@
-# rg_backend_academy
+# RG Backend Academy
 
+Educational full-stack project for learning backend development with Node.js, React, and a local PostgreSQL database.
+
+The repository is intentionally small at the moment. Use this document as the baseline environment guide before adding the backend, frontend, database schema, tests, and deployment notes.
+
+## Planned stack
+
+- Node.js 22 LTS or newer
+- npm, pnpm, or another package manager selected by the project
+- React for the frontend application
+- PostgreSQL running locally on Ubuntu
+- Git for version control
+
+## Ubuntu environment setup
+
+The commands below target Ubuntu or Ubuntu-based Linux distributions.
+
+### 1. Install system dependencies
+
+```bash
+sudo apt update
+sudo apt install -y curl ca-certificates gnupg git build-essential postgresql postgresql-contrib
+```
+
+### 2. Install Node.js 22 with nvm
+
+Using `nvm` keeps the project Node.js version isolated from the system installation.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+```
+
+Restart the terminal, then install and use Node.js 22:
+
+```bash
+nvm install 22
+nvm use 22
+node --version
+npm --version
+```
+
+Expected Node.js version:
+
+```text
+v22.x.x
+```
+
+This repository includes a `.nvmrc` file, so later terminal sessions can use:
+
+```bash
+nvm use
+```
+
+### 3. Start PostgreSQL
+
+```bash
+sudo systemctl enable --now postgresql
+sudo systemctl status postgresql
+```
+
+### 4. Create a local development database
+
+Use a dedicated application user instead of the default `postgres` superuser.
+
+```bash
+sudo -u postgres psql
+```
+
+Inside the PostgreSQL shell:
+
+```sql
+CREATE USER rg_academy WITH PASSWORD 'rg_academy';
+CREATE DATABASE rg_academy_dev OWNER rg_academy;
+GRANT ALL PRIVILEGES ON DATABASE rg_academy_dev TO rg_academy;
+\q
+```
+
+Test the connection:
+
+```bash
+psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
+```
+
+Exit with:
+
+```sql
+\q
+```
+
+### 5. Environment variables
+
+When the backend application is added, create a local `.env` file from the provided example file.
+
+Expected baseline variables:
+
+```bash
+DATABASE_URL="postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
+NODE_ENV="development"
+```
+
+Do not commit `.env` files with secrets or local credentials.
+
+## Suggested repository structure
+
+The exact structure may evolve, but this is the recommended starting point:
+
+```text
+.
+├── apps
+│   ├── backend
+│   └── web
+├── packages
+│   └── shared
+├── docs
+├── README.md
+└── AGENTS.md
+```
+
+## Development workflow
+
+After the project code is added, the usual local workflow should be:
+
+```bash
+nvm use
+npm install
+npm run dev
+```
+
+Recommended scripts to add once the application exists:
+
+- `npm run dev` - start local backend and frontend development servers.
+- `npm run test` - run automated tests.
+- `npm run lint` - run static checks.
+- `npm run format` - format source files.
+- `npm run db:migrate` - apply database migrations.
+- `npm run db:seed` - seed local development data.
+
+## PostgreSQL quick reference
+
+Open the project database:
+
+```bash
+psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
+```
+
+List databases:
+
+```sql
+\l
+```
+
+List tables:
+
+```sql
+\dt
+```
+
+Describe a table:
+
+```sql
+\d table_name
+```
+
+## Troubleshooting
+
+Check whether PostgreSQL is running:
+
+```bash
+sudo systemctl status postgresql
+```
+
+Restart PostgreSQL:
+
+```bash
+sudo systemctl restart postgresql
+```
+
+Check the installed Node.js version:
+
+```bash
+node --version
+```
+
+If `psql` cannot connect, verify that PostgreSQL is listening locally and that the database URL matches the user, password, host, port, and database name.
+
+## Documentation rules
+
+- Project documentation is written in English.
+- Code comments are written in English.
+- User-facing chat responses for this project should be in Czech unless the user asks otherwise.