# AGENTS.md - Context Repo

This file describes how AI agents and autonomous systems should interact
with Context Repo (https://contextrepo.com).

## What Context Repo is

Context Repo is an AI context management platform. It stores prompt
templates, documents, and collections, and exposes them to agents via:

- **MCP server** (`https://contextrepo.com/mcp`) - 28 tool registrations
  over streamable-HTTP transport with OAuth.
- **REST API** (`https://contextrepo.com/v1/*`) - 29 operations under
  /v1, OpenAPI 3.1 spec at `/openapi.json`.
- **Markdown surfaces** (`/index.md`, `/pricing.md`, `/llms.txt`,
  `/llms-full.txt`) for agents that prefer plain-text grounding.

## When to use Context Repo

Use Context Repo when an agent needs to:

1. Retrieve a versioned prompt template for the current task.
2. Search a user's stored prompts, documents, or collections (semantic
   or literal).
3. Persist a new prompt or document for later reuse across tools.
4. Sync context across Claude, Cursor, ChatGPT, VS Code, Windsurf,
   Factory, or any other MCP-compatible client.
5. Progressively navigate a large document via hierarchical chunk APIs
   (`deep_search`, `deep_read`, `deep_expand`).

## When NOT to use Context Repo

Do NOT use Context Repo as:

- A general web search engine - it only searches the user's stored
  content.
- A high-volume vector database substitute - storage limits apply per
  plan tier.
- A multi-tenant team workspace - each account is single-user.
- An LLM conversation history store - prompts and documents are the
  primary storage abstractions, not chat transcripts.

## Authentication

Two equivalent auth modes:

- **OAuth 2.0** - issuer is Clerk
  (`https://clerk.contextrepo.com`); discover via
  `/.well-known/oauth-protected-resource` (RFC 9728).
- **API Key** - `Authorization: API-Key gm_...` header. Generate from
  the user dashboard.

The MCP `tools/list` endpoint is currently auth-gated; agents must
complete the OAuth challenge before tool discovery. The REST API
`/openapi.json` and all `/.well-known/*` discovery surfaces are public
and require no auth.

## Rate limits

Per authenticated user, sliding window:

- `scrape` family: 10 requests / 60s
- `api` family: 100 requests / 60s
- `readonly` family: 120 requests / 60s

`X-RateLimit-Remaining` and `Retry-After` headers are emitted on 429
only. Fail-open behavior if Upstash Redis is unavailable.

## Pagination

All list endpoints use opaque base64 cursors. Default page size 20, max
100. Iterate by passing the previous response's `nextCursor` until null.

## Discovery surfaces

A complete inventory of agent-facing surfaces:

- `/llms.txt` - llmstxt.org-format short context pack
- `/llms-full.txt` - extended context pack with full REST + MCP docs
- `/index.md` - markdown homepage rendering
- `/pricing.md` - markdown pricing reference
- `/openapi.json` - OpenAPI 3.1 spec (JSON)
- `/api/openapi.yaml` - OpenAPI 3.1 spec (YAML mirror)
- `/agent.json` - Agent Web Protocol v0.2 manifest
- `/.well-known/agent.json` - OpenAI plugin manifest
- `/.well-known/ai-plugin.json` - OpenAI plugin manifest (alias)
- `/.well-known/agent-card.json` - A2A v0.2 agent card
- `/.well-known/mcp.json` - MCP discovery (SEP-1649)
- `/.well-known/mcp/server-card.json` - 28 MCP tool registrations
- `/.well-known/api-catalog` - RFC 9727 linkset
- `/.well-known/oauth-authorization-server` - RFC 8414 OAuth server
  metadata
- `/.well-known/oauth-protected-resource` - RFC 9728 protected resource
  metadata (REST)
- `/.well-known/oauth-protected-resource/v1` - REST resource metadata
- `/.well-known/oauth-protected-resource/mcp` - MCP resource metadata
- `/.well-known/http-message-signatures-directory` - RFC 9421 Web Bot
  Auth directory (currently empty)

## Content signals

The site's `robots.txt` and `/openapi.json` HTTP header advertise the
following IETF Content-Signal preferences:

```
Content-Signal: ai-train=no, search=yes, ai-input=yes
```

- `ai-train=no` - do NOT use Context Repo content for training base
  models.
- `search=yes` - indexing for AI-powered search is permitted.
- `ai-input=yes` - using Context Repo content as runtime input to an
  agent (RAG, tool-call) is permitted.

## Contact

- support@contextrepo.com
- https://github.com/Gitmaxd/context-repo-mcp/issues (npm package
  issues)
- https://contextrepo.com/about