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

ddiff --git a/AGENTS.md b/AGENTS.md
nnew file mode 100644
iindex 0000000..a4492ea
---- /dev/null
++++ b/AGENTS.md
@@@ -0,0 +1,159 @@
++# AGENTS.md — OpenVibe.Coupons
++
++## Project overview
++
++Coupon codes with merchant matching, restrictions, expiry and real-people validity reports, plus the
++public API the OpenVibe browser helper uses. Distinct from Deals even where they cross-link. Node.js/
++Express, PostgreSQL (`ov_coupons`), server-rendered, CommonJS, **no build step**.
++
++- Service id `coupons`, port `4850`, origin `https://openvibe.coupons`, unit `openvibe-coupons.service`,
++  release root `/opt/openvibe.coupons`.
++- It holds **no codes** today: nothing is seeded and no coupon source is enabled.
++
++## The four rules
++
++1. **No code is "working" because a model guessed it.** Status comes only from recent reports by
++   people; a submission, a source, staff or AI output cannot set it.
++2. **Unknown stays unknown.** An unstated expiry is "Expiry unknown" (`null` in JSON); no recent reports
++   means no confidence number; "no restrictions stated" is never "no restrictions".
++3. **Expired codes leave active results predictably** — at the instant their known expiry passes, in
++   the API, pages, feeds, sitemaps and Search.
++4. **A merchant page (or any page) cannot obtain anyone's data.** Lookups return the same bytes to
++   every caller; the API ignores cookies; the extension holds no OpenVibe session.
++
++## What it owns
++
++The nine charter tables in [migrations/](migrations/):
++
++| Table | What |
++|---|---|
++| `coupon_merchants` | `pending` (member proposal, invisible until staff approve), `active`, `disabled` |
++| `coupon_merchant_domains` | normalized host, registrable domain (eTLD+1), subdomain rule, optional path prefix |
++| `coupons` | code; status exactly `unknown\|reported_working\|reported_failed\|expired\|disabled`; confidence `NULL` when no recent reports; `expires_at` `NULL` with precision (`instant`/`date`) and basis (`evidence`/`submitter`/`source`/`staff`); review state `pending\|published`; origin `member\|staff\|source\|ai` |
++| `coupon_sources` | evidence: member/staff submissions (URL, own-domain flag), Sources items (id, revision, retrieval time), AI runs |
++| `coupon_restrictions` | min spend (minor units + ISO 4217), categories, new customers only, ISO 3166-1 regions, other |
++| `coupon_validation_reports` | worked/failed; one per (reporter, code, UTC day); reporter is an HMAC of the subject |
++| `coupon_status_history` | every status/confidence change with reason and actor |
++| `coupon_application_hints` | how to apply a code (one code or all of a merchant's) |
++| `coupon_watches` | private member watches |
++
++Plus `extension_installs` (browser-helper tokens, hashes only), the Sources importer state/holds, the
++SDK outbox and the publishing index sequencer.
++
++Not owned: the merchant's real terms, the browser extension itself
++([OpenVibe.Extensions](https://github.com/OpenVibers/OpenVibe.Extensions)), identity, the Search index.
++
++## Who calls it, and whom it calls
++
++- Callers: people in the browser; the **browser helper** with an extension token; OpenVibe.Sources'
++  importer; services with a Network service token audience `openvibe.coupons` and the route's
++  capability; staff moderation.
++- Depends on: **Network** (SSO client `coupons`, JWKS, account export/deletion); **Sources**
++  (`sources.item.read`, category `coupons`; the seeded `staff-coupon-codes` source is disabled until a
++  person enables it); **Events** (SDK outbox); **Search** (consumes `coupons.index_document.*`);
++  `openvibe-publishing` (seo gate, ssr, index hooks); PostgreSQL and Valkey; `openvibe-contracts`/
++  `openvibe-sdk`/`openvibe-shared` pins.
++
++## Repository map
++
++- **Entry:** [server/index.js](server/index.js) — app, worker (expiry sweep, importer), outbox;
++  graceful stop.
++- **App:** [server/app.js](server/app.js) — helmet/CSP, `/auth`, `/shared`, `/api/v1` (API),
++  `/api`, pages, discovery, health/ready.
++- **Config/db:** [server/config.js](server/config.js), [server/db.js](server/db.js).
++- **Domain:** [server/domain/](server/domain/) — `publication.js`, `merchants.js`, `coupons.js`,
++  `reports.js`, `installs.js`, `watches.js`, `facts.js`, `moderation.js`.
++- **Clients:** [server/clients/sources.js](server/clients/sources.js).
++- **HTTP/render:** [server/http/api.js](server/http/api.js), `public.js`, `discovery.js`,
++  `actor-limits.js`; [server/render/](server/render/) — pages, home, offer, store, short, layout.
++- **Auth:** [server/auth/viewer.js](server/auth/viewer.js); [server/sharing.js](server/sharing.js).
++- **Worker/importer:** [server/worker.js](server/worker.js), `server/events/consumer.js`.
++- **Deploy:** [deploy/systemd/openvibe-coupons.service](deploy/systemd/openvibe-coupons.service),
++  [deploy/nginx/openvibe.coupons.conf](deploy/nginx/openvibe.coupons.conf).
++
++## Commands
++
++```bash
++npm ci
++npm run dev                # NODE_ENV=development node server/index.js
++npm start                  # node server/index.js, http://127.0.0.1:4850
++npm test                   # test/run.js, PGlite, mock Network/Sources/Events
++npm run test:pg            # same on PostgreSQL (COUPONS_TEST_STORE=pg)
++npm test -- lifecycle      # filter by file name; --strict makes a skip fail
++ov test                    # the harness's sharded run of what the change reaches
++```
++
++## Database and migrations
++
++`ov_coupons` on the host's data role (ADR-035); PGlite in development/tests. Async through
++`openvibe-sdk/db`; migrations `migrations/NNNN_*.sql` applied at boot; never edit an applied migration,
++add a new number. The status/confidence history is append-only in spirit: a change writes
++`coupon_status_history` and the outbox in the same transaction, and the expiry sweep records the event
++and tombstone once.
++
++## Auth and privacy
++
++- People sign in through Network SSO for submissions, watches and reports. The **public API takes an
++  `Authorization` header only**; it ignores cookies and returns the same bytes to every caller, so a
++  merchant page cannot read a visitor's data.
++- The browser helper authenticates with an **extension token**: stored as a hash, scoped, revocable,
++  and refused immediately on revocation; no OpenVibe session lives in the extension.
++- Reports are never anonymous, deduplicated per (reporter, code, UTC day), only the latest per person
++  counts, and rate-limited per hour/day; the reporter is an HMAC, not a subject id.
++- Service callers need the route's capability (`coupons.*`); staff actions are audited.
++
++## Frontend loading model
++
++Every page is server-rendered and **useful without JavaScript**; there is no SPA, bundler or
++transpiler. `openvibe-shared` supplies the Frame, legal/SEO and `/shared/*` from the pinned
++node_modules; `openvibe-publishing` supplies the SSR/index helpers. Discovery (robots, sitemap, feeds,
++`llms.txt`, IndexNow) is generated from the same data. CSP and cache policy are in
++[server/app.js](server/app.js) and `openvibe-shared/cache-policy`.
++
++## Deploy
++
++`sudo ovhost deploy coupons` (git-checkout: fetch, fast-forward `/opt/openvibe.coupons`, install on a
++lockfile change, restart, wait for `/api/ready`). Unit `openvibe-coupons.service` on
++`127.0.0.1:4850`, env `/etc/openvibe/coupons.env`; the release migrates `ov_coupons` at boot; vhost
++[deploy/nginx/openvibe.coupons.conf](deploy/nginx/openvibe.coupons.conf). Rollback
++`sudo ovhost rollback coupons --to <sha>`. No secret in a command line, file or log.
++
++## Tests
++
++`npm test` runs each `test/*.test.js` in its own process with PGlite and in-process Network/Sources/
++Events mocks. The README's acceptance table maps each rule to its test: `lifecycle.test.js` (unknown
++stays unknown, status fields refused from everyone, AI held for review, expiry at the instant, the
++sweep once), `reports.test.js` (dedupe, latest-per-person, rate limits, no cookies/anonymous),
++`confidence.test.js` (the formula), `extension-privacy.test.js` (hashing, revocation, scopes) and more.
++`ov test` runs the same.
++
++## Conventions
++
++- CommonJS, 4-space indent, single quotes, semicolons; domain in `server/domain/`, HTTP in
++  `server/http/`, no SQL in routes.
++- Ids/errors/capabilities from `openvibe-contracts`; errors are problem+json with stable codes.
++- Dates are UTC; an expiry carries its precision and basis, and an unknown one stays `null`.
++- Escape all rendered text; no personal data in URLs, JSON-LD, feeds or the API.
++
++## Pitfalls
++
++- **A model, a source or staff cannot mark a code working.** Only recent people's reports move the
++  status; an AI-origin code is `pending` review. Do not add an admin "set working" path.
++- **Unknown is not zero/false.** No expiry → `null`, no reports → `confidence: null`, no stated
++  restriction → "none stated". Do not substitute defaults.
++- **Expiry is instantaneous.** API/page/feed/sitemap/Search must agree at `t-1ms` and `t`; an expired
++  page is noindex.
++- **The public API is cookie-blind.** Do not add session-based personalisation or per-caller bytes.
++- **Reports are per person per code per day**, latest wins; a second report does not add a second
++  count, and no anonymous report is accepted.
++- **Tracking/affiliate links are not introduced here**; a source's link policy is explicit, and the
++  code's evidence URL must be on the merchant's own domain where the rule says so.
++- **The extension token is a secret**: hash at rest, never returned after creation, revocation immediate.
++- **No Offer/validity JSON-LD** — the README deliberately omits it; do not add price/validity markup.
++
++## Documentation
++
++- [README.md](README.md) — the rules, tables, statuses/confidence, routes, API, extension credentials,
++  events, capabilities, acceptance, security and deploy.
++- [docs/capabilities-proposal/](docs/capabilities-proposal/), [docs/service-manifest-proposal.json](docs/service-manifest-proposal.json).
++- OpenVibe.Contracts holds the `coupons.*` shapes; Sources owns the item contract.
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]