diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c4ff06e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,141 @@
+# Примеры sless
+
+Примеры показывают различные сценарии использования serverless функций через Terraform провайдер `terra.k8c.ru/naeel/sless`.
+
+## Требования
+
+- Terraform >= 1.0
+- Доступ к `https://sless-api.kube5s.ru`
+
+## Провайдер
+
+Во всех примерах `main.tf` содержит:
+
+```hcl
+provider "sless" {
+  endpoint = "https://sless-api.kube5s.ru"
+}
+```
+
+---
+
+## Примеры
+
+### `simple-python` — джоб передаёт результат в HTTP-функцию (Python)
+
+При `apply` запускается джоб, его вывод передаётся в HTTP-функцию через `env_vars`.
+
+```bash
+cd simple-python
+terraform init
+terraform apply -auto-approve
+
+# Что вернул джоб (время на момент деплоя):
+terraform output job_result
+
+# Проверить функцию:
+curl -s $(terraform output -raw display_url)
+```
+
+---
+
+### `simple-node` — то же самое, но на Node.js 20
+
+```bash
+cd simple-node
+terraform init
+terraform apply -auto-approve
+
+terraform output job_result
+curl -s $(terraform output -raw display_url)
+```
+
+---
+
+### `hello-node` — минимальный пример на Node.js
+
+Две независимые функции: HTTP-функция (возвращает приветствие) и одноразовый джоб (суммирует числа).
+
+```bash
+cd hello-node
+terraform init
+terraform apply -auto-approve
+
+# Проверить HTTP-функцию:
+curl -s -X POST $(terraform output -raw trigger_url) \
+  -H 'Content-Type: application/json' -d '{"name":"World"}'
+
+# Посмотреть результат джоба:
+terraform output job_message
+```
+
+---
+
+### `notes-python` — CRUD API на Python + PostgreSQL
+
+Полноценное приложение: инициализация схемы БД через джобы, CRUD-функция, read-only функция для списка записей.
+
+**Переменные:**
+
+| Переменная | Описание | Дефолт |
+|---|---|---|
+| `pg_dsn` | DSN для подключения к PostgreSQL | `postgres://sless:sless-pg-password@postgres.sless.svc.cluster.local:5432/sless?sslmode=disable` |
+
+```bash
+cd notes-python
+terraform init
+
+# Опционально — переопределить DSN:
+# export TF_VAR_pg_dsn="postgres://user:pass@host:5432/db?sslmode=disable"
+
+terraform apply -auto-approve
+
+# Проверить инициализацию БД:
+terraform output db_init_table_status
+terraform output db_init_index_status
+
+# URL функций:
+terraform output notes_url       # CRUD
+terraform output notes_list_url  # список всех записей
+
+# Создать запись:
+curl -s -X POST "$(terraform output -raw notes_url)/add?title=Hello&body=World"
+
+# Список записей:
+curl -s $(terraform output -raw notes_list_url)
+
+# Обновить (id из предыдущего ответа):
+curl -s -X POST "$(terraform output -raw notes_url)/update?id=1&title=Updated&body=New+body"
+
+# Удалить:
+curl -s -X POST "$(terraform output -raw notes_url)/delete?id=1"
+```
+
+---
+
+## Общие команды
+
+```bash
+# Посмотреть текущее состояние ресурсов:
+terraform show
+
+# Пересоздать конкретный ресурс:
+terraform apply -replace=sless_function.имя -auto-approve
+
+# Повторно запустить джоб — увеличить run_id в .tf файле, затем:
+terraform apply -auto-approve
+
+# Удалить все ресурсы примера:
+terraform destroy -auto-approve
+```
+
+## Структура каждого примера
+
+```
+пример/
+├── main.tf        — провайдер
+├── *.tf           — ресурсы (функции, триггеры, джобы)
+├── outputs.tf     — URLs и статусы после apply
+├── variables.tf   — входные переменные (если есть)
+└── code/          — исходный код функций
+```