slaid098/opencode-config
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

docs(readme): bilingual cleanup with minimalism and fix stale command (#89)

Browse source 
* docs(readme): rewrite with bilingual structure and minimalism

* docs(handoff): add handoff + ADR for README cleanup

* docs(handoff): set PR number

---------

Co-authored-by: opencode-agent <agent@opencode.local>
This commit is contained in:
Sergey 2026-07-26 23:05:29 +03:00 • committed by GitHub
parent 4cb50a4824
commit eb5697e28f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 239 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

289
README.md
View file

@ -1,162 +1,233 @@
# opencode-config
Docker-based AI coding assistant with persistent memory — opencode configuration.
Personal opencode setup — Docker-based AI coding assistant with persistent memory plugin and pipeline automation.
## Quick start
## Russian
### Docker
### Quick start
```bash
git clone https://github.com/slaid098/opencode-config.git
cd opencode-config
cp .env.example .env # fill in your keys
cp .env.example .env # заполнить ключи (см. Configuration)
docker compose up -d
```
Access at http://localhost:4096.
Доступ: http://localhost:4096. Память инициализируется автоматически при первом старте контейнера.
### Bare (without Docker)
### Structure
```bash
git clone https://github.com/slaid098/opencode-config.git
cd opencode-config
opencode # .opencode/ auto-discovered
```
| Путь | Описание |
|------|----------|
| `AGENTS.md` | Глобальные правила оркестратора (главный агент = только план) |
| `.opencode/` | Конфигурация проекта (auto-discovered, без env var) |
| `.opencode/agents/` | Subagent definitions (docs-reviewer, memory-syncer, reviewer) |
| `.opencode/skills/` | Skill definitions (14 skills) |
| `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) |
| `src/` | Python RAG CLI (memory) |
| `docs/` | Handoffs, ADRs, project map |
## Structure
### Configuration
- `AGENTS.md` — global orchestrator rules (main agent = plan only, all via subagents)
- `.opencode/` — project-local config (auto-discovered, zero env var)
- `agents/` — subagent definitions (docs-reviewer, memory-syncer, reviewer)
- `commands/` — slash commands (run-pipeline, spec, configure-opencode)
- `skills/` — skill definitions (14 skills)
- `tools/` — custom tools (commit, create-issue, create-pr, memory-setup, merge-pr, pipeline-status, post-docs-review, post-review, spec-status, tunnel)
- `scripts/` — Python scripts (pipeline-status, spec-status, check-adr-refs, etc.)
- `opencode.json` — main config (providers, MCP servers, permissions)
- `app_data/workspaces/` — agent working directory
- `app_data/ssh/` — SSH keys (not in git)
- `src/` — Python RAG CLI (memory)
- `docs/` — handoffs, decisions (ADRs), project map
- `.github/workflows/` — CI workflows (ubuntu-latest)
Скопируйте `.env.example` → `.env` и заполните. Не-memory переменные:
## Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `AI_PROVIDER_BASE_URL` | — (required) | URL API AI-провайдера |
| `AI_PROVIDER_API_KEY` | — (required) | Ключ API AI-провайдера |
| `OPENCODE_SERVER_PASSWORD` | — (required) | Пароль сервера opencode |
| `GITHUB_TOKEN` | — (required) | GitHub personal access token |
| `CONTEXT7_API_KEY` | — (optional) | Context7 MCP API key |
| `ANTIDETECT_BROWSER_MCP_URL` | `http://localhost:8765/mcp` | Antidetect browser MCP URL (optional) |
Copy `.env.example` to `.env` and fill in:
Memory-переменные — в секции [Memory setup → Environment variables](#environment-variables-1).
| Variable | Description |
|----------|-------------|
| `AI_PROVIDER_BASE_URL` | AI provider API URL |
| `AI_PROVIDER_API_KEY` | AI provider API key |
| `OPENAI_BASE_URL` | Embeddings API URL (OpenRouter default) |
| `OPENAI_API_KEY` | Embeddings API key (OpenRouter) |
| `OPENAI_EMBEDDING_MODEL` | Embedding model (default: `qwen/qwen3-embedding-8b`) |
| `OPENAI_EMBEDDING_BATCH_SIZE` | Embedding batch size (default: 50) |
| `OPENCODE_SERVER_PASSWORD` | opencode server password |
| `GITHUB_TOKEN` | GitHub personal access token |
| `CONTEXT7_API_KEY` | Context7 MCP API key |
| `OPENCODE_MEMORY_REMOTE` | Git remote for your opencode-memory fork (required) |
| `MEMORY_CHUNK_SIZE` | Memory index chunk size (default: 512) |
| `MEMORY_CHUNK_OVERLAP` | Memory index chunk overlap (default: 64) |
| `ANTIDETECT_BROWSER_MCP_URL` | Antidetect browser MCP URL (optional) |
### Memory setup
## Memory setup
Плагин `@mathew-cf/opencode-memory` — гибридный поиск: ripgrep (keyword) + cloud embeddings (OpenRouter Qwen3 8B, 4096 dim, $0.01/M tokens).
Memory uses `@mathew-cf/opencode-memory` plugin — hybrid search: ripgrep (keyword) + cloud embeddings (OpenRouter Qwen3 8B, 4096 dim, $0.01/M tokens).
### How it works
#### How it works
```
opencode (plugin) → rag.js wrapper → python3 -m src.memory → OpenRouter API
↘ ripgrep (keyword search, parallel)
```
- `memory_search` runs both paths in parallel, merges results by score
- `memory_save` commits to memory repo, post-commit hook auto-pushes, then incremental reindex (only changed file, ~1 sec)
- First full reindex: ~4 min for 78 files / 2379 chunks via OpenRouter
- Index format: `.rag/index.json` (embeddings) + `.rag/meta.json` (SHA256 + version) + `.rag/.lock` (flock)
`memory_search` параллельно: ripgrep + embeddings, merge по score. `memory_save` коммитит + auto-push + incremental reindex (~1 sec). Первый full reindex: ~4 min для 78 файлов.
### Prerequisites
#### Prerequisites
1. **Fork the memory repo**: fork [`slaid098/opencode-memory`](https://github.com/slaid098/opencode-memory) to your GitHub account
2. **Get OpenRouter API key**: sign up at [openrouter.ai](https://openrouter.ai), create API key (Qwen3 8B = $0.01/M tokens; $9 balance ≈ 700K incremental saves)
3. **Fill `.env`** (see [Configuration](#configuration) table above):
```
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_API_KEY=sk-or-v1-...
OPENAI_EMBEDDING_MODEL=qwen/qwen3-embedding-8b
OPENAI_EMBEDDING_BATCH_SIZE=50
OPENCODE_MEMORY_REMOTE=https://github.com/<your-username>/opencode-memory.git
OPENCODE_MEMORY_DIR=/root/.local/share/opencode/opencode-memory
GITHUB_TOKEN=ghp_...
```
1. Fork [`slaid098/opencode-memory`](https://github.com/slaid098/opencode-memory) → ваш GitHub
2. OpenRouter API key ([openrouter.ai](https://openrouter.ai), Qwen3 8B = $0.01/M tokens)
3. Заполнить `.env` (см. Configuration + Environment variables ниже)
### Initialize
#### Initialize
#### In Docker (recommended)
Docker (рекомендуется): `docker compose up -d` — авто-инициализация через `memory-setup` tool.
Повтор вручную:
```bash
git clone https://github.com/slaid098/opencode-config.git
cd opencode-config
cp .env.example .env # fill in keys (see Prerequisites)
docker compose up -d
docker exec opencode /root/.config/opencode/scripts/setup-memory.sh
```
Memory initializes automatically on first container start (via `memory-setup` tool). To re-run manually:
Bare metal: `uv sync && .opencode/scripts/setup-memory.sh`.
```bash
docker exec opencode bash -c "cd /root/workspace/opencode-config && .opencode/scripts/setup-memory.sh"
```
#### setup-memory.sh steps
#### Bare metal
```bash
git clone https://github.com/slaid098/opencode-config.git
cd opencode-config
uv sync # install Python deps
cp .env.example .env # fill in keys
.opencode/scripts/setup-memory.sh
```
### setup-memory.sh steps
The script is idempotent — safe to re-run:
Скрипт идемпотентный (безопасно перезапускать):
1. Create `OPENCODE_MEMORY_DIR` if missing
2. Clone memory repo (or `pull --ff-only` if exists)
3. Verify remote origin matches `OPENCODE_MEMORY_REMOTE`
4. Install post-commit hook (auto-push on `memory_save`)
5. Build RAG index if `.rag/index.json` missing (full reindex via OpenRouter, ~4 min)
6. Generate JS wrapper at `node_modules/@mathew-cf/rag-cli/bin/rag.js` (delegates to Python CLI; original backed up to `.orig`)
5. Build RAG index if `.rag/index.json` missing (full reindex, ~4 min)
6. Generate JS wrapper at `rag.js` (delegates to Python CLI; original backed up to `.orig`)
### Verify it works
#### Verify
```bash
# Wrapper should be Python shim (~10 lines), not Rust binary (71 lines)
cat node_modules/@mathew-cf/rag-cli/bin/rag.js
cat node_modules/@mathew-cf/rag-cli/bin/rag.js # Python shim ~10 lines, not Rust binary (71)
cat $OPENCODE_MEMORY_DIR/.rag/meta.json | python3 -m json.tool | head -5 # version + sha256
ls -la $OPENCODE_MEMORY_DIR/.rag/ # index.json + meta.json + .lock (no index.bin)
```
# Meta should show our format (version + sha256), not Rust (model_id + hidden_size)
cat $OPENCODE_MEMORY_DIR/.rag/meta.json | python3 -m json.tool | head -5
# .rag/ should contain index.json + meta.json + .lock (no index.bin)
ls -la $OPENCODE_MEMORY_DIR/.rag/
# Search end-to-end (through wrapper, as plugin does)
```bash
node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind mount" \
-i $OPENCODE_MEMORY_DIR/.rag -k 3 --json
```
### Troubleshooting
#### Troubleshooting
| Симптом | Причина | Fix |
|---------|---------|-----|
| `Semantic search is unavailable` | Wrapper не сгенерирован / rag-cli не установлен | Re-run `setup-memory.sh` |
| Результаты без scores | Rust rag-cli (old wrapper) | Проверить `rag.js` = Python shim; re-run `setup-memory.sh` |
| `Index version mismatch` при каждом запуске | meta.json missing/stale | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run |
| `OPENAI_BASE_URL env var not set` | `.env` не загружен | Docker: `docker compose up -d --force-recreate`; bare: `.env` в CWD |
| 429 rate limit от OpenRouter | Batch too large / too fast | Уменьшить `OPENAI_EMBEDDING_BATCH_SIZE` (default 50, max 100) |
| Stale Rust artifacts (`index.bin`) | Миграция со старого rag-cli | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run `setup-memory.sh` |
#### Environment variables
| Variable | Default | Description |
|----------|---------|-------------|
| `OPENCODE_MEMORY_DIR` | `/root/.local/share/opencode/opencode-memory` | Расположение memory repo |
| `OPENCODE_MEMORY_REMOTE` | — (required) | Git remote для вашего fork opencode-memory |
| `OPENAI_BASE_URL` | — (required) | URL embeddings API (OpenRouter: `https://openrouter.ai/api/v1`) |
| `OPENAI_API_KEY` | — (required) | OpenRouter API key |
| `OPENAI_EMBEDDING_MODEL` | `qwen/qwen3-embedding-8b` | Embedding model (4096 dim) |
| `OPENAI_EMBEDDING_BATCH_SIZE` | `50` | Chunks per API call (OpenRouter max 100) |
| `MEMORY_CHUNK_SIZE` | `512` | Размер chunk в символах |
| `MEMORY_CHUNK_OVERLAP` | `64` | Overlap между chunks |
| `MEMORY_WRAPPER_PATH` | (auto) | Override rag.js wrapper path (for tests) |
| `MEMORY_WRAPPER_PYTHON` | (auto) | Override Python binary для wrapper (for tests) |
## English
### Quick start
```bash
git clone https://github.com/slaid098/opencode-config.git
cd opencode-config
cp .env.example .env # fill in keys (see Configuration)
docker compose up -d
```
Access at http://localhost:4096. Memory initializes automatically on first container start.
### Structure
| Path | Description |
|------|-------------|
| `AGENTS.md` | Global orchestrator rules (main agent = plan only) |
| `.opencode/` | Project-local config (auto-discovered, zero env var) |
| `.opencode/agents/` | Subagent definitions (docs-reviewer, memory-syncer, reviewer) |
| `.opencode/skills/` | Skill definitions (14 skills) |
| `.opencode/scripts/` | Python scripts (pipeline-status, spec-status) |
| `src/` | Python RAG CLI (memory) |
| `docs/` | Handoffs, ADRs, project map |
### Configuration
Copy `.env.example` → `.env` and fill in. Non-memory variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `AI_PROVIDER_BASE_URL` | — (required) | AI provider API URL |
| `AI_PROVIDER_API_KEY` | — (required) | AI provider API key |
| `OPENCODE_SERVER_PASSWORD` | — (required) | opencode server password |
| `GITHUB_TOKEN` | — (required) | GitHub personal access token |
| `CONTEXT7_API_KEY` | — (optional) | Context7 MCP API key |
| `ANTIDETECT_BROWSER_MCP_URL` | `http://localhost:8765/mcp` | Antidetect browser MCP URL (optional) |
Memory variables — see [Memory setup → Environment variables](#environment-variables-1) section.
### Memory setup
Plugin `@mathew-cf/opencode-memory` — hybrid search: ripgrep (keyword) + cloud embeddings (OpenRouter Qwen3 8B, 4096 dim, $0.01/M tokens).
#### How it works
```
opencode (plugin) → rag.js wrapper → python3 -m src.memory → OpenRouter API
↘ ripgrep (keyword search, parallel)
```
`memory_search` runs both paths in parallel, merges by score. `memory_save` commits + auto-pushes + incremental reindex (~1 sec). First full reindex: ~4 min for 78 files.
#### Prerequisites
1. Fork [`slaid098/opencode-memory`](https://github.com/slaid098/opencode-memory) to your GitHub
2. OpenRouter API key ([openrouter.ai](https://openrouter.ai), Qwen3 8B = $0.01/M tokens)
3. Fill `.env` (see Configuration + Environment variables below)
#### Initialize
Docker (recommended): `docker compose up -d` — auto-init via `memory-setup` tool.
Re-run manually:
```bash
docker exec opencode /root/.config/opencode/scripts/setup-memory.sh
```
Bare metal: `uv sync && .opencode/scripts/setup-memory.sh`.
#### setup-memory.sh steps
Script is idempotent — safe to re-run:
1. Create `OPENCODE_MEMORY_DIR` if missing
2. Clone memory repo (or `pull --ff-only` if exists)
3. Verify remote origin matches `OPENCODE_MEMORY_REMOTE`
4. Install post-commit hook (auto-push on `memory_save`)
5. Build RAG index if `.rag/index.json` missing (full reindex, ~4 min)
6. Generate JS wrapper at `rag.js` (delegates to Python CLI; original backed up to `.orig`)
#### Verify
```bash
cat node_modules/@mathew-cf/rag-cli/bin/rag.js # Python shim ~10 lines, not Rust binary (71)
cat $OPENCODE_MEMORY_DIR/.rag/meta.json | python3 -m json.tool | head -5 # version + sha256
ls -la $OPENCODE_MEMORY_DIR/.rag/ # index.json + meta.json + .lock (no index.bin)
```
```bash
node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind mount" \
-i $OPENCODE_MEMORY_DIR/.rag -k 3 --json
```
#### Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| `Semantic search is unavailable` in opencode | Wrapper not generated or rag-cli not installed | Re-run `setup-memory.sh` |
| Search returns results but no scores | Using Rust rag-cli (old wrapper) | Check `rag.js` is Python shim (10 lines); re-run `setup-memory.sh` |
| `Index version mismatch, full reindex` on every run | meta.json missing or stale | Delete `.rag/` and re-run `setup-memory.sh` |
| `OPENAI_BASE_URL env var not set` | .env not loaded | For Docker: `docker compose up -d --force-recreate`; for bare: ensure `.env` in CWD |
| 429 rate limit from OpenRouter | Batch too large or too fast | Reduce `OPENAI_EMBEDDING_BATCH_SIZE` (default 50, max 100 for OpenRouter) |
| Stale Rust artifacts (`index.bin` in `.rag/`) | Migrating from old rag-cli | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` then re-run `setup-memory.sh` |
| `Semantic search is unavailable` | Wrapper not generated / rag-cli not installed | Re-run `setup-memory.sh` |
| Results without scores | Rust rag-cli (old wrapper) | Check `rag.js` is Python shim; re-run `setup-memory.sh` |
| `Index version mismatch` on every run | meta.json missing/stale | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run |
| `OPENAI_BASE_URL env var not set` | `.env` not loaded | Docker: `docker compose up -d --force-recreate`; bare: `.env` in CWD |
| 429 rate limit from OpenRouter | Batch too large / too fast | Reduce `OPENAI_EMBEDDING_BATCH_SIZE` (default 50, max 100) |
| Stale Rust artifacts (`index.bin`) | Migrating from old rag-cli | `rm -rf $OPENCODE_MEMORY_DIR/.rag/` + re-run `setup-memory.sh` |
### Environment variables
#### Environment variables
| Variable | Default | Description |
|----------|---------|-------------|
@ -168,9 +239,9 @@ node node_modules/@mathew-cf/rag-cli/bin/rag.js search "docker compose bind moun
| `OPENAI_EMBEDDING_BATCH_SIZE` | `50` | Chunks per API call (OpenRouter max 100) |
| `MEMORY_CHUNK_SIZE` | `512` | Chunk size in characters |
| `MEMORY_CHUNK_OVERLAP` | `64` | Overlap between chunks |
| `MEMORY_WRAPPER_PATH` | (auto-detected) | Override rag.js wrapper path (for tests) |
| `MEMORY_WRAPPER_PYTHON` | (auto-detected) | Override Python binary for wrapper (for tests) |
| `MEMORY_WRAPPER_PATH` | (auto) | Override rag.js wrapper path (for tests) |
| `MEMORY_WRAPPER_PYTHON` | (auto) | Override Python binary for wrapper (for tests) |
## License
MIT — see [LICENSE](LICENSE)
MIT — see [LICENSE](LICENSE).

31
docs/decisions/039-pr-89-readme-bilingual-cleanup.md Normal file
View file

@ -0,0 +1,31 @@
# ADR-039: README bilingual cleanup with minimalism
## Статус
Accepted (2026-07-26)
## Контекст
README.md (PR #86, ADR-038) был English-only, 176 строк, с дублированием: env vars в 2 таблицах (Configuration + Environment variables), `cp .env.example .env` 4 раза, `git clone ... cd opencode-config` 3 раза. Команда `docker exec` в Initialize секции указывала на несуществующий путь — compose working_dir = `/root/workspace` (без opencode-config subdir), а `.opencode/scripts/setup-memory.sh` доступен в контейнере через bind-mount `./.opencode:/root/.config/opencode` по пути `/root/.config/opencode/scripts/setup-memory.sh`.
Issue #88 требует bilingual структуру (Russian primary + English 1:1) с минимализмом: таблицы вместо prose, 1-2 строки на концепт. Preserve 7 Memory setup подсекций, сжатых до 2-4 строк.
## Решение
Переписать README.md в новой структуре:
1. `## Russian` секция (Quick start, Structure, Configuration, Memory setup × 7 подсекций)
2. `## English` секция — точный 1:1 перевод Russian (те же заголовки, тот же контент, тот же порядок)
3. `## License` (1 строка)
Устранить дублирование: 1 env table на группу (non-memory в Configuration, 10 memory vars в Environment variables), `cp .env.example .env` 1 раз на язык, `git clone ... cd` 1 раз на язык.
Fix C1: docker exec команда → `/root/.config/opencode/scripts/setup-memory.sh` (реальный путь в контейнере через bind-mount).
Configuration table разделена на 2 группы: non-memory (6 vars) в Configuration секции, memory (10 vars) в Environment variables подсекции Memory setup — для контекстной группировки (как в PR #86).
## Альтернативы
- **English primary + Russian secondary** — отклонено: основная аудитория русскоязычная (AGENTS.md требует "Always respond to the user in Russian")
- **Отдельный README.ru.md + README.md (EN)** — отклонено: дробит документацию, пользователи могут смотреть только один файл
- **Только Russian (drop English)** — отклонено: репо публичный, international контрибьюторы не смогут прочитать
- **Interleaved (RU paragraph → EN paragraph)** — отклонено: сложно читать, нарушает сканируемость таблиц

28
docs/handoff/pr-89-readme-bilingual-cleanup.md Normal file
View file

@ -0,0 +1,28 @@
---
pr: 89
title: docs(readme): bilingual cleanup with minimalism and fix stale command
---
## Что сделано
Переписал README.md в минималистичном bilingual стиле: Russian primary + English 1:1 полный перевод.
- Структура: `## Russian` + `## English` секции, каждая с Quick start / Structure / Configuration / Memory setup (7 подсекций) / License
- Минимализм: таблицы вместо prose, 1-2 строки на концепт, code blocks ≤ 3 строк (verify команды разбиты на 2 блока для читаемости)
- **Fix C1**: docker exec команда исправлена на реальный путь в контейнере `/root/.config/opencode/scripts/setup-memory.sh` (bind-mount `./.opencode:/root/.config/opencode`), вместо старого `/root/workspace/opencode-config && .opencode/scripts/setup-memory.sh`
- Убрано дублирование: env table 1 на группу (не 2), `cp .env.example .env` 1 раз на язык, `git clone ... cd opencode-config` 1 раз на язык
- Memory setup 7 подсекций preserved и сжаты: How it works, Prerequisites, Initialize, setup-memory.sh steps, Verify, Troubleshooting (6 строк), Environment variables (10 vars)
- Объём: 246 строк (RU + EN + License), English = точный 1:1 перевод Russian
## Почему
Старый README (176 строк, English-only) содержал дублирование: env vars в 2 таблицах, `cp .env.example .env` 4 раза, `git clone ... cd` 3 раза. Команда `docker exec` в Initialize секции указывала на несуществующий путь (`/root/workspace/opencode-config` — compose working_dir `/root/workspace` без opencode-config subdir). Bilingual структура улучшает доступность для русскоязычных пользователей (основная аудитория) и сохраняет English для международной аудитории.
## Pending
— после merge: удалить старый handoff `docs/handoff/pr-86-readme-memory-setup-instructions.md` (заменён этим PR) — если принято отдельным PR
## Watch out
- Объём 246 строк вместо заявленных ~160: 7 Memory setup подсекций × 2 языка + troubleshooting 6 строк + 10 env vars требуют места; приоритет — содержательные требования issue (#88) над оценкой
- Anchor `[Memory setup → Environment variables](#environment-variables-1)` — GitHub добавляет `-1` суффикс для второго вхождения заголовка (RU → EN). Проверить работает ли ссылка после merge
- Verify команды разбиты на 2 code blocks (cat/ls + node search) — issue требовало "code blocks ≤ 3 строк", но это не строгое нарушение (логическая группировка)