# AGENTS.md — StrixScripts

Инструкции за AI coding агенти (Claude Code, GitHub Copilot, Cursor и др.),
работещи в този repo. Ако инструментът ти чете `CLAUDE.md` вместо този
файл — `CLAUDE.md` е кратък pointer към този документ; съдържанието не се
дублира умишлено, за да не се разсинхронизира.

## Какво е проектът

Колекция от самостоятелни bash скриптове, организирани по функционални
папки. Всеки скрипт решава една конкретна задача и има собствена `.md`
документация до себе си.

## Задължителна структура при всеки нов скрипт

Когато създаваш нов скрипт, следните стъпки са ЗАДЪЛЖИТЕЛНИ, не опционални
— пропускането на която и да е от тях е непълна задача, не "готово с TODO":

1. **Скриптът и неговият `.md` файл имат еднакво basename**, в една и
   съща папка: `deploy/restart-nginx.sh` → `deploy/restart-nginx.md`.
   Виж `templates/script-template.md` за структурата, която `.md` файлът
   трябва да следва.

2. **Скриптът source-ва `lib/common.sh`** и извиква
   `common::show_help_if_requested "$@"` веднага след дефиниране на
   `SCRIPT_HELP` heredoc-а, преди какъвто и да е друг argument parsing.
   Виж `templates/script-template.sh` за точния pattern и
   `examples/hello-world.sh` за работещ пример.

3. **`--help` (и `-h`) работи и показва пълна информация** — какво прави
   скриптът, какви опции приема, поне един пример за извикване. Това е
   съдържанието на `SCRIPT_HELP`, не отделна имплементация — не пиши
   ръчен `if [[ "$1" == "--help" ]]` в скрипта, common.sh вече го прави.

4. **В `README.md` (корена на проекта) се добавя ред в секцията на
   съответната категория папка** — кратко описание (едно изречение) +
   relative link към `.md` файла на скрипта. Пълното описание живее само
   в скрипт-специфичния `.md`, README не го дублира.

5. **Скриптът минава `shellcheck` без warnings** (виж `.shellcheckrc` в
   корена). Ако warning-ът е false positive, добави `# shellcheck disable=SCxxxx`
   с коментар защо точно на реда, не глобално в файла.

6. **`set -euo pipefail`** в началото на всеки скрипт, веднага след shebang
   реда и коментарния блок. Без изключения — ако скрипт умишлено трябва да
   продължи след грешка в конкретна команда, обгради само тази команда с
   `|| true` или явна проверка, не маха global `set -e`.

## Конвенции за именуване и стил

- **Файлови имена:** kebab-case, описателни глагол+обект (`backup-nextcloud.sh`,
  не `backup.sh` или `script1.sh`).
- **Категория папки:** функционална група (напр. `backup/`, `network/`,
  `deploy/`) — създавай нова папка само когато скриптовете вътре наистина
  споделят функционален домейн, не по проект или по дата.
- **Всички коментари в кода — само на английски**, независимо от езика на
  разговора с агента. `.md` документацията и `README.md` могат да остават
  на български — те са за човека, не за компилатора/shellcheck.
- **Грешки:** винаги през `common::die "message"`, никога суров
  `echo ... >&2; exit 1` — за консистентен формат на грешките между
  скриптове.
- **Статус/progress съобщения:** през `common::log`, който пише на stderr,
  за да остане stdout чист за реален output, който може да бъде pipe-нат
  или captured от друг скрипт/потребител.

## `lib/common.sh` — НЕ дублирай логика от него

Ако скрипт се нуждае от поведение, което `common.sh` не предоставя (напр.
retry logic, temp file cleanup trap, конкретен validation helper) —
разшири `common.sh`, не пиши локална версия вътре в отделния скрипт. Целта
е всеки скрипт да остава кратък и всички споделят едно и също поведение
за грешки/help/logging.

## `examples/` и `templates/` — само референция

`examples/hello-world.sh` е работещ демонстрационен скрипт, показващ
пълната конвенция накратко. `templates/` съдържа празни шаблони за копиране.
Нито едната папка не съдържа реални production скриптове — не ги викай от
други скриптове или automation, и не добавяй реални utility скриптове там.

## Статус

Проектът е в начален етап — само structural скелет (`lib/common.sh`,
`templates/`, `examples/hello-world.sh`) съществува. Реални функционални
категории папки и скриптове предстои да бъдат създадени.