docs: refresh agent guidance and opencode plan

AGENTS.md

@@ -5,6 +5,7 @@ This file is a navigation layer for architecture and implementation guidance.
 Start here:
 - Repo overview and commands: [README.md](README.md)
 - Working instructions and project conventions: [CLAUDE.md](CLAUDE.md)
+- Hard guardrails: [AGENT_CRITICAL_GUARDRAILS.md](AGENT_CRITICAL_GUARDRAILS.md)
 - Canonical feature architecture standard: [docs/FEATURE_ARCHITECTURE_STANDARD.md](docs/FEATURE_ARCHITECTURE_STANDARD.md)
 - Agent team launch/runtime debugging runbook: [docs/team-management/debugging-agent-teams.md](docs/team-management/debugging-agent-teams.md)
 

AGENT_CRITICAL_GUARDRAILS.md

@@ -4,6 +4,7 @@ These are the hard rules to keep agent work predictable and safe in this repo.
 
 - Read `CLAUDE.md` first, then follow `docs/FEATURE_ARCHITECTURE_STANDARD.md` for new medium and large features.
 - Use `pnpm` for project commands. Do not switch to `npm` or `yarn`.
+- Use the desktop Electron app (`pnpm dev`) for normal local development and smoke checks unless browser-mode internals are explicitly requested.
 - Do not run `pnpm lint:fix` unless the user explicitly asks for broad formatting changes.
 - Keep main, preload, renderer, and shared responsibilities separate.
 - Use `wrapAgentBlock(text)` instead of manually concatenating agent block markers.

CLAUDE.md

@@ -18,7 +18,7 @@ Key capabilities:
 - **Notification system** — alerts on task completion, agent attention needed, errors
 - **Zero-setup onboarding** — built-in Claude Code installation and authentication
 
-100% free, open source. No API keys. No configuration. Runs entirely locally.
+100% free, open source, and local-first. The app uses available Claude/Codex/OpenCode provider access instead of forcing a single app-level API-key setup.
 
 ## Tech Stack
 Electron 40.x, React 19.x, TypeScript 5.x, Tailwind CSS 3.x, Zustand 4.x
@@ -31,7 +31,7 @@ When running build/typecheck/test commands, pipe through `tail -20` to avoid flo
 - Hard guardrails: [`AGENT_CRITICAL_GUARDRAILS.md`](AGENT_CRITICAL_GUARDRAILS.md)
 
 - `pnpm install` - Install dependencies
-- `pnpm dev` - Dev server with hot reload
+- `pnpm dev` - Desktop Electron app with hot reload
 - `pnpm build` - Production build
 - `pnpm typecheck` - Type checking
 - `pnpm lint:fix` - Lint and auto-fix
@@ -108,8 +108,8 @@ Task tool_use blocks are filtered when subagent exists
 Keep orphaned Task calls (no matching subagent) for visibility.
 
 ### Agent Teams
-Claude Code's "Orchestrate Teams" feature: multiple sessions coordinate as a team.
+Agent Teams is this app's orchestration layer across Claude, Codex, and OpenCode runtimes.
-Official docs: https://code.claude.com/docs/en/agent-teams
+For Claude runtime behavior, also track Anthropic's upstream agent-team docs: https://code.claude.com/docs/en/agent-teams
 
 #### Debugging Team Launches And Teammates
 - Use [`docs/team-management/debugging-agent-teams.md`](docs/team-management/debugging-agent-teams.md) when a team launch hangs, a teammate remains `registered`, OpenCode shows `bootstrap unconfirmed`, messages are missing, or Task Log Stream looks wrong.
@@ -119,12 +119,13 @@ Official docs: https://code.claude.com/docs/en/agent-teams
 
 #### Message Delivery Architecture
 - **Lead** reads ONLY stdin (stream-json). Messages to lead must go through `relayLeadInboxMessages()` which converts inbox entries to stdin.
-- **Teammates** are independent CLI processes. Claude Code runtime monitors each teammate's inbox file and delivers messages between turns. No relay through lead needed.
+- **Native teammates** are independent CLI/process teammates. Claude/Codex-style teammates read their own inbox files between turns; no relay through the lead is needed.
-- **User → Teammate DM**: UI writes to `inboxes/{member}.json` with `from: "user"`. Teammate reads it directly.
+- **OpenCode secondary lanes** do not watch teammate inbox files. User DMs are persisted to `inboxes/{member}.json`, then delivered through the OpenCode runtime bridge with explicit delivery proof.
-- **Teammate → User response**: Teammate writes to `inboxes/user.json`. UI reads all inbox files including `user.json` via `TeamInboxReader`.
+- **User → Teammate DM**: UI writes to `inboxes/{member}.json` with `from: "user"`. Native teammates read it directly; OpenCode teammates receive it through runtime delivery.
-- **`relayMemberInboxMessages` is DISABLED** for teammate DMs (commented out in `teams.ts` and `index.ts`). It caused bugs: lead responding instead of teammate, duplicate messages, relay loops. Code preserved but not called.
+- **Teammate → User response**: Teammate writes to `inboxes/user.json` or uses the runtime-specific Agent Teams message tool that persists there. UI reads all inbox files including `user.json` via `TeamInboxReader`.
-- **`relayLeadInboxMessages` is ACTIVE** — lead needs it because lead reads stdin, not inbox files.
+- **`relayMemberInboxMessages` is legacy fallback code, not the normal teammate-DM path.** The UI caller in `src/main/ipc/teams.ts` is disabled because lead-mediated relay caused lead replies, duplicate messages, and relay loops.
-- Messages in `user.json` may lack `messageId` — `TeamInboxReader` generates deterministic IDs via sha256(from+timestamp+text).
+- **`relayLeadInboxMessages` is ACTIVE** - lead needs it because lead reads stdin, not inbox files.
+- Messages in `user.json` may lack `messageId` - `TeamInboxReader` generates deterministic IDs via sha256(from+timestamp+text).
 - See `docs/team-management/research-messaging.md` for full architecture details.
 
 #### Team Protocol Details

