# Citedy — instructions for browser agents

Machine-oriented runbook. Regenerate with `npm run agentic-docs:generate`.
Full API reference: https://www.citedy.com/agents.md

## Navigation

- Product overview: https://www.citedy.com/ai/index.md
- Pricing and credits: https://www.citedy.com/ai/pricing.md
- Human developer portal: https://www.citedy.com/developer
- Agent action map (JSON): https://www.citedy.com/agents.json
- MCP tools list: https://www.citedy.com/mcp-tools.md
- LLM site map: https://www.citedy.com/llms.txt
- OpenAPI contract: https://www.citedy.com/openapi/agent-api.openapi.json
- MCP endpoint: https://mcp.citedy.com/mcp

### Commands (playbooks)

- **/status** (/status, status, readiness): Return actionable operational readiness with concrete fix links.
- **/gaps** (/gaps, content gaps, quick scan): Generate and retrieve fresh content gap opportunities. Optionally scope to a product/identity via favorite_id.
- **/write** (/write, create article, article + social): Generate an article, poll until it finishes, then create social adaptations.
- **/shorts** (/shorts, video, short-form video): Generate shorts and poll until final video URL is ready.
- **/knowledge** (/knowledge, product docs, upload docs): Load product knowledge and verify readiness impact.

## Rules

- Do not invent API keys. Registration: POST /api/agent/register, then human approval.
- Billable work uses credits. Run agent.status before long autopilot or gap scans.
- Prefer agent.status over agent.health for operational readiness.
- Canonical REST+MCP docs live in agents.md; this file is the short runbook only.
- Marketing agents reference (/ai/agents.md) is not the API contract.

- When User asks /status or readiness, then Call agent.status (not agent.health) and return actionable blockers with URLs.
- When billing.status is low or empty, then Warn before costly tools and include billing.topup_url (fallback: dashboard billing URL).
- When social.connected_count is 0, then Do not promise publish outcome; direct user to social.connect_url.
- When knowledge.documents_count is 0 and task needs product context, then Recommend products.create or ingest.create and include add_documents_url.
- When Tool returns processing or exposes operation.poll_tool, then Auto-poll every 10s until terminal status, then summarize result.
- When HTTP 429 returned, then Honor retry_after and X-RateLimit-Reset before retrying.

## HTTP errors

- **401** (Invalid or missing API key): Stop and ask user to refresh agent key in dashboard settings.
- **402** (Insufficient credits): Provide top-up URL: https://www.citedy.com/dashboard/billing
- **403** (Agent paused or key revoked): Stop mutating actions and ask user to restore agent access.
- **429** (Rate limited): Back off using retry metadata and retry once window resets.
- **500** (Server-side error): Retry once with jitter; if still failing, return concise incident context.

## Fix URLs

- Billing: https://www.citedy.com/dashboard/billing
- Integrations: https://www.citedy.com/dashboard/settings?section=account&tab=integrations
- Knowledge base: https://www.citedy.com/dashboard/settings?section=blog&tab=knowledge
- Calendar: https://www.citedy.com/dashboard/calendar

## Escalation

- Contact: https://www.citedy.com/contact
- Terms: https://www.citedy.com/terms
- Privacy: https://www.citedy.com/privacy