> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# EvalGate Copilot

> Review and apply redacted, evidence-backed draft proposals with model-call, cost, authorization, and decision provenance.

EvalGate Copilot is an organization-scoped assistant for investigating evidence and proposing controlled changes. It is not a generic chatbot and it does not publish, activate, or silently mutate resources. Every actionable response becomes a persistent proposal with a redacted before/after diff, evidence, rationale, warnings, expected cost, the originating Model Gateway call, and an explicit human decision.

<Warning>
  Copilot acceptance creates a **draft** through the same domain service used by the product UI. Publishing a Prompt or Scorer version, activating a monitor, publishing a Dashboard, promoting a release, or applying an Evals-as-Code manifest remains a separate governed workflow.
</Warning>

## Supported resources

| Resource        | Proposal result                                                 | Protected-state behavior                                                                    |
| --------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Prompt Hub      | New immutable draft version with the reviewed version as parent | Never publishes or changes an environment binding                                           |
| Dataset Hub     | Redacted rows plus a new draft dataset snapshot                 | Archived datasets and invalid rows fail; a partial row/version failure is itemized          |
| Scorer Studio   | New immutable draft version with exact definition and parent    | Never approves, calibrates, or publishes                                                    |
| Continuous Eval | New configuration version for a draft monitor                   | Active or version-bound monitors are blocked and must use the manual monitor workflow       |
| Dashboards      | New immutable draft Dashboard version                           | Ownership and metric-reference invariants are rechecked; never publishes or changes a share |
| Deployments     | New release artifact draft                                      | Never promotes to candidate, canary, or live                                                |
| Evals-as-Code   | New immutable manifest draft version                            | Never plans or applies infrastructure/resource mutations                                    |

## Review workflow

<Steps>
  <Step title="Retain explicit context">
    Open Copilot from a supported product surface and retain only the resources needed for the investigation. A thread shows every retained resource. Context does not follow you unless it is retained in that thread.
  </Step>

  <Step title="Ask for an evidence-backed change">
    The request and authorized resource snapshots are redacted and bounded before the model call. Instruction-like content inside a resource is treated as untrusted data and removed. Every assistant call uses the organization Model Gateway and creates a model-call ledger record.
  </Step>

  <Step title="Inspect the proposal">
    Open **Copilot** from the platform navigation. Review the exact resource, redacted before state, proposed after state, linked evidence, rationale, warnings, expected cost, expiry, and model-call ID. A missing evidence list or unsafe proposal payload is rejected before it reaches this queue.
  </Step>

  <Step title="Record a decision rationale">
    Enter why the proposal is safe and useful or why it should be rejected. The decision stores your identity and current role/scopes; it does not rely on authorization captured when the proposal was generated.
  </Step>

  <Step title="Accept into a draft or reject">
    Acceptance displays a confirmation and rechecks permissions, accepted cost, expiration, the current resource hash, and domain invariants. Success links the created draft and rollback/source reference. Rejection records the rationale without changing the resource.
  </Step>
</Steps>

## Context, redaction, and prompt injection

A thread can retain at most 12 resources. Each resource snapshot is bounded to 32 KB for model context. Larger resources receive a hash-linked preview and a blocking warning; an incomplete preview cannot be accepted as a change. The context disclosure reports resource count, redacted count, truncated count, findings, and warnings.

Copilot removes common credentials, bearer tokens, API keys, GitHub tokens, JWTs, email addresses, and values under secret-like field names. It also removes instruction-like phrases such as requests to ignore system policy or reveal secrets. Raw secrets are not stored in Copilot messages or proposals. If the proposed **after** value itself contains sensitive or instruction-like content, it is rejected rather than made actionable.

## Proposal evidence contract

Every proposal retains:

* organization, thread, product surface, target type/ID/version, creator, creation time, and expiry;
* immutable redacted before and after values plus the expected current-resource SHA-256 hash;
* at least one evidence item whose resource is already retained and authorized in the thread;
* rationale, typed warnings, expected application cost, redaction state, and redaction findings;
* Model Gateway call ID and immutable creation-time authorization snapshot;
* current-state decision authorization, reviewer, rationale, idempotency key, timestamp, result, and failure detail;
* the created draft reference and rollback/source reference after successful application.

