Documentation gaps: entity linking pattern, normalization contract, schema ERD, OpenAPI spec

[tinkermonkey]

Problem

Several critical system behaviors are undocumented, making the system opaque to contributors and making it impossible to reason about correctness:

1. Entity linking is documented nowhere

core/entity_linker.py is the most subtle and failure-prone part of the system, but nothing documents:

• The algorithm (fetch people → extract phones/emails from domain_metadata → JSON path query against other domains → insert entity_links)
• Which JSON paths are queried for each domain (sender, recipients — but NOT calendar attendees)
• The phone/email normalization applied before matching
• Known failure modes (phone format mismatches, silent misses)
• The intended query patterns over entity_links (there are currently none)

2. No normalization contract between helpers and library

The phone number format emitted by context-helpers and the format expected by the entity linker are not the same operation and are documented nowhere. This is a correctness bug that produces silent link failures.

3. No schema ERD

The SQLite schema (storage/schema.sql) has 6 tables with cross-references, but no visual or generated reference. adapters → sources → source_versions → chunks → entity_links is non-obvious.

4. No published OpenAPI spec

FastAPI generates the spec automatically at /docs and /openapi.json, but it's not exported, versioned, or referenced in the README. Consumers have to run the server to discover the API surface.

Proposed additions

• documentation/entity-linking.md — algorithm, JSON paths queried per domain, normalization contract, failure modes, intended query patterns
• documentation/normalization-contract.md — the canonical phone/email format (E164) and what both helpers and library must implement
• documentation/schema-erd.md (or generated via dbdocs/SchemaCrawler) — ERD for the SQLite schema
• README update: add link to /docs for OpenAPI, add note about running generate-openapi.sh (or equivalent) to export the spec