neotoma 0.3.0 → 0.3.2

package/docs/reports/schema_redundancy_analysis.md

@@ -1,304 +0,0 @@
-# Schema Redundancy Analysis
-
-Generated: 2026-01-22
-
-## Executive Summary
-
-Analysis of 50 entity schemas identifies 7 areas with potential redundancies or overlaps. Most are intentional architectural choices, but some warrant review for consolidation.
-
-## Overview
-
-- **Total schemas**: 50
-- **Categories**: 4 (finance, productivity, knowledge, health)
-- **Duplicate aliases found**: 1 ("objective" → goal, outcome)
-- **Potential redundancy groups**: 7
-
-## Critical Finding: Duplicate Alias
-
-### ⚠️ ISSUE: "objective" alias collision
-
-**Types affected**: `goal`, `outcome`
-
-**Problem**: Both types use "objective" as an alias
-
-**Impact**: Ambiguous type resolution when users reference "objective"
-
-**Recommendation**: 
-- Remove "objective" alias from one type (suggest: remove from `goal`, keep for `outcome`)
-- Or clarify: goal = "target" aliases, outcome = "objective" aliases
-
----
-
-## Potential Redundancies (Review Recommended)
-
-### 1. Exercise vs Workout
-
-**Current**:
-- `exercise` (7 fields): "Single workout sessions or sets"
-- `workout` (11 fields): "Workout routines and exercise combinations"
-
-**Analysis**:
-- **exercise**: Appears to be individual exercise activities or sets
-- **workout**: Appears to be full workout routines (collections of exercises)
-
-**Question**: Are these truly distinct?
-- If exercise = single activity, workout = routine → Keep separate
-- If both refer to same concept → Consolidate
-
-**Recommendation**: 
-- **Keep separate** if: workout contains multiple exercises (parent-child relationship)
-- Clarify in descriptions: "exercise" = atomic activity, "workout" = combination
-- Consider: Should exercise instances link to workout via relationship?
-
----
-
-### 2. Email vs Message
-
-**Current**:
-- `email` (19 fields): "Email messages and threads"
-- `message` (16 fields): "Emails, DMs, chat transcripts"
-
-**Analysis**:
-- **email**: Specific to email messages
-- **message**: Generic for emails, DMs, SMS, chat
-
-**Overlap**: Both can represent emails
-
-**Recommendation**:
-- **Keep separate** - email is specific, message is generic
-- Clarify usage: email = email-specific fields (subject, thread), message = generic messaging
-- Or **consolidate**: Use message for all, add `message_type` field (email, dm, sms, chat)
-
----
-
-### 3. Contact vs Person vs Company
-
-**Current**:
-- `contact` (24 fields): "People and organization records"
-- `person` (18 fields): "Individual person records"
-- `company` (18 fields): "Company and organization records"
-
-**Analysis**:
-- **contact**: Can be person OR organization (generic)
-- **person**: Individual humans
-- **company**: Organizations
-
-**Overlap**: Contact can represent both person and company
-
-**Recommendation**:
-- **Keep all three** if: contact = unified view, person/company = specific types
-- Or **consolidate**: Remove contact, use person/company only with relationship links
-- Current pattern suggests: contact = data entry, person/company = resolved entities
-
-**Likely OK as-is**: Contact is likely the "raw" type from imports, person/company are resolved entity types
-
----
-
-### 4. Address vs Location
-
-**Current**:
-- `address` (17 fields): "Physical and mailing addresses"
-- `location` (17 fields): "Geographic locations and coordinates"
-
-**Analysis**:
-- **address**: Structured (street, city, state, postal_code, country)
-- **location**: Geographic (name, latitude, longitude, address)
-
-**Overlap**: Both can represent places, location includes address field
-
-**Recommendation**:
-- **Keep separate** if: address = postal address, location = geographic point
-- Or **consolidate**: Use location for all, add address components as fields
-- Consider: Should address be a property on other types rather than separate entity?
-
-**Likely OK as-is**: Address = postal addressing, Location = geographic coordinates
-
----
-
-### 5. Transaction vs Transfer vs Purchase vs Receipt vs Order
-
-**Current**:
-- `transaction`: "Individual debits/credits pulled from Plaid or uploads" (bank activity)
-- `transfer`: "Asset transfers between accounts" (your accounts only)
-- `purchase`: "Planned and completed purchase tracking" (intent to buy)
-- `receipt`: "Proof-of-purchase documents" (purchase proof)
-- `order`: "Trading orders and order tracking" (trading activity)
-
-**Analysis**:
-
-**Distinctions**:
-- **transaction**: External party activity (you ↔ merchant/bank)
-- **transfer**: Internal movement (your account A → your account B)
-- **purchase**: Planning/tracking purchases (before/after)
-- **receipt**: Document proving purchase occurred
-- **order**: Trading/brokerage orders (buy/sell stocks/crypto)
-
-**Overlap**: 
-- Receipt and purchase overlap (receipt proves purchase)
-- Transaction and receipt overlap (both record spending)
-
-**Recommendation**:
-- **Keep all five** - represent different aspects of financial activity
-- **transaction**: Bank's view (from Plaid/statements)
-- **transfer**: Your intentional moves between accounts
-- **purchase**: Your planning (wishlist → completed)
-- **receipt**: Physical/digital proof documents
-- **order**: Trading execution (brokerage-specific)
-
-**Relationships**: receipt → transaction (proves), purchase → transaction (resulted in), order → transaction (executed as)
-
-**Status**: ✅ **Well-differentiated** - these represent genuinely distinct concepts in personal finance
-
----
-
-### 6. Task-Related Types (task + 4 metadata types)
-
-**Current**:
-- `task` (24 fields): Core task definition
-- `task_attachment` (16 fields): Files attached to tasks
-- `task_comment` (14 fields): Comments on tasks
-- `task_dependency` (12 fields): Task blocking relationships
-- `task_story` (14 fields): Activity log entries for tasks
-
-**Analysis**:
-- Core task + 4 metadata/relationship types
-- All link back to task via `task_id`
-
-**Question**: Should metadata be separate types or embedded in task?
-
-**Recommendation**:
-- **Keep separate** for Asana import fidelity (preserves Asana structure)
-- Separate types enable:
-  - Many attachments per task
-  - Comment history
-  - Dependency graph
-  - Full activity audit trail
-- Alternative: Embed as arrays in task (loses granularity)
-
-**Status**: ✅ **Justified** - separate types provide better granularity for task management systems
-
----
-
-### 7. Habit-Related Types (habit + 2 metadata types)
-
-**Current**:
-- `habit` (12 fields): Core habit definition
-- `habit_completion` (7 fields): Daily completion tracking
-- `habit_objective` (9 fields): Target benefits
-
-**Analysis**:
-- Habit + tracking data + objectives
-
-**Question**: Should completions and objectives be separate types?
-
-**Recommendation**:
-- **Keep separate** for temporal tracking
-- Separate types enable:
-  - Daily completion log (many-to-one)
-  - Multiple objectives per habit
-  - Historical completion data
-- Alternative: Embed as arrays (loses temporal granularity)
-
-**Status**: ✅ **Justified** - separate types enable better habit tracking and analytics
-
----
-
-### 8. Strategy/Process/Goal/Outcome
-
-**Current**:
-- `strategy` (13 fields): "Strategic documents and tactics from markdown files"
-- `process` (8 fields): "Process documents and analysis records"
-- `goal` (11 fields): "Outcome targets or OKRs"
-- `outcome` (15 fields): "Outcomes represent what we're trying to achieve, organized by strategic goals"
-
-**Analysis**:
-- **strategy**: Long-term principles and approaches
-- **process**: Operational procedures
-- **goal**: Targets/OKRs
-- **outcome**: Results organized by goals
-
-**Overlap**: goal and outcome are very similar
-
-**Recommendation**:
-- **Consider consolidation**: goal + outcome → single "objective" type
-- Or clarify: goal = input target, outcome = achieved result
-- strategy and process are distinct (high-level vs operational)
-
-**Status**: ⚠️ **Review recommended** - goal vs outcome distinction unclear
-
----
-
-## Summary of Findings
-
-### ❌ Must Fix
-
-**Duplicate alias**: "objective" used by both `goal` and `outcome`
-- Remove from one type or namespace differently
-
-### ⚠️ Review Recommended
-
-1. **goal vs outcome** - Very similar, consider consolidation
-2. **exercise vs workout** - Clarify distinction or consolidate
-3. **email vs message** - Consider consolidating to message with type field
-
-### ✅ Justified Separations
-
-1. **transaction vs transfer** - Well differentiated (external vs internal)
-2. **Task metadata types** - Separate for granularity
-3. **Habit metadata types** - Separate for temporal tracking
-4. **contact vs person vs company** - Likely raw vs resolved entities
-5. **address vs location** - Postal vs geographic coordinates
-
-### Category Distribution
-
-- **Finance**: 18 types (36%) - Comprehensive financial tracking
-- **Productivity**: 13 types (26%) - Task and planning management
-- **Knowledge**: 12 types (24%) - Identity and information
-- **Health**: 7 types (14%) - Wellness tracking
-
-## Recommendations
-
-### Priority 1: Fix Duplicate Alias
-
-```typescript
-// In schema_definitions.ts
-goal: {
-  metadata: {
-    aliases: ["target", "okr"], // Remove "objective"
-  }
-}
-
-outcome: {
-  metadata: {
-    aliases: ["objective", "result", "deliverable"], // Keep "objective"
-  }
-}
-```
-
-### Priority 2: Clarify Descriptions
-
-Update descriptions to emphasize distinctions:
-
-- **exercise**: "Individual exercise activities or training sets (atomic unit)"
-- **workout**: "Complete workout routines combining multiple exercises"
-- **goal**: "Target metrics and OKRs to achieve"
-- **outcome**: "Achieved results and deliverables organized by strategic goals"
-- **email**: "Email-specific messages with threads and subjects"
-- **message**: "Generic messages (DMs, SMS, chat) without email-specific structure"
-
-### Priority 3: Consider Future Consolidation
-
-**Low priority** (only if schemas prove redundant in practice):
-- goal + outcome → single type with status (target vs achieved)
-- email + message → single type with message_type discriminator
-- exercise + workout → single type with workout_type (single vs routine)
-
-## Conclusion
-
-**Overall assessment**: Schema set is well-designed with intentional distinctions. Only 1 critical issue (duplicate alias) and 2-3 areas warranting clarification. Most apparent overlaps are justified architectural choices.
-
-**Action items**:
-1. Fix "objective" alias collision (immediate)
-2. Clarify exercise vs workout descriptions (documentation)
-3. Clarify goal vs outcome descriptions (documentation)
-4. Monitor usage patterns to validate separation decisions

