# CLAUDE.md — claude-agent (spațiul punții Discord)

Vezi `README.md` pentru context general.

## Cum lucrezi (OBLIGATORIU pentru orice cerere de dezvoltare)

1. **Citește [`TODO.md`](TODO.md)** — registrul viu al funcționalităților. Poate lucrul e
   deja început, blocat sau abandonat deliberat.
2. **Planifică pe Opus**, delegând unui subagent: `Agent(subagent_type: "Plan",
   model: "opus", ...)`. Firul rulează pe Sonnet; nu schimba modelul firului.
   **Pasul ăsta nu se sare pentru că sarcina pare mică.** Un singur fișier nou, un
   script de 20 de linii, o schimbare „evidentă" — tot trec prin subagentul Opus.
   Mărimea nu e criteriu; singurul criteriu e dacă schimbi ceva (vezi lista de
   excepții din documentul de flux).
3. **Postează planul în fir**, apoi **execută tu, pe Sonnet**.
4. **Actualizează [`TODO.md`](TODO.md)** la final — mută intrarea, scrie data absolută,
   adaugă o linie în `Jurnal`. Dacă rămâne ceva neterminat, scrie explicit următorul pas:
   firul următor nu va ști nimic din conversația asta.

Pașii, excepțiile (întrebări și diagnostice nu au nevoie de plan) și motivele sunt în
**[docs/flux-dezvoltare.md](docs/flux-dezvoltare.md)** — citește-l înainte de prima
cerere de dezvoltare din fir.

## Unde ești

Rulezi pe **LXC 171 (`claude-agent`, 10.0.20.171, nod pvemini)**, în ecosistemul Romfast:
un cluster Proxmox de 3 noduri, Oracle XE 21c, ERP-ul **ROA**, plus punțile de chat
(Discord, WhatsApp). Directorul acesta e doar spațiul de lucru al punții Discord —
**nu** e tot ce știi.

**Documentația reală a infrastructurii e în `/workspace/romfastsql/`**, un repo separat
(`git@gitea.romfast.ro:romfast/ROMFASTSQL.git`). Citește de acolo înainte să cauți cu
`find`/`grep` prin tot discul:

| Ai nevoie de… | Citește |
|---|---|
| Regulile proiectului + indexul complet de documentație | `/workspace/romfastsql/CLAUDE.md` |
| Infrastructură Proxmox (noduri, LXC, VM, rețea, incidente) | `/workspace/romfastsql/proxmox/README.md` |
| Codul punții Discord (acest bot) | `/workspace/romfastsql/proxmox/lxc171-claude-agent/discord-bridge/` |
| Codul Mariei (WhatsApp + RAG) | `/workspace/romfastsql/proxmox/lxc171-claude-agent/maria-whatsapp-bridge/` |
| Oracle (XE 21c/18c, migrări, cazuri clienți) | `/workspace/romfastsql/proxmox/lxc108-oracle/` |
| Reguli SQL de migrare (obligatoriu înainte de a scrie SQL) | `/workspace/romfastsql/system_instructions/system_prompt.md` |

Rezumat rapid, dacă nu vrei să deschizi nimic: [docs/infrastructure.md](docs/infrastructure.md).

## Memorie

Memoriile acestui director sunt **comune cu cele ale proiectului `romfastsql`**
(`~/.claude/projects/-workspace-claude-agent/memory` e un symlink către
`~/.claude/projects/-workspace-romfastsql/memory`). Deci ce s-a învățat lucrând pe
infrastructură e disponibil și în firele de pe Discord, și invers — scrie memorii
acolo, nu în fișiere ad-hoc. Copia veche, dinainte de unificare:
`~/.claude/projects/-workspace-claude-agent/memory.bak-2026-08-31`.

Sesiunile Discord sunt totuși **per fir**: un fir nou pornește o sesiune Claude nouă,
care are memoriile de mai sus dar nu conversația din alt fir. Ce trebuie să
supraviețuiască între fire se scrie în memorie sau în documentație, nu se presupune.

## Canal principal

