neotoma 0.3.0 → 0.3.2

package/docs/reports/mcp_cli_action_items_fidelity_report.md

@@ -1,189 +0,0 @@
----
-title: "MCP and CLI action items fidelity report"
-status: "report"
-created_date: "2026-02-02"
-related_proposal: "docs/proposals/mcp-cli-action-items.md"
----
-
-# MCP and CLI action items fidelity report
-## Scope
-This report evaluates current codebase fidelity against the action items in `docs/proposals/mcp-cli-action-items.md`. It covers contract alignment, MCP tooling, CLI behavior, fixtures, and documentation artifacts. It does not implement changes or define a release plan.
-
-## Purpose
-Provide a factual assessment of where the codebase aligns with the proposal and where gaps remain. Each action item includes current evidence and required changes.
-
-## Invariants
-1. Truth Layer boundaries remain intact. No strategy or execution logic is introduced.
-2. Determinism requirements remain enforced across ingestion, reducers, and tool calls.
-3. MCP tooling remains schema bound and auditable.
-4. Documentation must use active voice, short sentences, and no em dashes.
-
-## Definitions
-- **Fidelity**: The degree to which current code and docs meet the proposal action item intent.
-- **Aligned**: Evidence exists in code or docs that meets the action item.
-- **Partial**: Some components exist, but required alignment or enforcement is missing.
-- **Gap**: No evidence of implementation or enforcement.
-
-## Findings by action item
-
-### 1. Treat OpenAPI and domain schemas as the single core
-**Status**: Partial  
-**Evidence**:
-- OpenAPI exists in `openapi.yaml`.
-- Contract mappings exist in `src/shared/contract_mappings.ts` with coverage for OpenAPI operationIds.
-- Parity tests validate OpenAPI operation coverage in `tests/contract/contract_mapping.test.ts`.
-**Gap**:
-- MCP tool schemas remain defined outside OpenAPI in `src/server.ts` and `docs/specs/MCP_SPEC.md`.
-**Required changes**:
-- Derive MCP tool schemas from OpenAPI or generate OpenAPI from MCP schemas.
-
-### 2. Enforce 1:1 mapping between OpenAPI operations and MCP tools or CLI commands
-**Status**: Partial  
-**Evidence**:
-- Mapping registry exists in `src/shared/contract_mappings.ts`.
-- Parity tests validate operation coverage in `tests/contract/contract_mapping.test.ts`.
-**Gap**:
-- MCP only tools still bypass OpenAPI mapping.
-**Required changes**:
-- Reduce the MCP only tool list by adding OpenAPI coverage or CLI mappings where possible.
-
-### 3. Log CLI equivalent invocation for every MCP tool call
-**Status**: Partial  
-**Evidence**:
-- MCP request handling logs CLI equivalents via `buildCliEquivalentInvocation()` in `src/server.ts`.
-**Gap**:
-- MCP only tools log a placeholder command.
-**Required changes**:
-- Add CLI equivalents for MCP only tools or expand OpenAPI coverage.
-
-### 4. Define CLI output contract with `--json` and `--pretty`
-**Status**: Aligned  
-**Evidence**:
-- CLI supports `--json` and `--pretty` in `src/cli/index.ts`.
-- Output is produced through a single formatter in `src/cli/index.ts`.
-**Gap**:
-- None.
-**Required changes**:
-- None.
-
-### 5. Require idempotency keys for ingestion and corrections
-**Status**: Gap  
-**Evidence**:
-- Ingestion pipeline is documented in `docs/subsystems/ingestion/ingestion.md`.  
-**Gap**:
-- No idempotency key fields are visible in MCP or REST schemas in `src/actions.ts`.  
-**Required changes**:
-- Add idempotency fields to ingest and correct schemas and enforce them in handlers.
-
-### 6. Enforce strict, machine checkable error taxonomy
-**Status**: Partial  
-**Evidence**:
-- Error handling in `src/actions.ts` uses `handleApiError` and returns `{ error: message }`.  
-**Gap**:
-- Responses are string based and not aligned to `docs/subsystems/errors.md`.  
-**Required changes**:
-- Replace string errors with structured error envelopes and canonical error codes.
-
-### 7. Maintain replayable fixtures with expected extracted graphs
-**Status**: Partial  
-**Evidence**:
-- Fixtures are consolidated in `tests/fixtures/` with extensive coverage in `tests/fixtures/README.md`.  
-**Gap**:
-- Expected extracted graph outputs are not centrally documented.  
-**Required changes**:
-- Add expected snapshot or graph outputs alongside fixtures to support deterministic replay checks.
-
-### 8. Treat CLI as the reference executor
-**Status**: Gap  
-**Evidence**:
-- MCP stdio server entrypoint is `src/index.ts`. HTTP transport is `src/actions.ts`.  
-**Gap**:
-- No dedicated CLI wrapper exists.  
-**Required changes**:
-- Create a CLI module that invokes the same service layer as MCP and REST, then treat it as the reference executor.
-
-### 9. Keep MCP tools boring and atomic
-**Status**: Partial  
-**Evidence**:
-- MCP tools are defined in `src/server.ts`.  
-**Gap**:
-- MCP test failures in `docs/reports/FAILING_TESTS_SUMMARY.md` show method name mismatches. This indicates tooling instability.  
-**Required changes**:
-- Stabilize method naming and enforce atomic tool boundaries before adding composites.
-
-### 10. Publish canonical walkthrough: ingest, normalize, extract, query, replay
-**Status**: Partial  
-**Evidence**:
-- Pipeline flow is documented in `docs/subsystems/ingestion/ingestion.md`.
-- Step flows exist in `docs/releases/v0.2.0/integration_tests.md`.  
-**Gap**:
-- No standalone walkthrough doc that ties steps into a user facing guide.  
-**Required changes**:
-- Add a focused walkthrough in docs that links ingestion, query, and replay.
-
-### 11. Maintain fixtures repository with sample documents and expected outputs
-**Status**: Partial  
-**Evidence**:
-- Fixtures are in `tests/fixtures/`.  
-**Gap**:
-- Expected outputs are not centrally published.  
-**Required changes**:
-- Add expected outputs per fixture in a consistent structure.
-
-### 12. Build failure gallery for determinism breaks and system responses
-**Status**: Gap  
-**Evidence**:
-- Failure analyses exist in `docs/reports/` such as `FAILING_TESTS_SUMMARY.md`.  
-**Gap**:
-- No curated failure gallery doc that summarizes determinism issues and responses.  
-**Required changes**:
-- Create an index report that groups failure modes and links to existing analyses.
-
-## Testing requirements
-1. Add unit tests for idempotency key validation in ingestion and correction handlers.
-2. Add MCP to OpenAPI parity tests that enforce 1:1 mapping.
-3. Add CLI output contract tests for `--json` and `--pretty`.
-4. Add fixture replay tests that compare expected snapshots to reducer outputs.
-
-## Documentation requirements
-1. Add or update documentation to describe contract authority and tool parity.
-2. Add a canonical walkthrough doc.
-3. Add a failure gallery report.
-4. Add expected output documentation for fixtures.
-
-## Open issues
-No open issues at this time.
-
-## Agent Instructions
-### When to Load This Document
-Load this document when evaluating MCP and CLI alignment, contract surface changes, or proposal fidelity.
-
-### Required Co-Loaded Documents
-- `docs/foundation/core_identity.md`
-- `docs/architecture/determinism.md`
-- `docs/specs/MCP_SPEC.md`
-- `docs/subsystems/ingestion/ingestion.md`
-- `docs/subsystems/errors.md`
-- `docs/testing/fixtures_standard.md`
-- `docs/conventions/documentation_standards_rules.mdc`
-- `docs/conventions/writing_style_guide.md`
-
-### Constraints Agents Must Enforce
-1. Truth Layer boundaries remain intact.
-2. Determinism requirements remain enforced.
-3. MCP tool behavior remains schema bound.
-4. Documentation uses active voice and short sentences.
-5. No em dashes are used.
-
-### Forbidden Patterns
-- Introducing strategy or execution logic into Truth Layer code.
-- Parsing non JSON CLI output in MCP tools.
-- Returning free form string errors in MCP or REST.
-- Introducing composite MCP tools without explicit contract justification.
-- Omitting provenance or idempotency validation for ingestion.
-
-### Validation Checklist
-- [ ] Report includes required sections.
-- [ ] No em dashes or en dashes used.
-- [ ] Findings include evidence and required changes.
-- [ ] References align with current code paths.