Proposal content and decisions are immutable at the database layer. Only the proposal lifecycle, reviewer, application result, and terminal failure detail can advance. Model-call and thread organization identity is enforced by database constraints and triggers.

## Permission and cost behavior

Reading threads and proposals requires `eval:read`. Creating a thread, asking Copilot to act, accepting, or rejecting requires organization-member access and `eval:write`. The accept service rechecks both even when the API route already authorized the request, so a permission downgrade after generation fails closed.

If a proposal has a non-zero expected cost, the reviewer must explicitly accept a budget at least that large. A stale proposal, expired proposal, missing scope, blocking warning, changed domain invariant, or insufficient accepted budget does not call a mutation service.

## Failure and recovery

| Failure                                       | Result                                         | Recovery                                                                                               |
| --------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Resource changed after generation             | `STALE_PROPOSAL`; no mutation                  | Ask Copilot to regenerate from current context                                                         |
| Permission changed                            | `FORBIDDEN`; no mutation                       | Restore the intended role/scope or ask an authorized member to review                                  |
| Proposal expired                              | Proposal becomes `expired`; no mutation        | Generate a new proposal                                                                                |
| Accepted cost is too low                      | `BUDGET_EXCEEDED`; no mutation                 | Review the estimate and explicitly accept a sufficient bound                                           |
| Blocking redaction/truncation warning         | `VALIDATION_ERROR`; no mutation                | Narrow the resource or use the manual workflow with complete evidence                                  |
| Domain validation fails before mutation       | `apply_failed` with code/message               | Correct the resource or regenerate                                                                     |
| Dataset rows apply but version creation fails | `apply_failed` with accepted row IDs and cause | Inspect the partial result; repeated rows deduplicate, then create/review the dataset version manually |
| Duplicate decision request                    | Original decision returned                     | No action; decision idempotency prevents duplicate application                                         |

Do not interpret `apply_failed` as “nothing changed.” Inspect `applicationResult`; it explicitly distinguishes a pre-mutation failure from a partial domain result.

## HTTP interfaces

| Interface                                     | Purpose                                                                   |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| `GET/POST /api/copilot/threads`               | List threads or create one with explicit retained context                 |
| `GET /api/copilot/threads/{id}`               | Read the thread, redacted messages, and proposals                         |
| `GET/POST /api/copilot/threads/{id}/messages` | Read or append a redacted user message                                    |
| `POST /api/copilot/threads/{id}/actions`      | Run an organization Model Gateway action against current retained context |
| `GET /api/copilot/proposals`                  | Filter the organization proposal queue by status or domain                |
| `GET /api/copilot/proposals/{id}`             | Read immutable proposal evidence and decision history                     |
| `POST /api/copilot/proposals/{id}/accept`     | Revalidate and create the reviewed draft                                  |
| `POST /api/copilot/proposals/{id}/reject`     | Record an attributable rejection                                          |
| `POST /api/copilot/proposals/{id}/apply`      | Compatibility alias for accept-and-apply-to-draft                         |

Decision requests require a rationale and an idempotency key. Accept requests also carry `maxExpectedCostUsd`; use `null` only when the proposal has no expected cost.

## Verification evidence

The implementation is covered by proposal/redaction unit tests, organization and immutable-history database tests, authenticated API route tests, evidence-diff DOM tests, and an authenticated golden path that accepts a Prompt proposal into a draft and rejects a monitor proposal while proving reviewer/model-call attribution and redaction.

* [Unit contract tests](https://github.com/evalgate/ai-evaluation-platform/blob/main/tests/unit/copilot/copilot-contracts.test.ts)
* [Database invariants](https://github.com/evalgate/ai-evaluation-platform/blob/main/tests/integration/copilot/copilot.db.test.ts)
* [API routes](https://github.com/evalgate/ai-evaluation-platform/blob/main/tests/api/copilot.routes.test.ts)
* [Review UI](https://github.com/evalgate/ai-evaluation-platform/blob/main/tests/dom/copilot/copilot-workspace.test.tsx)
* [Authenticated golden path](https://github.com/evalgate/ai-evaluation-platform/blob/main/e2e/copilot-golden-path.spec.ts)