openvibers/openvibe.meme AGENTS.md

AGENTS.md

main 11.6 KB · 154 lines · markdown

Raw HistoryBlame Repository
1# AGENTS.md — OpenVibe.Meme
2
3## Project Overview
4
5OpenVibe.Meme is an open encyclopedia of internet memes and a maker attached to each entry. Every public entry cites
6where it started and how it spread, connects variations/related memes, and is a Search document. Members propose and
7edit entries (staff review revisions), vote in the weekly candidate list, make and render captions, analyse a meme,
8start a cited deep-dive, and generate a researched caption picture. AI is used through OpenVibe.AI; every judgement,
9usage cap and citation rule is in the code, not in a prompt alone.
10
11- **Domain:** `openvibe.meme` · **Port:** 5120 · **Service id:** `meme` · **Env prefix:** `MEME`
12- **Runtime:** Node 22, Express 4, PostgreSQL 18 through `openvibe-sdk/db` (PGlite in development/tests), Valkey
13 optional, `sharp` and ffmpeg for rendering, `openvibe-shared` for the shell.
14- **Read first:** [README.md](README.md), [STATUS.json](STATUS.json), [.env.example](.env.example).
15
16**Network context:** identity, roles and JWKS are OpenVibe.Network (OAuth client `meme`; staff is `global_mod` or
17above). Chat, Live and Video are **public reads only** (`server/upstreams.js`, `server/reddit-read.js`): Meme never
18reads a private VOD and never cites VOD **5709** or clip **483** (the fixed deny list in
19[server/deny-list.js](server/deny-list.js)). AI is OpenVibe.AI (`ai.generate`, `ai.run.create`) — never a provider
20directly. Wikipedia/Wikidata/Commons are paced, cached, attributed reads. Search documents wait in `meme_outbox` and
21are delivered by `openvibe-publishing/search-relay`. Events are OpenVibe.Events.
22
23## Commands
24
25```bash
26npm ci # install (contracts/sdk/shared pinned by tag)
27npm run dev # http://localhost:5120, PGlite under data/
28npm start # node server/index.js
29npm test # every test/*.test.js on temp PGlite, mocked Network/AI/upstreams
30npm run test:pg # the same through PostgreSQL + PgBouncer
31npm test -- judge # only test files whose name contains the word
32npm test -- --strict # a skipped test fails the run
33node --check <file.js> # syntax check (no linter configured)
34```
35
36No build step: server-rendered pages plus plain JS/CSS in [public/](public/) and local SVG placeholders in
37[public/img/](public/img/). Rendering of captions/pictures is server-side (`sharp`, `server/render-png.js`).
38
39## Architecture at a Glance
40
41- **Entry:** [server/index.js](server/index.js) — listener, telemetry, the importer and citation re-verifier, judge
42 job and Events subscriptions; graceful stop. `MEME_DRILL` keeps boot-time work off; tests drive `runOnce()`.
43- **App factory:** [server/app.js](server/app.js) — CSP, SSO, `/auth`, `/internal/events`, `/shared`+static, `/api/v1`,
44 discovery/agent twins, pages, 404/error handler.
45- **Config:** [server/config.js](server/config.js) — `load(env)` is pure; production `/etc/openvibe/meme.env`.
46- **Store/schema:** [server/store.js](server/store.js) and [migrations/](migrations/). Core tables: `meme_entries`,
47 `meme_citations`, `meme_judgements`, `meme_status_events`, `meme_origins`, `meme_spread_points`,
48 `meme_variations`, `meme_examples`, `meme_entry_related`, `meme_entry_revisions`, `meme_entry_redirects`,
49 `meme_votes`, `meme_templates`, `meme_captions`, `meme_reports`, `meme_reddit_*`, `meme_analyses`,
50 `meme_research`, `meme_deep_dives`, `meme_*_usage`, `meme_outbox`, `event_outbox`, `account_data_events`,
51 `telemetry_samples`.
52- **AI and rules:** [server/ai/](server/ai/) (`client.js`, `judge.js`, `gate.js`, `context.js`), [server/ai.js](server/ai.js),
53 [server/generate-ai.js](server/generate-ai.js), [server/research-ai.js](server/research-ai.js), [server/person-cap.js](server/person-cap.js),
54 [server/deny-list.js](server/deny-list.js), [server/text/no-looks.js](server/text/no-looks.js).
55- **Content jobs:** [server/importer.js](server/importer.js), [server/classics/](server/classics/) (`seed.js`,
56 `sources.js`), [server/trends.js](server/trends.js),
57 [server/reddit.js](server/reddit.js), [server/reverify.js](server/reverify.js), [server/research.js](server/research.js),
58 [server/analyze.js](server/analyze.js), [server/generate.js](server/generate.js), [server/pics-maker.js](server/pics-maker.js).
59- **HTTP:** [server/http/api.js](server/http/api.js), [server/http/pages.js](server/http/pages.js),
60 [server/http/principal.js](server/http/principal.js), [server/http/discovery.js](server/http/discovery.js),
61 [server/http/router.js](server/http/router.js). Views: [server/views/](server/views/).
62- **Auth/account data:** [server/auth/sso.js](server/auth/sso.js), [server/auth/keys.js](server/auth/keys.js),
63 [server/identity/account-data.js](server/identity/account-data.js), [server/identity/staff.js](server/identity/staff.js).
64- **Frontend:** [server/render/layout.js](server/render/layout.js), [server/render/html.js](server/render/html.js),
65 [server/render-png.js](server/render-png.js), [server/render/video.js](server/render/video.js); assets
66 [public/css/meme.css](public/css/meme.css), [public/js/meme.js](public/js/meme.js). Pages work without JavaScript.
67- **Deploy:** [deploy/systemd/openvibe-meme.service](deploy/systemd/openvibe-meme.service) (`/etc/openvibe/meme.env`,
68 `/opt/openvibe.meme`) and [deploy/nginx/openvibe.meme.conf](deploy/nginx/openvibe.meme.conf). `sudo ovhost deploy
69 meme`; database `ov_meme`; rollback on a failed `/api/ready`.
70
71## Ownership and Boundaries
72
73Meme owns entries, citations, judgements, status events, origins/spread/variations/examples/related, revisions and
74redirects, votes, templates/captions, reports, Reddit observations, analyses, research/deep dives, usage counters and
75the Search outbox. It is **not** the authority for Chat/Live/Video content (public reads only), accounts/roles
76(Network), AI runs (OpenVibe.AI), Search (documents in its outbox), event delivery (Events), or the host/database
77(Host). A hidden proposal is 404 unless its author or staff; a merged entry's old slug answers 301.
78
79## Auth and Capabilities
80
81- A person is the `meme_at` cookie or a Network user token, verified offline; a cookie write must come from
82 `https://openvibe.meme` (`meme.cross_site`). Per-actor limits: `MEME_LIMITS_MINUTE`, `MEME_LIMITS_HOUR`.
83- Staff = Network `global_mod` or above; staff proposals/revisions apply immediately, members' wait for review.
84- The one outbound service grant is OpenVibe.AI `ai.run.create` with a client-credentials token (`svc:meme`); never
85 name a provider — AI's routing decides and the run reports what answered.
86- Outbound also: `events.subscription.manage`, `search.document.write`, and `identity.subject.resolve` where needed.
87- AI budget is both per-day global and per-person (`meme_person_usage`; staff not counted). A refused call is 429
88 `meme.ai_budget`, unavailable AI 503 `meme.ai_unavailable`, unavailable Media 503 `meme.media_unavailable`.
89- Errors are RFC 9457 problem+json with stable `meme.*` codes.
90
91## API (JSON under `/api/v1`)
92
93Public: `GET /entries`, `GET /memes`, `GET /memes/:slug`, `GET /entries/:slug`, `/entries/:slug/revisions`,
94`/entries/:slug/series`, `/entries/:slug/deep-dive`, `GET /week`, `GET /trending`, `GET /trends`, `GET /templates`,
95`POST /caption-ideas`, `POST /render`, `GET /captions/:id[/render]`.
96Signed in: `POST /entries`, `POST /entries/:slug/revisions`, `POST /week/vote`, `POST /research`, `GET /research/:id`,
97`POST /research/:id/entry`, `POST /templates/uploads`, `POST /generate`, `POST /captions`,
98`POST /entries/:slug/report`. Staff: `/moderation/revisions`, `/staff/templates/uploads`,
99`POST /staff/templates/:id/review`, `/reports`, `/staff/candidates[/:slug]`, `POST /entries/:slug/publish|hide`,
100`PATCH /entries/:slug`, `POST /entries/:slug/revisions/:revision/review`. Machine endpoints `/api/health`,
101`/api/ready`, `/release.json`, `/metrics` are loopback only.
102
103## Conventions
104
105- CommonJS, 4-space indent, single quotes, semicolons; no linter/formatter. Async handlers through the router.
106- IDs are `mem_`/`mcp_`/`mrp_`/`anl_`/`rsc_` + ULID; slugs are unique and title-normalised (`title_key`, lowercase,
107 punctuation stripped, whitespace collapsed, unique per kind for public rows).
108- New schema = a new `migrations/NNNN_name.sql`; never edit one that has run.
109- Citations are verbatim with a canonical URL and an `observed_at`; re-verification marks `live|hidden|gone`, and a
110 hidden/gone origin blocks publishing with 409 `meme.origin_gone`. Never invent a citation or a source URL.
111- CSP: add every external origin to `helmet` in [server/app.js](server/app.js); Media images come from the named
112 `openvibe.media` host, not arbitrary CDNs.
113- **People may be described** (owner, 2026-10-31): the old looks filter is off; summaries may describe appearance.
114 What stays gated is sex acts/porn (the explicit gate) and the deny list. Do not reintroduce `noLooks`.
115- Phone first: `/`, `/m/:slug`, `/week`, `/make`, `/c/:id` must fit 390 px with no horizontal scroll.
116- "Calm reduces, only Off removes": hide/visibility reduces what is shown; only the explicit hide/delete path removes.
117- No Font Awesome; use `openvibe-shared` glyphs. Empty states use the shared kit.
118- Do not hand-write an entry as if AI/judge did; proposals, revisions and staff review are the only paths.
119
120## Key Pitfalls
121
122- **Deny list is fixed:** VOD 5709 and clip 483 (and denied words/sources in [server/deny-list.js](server/deny-list.js))
123 must never be cited, summarised or used as an example. [test/deny-list.test.js](test/deny-list.test.js) enforces it.
124- **Citations:** each entry has one origin citation plus later uses; the quote is verbatim and the canonical VOD offset
125 is seconds. The open web (Wikipedia/Wikidata/Commons) is a source too. A dead origin cannot be published.
126- **Classics:** a documented classic publishes on score + written text + a clean deny list; it needs no example uses
127 and is not held for describing people, but a low score, denied source or missing text still hides it
128 ([server/ai/gate.js](server/ai/gate.js), [test/classic-gate.test.js](test/classic-gate.test.js)).
129- **AI budget:** global and per-person caps are reserved before the call (`server/person-cap.js`); a retry must not
130 double-count. AI output is validated against the entry's sources before storage.
131- **Maker rendering:** safe editor geometry is persisted (`meme_captions.editor_state`, ≤8 KB); uploaded templates are
132 `pending` until staff review; the renderer must never fetch an arbitrary user URL (image loading uses the guarded
133 fetch in [server/fetch-image.js](server/fetch-image.js)).
134- **Search outbox:** public entries are documents; hiding tombstones them. The relay is off without `MEME_SEARCH_URL`
135 and documents wait — that is expected.
136- **Drill mode** (`MEME_DRILL`) keeps the importer, re-verifier, judge job and subscriptions off; add new timers there.
137- **Account deletion** erases personal rows and anonymizes public contributions through `/internal/events`; a
138 redelivery changes nothing.
139
140## Testing
141
142`npm test` runs each file in its own process on temp PGlite with mock Network/AI/upstreams: judge/gate/deny-list,
143encyclopedia/classics, citations/reverify, trends/Reddit, analyse/research/generate, captions/templates/pics maker,
144votes/week, staff revisions, search relay, SSO, pages, agent layer, real-content-first, contrast and migration.
145`npm run test:pg` for PostgreSQL. Run the narrowest file first, then the suite; always `node --check` changed files.
146
147## Documentation
148
149- [README.md](README.md) — entries/judge/encyclopedia/trends/analyse/deep dives/generator/importer/citations/Search/
150 pages/run/test/deploy.
151- [STATUS.json](STATUS.json) — stage, deployed flag, features and not-yet list.
152- [.env.example](.env.example) — variable names only.
153- [CHANGELOG.md](CHANGELOG.md), [SECURITY.md](SECURITY.md).
154