package/docs/reports/neotoma_pdf_interpreted_as_note_investigation_2026_02_23.md

@@ -1,89 +0,0 @@
-# Neotoma: PDF interpreted as "note" instead of invoice/document — Investigation
-
-**Date:** 2026-02-23  
-**Purpose:** Root-cause analysis for file interpretation entity typing when an invoice PDF produced a `note` entity populated from the client message instead of an `invoice` (or `document`) with PDF-derived fields.
-
----
-
-## 1. Summary
-
-- **Symptom:** Invoice PDFs stored via `store_structured` with `file_path` + structured `agent_message` produced entities with `entity_type: "note"`, snapshot content = client message text, and `extraction_field_keys` / `extracted_keys` = `["role", "content", "turn_key", "schema_version"]` (i.e. structured message keys, not PDF-derived fields).
-- **Root cause:** When the client sends **both** `entities` and `file_path` with the **same** `idempotency_key` (and no `file_idempotency_key`), the server runs the structured store first, then the unstructured store with that same key. The unstructured store finds the **existing source created by the structured store** (JSON body of the entities), re-downloads that JSON, and runs interpretation on it. The PDF is never stored or interpreted; the “document” sent to the LLM is the serialized conversation/agent_message, so the LLM returns `note` with message fields.
-- **Fix (implemented):** When both entities and unstructured (file) are present and `file_idempotency_key` is omitted, the server now uses a derived key for the file (e.g. `{idempotency_key}-file`) so the file gets its own source and interpretation runs on the PDF, not on the structured payload.
-
----
-
-## 2. Context (from report)
-
-- **Client:** Store two PDFs via `store_structured` with `file_path` + `mime_type`: invoice `342_25_MARK_P.ALIO.pdf`, work report `Detalle.pdf`.
-- **Payload:** Each call included a structured `agent_message` (role, content, turn_key) alongside the file, e.g. content: `"Attached: 342_25_MARK_P.ALIO.pdf (invoice 342/25). Retry for interpretation."`
-- **Result:** Interpretation ran (on retry). Both PDFs produced entities with `entity_type: "note"`; snapshot content was the client message text; no invoice/document fields.
-
----
-
-## 3. Root cause: idempotency key collision
-
-### 3.1 Store flow when both entities and file are present
-
-1. **Structured store runs first** (`storeStructuredInternal`) with `idempotency_key` (e.g. `conversation-{id}-{turn}-retry`).
-2. It creates a **source** by calling `storeRawContent` with:
-   - `fileBuffer = Buffer.from(JSON.stringify(entities), "utf-8")`
-   - `mimeType: "application/json"`
-   - `idempotencyKey: idempotency_key`
-3. So the first source for that key is the **JSON body** of the entities (conversation + agent_message).
-4. **Unstructured store** is then called with `idempotency_key: parsed.file_idempotency_key ?? parsed.idempotency_key`. If the client did not send `file_idempotency_key`, this is the **same** key.
-5. The unstructured branch looks up an existing source by `idempotency_key` and finds the one just created (the JSON source).
-6. It enters the **idempotency-key reinterpret** path: downloads “raw content” (the JSON), calls `extractTextFromBuffer`. For `application/json`, that returns `buffer.toString("utf8")` — the full JSON string.
-7. `raw_text_length` is therefore the length of that JSON (e.g. a few hundred chars). The code then calls `extractWithLLM(rawText, ...)` with that string as “Document content.”
-8. The LLM sees the JSON of the conversation and agent_message and “extracts” an entity — naturally returning something like `entity_type: "note"` and fields such as `role`, `content`, `turn_key`, `schema_version` from the message object.
-9. The **PDF is never stored and never interpreted.** The “file” source for that idempotency key is the structured payload, not the PDF.
-
-So:
-
-- **Type selection:** The type is “note” because the “document” is the agent message JSON, not the invoice PDF.
-- **Refinement source:** The refinement step correctly uses “extracted” fields, but those fields come from the LLM run on the JSON, so they are the structured message keys. There is no bug in refinement logic per se; the input to interpretation is wrong.
-- **Extraction length:** The 202/194 character “raw text” is the length of the JSON string passed as document content, not a limit of PDF extraction.
-
-### 3.2 Code references
-
-- **Combined store:** `src/server.ts` — when `hasEntities && hasUnstructured`, unstructured is called with `idempotency_key: parsed.file_idempotency_key ?? parsed.idempotency_key` (same key if `file_idempotency_key` omitted).
-- **Structured source creation:** `storeStructuredInternal` (same file) calls `storeRawContent` with the JSON buffer and that `idempotencyKey`.
-- **Idempotency reinterpret:** Same file, idempotency hit branch downloads content, `extractTextFromBuffer` for JSON returns string; that string is passed to `extractWithLLM`.
-
----
-
-## 4. How entity type and refinement work (for reference)
-
-- **Type selection:** In `runInterpretation`, `entityType` comes from `entityData.entity_type` or `entityData.type` or `"generic"`, then alias resolution and optional LLM inference. So the type is whatever the **extraction** (LLM or CSV) produced. For the bug case, extraction was run on the JSON, so the LLM returned `note`.
-- **Refinement:** `refineEntityTypeFromExtractedFields` in `schema_definitions.ts` treats `note` and `generic` as generic. It scores extracted field keys against schema required/optional fields. With only `role`, `content`, `turn_key`, `schema_version`, the note schema (e.g. `content` required) fits; invoice requires e.g. `invoice_number`, `invoice_date`, `amount_due`, `currency` — so refinement does not switch to invoice. Behavior is correct given the wrong extraction input.
-- **Invoice/document detection:** There is no separate “invoice vs document” detector. The LLM extraction prompt (`docs/prompts/llm_extraction_system_prompt.md`) defines entity_type criteria (receipt, invoice, note, etc.). If the input to the LLM is the PDF body (after the fix), the LLM can classify invoice vs note correctly; previously the input was the message JSON.
-
----
-
-## 5. Follow-ups and recommendations
-
-### 5.1 Implemented
-
-- **Idempotency key for file when both entities and file are present:** When `hasEntities && hasUnstructured` and `file_idempotency_key` is not provided, the server now uses a derived key for the unstructured store (`{idempotency_key}-file`) so the file is stored and interpreted under its own source. The PDF is then interpreted correctly; the structured source keeps the original `idempotency_key`. Change: `src/server.ts` (unstructuredOnlyArgs).
-
-- **Reinterpret uses file source when available:** When the client calls `reinterpret(source_id)` and that source is the "structured twin" (mime_type `application/json`, has `idempotency_key` not ending with `-file`), the server looks up a sibling source with key `{idempotency_key}-file` for the same user. If found, it uses that file source’s stored content for extraction and LLM, then runs interpretation still against the requested `source_id` (so new observations attach to the source the user asked to reinterpret). Response includes `interpretation_used_file_source: true` when the linked file source was used. This fixes reinterpret for sources created *after* the idempotency-key fix (where both JSON and file sources exist). Sources created by the old bug (only JSON source, no `-file` sibling) still reinterpret the JSON; re-storing the file is required to get a file source for those.
-
-### 5.2 Documentation
-
-- **Document** in MCP/developer docs that when storing both entities (e.g. conversation + message) and a file, clients should send a **distinct** `file_idempotency_key` for the file (e.g. `file-<slug>`) so file and structured payload do not share a key. The server now auto-derives a file key when omitted, but explicit `file_idempotency_key` remains clearer and stable across retries.
-
-### 5.3 Optional client hint for entity_type
-
-- The pipeline does not currently accept a client hint for desired `entity_type` for file interpretation. Adding an optional hint (e.g. `interpret_entity_type_hint: "invoice"`) could be considered so the LLM or refinement prefers that type when the document is ambiguous.
-
-### 5.4 PDF extraction limits
-
-- PDF text extraction (`file_text_extraction.ts`) uses `pdf-parse` and returns full extracted text (no artificial page/size cap in code). Short extraction (e.g. 202 chars) in the bug case was from the JSON string, not from the PDF. For real PDFs, if extraction is short (e.g. image-only or scanned), the code already has a vision fallback (first-page image + vision model).
-
----
-
-## 6. Related
-
-- `reports/neotoma-import-debug-report-2026-02-10.md` — import and interpretation debugging.
-- `reports/neotoma-mcp-interpretation-expected-vs-actual-2026-02-11.md` — interpretation expected vs actual.
-- MCP spec: `file_idempotency_key` is optional; when both entities and file are present, using it avoids key collision (and the server now mitigates when it is omitted).

package/docs/reports/plan_execution_changes_report.md

@@ -1,122 +0,0 @@
-# Plan execution changes report
-## Scope
-This report lists code, test, and documentation changes produced by executing the MCP CLI action item plans. It does not define new requirements or replace source specifications.
-
-## Purpose
-Provide a single, deterministic record of all changes made during plan execution.
-
-## Invariants
-1. Truth Layer boundaries remain unchanged.
-2. All changes preserve deterministic behavior.
-3. Error responses use structured ErrorEnvelope formats.
-4. Documentation updates follow Neotoma documentation standards.
-
-## Definitions
-- **Plan execution**: The set of changes made while implementing plan files for the MCP CLI action items.
-- **Mapped tool**: An MCP tool with a corresponding OpenAPI operation mapping.
-- **MCP only tool**: An MCP tool without an OpenAPI mapping.
-
-## Data models
-No new data models were introduced. Existing sources, observations, entities, snapshots, and timeline events remain unchanged.
-
-## Flows
-Changes were applied in this order:
-1. Contract and schema alignment for MCP tools and OpenAPI.
-2. CLI execution parity for MCP only tools.
-3. Error envelope standardization and error code updates.
-4. Deterministic fixture replay tests and expected outputs.
-5. Documentation updates and new reports.
-
-## Diagrams
-No new diagrams were added in this report.
-
-## Changes by plan
-### Plan 1: OpenAPI as single contract source
-- Added OpenAPI schema loader and resolver in `src/shared/openapi_schema.ts`.
-- MCP tool input schemas now derive from OpenAPI for mapped tools in `src/server.ts`.
-- Added contract test `tests/contract/openapi_schema.test.ts`.
-- Updated `docs/specs/MCP_SPEC.md` to clarify OpenAPI as schema authority.
-
-### Plan 2: 1:1 mapping coverage
-- Added `MCP_TOOL_TO_CLI_COMMAND` mapping for MCP only tools in `src/shared/contract_mappings.ts`.
-- Extended contract tests to require CLI command coverage for MCP only tools in `tests/contract/contract_mapping.test.ts`.
-
-### Plan 3: CLI equivalents logged
-- `buildCliEquivalentInvocation` now emits CLI for mapped tools and MCP only tools, including args redaction.
-- Added `neotoma mcp-only` CLI command to execute MCP handlers locally, requires `--user-id`.
-
-### Plan 6: Error taxonomy and envelopes
-- Standardized REST error responses to ErrorEnvelope format in `src/actions.ts`.
-- Added `RESOURCE_NOT_FOUND` to `docs/reference/error_codes.md`.
-- Extended `docs/subsystems/errors.md` with validation and resource errors.
-
-### Plan 7: Fixture replay graphs
-- Added deterministic reducer replay test `tests/fixtures/replay_graph.test.ts`.
-- Added expected snapshot fixture `tests/fixtures/expected/contact_snapshot.json`.
-
-### Plan 8: CLI reference executor
-- Introduced `NeotomaServer.executeToolForCli` for local execution.
-- CLI `mcp-only` command now routes to MCP handlers directly.
-
-### Plan 9: MCP tools atomic
-- Added `store_structured` and `store_unstructured` MCP tools.
-- Updated tool descriptions in `docs/developer/mcp/tool_descriptions.yaml`.
-- Updated `docs/specs/MCP_SPEC.md` to note atomic alternatives.
-
-### Plan 10: Canonical walkthrough
-- Added `docs/developer/canonical_walkthrough.md`.
-- Updated `docs/context/index_rules.mdc` to include the new developer doc.
-
-### Plan 11: Fixtures expected outputs
-- Added `tests/fixtures/expected/transaction_snapshot.json`.
-- Expanded `tests/fixtures/replay_graph.test.ts` to include transaction replay.
-- Updated `tests/fixtures/README.md`.
-
-### Plan 12: Failure gallery
-- Added `docs/reports/failure_gallery.md`.
-- Updated `docs/context/index_rules.mdc` to include reports section.
-- Added `docs/reports/*.md` to `docs/doc_dependencies.yaml`.
-
-## Examples
-Example error envelope used in REST responses:
-```json
-{
-  "error_code": "RESOURCE_NOT_FOUND",
-  "message": "Source not found",
-  "details": {
-    "resource": "source",
-    "id": "src_missing"
-  },
-  "timestamp": "2024-01-10T00:00:00.000Z"
-}
-```
-
-## Testing requirements
-1. `npm test` for unit and contract tests.
-2. `npm run test:unit` for deterministic snapshot replay tests.
-3. `node scripts/validate-doc-dependencies.js docs/reports/plan_execution_changes_report.md`.
-
-## Agent Instructions
-### When to Load This Document
-Load when summarizing or auditing the MCP CLI action item plan execution changes.
-
-### Required Co-Loaded Documents
-- `docs/NEOTOMA_MANIFEST.md`
-- `docs/conventions/documentation_standards.md`
-- `docs/private/governance/00_GENERATION.md`
-
-### Constraints Agents Must Enforce
-1. Report updates must remain deterministic and factual.
-2. No new requirements are introduced in this report.
-3. Links and references must remain valid.
-
-### Forbidden Patterns
-- Introducing new requirements in a report
-- Omitting required report sections
-- Including PII in examples
-
-### Validation Checklist
-- [ ] Required sections present
-- [ ] Examples deterministic
-- [ ] No PII or secrets
-- [ ] References are valid

