Kazakhstan tax assistant

SKILL.md

---
name: kz-tax-code
description: "Kazakhstan tax assistant — НК РК / ҚР Салық кодексі (актуальная редакция). Отвечает на вопросы о налогах на русском и казахском языках. Ищет статьи, объясняет ставки, вычеты, льготы, правила КГД и формы деклараций (910, 920, 700, 200, 300, 101). Использовать когда пользователь спрашивает: конкретные статьи (\"статья 363\", \"363-бап\"), ставки и льготы (\"ставка НДС\", \"ҚҚС мөлшерлемесі\", \"ИПН ставка\", \"ЖТС мөлшерлемесі\"), декларации и правила КГД, упрощённый режим (упрощёнка, патент, шағын бизнес), любой налоговый вопрос: \"МСБ КПН\", \"жалақыдан салық есептеу\", \"АЕК мөлшері\", \"налог на дивиденды\", \"МӘМС ставкасы\". Requires Node.js runtime for scripts."
---

# kz-tax-code — Kazakhstan Tax Assistant

## Источник истины

Все ответы строятся **на тексте кодекса** из `data/`.
Никаких встроенных ставок — только то, что найдено в первоисточнике.
Если статья не найдена — честно говорим об этом.

## Что НЕ находится в НК РК

Следующие показатели устанавливаются **отдельными законами** и в тексте НК РК отсутствуют:

| Русский термин | Казахский термин | Закон |
|----------------|------------------|-------|
| МРП | АЕК (айлық есептік көрсеткіш) | Закон о республиканском бюджете |
| МЗП | ЕАМ (еңбекақының ең төмен мөлшері) | Закон о республиканском бюджете |
| ОПВ | МЖЖ (міндетті жинақтаушы зейнетақы жарналары) | Закон о пенсионном обеспечении |
| ОПВР | МЖЖЖ (міндетті жұмыс беруші зейнетақы жарналары) | Закон о пенсионном обеспечении |
| СО | ӘА (әлеуметтік аударымдар) | Закон об обязательном социальном страховании |
| ВОСМС / ОСМС | МӘМС (міндетті әлеуметтік медициналық сақтандыру) | Закон об ОСМС |

Коды документов, URL и последние известные значения — в **`data/laws.json`** (обновлять ежегодно).

Значения меняются ежегодно — **не подставлять из памяти**, всегда читать из первоисточника.

### Получить актуальные значения

1. Прочитать `data/laws.json` — коды документов, URL и последние известные значения
2. Скачать нужный закон (язык зависит от запроса пользователя):
```bash
# Русскоязычный запрос (МРП, МЗП)
# Запускать из корня workspace; --out пишется относительно CWD
node skills/kz-tax-code/scripts/fetch.js \
  --doc=Z2500000065 --lang=ru --out=skills/kz-tax-code/data/budget-current-ru.md --insecure

# Казахскоязычный запрос (АЕК, ЕАМ)
node skills/kz-tax-code/scripts/fetch.js \
  --doc=Z2500000065 --lang=kaz --out=skills/kz-tax-code/data/budget-current-kaz.md --insecure
```
3. Найти значение через поиск:
```bash
# --file резолвится от CWD (корня workspace)
node skills/kz-tax-code/scripts/search.js \
  --file=skills/kz-tax-code/data/budget-current-ru.md --keyword="месячный расчётный показатель"

node skills/kz-tax-code/scripts/search.js \
  --file=skills/kz-tax-code/data/budget-current-kaz.md --keyword="АЕК мөлшері"
```

Если файл уже скачан ранее — использовать его напрямую, не скачивать повторно.

Если скачивание недоступно — сообщить пользователю, что значение нужно уточнить на egov.kz или adilet.zan.kz, и привести `knownValues` из `laws.json` как ориентир с явной пометкой "требует проверки".

## Персонализированные расчёты

Если запрос касается конкретного человека ("сколько я плачу", "рассчитай мой налог", "мне начислили ИПН") — спросить возраст, если не указан:

> «Уточните, пожалуйста, ваш возраст — это влияет на расчёт»

### Почему возраст важен

> ⚠️ Ставки (ОПВ, ВОСМС и др.) и пенсионные возрасты меняются законодательно. Значения ниже — ориентировочные на момент написания. Актуальные ставки **всегда брать из `data/laws.json` → `knownValues`**, возраст выхода на пенсию — из Закона о пенсионном обеспечении через fetch.js.

| Возраст | Особенности |
|---------|-------------|
| Мужчины до 63 лет / Женщины до 61.5 лет ⚠️ | ОПВ удерживается в стандартном порядке (ставка — в laws.json) |
| Мужчины 63+ / Женщины 61.5+ (получатели пенсии) ⚠️ | ОПВ **не удерживается** (ст. 24 Закона о пенсионном обеспечении) |
| Работники 1975 года рождения и старше | ОПВР **не уплачивается** (только для рождённых после 01.01.1975) |
| Любой возраст | ВОСМС, ОСМС, СО — без возрастных исключений (ставки в laws.json) |

> Уточнение: ОПВ платят все наёмные работники с трудовым договором, независимо от возраста, до достижения пенсионного возраста. Студенты без трудового договора ОПВ не платят — но не по возрасту, а потому что нет трудовых отношений.

Без знания возраста расчёт ОПВР может быть неверным (ОПВР только для рождённых после 1975 года).

## Версии кодекса

Метаданные актуальной и устаревшей версии — в `data/versions.json`.

