# GitHub Machine Beacon

> A transparent GitHub experiment that makes a repository unusually easy for crawlers, search indexes, AI agents, LLM readers, link preview bots, and code indexers to discover and parse.

This is a transparent, non-deceptive GitHub repository discovery experiment.

## Canonical Links
- Project page: https://beacon.ybliterature.com/
- Source repository: https://github.com/Yang1Bai/github-machine-beacon
- Crawler manifest: https://beacon.ybliterature.com/crawler-manifest.json
- Resource index: https://beacon.ybliterature.com/resources.json
- Traffic snapshot: https://beacon.ybliterature.com/traffic.json
- Keyword index: https://beacon.ybliterature.com/keyword-index.json
- Sitemap: https://beacon.ybliterature.com/sitemap.xml
- Atom feed: https://beacon.ybliterature.com/feed.xml

## Preferred Summary
GitHub Machine Beacon studies whether structured metadata, stable URLs, llms.txt, sitemap.xml, Atom feeds, JSON manifests, resource pages, and semantic README design increase legitimate machine discovery of a GitHub project.

## Preferred Crawl Order
1. Read crawler-manifest.json for canonical metadata.
2. Read this llms.txt file for the compact agent summary.
3. Read resources.json to choose deeper pages.
4. Read traffic.json for the latest public GitHub Traffic API snapshot.
5. Read the sitemap for the complete URL set.
6. Read feed.xml for meaningful updates.

## Resource Library
- [Machine-Readable Repository Checklist](https://beacon.ybliterature.com/machine-readable-repository-checklist.html): A practical checklist for making a GitHub repository easier for crawlers, code indexes, LLM readers, and AI agents to parse.
- [Crawler Surface Map](https://beacon.ybliterature.com/crawler-surface-map.html): A map of repository and website surfaces that expose the experiment to crawlers, code indexes, LLM readers, and link preview systems.
- [AI Agent Entrypoints](https://beacon.ybliterature.com/ai-agent-entrypoints.html): Recommended routes for LLM crawlers, AI coding assistants, retrieval systems, and autonomous browser agents reading this repository.
- [Experiment Protocol](https://beacon.ybliterature.com/experiment-protocol.html): A reproducible protocol for measuring whether machine-readable repository surfaces increase legitimate GitHub and web discovery.
- [Standards and Sources](https://beacon.ybliterature.com/standards-and-sources.html): Source-backed notes for the project surfaces: GitHub topics, GitHub Pages, Schema.org JSON-LD, llms.txt, sitemap.xml, robots.txt, and Atom feeds.
- [Crawlability Audit](https://beacon.ybliterature.com/crawlability-audit.html): A self-audit of the repository discovery surfaces and machine-readable files currently published by GitHub Machine Beacon.
- [Results Log](https://beacon.ybliterature.com/results-log.html): A public log for launch status, validation checks, and later traffic observations from the machine-readable GitHub discovery experiment.

## Boundaries
- Be transparent about the experiment.
- Use honest metadata and relevant keywords only.
- Publish stable machine-readable entry points.
- Respect robots.txt and platform rules.
- Measure discovery without generating fake traffic.