# 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 — 14 runtime components + system overview flowchart
- 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

## 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.

## Last verified

2026-07-11