AI_Svetlio

``
███████╗██╗ ██╗███████╗████████╗██╗ ██╗ ██████╗
██╔════╝██║ ██║██╔════╝╚══██╔══╝██║ ██║██╔═══██╗
███████╗██║ ██║█████╗ ██║ ██║ ██║██║ ██║
╚════██║╚██╗ ██╔╝██╔══╝ ██║ ██║ ██║██║ ██║
███████║ ╚████╔╝ ███████╗ ██║ ███████╗██║╚██████╔╝
╚══════╝ ╚═══╝ ╚══════╝ ╚═╝ ╚══════╝╚═╝ ╚═════╝

Universal AI Agent Toolkit & Project Memory v1.4.0
`

AI_Svetlio е система за управление на AI-assisted разработка, която решава ключови проблеми:

- 🧠 Памет между сесии — AI агентът "помни" къде сте спрели
- 🔄 Смяна на IDE — работи еднакво в Cursor, Claude Code, Antigravity
- 👥 Team-ready — колеги могат да се включат без обяснения
- 🛠️ Инструменти — каталог с проверени AI инструменти
- 🔒 Iron Rules — 11 правила за безопасна работа с AI агенти

---

📦 Инсталация

`bash
npm install -g ai-svetlio
`

$3


`bash
npm install -g ai-svetlio@latest # Последна версия (препоръчително)
npm install -g ai-svetlio@1.4.0 # Конкретна версия
`

$3

`bash
npm update -g ai-svetlio
`

---

🚀 Бърз старт

`bash


1. Глобална настройка (веднъж)

svetlio setup

2. В нов проект

mkdir my-project && cd my-project
svetlio init

3. Отвори в любимото IDE и работи!

cursor .

или

antigravity .

или

claude .
`

---

🔒 Iron Rules (Ново в v1.1.0)

11 задължителни правила за AI агентите, които предотвратяват типични грешки:

$3

1. ПАМЕТ ПЪРВО — Агентът винаги започва от .memory/STATE.md
2. НЕ ГАДАЙ — Чете документация, не търси "на посоки"
3. ПРОЧЕТИ ЦЕЛИЯ КОД — Преди редакция, чете целия файл
4. CONTEXT REFRESH — На всеки ~15 съобщения освежава контекста

$3

5. ЗАДЪЛЖИТЕЛЕН BACKUP — Преди редакция на работещ код
6. ЗАЩИТЕНИ ЗОНИ — Не пипа критични папки без одобрение
7. ВЕРИФИЦИРАЙ — Проверява резултата, не приема "на сляпо"

$3

8. ДОКУМЕНТИРАЙ ПЪРВО — Записва решение преди код
9. СТРУКТУРА — Файлове на правилното място
10. ГОЛЕМИ ЗАДАЧИ = МАЛКИ СТЪПКИ — >150 реда → план първо
11. ПИТАЙ ПРИ СЪМНЕНИЕ — По-добре да пита

$3

| Казваш | AI агентът прави |
|--------|------------------|
| refresh | Освежава контекста от .memory/ |
| внимавай | Влиза в REPAIR режим |
| backup първо | Прави backup преди промяна |
| обясни плана | Показва стъпките преди да започне |

---

🎯 Режими на работа

$3

Стандартна работа. AI агентът обновява .memory/ след всяка промяна.

$3

`bash
svetlio repair
`
За поправки на проблеми:
- ✅ Backup преди всяка промяна
- ✅ Одобрение на всяка стъпка
- ✅ Детайлно обяснение какво и защо

$3

`bash
svetlio onboard
`
За съществуващи проекти:
- ✅ Дълбок анализ на кода
- ✅ Извличане на логика
- ✅ Автоматично създаване на .memory/

$3

`bash
svetlio analyze
`
За legacy системи:
- ✅ Пълен анализ на всичко
- ✅ Документиране на бизнес логика
- ✅ Избор между EXTEND и REWRITE

#### 🔼 EXTEND
Добавяне на нови функции без промяна на съществуващия код.

#### 🔄 REWRITE
Пълно пренаписване със съвременни технологии, запазвайки UX.

---

📁 Структура на .memory/

`
project/
└── .memory/
├── STATE.md ← Къде сме сега
├── MODE.md ← Текущ режим
├── LOG.md ← Хронология на работата
├── ARCHITECTURE.md ← Структура на проекта
├── TOOLS.md ← Използвани инструменти
├── TODO.md ← Задачи
├── DECISIONS.md ← Взети решения
├── PROBLEMS.md ← Проблеми и решения
│
├── analysis/ ← От DEEP ANALYSIS
│ ├── FULL_SCAN.md
│ ├── BUSINESS_LOGIC.md
│ ├── TECH_DEBT.md
│ └── RECOMMENDATIONS.md
│
├── rewrite/ ← За REWRITE режим
│ ├── UX_CONTRACT.md
│ ├── USER_FLOWS.md
│ └── MIGRATION_MAP.md
│
└── backups/ ← Backups от REPAIR режим
`

---

📋 Команди

| Команда | Описание |
|---------|----------|
| svetlio setup | Глобална настройка (веднъж) |
| svetlio init | Инициализирай проект |
| svetlio onboard | Вкарай съществуващ проект |
| svetlio repair | Режим ремонт |
| svetlio analyze | Дълбок анализ |
| svetlio status | Покажи състояние |
| svetlio web | Web преглед на .memory/ в браузъра |
| svetlio shortcut | Създай desktop shortcut за Web Viewer |
| svetlio mcp-wizard | Wizard за MCP сървъри |
| svetlio log "съобщение" | Добави ръчен запис |

$3

| Команда | Описание |
|---------|----------|
| svetlio tools | Покажи каталога с инструменти |
| svetlio tools add | Добави инструмент към проекта |
| svetlio tools remove | Премахни инструмент |
| svetlio tools info | Покажи детайли за инструмент |
| svetlio registry | Търси в MCP Registry (16,000+ сървъра) |

Пример:
`bash


