# DocuSOR Documentation

DocuSOR gives coding agents shared, verified context and memory about your codebase: its services,
ports, routes, environment variables, and how to run it. The same context is served to every
agent and every engineer in your organization, whichever MCP-capable tool or model they use. It
writes that context when you connect a repository, proves it against your running app in an
isolated cloud sandbox, and re-checks it as your code changes. Agents read it through the DocuSOR
MCP server instead of re-exploring the repo.

## How DocuSOR works

1. **Onboarding writes a baseline.** When you connect a repository, DocuSOR scans it for services,
   ports, routes, configuration, and how the app boots, and turns what it finds into checks.
2. **Every fact is proven.** DocuSOR runs those checks against your app in an isolated sandbox.
   By default, agents are only served facts whose checks passed.
3. **Agents read it.** Coding agents call the DocuSOR MCP server and get the verified context in
   one call.
4. **Agents add to it.** When an agent learns something new, it writes it back to DocuSOR with a
   check. A passing run makes it part of the verified context for every other agent.
5. **It stays current.** DocuSOR re-validates each repository on a schedule (daily by default).
   If the latest run fails or drift is detected, served context is marked stale.

## Getting started

1. **Sign in** with GitHub, or with your company's SSO on Enterprise. Sign-in only identifies you.
   It gives DocuSOR no access to your code.
2. **Connect your repositories.** Install the DocuSOR GitHub App and choose the repositories you
   want covered, or, on Enterprise, connect a GitLab instance (cloud or self-managed). See
   [Repository access](#repository-access).
3. **Wait for onboarding.** DocuSOR writes and validates a baseline for each repository
   automatically. Onboarding is free and you don't add anything to your repository.
4. **Connect your coding agent** to the DocuSOR MCP server. See
   [Connect your coding agent](#connect-your-coding-agent-mcp-setup).
5. **Optional: add `AGENTS.md`.** Download it from **Settings** and commit it to your repository
   root. Most coding agents read this file automatically, and it tells them to use DocuSOR.

New organizations get 25 free credits. See [Credits and billing](#credits-and-billing).

## What your repository needs

DocuSOR needs a way to run your app:

- **With a Compose file** (`docker-compose.yml` or `compose.yml`), DocuSOR starts the stack and
  waits for it to be healthy before running checks.
- **Without a Compose file**, including Dockerfile-only repositories, DocuSOR does not start your
  app. A Dockerfile's `CMD` is not run. Checks on files, commands, and tooling still work. To check
  endpoints, the context needs a step that starts the app; your agent can add one.

A repository with no Compose file, Dockerfile, or `.docusor-cloud.yml` is skipped.

## Repository access

DocuSOR works with repositories on GitHub and GitLab. Standard plans connect GitHub; Enterprise
plans connect both GitHub and GitLab. Either way, it never pushes commits or edits
files in your repository, and it does not keep a copy of your code. Code is fetched for each run
and the sandbox is destroyed when the run ends. See [Security](https://docusor.ai/security) for details.

### GitHub

Install the DocuSOR GitHub App. You choose which repositories it can see and can change that list
or uninstall it at any time in GitHub under **Settings → GitHub Apps**.

- **Metadata (read).** Required for every GitHub App. Lists the repositories you selected.
- **Contents (read).** Reads your code at a specific commit so DocuSOR can run it in the sandbox.

The App has no write permissions. It receives these webhook events: **installation** and
**installation repositories** (to add or remove repositories) plus **push** (to react to new
commits).

### GitLab

GitLab.com and self-managed GitLab are available on Enterprise plans. Owners and admins connect
it from **Repository sources** on the dashboard:

1. Click **Connect GitLab** and enter the instance URL (must use `https://`).
2. Paste a group access token or service-account token with the `read_api` and
   `read_repository` scopes. Use the `api` scope instead if you want results posted as commit
   statuses on merge requests. The token is encrypted at rest.
3. Optionally enter a group path to import only that group and its subgroups.
4. To validate automatically, add the webhook URL and secret shown in DocuSOR under
   **Settings → Webhooks** in GitLab, with **Push events** and **Merge request events** enabled.

Revoke access at any time by revoking the token in GitLab.

## Connect your coding agent (MCP setup)

DocuSOR is a remote MCP server using the Streamable HTTP transport.

- **URL:** `https://connect.docusor.ai/mcp`
- **Header:** `docusor-org-mcp-key: <your key>`

**Get a key** on the **Team & Access** page. Create a per-engineer key (usage is attributed to
that engineer), or, as an org owner, generate the organization key. Keys are shown once. The
page can also download a ready-made config for each client below. Keep keys out of committed
files and revoke a leaked key on the same page.

**Claude Code**

```bash
claude mcp add --transport http docusor https://connect.docusor.ai/mcp \
  --header "docusor-org-mcp-key: <your key>"
```

Or in `.mcp.json`:

```json
{
  "mcpServers": {
    "docusor": {
      "type": "http",
      "url": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "docusor": {
      "url": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}
```

**VS Code / GitHub Copilot** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "docusor": {
      "type": "http",
      "url": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}
```

**Windsurf** (`mcp_config.json`)

```json
{
  "mcpServers": {
    "docusor": {
      "serverUrl": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}
```

To test the connection, ask your agent to "list my DocuSOR repos". It should call `list_repos`.

## Working with your coding agent

The MCP server explains its own workflow to the agent when it connects, and `getting_started`
returns the full tool map. The main tools:

- **Read:** `query_context` answers a targeted question with only the matching verified facts.
  `get_repo_context` returns a repository's full verified context.
- **Write:** `audit_repo` lists what is not yet documented or proven. `put_repo_context` writes
  new context and its checks as a draft. `validate_repo` runs the checks; a passing run promotes
  the draft to verified context. `get_run_report` shows why a run failed.
- **Check code changes:** `validate_changes` runs your uncommitted edits (up to 50 files, 1 MB)
  against the existing verified context before you commit.
- **Across repositories:** `get_dependency_graph` and `blast_radius` show which services depend
  on each other and what would break if a contract changes.
- **Docs:** `check_doc` tests one of your repository's Markdown files. See
  [Writing testable docs](https://docusor.ai/guides/testable-docs).

Context lives in DocuSOR, not in your repository. Agents should not edit `README.md` to satisfy
DocuSOR.

## Testing your docs

DocuSOR can also test your repository's own Markdown files, such as `README.md` and runbooks.
Write checkable facts as short claims (for example, "`GET /health` returns `200`"), then click
**Test a doc** on the repository page. DocuSOR reports each claim as passed or failed. See
[Writing testable docs](https://docusor.ai/guides/testable-docs).

## Credits and billing

Standard is pay-as-you-go with prepaid credits. **One credit costs $0.10**, or as little as $0.08
with larger packs. New organizations get 25 free credits.

**1 credit per read:**

- `get_repo_context` and `query_context`
- `get_dependency_graph` and `blast_radius`
- `check_contract_drift`, `get_shared_contract`, `list_contract_consumers`, and
  `list_upstream_changes`

**1 credit per run an agent starts:** `validate_repo`, `validate_changes`, and `check_doc`. The
credit is refunded if the run never executes.

**Free:**

- Onboarding, scheduled re-validation, and runs triggered by commits
- Runs and doc tests started from the dashboard
- `list_repos`, `search_repos`, `get_repo_validation_status`, `audit_repo`, `put_repo_context`,
  `get_pending_changes`, `get_run_status`, `get_run_report`, `ack_upstream_changes`,
  `getting_started`, and `how_to_write_context`

At zero balance, paid reads and agent-started runs stop until you buy more credits on the
**Billing** page. Free operations keep working.

## Enterprise

Enterprise is an annual platform fee plus prepaid credits, with unlimited repositories and seats.
It adds:

- **GitHub and GitLab.** Connect GitLab.com or self-managed GitLab alongside GitHub. See
  [Repository access](#repository-access).
- **SSO.** Engineers sign in with your identity provider over SAML or OIDC.
- **Teams.** Owners and admins group repositories into teams and choose who can see each one.
- **Self-hosting.** Run DocuSOR in your own infrastructure, including air-gapped environments, so
  code and context stay on your network.
- **Private runners.** Dedicated validation runners for your organization (add-on).
- **Audit logs** and **advanced support.**

To talk about Enterprise, use **Contact sales** on the [pricing section](https://docusor.ai/#pricing).

## Getting help

See the [FAQ](https://docusor.ai/faq). For security questions, email security@docusor.ai.
