# Document metadata extraction & temporal queries

## Description

Add metadata extraction during indexing to enable smart queries like 'documents I wrote this week'.

## Feature Scope

### 1. Metadata Extraction (Ingestion)

- Extract file timestamps: mtime, ctime, indexed_at
- Auto-generate categories/tags via LLM (optional, configurable)
- Parse frontmatter metadata from markdown (tags, author, date)
- Store content type hints (code, prose, notes, meeting, etc.)

### 2. Schema Changes

- Add `document_metadata` table or columns:
  - created_at (file ctime)
  - modified_at (file mtime)
  - indexed_at (timestamp)
  - categories (JSON array)
  - tags (JSON array)
  - content_type (enum: prose, code, notes, etc.)
  - author (optional, from git or frontmatter)

### 3. Smart Query Expansion

- Temporal expansions: 'this week', 'last month', 'recent', 'today'
- Category filters: 'meeting notes', 'code documentation'
- Example queries:
  - 'documents I wrote this week' → mtime > now-7d
  - 'recent meeting notes' → category=meeting AND mtime > now-30d
  - 'old project specs' → content_type=spec AND mtime < now-6mo

### 4. CLI/API Integration

- New flags: --since, --until, --category, --tag
- Filter support in search/query commands
- Faceted results showing category/date distribution

## Design Considerations

- LLM categorization should be opt-in (cost/speed)
- Fall back to rule-based categorization (file extensions, paths)
- Git integration for author detection (optional)
- Respect user privacy - no cloud metadata extraction

## Acceptance

- [ ] Implementation complete
- [ ] Tests passing
- [ ] Documentation updated

## Done summary

Implemented document metadata extraction and temporal query filters across ingestion, store, retrieval pipelines, CLI, API, MCP, tests, and docs.

Delivered:

- New document metadata migration (v6): source_ctime, indexed_at, content_type, categories, author, frontmatter_date.
- Ingestion metadata extraction:
  - Walker now captures ctime.
  - Sync infers content type, parses frontmatter categories/author/date, persists metadata.
  - INGEST_VERSION bumped to 4 for automatic backfill re-processing.
- Temporal parsing and matching utilities:
  - Supports ISO dates and relative tokens (today, yesterday, this/last week, this/last month, recent).
  - Query text inference when explicit bounds are omitted.
- Retrieval filter support:
  - BM25, vector, and hybrid now accept/propagate since/until/categories/author.
  - Hybrid applies metadata filters consistently in candidate assembly.
- Interface updates:
  - CLI search/vsearch/query/ask: --since, --until, --category, --author.
  - MCP schemas/tools: since/until/categories/author.
  - REST API search/query/ask: since/until/category/author.
- Contract/docs updates:
  - spec/cli.md, spec/mcp.md, search-results schema, docs/CLI.md, docs/API.md, docs/MCP.md, README.md.
- Tests:
  - Added pipeline temporal unit tests.
  - Added FTS metadata filter tests (temporal/category/author).
  - Updated migration/version expectations and MCP schema tests.

## Evidence

- Commits:
- Tests:
- PRs:
