# Chainfill Agent Guide

Chainfill is an enterprise document processing platform. Agents should operate it through structured tools first: `cf` CLI, MCP, REST/OpenAPI, then browser automation only when needed.

Start with `/docs/agents/how-to-use.md` when you need to choose a surface, plan a safe workflow, or tell a human what proof to request.

## Core Surfaces

| Surface | Use |
| --- | --- |
| `cf` CLI | Operational support, admin investigation, uploads, reprocess, export retry. |
| Chainfill MCP | Same operational surface exposed as MCP tools reflected from the CLI. |
| REST/OpenAPI | Integration code and direct API access. |
| Browser | Visual verification and workflows not yet covered by tools. |

## Agent Operating Rules

1. Authenticate a dedicated CLI profile first, for example `cf --profile <profile> login --env preview --pr <number>`.
2. Prefer command-specific `--json` so results are machine-readable.
3. Default write actions to `local` or preview.
4. Do not run production writes unless the user explicitly asks for production.
5. Use `--purpose testing` for test document uploads.
6. Treat admin impersonation as privileged. Include a reason, verify impersonation state, and end impersonation.
7. Treat export resend and endpoint delivery as external side effects.
8. Poll status endpoints rather than sleeping a fixed amount of time.
9. Stop and ask when company, user, document, endpoint, or document type targets are ambiguous.
10. Report command/tool name, arguments, environment, ids, and verification evidence after every mutation.
11. Never hide backend failures. Include status code, error body, and relevant ids.

## Action Contract Summary

Each agent-facing tool should be understood with this contract:

- `side_effect_level`: `read`, `write`, `high`, or `external`.
- `mutates`: whether it changes state.
- `supports_dry_run`: whether preview-only execution exists.
- `supports_test_mode`: whether it can run against test data or test endpoints.
- `test_mode_hint`: exact argument or mode, when available.
- `requires_confirmation`: whether to pause before calling.
- `idempotency`: `read_safe`, `caller_provided`, `backend_defined`, or `not_idempotent`.
- `required_scope`: permission category.
- `observability`: follow-up ids, status commands, or message commands to collect.
- `failure_policy`: how to react to failure.

## Common CLI Commands

### Read company/config context

```bash
cf --profile <profile> login --env preview --pr <PR>
cf --profile <profile> company list --json
cf --profile <profile> doctype list --json
cf --profile <profile> endpoint list --json
cf --profile <profile> workflow list
```

### Admin impersonation

```bash
cf --profile <profile> impersonate --user-id <user_id> --reason "<reason>"
cf --profile <profile> whoami
cf --profile <profile> company info
cf --profile <profile> end-impersonation
```

### Test document upload

```bash
cf --profile <profile> upload --file <file> --purpose testing
cf --profile <profile> monitor find --email-integration-id <email_integration_id> --json
cf --profile <profile> monitor show <order_uuid> --with-labels --json
```

### Debug processing

```bash
cf --profile <profile> monitor find --email-integration-id <email_integration_id> --json
cf --profile <profile> monitor show <order_uuid> --with-labels --json
cf --profile <profile> monitor traces --email-integration-id <email_integration_id> --json
cf --profile <profile> workflow paused <email_integration_id>
```

### Retry external delivery

```bash
cf --profile <profile> workflow retry-export-branch <email_integration_id>
cf --profile <profile> monitor traces --email-integration-id <email_integration_id> --json
```

Only run resend after explicit approval.

## MCP Tool Names

Register the full-coverage server with an isolated CLI profile:

```bash
cf --profile <profile> mcp install --client codex
# or: cf --profile <profile> mcp install --client claude --scope local
cf --profile <profile> mcp doctor --json
```

Start a fresh agent session after registration. The server exposes 25 typed
fast-path tools, including:

- `status`
- `whoami`
- `agents.docs`
- `agents.search-docs`
- `tasks.list`
- `tasks.inspect`
- `monitor.list`
- `monitor.show`
- `monitor.find`
- `monitor.traces`
- `monitor.export-attempts`
- `company.list`
- `company.info`
- `user.info`
- `workflow.list`
- `workflow.show`

It also exposes:

- `cli.search` — search every visible installed `cf` command.
- `cli.describe` — return the canonical typed schema and help for a command.
- `cli.execute` — run that command through the active isolated profile.

Use those three tools for any operation missing from the typed fast path. They
cover reads and writes across the complete visible CLI catalog while keeping the
model-facing schema small. `cli.execute` invokes the real CLI, preserving its
argument validation, confirmation, production, and impersonation guardrails.
For commands that consume stdin, pass a local UTF-8 `stdin_file`; do not place
secret payload contents directly in MCP arguments. Plaintext token/credential
results are withheld unless `include_sensitive_output=true`; use it only after
explicit approval to reveal the value.

## Playbooks

- How to use Chainfill with agents: `/docs/agents/how-to-use.md`
- Reupload test documents: `/docs/agents/playbooks/reupload-test-documents.md`
- Debug document processing: `/docs/agents/playbooks/debug-document-processing.md`
- Retry export delivery: `/docs/agents/playbooks/retry-export-delivery.md`
- External order retrieval API: `/docs/agents/playbooks/order-retrieval-api.md`
- Custom table inbound API: `/docs/agents/playbooks/custom-table-inbound-api.md`
- Inspect company configuration: `/docs/agents/playbooks/inspect-company-configuration.md`
- Customer support mailbox patterns: `/docs/agents/playbooks/customer-support-mailbox-patterns.md`
- Customer support hard-won lessons: `/docs/agents/playbooks/customer-support-lessons.md`
- Support agent feedback: `/docs/agents/playbooks/support-agent-feedback.md`
- Company brain runbook: `/docs/agents/company-brain/README.md`
- Support memory corpus: `/docs/agents/support-memory/README.md`

The company brain is the shared Chainfill GBrain deployment for durable agent memory. Use `/docs/agents/company-brain/README.md` for Supabase setup, source-scoped access, OAuth client handoff, credential rotation, seed import, and verification steps.

Support memory is prior-case context only. Import the Git-backed sanitized corpus into local GBrain with `gbrain import docs/agents/support-memory --no-embed`, or search the directory directly if GBrain is unavailable. Verify current live state before acting.

## Evaluation Tasks

Run the benchmark in `/docs/agents/evals.md` before calling a new host or model production-ready for Chainfill support. Minimum standard: no unapproved production writes, safe blocking on ambiguity, and verified status for every mutation.