@adaptic/maestro 1.0.0

package/scripts/post-interaction-indexer.py

@@ -0,0 +1,1598 @@
+#!/usr/bin/env python3
+"""Post-interaction auto-indexer — Memory Enhancement Phase 5.
+
+Automatically extracts entities, relationships, and facts from interactions
+and updates memory/indexes/entity-relationships.yaml.
+
+Integration points — call this script:
+  - After the inbox processor processes each inbox item
+  - After the backlog executor completes interaction-heavy tasks
+  - During session-end hook as part of session wrap-up
+  - Manually for backfill / one-off extraction
+
+Usage:
+  # Process a specific inbox item (JSON or YAML)
+  python3 scripts/post-interaction-indexer.py --input state/inbox/slack/1775230363.978999-dm.json
+
+  # Process all unprocessed interactions from today
+  python3 scripts/post-interaction-indexer.py --scan-today
+
+  # Dry run — show extractions without writing
+  python3 scripts/post-interaction-indexer.py --input <file> --dry-run
+
+  # Process from stdin (piped JSON)
+  echo '{"event_type":"email","email":{"from":"Jane <jane@co.com>"}}' | python3 scripts/post-interaction-indexer.py --stdin
+
+Output:
+  Logs extracted facts and index updates to stdout.
+
+Exit codes:
+  0 = success (updates made or would be made in dry-run)
+  1 = no new facts extracted
+  2 = error
+
+Performance target: < 2 seconds per interaction.
+
+Created: 2026-04-04 — Memory Enhancement Phase 5
+"""
+import argparse
+import json
+import re
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+# ─────────────────────────────────────────────
+# Path resolution
+# ─────────────────────────────────────────────
+SCRIPT_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPT_DIR.parent
+
+ENTITY_INDEX_PATH = REPO_ROOT / "memory" / "indexes" / "entity-relationships.yaml"
+ENTITY_INDEX_CACHE_PATH = REPO_ROOT / "memory" / "indexes" / ".entity-relationships.json"
+INBOX_DIR = REPO_ROOT / "state" / "inbox"
+PROCESSED_DIR = INBOX_DIR / "processed"
+
+# ─────────────────────────────────────────────
+# YAML handling — import PyYAML if available
+# ─────────────────────────────────────────────
+_yaml_mod = None
+_yaml_loader = None
+try:
+    import yaml as _yaml_mod
+    try:
+        _yaml_loader = _yaml_mod.CSafeLoader  # C extension — 10x faster
+    except AttributeError:
+        _yaml_loader = None
+except ImportError:
+    pass
+
+
+def _load_yaml(text):
+    """Parse YAML text using PyYAML (required for this script)."""
+    if _yaml_mod is None:
+        raise RuntimeError("PyYAML is required. Install with: pip3 install pyyaml")
+    if _yaml_loader is not None:
+        return _yaml_mod.load(text, Loader=_yaml_loader) or {}
+    return _yaml_mod.safe_load(text) or {}
+
+
+def _dump_yaml(data):
+    """Dump data to YAML string, preserving readability."""
+    if _yaml_mod is None:
+        raise RuntimeError("PyYAML is required.")
+    return _yaml_mod.dump(
+        data,
+        default_flow_style=False,
+        allow_unicode=True,
+        sort_keys=False,
+        width=120,
+    )
+
+
+# ─────────────────────────────────────────────
+# Entity index loading (with JSON cache for speed)
+# ─────────────────────────────────────────────
+def load_entity_index():
+    """Load and return the full entity-relationships.yaml as a dict.
+
+    Uses a JSON cache (same as pre-draft-context.py) when available,
+    falling back to YAML parsing. The JSON cache is 10-50x faster to load.
+
+    Returns dict with 'entities' (list) and 'relationships' (list).
+    """
+    if not ENTITY_INDEX_PATH.exists():
+        return {
+            'schema_version': 1,
+            'last_updated': datetime.now(timezone.utc).isoformat(),
+            'last_updated_by': 'post-interaction-indexer',
+            'entities': [],
+            'relationships': [],
+        }
+
+    # Try JSON cache first (much faster than YAML parsing)
+    if ENTITY_INDEX_CACHE_PATH.exists():
+        yaml_mtime = ENTITY_INDEX_PATH.stat().st_mtime
+        json_mtime = ENTITY_INDEX_CACHE_PATH.stat().st_mtime
+        if json_mtime >= yaml_mtime:
+            try:
+                data = json.loads(ENTITY_INDEX_CACHE_PATH.read_text(encoding='utf-8'))
+                if isinstance(data, dict):
+                    if 'entities' not in data or data['entities'] is None:
+                        data['entities'] = []
+                    if 'relationships' not in data or data['relationships'] is None:
+                        data['relationships'] = []
+                    return data
+            except Exception:
+                pass  # Fall through to YAML
+
+    # Parse YAML (slow path)
+    text = ENTITY_INDEX_PATH.read_text(encoding='utf-8')
+    data = _load_yaml(text)
+    if not isinstance(data, dict):
+        data = {'entities': [], 'relationships': []}
+
+    if 'entities' not in data or data['entities'] is None:
+        data['entities'] = []
+    if 'relationships' not in data or data['relationships'] is None:
+        data['relationships'] = []
+
+    # Write JSON cache for next time
+    try:
+        ENTITY_INDEX_CACHE_PATH.write_text(
+            json.dumps(data, default=str, ensure_ascii=False),
+            encoding='utf-8',
+        )
+    except Exception:
+        pass
+
+    return data
+
+
+def build_lookups(data):
+    """Build fast lookup dicts from entity index data.
+
+    Returns dict with:
+      by_name: lowercase name/alias -> entity dict
+      by_email: lowercase email -> entity dict
+      by_id: entity id -> entity dict
+      rel_ids: set of relationship ids
+    """
+    by_name = {}
+    by_email = {}
+    by_id = {}
+
+    for entity in data.get('entities', []):
+        if not isinstance(entity, dict):
+            continue
+
+        eid = entity.get('id', '')
+        if eid:
+            by_id[eid] = entity
+
+        name = entity.get('name', '')
+        if name and isinstance(name, str):
+            by_name[name.lower()] = entity
+            # Also index first-last shorthand
+            parts = name.split()
+            if len(parts) >= 2:
+                short = f"{parts[0]} {parts[-1]}"
+                by_name[short.lower()] = entity
+            if len(parts) >= 1:
+                first = parts[0].lower()
+                if first not in by_name:
+                    by_name[first] = entity
+
+        aliases = entity.get('aliases', []) or []
+        if isinstance(aliases, list):
+            for alias in aliases:
+                if alias and isinstance(alias, str):
+                    by_name[alias.lower()] = entity
+
+        email = entity.get('email', '')
+        if email and isinstance(email, str):
+            by_email[email.lower()] = entity
+
+    rel_ids = set()
+    for rel in data.get('relationships', []):
+        if isinstance(rel, dict) and rel.get('id'):
+            rel_ids.add(rel['id'])
+
+    return {
+        'by_name': by_name,
+        'by_email': by_email,
+        'by_id': by_id,
+        'rel_ids': rel_ids,
+    }
+
+
+# ─────────────────────────────────────────────
+# Input parsing — normalize various formats
+# ─────────────────────────────────────────────
+def parse_input_file(filepath):
+    """Parse an inbox item file (JSON or YAML) into a normalized dict.
+
+    Returns dict with keys:
+      source_type: 'slack' | 'email' | 'calendar' | 'meeting' | 'unknown'
+      timestamp: ISO timestamp string
+      sender_name: str or None
+      sender_email: str or None
+      sender_slack_id: str or None
+      channel: str or None
+      subject: str or None
+      content: str
+      raw: original parsed data
+      source_file: str
+    """
+    path = Path(filepath)
+    if not path.exists():
+        raise FileNotFoundError(f"Input file not found: {filepath}")
+
+    text = path.read_text(encoding='utf-8')
+    return parse_input_text(text, str(path))
+
+
+def parse_input_text(text, source_label="stdin"):
+    """Parse input text (JSON or YAML) into normalized dict."""
+    text = text.strip()
+    if not text:
+        raise ValueError("Empty input")
+
+    raw = None
+
+    # Try JSON first
+    if text.startswith('{') or text.startswith('['):
+        try:
+            raw = json.loads(text)
+        except json.JSONDecodeError:
+            pass
+
+    # Try YAML if JSON failed
+    if raw is None:
+        try:
+            raw = _load_yaml(text)
+        except Exception:
+            pass
+
+    if raw is None:
+        raise ValueError(f"Could not parse input as JSON or YAML: {source_label}")
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"Expected dict, got {type(raw).__name__}: {source_label}")
+
+    # Normalize based on event_type or service field
+    event_type = raw.get('event_type', raw.get('type', 'unknown'))
+    # YAML inbox items use 'service' field instead of 'event_type'
+    service = raw.get('service', '')
+    if event_type == 'unknown' and service:
+        if service == 'slack':
+            event_type = 'dm'  # Treat as DM for fact extraction
+        elif service == 'gmail':
+            event_type = 'email'
+        elif service == 'calendar':
+            event_type = 'calendar'
+
+    result = {
+        'source_type': 'unknown',
+        'timestamp': '',
+        'sender_name': None,
+        'sender_email': None,
+        'sender_slack_id': None,
+        'channel': None,
+        'subject': None,
+        'content': '',
+        'raw': raw,
+        'source_file': source_label,
+    }
+
+    if event_type in ('dm', 'thread_reply', 'channel_message'):
+        result['source_type'] = 'slack'
+        slack_event = raw.get('slack_event', {})
+        result['timestamp'] = raw.get('timestamp', raw.get('received_at', ''))
+        result['sender_slack_id'] = slack_event.get('user', raw.get('sender'))
+        result['content'] = slack_event.get('text', raw.get('content', ''))
+        result['channel'] = slack_event.get('channel', raw.get('channel', ''))
+        # For YAML format inbox items
+        sender = raw.get('sender', '')
+        if sender:
+            result['sender_name'] = sender.replace('-', ' ').title()
+        # Check for subject in YAML format
+        result['subject'] = raw.get('subject')
+
+    elif event_type == 'email':
+        result['source_type'] = 'email'
+        email_data = raw.get('email', {})
+        result['timestamp'] = email_data.get('date', raw.get('received_at', raw.get('timestamp', '')))
+        from_field = email_data.get('from', '')
+        result['sender_name'], result['sender_email'] = _parse_email_from(from_field)
+        result['subject'] = email_data.get('subject', '')
+        result['content'] = email_data.get('body', email_data.get('snippet', raw.get('content', '')))
+
+    elif event_type in ('calendar', 'meeting'):
+        result['source_type'] = event_type
+        result['timestamp'] = raw.get('timestamp', raw.get('start_time', raw.get('date', '')))
+        result['subject'] = raw.get('subject', raw.get('title', raw.get('summary', '')))
+        result['content'] = raw.get('content', raw.get('description', raw.get('notes', '')))
+        # Calendar events may have attendees
+        attendees = raw.get('attendees', [])
+        if attendees and isinstance(attendees, list):
+            # Store first attendee as sender for context
+            att = attendees[0]
+            if isinstance(att, dict):
+                result['sender_email'] = att.get('email', '')
+                result['sender_name'] = att.get('name', att.get('displayName', ''))
+            elif isinstance(att, str):
+                if '@' in att:
+                    result['sender_email'] = att
+                else:
+                    result['sender_name'] = att
+
+    elif event_type == 'priority_trigger':
+        result['source_type'] = 'slack'
+        result['timestamp'] = raw.get('timestamp', '')
+        sender = raw.get('sender', '')
+        if sender:
+            result['sender_name'] = sender.replace('-', ' ').title()
+        result['channel'] = raw.get('channel', '')
+        result['content'] = raw.get('content', '')
+        result['subject'] = raw.get('reason', '')
+
+    return result
+
+
+def _parse_email_from(from_field):
+    """Parse an email From header into (name, email).
+
+    Examples:
+      'Nima Masroori <nima@adaptic.ai>' -> ('Nima Masroori', 'nima@adaptic.ai')
+      '"Zapier" <learn@send.zapier.com>' -> ('Zapier', 'learn@send.zapier.com')
+      'jane@example.com' -> (None, 'jane@example.com')
+    """
+    if not from_field:
+        return None, None
+
+    # Pattern: "Name" <email> or Name <email>
+    match = re.match(r'^"?([^"<]+?)"?\s*<([^>]+)>', from_field.strip())
+    if match:
+        name = match.group(1).strip().strip('"')
+        email = match.group(2).strip()
+        # Handle calendar notification format: "user@domain.com (Google Calendar)"
+        # The "name" portion is actually an email, and the real email is calendar-noreply
+        if '(Google Calendar)' in name or '(Calendar)' in name:
+            # This is a calendar notification — extract the real email from the name portion
+            real_email_match = re.match(r'([^\s@]+@[^\s@]+\.[^\s@]+)', name)
+            if real_email_match:
+                return None, real_email_match.group(1)
+            return None, email
+        return name, email
+
+    # Bare email
+    match = re.match(r'^([^\s@]+@[^\s@]+\.[^\s@]+)$', from_field.strip())
+    if match:
+        return None, match.group(1)
+
+    return None, None
+
+
+# ─────────────────────────────────────────────
+# Fact extraction engine
+# ─────────────────────────────────────────────
+class ExtractedFact:
+    """Represents a single fact extracted from an interaction."""
+
+    def __init__(self, fact_type, data, source_ref, confidence='extracted'):
+        self.fact_type = fact_type  # 'new_entity', 'new_relationship', 'entity_update'
+        self.data = data           # dict with the actual data
+        self.source_ref = source_ref
+        self.confidence = confidence
+
+    def __repr__(self):
+        return f"ExtractedFact({self.fact_type}, {self.data.get('id', self.data.get('name', '?'))})"
+
+
+def extract_facts(interaction, lookups):
+    """Extract new entities, relationships, and updates from an interaction.
+
+    Args:
+        interaction: Normalized interaction dict (from parse_input_text)
+        lookups: Entity index lookup dicts (from build_lookups)
+
+    Returns:
+        list of ExtractedFact objects
+    """
+    facts = []
+    now_iso = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+    source_file = interaction.get('source_file', 'unknown')
+
+    # Build source reference
+    source_ref = _build_source_ref(interaction)
+
+    # --- Extract from email sender ---
+    if interaction['source_type'] == 'email':
+        sender_name = interaction.get('sender_name')
+        sender_email = interaction.get('sender_email')
+
+        if sender_email and sender_email.lower() not in lookups['by_email']:
+            # Skip automated/noreply senders
+            if not _is_automated_sender(sender_email, sender_name):
+                person_id = _generate_person_id(sender_name, sender_email)
+
+                # Quality check: only create person entity if name looks real
+                if not _is_low_quality_person_name(sender_name):
+                    entity_data = {
+                        'id': person_id,
+                        'type': 'person',
+                        'name': sender_name or _name_from_email(sender_email),
+                        'email': sender_email,
+                        'confidence': 'extracted',
+                        'first_seen': now_iso,
+                        'source': source_ref,
+                    }
+                    if sender_name:
+                        entity_data['aliases'] = [sender_name.split()[0]] if ' ' in sender_name else []
+
+                    # Only add if id not already present
+                    if person_id not in lookups['by_id']:
+                        facts.append(ExtractedFact('new_entity', entity_data, source_ref))
+
+                    # Try to extract company from email domain
+                    company_fact = _extract_company_from_email(sender_email, sender_name, lookups, source_ref, now_iso)
+                    if company_fact:
+                        facts.append(company_fact)
+
+                    # Create employment relationship if we can infer company
+                    emp_fact = _extract_employment_from_email(person_id, sender_email, lookups, source_ref)
+                    if emp_fact:
+                        facts.append(emp_fact)
+
+        elif sender_email and sender_email.lower() in lookups['by_email']:
+            # Known entity — check for updates
+            existing = lookups['by_email'][sender_email.lower()]
+            updates = _check_entity_updates(existing, interaction, source_ref)
+            facts.extend(updates)
+
+    # --- Extract from email subject ---
+    subject = interaction.get('subject', '') or ''
+    content = interaction.get('content', '') or ''
+    combined_text = f"{subject} {content}"
+
+    # Extract email addresses mentioned in content
+    email_facts = _extract_emails_from_text(combined_text, lookups, source_ref, now_iso)
+    facts.extend(email_facts)
+
+    # Extract phone numbers mentioned in content
+    phone_facts = _extract_phones_from_text(combined_text, lookups, source_ref)
+    facts.extend(phone_facts)
+
+    # Extract role/title mentions for known entities
+    title_facts = _extract_title_updates(combined_text, lookups, source_ref)
+    facts.extend(title_facts)
+
+    return facts
+
+
+def _build_source_ref(interaction):
+    """Build a source reference string from interaction metadata."""
+    parts = [interaction.get('source_type', 'unknown')]
+    ts = interaction.get('timestamp', '')
+    if ts:
+        # Normalize timestamp to date portion
+        date_match = re.match(r'(\d{4}-\d{2}-\d{2})', str(ts))
+        if date_match:
+            parts.append(date_match.group(1))
+        else:
+            parts.append(str(ts)[:20])
+
+    sender = interaction.get('sender_name') or interaction.get('sender_email') or ''
+    if sender:
+        parts.append(sender)
+
+    source_file = interaction.get('source_file', '')
+    if source_file:
+        # Use just the filename, not full path
+        parts.append(Path(source_file).name)
+
+    return ' | '.join(parts)
+
+
+def _is_automated_sender(email, name):
+    """Check if this sender is an automated system (newsletters, notifications)."""
+    if not email:
+        return True
+
+    email_lower = email.lower()
+    automated_patterns = [
+        'noreply', 'no-reply', 'donotreply', 'notifications',
+        'mailer-daemon', 'postmaster', 'newsletter', 'updates@',
+        'info@send.', 'learn@send.', 'digest@', 'alerts@',
+        'support@', 'system@', 'admin@', 'bounce',
+        'calendar-notification', 'calendar-server',
+        'invite@', 'notify@', 'team@',
+    ]
+    for pattern in automated_patterns:
+        if pattern in email_lower:
+            return True
+
+    automated_domains = [
+        'sparkpostmail.com', 'sendgrid.net', 'mailchimp.com',
+        'intercom-mail.com', 'mandrillapp.com', 'amazonses.com',
+        'postmarkapp.com', 'mailgun.org', 'railway.app',
+        'calendar.google.com', 'google.com', 'airtable.com',
+        'anthropic.com', 'gamma.app', 'calendly.com',
+        'notion.so', 'linear.app', 'slack.com',
+        'figma.com', 'github.com', 'atlassian.com',
+        'stripe.com', 'twilio.com', 'hubspot.com',
+        'consensus.app', 'superhuman.com',
+    ]
+    domain = email_lower.split('@')[-1] if '@' in email_lower else ''
+    for ad in automated_domains:
+        if domain.endswith(ad):
+            return True
+
+    # Skip subdomains of known services (e.g. notify.railway.app, send.calendly.com)
+    domain_parts = domain.split('.')
+    service_roots = {
+        'railway', 'google', 'airtable', 'anthropic', 'gamma',
+        'calendly', 'notion', 'linear', 'slack', 'figma',
+        'github', 'atlassian', 'stripe', 'twilio', 'hubspot',
+        'consensus', 'superhuman', 'zapier',
+    }
+    for part in domain_parts:
+        if part in service_roots:
+            return True
+
+    # Skip common automated service senders
+    if name:
+        name_lower = name.lower()
+        automated_names = [
+            'zapier', 'slack', 'google', 'github', 'notion', 'linear',
+            'railway', 'airtable', 'anthropic', 'gamma', 'calendly',
+            'google calendar', 'the airtable team', 'stripe',
+        ]
+        # Check exact match and prefix match
+        if name_lower in automated_names:
+            return True
+        # Check if name contains service-like patterns
+        for an in automated_names:
+            if an in name_lower:
+                return True
+        # Names with "from" pattern like "Christian From Consensus"
+        if ' from ' in name_lower:
+            return True
+        # Names that are just a single word and look like a service
+        if len(name_lower.split()) == 1 and name_lower in service_roots:
+            return True
+
+    return False
+
+
+def _is_low_quality_person_name(name):
+    """Check if a name looks like it's not a real person name.
+
+    Filters out single generic words, service names, and names with
+    special patterns that indicate non-person senders.
+    """
+    if not name:
+        return True
+
+    name_stripped = name.strip()
+    if not name_stripped:
+        return True
+
+    # Names containing commas with corporate suffixes (e.g. "Anthropic, PBC")
+    if re.search(r',\s*(PBC|LLC|Inc|Ltd|Corp|GmbH|SA|BV)', name_stripped, re.IGNORECASE):
+        return True
+
+    # Single-word names that are generic/ambiguous
+    words = name_stripped.split()
+    if len(words) == 1:
+        generic_singles = {
+            'info', 'admin', 'support', 'team', 'hello', 'contact',
+            'speakers', 'events', 'news', 'updates', 'billing',
+            'sales', 'marketing', 'hr', 'legal', 'finance',
+            'ops', 'operations', 'engineering', 'product',
+            'security', 'compliance', 'risk', 'audit',
+        }
+        if words[0].lower() in generic_singles:
+            return True
+
+    # Names starting with "The" (e.g. "The Airtable Team")
+    if name_stripped.lower().startswith('the '):
+        return True
+
+    return False
+
+
+def _generate_person_id(name, email):
+    """Generate a person entity ID from name or email.
+
+    Follows existing convention: person:firstname-lastname
+    """
+    if name:
+        parts = name.lower().split()
+        if len(parts) >= 2:
+            slug = f"{parts[0]}-{parts[-1]}"
+        elif parts:
+            slug = parts[0]
+        else:
+            slug = email.split('@')[0].replace('.', '-') if email else 'unknown'
+    elif email:
+        slug = email.split('@')[0].replace('.', '-').replace('_', '-')
+    else:
+        return 'person:unknown'
+
+    # Clean slug
+    slug = re.sub(r'[^a-z0-9-]', '', slug)
+    return f"person:{slug}"
+
+
+def _generate_company_id(name):
+    """Generate a company entity ID from name."""
+    slug = name.lower()
+    slug = re.sub(r'[^a-z0-9\s-]', '', slug)
+    slug = re.sub(r'\s+', '-', slug.strip())
+    slug = re.sub(r'-+', '-', slug)
+    return f"company:{slug}"
+
+
+def _name_from_email(email):
+    """Derive a display name from an email address."""
+    if not email:
+        return 'Unknown'
+    local = email.split('@')[0]
+    # Handle formats: first.last, first_last, firstlast
+    parts = re.split(r'[._]', local)
+    return ' '.join(p.capitalize() for p in parts if p)
+
+
+def _extract_company_from_email(email, sender_name, lookups, source_ref, now_iso):
+    """Try to extract a company entity from an email domain.
+
+    Returns an ExtractedFact for a new company, or None.
+    """
+    if not email or '@' in email is False:
+        return None
+
+    domain = email.lower().split('@')[-1]
+
+    # Skip common personal/free email providers
+    free_providers = {
+        'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com',
+        'icloud.com', 'me.com', 'aol.com', 'protonmail.com',
+        'live.com', 'msn.com', 'mail.com', 'zoho.com',
+    }
+    if domain in free_providers:
+        return None
+
+    # Skip Adaptic domains (already known)
+    if 'adaptic' in domain:
+        return None
+
+    # Derive company name from domain
+    domain_prefix = domain.split('.')[0]
+    company_name = domain_prefix.replace('-', ' ').title()
+
+    # Check if this company domain already maps to a known entity:
+    # 1. Exact email domain match on any entity
+    # 2. Domain prefix starts with or equals a known company name word (>= 4 chars)
+    # 3. Existing entity has this domain in its email
+    domain_prefix_lower = domain_prefix.lower()
+    for entity in lookups.get('by_id', {}).values():
+        if not isinstance(entity, dict):
+            continue
+        # Check email domain match
+        existing_email = entity.get('email', '')
+        if existing_email and isinstance(existing_email, str):
+            existing_domain = existing_email.lower().split('@')[-1] if '@' in existing_email else ''
+            if existing_domain == domain:
+                return None  # Company already represented
+        # Check domain-to-company-name fuzzy match (for known companies only)
+        if entity.get('type') == 'company':
+            ename = (entity.get('name') or '').lower()
+            ename_slug = re.sub(r'[^a-z0-9]', '', ename)
+            # Require domain prefix to START with the company name slug
+            # or the company name slug to START with the domain prefix
+            # This avoids "inc" in "evolveinteriors" false positive
+            if len(ename_slug) >= 4 and (
+                domain_prefix_lower.startswith(ename_slug) or
+                ename_slug.startswith(domain_prefix_lower)
+            ):
+                return None  # Fuzzy match to existing entity
+            # Also check each significant word (>= 5 chars to avoid short word collisions)
+            ename_words = re.sub(r'[^a-z0-9\s]', '', ename).split()
+            for word in ename_words:
+                if len(word) >= 5 and domain_prefix_lower.startswith(word):
+                    return None
+            # Also check aliases
+            for alias in (entity.get('aliases', []) or []):
+                if isinstance(alias, str) and len(alias) >= 4:
+                    alias_slug = re.sub(r'[^a-z0-9]', '', alias.lower())
+                    if domain_prefix_lower.startswith(alias_slug) or alias_slug.startswith(domain_prefix_lower):
+                        return None
+
+    company_id = _generate_company_id(company_name)
+
+    # Check if company id already exists
+    if company_id in lookups['by_id']:
+        return None
+    if company_name.lower() in lookups['by_name']:
+        return None
+
+    return ExtractedFact('new_entity', {
+        'id': company_id,
+        'type': 'company',
+        'name': company_name,
+        'domain': domain,
+        'confidence': 'extracted',
+        'first_seen': now_iso,
+        'source': source_ref,
+    }, source_ref)
+
+
+def _extract_employment_from_email(person_id, email, lookups, source_ref):
+    """Try to infer an employment relationship from email domain.
+
+    Returns an ExtractedFact for a new relationship, or None.
+    """
+    if not email or '@' not in email:
+        return None
+
+    domain = email.lower().split('@')[-1]
+
+    # Skip free providers
+    free_providers = {
+        'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com',
+        'icloud.com', 'me.com', 'aol.com', 'protonmail.com',
+        'live.com', 'msn.com', 'mail.com', 'zoho.com',
+    }
+    if domain in free_providers:
+        return None
+
+    # Find company entity matching this domain via multiple strategies
+    domain_prefix = domain.split('.')[0].lower()
+    company_id = None
+    for entity in lookups.get('by_id', {}).values():
+        if not isinstance(entity, dict):
+            continue
+        if entity.get('type') != 'company':
+            continue
+        # Strategy 1: Exact domain field match
+        entity_domain = entity.get('domain', '')
+        if entity_domain == domain:
+            company_id = entity['id']
+            break
+        # Strategy 2: Email domain match on any entity email
+        existing_email = entity.get('email', '')
+        if existing_email and isinstance(existing_email, str):
+            if '@' in existing_email and existing_email.lower().split('@')[-1] == domain:
+                company_id = entity['id']
+                break
+        # Strategy 3: Fuzzy match — domain prefix starts with company slug or vice versa
+        ename = (entity.get('name') or '').lower()
+        ename_slug = re.sub(r'[^a-z0-9]', '', ename)
+        if len(ename_slug) >= 4 and (
+            domain_prefix.startswith(ename_slug) or
+            ename_slug.startswith(domain_prefix)
+        ):
+            company_id = entity['id']
+            break
+        # Check significant words (>= 5 chars)
+        ename_words = re.sub(r'[^a-z0-9\s]', '', ename).split()
+        for word in ename_words:
+            if len(word) >= 5 and domain_prefix.startswith(word):
+                company_id = entity['id']
+                break
+        if company_id:
+            break
+
+    # Also check if the company id we'd generate already exists
+    if not company_id:
+        company_name = domain.split('.')[0].replace('-', ' ').title()
+        candidate_id = _generate_company_id(company_name)
+        if candidate_id in lookups['by_id']:
+            company_id = candidate_id
+
+    if not company_id:
+        return None
+
+    # Generate relationship id
+    person_slug = person_id.replace('person:', '')
+    company_slug = company_id.replace('company:', '')
+    rel_id = f"rel:{person_slug}-{company_slug}-employed"
+
+    if rel_id in lookups['rel_ids']:
+        return None
+
+    return ExtractedFact('new_relationship', {
+        'id': rel_id,
+        'subject': person_id,
+        'predicate': 'employed_by',
+        'object': company_id,
+        'status': 'inferred',
+        'confidence': 'extracted',
+        'source': {
+            'type': 'interaction',
+            'ref': source_ref,
+            'confidence': 'medium',
+        },
+        'notes': f"Inferred from email domain ({domain}).",
+    }, source_ref)
+
+
+def _check_entity_updates(existing, interaction, source_ref):
+    """Check if interaction reveals updated info for a known entity.
+
+    Only updates fields that are currently empty or adds new info.
+    NEVER overwrites verified facts with extracted ones.
+
+    Returns list of ExtractedFact with type 'entity_update'.
+    """
+    facts = []
+
+    # Check if we now know a phone number that was previously missing
+    content = interaction.get('content', '') or ''
+    subject = interaction.get('subject', '') or ''
+    combined = f"{subject} {content}"
+
+    entity_id = existing.get('id', '')
+
+    # Look for phone numbers in content that could belong to this sender
+    phone_match = re.search(r'(?:phone|mobile|cell|tel|call me)[\s:]*(\+?[\d\s()-]{10,18})', combined, re.IGNORECASE)
+    if phone_match and not existing.get('phone') and not existing.get('mobile'):
+        phone = re.sub(r'[^\d+]', '', phone_match.group(1))
+        if len(phone) >= 10:
+            facts.append(ExtractedFact('entity_update', {
+                'entity_id': entity_id,
+                'field': 'phone',
+                'value': phone_match.group(1).strip(),
+                'confidence': 'extracted',
+                'source': source_ref,
+            }, source_ref))
+
+    return facts
+
+
+def _extract_emails_from_text(text, lookups, source_ref, now_iso):
+    """Extract email addresses mentioned in text that are not yet indexed."""
+    facts = []
+    if not text:
+        return facts
+
+    # Find all email addresses in text
+    email_pattern = r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
+    found_emails = set(re.findall(email_pattern, text))
+
+    for email in found_emails:
+        email_lower = email.lower()
+        if email_lower in lookups['by_email']:
+            continue
+        if _is_automated_sender(email, None):
+            continue
+        # Skip Adaptic emails — likely already known or will be added manually
+        if 'adaptic' in email_lower:
+            continue
+
+        # Derive name and check quality — skip generic local parts
+        derived_name = _name_from_email(email)
+        if _is_low_quality_person_name(derived_name):
+            continue
+
+        # Skip if the local part itself is a generic role/function
+        local_part = email_lower.split('@')[0]
+        generic_locals = {
+            'info', 'admin', 'support', 'team', 'hello', 'contact',
+            'speakers', 'events', 'news', 'updates', 'billing',
+            'sales', 'marketing', 'hr', 'legal', 'finance',
+            'office', 'enquiries', 'inquiries', 'general',
+            'accounts', 'reception', 'helpdesk', 'service',
+        }
+        if local_part in generic_locals:
+            continue
+
+        person_id = _generate_person_id(None, email)
+        if person_id in lookups['by_id']:
+            continue
+
+        facts.append(ExtractedFact('new_entity', {
+            'id': person_id,
+            'type': 'person',
+            'name': _name_from_email(email),
+            'email': email,
+            'confidence': 'extracted',
+            'first_seen': now_iso,
+            'source': source_ref,
+            'notes': 'Auto-extracted from message content. Name derived from email — verify.',
+        }, source_ref))
+
+    return facts
+
+
+def _extract_phones_from_text(text, lookups, source_ref):
+    """Extract phone numbers from text and try to match to known entities."""
+    facts = []
+    if not text:
+        return facts
+
+    # Find phone patterns: +971 XX XXX XXXX, (XXX) XXX-XXXX, etc.
+    phone_pattern = r'\+?\d[\d\s()-]{9,17}\d'
+    matches = re.findall(phone_pattern, text)
+
+    for phone_raw in matches:
+        phone_clean = re.sub(r'[^\d+]', '', phone_raw)
+        if len(phone_clean) < 10:
+            continue
+
+        # Check if any existing entity already has this phone
+        already_known = False
+        for entity in lookups['by_id'].values():
+            if not isinstance(entity, dict):
+                continue
+            for field in ('phone', 'mobile'):
+                existing_phone = entity.get(field, '')
+                if existing_phone:
+                    existing_clean = re.sub(r'[^\d+]', '', str(existing_phone))
+                    if existing_clean == phone_clean:
+                        already_known = True
+                        break
+            if already_known:
+                break
+
+        # We don't create entities just from phone numbers — too ambiguous
+        # But we could flag them for manual review if needed
+
+    return facts
+
+
+def _extract_title_updates(text, lookups, source_ref):
+    """Look for title/role mentions that could update known entities.
+
+    Patterns: "X, Title at Company" or "X (Title)" in signatures.
+    """
+    facts = []
+    if not text:
+        return facts
+
+    # Common patterns in email signatures / introductions
+    # "FirstName LastName, Title" or "FirstName LastName | Title"
+    sig_patterns = [
+        r'(?:^|\n)\s*([A-Z][a-z]+\s+[A-Z][a-z]+)\s*[,|]\s*([A-Z][A-Za-z\s&/-]+?)(?:\n|$)',
+        r'(?:^|\n)\s*([A-Z][a-z]+\s+[A-Z][a-z]+)\s*\n\s*([A-Z][A-Za-z\s&/-]+?)(?:\n|$)',
+    ]
+
+    for pattern in sig_patterns:
+        matches = re.finditer(pattern, text)
+        for match in matches:
+            person_name = match.group(1).strip()
+            title = match.group(2).strip()
+
+            # Must be a known entity
+            entity = lookups['by_name'].get(person_name.lower())
+            if not entity:
+                continue
+
+            existing_role = entity.get('primary_role', '')
+            # Only suggest update if role is empty or meaningfully different
+            if existing_role and existing_role.lower().strip() == title.lower().strip():
+                continue
+            if not title or len(title) < 3 or len(title) > 60:
+                continue
+
+            # Don't overwrite verified roles
+            if existing_role:
+                continue
+
+            facts.append(ExtractedFact('entity_update', {
+                'entity_id': entity.get('id', ''),
+                'field': 'primary_role',
+                'value': title,
+                'confidence': 'extracted',
+                'source': source_ref,
+            }, source_ref))
+
+    return facts
+
+
+# ─────────────────────────────────────────────
+# Index update application
+# ─────────────────────────────────────────────
+def apply_facts(data, facts, lookups, dry_run=False):
+    """Apply extracted facts to the entity index data.
+
+    Follows safety rules:
+      - NEVER removes existing entries
+      - NEVER overrides verified facts with extracted ones
+      - Idempotent — duplicate facts are skipped
+      - New entries marked with confidence: extracted
+
+    Args:
+        data: The full entity index dict (will be mutated)
+        facts: List of ExtractedFact objects
+        lookups: Current lookup dicts (will be updated as we go)
+        dry_run: If True, just report what would happen
+
+    Returns:
+        dict with: entities_added, relationships_added, entities_updated, skipped
+    """
+    stats = {
+        'entities_added': 0,
+        'relationships_added': 0,
+        'entities_updated': 0,
+        'skipped': 0,
+        'details': [],
+    }
+
+    for fact in facts:
+        if fact.fact_type == 'new_entity':
+            entity_data = fact.data
+            eid = entity_data.get('id', '')
+
+            # Idempotency check — skip if already exists
+            if eid in lookups['by_id']:
+                stats['skipped'] += 1
+                continue
+
+            email = entity_data.get('email', '')
+            if email and email.lower() in lookups['by_email']:
+                stats['skipped'] += 1
+                continue
+
+            name = entity_data.get('name', '')
+            if name and name.lower() in lookups['by_name']:
+                stats['skipped'] += 1
+                continue
+
+            # Format the entity for YAML (matching existing schema)
+            new_entity = {'id': eid, 'type': entity_data.get('type', 'person')}
+            if entity_data.get('name'):
+                new_entity['name'] = entity_data['name']
+            if entity_data.get('aliases'):
+                new_entity['aliases'] = entity_data['aliases']
+            if entity_data.get('email'):
+                new_entity['email'] = entity_data['email']
+            if entity_data.get('domain'):
+                new_entity['domain'] = entity_data['domain']
+            if entity_data.get('primary_role'):
+                new_entity['primary_role'] = entity_data['primary_role']
+            if entity_data.get('primary_company'):
+                new_entity['primary_company'] = entity_data['primary_company']
+            new_entity['confidence'] = 'extracted'
+            new_entity['first_seen'] = entity_data.get('first_seen', datetime.now(timezone.utc).isoformat())
+            new_entity['extraction_source'] = fact.source_ref
+            if entity_data.get('notes'):
+                new_entity['notes'] = entity_data['notes']
+
+            if not dry_run:
+                data['entities'].append(new_entity)
+
+            # Always update lookups (even in dry-run) to prevent duplicates across files
+            lookups['by_id'][eid] = new_entity
+            if name:
+                lookups['by_name'][name.lower()] = new_entity
+            if email:
+                lookups['by_email'][email.lower()] = new_entity
+
+            stats['entities_added'] += 1
+            stats['details'].append(f"+ Entity: {entity_data.get('name', eid)} ({entity_data.get('type', '?')})")
+
+        elif fact.fact_type == 'new_relationship':
+            rel_data = fact.data
+            rel_id = rel_data.get('id', '')
+
+            # Idempotency check
+            if rel_id in lookups['rel_ids']:
+                stats['skipped'] += 1
+                continue
+
+            new_rel = {
+                'id': rel_id,
+                'subject': rel_data.get('subject', ''),
+                'predicate': rel_data.get('predicate', ''),
+                'object': rel_data.get('object', ''),
+                'status': rel_data.get('status', 'inferred'),
+                'confidence': 'extracted',
+            }
+            if rel_data.get('role'):
+                new_rel['role'] = rel_data['role']
+            if rel_data.get('scope'):
+                new_rel['scope'] = rel_data['scope']
+            if rel_data.get('source'):
+                new_rel['source'] = rel_data['source']
+            if rel_data.get('notes'):
+                new_rel['notes'] = rel_data['notes']
+
+            if not dry_run:
+                data['relationships'].append(new_rel)
+
+            # Always update lookups (even in dry-run) to prevent duplicates
+            lookups['rel_ids'].add(rel_id)
+
+            stats['relationships_added'] += 1
+            stats['details'].append(
+                f"+ Relationship: {rel_data.get('subject', '?')} "
+                f"--[{rel_data.get('predicate', '?')}]--> "
+                f"{rel_data.get('object', '?')}"
+            )
+
+        elif fact.fact_type == 'entity_update':
+            update = fact.data
+            entity_id = update.get('entity_id', '')
+            field = update.get('field', '')
+            value = update.get('value', '')
+
+            entity = lookups['by_id'].get(entity_id)
+            if not entity:
+                stats['skipped'] += 1
+                continue
+
+            # Safety: never overwrite existing verified data
+            existing_value = entity.get(field, '')
+            if existing_value and entity.get('confidence', 'verified') != 'extracted':
+                stats['skipped'] += 1
+                continue
+
+            if not dry_run:
+                entity[field] = value
+                # Find and update in the entities list
+                for i, e in enumerate(data['entities']):
+                    if isinstance(e, dict) and e.get('id') == entity_id:
+                        data['entities'][i][field] = value
+                        break
+
+            stats['entities_updated'] += 1
+            stats['details'].append(f"~ Update: {entity_id}.{field} = {value}")
+
+        else:
+            stats['skipped'] += 1
+
+    return stats
+
+
+# ─────────────────────────────────────────────
+# YAML file writing — preserves existing structure
+# ─────────────────────────────────────────────
+def write_entity_index(data):
+    """Write the entity index back to YAML, preserving the general structure.
+
+    Uses PyYAML's dump but with careful formatting to match the existing style
+    as closely as possible.
+    """
+    # Update metadata
+    data['last_updated'] = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+    data['last_updated_by'] = 'post-interaction-indexer'
+
+    # We need to write the YAML preserving comments and structure.
+    # Since PyYAML strips comments, we use a hybrid approach:
+    # 1. Read the existing file
+    # 2. Append new entities and relationships at the end of their sections
+    # 3. For updates, do targeted text replacement
+
+    if not ENTITY_INDEX_PATH.exists():
+        # Fresh write
+        output = _dump_yaml(data)
+        ENTITY_INDEX_PATH.write_text(output, encoding='utf-8')
+        _invalidate_cache()
+        return
+
+    existing_text = ENTITY_INDEX_PATH.read_text(encoding='utf-8')
+
+    # Update last_updated timestamp in-place
+    existing_text = re.sub(
+        r'^last_updated:.*$',
+        f'last_updated: "{data["last_updated"]}"',
+        existing_text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    existing_text = re.sub(
+        r'^last_updated_by:.*$',
+        f'last_updated_by: {data["last_updated_by"]}',
+        existing_text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+
+    # Find new entities that need to be appended
+    # We identify them by checking which entity IDs are NOT already in the file text
+    new_entities_yaml = []
+    for entity in data.get('entities', []):
+        if not isinstance(entity, dict):
+            continue
+        eid = entity.get('id', '')
+        if not eid:
+            continue
+        # Check if this entity ID already exists in the file
+        if f"id: {eid}" in existing_text:
+            continue
+        # Format as YAML block
+        new_entities_yaml.append(_format_entity_yaml(entity))
+
+    # Find new relationships
+    new_rels_yaml = []
+    for rel in data.get('relationships', []):
+        if not isinstance(rel, dict):
+            continue
+        rid = rel.get('id', '')
+        if not rid:
+            continue
+        if f"id: {rid}" in existing_text:
+            continue
+        new_rels_yaml.append(_format_relationship_yaml(rel))
+
+    # Append new entities before the relationships section
+    if new_entities_yaml:
+        entities_block = '\n'.join(new_entities_yaml)
+        # Find the relationships section marker
+        rel_marker = '# =============================================================================\n# RELATIONSHIPS'
+        if rel_marker in existing_text:
+            existing_text = existing_text.replace(
+                rel_marker,
+                f"  # ---------------------------------------------------------------------------\n"
+                f"  # Auto-extracted entities (Phase 5 indexer — {data['last_updated']})\n"
+                f"  # ---------------------------------------------------------------------------\n"
+                f"{entities_block}\n\n"
+                f"{rel_marker}",
+            )
+        else:
+            # Fallback: append before 'relationships:' line
+            existing_text = re.sub(
+                r'^(relationships:)',
+                f"  # Auto-extracted entities\n{entities_block}\n\n\\1",
+                existing_text,
+                count=1,
+                flags=re.MULTILINE,
+            )
+
+    # Append new relationships at the end of the relationships section
+    # (before any subsequent top-level section like commitments:)
+    if new_rels_yaml:
+        rels_block = '\n'.join(new_rels_yaml)
+        rels_insert = (
+            f"\n  # ---------------------------------------------------------------------------\n"
+            f"  # Auto-extracted relationships (Phase 5 indexer — {data['last_updated']})\n"
+            f"  # ---------------------------------------------------------------------------\n"
+            f"{rels_block}\n"
+        )
+
+        # Find the next top-level section after relationships:
+        # Look for patterns like "commitments:", "# ===..." followed by a top-level key
+        # We insert BEFORE the commitments section marker
+        commit_marker = '# =============================================================================\n# COMMITMENTS'
+        if commit_marker in existing_text:
+            existing_text = existing_text.replace(
+                commit_marker,
+                f"{rels_insert}\n{commit_marker}",
+            )
+        else:
+            # Try to find 'commitments:' as a top-level key
+            commitments_match = re.search(r'^commitments:\s*$', existing_text, re.MULTILINE)
+            if commitments_match:
+                # Insert before the commitments section (including its header comments)
+                # Walk backwards from the match to find the section header comments
+                insert_pos = commitments_match.start()
+                # Check for preceding comment block
+                preceding = existing_text[:insert_pos].rstrip()
+                comment_lines = []
+                for line in reversed(preceding.split('\n')):
+                    stripped = line.strip()
+                    if stripped.startswith('#') or stripped == '':
+                        comment_lines.insert(0, line)
+                    else:
+                        break
+                if comment_lines:
+                    # Find the start of the comment block
+                    comment_text = '\n'.join(comment_lines)
+                    insert_pos = existing_text.rfind(comment_text, 0, commitments_match.start())
+                    if insert_pos >= 0:
+                        existing_text = (
+                            existing_text[:insert_pos] +
+                            rels_insert + '\n' +
+                            existing_text[insert_pos:]
+                        )
+                    else:
+                        existing_text = (
+                            existing_text[:commitments_match.start()] +
+                            rels_insert + '\n' +
+                            existing_text[commitments_match.start():]
+                        )
+                else:
+                    existing_text = (
+                        existing_text[:commitments_match.start()] +
+                        rels_insert + '\n' +
+                        existing_text[commitments_match.start():]
+                    )
+            else:
+                # No commitments section — append at end
+                if not existing_text.endswith('\n'):
+                    existing_text += '\n'
+                existing_text += rels_insert
+
+    ENTITY_INDEX_PATH.write_text(existing_text, encoding='utf-8')
+    _invalidate_cache()
+
+
+def _format_entity_yaml(entity):
+    """Format a single entity as a YAML block matching the existing style."""
+    lines = []
+    lines.append(f"  - id: {entity['id']}")
+    lines.append(f"    type: {entity.get('type', 'person')}")
+    if entity.get('name'):
+        lines.append(f"    name: {entity['name']}")
+    if entity.get('aliases'):
+        aliases_str = json.dumps(entity['aliases'])
+        lines.append(f"    aliases: {aliases_str}")
+    if entity.get('primary_company'):
+        lines.append(f"    primary_company: {entity['primary_company']}")
+    if entity.get('primary_role'):
+        lines.append(f"    primary_role: {entity['primary_role']}")
+    if entity.get('email'):
+        lines.append(f"    email: {entity['email']}")
+    if entity.get('phone'):
+        lines.append(f'    phone: "{entity["phone"]}"')
+    if entity.get('timezone'):
+        lines.append(f"    timezone: {entity['timezone']}")
+    if entity.get('domain'):
+        lines.append(f"    domain: {entity['domain']}")
+    if entity.get('confidence'):
+        lines.append(f"    confidence: {entity['confidence']}")
+    if entity.get('first_seen'):
+        lines.append(f'    first_seen: "{entity["first_seen"]}"')
+    if entity.get('extraction_source'):
+        lines.append(f'    extraction_source: "{entity["extraction_source"]}"')
+    if entity.get('notes'):
+        # Escape quotes in notes
+        notes = str(entity['notes']).replace('"', '\\"')
+        lines.append(f'    notes: "{notes}"')
+    lines.append('')
+    return '\n'.join(lines)
+
+
+def _format_relationship_yaml(rel):
+    """Format a single relationship as a YAML block matching the existing style."""
+    lines = []
+    lines.append(f"  - id: {rel['id']}")
+    lines.append(f"    subject: {rel.get('subject', '')}")
+    lines.append(f"    predicate: {rel.get('predicate', '')}")
+    lines.append(f"    object: {rel.get('object', '')}")
+    lines.append(f"    status: {rel.get('status', 'inferred')}")
+    if rel.get('role'):
+        lines.append(f"    role: {rel['role']}")
+    if rel.get('scope'):
+        lines.append(f'    scope: "{rel["scope"]}"')
+    lines.append(f"    confidence: {rel.get('confidence', 'extracted')}")
+    if rel.get('source'):
+        src = rel['source']
+        if isinstance(src, dict):
+            lines.append(f"    source:")
+            lines.append(f"      type: {src.get('type', 'interaction')}")
+            ref = str(src.get('ref', '')).replace('"', '\\"')
+            lines.append(f'      ref: "{ref}"')
+            lines.append(f"      confidence: {src.get('confidence', 'medium')}")
+        else:
+            src_str = str(src).replace('"', '\\"')
+            lines.append(f'    source: "{src_str}"')
+    if rel.get('notes'):
+        notes = str(rel['notes']).replace('"', '\\"')
+        lines.append(f'    notes: "{notes}"')
+    lines.append('')
+    return '\n'.join(lines)
+
+
+def _invalidate_cache():
+    """Remove the JSON cache so it gets rebuilt on next read."""
+    try:
+        if ENTITY_INDEX_CACHE_PATH.exists():
+            ENTITY_INDEX_CACHE_PATH.unlink()
+    except Exception:
+        pass
+
+
+# ─────────────────────────────────────────────
+# Scan mode — process today's unprocessed items
+# ─────────────────────────────────────────────
+def scan_today(dry_run=False):
+    """Scan all inbox directories for today's items and process them.
+
+    Returns overall stats dict.
+    """
+    today = datetime.now(timezone.utc).strftime('%Y-%m-%d')
+    total_stats = {
+        'files_scanned': 0,
+        'files_with_facts': 0,
+        'entities_added': 0,
+        'relationships_added': 0,
+        'entities_updated': 0,
+        'skipped': 0,
+        'errors': 0,
+        'details': [],
+    }
+
+    # Load entity index once
+    data = load_entity_index()
+    lookups = build_lookups(data)
+
+    # Scan each inbox subdirectory
+    inbox_dirs = ['slack', 'gmail', 'calendar', 'internal', 'whatsapp', 'sms']
+    for subdir in inbox_dirs:
+        inbox_path = INBOX_DIR / subdir
+        if not inbox_path.exists():
+            continue
+
+        for item_file in sorted(inbox_path.iterdir()):
+            if item_file.is_dir():
+                continue
+            # Process both .json and .yaml files (including .processed ones)
+            if not (item_file.suffix in ('.json', '.yaml', '.yml') or
+                    str(item_file).endswith('.json.processed') or
+                    str(item_file).endswith('.yaml.processed') or
+                    str(item_file).endswith('.yml.processed')):
+                continue
+
+            total_stats['files_scanned'] += 1
+
+            try:
+                interaction = parse_input_file(item_file)
+                facts = extract_facts(interaction, lookups)
+                if facts:
+                    total_stats['files_with_facts'] += 1
+                    result = apply_facts(data, facts, lookups, dry_run=dry_run)
+                    total_stats['entities_added'] += result['entities_added']
+                    total_stats['relationships_added'] += result['relationships_added']
+                    total_stats['entities_updated'] += result['entities_updated']
+                    total_stats['skipped'] += result['skipped']
+                    total_stats['details'].extend(result['details'])
+            except Exception as e:
+                total_stats['errors'] += 1
+                total_stats['details'].append(f"! Error processing {item_file.name}: {e}")
+
+    # Also scan the processed directory
+    if PROCESSED_DIR.exists():
+        for item_file in sorted(PROCESSED_DIR.iterdir()):
+            if item_file.is_dir():
+                continue
+            if not (item_file.suffix in ('.json', '.yaml', '.yml') or
+                    str(item_file).endswith('.json.processed')):
+                continue
+
+            total_stats['files_scanned'] += 1
+
+            try:
+                interaction = parse_input_file(item_file)
+                facts = extract_facts(interaction, lookups)
+                if facts:
+                    total_stats['files_with_facts'] += 1
+                    result = apply_facts(data, facts, lookups, dry_run=dry_run)
+                    total_stats['entities_added'] += result['entities_added']
+                    total_stats['relationships_added'] += result['relationships_added']
+                    total_stats['entities_updated'] += result['entities_updated']
+                    total_stats['skipped'] += result['skipped']
+                    total_stats['details'].extend(result['details'])
+            except Exception as e:
+                total_stats['errors'] += 1
+                total_stats['details'].append(f"! Error processing {item_file.name}: {e}")
+
+    # Write updates if not dry run
+    if not dry_run and (total_stats['entities_added'] > 0 or
+                        total_stats['relationships_added'] > 0 or
+                        total_stats['entities_updated'] > 0):
+        write_entity_index(data)
+
+    return total_stats
+
+
+# ─────────────────────────────────────────────
+# CLI entry point
+# ─────────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser(
+        description='Post-interaction auto-indexer — extract entities and relationships from interactions.'
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument('--input', dest='input_file',
+                       help='Path to an inbox item file (JSON or YAML)')
+    group.add_argument('--scan-today', action='store_true',
+                       help='Scan all inbox directories for items to process')
+    group.add_argument('--stdin', action='store_true',
+                       help='Read interaction data from stdin')
+
+    parser.add_argument('--dry-run', action='store_true',
+                        help='Show what would be extracted without writing to index')
+
+    args = parser.parse_args()
+
+    t0 = time.time()
+
+    try:
+        if args.scan_today:
+            # Scan mode
+            stats = scan_today(dry_run=args.dry_run)
+            elapsed = round((time.time() - t0) * 1000, 1)
+
+            prefix = "[DRY RUN] " if args.dry_run else ""
+            print(f"{prefix}Post-interaction indexer — scan complete")
+            print(f"  Files scanned:       {stats['files_scanned']}")
+            print(f"  Files with new facts: {stats['files_with_facts']}")
+            print(f"  Entities added:      {stats['entities_added']}")
+            print(f"  Relationships added: {stats['relationships_added']}")
+            print(f"  Entities updated:    {stats['entities_updated']}")
+            print(f"  Skipped (dupes):     {stats['skipped']}")
+            if stats['errors']:
+                print(f"  Errors:              {stats['errors']}")
+            print(f"  Elapsed:             {elapsed}ms")
+
+            if stats['details']:
+                print(f"\n  Changes:")
+                for detail in stats['details']:
+                    print(f"    {detail}")
+
+            if stats['entities_added'] > 0 or stats['relationships_added'] > 0 or stats['entities_updated'] > 0:
+                sys.exit(0)
+            else:
+                sys.exit(1)
+
+        else:
+            # Single item mode
+            if args.stdin:
+                text = sys.stdin.read()
+                interaction = parse_input_text(text, 'stdin')
+            else:
+                interaction = parse_input_file(args.input_file)
+
+            # Load index
+            data = load_entity_index()
+            lookups = build_lookups(data)
+
+            # Extract facts
+            facts = extract_facts(interaction, lookups)
+            elapsed_extract = round((time.time() - t0) * 1000, 1)
+
+            if not facts:
+                prefix = "[DRY RUN] " if args.dry_run else ""
+                print(f"{prefix}No new facts extracted from interaction.")
+                print(f"  Source: {interaction.get('source_type', '?')} | "
+                      f"Sender: {interaction.get('sender_name') or interaction.get('sender_email') or 'unknown'}")
+                print(f"  Elapsed: {elapsed_extract}ms")
+                sys.exit(1)
+
+            # Apply facts
+            stats = apply_facts(data, facts, lookups, dry_run=args.dry_run)
+
+            # Write if not dry run
+            if not args.dry_run and (stats['entities_added'] > 0 or
+                                     stats['relationships_added'] > 0 or
+                                     stats['entities_updated'] > 0):
+                write_entity_index(data)
+
+            elapsed_total = round((time.time() - t0) * 1000, 1)
+
+            prefix = "[DRY RUN] " if args.dry_run else ""
+            print(f"{prefix}Post-interaction indexer — extraction complete")
+            print(f"  Source: {interaction.get('source_type', '?')} | "
+                  f"Sender: {interaction.get('sender_name') or interaction.get('sender_email') or 'unknown'}")
+            print(f"  Facts extracted:     {len(facts)}")
+            print(f"  Entities added:      {stats['entities_added']}")
+            print(f"  Relationships added: {stats['relationships_added']}")
+            print(f"  Entities updated:    {stats['entities_updated']}")
+            print(f"  Skipped (dupes):     {stats['skipped']}")
+            print(f"  Elapsed:             {elapsed_total}ms")
+
+            if stats['details']:
+                print(f"\n  Changes:")
+                for detail in stats['details']:
+                    print(f"    {detail}")
+
+            if stats['entities_added'] > 0 or stats['relationships_added'] > 0 or stats['entities_updated'] > 0:
+                sys.exit(0)
+            else:
+                sys.exit(1)
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == '__main__':
+    main()