README.md

@@ -5,7 +5,7 @@
   <a href="docs/screenshots/8.png"><img src="docs/screenshots/8.png" width="75" alt="Task Detail" /></a>&nbsp;
   <img src="resources/icons/png/1024x1024.png" alt="Agent Teams" width="80" />&nbsp;
   <a href="docs/screenshots/9.png"><img src="docs/screenshots/9.png" width="75" alt="Execution Logs" /></a>&nbsp;
-  <a href="docs/screenshots/3.jpg"><img src="docs/screenshots/3.png" width="75" alt="Agent Comments" /></a>&nbsp;
+  <a href="docs/screenshots/3.png"><img src="docs/screenshots/3.png" width="75" alt="Agent Comments" /></a>&nbsp;
   <a href="docs/screenshots/4.png"><img src="docs/screenshots/4.png" width="75" alt="Create Team" /></a>&nbsp;
   <a href="docs/screenshots/6.png"><img src="docs/screenshots/6.png" width="65" alt="Settings" /></a>
 </p>

docs/team-management/README.md

@@ -1,12 +1,12 @@
 # Team Management Feature
 
-Интерфейс для управления командами тиммейтов Claude Code внутри Agent Teams (Electron).
+Интерфейс для управления командами AI-тиммейтов внутри Agent Teams (Electron), включая Claude, Codex и OpenCode runtime paths.
 
 ## Что делает
 
 - Видеть состав команды и роли участников
 - Kanban-доска с 5 колонками: TODO, IN PROGRESS, REVIEW, DONE, APPROVED
-- Отправка сообщений тиммейтам через inbox-файлы
+- Отправка сообщений тиммейтам через inbox-файлы и runtime-aware delivery для OpenCode
 - Review flow: запрос ревью, ручное ревью и прямое manual approval из DONE
 - Live updates через file watcher
 
@@ -30,9 +30,9 @@
 
 ⚠️ `agent-attachments-*.md` (architecture plan + phase 1-5 plans) - это исторические дизайн-документы для feature attachments. Фактическая реализация в `src/features/agent-attachments/` может отличаться от описанной архитектуры. Для актуального состояния см. код в `src/features/agent-attachments/core/domain/` и тесты.
 
-### 1. Messaging: Inbox-файлы
+### 1. Messaging: inbox + runtime delivery
 
-Единственный способ общаться с **запущенными** тиммейтами. SDK и CLI создают новые сессии, а не подключаются к существующим. Подробности: [research-messaging.md](./research-messaging.md)
+Для native Claude/Codex-style тиммейтов основной путь - durable inbox-файлы. Lead inbox доставляется через `relayLeadInboxMessages()`, потому что lead читает stdin. OpenCode secondary lanes не читают `inboxes/{member}.json` напрямую, поэтому UI сначала сохраняет сообщение в inbox, затем доставляет его через runtime bridge с delivery proof. Подробности: [research-messaging.md](./research-messaging.md) и [debugging-agent-teams.md](./debugging-agent-teams.md)
 
 ### 1.1 Roster source: members.meta.json + inboxes
 
@@ -87,7 +87,7 @@ Kanban-позиция (REVIEW, APPROVED) хранится в `kanban-state.json`
 
 ### Members: полный список через union
 
-- `union(config members + inbox filenames + task owners)` — единственный способ получить полный список
+- `union(members.meta.json + config members + inbox filenames + task owners)` - единственный способ получить полный список
 - `owner` в task-файлах — опционален (агент может не иметь owner до назначения)
 
 ### Graceful Degradation

docs/team-management/debugging-agent-teams.md

@@ -17,17 +17,18 @@ Team root:
 ```bash
 TEAM="<team-name>"
 TEAM_DIR="$HOME/.claude/teams/$TEAM"
+TASKS_DIR="$HOME/.claude/tasks/$TEAM"
 ```
 
 Important files and folders:
 - `config.json` - configured members, provider/model selection, project path
-- `members-meta.json` - member metadata, removed members, worktree settings if present
+- `members.meta.json` - member metadata, removed members, worktree settings if present
 - `launch-state.json` - current app-side truth for member launch/liveness
 - `bootstrap-state.json` - bootstrap phase summary when present
 - `bootstrap-journal.jsonl` - ordered bootstrap events from the CLI/runtime
 - `inboxes/*.json` - durable inbox messages for user, lead, and native teammates
 - `sentMessages.json` - app-side sent-message records
-- `tasks/*.json` - task board state
+- `$TASKS_DIR/*.json` - task board state
 - `.opencode-runtime/lanes.json` - OpenCode lane index
 - `.opencode-runtime/lanes/<encoded-lane-id>/manifest.json` - lane-scoped runtime store manifest
 - `.opencode-runtime/lanes/<encoded-lane-id>/opencode-sessions.json` - committed OpenCode session evidence
@@ -155,7 +156,7 @@ For task stalls:
 
 ```bash
 TASK="<short-or-full-task-id>"
-rg -n "$TASK" "$TEAM_DIR/tasks" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
+rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
 ```
 
 Important distinctions: