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

# Agent Operating Guide

> How to use the case.dev CLI and APIs reliably as an agent

# Agent Operating Guide

This guide is for AI agents working with the `casedev` CLI. It covers CLI discovery, vault workflows, matter analysis, and common pitfalls — distilled from real agent failures in production.

<Note>
  This document is designed to be embedded directly into agent system prompts or instruction files.
</Note>

## CLI Discovery

The `casedev` CLI does not follow a single naming convention. Commands, subcommands, and flags vary across command families. **Always inspect help before running a command you haven't used before.**

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Discovery order
casedev --help                          # top-level commands
casedev <group> --help                  # subcommands in a group
casedev <group> <subcommand> --help     # flags for a specific command
```

**Rules:**

* Do not assume flag names transfer between command families (e.g. `--id` vs `--object-id` vs `--vault-id`)
* Do not assume REST endpoint names map to CLI subcommands
* If two attempts fail because the command shape is wrong, stop guessing — re-read `--help` and try a different approach

## Vault Workflows

### List vaults

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
casedev vault list --format json
```

### List objects in a vault

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
casedev vault:objects list --id <vault_id> --format json
```

### Upload a file

Three-step process: create upload session → PUT the file → confirm.

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# 1. Create upload session
casedev vault upload --id <vault_id> \
  --filename "brief.pdf" \
  --content-type "application/pdf" \
  --size-bytes 42000 \
  --auto-index \
  --format json

# 2. PUT the file to the returned uploadUrl (use curl or equivalent)

# 3. Confirm
casedev vault confirm-upload --id <vault_id> \
  --object-id <object_id> \
  --success \
  --size-bytes 42000 \
  --error-code "" \
  --error-message ""
```

<Warning>
  The confirm step requires `--error-code ""` and `--error-message ""` even on success. Do not assume a `vault:objects upload` shortcut exists — use the three-step flow above.
</Warning>

### Get extracted text

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
casedev vault:objects get-text --id <vault_id> --object-id <object_id> --format json
```

Only call this after you've identified the specific document you need.

### GraphRAG

Do not assume GraphRAG supports free-form querying. Always inspect the available subcommands first:

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
casedev vault:graphrag --help
```

Known subcommands include `get-stats`, `init`, and `process-object` — but the surface may change.

## Matter Analysis Workflow

When analyzing a matter (a legal case with uploaded documents), work in this order:

### 1. Build a filing map

List the vault objects and identify anchor documents first:

* Complaint / amended complaint
* Answer
* Motion to dismiss + opposition + reply
* Court orders
* Key declarations

Ignore peripheral filings until you've covered the core.

### 2. Extract parties

Start with the civil cover sheet, complaint caption, or answer caption — these are the most reliable sources.

### 3. Read the complaint

Focus on:

* Opening factual overview
* Causes of action
* Prayer for relief

Do not start from an arbitrary middle section.

### 4. Read defense arguments

Prioritize the latest operative defense briefs:

* Motion to dismiss
* Answer / affirmative defenses
* Brief headings and issue statements

### 5. Compile evidence

Tie evidence to actual filings — emails, contracts, declarations, exhibits cited in briefs.

### 6. Write the summary

Structure:

1. Parties
2. Claims
3. Key evidence
4. Plaintiff arguments
5. Defense arguments
6. Procedural posture
7. Open uncertainties

## Document Prioritization

| Priority   | Document types                                                                              |
| ---------- | ------------------------------------------------------------------------------------------- |
| **High**   | Complaint, amended complaint, answer, motion to dismiss, opposition/reply, court orders     |
| **Medium** | Declarations supporting core motions, key exhibits cited in briefs, case management orders  |
| **Low**    | Stray exhibits, side motions by non-core parties, intervention attempts, uncited appendices |

## Reading Best Practices

* **Use filenames as hints** — `001-Complaint.pdf` tells you more than a text search
* **Read small, targeted sections first** — issue statements, prayer for relief, conclusion sections
* **Don't dump entire documents** hoping to find the answer
* **Watch for OCR noise** — corroborate with other filings if text quality is poor, rely on headings over garbled body text
* **Never claim full understanding from partial text** — if content is truncated or starts mid-document, say so and keep collecting

## Anti-Patterns

| Category | What to avoid                                                                                                                           |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| CLI      | Guessing subcommands from API names, repeating wrong flags, skipping `--help`, treating help output as a success response               |
| Analysis | Starting with peripheral filings, summarizing from truncated excerpts, conflating allegations with proven facts, overstating confidence |

## Prompt Snippet

Embed this in agent instructions for reliable `casedev` usage:

```
Never guess casedev commands — inspect --help first. For matter analysis,
identify anchor filings before reading text. Prefer targeted retrieval over
raw document dumps. Do not claim comprehensive understanding from truncated
or mid-document excerpts. After two command-shape failures, stop and remap
the CLI surface.
```