# Repository Guidelines

## Project Structure & Module Organization
- Root `README.md` describes the learning roadmap (RU) and serves as the main page of the MkDocs site.
- `dwh-modeling/` contains the article and demo DWH model; SQL lives in `dwh-modeling/sql` as ordered scripts `01_...sql`–`09_...sql` (07–09 are homework DDL, template and solution).
- `postgres-bookings/` is a Dockerized PostgreSQL + demo “bookings” DB; start it first, then apply DWH scripts against the `demo` database.
- `mkdocs.yml` — MkDocs Material config; `docs_dir: .` (repo root = site root). Excluded dirs: `project/`, `postgres-bookings/`, `.gitea/`, `.github/`, `.claude/`.
- `.gitea/workflows/deploy-site.yml` — основной CI/CD: push в `main` → строгая
  сборка → атомарная публикация на VPS через repository-scoped Gitea Runner.
- `.github/workflows/deploy-site.yml` — сохранённый workflow для резервной
  публикации на GitHub Pages; Gitea его не исполняет.
- `project/` — PRD, ADR, and TODO.md (excluded from site). `project/TODO.md` is the prioritized project backlog: check it when planning or proposing work, and mark items done there when you complete them.

## Build, Test, and Development Commands
- Start demo Postgres:  
  `cd postgres-bookings && bash download_db.sh && docker compose up -d`
- Open `psql` inside the container:  
  `cd postgres-bookings && ./psql_sh`
- Apply DWH schema from the repo root (after Postgres is up):  
  `psql -h 127.0.0.1 -p 5432 -U postgres -d demo -f dwh-modeling/sql/01_ddl_stg-dds.sql`
- Stop and reset the cluster when needed:  
  `cd postgres-bookings && docker compose down -v`

## Coding Style & Naming Conventions
- SQL: PostgreSQL dialect, uppercase keywords, `snake_case` identifiers, 4-space indentation, and concise comments (`-- ...`).
- SQL files: keep numeric prefixes (`01_`, `02_`, …) to reflect execution order and use descriptive suffixes like `ddl_*` / `dml_*`.
- Shell: target `bash`, prefer simple, POSIX-friendly constructs; mirror the style of existing scripts in `postgres-bookings/`.

## Markdown Style (dual-compatible: GitHub + MkDocs Material)

All `.md` files MUST render correctly on both GitHub and the MkDocs Material site. Follow these rules:

**Headings:**
- `README.md` (root): start from `##` (H2). Do NOT use `#` (H1) — MkDocs uses H1 as page title, multiple H1s break the right-sidebar TOC.
- `dwh-modeling/*.md`: may use `#` (H1) since each file is a separate page on the site.

**Lists:**
- Always leave a **blank line before the first list item** after a paragraph, heading, or any non-list text. Python-Markdown (MkDocs) requires this; GitHub tolerates its absence but blank lines don't hurt.
- Use **4-space indentation** for nested lists (not 2-space). GitHub supports both, Python-Markdown requires 4.
- Example:
  ```markdown
  Some introductory text:

  - Item one
  - Item two
      - Nested item (4 spaces)
  ```

**Links:**
- Internal links: always use **relative paths to `.md` files**: `[text](dwh-modeling/SCD.md)`. MkDocs resolves them automatically.
- Anchor links: use lowercase slugs with single hyphens. Avoid em-dash `—` in headings (it produces `--` in MkDocs slugs vs `-` on GitHub). Use commas or colons instead.

**Special characters in headings:**
- OK: colons `:`, commas `,`, parentheses `()`, guillemets `«»` — stripped equally by both platforms.
- Avoid: em-dash `—`, en-dash `–` — slug behavior differs between GitHub and MkDocs.

## MkDocs Site Commands
- Initialize or update the persistent local environment:
  `python3 -m venv "${HOME}/.cache/de-roadmap-mkdocs" && "${HOME}/.cache/de-roadmap-mkdocs/bin/python" -m pip install -r .gitea/requirements-site.txt`
- Local preview (user starts, ask user to run via `!`):
  `"${HOME}/.cache/de-roadmap-mkdocs/bin/python" -m mkdocs serve`
- Build with strict validation (catches broken links/anchors):
  `"${HOME}/.cache/de-roadmap-mkdocs/bin/python" -m mkdocs build --strict`
- Visual check via Playwright (when `mkdocs serve` is running on port 8000):
  `npx playwright screenshot --viewport-size='1280,800' 'http://127.0.0.1:8000/#anchor' /path/to/screenshot.png`
  Then read the screenshot with the Read tool to inspect rendering. Use `--viewport-size='1280,2000'` for tall pages.
- Kill stuck dev server: `lsof -ti :8000 | xargs kill`
- Site URL: `https://de.dementev.space/` (старый адрес `https://dementev-dev.github.io/de-roadmap/` отдаёт 404)

## Testing Guidelines
- There is no dedicated test framework; treat SQL scripts as executable documentation.
- For `dwh-modeling/sql`, run scripts sequentially and rerun `04_validation.sql` after changes to ensure the demo model still loads and basic checks pass.
- For `postgres-bookings`, after modifications run `docker compose up -d && ./psql_sh` and verify simple queries such as `SELECT COUNT(*) FROM bookings.flights;`.

## Commit & Pull Request Guidelines

**Required:** Read [COMMIT_RULES.md](COMMIT_RULES.md) before making commits.

Pull requests should focus on one topic, include a brief context, list of changes, and manual steps to reproduce or validate (commands you ran, expected results).

## Security & Configuration Tips
- Do not commit personal `.env` files or credentials; use local overrides only.
- Gitea Runner работает в host mode: не расширяйте его scope, не добавляйте
  пользователя `gitea-runner` в `sudo` или `docker` и не выдавайте ему запись
  вне `/var/lib/gitea-runner` и `/srv/de-roadmap`.
- Demo credentials and ports in `postgres-bookings` are for local training only—never reuse them in shared or production environments.