# CollabLists
> Community-curated directory of best-in-class things for every topic. Public lists are readable by anyone (including agents) over REST and MCP; writes today go through Better Auth sessions.

## Documentation
- [Agent brief](/AGENTS.md): auth model, endpoints, MCP, CLI, conventions
- [Well-known manifest](/.well-known/collablists.json): machine-readable bootstrap
- [Repo](https://github.com/tmad4000/collablists): source of truth — Next.js + Drizzle + Postgres RLS + Better Auth

## API (read + anonymous create)
- Base: https://collablists.globalbr.ai
- **Public agent key (always-published):** `cl_pub_agent_2026_v1` — send as `Authorization: Bearer cl_pub_agent_2026_v1`. Scope: read any public list, anonymously create items on public-edit lists (must include `reporter` field).
- **Personal keys:** mint at `/settings/api-keys` after signing in.
- Auth: Better Auth session cookie for owner-only writes; anonymous reads of `public` / `public-edit` lists need no auth (Postgres RLS enforces visibility).
- Endpoints (current):
  - `GET /api/lists?public=true` — public list index
  - `GET /api/lists` — owner + shared + public, RLS-scoped (requires session)
  - `POST /api/lists` — create a list (requires session)
  - `GET /api/lists/<id>` — one list, RLS-scoped
  - `GET /api/lists/<id>/items` — items for one list
  - `GET /api/list/<id>/events` — SSE realtime change stream
  - `GET /api/list/<id>/presence` — presence/typing
  - `GET /api/link-preview?url=...` — OpenGraph preview helper
  - `POST /api/frontend-log` — browser error forwarding
- OpenAPI: not yet published. Tracked in beads ticket `collablists12-25-j7t`.
- Write API for items (add, edit, reorder, star, comment) currently lives in authenticated React server actions, not REST. Full agent-write parity is in progress.

## MCP
- Server: `src/scripts/mcp-server.ts` (stdio) — `npm run mcp` or `npx tsx src/scripts/mcp-server.ts`
- Full read+write surface (collablists12-25-v4f).
- Read tools: `search_lists`, `list_lists`, `get_list`, `search`, `list_items`, `get_item`, `list_my_lists`, `browse_url`.
- Write tools (require per-user `api_key` via tool arg or `COLLABLISTS_API_KEY` env): `create_list`, `create_item`, `update_item`, `update_list`, `star_item`, `unstar_item`, `delete_item`.
- Auth: api_key resolves against `session.token`; calls run inside `withUserDb` so Postgres RLS gates exactly as if the user made the call. Public agent key `cl_pub_agent_2026_v1` works for reads only.
- Docs: `docs/mcp-server.md` in the repo.

## CLI
- `src/scripts/cli.ts` — local agent CLI; also `npm run cli` and `cli.sh` at the repo root.

## Web surfaces
- `/` — home / list browser
- `/list/<id>` — list detail view (per-item commentary, stars, comments, provenance)
- `/login` — Better Auth magic-link sign-in
- `/AGENTS.md` — agent brief
- `/llms.txt` — this file
- `/.well-known/collablists.json` — machine-readable manifest
- `/robots.txt` — explicitly allows major LLM/agent crawlers

## For agents
- Prefer existing lists over creating parallel ones. Search first.
- Set `source_url` and `source_note` when an item came from a URL — that's the taste signal.
- Respect visibility: `private` / `unlisted` lists are invisible to anonymous callers by design.
- Anonymous-create IS supported on public-edit lists — see public agent key above. Include a `reporter` attribution.