devnet: README with source table and ceilings

README.md

@@ -1,30 +1,77 @@
 ---
-title: LeadGen
-emoji: 🎯
+title: devnet
+emoji: 🛰️
 colorFrom: blue
-colorTo: blue
+colorTo: gray
 sdk: docker
-app_port: 7860
+pinned: false
+license: mit
 ---
 
-# LeadGen
+# devnet — developer internet for AI agents
 
-Find people actively asking for solutions like yours.
+One interface to the places builders use: **PyPI, GitHub, Hacker News, and any RSS/Atom feed**.
 
-## Tech Stack
+The point is not access — an agent already has `curl`. The point is **ground truth instead of
+guessing**: exact versions, yanked releases, real issue threads, searchable discussions.
 
-- Frontend: HTML/CSS/JS
-- Backend: Python (FastAPI) — coming soon
-- Database: Supabase (PostgreSQL)
-- AI: Jev AI (classification + scoring)
+## Interfaces
 
-## Project Structure
+| | |
+|---|---|
+| MCP | `https://lljz66-api.hf.space/mcp` |
+| REST | `https://lljz66-api.hf.space/v1/...` |
+| Health | `https://lljz66-api.hf.space/health` |
+| OpenAPI | `https://lljz66-api.hf.space/docs` |
 
+## Tools
+
+| tool | answers |
+|---|---|
+| `pypi_package(name)` | current version, deps, yanked releases, release history |
+| `github_repository(owner, name)` | stars, language, license, topics, last push |
+| `github_issues(owner, name, state?, limit?)` | real issue threads (PRs filtered out) |
+| `hackernews_search(query, limit?, kind?)` | what builders are actually saying |
+| `rss_read(url, limit?)` | any engineering blog, changelog or AI-lab feed |
+
+The join is the product: `pypi_package("httpx")` + `github_issues(...)` + `hackernews_search(...)`
+answers *"why is this package broken at this version?"* in one round trip.
+
+## Source status
+
+| source | auth | rate limit | cost | commercial | verified |
+|---|---|---|---|---|---|
+| PyPI JSON | none | undocumented, be gentle | free | metadata is public | ⚠️ unverified |
+| GitHub REST | optional token | 60/hr anon, 5000/hr token | free | GitHub API ToS, attribution | ⚠️ unverified |
+| HN (Algolia) | none | generous | free | public API, no restriction | ⚠️ unverified |
+| RSS | none | per publisher | free | **inherits each publisher's terms** | ⚠️ unverified |
+
+⚠️ Nothing here has been executed yet. `smoke.py` must pass before launch, and the license/terms
+column must be re-verified against each vendor's current terms. This table is not legal advice.
+
+## Configuration
+
+| env | effect |
+|---|---|
+| `GITHUB_TOKEN` | optional, raises GitHub from 60 to 5000 req/hr |
+| `DEVNET_KEYS` | comma/space separated keys for the `X-Key` header |
+| `DEVNET_OPEN=1` | disable the key check (demo only) |
+
+With no `DEVNET_KEYS` set the service is open, which is fine for a smoke test and unsafe in public.
+
+## Check it
+
+```bash
+PYTHONPATH=src python smoke.py
 ```
-/
-├── frontend/              # Static HTML/CSS/JS
-│   └── index.html         # URL input page
-├── backend/               # Backend folder (ready for use)
-├── Dockerfile             # Python HTTP server on port 7860
-└── README.md              # This file
-```
+
+## Deliberate ceilings
+
+| simplification | ceiling | upgrade |
+|---|---|---|
+| in-process TTL cache | one container, lost on restart | Redis |
+| one shared `X-Key` | cannot rotate per customer | DB-backed keys |
+| sync `requests` | fine to low thousands req/min | `httpx` async |
+| no database | no history, no quota accounting | SQLite/Postgres |
+| RSS 2.0 + Atom only | no RSS 1.0/RDF, no podcast enclosures | branch per real feed |
+| no GitHub search tool | repo/issues only | add when an agent needs it |