# 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 the AI Context Repo for agents. It stores prompt
templates, documents, and collections, and exposes them to agents via:

- **MCP server** (`https://contextrepo.com/mcp`) - 29 tool registrations
  over streamable-HTTP transport with OAuth. Grok uses the dedicated
  `https://contextrepo.com/grok-mcp` compatibility entrypoint for the
  same server and tools.
- **REST API** (`https://api.contextrepo.com/v1/*`) - 35 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, Grok, VS Code,
   Grok Bot, Factory, or another client with compatible transport and
   authentication support.
5. Progressively navigate a large document via hierarchical chunk APIs
   (`deep_search`, `deep_read`, `deep_expand`).
6. Get one best-effort synthesized answer over stored document evidence
   with `reason`, rather than manually reading ranked search results.
7. Save conversations, decisions, and session handoffs from ChatGPT,
   Claude, or another connected agent, then find and reuse them from
   other connected clients. The Chrome Extension saves the visible
   ChatGPT or Claude conversation as a Markdown document.
8. Keep a public web page as a searchable document (Pro Max and Ultimate):
   save it by URL
   (REST `POST /v1/documents/scrape`, the dashboard, or the Chrome
   Extension), then refresh it later to keep it current.
9. Share a prompt or document with people through a read-only public
   link, published from the dashboard.

Reason operates on document content only, not prompts. It is read-only,
does not persist its answer or reasoning trace, and reports non-exhaustive
limitations. Disagreements appear as ordinary cited statements in the answer.

## ChatGPT terminology

ChatGPT App is the primary product name for Context Repo's ChatGPT
integration. Its `search` and `fetch` tools implement the OpenAI Apps SDK
Company Knowledge compatibility contract. These terms describe the app and
its technical contract, not separate Context Repo integrations.

## When not to use Context Repo

Context Repo holds the context you and your agents choose to keep. A few
jobs belong to other tools:

- **Open-web search.** Context Repo searches your stored content, not the
  live web. Use it alongside a search tool: when a page is worth keeping,
  save it by URL (Pro Max and Ultimate) and refresh it later to keep it current.
- **Raw vector storage for bulk application data.** Context Repo does not
  accept your own vectors, and plan storage limits apply. Instead, it runs
  retrieval for you: automatic chunking and embeddings, semantic and
  exact-match search, step-by-step `deep_search` inside long documents,
  and cited answers from `reason`.
- **Organization or team accounts.** Each account belongs to one person
  today; there are no shared org workspaces, member seats, or org-level
  roles. Within one account, a team of agents works well:
  - Connect several agents and tools to the same repository, each with its
    own API key scoped to prompts, documents, or both, with read or write
    access.
  - Document updates and restores through MCP must name the revision they
    are based on (`expectedRevision`), so one agent cannot silently
    overwrite another's edit. REST clients get the same check by sending
    `If-Match` or `expectedRevision`.
  - For documents several agents edit at the same time, turn on
    `lease_required`. Through the REST API, an agent takes a time-limited
    lease before writing. Each lease carries a fence number: once a lease
    is released, or expires and another agent takes it, writes that still
    carry the old lease are rejected. MCP clients cannot hold a lease, so
    lease-managed documents are written through REST.
  - Share a prompt or document with people through a read-only public
    link, published from the dashboard.

## Authentication

Two supported auth modes:

- **OAuth 2.0** - issuer is Clerk
  (`https://clerk.contextrepo.com`). Canonical MCP clients discover
  `/.well-known/oauth-protected-resource/mcp`; Grok discovers
  `/.well-known/oauth-protected-resource/grok-mcp` (RFC 9728).
- **API Key** - `Authorization: API-Key gm_...` header. Generate from
  the user dashboard. API-key access is limited to the prompt or document
  scopes granted to that key, while interactive session and OAuth tokens
  carry the signed-in user's authority.

The canonical `/mcp` discovery methods are public; agents can list
tools without completing the OAuth challenge first. The following
JSON-RPC methods are reachable without auth at `/mcp`:

- `initialize`
- `notifications/initialized`
- `ping`
- `tools/list`
- `resources/list`
- `resources/templates/list`

Everything else (notably `tools/call`, `prompts/list`, `prompts/get`,
and authenticated `resources/read` schemes) requires either a
Clerk-issued bearer token or a Context Repo API key. Public
`initialize` still advertises the native `prompts` capability. The REST
API `/openapi.json` and all `/.well-known/*` discovery surfaces are
public and require no auth.

The public method list above applies only to the canonical `/mcp` endpoint.
Every `/grok-mcp` request requires authentication, including `initialize`
and `tools/list`, so Grok receives the OAuth challenge it needs before
tool discovery.

## Rate limits

Per authenticated user, sliding window:

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

Responses may include `X-RateLimit-*` metadata. On `429`, honor the
`Retry-After` header before retrying.

## Pagination

REST list endpoints default to 20 items and cap pages at 100. Continue
with the previous response's `pagination.cursor` while
`pagination.hasMore` is true.

Native MCP `prompts/list` requests 100 items per page. Pass its optional
response `nextCursor` value as the next request's `params.cursor`, and
stop when `nextCursor` is absent.

## Document revisions and coordination

MCP `update_document` and `restore_document_version` require
`expectedRevision` from `get_document` or the latest successful document
acknowledgement. Each invocation makes exactly one REST write with no preflight
GET. On `REVISION_MISMATCH`, read again. If the intended state is already
present, stop; otherwise reapply the change to the latest content and retry
with its revision. Documents using `lease_required` managed editing must use
the REST coordination workflow; MCP does not accept lease credentials.

The following lower-level contract applies to raw REST clients.
Document reads expose the canonical `revision`, `contentHash`,
`lastChangedAt`, and `ETag`. PATCH and restore accept either `If-Match`
or body `expectedRevision`. When both are supplied, their revisions must
agree and the header's content hash is also checked. Preconditions and
`Idempotency-Key` remain optional in standard mode; writes that do not
change the logical document return `noop: true` without creating another
revision.

Owners can enable the `lease_required` policy with
`PUT /v1/documents/{id}/coordination` and return to standard mode with
`DELETE /v1/documents/{id}/coordination`. Both policy changes require
the exact current `ETag` in `If-Match`. Inspect policy and caller-visible
lease state with `GET /v1/documents/{id}/coordination`.

Acquire, renew, or release a lease with
`POST /v1/documents/{id}/coordination/lease`. Lease operations require
`Idempotency-Key`; renew and release also require
`X-ContextRepo-Lease-Id` and `X-ContextRepo-Lease-Fence`. Managed PATCH
and restore require either revision precondition above plus
`Idempotency-Key`, `X-ContextRepo-Lease-Id`, and
`X-ContextRepo-Lease-Fence`. Refresh and coordination-policy operations
retain their existing preconditions: managed refresh still requires
`If-Match`, the key, and both lease headers.

Retry the identical operation with its original revision, key, payload,
lease fields, and original precondition representation (`If-Match` or body
`expectedRevision`). Do not replace the revision or key to recover an
uncertain result. Matching receipts are retained for 24 hours from creation.
Reconcile uncertain operations by reading the document and history before
taking further action.

Update and restore return compact acknowledgements with revision
metadata. Restoring an incomplete historical snapshot succeeds with the
`LEGACY_PARTIAL_SNAPSHOT` warning so agents know fields absent from that
legacy snapshot were preserved.

Runtime inventory: 35 REST operations are implemented by 37
physical Convex HTTP route registrations over 16 database tables. The
MCP surface remains 29 tools.

## 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
- `/docs/llms.txt` - index of every docs page; `/docs/llms-full.txt` has
  them all as Markdown, and any docs page is its URL plus `.md`
- `/docs-mcp` - public docs MCP server, no sign-in (`search_docs`,
  `read_docs_page`, `list_docs_pages`); separate from `/mcp`
- `/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` - 29 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 canonical MCP
  protected-resource metadata fallback
- `/.well-known/oauth-protected-resource/v1` - REST resource metadata
- `/.well-known/oauth-protected-resource/mcp` - MCP resource metadata
- `/.well-known/oauth-protected-resource/grok-mcp` - Grok MCP
  compatibility-resource metadata
- `/.well-known/http-message-signatures-directory` - RFC 9421 Web Bot
  Auth directory (currently empty)

## Plan limits

Every REST and MCP request except `GET /v1/user/me` needs an active plan.
A request the plan does not allow fails with `402` and the envelope
`{ "error": { "code", "reason", "message", "details" } }`. `reason` is one of:

- `PLAN_REQUIRED`: no active plan. Start a trial or choose a plan.
- `FEATURE_NOT_IN_PLAN`: the plan lacks the feature.
  `details.plansWithFeature` names the plans that have it.
- `QUOTA_EXCEEDED`: an allowance is used up. `details` names the `meter`,
  `limit`, `used`, and `resetsAt`.

`503` with `ENTITLEMENT_UNAVAILABLE` is
temporary; honor `Retry-After`. `GET /v1/user/me` returns the current
`plan` and `usage`. Every plan limit: https://contextrepo.com/pricing.md

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