# AGENTS.md — OpenVibe.Fun

## Project Overview

OpenVibe.Fun is the Fun room: IRL quest boards attached to a public OpenVibe.Live channel, a deterministic
"what's fun near me" guide from OpenStreetMap (Ticketmaster only when a key is configured), and group plans with one
vote each and a winner the viewer can add to their own OpenVibe.Today.

- **Domain:** `openvibe.fun` · **Port:** 5140 · **Service id:** `fun` · **Env prefix:** `FUN`
- **Runtime:** Node 22, Express 4, PostgreSQL 18 through `openvibe-sdk/db` (embedded PGlite in development/tests),
  Valkey 9 for shared limit counters.
- **Read first:** [README.md](README.md) (ownership, API and safety rules) and [STATUS.json](STATUS.json).

**Network context:** identity, roles and the OpenCoins wallet are OpenVibe.Network (OAuth client `fun`, PKCE S256;
staff means Network role `global_mod` or above). Fun **reads** Live's public channel state and Chat's public history
through `server/upstreams.js`; it never posts to Live or Chat. Today is written only with the signed-in person's own
Network token (`server/today.js`). Account export/deletion arrives from OpenVibe.Events at `/internal/events`. Search
documents wait in `fun_outbox` and are delivered by `openvibe-publishing/search-relay` (`server/search.js`). Fun owns
no other service's state.

## Commands

```bash
npm ci                         # install (the repo pins contracts/sdk/shared by tag)
npm run dev                    # http://localhost:5140, NODE_ENV=development
npm start                      # node server/index.js
npm test                       # every test/*.test.js in its own process, temp PGlite, mocked Network/upstreams
npm run test:pg                # the same through PostgreSQL + PgBouncer (openvibe-sdk scripts/test-services.sh up)
npm test -- quests             # only test files whose name contains the word
npm test -- --strict           # a skipped test fails the run
node --check <file.js>         # syntax check (no linter/formatter in this repo)
```

`test/run.js` uses `openvibe-shared/test-runner`; tests never reach the internet — upstream fixtures are local. There
is **no build step**: pages are server-rendered and assets are served from `public/` with content-hash cache headers.

## Architecture at a Glance

- **Entry:** [server/index.js](server/index.js) — starts the listener, telemetry tick/retention, the read-only chat
  sync, the OpenCoin retry timer and the Events subscriptions; `FUN_DRILL` keeps boot-time work off. Graceful stop is
  `createLifecycle()` in the same file.
- **App factory:** [server/app.js](server/app.js) — helmet/CSP, SSO middleware, `/auth`, `/internal/events`,
  `/shared` + static, `/api/v1`, the agent layer (Markdown twins and `/.well-known/agent.json`), pages, 404 and error
  handler. Tests build this app with `createApp({ store, fetchImpl, ... })`.
- **Config:** [server/config.js](server/config.js) — `load(env)` is pure; production reads `/etc/openvibe/fun.env`.
  Only variable **names** appear in code and docs.
- **Database:** [server/db.js](server/db.js) — migrations in [migrations/](migrations/) run at boot with
  `DATABASE_DIRECT_URL` (owner); `DATABASE_URL` serves through PgBouncer. No table is created at runtime.
- **Store/domain:** [server/store.js](server/store.js), [server/quests/](server/quests/) (`ideas.js`, `safety.js`),
  [server/guide/](server/guide/) (`index.js`, `places.js`, `upstream.js`, `events.js`),
  [server/chat-sync.js](server/chat-sync.js), [server/coins.js](server/coins.js),
  [server/sharing.js](server/sharing.js), [server/today.js](server/today.js).
- **HTTP:** [server/http/router.js](server/http/router.js) is the async router; [server/http/api.js](server/http/api.js)
  mounts `/api/v1`, [server/http/pages.js](server/http/pages.js) the pages, [server/http/principal.js](server/http/principal.js)
  decides person vs service token and capabilities. Views are under [server/views/](server/views/).
- **Auth:** [server/auth/sso.js](server/auth/sso.js) + [server/auth/keys.js](server/auth/keys.js) — Network OAuth2
  PKCE and offline JWKS verification; staff from the Network role claim ([server/identity/staff.js](server/identity/staff.js)).
  Account export/deletion: [server/identity/account-data.js](server/identity/account-data.js).
- **Frontend:** server-rendered HTML through [server/render/layout.js](server/render/layout.js) and
  [server/render/html.js](server/render/html.js), which pull the OpenVibe Frame/kit from `openvibe-shared`. Assets:
  [public/css/fun.css](public/css/fun.css), [public/js/fun.js](public/js/fun.js). Pages work without JavaScript; JS
  only adds convenience. Markdown twins come from [server/agent-pages.js](server/agent-pages.js) and
  [server/agent-descriptor.js](server/agent-descriptor.js).
- **Deploy:** [deploy/systemd/openvibe-fun.service](deploy/systemd/openvibe-fun.service) (127.0.0.1:5140,
  `/etc/openvibe/fun.env`) and [deploy/nginx/openvibe.fun.conf](deploy/nginx/openvibe.fun.conf) (TLS, www → apex,
  `/internal` and `/metrics` closed). `sudo ovhost deploy fun` on the host; database `ov_fun`; /opt/openvibe.fun.

## Ownership and Boundaries

Fun is the authority for the tables its migrations create: quest boards/quests/votes/checks/badges/rewards, plans and
their options/votes, `fun_reports`, `fun_chat_seen`/`fun_chat_cursors`, `fun_geo_cache`, `fun_outbox`,
`account_data_events`, sharing tables and `telemetry_samples`. It is **not** the authority for:

