AGENTS.md: the context an agent starts from (#233)

ddiff --git a/AGENTS.md b/AGENTS.md
nnew file mode 100644
iindex 0000000..79d607d
---- /dev/null
++++ b/AGENTS.md
@@@ -0,0 +1,98 @@
++# AGENTS.md — OpenVibe.SDK
++
++## Project overview
++
++The one supported way for any app — first-party service or an outside developer — to call the
++OpenVibe network. This repository is the npm package `openvibe-sdk` (MIT), a dependency-free
++JavaScript/TypeScript client library, not a service: it owns no database, no port and no deploy.
++
++- **Entry points:** `index.js` (Node, CommonJS), `browser.js` (browser-safe), `esm/*.mjs` (generated
++  ESM shims for every subpath), `types/*.d.ts`, and `browser/openvibe-sdk.mjs` (one self-contained
++  browser bundle, checked in).
++- **Source:** one module or directory per capability under `src/` (`src/core/`, `src/auth/`,
++  `src/db/`, `src/service/`, `src/events.js`, `src/valkey.js`, `src/media.js`, `src/community.js`,
++  `src/chat.js`, `src/ai.js`, `src/tools.js`, …), each exposing a `create*Client` factory.
++- **Contract types:** `openvibe-contracts` is a dev dependency used by the tests; at runtime the SDK
++  copies the types and shapes it needs, so consumers install the SDK alone.
++- **Docs:** `README.md` is the API reference, `docs/` holds capability guides
++  (`docs/service.md`, `docs/consent.md`, `docs/tools-routing.md`, `docs/identity-emails.md`, …),
++  `docs/api-surface.json` is the generated export inventory and `docs/one-point-oh.*` the 1.0
++  freeze plan.
++- **CLI:** `bin/openvibe-download.js` installs as the `openvibe-download` command.
++
++## Who calls it, what it calls
++
++Every OpenVibe service pins a released SDK tag
++(`"openvibe-sdk": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/vX.Y.Z"`)
++and calls services only through it. The rule in `README.md` is binding: **if a capability is not in
++the SDK, it is not public** — a route with no SDK wrapper is internal and may change without notice.
++To make something public, define it in OpenVibe.Contracts first, then wrap it here.
++
++The SDK never talks to a database or to another SDK module directly; each client takes a
++`createClient()` and calls one service's documented HTTP API: Network (auth, identity, registry,
++projects, user cards), Events, Media, Community, Chat, AI, Tools, Search, Bench, Vision, Live,
++OpenRestream, Inventory, Tips, Blog, Reviews, Wiki, Coupons, Deals, Trade, Space, Host, Run, Video,
++Work, Zone and VIP. `src/testing` provides `createMockPlatform()` so an app can test without the
++network.
++
++## Commands
++
++```bash
++npm ci                     # install (Node >= 20)
++npm test                   # every test/*.test.js, one process each, no network
++npm test -- core pack      # only files whose name contains a word
++npm test -- --strict       # a skipped test fails the run
++node scripts/esm.js        # regenerate esm/*.mjs from the CommonJS sources
++node scripts/browser-bundle.js   # regenerate browser/openvibe-sdk.mjs (checked in; a stale bundle fails test/bundle.test.js)
++node scripts/surface.js --check  # compare exports with docs/api-surface.json; exits non-zero on a 1.0-core break
++node scripts/surface.js    # rewrite docs/api-surface.json after an intentional export change
++node --check <file.js>     # syntax check; there is no linter
++```
++
++There is no build step for consumers and no runtime dependency: the package is plain CommonJS with
++checked-in ESM and browser bundles. `npm test` uses local stub servers and `createMockPlatform()`;
++it never touches the live platform.
++
++## Conventions
++
++- **CommonJS** (`require` / `module.exports`) in `src/`; ESM files under `esm/` are generated, never
++  edited by hand.
++- **4-space indent, single quotes, semicolons.** No linter or formatter is configured.
++- **`create<Thing>Client` factories** take a `createClient()` (or explicit `{baseUrl, tokenClient}`)
++  and return a plain object of methods. Errors are `OpenVibeError`/`ToolRunError` with a problem
++  code, not bare `Error`.
++- **Every subpath is an entry in `package.json` `exports`** with `types`, `import` and `default`
++  (and `browser` when browser-safe). Add a capability to `index.js`, `browser.js` (if safe),
++  `types/`, `esm/`, and `docs/api-surface.json`.
++- **Writes are retried only when idempotent.** Either the service honours `Idempotency-Key` or the
++  client does not retry (chat, live, streams and other writes are documented as never retried).
++- **Deadlines, trace propagation and safe retries** live in `src/core`; use them instead of
++  `fetch` + `setTimeout` by hand.
++- **No secrets in code or tests.** Tokens are injected; `src/redact` is the shared scrubber.
++
++## Key pitfalls
++
++- **The 1.0 core surface is frozen:** `core`, `auth`, `events`, `db` and `media` cannot lose or
++  rename an export without a major release. `test/surface.test.js` pins the exact lists and
++  `docs/one-point-oh.json` gives each name a tier.
++- **Generated files are checked in:** `esm/`, `browser/openvibe-sdk.mjs`, `types/` and
++  `docs/api-surface.json` must be regenerated and committed with a source change; the tests fail on
++  a stale bundle or surface. Never edit `node_modules`.
++- **Browser safety:** only browser-safe modules may be added to `browser.js` or the bundle — no
++  `fs`, `crypto` server APIs, `pg` or Valkey. A Node-only capability gets an `exports` entry with
++  `"browser": null` (see `./app-signin`).
++- **Versioning:** every release is a tag and services pin it; the changelog is `CHANGELOG.md`.
++  Breaking a frozen core export, changing a problem code or a retry rule is a major-version change.
++- **Consumers copy nothing:** `openvibe-sdk/no-looks` is deprecated (AI text may describe people);
++  `src/explicit` is the rule for sexual content, `src/front-page` for what may lead a front page.
++- **Do not add a runtime dependency.** The package is deliberately dependency-free and needs only
++  Node >= 20 or a browser with `fetch`, Web Crypto and `TextDecoder`.
++
++## Testing
++
++`test/run.js` runs every `test/*.test.js` in its own process (240 s timeout), honours
++`npm test -- <filter>`, and treats a skipped file as not passed; `--strict` makes any skip fail the
++run. Files under `test/` use `assert` and local stub servers, never the live platform; `testdata/`
++holds fixtures. `test/browser-entries.test.js` and `test/bundle.test.js` guard the browser surface;
++`test/surface.test.js` guards the public API inventory. Run `node scripts/surface.js --check` before
++committing a client change.
ddiff --git a/CLAUDE.md b/CLAUDE.md
nnew file mode 100644
iindex 0000000..43c994c
---- /dev/null
++++ b/CLAUDE.md
@@@ -0,0 +1 @@
+[email protected]