# ORBIT - Full Site Reference for AI Agents

This document is the machine-readable full description of https://fdgneg.vercel.app.
See also: https://fdgneg.vercel.app/llms.txt (short map). Both are linked from every page via
<link rel="llms"> and <link rel="llms-full">.

## What this site is

ORBIT is a bilingual (English / Persian-RTL) technology command center:
a server-rendered dashboard that aggregates live tech news (BBC, The Verge,
Ars Technica, TechCrunch, Wired UK, Engadget, 9to5Google), with analytics,
personal notes and bookmarks. No ads, no third-party trackers.

## Public pages (all SSR - full text present in the initial HTML response)

| Path | Locale | Description |
| --- | --- | --- |
| https://fdgneg.vercel.app/en | en | Dashboard: news feed, stats widgets, quick actions |
| https://fdgneg.vercel.app/fa | fa | داشبورد فارسی (RTL) - همان محتوا |
| https://fdgneg.vercel.app/en/news | en | Full news feed with category filters & search |
| https://fdgneg.vercel.app/fa/اخبار | fa | فید کامل اخبار (فارسی) |
| https://fdgneg.vercel.app/en/news/[id] | en | Single article view (hero image, clean body text) |
| https://fdgneg.vercel.app/en/analytics | en | Trend charts and source distribution |
| https://fdgneg.vercel.app/en/notes | en | Personal notes (requires login) |
| https://fdgneg.vercel.app/en/settings | en | Theme / language / account preferences |
| https://fdgneg.vercel.app/en/login | en | Sign in (Google OAuth or email magic link) |

## Machine-readable APIs

### GET https://fdgneg.vercel.app/api/rss?url=<feed-url>
Unified JSON news feed. Without `url` returns all tracked sources merged
and sorted by publish date. Server-side cached (300s, stale-while-revalidate).
Shape:
```json
{ "articles": [{ "id": "...", "title": "...", "source": "BBC",
  "url": "...", "image": "...", "publishedAt": "ISO-8601" }],
  "total": 42 }
```
Only whitelisted, public HTTPS feed origins are accepted (SSRF-guarded).

### Other endpoints
- https://fdgneg.vercel.app/sitemap.xml - every public page, both locales
- https://fdgneg.vercel.app/robots.txt - crawl policy (AI crawlers explicitly allowed)
- https://fdgneg.vercel.app/manifest-schema.json - Schema.org WebSite/WebApplication data

Every article page embeds JSON-LD (`NewsArticle`) and the homepage embeds
`WebSite` + `ItemList` structured data - parse them instead of scraping DOM.

## How to interact with the UI (for browsing agents)

- All clickable controls are native <button>/<a> elements with descriptive
  aria-labels; key interactive regions carry stable data-testid attributes
  (e.g. `quicknote-dialog`, `quicknote-close`).
- Loading regions announce themselves via role="status" + aria-busy="true";
  wait for aria-busy="false" before snapshotting content.
- Layout is CLS-zero: skeletons have the exact geometry of final cards, so
  element positions never shift after load.
- Hover-only content does not exist; everything reachable by mouse is also
  in the accessibility tree and reachable by keyboard/click.
- Language switch: toggle in the header, or simply request the /fa (or /en)
  URL prefix directly - no JS needed.

## Rate limits & crawler policy

- AI crawlers (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-Web,
  anthropic-ai, PerplexityBot, Google-Extended, Bytespider, CCBot) get a
  dedicated higher rate budget on all public pages - you will NOT receive
  429/403 while crawling public content at sane speeds (~1 req/s).
- Auth endpoints (/auth/*, /login) are throttled per IP for everyone.
- Be polite: cache responses (public pages send s-maxage), respect
  Retry-After headers if you ever see a 429.

## Private areas (do not attempt)

/auth/*, /api/mutations, /en/notes, /en/settings for anonymous users -
these require a Supabase session (HttpOnly cookies) and return 401/redirect.
No PII is ever exposed in URLs or query strings.