Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (55 loc) · 3.89 KB

AGENTS.md

File metadata and controls

79 lines (55 loc) · 3.89 KB
Raw

AGENTS.md: blockchains.github.io

Instructions for AI coding agents (Grok, Cursor, Claude Code, Codex, Copilot and others) working in this repo or using it as a building block. Humans: see README.md.

What this is

Blockchain Lab Hub: static GitHub Pages site with 75 free services (AI briefs via Grok, gas/RPC/chain monitors, finders, feeds), machine-readable services.json, health data, and the org-wide llms.txt and blocks.json catalogue.

Setup

pip install -q playwright && python -m playwright install chromium

Build and test

python scripts/gen_site.py && git diff --exit-code -- '*.html' sitemap.xml robots.txt
python tests/validate.py
python tests/serve.py 43117 & sleep 2; BASE=http://127.0.0.1:43117 python tests/e2e.py
GH_TOKEN=$(gh auth token) python scripts/blocks.py   # rebuild blocks.json, llms.txt, llms-full.txt from every repo's blocks.json + AGENTS.md (token optional)

Tests hit live public networks/APIs (the org rule is no mocks). A failure can be an upstream outage: re-run before changing code.

Structure

Path What
scripts/gen_site.py generates every page + sitemap/robots
scripts/job_*.py scheduled data jobs (daily, gas, rpc, health, ai…)
scripts/blocks.py aggregates blocks.json, llms.txt and llms-full.txt; /blocks/ page is in gen_site.py
services.json service catalogue
data/ published data
llms.txt, llms-full.txt, blocks.json org-wide AI entry points, generated by scripts/blocks.py (not this repo's own manifest)
blocks/hub.json this repo's own block manifest
blocks/index.html human-readable blocks catalogue (generated by gen_site.py, renders /blocks.json)
tests/ validate.py, e2e.py, serve.py

Conventions

  • Pages are generated by scripts/gen_site.py; commit regenerated HTML.
  • No servers, no trackers; everything is static + scheduled Actions.

Extension points

  • New service: page in gen_site.py, entry in services.json, a check in tests/e2e.py (the hub test expects the card count to match).
  • New repo block: add blocks.json to that repo, then run python scripts/blocks.py.

Do

  • Run the e2e locally after changing pages.

Don't

  • Hand-edit generated pages.
  • Invent data, mock network responses in shipped code, or hard-code values that should come from the live source; every repo here is 'no mocks, real data'.
  • Commit secrets, keys or .env files. Run gitleaks before pushing; CI and the org policy reject leaks.

Using it from another project

  • services.json (http): catalogue of every service with id, name, url, category
  • blocks.json (http): aggregated blocks.json of every live Blockchains repo
  • llms.txt (http): org-wide doc map for LLMs (+ llms-full.txt)
  • data/*.json (http): gas.json, liveness.json, rpc-latency.json, incidents.json, events.json, jobs.json, grants.json, depeg.json, status.json, ai/*.json
  • feeds (http): incident RSS + /events/events.ics

See the README section Use as a building block for a copy-paste example.

Related blocks