# Vojo — AI Context Bank

**Single source of truth for every AI agent working on this repo.**

## Directive

Any agent (Claude Code, Cursor, Codex, Windsurf, Cline, Copilot, Aider, …) working here MUST:

1. Read every file in [docs/ai/](.) before making non-trivial changes.
2. Treat this folder as the ONLY authoritative source for project context.
3. Write new project knowledge HERE, not in `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `AGENTS.md`, home-dir memory, or wherever else your tool defaults to.
4. If a top-level agent file (like `CLAUDE.md`) appears to disagree with anything in `docs/ai/`, `docs/ai/` wins. Treat the top-level file as a stale pointer and fix it.

## Contents

| File | What's in it |
|------|--------------|
| [overview.md](overview.md) | What Vojo is, infrastructure, deployment target, developer profile, default homeserver rule |
| [architecture.md](architecture.md) | Stack, source layout, routing, features, state management, Matrix SDK patterns, git workflow |
| [i18n.md](i18n.md) | i18next setup, translation patterns, Russian-language quality standards, localization progress |
| [android.md](android.md) | Capacitor wrapper, Android build chain, edge-to-edge, Service Worker invariants, ADB workflow |
| [electron.md](electron.md) | Electron desktop wrapper, privileged `vojo://` scheme for SW, build chain, IPC security, Windows distribution |
| [bugs.md](bugs.md) | Known bugs & regressions |
| [server-side.md](server-side.md) | Some configs that deployd on server |
| [ai-bot.md](ai-bot.md) | Vojo AI bot (`@ai:vojo.chat`) — server-side Grok-voiced cascade appservice: request flow, routes, provider seam, spend ledger, current cheap-web config |

## Rules for updating

- Prefer editing an existing entry over adding a new one.
- Don't duplicate content across files — pick the best home and cross-link if needed.
- Do not create a new `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc. with project knowledge. Those files should only contain a pointer back here.
- If you add a new topic file, also add it to the table above.