Търси MCP сървър за Airtable

svetlio registry airtable

Добави към проекта

svetlio tools add mcp-airtable

Виж как да го инсталираш

svetlio tools info mcp-airtable
`

---

🏭 MCP Server Creators

AI_Svetlio включва wizard за създаване на MCP сървъри:

`bash
svetlio mcp-wizard
`

$3

| Инструмент | Език | За кого |
|------------|------|---------|
| FastMCP ⭐ | Python | Production, custom логика |
| generator-mcp | Node.js | Бърз старт, VS Code |
| openapi-to-mcpserver | Node.js | Съществуващи APIs (⚠️ внимание) |

---

🔄 Workflow примери

$3


`bash
mkdir email-collector && cd email-collector
svetlio init --name "Email Collector"
cursor .

Кажи: "Искам MCP сървър за събиране на имейли"

`

$3

`bash
cd my-old-project
svetlio onboard

AI анализира и създава .memory/

cursor .

Продължи работа нормално

`

$3

`bash
svetlio repair

AI ще пита за одобрение преди всяка промяна

Кажи: "Има бъг в search функцията"

`

$3

`bash
cd old-php-app
svetlio analyze

AI анализира всичко, после питаш:

"Искам да пренапиша с FastAPI и React"

AI прави REWRITE като запазва UX

`

$3

`

След ~15 съобщения, кажи:

"refresh"

AI агентът ще отговори:

⚡ Context Refresh:
- Работим по: [от STATE.md]
- Режим: [от MODE.md]
- Следваща задача: [от TODO.md]
Продължавам ли?
`

$3

При първа сесия (▶ старт) — залепи в чата:
`
Здравей! Започваме работа по проекта.
🚨 ИНИЦИАЛИЗАЦИЯ: Прочети .memory/MODE.md, STATE.md, ARCHITECTURE.md, TOOLS.md
Докладвай какво виждаш и очаквай инструкции.
`

При продължаване (▶ продължаваме) — залепи в чата:
`
Здравей! Продължаваме работа по проекта.
🚨 ИНИЦИАЛИЗАЦИЯ: Прочети .memory/MODE.md, STATE.md, PROBLEMS.md, DECISIONS.md
⚠️ Спазвай Iron Rules. Докладвай състоянието.
`

> 📖 Пълни шаблони: documents/USER_GUIDE.md

---

🤝 Работа с екип

`bash


Колега клонира проекта

git clone ...
cd project

Вижда състоянието

svetlio status

Чете какво е направено

cat .memory/STATE.md
cat .memory/LOG.md

Продължава от там

