# AGENTS.md

> This file is the machine-readable manifest for this beacon.
> Fetch it with: curl http://localhost:3700/

## Identity

name: beacon
owner: Adam Calisto (GitHub: Ig0tU / HuggingFace: acecalisto3)
version: 1.0.0
base_url: https://acecalisto3-beacon.hf.space
auth: owner-session (Chrome profile clone or live CDP bridge)

---

## What this is

A personal authenticated web proxy.  
The owner has signed into sites once, in their real browser.  
This beacon carries those sessions and serves any page the owner can see —  
as clean text, structured JSON, or RSS — callable by anyone or any agent.

Think of it as a live RSS ticker that works on any URL on the web.

---

## Endpoints

### GET /
Returns this file (AGENTS.md). Machine-readable capability discovery.

### GET /raw?url=<url>
Returns clean readable text extracted from any URL.
Uses Mozilla Readability (same engine as Firefox Reader View).
Content-Type: text/plain

Example:
  curl "http://localhost:3700/raw?url=https://example.com/paywalled-article"

### GET /json?url=<url>
Returns structured article data as JSON.
Fields: url, title, byline, siteName, excerpt, content, publishedTime, length
Content-Type: application/json

Example:
  curl "http://localhost:3700/json?url=https://example.com" | jq .title

### GET /feed?url=<url>
Returns RSS 2.0 feed generated from any URL.
Article pages → single item feed.
Link-list pages (HN, Reddit, news sites) → feed of all significant links.
Content-Type: application/rss+xml

Example:
  curl "http://localhost:3700/feed?url=https://news.ycombinator.com" > hn.rss

### GET /screenshot?url=<url>
Returns PNG screenshot of any URL.
Content-Type: image/png

Example:
  curl "http://localhost:3700/screenshot?url=https://example.com" > shot.png

### POST /session/:name
Saves the current authenticated browser context for a named site.
Use this after logging into a site via your real Chrome (CDP bridge mode).
Returns: { saved: "<path to snapshot JSON>" }

Example:
  curl -X POST "http://localhost:3700/session/wsj"

### GET /agents.md
Returns this file. Standard curlyCue spec path.

### GET /spaces/:owner/:name/agents.md
curlyCue — AGENTS.md for any HuggingFace Space.
Resolution: native → Gradio schema → HF metadata → pre-populated library.

  curl https://acecalisto3-beacon.hf.space/spaces/black-forest-labs/FLUX.1-schnell/agents.md
  curl https://acecalisto3-beacon.hf.space/spaces/acecalisto3/urld/agents.md

### GET /datasets/:owner/:name/agents.md
curlyCue for HuggingFace datasets — schema, splits, and flash-to-agent curl commands.

  curl https://acecalisto3-beacon.hf.space/datasets/wikipedia/20220301.en/agents.md

### GET /health
Returns: { status: "ok", ts: <unix ms>, port: 7860 }

---

## Session strategy

Priority order at startup:
1. CDP bridge — connects to your already-running Chrome (all sessions live)
   To enable: open -a "Google Chrome" --args --remote-debugging-port=9222
2. Profile clone — loads your Chrome profile from sessions/chrome-profile/
   To sync: cd beacon && npm run sync-profile
3. Fresh browser — no sessions, will be anonymous on paywalled sites

---

## Agent integration (skip-agent / any LLM agent)

Add these tools to your agent:

  fetch_web  → GET /raw?url=<url>       returns page text
  fetch_rss  → GET /feed?url=<url>      returns RSS XML
  fetch_json → GET /json?url=<url>      returns article JSON

Set BEACON_URL env var to point to this server.
Default: http://localhost:3700

---

## AGENTS.md spec (draft v0.1)

This file format is a proposal for agent-first sites.
Instead of robots.txt (what to hide), AGENTS.md declares what to serve.

Conventions:
- Serve AGENTS.md at GET /
- Endpoints described in ## Endpoints section
- Auth method declared under ## Identity
- Content-Type hints per endpoint

Sites adopting this pattern become curl-callable APIs
without writing a single line of custom API code.