# Pubfuse — canonical context for AI agents & developers

> When code and docs disagree, treat the files below as intent.
> Portal: https://www.pubfuse.com/developer · API reference: https://www.pubfuse.com/docs

## Codex / Cursor / any AI with the GitHub repo

**Prefer the checked-in folders** (source of truth — no mirror lag):

- `.cursor/agents/` — team subagents (Fedel, Marco, Jenny, …)
- `.cursor/skills/` — domain skills (`*/SKILL.md` + `references/`)
- `.agents/skills/` — workflow skills (impeccable, brainstorming, …)
- `docs/TEAM_ROSTER.md` — personas and how to invoke each agent
- `docs/specs/E35-authoritative-dev-ai-docs/domain-model.md`
- `docs/specs/E35-authoritative-dev-ai-docs/system-architecture.md`
- `web/public/openapi.yaml` (same as `/openapi.yaml` on the site)

You do **not** need `/ai/` if you already have the repo. `/ai/` is a **published copy** for website-only AIs.

After editing agents/skills, maintainers run `npm run publish-ai` so `web/public/ai/` stays identical; CI fails on drift.

## Website-only AIs (no repo clone)

Fetch these URLs:

1. https://www.pubfuse.com/llms.txt (this file)
2. https://www.pubfuse.com/ai/index.md — agents + skills index (mirror of `.cursor/`)
3. https://www.pubfuse.com/ai/manifest.json — machine-readable URL list
4. https://www.pubfuse.com/ai/TEAM_ROSTER.md
5. https://www.pubfuse.com/openapi.yaml — REST API (Redoc UI at /docs)
6. https://www.pubfuse.com/developer — human + AI portal hub

## Canonical source-of-truth (repo paths)

- docs/specs/E35-authoritative-dev-ai-docs/domain-model.md — Canonical entities: User · Creator · Project · Track · Playlist · Radio · gifts
- docs/specs/E35-authoritative-dev-ai-docs/system-architecture.md — runtime components + system overview flowchart
- docs/specs/E41-marketplace-app-factory/contract.md — App Factory scores CRUD + registry provision
- docs/specs/E41-marketplace-app-factory/README.md — Factory thesis, phases, ops console
- docs/specs/E43-marketplace-intelligence-ai-native/README.md — Marketplace Intelligence + AI-native sites (Wave A + Phase 1)
- docs/specs/E43-marketplace-intelligence-ai-native/api-contracts/scoring.md — Admin scoring / opportunities API
- docs/specs/E43-marketplace-intelligence-ai-native/api-contracts/ai-manifest.md — Site AI-manifest + capabilities + readiness
- docs/specs/E43-marketplace-intelligence-ai-native/api-contracts/ai-package-and-telemetry.md — Telemetry ingest + AI-package retrofit
- command-center/data/architecture.js — Command Center architecture ledger (keep in sync with system-architecture.md)
- web/public/openapi.yaml — REST API contract · ~99% route coverage · admin/planning marked x-internal
- docs/specs/E35-authoritative-dev-ai-docs/docs-maintenance.md — Living-docs process
- `.cursor/agents/` + `.cursor/skills/` — **SoT**; mirrored to `web/public/ai/` for the public site

## Cursor agents & skills

| Path | Audience |
|------|----------|
| `.cursor/agents/*.md` | Codex / Cursor with repo |
| `.cursor/skills/<name>/SKILL.md` | Codex / Cursor with repo |
| https://www.pubfuse.com/ai/agents/*.md | Website-only AIs |
| https://www.pubfuse.com/ai/skills/<name>/SKILL.md | Website-only AIs |

Recommended: pick a persona from the roster, open the matching agent file, then follow its skill.

## Key entry points

- /developer — Portal hub (five pillars + inline domain model & architecture + AI pack links)
- /docs — Redoc API reference (x-internal operations excluded from public view)
- /features — Shipped feature matrix
- /sdk-docs — iOS / Android / web SDK quickstarts
- /app/ai/playground — AI Platform playground (auth required)
- /postman/Pubfuse-AI-Platform.postman_collection.json — Postman collection
- /postman/Pubfuse-AI-Platform.postman_environment.json — Postman environment

## AI stack (three surfaces) — portal /developer#ai-stack

Go REST is the **only** public AI boundary. Never call RunPod / workers / weight URLs from a client.
Full character + voice guide: https://www.pubfuse.com/ai/skills/pubfuse-ai-character-platform/SKILL.md
Video guide: https://www.pubfuse.com/ai/skills/pubfuse-ai-video-studio/SKILL.md
LTX LoRA likeness/request guide: https://www.pubfuse.com/ai/skills/ltx-lora-request-contract/SKILL.md