package/docs/specs/FUNCTIONAL_REQUIREMENTS.md

@@ -1,160 +0,0 @@
-# Neotoma Functional Requirements
-**Note:** This is a **high-level summary** document for stakeholders and quick reference. For implementation details, see:
-- [`docs/subsystems/ingestion/ingestion.md`](../subsystems/ingestion/ingestion.md) — Complete ingestion pipeline, extraction rules, schema detection
-- [`docs/subsystems/record_types.md`](../subsystems/record_types.md) — Complete type catalog, field mappings, extraction patterns
-- [`docs/subsystems/schema.md`](../subsystems/schema.md) — Database schema, JSONB structures, schema evolution
-- [`docs/subsystems/search/search.md`](../subsystems/search/search.md) — Search query models, ranking, filtering
-- [`docs/architecture/architecture.md`](../architecture/architecture.md) — System architecture, data flows, layer boundaries
-- [`docs/specs/MCP_SPEC.md`](./MCP_SPEC.md) — Complete MCP action specifications
-**In case of conflict, detailed subsystem docs are authoritative.**
-## Purpose
-Consolidates functional requirements from all Neotoma subsystems into a single reference document for stakeholders and planning.
-## 1. Ingestion Requirements
-**Dual-Path Ingestion:**
-1. **File Upload Path:** Accept PDF, JPG, PNG files (max 50MB), extract text, detect schema, extract fields
-2. **Agent Interaction Path:** Accept structured data via MCP `store_record`, direct property assignment
-**File Upload MUST:**
-- Accept PDF, JPG, PNG files (max 50MB)
-- Extract text via pdf-parse or Tesseract OCR
-- Detect schema type via rule-based matching
-- Extract fields deterministically
-- Generate content hash for deduplication
-- Process files in <10s (P95)
-**Agent Interaction MUST:**
-- Accept structured data via MCP `store_record`
-- Validate schema type and properties
-- Create records with user-provided properties
-- Support entity resolution and timeline generation across agent-created data
-**MUST NOT:**
-- Accept files >50MB
-- Use LLM for extraction (MVP)
-- Automatically ingest without user action
-See [`docs/subsystems/ingestion/ingestion.md`](../subsystems/ingestion/ingestion.md)
-## 2. Schema Requirements
-**Note:** Neotoma uses a **two-tier type system**:
-- **Application types** (this list): Used in code, database, and MCP actions
-- **Schema families** (`Financial`, `Productivity`, etc.): Used for documentation only
-See [`docs/subsystems/record_types.md`](../subsystems/record_types.md) for complete type catalog and [`docs/NEOTOMA_MANIFEST.md`](../NEOTOMA_MANIFEST.md) section 14 for two-tier system explanation.
-**MVP Application Types (Tier 1 ICP-aligned):**
-**Finance:**
-- `invoice` — Invoices (money owed to/from vendors)
-- `receipt` — Proof-of-purchase documents
-- `transaction` — Individual debits/credits (from uploads, not Plaid)
-- `statement` — Periodic statements (bank, credit, utilities)
-- `account` — Financial account snapshots
-**Productivity:**
-- `note` — Free-form text, journals, markdown files
-- `document` — Structured files, specs, PDFs, knowledge assets (generic fallback)
-- `message` — Emails, DMs, chat transcripts (from Gmail integration)
-- `task` — Action items with status
-- `project` — Multi-step initiatives
-- `event` — Meetings, appointments, calendar events
-**Knowledge:**
-- `contact` — People and organization records
-- `dataset` — Tabular datasets (CSV, spreadsheet uploads)
-**Legal/Compliance:**
-- `contract` — Contracts and legal documents (critical for knowledge workers and founders)
-**Travel:**
-- `travel_document` — Flight itineraries, hotel bookings, boarding passes
-**Identity:**
-- `identity_document` — Passports, IDs, licenses
-**MUST:**
-- Assign application type deterministically (multi-pattern matching)
-- Extract fields per type-specific rules (see `record_types.md`)
-- Version JSONB schemas (`schema_version` field required)
-- Support additive evolution (no breaking changes)
-- Fallback to `document` if no type matches 2+ patterns
-**MUST NOT:**
-- Use schema family names (`Financial`, `Productivity`) as database types
-- Mix application types and families in code
-**Rationale:** These application types directly support Tier 1 ICP workflows:
-- **AI-Native Individual Operators:** Research synthesis (document, note), contract analysis (contract), travel planning (travel_document), invoice management (invoice, receipt)
-- **High-Context Knowledge Workers:** Due diligence (contract, document, contact), legal research (contract, document), market research (document, note), client work (message, contact, note)
-- **AI-Native Founders & Small Teams:** Team knowledge base (document, note, message), investor relations (document, invoice), product planning (document, note), hiring (contact, document)
-See [`docs/subsystems/schema.md`](../subsystems/schema.md), [`docs/subsystems/record_types.md`](../subsystems/record_types.md), and [`src/config/record_types.ts`](../../src/config/record_types.ts)
-## 3. Entity Resolution Requirements
-**MUST:**
-- Generate hash-based entity IDs
-- Normalize entity names (lowercase, trim, remove suffixes)
-- Deduplicate entities globally
-- Link records to entities via graph edges
-**Example:**
-- "Acme Corp" → `ent_abc123...`
-- "ACME CORP" → `ent_abc123...` (same ID)
-See [`docs/NEOTOMA_MANIFEST.md`](../NEOTOMA_MANIFEST.md) section 15
-## 4. Event Generation Requirements
-**MUST:**
-- Extract events from date fields only
-- Generate deterministic event IDs
-- Link events to source records and fields
-- Sort timeline chronologically
-See [`docs/NEOTOMA_MANIFEST.md`](../NEOTOMA_MANIFEST.md) section 16
-## 5. Search Requirements
-**MUST:**
-- Support structured filters (type, date range, properties)
-- Support full-text search over raw_text
-- Rank results deterministically (tiebreakers required)
-- Return results in <500ms (P95)
-**MUST NOT:**
-- Use semantic search for ranking (MVP)
-- Return nondeterministic order
-See [`docs/subsystems/search/search.md`](../subsystems/search/search.md)
-## 6. Graph Requirements
-**MUST:**
-- Insert records, entities, events transactionally
-- Create typed edges (record→entity, record→event, event→entity)
-- Maintain zero orphan nodes
-- Prevent cycles
-See [`docs/architecture/architecture.md`](../architecture/architecture.md)
-## 7. MCP Requirements
-**MUST:**
-- Provide 8 MVP actions (store, update, retrieve, delete, upload, providers)
-- Plaid actions (4) moved to post-MVP (Tier 3+ use case)
-- Validate all inputs
-- Return structured JSON
-- Use ErrorEnvelope for errors
-See [`docs/specs/MCP_SPEC.md`](./MCP_SPEC.md)
-## 8. UI Requirements
-**MUST:**
-- Provide list, detail, timeline, dashboard views
-- Support keyboard navigation
-- Include ARIA labels
-- Localize UI text (preserve content language)
-See [`docs/specs/UI_SPEC.md`](./UI_SPEC.md)
-## Detailed Documentation References
-- [`docs/subsystems/ingestion/ingestion.md`](../subsystems/ingestion/ingestion.md)
-- [`docs/subsystems/schema.md`](../subsystems/schema.md)
-- [`docs/subsystems/search/search.md`](../subsystems/search/search.md)
-- [`docs/architecture/architecture.md`](../architecture/architecture.md)
-## Agent Instructions
-### When to Load This Document
-Load `docs/specs/FUNCTIONAL_REQUIREMENTS.md` when:
-- Planning feature scope and requirements
-- Understanding MVP functional boundaries
-- Validating feature against requirements
-- Quick reference for subsystem requirements
-### Required Co-Loaded Documents
-- `docs/NEOTOMA_MANIFEST.md` (always)
-- `docs/subsystems/record_types.md` (for schema type requirements)
-- Detailed subsystem docs for implementation (ingestion.md, schema.md, search.md, etc.)
-### Constraints Agents Must Enforce
-1. **Use application types:** Code must use granular types (`invoice`, `receipt`) from `record_types.md`, NOT schema families
-2. **AI interpretation for unstructured files:** Via interpretation service with auditability and idempotence (section 1)
-3. **Multi-pattern matching:** Schema detection must use 2+ patterns (section 2)
-4. **Deterministic ranking:** Search must use tiebreakers (section 5)
-5. **MCP action catalog:** Only 8 MVP actions allowed (section 7)
-6. **Defer to detailed docs:** This is a summary; detailed subsystem docs are authoritative
-### Forbidden Patterns
-- Using LLM for extraction in MVP
-- Using schema family names as database types
-- Implementing semantic search in MVP (section 5)
-- Adding non-MVP MCP actions (Plaid is post-MVP)
-- Violating consistency models per subsystem
-### Validation Checklist
-- [ ] Feature requirements match detailed subsystem docs
-- [ ] Uses application types (not schema families)
-- [ ] AI interpretation uses interpretation service with audit trail
-- [ ] Schema detection uses multi-pattern matching
-- [ ] Search ranking is deterministic
-- [ ] Only MVP MCP actions used
-- [ ] Cross-checked against NEOTOMA_MANIFEST.md invariants

