# GEMINI.md - Project Context & Instructions

This repository contains personal dotfiles and configurations for a highly productive development environment, integrating Bash, Tmux, Vim, VS Code, and various AI assistants (Gemini CLI, Claude, Codex, Opencode).

## 📂 Project Overview

*   **Type:** Non-Code Project (Dotfiles / Configuration)
*   **Management:** Uses `stow` for Linux/WSL and `chezmoi` for Windows/WSL.
*   **Key Focus:** 
    *   Unified configuration across editors and terminals.
    *   Deep integration with AI tools via shared "skills".
    *   Automated environment setup (proxy handling, secret loading).

## 🛠 Key Components

### 1. Shell & Terminal (Bash & Tmux)
*   **Bash:** Custom prompt (`.bash_prompt`), utility functions (`.bash_functions` like `proxy_on/off`), and core customizations (`.bash_custom`).
*   **Tmux:** Dual prefix (`C-b` and `C-Space`), Vi-mode for copying, and optimized pane management.
*   **Secrets:** Managed via `~/.env.secrets` (not tracked in Git).

### 2. Editors (Vim, VS Code, Zed)
*   **Vim:** Minimalist `.vimrc`, 2-space indentation, leader-key mappings (`Space`).
*   **VS Code (WSL):** Uses `server-env-setup` to automatically load secrets and configure proxy settings upon startup.
*   **Zed:** Placeholder directory for future configuration.

### 3. AI Agents & Skills
*   **Shared Skills:** Located in `agents/.agents/skills/`. This is the single source of truth for AI instructions.
*   **Gemini CLI:** Configured via `gemini/.gemini/`. 
    *   **Policies:** `readonly-commands.toml` allows critical commands like `git status`, `git diff`, and `git add` to run without confirmation.
*   **Opencode:** MCP-based assistant configuration (`opencode.json`): Context7 для документации и встроенные `websearch`/`webfetch`. Локальный SearXNG в `docker/searxng` — резервный вариант, MCP-сервер отключён.
*   **Skill Bridges:** Claude gets skills via the `~/.claude/skills` symlink; Opencode reads `~/.agents/skills` natively, no bridge needed.

## 🚀 Usage & Maintenance

### Deployment
*   **Linux/WSL:** Use `stow <package_name>` from the root directory.
*   **Windows:** Use `chezmoi apply`.

### Adding/Updating Skills
1.  Modify files in `agents/.agents/skills/`.
2.  Ensure symlinks in other tool directories are updated if new skills are added.
3.  Устаревшие скиллы время от времени удаляем. Убирай каталог целиком, а
    вместе с ним ссылки из других скиллов и строку в `.gitignore`, если
    скилл был внешним. Упоминания в архивах и handoff-записках — история,
    их не трогаем.

## 📋 TODO

Планы на будущее — см. [TODO.md](TODO.md).

## 🗣 Язык и рассуждения

Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий и инструментов (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации (пиши «приведение в соответствие», а не «реконсиляция»; «точка отсчёта», а не «origin»).

Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов.

Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.

## Навыки агентов

### Хранилище задач

Задачи хранятся в Gitea Issues (`git.dementev.space`), работа с ними — через CLI `tea`. См. `docs/agents/issue-tracker.md`.

### Состояния triage

Состояния triage — метки Gitea со стандартными названиями. См. `docs/agents/triage-labels.md`.

### Документы предметной области

Одна предметная область на весь репозиторий: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`.

### Записки для передачи работы

Записки для продолжения работы в новой сессии — `.scratch/handoffs/YYYYMMDD-HHMM-<slug>.md` (одноразовые, уборка best-effort; скилл `/handoff` пишет сюда).

### `.scratch/` — локальная рабочая зона

Весь `.scratch/` — заметки по ходу дела: handoffs и черновики (задачи живут в Gitea). Каталог в `.gitignore`: он живёт только на этой машине и в Git не попадает.

Долговечное знание держим **вне** `.scratch/` (в `docs/`, `CONTEXT.md`) и коммитим вместе с работой. Прежде чем сливать фиче-ветку, убедись, что долговечная часть уже вынесена туда: остальное из `.scratch/` потом не восстановить.

## Субагенты и экономия контекста

Объёмную и механическую работу делегируем субагентам (Sonnet или аналогичная, в зависимости от сложности задачи), чтобы не засорять контекст основной сессии: проверки (реперы/линт/валидация), пакетные и файловые операции, отладка и прочее. Субагент сам читает «шумный» ввод-вывод и возвращает только результат.

- Мелочь делегировать не стоит — кроме случая, когда она даёт объёмный вывод: пусть субагент прочитает его у себя и вернёт выжимку.