| Версия | Смысл | Когда использовать |
|--------|-------|-------------------|
| `current` (default) | Действующий НК РК | Всегда, если пользователь не уточняет период |
| `outdated` | Предыдущая редакция | Только если явно спрашивают о прошлом периоде или «старом кодексе» |

Агент **не называет год** в команде — только `--version=current` или `--version=outdated`.
Какой именно кодекс сейчас актуален — читать из `versions.json` и сообщать пользователю (`versionName` в ответе скрипта).

## Определение языка

Язык определяется **автоматически** по содержимому запроса — явно указывать `--lang` не нужно.

| Запрос | Язык поиска | Логика |
|--------|-------------|--------|
| Содержит казахские буквы (ә, ғ, қ, ң, ө, ү, ұ, і, һ) | `--lang=kaz` | Авто-определение |
| Только кириллица без казахских букв | `--lang=ru` | Авто-определение |
| Явно указан `--lang=ru\|kaz` | По флагу | Приоритет над авто |

> Казахские термины: ЖТС (ИПН), КТС (КПН), ҚҚС (НДС), ӘС (СН), АЕК (МРП), ЕАМ (МЗП), МЖЖ (ОПВ), МЖЖЖ (ОПВР), ӘА (СО), МӘМС (ВОСМС/ОСМС)

## Workflow

### 1. Определи версию
- По умолчанию: `--version=current`
- Переключиться на `--version=outdated` только если пользователь явно говорит о прошлом периоде или «старом» кодексе

### 2. Выбери режим поиска (от точного к общему)

```bash
# Знаешь номер статьи → article (самый точный)
node skills/kz-tax-code/scripts/search.js --article=363
node skills/kz-tax-code/scripts/search.js --article=363 --version=outdated

# Keyword — язык определяется автоматически по тексту запроса
node skills/kz-tax-code/scripts/search.js --keyword="дивиденды нерезидент"
node skills/kz-tax-code/scripts/search.js --keyword="ҚҚС мөлшерлемесі"

# Topic — язык тоже авто
node skills/kz-tax-code/scripts/search.js --topic="НДС экспорт освобождение"
node skills/kz-tax-code/scripts/search.js --topic="жалақыдан ЖТС есептеу"

# Поиск по другому закону (АЕК/МРП, МЖЖ/ОПВ, МӘМС/ВОСМС и т.д.)
# --file резолвится от CWD (корня workspace)
node skills/kz-tax-code/scripts/search.js --file=skills/kz-tax-code/data/budget-current-ru.md --keyword="месячный расчётный"
node skills/kz-tax-code/scripts/search.js --file=skills/kz-tax-code/data/budget-current-kaz.md --keyword="АЕК мөлшері"
```

Приоритет: `--article` > `--keyword` > `--topic`

### 3. Прочитай результат и ответь

Из JSON-ответа использовать:
- `versionName` — для указания версии кодекса в ответе
- `results[].article` + `results[].title` — для цитирования статьи
- `results[].text` — полный текст статьи (только в режимах `article` и `title_match`)
- `results[].context` — подсвеченный фрагмент вокруг совпадения (только в `keyword_exact`, `keyword_fallback`, `topic`)
- Правило: если есть `text` — читай его; если только `context` — достаточно контекста

Всегда указывать: какой кодекс (`versionName`), какая статья, какой пункт.
Для расчётов: найти нужные статьи (ставки, вычеты, порядок исчисления) и применить формулу по тексту кодекса — не придумывать из головы.

## Формат ответа

Всегда указывать `versionName` из ответа скрипта — не хардкодить год.

**На русском:**
> Согласно **статье 363 {{versionName}}**, ставка ИПН для резидентов по доходам до 8 500 МРП — **10%**, свыше — **15%** с суммы превышения.
> *(Статья 363, пункт 1)*

**На казахском:**
> **ҚР Салық кодексінің 363-бабына** сәйкес ({{versionName}}) резиденттер үшін 8 500 АЕК-ке дейінгі кірістер бойынша ЖТС мөлшерлемесі — **10%**, одан жоғары — **15%**.
> *(363-бап, 1-тармақ)*

Если в ответе есть `externalHints` — термин не в НК, объяснить пользователю и предложить получить данные через fetch.js.

Если статья не найдена:
> Статья по данному запросу не найдена в {{versionName}}. Попробуйте уточнить номер статьи или ключевые слова.

## Обновление кодекса

Когда выходит новый НК РК:

**Рекомендуемый способ (безопасный):**
1. Открыть adilet.zan.kz в браузере, найти новый кодекс
2. Сохранить страницу как HTML (ru и kaz версии)
3. Запустить:
```bash
node skills/kz-tax-code/scripts/update.js \
  --doc=K2600000XXX --name="НК РК 2027" --effective=2027-01-01 \
  --html-ru=./nk-ru.html --html-kaz=./nk-kaz.html
```

**Автоматическое скачивание** (только в доверенной сети, требует `--insecure`):
```bash
node skills/kz-tax-code/scripts/update.js \
  --doc=K2600000XXX --name="НК РК 2027" --effective=2027-01-01 --insecure
```
> ⚠️ `--insecure` отключает проверку TLS-сертификата (adilet.zan.kz использует НУЦ РК CA, не входящий в trust store Node.js). Не использовать в ненадёжных сетях.

Скрипт:
1. Парсит HTML → Markdown
2. Переместит текущий `current` → `outdated`
3. Сохранит новый как `current`
4. Обновит `data/versions.json`

Номер документа (`--doc`) берётся из URL страницы на adilet.zan.kz.