Perform CRUD operations on items within Directus collections

## Actions

- `read`: Query items with filtering/pagination/field selection
- `create`: Add items with nested relations
- `update`: Modify items with partial data
- `delete`: Remove items by primary keys

## Essential Query Patterns

### Field Selection (Always Use)

```json
{ "fields": ["title", "status", "author.name", "categories.*"] }
```

For M2A relations: `"sections.item:headings.title", "sections.item:paragraphs.body"`

### Filtering Operators

Core: `_eq`, `_neq`, `_in`, `_nin`, `_null`, `_nnull`, `_lt`, `_lte`, `_gt`, `_gte`, `_between`, `_contains`,
`_icontains`, `_starts_with`, `_ends_with`, `_empty`, `_nempty` Relations: `_some`, `_none` (O2M only) Logic: `_and`,
`_or`

```json
{"status": {"_eq": "published"}}
{"title": {"_icontains": "keyword"}}
{"categories": {"_some": {"name": {"_eq": "News"}}}}
{"_or": [{"status": {"_eq": "published"}}, {"featured": {"_eq": true}}]}
```

### Deep Queries (Nested Relations)

```json
{
	"fields": ["title", "comments.text", "comments.author.name"],
	"deep": {
		"comments": {
			"_filter": { "status": { "_eq": "approved" } },
			"_sort": ["-date_created"],
			"_limit": 5
		}
	}
}
```

## Create/Update/Delete Best Practices

- ALWAYS show the item URL if it is present in the result for create or update

### Creating Items

- ALWAYS make sure you fully understand the collection's schema before trying to create items.

**✅ GOOD - Single with Relations:**

```json
{
	"action": "create",
	"collection": "posts",
	"data": [
		{
			"title": "New Post",
			"author": { "name": "John Doe", "email": "john@example.com" }, // Creates nested
			"categories": [1, 2, { "name": "New Category" }], // Mix existing + new
			"status": "draft"
		}
	]
}
```

**✅ GOOD - Batch Create:**

```json
{
	"action": "create",
	"collection": "posts",
	"data": [
		{ "title": "Post 1", "author_id": 1 },
		{ "title": "Post 2", "author_id": 2 }
	]
}
```

**❌ BAD - Missing Required Fields:**

```json
// Don't create without checking schema first
{ "title": "Post" } // Missing required fields like status
```

### Updating Items

**✅ GOOD - Update with Keys:**

```json
{
	"action": "update",
	"collection": "posts",
	"keys": ["uuid-1", "uuid-2"],
	"data": [{ "status": "published" }] // Partial update
}
```

**✅ GOOD - Batch Update (Different Data):**

```json
{
	"action": "update",
	"collection": "posts",
	"data": [
		{ "id": "uuid-1", "title": "Updated Title 1" },
		{ "id": "uuid-2", "title": "Updated Title 2" }
	]
}
```

**✅ GOOD - Relational Updates:**

```json
{
	"action": "update",
	"collection": "posts",
	"keys": ["uuid-1"],
	"data": [
		{
			"categories": {
				"create": [{ "name": "New Category" }],
				"update": [{ "id": 3, "name": "Renamed" }],
				"delete": [5]
			}
		}
	]
}
```

**❌ BAD - Update Without Keys:**

```json
// Don't update without specifying which items
{
	"action": "update",
	"data": [{ "status": "published" }] // Will fail - no keys provided
}
```

### Deleting Items

- ALWAYS get written confirmation with the user before deleting any items.

**✅ GOOD - Delete by Keys:**

```json
{
	"action": "delete",
	"collection": "posts",
	"keys": ["uuid-1", "uuid-2"]
}
```

**❌ BAD - Delete All (Dangerous):**

```json
// Never delete without keys - use query to get keys first
{
	"action": "delete",
	"collection": "posts" // Will fail - keys required
}
```

### Singleton Collections

**✅ GOOD - Singleton Read:**