cursor .
`

---

🔌 IDE поддръжка

| IDE | Rules файл | Статус |
|-----|------------|--------|
| Cursor | .cursorrules | ✅ Пълна |
| Claude Code | CLAUDE.md | ✅ Пълна |
| Antigravity | .antigravity/rules.md | ✅ Пълна |
| Windsurf | .windsurfrules | 🟡 Частична |
| VS Code + Copilot | - | 🟡 Частична |

---

📊 Инструменти в каталога

$3

- FastMCP (Python) ⭐
- generator-mcp (Node.js)
- openapi-to-mcpserver

$3

- mcp-github
- mcp-postgres
- mcp-notion
- mcp-firecrawl

$3

- CrewAI
- LangChain
- AutoGen

$3

- antigravity-awesome-skills
- awesome-cursorrules

$3

- vibe-tools
- ralph-loop

---

🧠 Философия

Базирана на Ralph концепцията:

> "State lives in FILES and GIT, not in LLM's memory"

- .memory/ е единственият източник на истина
- AI агентът чете, не помни
- Git commit = snapshot на паметта
- Всяко IDE чете същата памет

---

⚠️ Споделена отговорност

Паметта на Светльо е споделена отговорност между теб и AI агента.

AI агентът обновява .memory/ в края на всяка сесия, но само ако му дадеш време да завърши. Това не е бъг — това е технологично ограничение на всички AI агенти. Те нямат контрол над момента на затваряне.

Твоята част от сделката:
- ✅ Изчакай агентът да потвърди, че е записал промените
- ✅ Виж "✓ Записано в .memory/" преди да затвориш
- ❌ Не затваряй чата/IDE-то по средата на запис

> 💡 Ако затвориш преди записа — паметта остава неактуална и следващата сесия започва с грешен контекст. Няма как да бъде иначе.

---

📖 Документация

- USER_GUIDE.md — Пълен наръчник за потребителя
- IRON_RULES.md — Детайлни правила за AI агентите

---

📝 Changelog

$3


- 🌐 svetlio web — визуален Web Viewer за .memory/ файловете (read-only, auto-refresh на 5 сек)
- 🖥️ svetlio shortcut — създава desktop shortcut за бързо отваряне на Web Viewer
- 📄 open-memory.bat/.sh — генерира се при svetlio init за двоен клик стартиране
- 🎨 Автоматична тема — следва системната настройка (тъмна/светла)
- 📱 Responsive дизайн — работи на всички размери екрани

$3

- 📖 Context Refresh — намален от ~20 на ~15 съобщения
- 📦 USER_GUIDE.md — подробно инсталиране/деинсталиране, запазване на паметта при ъпдейт
- 🚀 Шаблони — готови "старт"/"продължаваме" за бърз старт на сесия
- 🐛 Fix — ~30 поправени команди от ребрандирането

$3

- 🐛 Фикс — коригиран version display в CLI

$3

- 🔄 Ребрандиране — от svet-ai към ai-svetlio
- ✨ Нова CLI команда — svetlio вместо svet
- 📦 Нов npm пакет — ai-svetlio
- ⚠️ svet-ai deprecated — потребителите се насочват към ai-svetlio

$3

- 📖 Документация за безопасно обновяване — процедура в USER_GUIDE.md
- ❓ Нови FAQ въпроси — "Как да обновя без да загубя работата си?"

$3

- 🔌 MCP Registry интеграция — достъп до 16,000+ MCP сървъра
- ✨ svetlio tools add — добавяне на инструменти към проект
- ✨ svetlio tools remove — премахване на инструменти
- ✨ svetlio tools info — детайли и инсталация
- ✨ svetlio registry — търсене в официалния MCP Registry
- 📦 Нови MCP сървъри — Airtable, Supabase, Slack, Google Drive, Brave Search

$3

- ✨ Iron Rules — 11 задължителни правила за AI агенти
- ✨ Context Refresh — автоматично освежаване на контекста
- ✨ Big Task Protocol — план първо за сложни задачи
- ✨ Backup First — задължителен backup преди редакция

$3

- 🎉 Първа версия
- 📁 .memory/` система
- 🎯 Режими: NORMAL, REPAIR, ONBOARD, ANALYZE

---

📝 License

MIT

---

🙏 Credits

Създаден от общността за общността.

Вдъхновен от:
- Ralph Loop философията
- Antigravity Kit
- Awesome Cursorrules
- MCP екосистемата