Utilizatorul comunică cu acest agent în principal prin **Discord**, prin puntea
Discord → Claude Code (vezi și `docs/echo-roa2web.md` pentru diferența față de
Echo/MoltBot). Botul care răspunde pe Discord este acest agent (**claude-agent**,
LXC 171), nu Echo. Atașamentele trimise pe Discord ajung la tine din 2026-08-31:
imaginile (png/jpeg/gif/webp, max 4) le vezi direct, fișierele text intră în prompt,
restul sunt doar numite. Mesajele vocale, nu — vezi `TODO.md`.

## Documentație locală

| Subiect | Fișier |
|---------|--------|
| **Progresul funcționalităților (de citit și actualizat la fiecare cerere)** | [TODO.md](TODO.md) |
| **Fluxul de lucru: plan pe Opus → execuție pe Sonnet → TODO.md** | [docs/flux-dezvoltare.md](docs/flux-dezvoltare.md) |
| Infrastructură Proxmox — rezumat (noduri, LXC, VM, proiecte) | [docs/infrastructure.md](docs/infrastructure.md) |
| Echo (LXC 110 moltbot) — acces și comenzi pentru roa2web | [docs/echo-roa2web.md](docs/echo-roa2web.md) |
| Punte Discord → Claude Code — context | [docs/discord-bridge-context.md](docs/discord-bridge-context.md) |
| **Care chatbot e care** (trei „Maria", doi boți de Discord, două punți WhatsApp) | `/workspace/romfastsql/docs/chatboti-si-punti.md` |
| Maria — punte WhatsApp + RAG | [docs/maria-whatsapp-rag-prototype.md](docs/maria-whatsapp-rag-prototype.md) |

## Maria (RAG) — GRANIȚĂ OBLIGATORIE

**Maria e chatbot de suport tehnic pentru clienții ERP ROA. Nu are voie să vadă nimic
din infrastructura Romfast.**

Maria răspunde exclusiv din depozitul ei de documente
(`~/.maria-bridge/documents/`, sincronizat din `D:\GoogleDrive\romfast\document_store`);
prin construcție nu are shell, nici acces la fișiere în afara acelui depozit. Granița se
poate rupe doar dacă **tu** pui acolo ce nu trebuie. Deci:

- **NU** copia niciodată în `~/.maria-bridge/documents/` (sau în dosarul Drive
  `document_store`) fișiere din `/workspace/romfastsql/proxmox/`, `docs/` de aici,
  `docs/infrastructure.md`, README-uri de infrastructură, runbook-uri, proceduri DR
  sau de failover.
- **NU** pune acolo IP-uri interne, nume de noduri/containere, porturi, chei SSH,
  parole, token-uri, string-uri de conexiune Oracle, adrese de clienți sau orice
  altceva operațional.
- În depozit intră **doar material orientat spre client final**: cum se folosește ROA,
  proceduri din aplicație, întrebări frecvente, mesaje de eroare din interfață.
- Când utilizatorul cere „adaugă documentul X la Maria", verifică întâi conținutul
  cu acest filtru. Dacă e material de infrastructură, refuză și spune de ce.
- Nu extinde `DOCS_DIR`, nu adăuga surse noi de indexare și nu adăuga unelte de
  fișiere/shell consumerului Mariei (`rag/consumer.py`) fără cerere explicită.
- **Profilurile de client** (`rag/client.py`, `~/.maria-bridge/clients.json`) sunt
  permise și separate de depozitul de documente: conțin doar ce ar spune clientul
  despre firma lui (nume, domeniu, program ROA folosit, particularități). **NU**
  sunt o portiță spre infrastructură — nu pune acolo date tehnice de instalare
  (server, utilizator de bază de date, parole, IP-uri). Același filtru ca mai sus.

Pentru contrast: **tu** (punte Discord) ai voie la toată infrastructura, inclusiv SSH
și `pct exec` — vezi memoriile. Maria, nu.

## Convenții de lucru

- Pentru sarcini care se pot repeta (ex: extragere transcript video, procesare de
  fișiere), scrie un script reutilizabil (bash/python) în `tools/` în loc de comenzi
  ad-hoc de unică folosință.
- Acest director e **repo propriu** (`git@gitea.romfast.ro:romfast/claude-agent.git`).
  Nu comite aici modificări la codul punții sau la documentația de infrastructură —
  alea aparțin repo-ului `romfastsql`. `/workspace` e la rândul lui alt repo
  (`romfast/workspace`) și ignoră acest director.