package/docs/specs/GENERAL_REQUIREMENTS.md

@@ -1,30 +0,0 @@
-## MVP Ingestion
-- The ingestion pipeline MUST deterministically ingest all user-selected source files in the configured import set and create **Records** with:
-  - Extracted properties defined by the active **Schema Types**
-  - Complete **Provenance** (file, timestamps, user, path or upload source)
-  - Links into the **Memory Graph** (to related Records, Entities, and Events)
-- The normalization layer MUST include a deterministic OCR pipeline for image-based and scanned documents, such that:
-  - Given the same input image/PDF, the OCR output text is identical across runs (no randomness, no model drift in MVP), and
-  - OCR failures or low-confidence regions are surfaced explicitly in metadata without fabricating or inferring missing content.
-- For any source file that represents more than one logical **Event** (e.g., logs, chats, multi-transaction statements), ingestion MUST:
-  - Create at least one **file-level Record** representing the source file, and
-  - Create additional **Records and/or Events** for each logical event, with deterministic, rule-based mapping from the file content, and
-  - Link all event-derived records back to the file-level Record in the Memory Graph.
-- For CSV and spreadsheet source files, ingestion MUST:
-  - Create one **file-level Record** for the spreadsheet, and
-  - Create one **row-level Record** per non-header row according to the configured Schema Type, and
-  - Preserve deterministic linkage between each row-level Record and the file-level Record in the Memory Graph.
-- For chat transcripts (e.g., logs exported from LLM apps), MVP MUST provide a **separate CLI tool or flow** (outside the Truth Layer ingestion pipeline) that can:
-  - Non-deterministically convert a raw chat export into well-structured JSON files (one record per JSON object with explicit schema types and properties), and then
-  - Feed the resulting JSON files into the standard deterministic ingestion path described above, so that Neotoma itself never performs non-deterministic interpretation of chat content.
-### MVP Schema Catalog
-- For MVP, the system MUST use a curated **Tier 1 / Tier 2 schema catalog** (financial, tax, transactional, and core administrative document types) defined statically in the canonical type mappings and extraction rules, with a deterministic generic fallback (e.g., `PDFDocument`) for unrecognized documents.
-- The initial schema catalog SHOULD be fleshed out **within Tier 1 (and selectively Tier 2)** by:
-  - Deriving additional Tier 1 schema types from representative real-world sample files (including those in the initial import set), and
-  - Adding only those Tier 2 schemas that are clearly high-leverage for the MVP ICPs,
-  - Always preserving all determinism, explainability, and schema-first constraints from the Neotoma manifest.
-## MVP UI
-- The design system MUST present information at an effective density comparable to Notion, implemented via:
-  - Compact but readable typography and spacing, and
-  - Layouts that surface all core properties of a selected Record without excessive scrolling.
-- The UI MUST present one primary data focus per screen or panel (e.g., Records list, Record detail, Timeline, Entities), and MUST NOT present multi-surface dashboards that mix unrelated data types in a way that overwhelms users in MVP.

