AGENTS.md · pollinations/pollinations

Sections

1. App Submission Handling
2. Discord
3. Repository Structure
4. API Gateway
5. Durable Media Requests
6. Coding Principles — Simplicity & Radical YAGNI (CRITICAL)
7. Secret Mutation Safety
8. Cloudflare Production Deployment Safety
9. Tinybird Deployment Safety (CRITICAL)
10. Economics Environment Safety
11. Code Style & Workflow
12. Testing
13. Data-processing documentation maintenance
14. Models & API Changes
15. Workflow Orchestration
16. Compact Instructions
17. Git Workflow
18. Communication Style
19. GitHub Project Manager
20. Contributor Attribution

First lines (shown under the repo's MIT license)

# Agent Guidelines for pollinations.ai

## App Submission Handling

Two-phase review: AI evidence + human decision via `apps-review-submissions.yml`. Source of truth: `operations/app-management/app.json`.

Flow: user opens an `APP-SUBMISSION` issue → AI checks the live app and optional repository → `APP-NEEDS-INFO` or `APP-REVIEW` → maintainer adds `APP-APPROVED` → `apps-publish-submissions.yml` validates the issue again, prepends the app to `operations/app-management/app.json`, and opens an auto-merge PR that closes the issue via `Fixes #NNN`.

`APP-SUBMISSION` is the persistent type label. `APP-NEEDS-INFO`, `APP-REVIEW`, and `APP-APPROVED` describe review state. Quest rewards are detected separately from the merged catalog and are not announced by the submission workflows.

The optional Quest field names an open POLLEN-QUEST issue. The catalog PR then closes that quest too, and the quest check pays the submitter as the co-author of the bot's commit. Approving such a submission also accepts the quest, so check that the app completes it.

New submissions must credit Pollinations with the badge (`packages/ui/src/brand/badge-made-with.svg`) in the README, or on the app page when there is no repository, and upload a 16:9 screenshot (PNG/JPEG/WebP, ≤5 MB, ≥1280×720). Publishing converts it to WebP 1280×720 on `media.pollinations.ai` and sets `screenshotUrl`.

Catalog fields are defined in `operations/app-management/app.js`; categories and platforms in `operations/app-management/ingestion/submission.js`. After manual catalog edits, run `node operations/app-management/app.js validate`.

## Discord

Guild ID `885844321461485618` (https://discord.gg/k9F7SyTgqn) — use for Discord MCP tools.

## Repository Structure

- `enter.pollinations.ai/` — Auth gateway + billing (Cloudflare Worker)
- `gen.pollinations.ai/` — Edge router + image/text generation Worker
- `operations/infrastructure/gpu/` — Image GPU backends, fleet inventory, and deployment tooling
- `pollinations.ai/` — React frontend
- `packages/sdk/` — `@pollinations/sdk` (client + React hooks)
- `packages/mcp/` — shared handlers for the hosted stateless MCP server (see `packages/mcp/AGENTS.md`)
- `shared/` — auth, registry, IP queue; `shared/registry/` holds model registries
- `apps/` — Applications maintained in this repository
- `operations/app-management/` — Community app catalog and automation
- `operations/` — Internal dashboards, monitoring, economics, and infrastructure
- `operations/social/` — Discord/Reddit/GitHub automation
- `operations/community-monitor/` — Community model monitor agent; runs with the Discord bots on the `monitoring-agents` EC2 box (see `operations/infrastructure/gpu/GPU_INSTANCES.md`)

## API Gateway

Primary: `https://gen.pollinations.ai` → routes to `enter.pollinations.ai` for auth/billing.

- Auth: `pk_` (frontend), `sk_` (backend). Keys: https://enter.pollinations.ai/keys
- Billing: Pollen credits ($1 ≈ 1 Pollen). API reference: `APIDOCS.md`; service operations: `.claude/skills/enter-services/SKILL.md`.
- Pack checkout: Stripe. Polar is retired from runtime; do not add Polar SDKs,
  Worker bindings, webhooks, or automated writes. Historical Polar handling
  (pre-Stripe pack revenue, Nov 2025–Jan 2026) lives in the Economics provider
  collection skill (`.claude/skills/economics-provider-collection/`).
- Services: Text (Portkey, multi-provider), Image (gen Worker dispatch to providers/GPU backends), Video (Wan/Veo/LTX), Audio (ElevenLabs, TTM)
- Bill from the usage the provider reports: a usage block, or a billing header
  such as fal's `x-fal-billable-units`. Do not rebuild the provider's price
  formula from request parameters. Derive usage from the request only when the
  provider reports none, and check it against the provider's billing records.
- Successful billable text responses must contain valid provider usage. Reject
  non-stream responses without it; streamed protocols must contain terminal
  usage and fail the stream otherwise.
- Wallet: Pollen is earned by completing Quests; balances live in the `tier_balance` (shown as Quest Pollen) and `pack_balance` (Paid) buckets. The legacy `tier` D1 column and `tier_balance` wire name are kept for compatibility; see `shared/db/better-auth.ts`.
- Referral links must use the canonical landing page with a short `?ref=` value; record analytics behind the page instead of exposing a tracking API as the destination URL.

### Local Development

Run `npm run dev` per service: enter on `3000` (API at `/api/*`), gen on `8788` (including image API tests).

Staging databases are disposable. Migrate, clear, or recreate staging data as needed for the task without repeated confirmation; verify the target is staging first. Production data and secret changes retain their separate approval rules.

Local API test:

```bash
curl "http://localhost:8788/image/test?model=flux" -H "Authorization: Bearer $TOKEN"
curl "http://localhost:8788/v1/chat/completions" -H "Authorization: Bearer $TOKEN" ...
```

## Durable Media Requests

- Media generation uses the durable generation coordinator so callers can
  disconnect and rejoin long-running generations. Add a request-wide deadline
  only when a concrete provider or product contract requires one.
- Prove identical-request disconnect/rejoin, one upstream execution, completed
  R2 cache retrieval, one wallet debit, and one billed Tinybird event.

## Coding Principles — Simplicity & Radical YAGNI (CRITICAL)

- For coding and code reviews, read and use the repo-wide [Ponytail skill](.agents/skills/ponytail/SKILL.md) to look for the smallest correct solution. Its brevity advice does not override explicit requests or this repository's safety, testing, and design-decision requirements.
- Code is debt: implement only what's needed now. Prefer deleting or reusing code over adding it; avoid speculative abstractions, configuration, and helpers.
- Use plain data and small functions. No classes or inheritance; compose functions and keep side effects at the edges where practical.
- Prefer declarative tables, configuration, and data transformations when they make behavior clearer. Keep control flow easy to follow; fewer lines do not justify clever or dense code.
- Keep data flow unidirectional and state ownership explicit. Derive values from their source instead of maintaining synchronized copies.
- Keep modules loosely coupled with focused responsibilities and explicit inputs/outputs. Keep gateways thin; transform requests only where the actual protocol or provider contract requires it.
- Reuse existing patterns and one source of truth. Share genuinely common logic without forcing unrelated cases into a generic framework.
- No legacy compatibility fallbacks or extra runtime guards solely for a brief deployment cutover. Prefer a one-time migration and coordinated consumer updates, then remove obsolete paths.
- Simplification must preserve required behavior. Check real consumers before deleting code; preserve auth, billing, and meaningful model semantics. Judge success by reduced complexity and correctness, not deleted-line counts alone.
- Registry-declared fallback pairs are maintainer-owned; do not add runtime price, compatibility, target availability/privacy, or parameter-normalization guards unless a concrete declared pair requires one.

## Secret Mutation Safety

**CRITICAL — never mutate a secret without the user's separate, explicit, scoped approval.**

- A secret mutation changes secret material or its lifecycle: creating, replacing, rotating, revoking, or regenerating a credential, token, API key, certificate, GitHub secret, provider secret, or encrypted SOPS value.
- Re-uploading unchanged encrypted values through an existing reviewed deployment workflow is routine deployment, not rotation, and needs no separate secret approval. This exception applies only when the user requested the deployment and the diff changes neither the secret source, mapping, target environment, nor upload command.
- Before any mutation, stop and state the exact secret name (never its value), environments, reason, expected impact, execution order, verification, and rollback.
- Require a new approval in the current conversation after presenting that plan. General instructions such as “go ahead,” “fix it,” “deploy,” “continue,” or approval for the surrounding model/task work do not count.
- For a first-time secret addition, require: `Yes, you can add <SECRET_NAME> to <ENVIRONMENTS> now.`
- For replacing an existing secret, require: `Yes, you can rotate <SECRET_NAME> in <ENVIRONMENTS> now.`
- Approval is valid only for the named secret, environments, and one described operation. Never reuse or broaden it.
- Do not edit a secret file, change provider/GitHub secret state, or open or push a secret-change PR before receiving that approval.
- If exposure is suspected, report it immediately and stop. Do not revoke or rotate until the explicit approval is received.
- Read-only inspection may continue, but never print, echo, log, or otherwise expose secret values.
- Never synchronize production secrets from an unmerged commit or a branch other than `production`.
- For rotation, add and verify the replacement first, merge the encrypted update, deploy from `production`, run live tests for every affected service, and only then revoke the previous credential.

## Cloudflare Production Deployment Safety

**CRITICAL — production Cloudflare deployments must always run through GitHub Actions:**

- Use the production deployment workflow `Deploy / Cloudflare production`; use `workflow_dispatch` (and its `service` input to target one worker) when path filters do not trigger it.
- Dispatch production workflows only from the `production` branch. Select a secret-synchronization input only after the Secret Mutation Safety approval gate.
- Never run `wrangler deploy --env production`, a production deployment npm script, or a direct production Worker upload from a local machine or agent session.
- If CI credentials lack a required permission, follow the Secret Mutation Safety approval gate before updating the scoped GitHub Actions secret and rerunning the workflow. Never bypass CI with a local Cloudflare OAuth session.
- After the workflow succeeds, verify the active Worker version and required bindings before testing production traffic.

## Tinybird Deployment Safety (CRITICAL)

- Two workspaces: `pollinations_enter` (prod) and `pollinations_enter_staging` (staging + dev + local). Pipes and datasources must be deployed to **both** — no CI auto-deploy yet, tracked in #11127.
- Use the Tinybird **Forward CLI** as `tb` (not Classic) from `enter.pollinations.ai/observability`, always with `--cloud` (otherwise it hits Tinybird Local/Docker).
- Do not rely on `.tinyb` for workspace selection. Always pass an explicit workspace-scoped `TB_TOKEN` with `WORKSPACE:DEPLOY` and `--host https://api.europe-west2.gcp.tinybird.co`; never source deploy credentials from Enter runtime secrets.
- Always validate and deploy to **staging first**, verify, then prod only when requested.
- Validate first: `tb --cloud --host "$TB_HOST" deployment create --check --no-allow-destructive-operations`
- Deploy staging: `tb --cloud --host "$TB_HOST" deployment create --wait --no-allow-destructive-operations`
- Verify staging: `tb --staging --cloud --host "$TB_HOST" endpoint ls` and `tb --cloud --host "$TB_HOST" deployment ls`
- Never `tb push` (deprecated). Avoid `tb deploy`; use explicit `deployment create` commands so promotion is never accidental.
- Intentional staging migrations/resets within the task may use `--allow-destructive-operations` without further confirmation. Production destructive operations, `--auto`, and `deployment promote` require explicit permission.
- Verify all consumers within a workspace before modifying a pipe (pipes are NOT cross-workspace; each workspace has its own copy)
- Investigate datasource or pipe deletions reported by validation. Restore accidentally missing definitions; intentional staging deletions follow the disposable-data rule above. Ask before deleting production resources.
- Forward materialized views cannot use `UNION`; split sources into separate materialized pipes writing to the same datasource.
- Timeouts: use `uniq()` not `uniqExact()`; avoid CTE+JOIN; single-pass queries; for large time ranges use `start_date` parameter week-by-week
- Full procedure: `.claude/skills/tinybird-deploy/SKILL.md`

## Economics Environment Safety

- `operations/economics/web` local development must read Tinybird staging
  (`pollinations_enter_staging`) through
  `operations/economics/secrets/web.dev.json`.
- Production Economics deployments read
  `operations/economics/secrets/web.json`. Never decrypt that production file
  directly into the local `.dev.vars` file.
- After switching, merging, or rebasing an Economics branch, rerun
  `npm run decrypt-vars` before trusting the local dashboard. The generated
  `.dev.vars` must preserve the separately approved app session signing secret
  and load the staging-only read token via `scripts/write-dev-vars.mjs`.
- A local dashboard showing production-only or stale provider rows is an
  environment-routing failure; fix the local reader before changing ledger
  data or publishing another correction.

## Code Style & Workflow

- Modern JS/TS, ES modules (all `.js` are ESM). Follow existing formatting. Comment complex logic.
- Run `npx @biomejs/biome check --write <file>` after edits and before commits. It runs the repo's own Biome once `npm ci` has installed it; a bare `npx biome` can run an unrelated npm package.
- Before implementing or resuming work: read the latest accepted decision and current code, verify API assumptions on the web, and check related PRs/issues. Before reviving old work, check its discussion, close reason, and remaining user-visible gap; an absent feature alone is not evidence that it is needed.
- Reuse existing logic: search `shared/` for auth, queue, registry, SSE parsing, and retry utilities before writing new ones.
- Use environment variables for credentials; validate input.
- When adding a React browser/IIFE bundle, grep bundled dependencies'
  published dist for `react/jsx-runtime` and `react-dom` imports before
  choosing shim vs external; transitive deps such as `@ark-ui/react` Portal can