```json
{
	"action": "read",
	"collection": "settings", // Singleton collection
	"query": { "fields": ["site_name", "logo"] }
}
```

**✅ GOOD - Singleton Update:**

```json
{
	"action": "update",
	"collection": "settings",
	"data": { "site_name": "New Name" } // No keys needed for singleton
}
```

## Advanced Relationship Patterns

### Many-to-One (M2O)

```json
// Create with nested author
{"title": "Article", "author": {"name": "New Author"}}
// Link existing author
{"title": "Article", "author": "existing-uuid"}
// Remove relation
{"author": null}
```

### One-to-Many (O2M)

```json
// Link to existing comments
{"comments": [1, 5, 9]}
// Create/update/delete operations
{
  "comments": {
    "create": [{"text": "New comment"}],
    "update": [{"id": 5, "text": "Updated"}],
    "delete": [1, 9]
  }
}
```

### Many-to-Any (M2A)

```json
{
	"sections": [
		{ "collection": "headings", "item": { "text": "Title", "level": 1 } },
		{ "collection": "paragraphs", "item": { "content": "Body text" } }
	]
}
```

### Translations

```json
// Create with multiple languages
{
  "title": "Main Title",
  "translations": [
    {"languages_code": "en-US", "title": "English Title", "content": "English content"},
    {"languages_code": "fr-FR", "title": "Titre Français", "content": "Contenu français"}
  ]
}

// Read specific language
{
  "fields": ["title", "translations.title", "translations.content"],
  "deep": {
    "translations": {
      "_filter": {"languages_code": {"_eq": "fr-FR"}}
    }
  }
}
```

## LLM Decision Rules

### Schema-First Pattern (Critical)

1. **Always call `schema()` first** to discover collections
2. **Examine specific schemas**: `schema(keys: ["collection"])` for field details based on users query
3. **Follow relation chains**: Check `relation.related_collections` in field definitions when it's relevant to your task
4. **IMPORTANT: Never guess field names** - Always use exact names from schema. If you're not 100% sure, ask the user

### Before Creating Items

1. **Check required fields** in schema
2. **Validate field types** match schema definitions
3. **Check for singleton collections** (`collection.singleton: true`)
4. **Verify relation targets exist** before linking. You can also create new relation items by nesting

### Before Updating Items

1. **Use keys parameter** for bulk updates with same data
2. **Use data array** for batch updates with different data per item
3. **Include primary key in data** when using batch update
4. **Check field permissions** - some fields may be read-only

### Before Deleting Items

1. **Always require explicit keys** - never delete by query alone
2. **Check for related data** that might be affected
3. **Validate cascade behavior** for relationships
4. **Consider soft delete** if collection has status field

### Performance & Safety

- **Use `fields`** to minimize payload size
- **Apply `limit`** for large result sets (default: no limit)
- **Batch operations** are transactional - all succeed or all fail
- **Primary keys returned** from create/update operations for chaining
- **Validation errors** are thrown before database operations

### Error Patterns to Avoid

- Creating without checking required fields through `scehma(keys: ["collection"])`
- Updating without keys or with invalid primary keys
- Deleting system collections (directus\_\*)
- Assuming field names without schema verification
- Missing foreign key references in relations
- Exceeding mutation limits in batch operations

### Singleton vs Regular Collections

**Regular Collections**: Require keys for update/delete, return arrays **Singleton Collections**: No keys needed, return
single objects, auto-upsert behavior

## Functions & Aggregation

Date: `year(field)`, `month(field)`, `day(field)`, `hour(field)` Aggregate: `count`, `sum`, `avg`, `min`, `max`

```json
{"filter": {"year(date_created)": {"_eq": 2024}}}
{"aggregate": {"count": ["*"], "sum": ["price"]}, "groupBy": ["category"]}
```

## Restrictions

- Cannot operate on `directus_*` collections
- Respects user permissions/RBAC
- Delete operations may be environment-disabled