beaver-gateway/.claude/CLAUDE.md

Code Principles

• Simplicity: Write simple, straightforward code
• Readability: Make code easy to understand
• Maintainability: Write code that's easy to update
• Less Code = Less Debt: Minimize code footprint
• NEVER write comments - code should be self-documenting

Layout

• src/beaver_gateway - python, unopinionated primitives (no vault paths, no agent names, no Russian): one package per capability - agents, backends, conversations, jobs, frontends, mcp, vault, security, events, storage; config.py loads a setup, app.py builds the runtime, cli.py is the entrypoint
• every string shown to a model or a user lives in a *Texts dataclass with English defaults (conversations/texts.py, frontends/telegram/texts.py); a setup overrides them
• ui - SvelteKit SPA (admin + Obsidian panel), served by the gateway from ui/build
• docs/MISSION.md, docs/PRD.md, docs/PLAN.md, docs/PROGRESS.md - keep PROGRESS.md current
• docstrings: one line per module saying what it is for, one line per public configuration field; no section references, phases or history

Checking commands

After writing code, always run (or make check):

ruff format          # python formatter
ruff check --fix     # python linter
ty check             # python type-checker
cd ui && bun fix     # frontend linter+formatter (ultracite)
cd ui && bun check   # svelte-check

Dependencies: uv add / cd ui && bun add, never edit lock files by hand.