# Portal Nexus

## What is Portal Nexus?
Portal Nexus is a single login for game creation — access multiple models to generate assets, spritesheets, voice, music, NPC dialogue, and more without managing multiple provider accounts. One credit balance covers smart routing, MCP agent connections, and usage analytics. Tagline: Create assets for your games.

## Products & Features
- Tool catalog: Browse 25+ AI game-dev tools (2D, 3D, voice, music, NPC, code).
- Smart routing: Choose cheapest, best, or fastest provider per request.
- Unified billing: One credit balance across all providers; no markup on provider rates.
- MCP hub: Local MCP server for Cursor and agents (`@gamerouter/mcp`).
- Playground / Create Assets: Prompt dock overlay routes to /create for generation preview; /preview shows recent generated assets; /prompts has example prompts (legacy /templates redirects here).
- Dashboard: API keys, jobs, Connect (MCP agents), credits, usage, analytics, and project settings.
- Docs: Quickstart, API reference, engine guides (Godot, Unity), MCP architecture.
- Guides: Browse tools → generate assets → connect agents → ship via MCP → manage projects at /guides.
- Portal Studio (sibling app): https://studio.portalgaming.com — visual agent workspace in the Portal ecosystem.

## Who We Serve
- Solo and indie game developers
- Small studios integrating AI into production pipelines
- Agent builders wiring game-dev tools via MCP
- Engine plugin and tooling authors

## Key Pages
- Homepage: https://nexus.portalgaming.com/
- App landing (Discover): https://nexus.portalgaming.com/discover — default signed-in and Hub iframe landing. `/home` and Hub iframe `/` redirect here.
- Guides: https://nexus.portalgaming.com/guides
- Contact: https://nexus.portalgaming.com/contact
- Tools (redirects to Discover): https://nexus.portalgaming.com/tools
- Create: https://nexus.portalgaming.com/create
- Preview: https://nexus.portalgaming.com/preview
- Prompts: https://nexus.portalgaming.com/prompts
- Templates (redirects to Prompts): https://nexus.portalgaming.com/templates
- Connect: https://nexus.portalgaming.com/dashboard/connect
- Projects: https://nexus.portalgaming.com/projects
- Search: https://nexus.portalgaming.com/search
- Pricing: https://nexus.portalgaming.com/pricing
- Dashboard: https://nexus.portalgaming.com/dashboard
- For AI Agents: https://nexus.portalgaming.com/for-agents
- Open Graph preview: https://nexus.portalgaming.com/nexus-opengraph.png?v=20260810b
- Robots: https://nexus.portalgaming.com/robots.txt
- Sitemap: https://nexus.portalgaming.com/sitemap.xml

## User Authentication
- Portal Nexus and Portal Studio share one AIR Account (MOCA AIR Kit).
- Sign in via Log in on the welcome page or header — opens the AIR Kit login popup directly.
- After AIR login, `POST /api/auth/bootstrap` provisions a stable per-user API key and credit balance in Supabase.
- Session storage key: `PORTAL_AIR_SESSION` (localStorage, ~50 min TTL).
- User API key storage key: `gamerouter_api_key` (localStorage) — same key works in Studio bridge and MCP.
- Server JWT verification: `GET /api/auth/me` with `Authorization: Bearer <air_access_token>`.
- User-scoped data in Supabase: `portal_users`, `portal_api_keys`, `portal_credit_balances`, `portal_recent_tools`, plus `project_folders` / `project_assets` keyed by API key hash.

## API Overview
- Base path: `/api/v1/`
- Auth: `Authorization: Bearer <api_key>`
- Endpoints: `/generate/2d`, `/generate/3d`, `/generate/image`, `/generate/voice`, `/generate/music`, `/npc/chat`, `/tools`, `/engines`, `/projects`, `/projects/folders`, `/projects/assets`, `/credits`, `/usage`, `/mcp/connect`, `/mcp/execute`
- MCP package: `packages/gamerouter-mcp` — stdio MCP calling Portal Nexus HTTP routes with `GAMEROUTER_API_KEY` (includes project folder list/save tools)

## Technology & Integrations
- Next.js App Router, TypeScript, Tailwind CSS, shadcn/ui
- Supabase (Postgres + RLS), AIR Kit auth (shared with Portal Studio), Stripe billing (planned/production rollout)
- Supported engine references: Godot, Unity, Unreal, GB Studio, Web/Phaser
- Provider references: PixelLab, Meshy, ElevenLabs, Suno, Inworld, Fal.ai, and others in the tool catalog

## Frequently Asked Questions
Q: What does Portal Nexus do?
A: Portal Nexus routes game-development AI requests to the best provider, bills from one credit balance, and exposes tools through REST and MCP.

Q: How is billing handled?
A: Developers purchase credits. Platform fee applies on credit purchase; underlying provider rates are not marked up.

Q: Does Portal Nexus run MCP on its servers?
A: MCP processes run locally on the developer machine. HTTP API calls use your Portal Nexus API key for generation and billing.

Q: Is there information for AI agents?
A: Yes. See /for-agents and /llms.txt for structured, crawlable summaries.