Add initial scripts and project conventions

AGENTS.md

@@ -0,0 +1,85 @@
+# 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`) съществува. Реални функционални
+категории папки и скриптове предстои да бъдат създадени.