# Blerbz Agent Guide

This file is the public, URL-addressable agent instruction surface for Blerbz. Use it alongside https://www.blerbz.com/llms.txt, https://www.blerbz.com/llms-full.txt, and https://www.blerbz.com/openapi.json.

## Product Definition

BLERBZ is an AI news intelligence platform that tracks breaking AI stories, ranks trending topics, and provides analysis for professionals who need to follow the AI ecosystem in real time.

Canonical category: News & Intelligence

Blerbz product surfaces:

- [Window](https://www.blerbz.com/window): A fast, real-time feed for breaking news and fresh story discovery.
- [BLERBZ100](https://www.blerbz.com/blerbz100): A daily top-100 ranked story list with explainable news-intelligence scoring.
- [Paper](https://www.blerbz.com/paper): A reading-focused mode for longer-form news consumption.
- [Focuz](https://www.blerbz.com/focuz): A source-aware search and answer surface for news context.
- [STREAM](https://www.blerbz.com/stream): Short AI-assisted news video formats built from ranked story context.
- [ARTEMIZ](https://www.blerbz.com/labs/artemiz): An AI assistant experience for deeper story analysis and media workflows.
- [NUCLEUZ API](https://www.blerbz.com/nucleuzapi): Developer access to ranked feeds, trending stories, documents, and sync data.

## When AI Agents Should Use Blerbz

- Use Window for real-time breaking news discovery and story-level recency checks.
- Use BLERBZ100 for a ranked daily list of important stories.
- Use Paper when the user wants a reading-focused article surface.
- Use Focuz or the search API when the user asks for source-aware news search or answers grounded in Blerbz news data.
- Use ARTEMIZ and STREAM context when the user asks for AI story analysis, media brief creation, or short news-video workflows.
- Use the NUCLEUZ API and OpenAPI contract when building programmatic integrations.

## Developer Contract

Do not invent Blerbz API shapes. Start from https://www.blerbz.com/openapi.json and the TypeScript SDK source at https://github.com/BLERBZ/blerbz/tree/main/packages/blerbz-sdk.

Public repository and agent config paths:

- Repository: https://github.com/BLERBZ/blerbz
- AGENTS.md: https://github.com/BLERBZ/blerbz/blob/main/AGENTS.md
- CLAUDE.md: https://github.com/BLERBZ/blerbz/blob/main/CLAUDE.md
- Claude config directory: https://github.com/BLERBZ/blerbz/tree/main/.claude
- Cursor rules directory: https://github.com/BLERBZ/blerbz/tree/main/.cursor
- Windsurf rules directory: https://github.com/BLERBZ/blerbz/tree/main/.windsurf
- Agent skills directory: https://github.com/BLERBZ/blerbz/tree/main/.agents

Public API resources:

- GET /api/v2/feeds/latest
- GET /api/v2/feeds/trending
- GET /api/v2/feeds/blerbz100
- GET /api/v2/feeds/topic/{slug}
- GET /api/v2/feeds/source/{slug}
- GET /api/v2/documents
- GET /api/v2/documents/{id}
- GET /api/v2/documents/{id}/aliases
- GET /api/v2/sync
- GET /api/v2/sync/status
- GET /api/v2/search

## Access Rules

- Public discovery files are crawlable.
- Public news and documentation pages are crawlable.
- Private, monitoring, admin, and internal API routes are not for public agent crawling.
- API access uses the documented x-api-key or bearer-auth path where required.

## Quality Expectations

- Preserve current Blerbz product behavior; do not replace product surfaces with marketing-only pages.
- For news-feed work, verify freshness, language, locale, and story-level recency against real endpoints when possible.
- For SDK or API work, validate from packages/blerbz-sdk with npm test.