### Models (public IDs)

Text (E29) — GET /api/ai/v1/models · /capabilities:
- pubfuse-llama-8b — general prose (chat, marketing, lyrics, video_script, social_planning, creator_assistant, real_estate)
- pubfuse-qwen-coder-7b — code_assistant
- pubfuse-llama-guard-8b — stream_moderation
- gemini-flash-fallback — Phase 0 primary / vLLM fallback
- pubfuse-bge-embed · pubfuse-whisper-turbo — reference until gateway v2

Video (E39) — GET /api/ai/video-generation-capabilities (defaultModelId + models[]):
- ltx-2.3 (LTX) — default live · video + optional audio · family ltx
- wan-2.2 (Wan) — silent video · Live when models[] row enabled:true · family wan

Voice (E52):
- qwen3-tts — Voice Studio design/clone infer · live GPU gated by AI_VIDEO_TTS_ENABLED (default off → plan_only)

### AI Platform text (E29)

Playground: /app/ai/playground (auth).
POST /api/ai/v1/capabilities/{id}/run · POST /api/ai/v1/chat/completions
Use outputs as prompt / script.dialogue for Studio — do not invent video modes.

### AI Video Studio (E39) — generate video programmatically

Self-hosted LTX + Wan. **Clients call the Pubfuse API only**; GPU providers/workers/secrets stay backend.

Flow: capabilities → ensure prepaid credit balance (buy a pack if short) → create → poll → resolve outputUrl → play / use-as-clip.

Endpoints (Bearer JWT + X-App-Id):
- GET  /api/ai/video-generation-capabilities — defaultModelId, models[], modes, durations, pricing[] (authoritative), etaByDuration[], aspectRatios, enabled/killSwitch
- POST /api/ai/video-generations — create (reserves credits; idempotencyKey); requires rightsAttested:true; optional E52 cast/voice/script
- GET  /api/ai/video-generations/{id} — poll status/stage/progress/etaSeconds/outputUrl
- POST /api/ai/video-generations/{id}/cancel|retry|use-as-clip
- GET  /api/ai/video-credits/packs (public) · GET /balance · GET /ledger · POST /checkout · POST /iap/apple|/iap/google

Rules:
1. Never compute credit cost — read pricing[] from the selected models[] row (mode × durationSeconds).
2. Credits are prepaid + hard-gated: create returns 402 AI_VIDEO_INSUFFICIENT_CREDITS (required/available) before any GPU dispatch. Buy a pack first.
3. Pricing is COGS-aware: retail ≥ 2× GPU COGS (≥50% gross margin). See docs/specs/E39-ai-video-studio/credits-cost.md.
4. outputUrl may be relative (/api/files/{id}/public); resolve against the API base URL before playback (served same-origin 200, not a redirect).
5. Only send params the selected model row allowlists (else AI_VIDEO_PARAM_NOT_ALLOWED). quality does not change price today.
6. Only use a mode from the selected row — text_to_video, image_to_video, image_to_promo (when advertised). image_to_video needs inputImageFileId; image_to_promo needs musicTrackId or audioFileId.
7. Never call a provider/worker/RunPod directly; the provider-callback route is worker→API (HMAC) only.
8. Read capabilities.aspectRatios — never hardcode ratios. Preserve intrinsic aspect in playback.

### AI Influencers / Characters / Voice Studio (E52)

Portal: https://www.pubfuse.com/developer#ai-start (alias /documentation → /developer) · #ai-stack
Consumer overview: docs/AI-INFLUENCERS.md → docs/specs/E52-ai-character-influencer-platform/consumer-overview.md
Agent skill: /ai/skills/pubfuse-ai-character-platform/SKILL.md
LTX LoRA request contract: /ai/skills/ltx-lora-request-contract/SKILL.md

Flow: create → lock training set (images ± short video) → train → Quality Lab (human) → publish → AccessGrant → cast.
Ready ≠ client-castable until publish. Mental model: look (LoRA) ≠ voice ≠ published influencer.
For character modes, `prompt` is visual scene direction and `script.dialogue` is the exact speech. Do not mix them.