- identity, accounts, roles, sessions or the wallet — OpenVibe.Network;
- Live channels, Chat rooms/history, Today calendars — read-only upstreams or the person's own token;
- OSM/Ticketmaster data — cached, attributed public sources, never paid providers;
- event delivery (OpenVibe.Events), the host/database/Valkey (OpenVibe.Host), or the search index (OpenVibe.Search).

Public quests/plans are anonymized on account deletion; shared plans stay for their other members. Never silently keep
a deleted person's name on a row.

## Auth and Capabilities

- A person is the `fun_at` session cookie or `Authorization: Bearer <Network user token>`, verified offline. A
  cookie-authenticated write must come from `https://openvibe.fun` (403 `fun.cross_site`).
- Per-actor limits: `FUN_LIMITS_MINUTE`, `FUN_LIMITS_HOUR`; shared counters use Valkey.
- **Inbound v1: no service capability guards a route.** Do not invent one.
- **Outbound:** `events.subscription.manage` at boot; `network.account.export.contribute` and
  `network.account.deletion.confirm` through `openvibe-sdk/account-data`; `search.document.write` for the Search
  relay; `network.coins.credit` + `identity.subject.resolve` only when `FUN_COINS=on`.
- The OpenCoin credit is an outbox (`fun_quest_rewards`) with retries; the local badge is always paid.

## API (JSON under `/api/v1`)

`GET /guide`, `GET /quests`, `GET /quests/ideas`, `GET /quests/boards/:id`, `GET /quests/:slug`,
`POST /quests/boards`, `POST /quests/boards/:id/suggest|idea`, `POST /quests/:slug/vote|accept|live|complete|verify|hide|report`;
`GET /plans`, `GET /plans/:slug`, `POST /plans`, `POST /plans/:slug/options|vote|decide|today|hide|report`;
`GET /reports` (staff). Discovery/health: `/api/v1/ping`, `/openapi.json`, `/llms.txt`, `/sitemap.xml`, `/robots.txt`,
`/api/health`, `/api/ready`, `/release.json`, `/metrics` (loopback only). Errors are RFC 9457
`application/problem+json` with a stable `code` (`fun.invalid`, `fun.quest.*`, `fun.plan.*`, `fun.rate_limited`, …).

## Conventions

- CommonJS (`require`/`module.exports`), 4-space indent, single quotes, semicolons; no linter/formatter.
- Every route handler goes through [server/http/router.js](server/http/router.js) so async rejections reach the error
  handler. Never log request bodies; never return raw rows — page/view code renders explicit fields.
- IDs are `prefix_` + ULID via the store; timestamps are ISO strings from the injected clock.
- New schema = a new `migrations/NNNN_name.sql`; never edit a migration that has run. Keep table prefixes `fun_`.
- CSP: add every external origin to the `helmet` directives in [server/app.js](server/app.js); images/frames default
  to self plus the named OpenVibe hosts. Do not widen `frameAncestors` or `objectSrc`.
- Phone first: pages must work at 390 px with no horizontal overflow; the navbar/footer come from `openvibe-shared`.
- "Calm reduces, only Off removes": a user preference may de-emphasize content, never delete it; an Off switch is the
  only removal.
- Public pages must have real content in the first paint — no placeholder text or fake counts (`home-real-content`,
  `home-real-first` tests); link-outs must be real (`remind-links`).
- Do not add model calls or a new AI capability here: v1 is deterministic.

## Key Pitfalls

- **No build step.** Editing `public/` is live on deploy; do not add `?v=` by hand — the layout's asset version does
  that.
- **Upstreams are public and optional.** Ticketmaster is off without `TICKETMASTER_API_KEY`; OSM must be paced,
  cached, attributed (ODbL) and has a stale fallback. Never fetch an arbitrary user URL.
- **Read-only chat.** `server/chat-sync.js` ingests `!quest`/`!plan` commands idempotently per chat message id; it
  must never write to Chat or Live.
- **Drill mode.** Anything started at boot (timers, loops, outbound calls) must be off under `FUN_DRILL`.
- **Agent layer.** `.md` paths and `?format=markdown` are handled before page routes so `/q/x.md` is a twin, not a
  quest slug. New top-level page routes must also be visible to [server/http/pages.js](server/http/pages.js) and the
  sitemap/llms artifacts.
- **Safety filter.** `server/quests/safety.js` is explainable and must keep rejecting dangerous, illegal,
  trespassing and harassing suggestions before storage.
- **Account deletion** runs through `/internal/events` only (loopback, signature-verified); a redelivered event must
  change nothing.
- **No Font Awesome** in new UI unless the shared kit/glyph test for the page allows it; use the shared glyph set.

## Testing

`npm test` boots every `test/*.test.js` in its own process on a temporary PGlite database with a mock Network and
fixture upstreams (`test/run.js`). The suite covers migration, quest safety/state machine, chat idempotency, plan
voting/tie/Today, Search documents, SSO, cache/pages, coins opt-in off/on, sharing, account export/deletion, agent
layer, real-content-first and broken-link regressions. `npm run test:pg` runs the same suite through PostgreSQL +
PgBouncer. Run the narrowest file first (`npm test -- quests`), then the suite. Always `node --check` changed files.

## Documentation

- [README.md](README.md) — purpose, owns/does-not-own, capabilities, API, quest safety, guide, plans, pages, Search,
  run/test, deploy.
- [STATUS.json](STATUS.json) — current stage, deployed flag, features and not-yet list.
- [.env.example](.env.example) — every variable (names only; never commit values).
- [CHANGELOG.md](CHANGELOG.md) — released changes.
- [SECURITY.md](SECURITY.md) — vulnerability reporting.