---
name: inbox-watch
title: "Inbox Watch"
description: "Monitor inbox and root folder for new files, auto-route to knowledge base ingestion"
category: core
status: active
triggers:
  - "check inbox"
  - "new files"
  - "inbox watcher"
  - "process inbox"
---

## Instructions

Monitor the vault inbox and root folder for new or changed files, then route them into the knowledge pipeline.

### Scan Behavior

The inbox watcher runs every 30 seconds and checks two locations:
1. **Root folder** — the user's chosen vault directory (outside `.agntspace/`)
2. **KB inbox** — `.agntspace/inbox/` drop zone

### File Type Handling

| Type | Extensions | Processing |
|------|-----------|------------|
| Markdown | .md | Direct text extraction, wiki-link aware |
| Text | .txt | Plain text extraction |
| HTML | .html | Strip tags, extract text content |
| PDF | .pdf | Text extraction (PyMuPDF/pdfplumber) |
| Images | .png, .jpg, .jpeg | Vision LLM analysis (multimodal) |
| Data | .csv | Structure-aware extraction |

### Auto-Routing Rules

1. **Root folder files** — copied (never moved) into the most relevant KB's inbox (auto-routed to the single KB when only one exists, otherwise the `general` KB)
2. **KB inbox files** — routed to the appropriate KB based on content or default to general
3. **Project-specific content** — if a source mentions a known project, route to project-scoped KB
4. **Duplicate detection** — content-hash checked across all KBs before processing

### Retry Policy

- Files that fail processing are retried on subsequent scan cycles
- Maximum **5 retry attempts** per file per session
- After 5 failures, the file is marked as permanently skipped for this session
- Failed files are logged with the error reason

### Concurrency Control

- A lock prevents the watcher and API from double-processing the same file
- Only one ingest operation runs at a time per KB

### Post-Processing

After successful ingest:
- File is marked as "known" (tracked by path + content hash)
- Source summary created in the KB's `sources/` directory
- Original moved to `library/{type}/{YYYY-MM}/`
- If 3+ files processed in a batch, triggers compile + reflect cycle

## Rules

- NEVER modify or move files in the root folder — read-only, copy only
- User's existing files are never touched
- Only supported file types are processed — unknown extensions are ignored
- Inbox watcher is lightweight — no LLM calls during scan, only during ingest
- Large files (>10MB) are skipped with a warning
- Binary files (executables, archives) are always skipped