package/docs/specs/ICP_PRIORITY_TIERS.md

@@ -1,132 +0,0 @@
-# Neotoma ICP Priority Tiers
-## Grouped by Addressability, Revenue Potential, and Early GTM Fit
-**For detailed ICP profiles (pain points, use cases, workflows), see [`docs/specs/ICP_PROFILES.md`](./ICP_PROFILES.md).**
-# TIER 1 — Early Revenue, Highest Intent, Fastest Adoption
-(Neotoma MVP MUST directly serve these ICPs)
-These ICPs require no multi-user features, no enterprise controls, no deep integrations.  
-They experience immediate pain from fragmented truth and are willing to pay now.  
-They also naturally become bottom-up champions for B2B adoption.
-### Included ICPs
-- **AI-Native Individual Operators**  
-  Heavy ChatGPT/Claude/Raycast/Cursor users; strongest personal pain; immediate activation.  
-- **High-Context Knowledge Workers**  
-  Analysts, researchers, consultants, lawyers; high document load; rely on cross-document reasoning.  
-- **AI-Native Founders & Small Teams (2–20 people)**  
-  Will initially adopt individually, then expand into team usage organically.  
-  They bridge B2C → B2B expansion.  
-### Why Tier 1
-- Lowest activation friction  
-- Highest willingness to pay early  
-- Strongest retention and daily use  
-- They validate ingestion, schema, events, and MCP  
-- They pull Neotoma into larger organizations through bottom-up demand  
-# TIER 2 — Early B2B Expansion (High Revenue Leverage, Medium Activation Friction)
-After Tier 1 proves the product and memory substrate, these ICPs represent the next wave of revenue expansion.  
-They require some multi-user features and stronger organizational semantics—but still adopt relatively early.
-### Included ICPs
-- **Hybrid Product Teams (PM + Eng + Design + Marketing)**  
-  Coordination breakdown is significant; many AI tools in use; high ROI.  
-- **Cross-Functional Operational Teams (Ops, RevOps, Marketing Ops)**  
-  Rely heavily on content + workflows + repetitive AI tasks; crave consistency.  
-- **Developer Integrators**  
-  Build internal tools, automations, and agent systems; require stable truth APIs.  
-- **AI Tool Integrators (Cursor, Raycast, VSCode, Claude Tools)**  
-  Integrate Neotoma to provide persistent memory across tools.
-### Why Tier 2
-- Medium friction, but high upside  
-- Bigger seats and higher ACVs ($2–20k ARR per team)  
-- Require multi-agent alignment, versioned truth, and shared memory  
-- Benefit enormously from the Organizational Memory substrate  
-# TIER 3 — B2C Power Users (High Value, Lower ARPU, Slower GTM)  
-These ICPs get strong value from Neotoma but are **not ideal initial revenue drivers**.  
-They will convert gradually through inbound, bottom-up adoption.
-### Included ICPs
-- **Cross-Border Solopreneurs**  
-  High document entropy; rely heavily on receipts, invoicing, travel.  
-- **Multi-System Information Workers**  
-  Benefit from unification, but require education.  
-- **High-Entropy Households / Family Managers**  
-  Strong personal need, but slow adoption curve.
-### Why Tier 3
-- Good long-term base  
-- Lower ARPU  
-- Higher support/education requirements  
-- Conversion dependent on trust built through Tier 1 success  
-# TIER 4 — Strategy-Layer ICPs (Agentic Portfolio)  
-(Requires later product maturity and asset/tax modeling stack)
-These ICPs rely on structured truth but need **Agentic Portfolio** capabilities built on top of Neotoma.  
-They are **not** early targets for MVP revenue.
-### Included ICPs
-- **High-Net-Worth Individuals**  
-- **Multi-Jurisdiction Residents**  
-- **Crypto-Native Power Users (staking, LPs, vaults)**  
-- **Startup Founders with Equity Docs**  
-- **Family-Office-Lite Users**
-### Why Tier 4
-- High future ACV  
-- Complex requirements (risk, tax, multi-asset planning)  
-- Requires a mature truth layer + strategy engine  
-# TIER 5 — Execution-Layer ICPs (Agentic Wallet)  
-(Last to pursue; dependent on Agentic Portfolio + chain execution layer)
-### Included ICPs
-- **High-Frequency On-Chain Actors**  
-- **Agent-Compatible Crypto Users**  
-- **Protocol Explorers**  
-- **Bitcoin/Stacks Ecosystem Power Users**
-### Why Tier 5
-- Requires on-chain execution, safety systems, transaction simulation  
-- High regulatory and technical burden  
-- Must come after organizational expansion  
-# TIER 6 — Enterprise AI Deployments (Future)  
-(Only when Neotoma supports full org-wide agent orchestration)
-### Included ICPs
-- **Mid-market + enterprise teams (200–10,000 employees)**  
-- **Companies deploying dozens of internal AI agents**  
-- **Organizations requiring AI governance + auditability**
-### Why Tier 6
-- Highest ACV and long-term potential  
-- Highest product complexity  
-- Requires advanced permissions, multi-user governance, agent orchestration, and full organizational memory architecture  
-- Must be built after Neotoma is proven across many smaller teams  
-# Final Tier Summary (Prioritized for GTM)
-### **Tier 1 — Immediate Activation + Early Revenue**  
-- AI-Native Individuals  
-- High-Context Knowledge Workers  
-- AI-Native Small Teams (individual → team expansion)
-### **Tier 2 — Early B2B Expansion**  
-- Hybrid Product Teams  
-- Ops Teams  
-- Developer + AI Tool Integrators
-### **Tier 3 — B2C Power Users (Long-Term Organic Growth)**  
-- Cross-Border Solopreneurs  
-- Multi-System Workers  
-- Households
-### **Tier 4 — Strategy-Layer (Agentic Portfolio)**  
-- HNW, Multi-Jurisdiction, Equity-Heavy Founders, Crypto Power Users
-### **Tier 5 — Execution-Layer (Agentic Wallet)**  
-- On-chain operators, agent-compatible users, protocol explorers
-### **Tier 6 — Enterprise Deployments**  
-- org-wide AI memory substrate customers
-# One-Line GTM Summary
-**Start with AI-native individuals → expand to small AI-native teams → land hybrid product orgs → grow into strategy/execution layers → end in enterprise memory adoption.**
-## Agent Instructions
-### When to Load This Document
-Load when:
-- Planning GTM strategy or product roadmap
-- Prioritizing feature development
-- Making decisions about multi-user features vs single-user focus
-- Understanding which ICPs require which product layers (Truth vs Strategy vs Execution)
-### Required Co-Loaded Documents
-- `docs/NEOTOMA_MANIFEST.md` (always)
-- `docs/specs/MVP_OVERVIEW.md` (for MVP scope alignment)
-- `docs/specs/ICP_PROFILES.md` (for detailed ICP profiles)
-### Constraints Agents Must Enforce
-1. MVP MUST directly serve Tier 1 ICPs
-2. Tier 2+ features require explicit product maturity milestones
-3. Tier 4+ ICPs require Agentic Portfolio/Wallet layers (not Neotoma MVP scope)
-4. All product decisions must align with tier prioritization
-### Validation Checklist
-- [ ] Feature serves Tier 1 ICPs (MVP requirement)
-- [ ] Tier 2+ features clearly marked as post-MVP
-- [ ] Strategy/Execution layer features correctly attributed to Agentic Portfolio/Wallet
-- [ ] GTM roadmap follows tier progression