Vice City Hub 🌴 — v12 "Open to Agents"
The GTA VI fan hub for humans and AI agents. Neon UI for people, MCP + REST + llms.txt + safe auto-buy for machines.
Live: https://vicecityhub.github.io/vicecityhub · Agent docs: /llms.txt · Agent console: /agents.html
What v12 adds
| Layer | What | Where |
|---|
| Agent API (REST) | catalog, news, RP data, search, quotes, orders, intents | supabase/functions/agent-api/ |
| MCP server | 17 tools, stateless streamable-HTTP | …/agent-api/mcp |
| Discovery | llms.txt, llms-full.txt, .well-known/{agent.json,mcp.json,api-catalog,ai-plugin.json,security.txt}, openapi.json | generated → public/ |
| Static feeds | data/{news,catalog,rp-*}.json + manifest data/index.json | generated → public/data/ |
| Per-page SEO/agent markup | <link> hints, one JSON-LD @graph, <noscript> content | vite-plugins/agent-surface.ts |
| Agent purchases | price-locked quotes → idempotent orders → PayPal or on-chain stablecoin, human-set spend mandates | orders.ts, verify.ts, owner.ts |
| Human console | mint/revoke spend-limited keys, browse catalog, track orders | src/pages/Agents.tsx |
Humans keep the full neon UI (React SPA per page). Nothing was removed from the human experience.
Single source of truth
site.config.json — name, URLs, page list (titles, descriptions, priorities, feeds). The generator, the Vite plugin, llms.txt, the sitemap and all JSON-LD read from it. Add a page → add one entry there.
Build pipeline
npm run build
├─ prebuild scripts/gen-agent-surface.mjs live API → public/{llms*.txt, openapi.json, sitemap.xml, .well-known/*, data/*}
├─ tsc -b
└─ vite build (agentSurface plugin injects discovery links + JSON-LD + <noscript> into every HTML entry)
The generator never fails a build: if the API is unreachable it keeps the previous files (--strict to fail instead).
CI (.github/workflows/deploy.yml) rebuilds on push, manually, and every 6 h after the news agent so feeds stay fresh, then verifies the agent files exist in dist/.
Project map
site.config.json ← edit pages/URLs here
vite-plugins/agent-surface.ts
scripts/
gen-agent-surface.mjs ← llms.txt, .well-known, feeds, sitemap
test-agent-api.mjs ← 30-check safe smoke test (never moves money)
news-agent.mjs ← scheduled news ingestion
selftest-verify.mjs ← on-chain verifier self-test
public/ ← robots.txt + generated agent files (committed so Pages works even if generation fails)
src/{pages,components,lib,rp-hub}
supabase/functions/{agent-api,paypal-checkout,printful-hub,link-preview,…}
docs/legacy/ ← old one-off notes/scripts (kept, not used)
Agent purchase protocol (short)
POST /v1/agents/register → key ($100/order, $250/day) — or a human mints a bigger mandate in the console.POST /v1/quotes → price locked 15 min.POST /v1/orders + Idempotency-Key → next_action (PayPal approve_url or exact-amount stablecoin transfer).- Crypto (no PayPal, fully automatic): send exactly
amount_due in USDT/USDC. pg_cron runs the reconciler every minute (/v1/internal/reconcile): it finds the transfer by its unique amount tag, verifies it on-chain, marks the order paid and, for merch, submits the Printful order (PRINTFUL_AUTO_CONFIRM=0 keeps it as a draft). Failed Printful calls are retried by the reconciler. payment-proof is an optional shortcut. PayPal: capture → GET /v1/orders/{id}/status until paid.
Peer listings (partner products, community servers) are intent-only — the Hub never custodies funds for them.
Develop
npm ci
npm run dev # Vite
npm run gen:agent # regenerate agent surface
npm run typecheck
npm run test:agent # smoke-test the live Agent API
npm run build
Deploy the edge function: npx supabase functions deploy agent-api --no-verify-jwt --use-api
Known platform limits (GitHub Pages project site)
robots.txt, llms.txt and /.well-known/* are served under /vicecityhub/, not at the host root. Crawlers and some agents look at https://vicecityhub.github.io/robots.txt (root). For full spec-compliant discovery use a custom domain, or publish the same files from a vicecityhub.github.io user-site repo. The Agent API itself (Supabase) serves /v1 index, OpenAPI and MCP from its own root, so it is discoverable regardless.
