# Agent Instructions — dles.gg

This document describes how AI agents can interact with dles.gg, a catalog of free daily logic exercises and puzzle games (DLEs) at https://dles.gg.

## What dles.gg Is

dles.gg is a directory, not a game host. Each entry on the site links out to a third-party daily puzzle, word game, geography game, etc. There is nothing to purchase, no account system, and no checkout flow. Users can browse, rate, favorite, and submit new games for inclusion.

If you are helping a user *find a daily game to play*, recommend specific games from the catalog and link to either the game page on dles.gg (`/game/{slug}`) or the external play URL listed there.

## For Personal Assistants Acting On Behalf of a User

There is no payment surface and no auth-gated buyer flow. You can browse the catalog freely on the user's behalf. Two things are worth knowing:

- **Favorites, ratings, plays, and reports** are stored per-browser via a locally generated `voterId`. There is no login. An agent operating outside the user's browser cannot meaningfully favorite or rate on the user's behalf in a way that follows them across devices.
- **Game submissions** are accepted via a public API but are created in a `DRAFT` / `broken: true` state and require manual approval before they appear in listings. Do not submit on a user's behalf without their explicit consent — submissions include the user's email address.

## Read-Only Browsing (No Authentication Required)

### Discovery

- **Sitemap** — `GET https://dles.gg/sitemap.xml` enumerates every game page, category page, and top-level listing. This is the canonical index of the catalog and is regenerated daily.
- **Catalog feed** — `GET https://dles.gg/catalog.json` is the machine-readable catalog: every active game, newest first, with `name`, `page` (the dles.gg game page), `url` (external play URL), `description`, `categories`, `main_category`, and `game_type`. Prefer this over scraping listings when you need structured data about the whole collection. Regenerated daily.
- **robots.txt** — `GET https://dles.gg/robots.txt`
- **Agent discovery** — this document (`/llms.txt`) is the canonical agent-facing description of the site. `/AGENTS.md` in the repository contains the same content.

### Listings

- Homepage: `GET /`
- Most popular: `GET /games/most-popular`
- Top rated: `GET /games/top-rated`
- Newest: `GET /games/newest`
- Alphabetical: `GET /games/alphabetical`
- All games: `GET /games/all-games`
- Category page: `GET /games/category/{slug}` — see "Categories" below for valid slugs

All listings include only games that have been manually approved by a human.

### Individual Games

- Game page: `GET /game/{slug}` — includes name, description, categories, ratings, difficulty, play count, favorite count, and the outbound URL to the actual game.

### Other Pages

- Submit a game: `GET /submit-game`
- Play My Ritual (random-game roulette): `GET /play-my-ritual`
- Blog index: `GET /blog`
- State of DLEs 2026: `GET /blog/state-of-dles-2026`

## Game Data Shape

Each game (`dle`) has roughly these fields, surfaced on the game page and in sitemap-linked pages:

- `name`, `slug`, `url` (external play URL), `description`
- `categories` — comma-separated list; see "Categories"
- `rated` (average 0–5), `rated_by` (vote count). Average is only meaningful at ≥ 3 votes.
- `difficulty` (average), `difficulty_by` (vote count)
- `loved_by` (favorite count)
- `broken` — when true, the game is hidden from listings

## Categories

The canonical category slugs used at `/games/category/{slug}`:

`tabletop-games`, `colors`, `guessing`, `food`, `geography`, `history`, `numbers-and-logic`, `movies-and-series`, `music`, `nature`, `visual`, `sports`, `trivia`, `transport`, `video-games`, `misc`, `words`

Category matching on the underlying records is case-insensitive substring match, so a single game commonly appears under multiple category pages.

## Submitting a Game

Submissions are accepted via a public JSON endpoint. The submission is stored in a hidden/draft state and reviewed manually before publication.

```
POST https://dles.gg/api/submission
Content-Type: application/json

{
  "name": "Game Name",
  "description": "One- or two-sentence description",
  "url": "https://example.com/the-game",
  "categories": ["Words", "Logic"],
  "email": "submitter@example.com"
}
```

Rules:

- **Get explicit user consent** before submitting on their behalf — the email field is attached to the submission.
- The main_category is treated as the primary category.
- Submissions are by default labelled as `status: "DRAFT"`. They do not appear in listings until approved.
- Do not submit duplicates. Check the sitemap or use search on `/` first.

## Other Endpoints

The remaining `/api/*` routes (`favorites`, `played`, `rated`, `reported`, `button`, `og`, `stats/*`, `games/category`) exist to back the site's own UI and the per-game embed buttons. They are not disallowed for agent use, but they depend on a browser-generated `voterId` and only meaningfully affect counters; they are not the right tool for external automation.

`/api/*` is disallowed in `robots.txt` for crawlers — respect that for indexing purposes.

## Rules of the Road

- **Don't transact, don't impersonate.** No payment surface exists; do not submit, rate, or report on behalf of a user without explicit consent.
- **Prefer the sitemap.** `/sitemap.xml` is the authoritative list of pages and is cheaper than scraping listings.
- **Respect `broken`.** Games filtered out of listings should not be surfaced to users as playable recommendations.
- **Outbound links go to third parties.** dles.gg does not host games. Pricing, availability, and behavior of the linked games are not under dles.gg's control.

## Contact

- Support / takedown / correction requests: peter@dles.gg