# AGENTS.md — OpenVibe.Help

## Project Overview

OpenVibe.Help is the help and support centre for every OpenVibe site: answers generated from the pinned
OpenVibe.Contracts manifests, search over those answers plus OpenVibe.Search's public network index, and a support
ticket that stays one conversation with staff.

- **Domain:** `openvibe.help` · **Port:** 5020 · **Service id:** `help` · **Env prefix:** `HELP`
- **Runtime:** Node 22, Express 4, PostgreSQL 18 through `openvibe-sdk/db` (embedded PGlite in development/tests),
  Valkey 9 for shared per-caller counters.
- **Read first:** [README.md](README.md) and [STATUS.json](STATUS.json).

**Network context:** identity, sessions and staff roles are OpenVibe.Network (OAuth client `help`, PKCE S256; staff is
the Network role `admin` or `global_mod`). The help text is OpenVibe.Contracts (read-only, quoted verbatim). The
"From across OpenVibe" half of `/search` calls OpenVibe.Search's public API. Account export/deletion arrives from
OpenVibe.Events at `/internal/events`. Help owns no text, account, search index or event broker of its own.

## Commands

```bash
npm ci                         # install (contracts/sdk/shared are pinned by tag)
npm run dev                    # http://localhost:5020, NODE_ENV=development
npm start                      # node server/index.js
npm test                       # every test/*.test.js on temp PGlite, mocked Network/Search, no internet
npm run test:pg                # the same through PostgreSQL + PgBouncer
npm test -- tickets            # 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 configured)
```

`test/run.js` uses `openvibe-shared/test-runner`, one process per file. There is **no build step**; pages are
server-rendered and static assets are served from [public/](public/).

## Architecture at a Glance

- **Entry:** [server/index.js](server/index.js) — listener, telemetry flush/retention and the Events subscriptions;
  graceful stop is `createLifecycle()` in the same file.
- **App factory:** [server/app.js](server/app.js) — helmet/CSP, SSO, `/auth`, `/internal/events`, static/`/shared`,
  `/api/v1`, discovery + Markdown twins, pages, 404/error handler. Tests call `createApp({ store, fetchImpl, ... })`.
- **Config:** [server/config.js](server/config.js) — `load(env)` is pure; production reads `/etc/openvibe/help.env`.
  Only variable names appear in code/docs.
- **Catalog (no database):** [server/catalog.js](server/catalog.js) reads every product and service manifest from
  `openvibe-contracts` at boot, merges a domain that is both, and generates one article per manifest FAQ entry.
  Nothing is stored; restart to pick up a new Contracts pin. Pages are [server/http/pages.js](server/http/pages.js).
- **Search:** [server/search.js](server/search.js) is the OpenVibe.Search client for network results;
  [server/search-index.js](server/search-index.js) publishes Help's own article pages to Search using
  `openvibe-publishing/search-feed` and the outbox tables `event_outbox` / `help_index_revisions`.
- **Tickets:** [server/tickets/](server/tickets/) (store, pages/routes, staff) — the only personal data Help owns.
  `server/http/api.js` mounts the ticket API; [server/http/principal.js](server/http/principal.js) keeps
  `CAPABILITIES` deliberately empty.
- **Auth/account data:** [server/auth/sso.js](server/auth/sso.js), [server/auth/keys.js](server/auth/keys.js) and
  [server/identity/account-data.js](server/identity/account-data.js).
- **Database:** [server/db.js](server/db.js) — [migrations/](migrations/) at boot with `DATABASE_DIRECT_URL` (owner);
  `DATABASE_URL` serves. Tables: `help_tickets`, `help_messages`, `account_data_events`, `event_outbox`,
  `help_index_revisions`, `telemetry_samples` (plus the Contracts-free `things` fixture table).
- **Frontend:** server-rendered HTML through [server/render/layout.js](server/render/layout.js) and
  [server/render/html.js](server/render/html.js), with the OpenVibe Frame/kit from `openvibe-shared`; assets in
  [public/css/](public/css/). Pages work with JavaScript off. Markdown twins:
  [server/agent-pages.js](server/agent-pages.js), [server/agent-descriptor.js](server/agent-descriptor.js).
- **Deploy:** [deploy/systemd/openvibe-help.service](deploy/systemd/openvibe-help.service) (127.0.0.1:5020,
  `/etc/openvibe/help.env`) and [deploy/nginx/openvibe.help.conf](deploy/nginx/openvibe.help.conf). `sudo ovhost
  deploy help`; database `ov_help`; checkout at `/opt/openvibe.help`; rollback restores the previous sha when
  `/api/ready` fails after the restart.

## Ownership and Boundaries

Help owns support tickets, their messages and the receipts of account-export/deletion events it applied. It does
**not** own accounts, roles or sessions (Network), the help text or manifests (Contracts), the network search index
(Search), event delivery (Events), or the host/database/Valkey (Host). The catalog is derived state: never put it in
a migration or cache it across a Contracts pin. A ticket is private: anyone but its requester gets 404, staff may read
all via their Network role.

