# Import Workflow

## How It Works

The user's writing samples are **not stored locally**. When you import a document, it is uploaded to the Author's Voice API and stored in a cloud database. The API chunks the content, indexes it for search, and uses it for voice matching when `rewrite` or `generate` is called.

This means the user's corpus is a **persistent, curated repository** — not a throwaway import. Every document you add stays in the database and directly influences all future voice output. The quality of the corpus IS the quality of the voice.

**Think of it like a training set:**
- Documents tagged `Human` are the ground truth. They define the voice.
- Documents tagged `AI` or `AI-Assisted` are penalized in retrieval — they exist for reference but don't shape the voice.
- Wrongly tagged documents (AI content marked as Human) **corrupt the voice profile**. The system will learn AI patterns as if they were the author's patterns. This is the single worst thing that can happen to voice quality.
- Wrong categories cause cross-contamination — email samples polluting blog voice, tweets diluting long-form style.

**The agent's job during import is curation, not bulk ingestion.** Every document must be verified with the user before it enters the corpus.

**Corpus size guidelines:**
- **Minimum**: 3-5 documents, ~5,000 words — enough for basic pattern detection
- **Good**: 10+ documents, ~15,000+ words — reliable voice profile
- **Per category**: At least 3 documents in each category you plan to use for voice output
- More is better, but only if it's genuinely human-written. 5 authentic documents beat 50 mixed ones.

If the user doesn't have enough samples yet, tell them. A thin corpus produces a weak profile — the agent should set expectations rather than generate from insufficient data.

---

## Critical Rules

These rules are non-negotiable. Violating them degrades voice quality.

### 1. Always Tag Authenticity

Voice profiles are ONLY built from Human-written content. AI-generated docs pollute the voice fingerprint.

**The agent MUST follow this process:**
1. Gather candidate documents (URLs the user provides, or raw content)
2. Present the list to the user and ask:
   - "Which of these did YOU write? (Human)"
   - "Which were AI-generated or AI-assisted?"
3. Only import docs the user confirms as Human with `"authenticity": "Human"`
4. Tag AI/uncertain docs as `"AI"` or `"AI-Assisted"`, or skip them
5. Ask about categories for each doc

**NEVER assume a document is human-written.** Many users have a mix.
**NEVER bulk-import without user confirmation per document.**

### 2. Authenticity Labels
- `Human` — written entirely by a human (default)
- `AI-Assisted` — human-written with AI help
- `AI` — generated by AI
- `Untagged` — unknown origin

### 3. Category Pollution Destroys Voice Quality

Categories control which writing samples the retrieval layer pulls back. Wrong category = wrong examples = wrong voice.

**Impact**: Blog posts tagged as "email" → retrieval pulls email-style samples → output sounds corporate, not blog-voice. Tweets tagged as "blog" → retrieval pulls long-form samples → output loses punchy fragments.

**The agent MUST:**
1. Ask the user what category each document belongs to during import
2. Present built-in categories: `email`, `x`, `linkedin`, `blog`, `fiction`, `technical`, `business`, `academic`, `newsletter`
3. If uncertain, ask the user — NEVER guess categories
4. When calling `rewrite`, ALWAYS pass `category` to scope retrieval
5. If a document doesn't fit any category, use the most stylistically similar one

**NEVER leave category empty** when the user has categorized content. Empty category retrieves from all categories, diluting the voice signal with stylistically mixed samples.

---

## Import Tools Quick Reference

| Tool | Use |
|------|-----|
| `import_from_url` | Import from any public URL (`url`, `categories[]`, `authenticity`) |
| `bulk_import` | Import multiple docs, max 50 (global `authenticity`) |
| `upload_content` | Upload raw markdown. Minimal payload `{docId, content}` — `profileId` optional (auto-resolves a default profile), `content` server-chunked on blank lines. |

After import: run `setup_voice` to create/update the voice profile. Update `local/state.md`.