package/docs/reports/schema_distinctions.md

@@ -1,210 +0,0 @@
-# Schema Type Distinctions and Redundancy Analysis
-
-Generated: 2026-01-22
-
-## Quick Reference: Common Confusions
-
-### Transaction vs Transfer
-
-**transaction**: External economic activity (you ↔ third party)
-- Bank feed imports from Plaid
-- Receipt purchases from merchants
-- Salary deposits from employers
-- Rent payments to landlords
-- **Key fields**: merchant_name, category, bank_provider
-
-**transfer**: Internal asset movement (your account A → your account B)
-- Moving money between your own accounts
-- Retirement contributions (checking → IRA)
-- Portfolio rebalancing (stocks → bonds)
-- Crypto custody changes (exchange → cold wallet)
-- **Key fields**: origin_account, destination_account
-
-**Example**:
-- Transaction: "Coffee Shop -$5.00" (you → merchant)
-- Transfer: "Checking → Savings $1000" (your account → your account)
-
----
-
-### Exercise vs Workout
-
-**exercise**: Individual exercise activities (atomic unit)
-- Single activity: "squats", "push-ups", "running"
-- Specific sets: "3 sets x 15 reps"
-- **Key fields**: name, sets, reps, duration
-
-**workout**: Complete workout routines (combination)
-- Full routine: "Full Body Circuit"
-- Multiple exercises: "squats, pushups, pullups, planks"
-- Workout plan with circuits
-- **Key fields**: exercises (list), circuits, primary_muscles
-
-**Example**:
-- Exercise: "Squats - 3 sets x 15 reps"
-- Workout: "Full Body Circuit" (contains: squats, pushups, pullups, planks)
-
----
-
-### Email vs Message
-
-**email**: Email-specific messages
-- Email threads with subjects
-- Sender/recipient email addresses
-- Email-specific metadata (thread_id, reply-to)
-- **Key fields**: subject, thread_id, email-specific structure
-
-**message**: Generic messages without email structure
-- DMs, SMS, chat messages
-- Social media messages
-- Any text communication that's not email
-- **Key fields**: channel, platform-specific metadata
-
-**Example**:
-- Email: "Subject: Q1 Report" (email thread)
-- Message: "Hey, can we meet at 3?" (Slack DM)
-
----
-
-### Goal vs Outcome
-
-**goal**: Target metrics you're trying to achieve
-- OKRs (Objectives and Key Results)
-- Target metrics: "Reach $100k revenue"
-- Future-oriented targets
-- **Key fields**: target_value, metric, deadline
-
-**outcome**: Results organized by strategic goals
-- What you're trying to achieve (deliverable-focused)
-- Can be strategic (long-term), tactical (methods), or operational (procedures)
-- Links to goals via goal_id
-- **Key fields**: outcome_name, outcome_type, goal_id, status
-
-**Example**:
-- Goal: "Increase revenue by 50% by Q4" (target metric)
-- Outcome: "Launch MVP" (deliverable, links to startup goal)
-
----
-
-### Contact vs Person vs Company
-
-**contact**: Unified people and organization records (raw entry)
-- Can represent person OR organization
-- Data as entered (mixed type)
-- **Key fields**: name, email, organization, contact_type
-
-**person**: Individual human records (resolved)
-- Specifically individuals
-- Extracted/resolved from contacts
-- **Key fields**: name, email, phone, title
-
-**company**: Organization records (resolved)
-- Specifically organizations
-- Extracted/resolved from contacts
-- **Key fields**: name, industry, website
-
-**Pattern**: contact = raw input, person/company = resolved entities
-
----
-
-### Address vs Location
-
-**address**: Postal/mailing addresses
-- Structured address components
-- For mail delivery
-- **Key fields**: street, city, state, postal_code, country
-
-**location**: Geographic coordinates and places
-- Latitude/longitude
-- Named places with coordinates
-- **Key fields**: name, latitude, longitude, address (can include)
-
-**Example**:
-- Address: "123 Main St, City, State 12345" (postal)
-- Location: "Central Park" (lat: 40.785, lon: -73.968, address: "...")
-
----
-
-### Purchase vs Receipt vs Order
-
-**purchase**: Planned and completed purchase tracking
-- Wishlist → intent → completion
-- Status transitions (pending → in_progress → completed)
-- **Key fields**: item_name, status, created_date, completed_date
-
-**receipt**: Proof-of-purchase documents
-- Physical/digital receipts
-- Document proving purchase occurred
-- **Key fields**: receipt_number, merchant_name, amount_total, date
-
-**order**: Trading orders (brokerage-specific)
-- Stock/crypto buy/sell orders
-- Limit orders, stop losses
-- **Key fields**: order_type, asset_type, price, accounts
-
-**Distinctions**:
-- Purchase = planning/tracking (before/during/after)
-- Receipt = proof document (after)
-- Order = trading execution (brokerage-specific)
-
----
-
-## Redundancy Analysis Results
-
-### ❌ Fixed Issues
-
-**Duplicate alias "objective"**: Was used by both `goal` and `outcome`
-- ✅ Fixed: Removed from `goal`, kept for `outcome`
-- goal now uses: ["target", "okr", "key_result"]
-- outcome keeps: ["objective", "result", "deliverable"]
-
-**Ambiguous descriptions**: Clarified distinctions
-- ✅ Fixed: Updated descriptions for exercise, workout, goal, outcome, email, message
-
-### ✅ Intentional Separations (No Action Needed)
-
-**Task metadata types** (5 types):
-- task, task_attachment, task_comment, task_dependency, task_story
-- **Justified**: Preserves Asana import fidelity, enables granular tracking
-
-**Habit metadata types** (3 types):
-- habit, habit_completion, habit_objective
-- **Justified**: Enables temporal completion tracking and multiple objectives per habit
-
-**Financial transaction types** (5 types):
-- transaction, transfer, purchase, receipt, order
-- **Justified**: Each represents distinct financial concept with different use cases
-
-**Identity types** (5 types):
-- contact, person, company, address, location
-- **Justified**: contact = raw entry, person/company = resolved entities, address/location = different coordinate systems
-
-### No Action Recommended
-
-All other schema separations are well-justified and serve distinct purposes.
-
----
-
-## Schema Health Metrics
-
-**Total schemas**: 50  
-**Duplicate aliases**: 0 (fixed)  
-**Well-differentiated**: 50/50 (100%)  
-**Category balance**: Reasonable (18 finance, 13 productivity, 12 knowledge, 7 health)
-
----
-
-## Conclusion
-
-**No true redundancies found.** All schema separations are intentional architectural choices:
-
-1. **transaction vs transfer**: External vs internal activity ✅
-2. **exercise vs workout**: Atomic vs composite ✅
-3. **email vs message**: Email-specific vs generic ✅
-4. **goal vs outcome**: Target vs achieved result ✅
-5. **contact vs person/company**: Raw vs resolved ✅
-6. **address vs location**: Postal vs geographic ✅
-7. **Task/habit metadata**: Granularity by design ✅
-
-**Critical fix applied**: Removed duplicate "objective" alias.
-
-**Schema set is healthy and well-designed.**