## Auth and Capabilities

- A person is the `help_at` session cookie or a Network user token verified offline with the Network JWKS. A
  cookie-authenticated write must be same-origin (`request.cross_site`).
- Staff = Network role `admin` or `global_mod`; no `help.*` capability exists yet. `CAPABILITIES` in
  [server/http/principal.js](server/http/principal.js) is empty on purpose — add a capability here and in
  `openvibe-contracts` together when a route is for an app, never one alone.
- 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 feed.
- Problem codes are RFC 9457 `application/problem+json`: `token.required`, `help.person_required`,
  `request.cross_site`, `staff.forbidden`, `ticket.not_found`, `help.site.not_found`, `ticket.invalid`,
  `rate_limited`.

## API and Pages

Pages: `/`, `/sites`, `/sites/:id`, `/a/:site/:slug`, `/search`, `/tickets`, `/tickets/:id`, `/staff`, `/updates`,
plus discovery (`/llms.txt`, `/sitemap.xml`, `/robots.txt`, `/.well-known/agent.json`) and the Markdown twins.

`/api/v1`: `GET /ping`, `GET /sites`, `GET /sites/:id`, `GET /articles?q=`, `POST /tickets`, `GET /tickets`,
`GET /tickets/:id`, `POST /tickets/:id/messages`, `GET /staff/tickets` (staff), `POST /tickets/:id/state` (staff).
Machine endpoints `/api/health`, `/api/ready`, `/release.json`, `/metrics` are loopback only.

## Conventions

- CommonJS, 4-space indent, single quotes, semicolons; no linter/formatter.
- Route handlers go through [server/http/router.js](server/http/router.js); errors from async handlers must reach the
  error handler. Never log request bodies or ticket bodies.
- IDs are `tkt_`/`msg_` + ULID; reads are explicit field maps, not raw rows.
- New schema = a new `migrations/NNNN_name.sql`; never edit a migration that has run.
- CSP: every external origin belongs in the `helmet` directives in [server/app.js](server/app.js); `frameAncestors`
  stays `'none'`. The kit/Frame come from the named OpenVibe hosts, not arbitrary CDNs.
- Phone first: every answer and ticket page must fit 390 px (and the longest at 320 px) with no horizontal scroll;
  [test/phone-clipping.test.js](test/phone-clipping.test.js) measures this in Chrome.
- Empty states use the shared kit (`class="ovk-empty"` with a next action), not bespoke markup
  ([test/empty-states.test.js](test/empty-states.test.js)).
- "Calm reduces, only Off removes": preferences may de-emphasize, never delete. Never add a hidden removal path.
- No model call belongs in Help: articles are manifest text, not generated copy.

## Key Pitfalls

- **Catalog is rebuilt at boot.** A new site or FAQ is a Contracts change and a pin bump, not an edit here; a stale
  pin means a missing site. Never hand-write an article.
- **Ticket privacy.** `GET /tickets/:id` returns 404 to anyone but the requester (staff excepted); keep that check on
  every new read path. `page_url` is stored as text and never fetched.
- **No build step.** Editing [public/](public/) takes effect on deploy; content hashing adds `?v=`, so never hand-add
  it. `home-short` and `perf-budget` tests fail when first paint or the home's size grows.
- **Account deletion** is loopback-only, signature-verified and idempotent: a redelivered `/internal/events` event
  must change nothing.
- **Drill mode** (`HELP_DRILL`) keeps boot-time timers, outbound calls and subscriptions off; add any new one to it.
- **Markdown twins** are served before page routes so `/a/site/x.md` is a twin, not an article slug; new top-level
  pages must be added to the page router and the sitemap/llms artifacts.
- **`event_outbox` indexing:** the rejected-count query needs the partial index in
  [migrations/0006_outbox_rejected_index.sql](migrations/0006_outbox_rejected_index.sql); do not drop it.
- **No Font Awesome** in new UI; use the shared kit's glyphs.

## Testing

`npm test` runs each `test/*.test.js` in its own process on a temp PGlite database with a mock Network.
[test/tickets.test.js](test/tickets.test.js), [test/help-articles.test.js](test/help-articles.test.js),
[test/help-search.test.js](test/help-search.test.js), [test/search-index.test.js](test/search-index.test.js),
[test/account-data.test.js](test/account-data.test.js), SSO/limits/secret-leak/redirect regressions, layout and
discovery. [test/phone-clipping.test.js](test/phone-clipping.test.js) uses a real Chrome and reports a skip when
Chrome is absent. Run the narrowest file (`npm test -- tickets`), then the suite; `npm run test:pg` for the PostgreSQL
path. Always `node --check` changed files.

## Documentation

- [README.md](README.md) — purpose, ownership, capabilities, what it does, pages, API, configuration, tests, deploy,
  account data, threat notes.
- [STATUS.json](STATUS.json) — stage, deployed state, features and not-yet list.
- [.env.example](.env.example) — every variable name (never commit values).
- [CHANGELOG.md](CHANGELOG.md), [SECURITY.md](SECURITY.md) — releases and vulnerability reporting.