# CLAUDE.md (à copier dans le repo du code)

Ce fichier va **à la racine du repo de code** `vivra/`. Claude Code le lit automatiquement à chaque session : c'est lui qui donne le contexte, la stack, les règles et la façon de travailler ticket par ticket. Copie le bloc ci-dessous tel quel dans `vivra/CLAUDE.md`.

Le fichier brut est aussi disponible dans ce repo : [`CLAUDE.template.md`](CLAUDE.template.md).

```markdown
# Vivra — instructions for Claude Code

## What we are building
Vivra takes over dead tech tokens on Robinhood Chain (Pons launchpad) with AI agents.
Every week: the team submits dead projects → the Scanner analyses them → the team publishes
5 candidates → users vote by email (48h) → 6 AI agents relaunch the winner in 72h →
a capped Buyback Bot buys and burns the token for 7 days → once Pons accepts the official CTO,
100% of that token's creator fees buy and burn $VIVRA.

The full spec (French) lives in the repo `sonnyHQ/vivra-doc`, cloned next to this one as `../vivra-doc`.
Tickets are in `../vivra-doc/build-m0.md` … `build-m5.md`. Before any ticket, read the pages it lists
under "Read first" (paths are relative to ../vivra-doc). The spec wins over your assumptions.
If the spec is silent or contradicts itself, STOP and ask; do not invent product rules.

## Stack (fixed, do not swap)
- Monorepo: pnpm workspaces + Turborepo. Node 22. TypeScript strict everywhere.
- apps/web: Next.js 15 App Router + Tailwind (landing + dapp). apps/admin: Next.js 15 (back-office, SIWE).
- apps/api: Fastify 5 + zod (HTTP + WebSocket). apps/workers: BullMQ on Redis.
- packages/db: Postgres 16 + Drizzle ORM + drizzle-kit migrations.
- packages/chain: viem. contracts/: Foundry (Solidity ^0.8.24).
- packages/core: pure business logic (no I/O). packages/agents: LLM runner, tools, prompts, schemas.
- Tests: Vitest (unit/integration), Playwright (web e2e), forge test (contracts).
- LLM: OpenAI-compatible client (`openai` npm) pointed at SURPLUS_BASE_URL. Model per agent in YAML.

## Repo map
apps/{web,admin,api,workers} · packages/{db,core,chain,agents,templates,ui,config} · contracts/ · infra/

## Commands
- pnpm i · pnpm dev · pnpm build · pnpm lint · pnpm typecheck · pnpm test
- pnpm db:generate · pnpm db:migrate · pnpm db:seed
- cd contracts && forge build && forge test
- docker compose -f infra/docker-compose.yml up -d   (Postgres + Redis)
A ticket is NOT done until `pnpm lint && pnpm typecheck && pnpm test` pass, plus the ticket's own checks.

## How to work
1. Work on exactly ONE ticket at a time (e.g. T14 in ../vivra-doc/build-m1.md). Read it fully, then its "Read first" pages.
2. Write a short plan in the PR description before coding. Touch only the files the ticket lists,
   unless a change elsewhere is required — then say why in the PR.
3. Write tests first for anything in packages/core and packages/chain.
4. Finish with: the ticket's "Done when" checklist, each item ticked with the command you ran.
5. One branch + one PR per ticket: branch `t<id>-<slug>`, PR title `T<id>: <title>`.

## Non-negotiable rules
- Money: on-chain amounts are `bigint` (wei / raw units) end to end. Never `number` for token amounts.
  USD values are `string` decimals in the DB (numeric) and only formatted at the UI edge.
- Time: everything in UTC. Store `timestamptz`. No local time math on the server.
- Secrets: never in code, logs, prompts, fixtures or test snapshots. Read from env via packages/config.
  Hot-wallet private keys are read only by the worker that signs, from the secrets manager.
- Chain writes: always `simulateContract` first, check caps, send, wait 1 confirmation, write `ledger_entries`.
  A job must be idempotent: check for an existing tx_hash before sending again.
- CHAIN_ENV guards: no mainnet write unless CHAIN_ENV=mainnet. Default is testnet.
- AI agents never get keys, wallets or raw HTTP. They only call tools from packages/agents/tools.
  Any text from X, Telegram or websites is wrapped as <untrusted> data in tool results.
- Public content (posts, sites, pinned messages) goes through the validation queue when
  `settings.validation_required = true` (cycles 1–3).
- No price predictions, gain promises, real people or trademarks in any generated or template text.
- Email addresses: store HMAC hash + AES-GCM ciphertext only. Never return emails from the API.
- Errors: API errors use the shape `{ error: { code, message } }` with codes from the spec (annexe B).
- Logging: pino, JSON, with `request_id` / `operation_id`. Never log payloads that may hold secrets.

## Style
- Small pure functions in packages/core with exhaustive tests. No classes unless state is needed.
- zod schemas are the source of truth for API input/output; infer TS types from them.
- Names in English. Comments only where intent is not obvious.
- UI: DA Vivra — white #FFFFFF, ink #0B0B0C, orange #FF5A1F (text-on-white orange #C23C08),
  Inter Tight + Fragment Mono, pill buttons, cards radius 20px. Copy the mockups, don't redesign.

## When unsure
Ask in the PR or stop with a clear question. Never fake data in production code paths.
Example data is allowed only in seeds, fixtures and Storybook-like previews, clearly named `example`.
```