What we have (admin UI /pubfuse-admin/ai-influencers/*):
- Characters · Readiness (drag-drop stills + MP4/WebM/MOV; Save as next training set) · Training (+ push on complete/fail)
- Quality Lab (per-job samples; placeholder auto-scores; retrain if prompts lack pfchr… trigger)
- Versions publish/rollback · Voices · App access (multi-app grants) · Content Lab · Usage

Catalog (JWT + X-App-Id) — factory apps display:
- GET /api/ai/characters · /api/ai/characters/{id}
- GET /api/ai/influencers · /api/ai/influencers/{id}
- GET /api/ai/voices · /api/ai/voices/{id} (?ready=true)
- List/detail include displayName, shortBio, thumbnailFileId, profileImageUrl (/api/files/{id}/public)
- Character detail also has description (same as bio). Admin sets profile via thumbnailFileId upload.

Cast on video create (optional, omit → E39-only):
- characterId or cast[{characterId,voiceId?,characterVersionId?}] · voiceId · script.dialogue · voiceEnabled (+1 credit when configured)
- Phase A/B kinds only: internal_influencer | fictional
- Never send client artifactIds; LoRA family must match selected modelId family (LTX ≠ Wan)
- Inference attach gated by AI_CHARACTER_INFER_CHARACTER_ATTACH_ENABLED (default off → AI_CHARACTER_ATTACH_DISABLED)
- LTX likeness triage: owner debug JSON should show `characterAttach.resolved: true`, `workerBody.character`, and redacted `workerBody.cast[].artifacts[]`; `workerBody.mode: "text_to_video"` alone is normal for LTX internals.

Admin API /api/pubfuse-admin/ai:
- Characters CRUD · datasets · train → approve → publish · AccessGrant mint
- Voices: POST /characters/{id}/voices — authorized_clone requires sampleFileId + Consent voice.attach
- Infer: POST /voices/design-infer · /voices/clone-infer · /voices/{voiceId}/infer (qwen3-tts; plan_only until TTS gate on)

Identity binding: train captions + eval prompts share pfchr… trigger (TrainingCaptionForItem / RenderEvalPromptText).
Pre-trigger jobs render strangers — retrain; do not approve.

Specs: docs/specs/E52-ai-character-influencer-platform/ · contracts catalog.md · admin-characters.md · generation.md · voice-tts-inference.md

## Domain rules (must hold)

1. A User can own many Creators/Artists.
2. A Creator ≠ User — it stores Projects and never logs in.
3. Project → Tracks (albums hold tracks).
4. A Playlist is owned by a User but may curate cross-user Projects/Tracks.
5. Uploading a Track without a Project auto-creates a default Creator + default Project.
6. Users receive gifts and social reactions.
7. A Radio station is triggered by attaching a Playlist as its source.

## Identity & tenancy

Send X-App-Id (app_ids.id UUID) and optional X-SDK-Client-Id on REST calls.
Mismatch vs the JWT user's users.app_id → 403 APP_ID_MISMATCH.
See docs/APP-CLIENT-IDENTITY.md.

## Marketplace App Factory (E41)

Ops: https://www.pubfuse.com/pubfuse-admin/app-factory (super-admin) — Add/Edit/Delete opportunity ideas, Approve → Create registry app, provision jobs.
Admin API: GET/POST/PATCH/DELETE /api/admin/marketplace/opportunity-scores; POST …/approve|reject; POST /api/admin/marketplace/apps (opportunityScoreId must be approved).
Pubfuse = users/login/billing/AI control plane. Each vertical app = private GitHub repo + Cloudflare host; optional app-owned database for product services. Config: pubfuse-app.json + .env.example (never secrets).
Specs: docs/specs/E41-marketplace-app-factory/ · Command Center architecture.js · /developer portal.

## Marketplace Intelligence + AI-native sites (E43)

Wave A (AI package + telemetry) and Phase 1 scoring/manifest APIs are live on beta. Blueprint APIs (T-700) in progress.

Scoring (admin JWT): /api/admin/marketplace/intelligence/* — opportunities, score, evidence, score-models.
  Contract: docs/specs/E43-marketplace-intelligence-ai-native/api-contracts/scoring.md

AI-manifest (public): GET /api/sites/{siteId}/ai-manifest · /capabilities · /skills
AI-manifest (admin): /api/admin/sites/{siteId}/ai-manifest · readiness · capabilities · skills · evaluate
  Contract: docs/specs/E43-marketplace-intelligence-ai-native/api-contracts/ai-manifest.md

Telemetry (JWT + X-App-Id, enrolled apps): POST /api/telemetry/events · /api/telemetry/events/batch
Admin: GET /api/admin/marketplace/apps/{id}/telemetry/summary; POST …/retrofit-ai-package (single + bulk)
  Contract: docs/specs/E43-marketplace-intelligence-ai-native/api-contracts/ai-package-and-telemetry.md
  Ops: docs/specs/E43-marketplace-intelligence-ai-native/ops-retrofit-ai-package.md

Epic: docs/specs/E43-marketplace-intelligence-ai-native/README.md

## Last verified

2026-07-26