power

name	power
version	3.2.1
description	Maintains and validates the P.O.W.E.R. knowledge base (P.A.R.A. + OKF v0.1 + Graph RAG + LLM-Wiki + Execution Rules).

⚡ P.O.W.E.R. Knowledge Management Skill

Цей скілл призначений для автоматизації управління, перевірки та підтримки життєвого циклу бази знань Obsidian Second Brain за гібридною методологією P.O.W.E.R.

🚀 Основні сценарії використання

Скілл автоматично активується ШІ-агентами (Antigravity CLI та OpenCode) або вручну користувачем при виконанні наступних завдань:

1. Ingest (Імпорт знань) — додавання або редагування документів у базі знань.
2. Indexing (Переіндексація) — оновлення змісту та переліку концепцій.
3. Linting (Перевірка здоров'я) — пошук битих посилань, помилок у метаданих чи сторінок-сиріт.
4. ROT Audit — виявлення дублікатів, застарілих та тривіальних нотаток.
5. Auto-Archive — автоматичне архівування застарілих нотаток до 04_Archive/.
6. Relation Suggestions (Graph RAG v2) — аналіз перетину ключових слів, тегів та явних лінків для гібридного (вектор + граф) Graph RAG пошуку.
7. Cron Maintenance — автоматичне виконання lint + index + rot audit.
8. Sync & Commit — фіксація змін у Git згідно з правилами безпеки хоста.
9. Rename & Propagation — перейменування файлу та автоматичне оновлення зв'язків.

---

🛠️ Доступні інструменти (Scripts + CLI)

Скілл містить автоматизовані скрипти у каталозі scripts/ та CLI:

Scripts

1. lint_brain.py — скрипт лінтера + ROT аудиту (v3.2.1):

python3 .agents/skills/power/scripts/lint_brain.py

2. generate_index.py — скрипт автоматичної побудови ієрархічного індексу:

python3 .agents/skills/power/scripts/generate_index.py

CLI (power, 15 команд)

1. power init <path> — створити структуру vault
2. power lint <path> — перевірка метаданих, посилань, orphan
3. power index <path> — генерація ієрархічного індексу
4. power ingest <path> — створення нотатки з OKF метаданими
5. power search <path> <query> — повнотекстовий пошук
6. power sync <path> — побудова FTS і dense-індексу
7. power rot <path> — ROT аудит (дублікати, застарілі, тривіальні)
8. power archive <path> — архівування застарілих нотаток
9. power status <path> — панель стану vault
10. power cron <path> — автоматичне обслуговування
11. power heal <path> — автовиправлення frontmatter
12. power markdown-check <path> — перевірка якості Markdown
13. power suggest-related <path> — пропозиції зв'язків Graph RAG
14. power synthesize <path> — створення підсумкової нотатки сесії
15. power rename <path> --old <old_path> --new <new_path> — перейменування нотатки з оновленням зв'язків Graph RAG

MCP Tools (12) — FastMCP 3.x (v3.2.1)

• lint_vault, generate_index, read_sub_index, ensure_sub_index, ingest_note
• search_vault_tool, synthesize_session
• rot_audit, archive_notes, suggest_related_tool
• heal_frontmatter_tool, check_markdown_tool

Конфігурація (v3.2.1)

• Модель ембеддінгів — канонічно BAAI/bge-m3 (1024 dim) через direct ONNX Runtime. BGE-M3 natively підтримує dense + sparse + ColBERT в одній моделі, що дозволяє гібридний пошук (RRF) без окремого BM25. Провайдер змінюється через POWER_EMBED_PROVIDER; fastembed/MiniLM лишається полегшеним opt-in fallback.
• Реранкер за замовчуванням — onnx-community/bge-reranker-v2-m3-ONNX (SHA-pinned, Apache-2.0, UA+EN). jinaai/jina-reranker-v2-base-multilingual (CC-BY-NC) лишається явним opt-in.
• Контроль ресурсів:
  • POWER_EMBED_BATCH_SIZE (за замовчуванням 8) — лімітує пікове використання RAM при синхронізації/ембеддінгу. При MemoryError розмір батча автоматично зменшується вдвічі.
  • POWER_EMBED_NUM_THREADS (за замовчуванням 2) — обмежує потоки ONNX/OMP/OpenBLAS.
  • POWER_EMBED_COMMIT_EVERY (за замовчуванням 50) — частота збереження векторів у SQLite для зниження навантаження на диск.
  • POWER_SYNC_VMEM_LIMIT_MB (за замовчуванням 0 = вимкнено) — опціональний ліміт віртуальної пам'яті (RLIMIT_AS) процесу синхронізації.
• ROT аудит (A2) — паралельна перевірка посилань через ThreadPoolExecutor(max_workers=16).
• MCP ентрі-поінт — /root/geminicli/.agents/mcp_servers/power_server.py → power_framework.mcp

---

📖 Hierarchical Navigation Protocol (On-Demand Sub-Index Reading)

P.O.W.E.R. використовує ієрархічну індексацію для оптимізації контексту AI-агентів:

vault/
├── index.md              # Navigation map (small, ~2KB)
├── 01_Projects/
│   └── _index.md         # Detailed entries for Projects
├── 02_Areas/
│   └── _index.md         # Detailed entries for Areas
├── 03_Resources/
│   └── _index.md         # Detailed entries for Resources
└── 06_Daily_Logs/
    └── _index.md         # Detailed entries for Daily Logs

Step-by-Step Agent Navigation Rules:

1. Direct Reading / Search First: If the path is known or a specific file is needed, read it directly or search using grep_search.
2. Use Indices Only if Unknown: Read index.md or call read_sub_index (read folder/_index.md) only if the path is unknown and grep_search yields no results.
3. NEVER glob all .md files / list large folders: Use grep_search instead of list_dir for large categories to preserve tokens.

Token Efficiency Comparison:

Approach	Token Cost	Context Quality
Read all .md files	🔴 ~50K+	Full but wasteful
Read only index.md	🟢 ~2K	Insufficient
index.md + relevant _index.md	🟡 ~5-8K	Optimal balance
+ specific notes	🟡 ~10-15K	Precise, targeted

---

📋 Інструкції для ШІ-агента (Step-by-Step Rules)

Коли ви працюєте з базою знань у просторі ваулта (Workspace/Vault Root), ЗАВЖДИ дотримуйтеся наступного ланцюжка дій (PAV + P.O.W.E.R.):

Крок 1. Перевірка метаданих (OKF Frontmatter)

При створенні або редагуванні файлів упевнитись, що файл починається з правильної плашки (OKF v0.1 — type є єдиним обов'язковим полем):

---
type: Project | Area | Resource | Daily Log | Archive | System Guide
title: "Назва сторінки"
description: "Опис в один рядок для каталогу"
tags: [тег1, тег2]
timestamp: YYYY-MM-DDTHH:MM:SS+TZ
---

Крок 2. Автоматична генерація ієрархічного каталогу (Index)

Після додавання/зміни файлу виконайте скрипт генерації індексу. Він автоматично оновить index.md та всі _index.md файли:

python3 .agents/skills/power/scripts/generate_index.py

Крок 3. Додавання запису у Change Log

Запишіть виконану дію в кінець файлу log.md у хронологічному форматі:

## [YYYY-MM-DD] <operation_type> | <action_title>

- **Action:** Стислий опис того, що зроблено
- **Result:** Які файли змінено/створено

Крок 4. Валідація лінтером (Lint check)

Запустіть скрипт лінтера, щоб перевірити, чи не з'явилися нові биті посилання чи сторінки-сироти:

python3 .agents/skills/power/scripts/lint_brain.py

Якщо лінтер звітує про помилки (наприклад, broken links у Home.md), негайно виправте їх.

Крок 5. Git Commit & Push (Execution Rules)

• Коміти виконуються лише в окремі гілки feature/* or fix/*.
• Git налаштовується на GPG-підпис комітів за допомогою ключів розробника з .env файлу.
• Після пушу відкривається Pull Request та здійснюється злиття.
• Обов'язково запускається скілл cleanup-branches для прибирання злитих гілок.