X Algorithm Explained

A bilingual, source-grounded visual guide to the X “For You” recommendation system.

Русская версия README

Website: lemelson.github.io/x-algorithm-explained

X Algorithm Explained turns the public xai-org/x-algorithm repository into an interactive English/Russian walkthrough. It covers candidate retrieval, filtering, Phoenix action prediction, weighted scoring, ranking adjustments, diversity, cold-start eligibility, and final visibility checks.

What is inside

• A step-by-step journey from viewer context to a ranked feed.
• Source-linked explanations of in-network and out-of-network retrieval.
• An interactive probability × coefficient calculator.
• Author diversity, network-distance, cold-start, and DPP visualizations.
• A practical growth playbook that separates code-backed facts from editorial guidance.
• A technical quiz with explanations and links to the pinned source.
• Statically rendered English and Russian URLs.

Evidence boundary

The explainer is pinned to upstream snapshot a389166. It does not claim access to private production parameters, current experiments, anti-abuse systems, or a guaranteed impressions formula.

Coefficient ratios are comparisons at equal predicted probability—not exchange rates between real actions. The visible follower ranges (0–100, 101–500, 501–1,000, and 1,001+) are editorial planning bands, not ranking thresholds.

Run and verify locally

Requires Node.js 22.13 or newer.

npm ci
npm run dev

Before submitting a change:

npm run verify
npm run build:github-pages
node --test tests/github-pages-build.test.mjs
git diff --check

Deployment

The workflow in .github/workflows/deploy-pages.yml verifies the project, creates a static artifact, and deploys main through the official GitHub Pages Actions flow. The repository setting Pages → Build and deployment → Source must be GitHub Actions.

The canonical URL, project URL, source snapshot, author, and review date live in site.config.json. After changing them, regenerate and check the discovery files:

npm run metadata:sync
npm run metadata:check

Search and agent discovery

The deployed artifact includes:

• robots.txt with explicit allow rules for ordinary crawlers, OAI-SearchBot, and GPTBot.
• A bilingual sitemap.xml with reciprocal hreflang entries.
• Canonical links, language alternates, Open Graph and Twitter Card metadata.
• Article, WebSite, and SoftwareSourceCode structured data.
• llms.txt, llms-full.txt, and index.md as optional agent-readable summaries.
• site.webmanifest, humans.txt, and an optimized 1200×630 social image.

llms.txt is an emerging convention, not a guarantee that an AI system will index or cite the site.

GitHub project Pages cannot set the origin-level https://lemelson.github.io/robots.txt; the repository can only publish its own file under /x-algorithm-explained/robots.txt. Crawlers normally request the origin-level file, and a missing root file generally means crawling is not restricted. The page-level robots metadata, sitemap, canonical URLs, and language alternates remain effective discovery signals.

Google Search Console and Yandex Webmaster verification tokens are intentionally not committed. After publication, the site owner can verify the property and submit:

https://lemelson.github.io/x-algorithm-explained/sitemap.xml

Project map

app/                    pages, metadata, structured data, and interactive UI
public/                 crawler, agent, manifest, and social assets
scripts/                deterministic discovery-file and Pages preparation tools
tests/                  server-rendered and static-artifact checks
.github/workflows/      GitHub Pages deployment
site.config.json        canonical project and source metadata

Open source

This is an independent educational project and is not affiliated with or endorsed by X Corp. Contributions are welcome; see CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md. The project is licensed under the MIT License.