neotoma 0.3.0 → 0.3.2

package/docs/architecture/source_material_model.md

@@ -1,281 +0,0 @@
-# Source Model Architecture
-
-**Authoritative Vocabulary:** [`docs/vocabulary/canonical_terms.md`](../vocabulary/canonical_terms.md)
-
-## Overview
-
-The [source](../vocabulary/canonical_terms.md#source) model unifies [ingestion](../vocabulary/canonical_terms.md#ingestion) through a single write primitive. Agents and file upload handlers submit [source](../vocabulary/canonical_terms.md#source) via the unified `ingest` MCP action. The server processes [source](../vocabulary/canonical_terms.md#source) into [observations](../vocabulary/canonical_terms.md#observation) and [entities](../vocabulary/canonical_terms.md#entity) using [entity schemas](../vocabulary/canonical_terms.md#entity-schema) with deterministic [extraction](../vocabulary/canonical_terms.md#extraction) rules.
-
-**Key Principle:** Agents submit [source](../vocabulary/canonical_terms.md#source). The server compiles knowledge.
-
-## Three-Layer Truth Model
-
-Neotoma implements a three-layer truth model:
-
-1. **[Source](../vocabulary/canonical_terms.md#source)** — Unified [ingestion](../vocabulary/canonical_terms.md#ingestion) primitive (files + agent data)
-2. **[Observation](../vocabulary/canonical_terms.md#observation)** — Granular facts [extracted](../vocabulary/canonical_terms.md#extraction) from [source](../vocabulary/canonical_terms.md#source)
-3. **[Entity](../vocabulary/canonical_terms.md#entity)** — Logical thing with stable ID
-4. **[Snapshot](../vocabulary/canonical_terms.md#snapshot)** — Deterministic [reducer](../vocabulary/canonical_terms.md#reducer) output
-
-**Rationale:** [Source](../vocabulary/canonical_terms.md#source) serves as the document layer, unifying file uploads and agent submissions into a single [ingestion](../vocabulary/canonical_terms.md#ingestion) path. This eliminates the previous document/record separation and simplifies the architecture.
-
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-flowchart TD
-    SourceNode[Source<br/>Files + Agent Data]
-    Observation[Observation<br/>Granular Facts]
-    Entity[Entity<br/>Stable ID]
-    Snapshot[Snapshot<br/>Current Truth]
-    SourceNode -->|Extract| Observation
-    Observation -->|Merge via Reducer| Snapshot
-    Entity -.->|Target| Observation
-    Entity -.->|Represents| Snapshot
-    style SourceNode fill:#e1f5ff
-    style Observation fill:#fff4e6
-    style Entity fill:#e6ffe6
-    style Snapshot fill:#ffe6f0
-```
-
-## Unified `ingest` Action
-
-Agents and file handlers submit [source](../vocabulary/canonical_terms.md#source) via the unified `ingest` MCP action:
-
-**For Unstructured [Source](../vocabulary/canonical_terms.md#source):**
-```typescript
-// Unstructured source (files, raw text)
-{
-  user_id: string;                    // Required: User ID (UUID)
-  file_content: string;               // Base64-encoded file content
-  mime_type: string;                  // MIME type (e.g., "application/pdf")
-  original_filename?: string;         // Optional: Original filename
-  interpret?: boolean;                // Optional: Run interpretation (default: true)
-  interpretation_config?: {           // Optional: Interpretation configuration
-    provider?: string;
-    model_id?: string;
-    temperature?: number;
-  };
-}
-```
-
-**For Structured [Source](../vocabulary/canonical_terms.md#source):**
-```typescript
-// Structured source (JSON with entity types)
-{
-  user_id: string;                    // Required: User ID (UUID)
-  entities: Array<{                   // Array of entity data
-    entity_type: string;              // Entity type (e.g., "invoice", "note")
-    // ... entity-specific fields
-  }>;
-  provenance?: {
-    source_refs?: string[];           // Immediate source IDs
-    extracted_at: string;             // ISO 8601 timestamp
-    extractor_version: string;        // Version string
-    agent_id?: string;                // Optional agent identifier
-  };
-}
-```
-
-## [Entity Schema](../vocabulary/canonical_terms.md#entity-schema) (Replaces Capabilities)
-
-[Entity schemas](../vocabulary/canonical_terms.md#entity-schema) define how [source](../vocabulary/canonical_terms.md#source) is processed. Each [entity type](../vocabulary/canonical_terms.md#entity-type) has an [entity schema](../vocabulary/canonical_terms.md#entity-schema) that includes:
-
-```typescript
-interface EntitySchema {
-  entity_type: string;                        // "invoice", "transaction", etc.
-  schema_version: string;                     // Schema registry version
-  fields: Record<string, FieldDefinition>;    // Field definitions
-  merge_policies: Record<string, MergePolicy>; // Per-field merge policies
-  canonicalization_rules: CanonicalizationRules; // For deduplication
-  entity_extraction_rules: EntityExtractionRule[]; // Multi-entity extraction
-}
-```
-
-**[Entity Schema](../vocabulary/canonical_terms.md#entity-schema) Components:**
-- **Field definitions**: Types, validators, required fields
-- **Merge policies**: How [observations](../vocabulary/canonical_terms.md#observation) are merged into [entity snapshots](../vocabulary/canonical_terms.md#entity-snapshot)
-- **[Canonicalization rules](../vocabulary/canonical_terms.md#canonicalization-rules)**: For deterministic deduplication
-- **[Entity extraction rules](../vocabulary/canonical_terms.md#entity-extraction-rule)**: For multi-[entity](../vocabulary/canonical_terms.md#entity) [extraction](../vocabulary/canonical_terms.md#extraction)
-
-**Initial [Entity Types](../vocabulary/canonical_terms.md#entity-type):**
-- `invoice`
-- `transaction`
-- `receipt`
-- `contract`
-- `note`
-- `company`
-- `person`
-- `task`
-
-## [Entity Extraction Rules](../vocabulary/canonical_terms.md#entity-extraction-rule)
-
-All [source](../vocabulary/canonical_terms.md#source) [extracts](../vocabulary/canonical_terms.md#extraction) at least one [entity](../vocabulary/canonical_terms.md#entity). [Entity schemas](../vocabulary/canonical_terms.md#entity-schema) define [extraction](../vocabulary/canonical_terms.md#extraction) rules:
-
-```typescript
-interface EntityExtractionRule {
-  source_field?: string;      // Field in source
-  entity_type: string;        // Entity type to create
-  extraction_type: "material_self" | "field_value" | "array_items";
-}
-```
-
-**[Extraction](../vocabulary/canonical_terms.md#extraction) Types:**
-1. **`material_self`**: [Source](../vocabulary/canonical_terms.md#source) itself becomes [entity](../vocabulary/canonical_terms.md#entity) (e.g., note → note [entity](../vocabulary/canonical_terms.md#entity))
-2. **`field_value`**: [Extract](../vocabulary/canonical_terms.md#extraction) from single field (e.g., vendor_name → company [entity](../vocabulary/canonical_terms.md#entity))
-3. **`array_items`**: [Extract](../vocabulary/canonical_terms.md#extraction) from array field (e.g., tasks array → task [entities](../vocabulary/canonical_terms.md#entity))
-
-**Example: Note with tasks**
-```typescript
-// Structured source via unified ingest action
-{
-  user_id: "user-uuid",
-  entities: [{
-    entity_type: "note",
-    title: "Project Alpha",
-    content: "Project notes...",
-    tasks: ["Design UI", "Implement API", "Write tests"]
-  }],
-  provenance: {
-    source_refs: [],
-    extracted_at: "2025-01-15T10:00:00Z",
-    extractor_version: "neotoma-mcp:v0.2.15"
-  }
-}
-```
-
-**[Entities](../vocabulary/canonical_terms.md#entity) [extracted](../vocabulary/canonical_terms.md#extraction):**
-- Note [entity](../vocabulary/canonical_terms.md#entity) (from `material_self` rule): "Project Alpha"
-- Task [entity](../vocabulary/canonical_terms.md#entity): "Design UI"
-- Task [entity](../vocabulary/canonical_terms.md#entity): "Implement API"
-- Task [entity](../vocabulary/canonical_terms.md#entity): "Write tests"
-
-## Deduplication Strategy
-
-[Source](../vocabulary/canonical_terms.md#source) uses deterministic deduplication via `content_id`:
-
-1. **Normalize** data per [entity schema](../vocabulary/canonical_terms.md#entity-schema) [canonicalization rules](../vocabulary/canonical_terms.md#canonicalization-rules)
-2. **Compute hash** from: `{ entity_type, normalized_body, source_refs, extractor_version }`
-3. **Check for existing** [source](../vocabulary/canonical_terms.md#source) with same `content_id`
-4. **Return existing** if duplicate, **create new** if unique
-
-**Unique constraint:** `content_id` is unique in `sources` table.
-
-## [Provenance](../vocabulary/canonical_terms.md#provenance) Tracking
-
-[Source](../vocabulary/canonical_terms.md#source) [provenance](../vocabulary/canonical_terms.md#provenance) includes:
-- **`source_refs`**: Immediate source IDs (not full chain)
-- **`extracted_at`**: ISO 8601 timestamp
-- **`extractor_version`**: Version of [extraction](../vocabulary/canonical_terms.md#extraction) logic
-- **`agent_id`**: Optional agent identifier
-
-**[Provenance](../vocabulary/canonical_terms.md#provenance) chain:** [Source](../vocabulary/canonical_terms.md#source) → [Observation](../vocabulary/canonical_terms.md#observation) → [Entity](../vocabulary/canonical_terms.md#entity) → [Snapshot](../vocabulary/canonical_terms.md#snapshot)
-
-Each layer maintains full [provenance](../vocabulary/canonical_terms.md#provenance):
-- [Observations](../vocabulary/canonical_terms.md#observation) reference `source_material_id`
-- [Snapshots](../vocabulary/canonical_terms.md#snapshot) include [provenance](../vocabulary/canonical_terms.md#provenance) from [observations](../vocabulary/canonical_terms.md#observation)
-- Timeline [events](../vocabulary/canonical_terms.md#event) reference [source](../vocabulary/canonical_terms.md#source)
-
-## [Ingestion](../vocabulary/canonical_terms.md#ingestion) Flow
-
-### Unstructured [Source](../vocabulary/canonical_terms.md#source) (Files)
-
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-flowchart LR
-    File[File Upload]
-    Ingest[Unified ingest]
-    Store[Store Source]
-    Interpret[Interpretation]
-    Structured[Structured Source]
-    Schema[Entity Schema Processing]
-    Obs[Observations]
-    File --> Ingest
-    Ingest --> Store
-    Store --> Interpret
-    Interpret --> Structured
-    Structured --> Schema
-    Schema --> Obs
-```
-
-1. **Upload file** via `ingest` with `file_content` and `mime_type`
-2. **Store** unstructured [source](../vocabulary/canonical_terms.md#source) with content-addressed deduplication
-3. **Run [interpretation](../vocabulary/canonical_terms.md#interpretation)** to transform into structured [source](../vocabulary/canonical_terms.md#source) with [entity types](../vocabulary/canonical_terms.md#entity-type)
-4. **Process via [entity schema](../vocabulary/canonical_terms.md#entity-schema)** for normalization and [entity extraction](../vocabulary/canonical_terms.md#entity-extraction-rule)
-5. **Create [observations](../vocabulary/canonical_terms.md#observation)** for each [extracted](../vocabulary/canonical_terms.md#extraction) [entity](../vocabulary/canonical_terms.md#entity)
-
-### Structured [Source](../vocabulary/canonical_terms.md#source) (Agent Data)
-
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-flowchart LR
-    Agent[Agent Submission]
-    Ingest[Unified ingest]
-    Store[Store Source]
-    Schema[Entity Schema Processing]
-    Obs[Observations]
-    Agent --> Ingest
-    Ingest --> Store
-    Store --> Schema
-    Schema --> Obs
-```
-
-1. **Submit** via `ingest` with `entities` array
-2. **Store** structured [source](../vocabulary/canonical_terms.md#source) with content-addressed deduplication
-3. **Process via [entity schema](../vocabulary/canonical_terms.md#entity-schema)** for normalization and [entity extraction](../vocabulary/canonical_terms.md#entity-extraction-rule)
-4. **Create [observations](../vocabulary/canonical_terms.md#observation)** for each [extracted](../vocabulary/canonical_terms.md#extraction) [entity](../vocabulary/canonical_terms.md#entity)
-
-**Unified [ingestion](../vocabulary/canonical_terms.md#ingestion):** Files and agent submissions both create [source](../vocabulary/canonical_terms.md#source) — single write primitive.
-
-## UX Model
-
-**Primary UX:** [Entities](../vocabulary/canonical_terms.md#entity), [observations](../vocabulary/canonical_terms.md#observation), [relationships](../vocabulary/canonical_terms.md#relationship) (what users interact with)
-
-**Secondary UX:** [Source](../vocabulary/canonical_terms.md#source) inspection (historical/debugging via MCP queries, temporal log review)
-
-**Key Points:**
-- [Source](../vocabulary/canonical_terms.md#source) is internal storage artifacts, not primary user-facing objects
-- File uploads create [source](../vocabulary/canonical_terms.md#source), but UI shows resulting [entities](../vocabulary/canonical_terms.md#entity)/[observations](../vocabulary/canonical_terms.md#observation)
-- [Source](../vocabulary/canonical_terms.md#source) inspection available via MCP queries for debugging/[provenance](../vocabulary/canonical_terms.md#provenance)
-
-**UI Navigation:**
-- [Entity](../vocabulary/canonical_terms.md#entity) lists and detail views
-- [Observation](../vocabulary/canonical_terms.md#observation) [provenance](../vocabulary/canonical_terms.md#provenance) panels
-- [Relationship](../vocabulary/canonical_terms.md#relationship) graphs
-- Timeline views
-
-**[Source](../vocabulary/canonical_terms.md#source) Inspection:**
-- MCP queries for [source](../vocabulary/canonical_terms.md#source) history
-- Temporal log review (audit trail)
-- [Provenance](../vocabulary/canonical_terms.md#provenance) chains (which [source](../vocabulary/canonical_terms.md#source) contributed to [entity](../vocabulary/canonical_terms.md#entity))
-
-## Migration from Legacy Systems
-
-**v0.2.15 Breaking Change:**
-- **Removed:** `store_record` MCP action
-- **Deprecated:** `submit_payload` and `ingest_structured` MCP actions (merged into unified `ingest`)
-- **Eliminated:** `records` table (replaced by `sources` table)
-- **Updated:** [Observations](../vocabulary/canonical_terms.md#observation) reference `source_material_id` instead of `source_record_id` or `source_payload_id`
-- **Eliminated:** Capability registry (rules moved to [entity schemas](../vocabulary/canonical_terms.md#entity-schema))
-
-**Migration strategy:** See [`docs/releases/v0.2.15/release_plan.md`](../releases/v0.2.15/release_plan.md)
-
-## Design Decisions
-
-1. **[Source](../vocabulary/canonical_terms.md#source) Storage:** Dedicated `sources` table with unique constraint on `content_id`
-2. **[Entity Schema](../vocabulary/canonical_terms.md#entity-schema) Versioning:** Version bumps create new schema version
-3. **[Provenance](../vocabulary/canonical_terms.md#provenance) Depth:** `source_refs` includes immediate source IDs only (not full chain)
-4. **Three-Layer Model:** [Source](../vocabulary/canonical_terms.md#source) → [Observation](../vocabulary/canonical_terms.md#observation) → [Entity](../vocabulary/canonical_terms.md#entity) → [Snapshot](../vocabulary/canonical_terms.md#snapshot)
-5. **Unified [Ingestion](../vocabulary/canonical_terms.md#ingestion):** File uploads and agent submissions both use unified `ingest` action
-6. **[Observation](../vocabulary/canonical_terms.md#observation) Schema:** `source_material_id` references [source](../vocabulary/canonical_terms.md#source)
-7. **[Entity Extraction](../vocabulary/canonical_terms.md#entity-extraction-rule):** All [source](../vocabulary/canonical_terms.md#source) [extracts](../vocabulary/canonical_terms.md#extraction) at least one [entity](../vocabulary/canonical_terms.md#entity)
-8. **No Capabilities:** [Canonicalization rules](../vocabulary/canonical_terms.md#canonicalization-rules) and [entity extraction rules](../vocabulary/canonical_terms.md#entity-extraction-rule) defined in [entity schemas](../vocabulary/canonical_terms.md#entity-schema)
-
-## Success Criteria
-
-- Agents can submit [source](../vocabulary/canonical_terms.md#source) via unified `ingest` MCP action
-- Same [source](../vocabulary/canonical_terms.md#source) content → same `content_id` (deterministic deduplication)
-- [Source](../vocabulary/canonical_terms.md#source) compiles into [observations](../vocabulary/canonical_terms.md#observation) → [entities](../vocabulary/canonical_terms.md#entity) → [entity snapshots](../vocabulary/canonical_terms.md#entity-snapshot)
-- File uploads create [source](../vocabulary/canonical_terms.md#source) (unified [ingestion](../vocabulary/canonical_terms.md#ingestion) path)
-- [Observations](../vocabulary/canonical_terms.md#observation) reference `source_material_id`
-- All [source](../vocabulary/canonical_terms.md#source) [extracts](../vocabulary/canonical_terms.md#extraction) at least one [entity](../vocabulary/canonical_terms.md#entity)
-- Multi-[entity](../vocabulary/canonical_terms.md#entity) [extraction](../vocabulary/canonical_terms.md#extraction) supported (note with tasks example)
-

package/docs/conventions/TEST_EXECUTION_IMPROVEMENTS.md

@@ -1,205 +0,0 @@
-# Test Execution Improvements Summary
-
-**Date:** 2026-01-23  
-**Purpose:** Document improvements to agent test execution workflow to prevent bugs from being discovered only during manual testing
-
-## Problem Statement
-
-Agents were implementing features but not running tests automatically, leading to:
-- Bugs discovered only during manual testing
-- Time-intensive debugging via logs and screenshots
-- Weak test assertions that didn't catch real bugs
-- Missing edge case coverage
-
-## Solution
-
-Created comprehensive test execution rules and updated workflows to enforce mandatory test execution.
-
-## New Rules Created
-
-### 1. Agent Test Execution Rules
-**File:** `docs/conventions/agent_test_execution_rules.mdc`
-
-**Purpose:** Ensures agents automatically run tests after every code change and fix failures before proceeding.
-
-**Key Requirements:**
-- MANDATORY test execution after every code change
-- MANDATORY test fixes before proceeding if tests fail
-- MANDATORY test verification before marking implementation complete
-- Test execution commands for different change types (backend, frontend, DB)
-
-**When Applied:**
-- After implementing new features
-- After modifying existing code
-- Before marking any implementation as complete
-
-### 2. Test-First Workflow Rules
-**File:** `docs/conventions/test_first_workflow_rules.mdc`
-
-**Purpose:** Enforces test-first (TDD) or test-alongside development to catch bugs early.
-
-**Key Requirements:**
-- Write tests FIRST or alongside implementation (not after)
-- Run tests frequently during development
-- Fix test failures immediately
-- Verify coverage meets requirements
-
-**Workflow Options:**
-- Pure TDD: Write tests → Run (RED) → Implement (GREEN) → Refactor
-- Test-Alongside: Write tests alongside implementation, run frequently
-
-### 3. UI Test Requirements Rules
-**File:** `docs/conventions/ui_test_requirements_rules.mdc`
-
-**Purpose:** Ensures UI changes are thoroughly tested with Playwright E2E tests.
-
-**Key Requirements:**
-- MANDATORY Playwright tests for all UI changes
-- Test user interactions and flows
-- Test error states and edge cases
-- Test responsive behavior
-
-**Test Types Required:**
-- Component rendering tests
-- User interaction tests
-- Form submission tests
-- Error state tests
-- Edge case tests (empty states, loading states)
-- Responsive behavior tests
-
-## Workflow Updates
-
-### 1. Feature Unit Execution Instructions
-**File:** `docs/feature_units/standards/execution_instructions.md`
-
-**Updates:**
-- Added mandatory test execution steps to implementation order
-- Added references to new test execution rules
-- Added test verification step before completion
-- Updated constraints to require test execution
-
-**New Implementation Order:**
-1. Load documentation (including test execution rules)
-2. Implement domain logic + write/run unit tests immediately
-3. Implement application logic + write/run integration tests immediately
-4. Implement UI + write/run E2E tests immediately
-5. **Final test verification** (run full test suite)
-6. Documentation
-7. Review and deploy
-
-### 2. Pre-Commit Hook
-**File:** `.husky/pre-commit`
-
-**Updates:**
-- Added mandatory type check (`npm run type-check`)
-- Added mandatory lint check (`npm run lint`)
-- Added mandatory unit tests (`npm test`)
-- Added conditional integration tests (if backend/DB files changed)
-- Added conditional E2E tests (if frontend/UI files changed)
-
-**Behavior:**
-- Blocks commits if any tests fail
-- Runs only relevant tests based on changed files
-- Provides clear error messages
-
-## How Agents Will Use These Rules
-
-### During Feature Implementation
-
-1. **Load test execution rules:**
-   - `docs/conventions/agent_test_execution_rules.mdc`
-   - `docs/conventions/test_first_workflow_rules.mdc`
-   - `docs/conventions/ui_test_requirements_rules.mdc` (if UI changes)
-
-2. **Follow test-first workflow:**
-   - Write tests first (TDD) or alongside implementation
-   - Run tests after each function/component
-   - Fix failures immediately
-
-3. **Before marking complete:**
-   - Run full test suite
-   - Verify all tests pass
-   - Check coverage meets requirements
-   - Document test results
-
-### Test Execution Commands
-
-**For backend changes:**
-```bash
-npm run type-check
-npm run lint
-npm test
-npm run test:integration
-```
-
-**For frontend changes:**
-```bash
-npm run type-check
-npm run lint
-npm test
-npm run test:e2e
-```
-
-**For all changes:**
-```bash
-npm run type-check
-npm run lint
-npm test
-```
-
-## Expected Outcomes
-
-### Immediate Benefits
-
-1. **Bugs caught early:** Tests run automatically, catching bugs before manual testing
-2. **Faster feedback:** Agents get immediate feedback on code changes
-3. **Better test quality:** Test-first workflow ensures comprehensive coverage
-4. **Reduced manual debugging:** Fewer bugs reach manual testing phase
-
-### Long-Term Benefits
-
-1. **Higher code quality:** Comprehensive test coverage prevents regressions
-2. **Faster development:** Automated test execution saves time
-3. **Better agent behavior:** Agents learn to test proactively
-4. **Reduced debugging time:** Bugs caught early are easier to fix
-
-## Validation
-
-To verify these improvements are working:
-
-1. **Check agent behavior:**
-   - Agents should run tests after every code change
-   - Agents should fix failing tests before proceeding
-   - Agents should document test results in status updates
-
-2. **Check test coverage:**
-   - Run `npm run test:coverage` to verify coverage
-   - Check that new features have tests
-   - Verify edge cases are tested
-
-3. **Check pre-commit hook:**
-   - Try committing with failing tests (should be blocked)
-   - Verify only relevant tests run based on changed files
-
-## Related Documents
-
-- `docs/conventions/agent_test_execution_rules.mdc` — Mandatory test execution
-- `docs/conventions/test_first_workflow_rules.mdc` — Test-first workflow
-- `docs/conventions/ui_test_requirements_rules.mdc` — UI test requirements
-- `docs/testing/testing_standard.md` — Testing standards
-- `docs/testing/test_quality_enforcement_rules.mdc` — Test quality patterns
-- `docs/feature_units/standards/execution_instructions.md` — Feature Unit execution workflow
-
-## Next Steps
-
-1. **Monitor agent behavior:** Watch for agents following new rules
-2. **Review test coverage:** Ensure new features have comprehensive tests
-3. **Adjust rules as needed:** Refine rules based on actual usage
-4. **Document learnings:** Update rules with lessons learned from bugs
-
-## Notes
-
-- Rules are automatically synced to `.cursor/rules/` via setup script
-- Pre-commit hook will block commits if tests fail
-- Agents should load these rules when implementing features
-- Test execution is now mandatory, not optional

package/docs/conventions/always_on_rules_review.md

@@ -1,66 +0,0 @@
-# Review: Repo Rules Currently Always Applied but Should Be On-Demand
-
-## Summary
-
-The selective rule injection plan defines **three always-on repo rules**: `docs/context/index_rules.mdc`, `docs/conventions/rule_router_rules.mdc`, and `docs/foundation/agent_instructions_rules.mdc`. The foundation setup script **honors `cursor_rules_manifest.json`** when present: it installs only the allowlisted foundation rules and the three repo rules above (kernel-only), and removes any other rules from `.cursor/rules/`. Run `npm run setup:cursor` with `jq` installed to get kernel-only install. Below is the list of repo rules that are **on-demand only** (loaded via the router when the trigger matches).
-
-## Intended Always-On (per manifest)
-
-We use **three** always-on repo rules so each has a single job: index (where to go), router (when to load what), agent instructions (constraints and checklist). You can instead use **one** always-on rule; see "Single always-on option" below.
-
-| Source | Installed as | Status |
-|--------|--------------|--------|
-| `docs/context/index_rules.mdc` | `context_index_rules.mdc` | Installed (correct) |
-| `docs/foundation/agent_instructions_rules.mdc` | `foundation_agent_instructions_rules.mdc` | Installed (correct) |
-| `docs/conventions/rule_router_rules.mdc` | `conventions_rule_router_rules.mdc` | Installed (correct) |
-
-### Single always-on option
-
-To have **one** always-on repo rule: add a loader rule that tells the agent to load the three docs above from `docs/` at session start. Then install only that loader in `.cursor/rules/` and keep the three as normal docs (not copied). Steps:
-
-1. Add `docs/context/kernel_loader_rules.mdc` (or similar) whose content is: at session start, load in order `docs/context/index_rules.mdc`, `docs/conventions/rule_router_rules.mdc`, `docs/foundation/agent_instructions_rules.mdc`.
-2. In `cursor_rules_manifest.json`, set `always_on.repo_rules` to that one path, e.g. `["docs/context/kernel_loader_rules.mdc"]`.
-3. Run `npm run setup:cursor`. Only the loader is copied; the three source docs stay in `docs/` and are loaded by following the loader.
-
-## Repo Rules That Should NOT Be Always Applied (on-demand only)
-
-These **20** repo rules are currently in `.cursor/rules/` and always applied. Per the manifest they should be loaded only when the router trigger matches.
-
-| Installed name | Source path | Router trigger (if any) |
-|----------------|-------------|-------------------------|
-| `conventions_code_conventions_rules.mdc` | `docs/conventions/code_conventions_rules.mdc` | Code style, naming, TypeScript/SQL/YAML/shell |
-| `conventions_documentation_standards_rules.mdc` | `docs/conventions/documentation_standards_rules.mdc` | Creating or editing documentation |
-| `conventions_plan_format_rules.md` | `docs/conventions/plan_format_rules.md` | Creating or editing documentation |
-| `conventions_prefer_cli_tools_rules.mdc` | `docs/conventions/prefer_cli_tools_rules.mdc` | Prefer CLI over dashboard |
-| `conventions_social_media_conventions_rules.mdc` | `docs/conventions/social_media_conventions_rules.mdc` | Social media, tweets, posts |
-| `conventions_ui_imports_rules.mdc` | `docs/conventions/ui_imports_rules.mdc` | Modifying UI, components |
-| `conventions_ui_style_guide_enforcement_rules.mdc` | `docs/conventions/ui_style_guide_enforcement_rules.mdc` | Modifying UI |
-| `conventions_ui_test_requirements_rules.mdc` | `docs/conventions/ui_test_requirements_rules.mdc` | UI test coverage |
-| `developer_agent_instructions_sync_rules.mdc` | `docs/developer/agent_instructions_sync_rules.mdc` | MCP/CLI instruction parity |
-| `developer_bug_learning_rules.mdc` | `docs/developer/bug_learning_rules.mdc` | Bug fix, regression test, learning |
-| `developer_cli_debugging_rules.mdc` | `docs/developer/cli_debugging_rules.mdc` | Debugging CLI |
-| `developer_env_check_rules.mdc` | `docs/developer/env_check_rules.mdc` | Env vars, .env, config |
-| `developer_mcp_bug_investigation_rules.mdc` | `docs/developer/mcp_bug_investigation_rules.mdc` | Debugging MCP |
-| `developer_pre_release_validation_rules.mdc` | `docs/developer/pre_release_validation_rules.mdc` | Pre-release, validation |
-| `testing_full_route_coverage_rules.md` | `docs/testing/full_route_coverage_rules.md` | UI test coverage, route coverage |
-| `testing_integration_test_quality_rules.mdc` | `docs/testing/integration_test_quality_rules.mdc` | Writing/reviewing integration tests |
-| `testing_test_quality_enforcement_rules.mdc` | `docs/testing/test_quality_enforcement_rules.mdc` | Writing/reviewing tests |
-| `ui_design_system_automation_rules.mdc` | `docs/ui/design_system_automation_rules.mdc` | Modifying UI, design system |
-| `ui_design_system_sync_rules.mdc` | `docs/ui/design_system_sync_rules.mdc` | Modifying UI, design system |
-| `docs_anchor_and_docs_ui.mdc` | **No source in docs/** (file exists only in `.cursor/rules/`) | **Missing from router** (see below) |
-
-## Gap: docs_anchor_and_docs_ui (optional)
-
-`docs_anchor_and_docs_ui.mdc` governs documentation location and web docs navigation. With manifest-based install it is **not** in the kernel (no source under `docs/` in the manifest). The setup script removes it when using the manifest. To have it on-demand: add a source file under `docs/` (e.g. `docs/conventions/docs_anchor_and_docs_ui_rules.mdc`), add it to the router table with a trigger such as **Creating or moving documentation, updating docs navigation or doc dependencies**, and optionally add it to `cursor_rules_manifest.json` `always_on.repo_rules` if you want it always-on.
-
-## Manifest enforcement
-
-When `cursor_rules_manifest.json` exists in the repo root and `jq` is installed, `npm run setup:cursor` installs only the kernel (allowlisted foundation rules + the three repo rules). Any other file in `.cursor/rules/` (e.g. `neotoma_cli.mdc`, `docs_anchor_and_docs_ui.mdc`) is removed. The CLI may re-add `neotoma_cli.mdc` when you run `neotoma cli-instructions check` or start a session.
-
-## Why some rules still have alwaysApply: true (Cursor/Claude)
-
-**Source of truth:** Foundation rule files (e.g. `foundation/agent_instructions/cursor_rules/*.mdc`) and docs rule files use frontmatter with `alwaysApply: true` by default. Cursor’s setup copies from these sources; the Claude setup script (`scripts/setup_claude_instructions.sh`) also copies frontmatter **verbatim** and does not use the cursor manifest or change `alwaysApply`. So every rule that is copied into `.claude/rules/` keeps whatever the source has.
-
-**Result:** In `.claude/rules/`, every rule ends up with `alwaysApply: true` because the sources were written when the model was “all rules always on.” That burns context even when a rule is only needed in specific situations (e.g. “document an always/never instruction,” “create a rule,” “fix a bug”).
-
-**Fix:** In the **source** (foundation or docs), set `alwaysApply: false` and keep a clear `description` for rules that are only needed in specific contexts. Then both Cursor and Claude will get “Apply Intelligently” when scripts run. Example: `instruction_documentation.mdc` is only needed when the user says “always X” or “never Y” or when creating/editing rules, so it should have `alwaysApply: false`.

package/docs/conventions/code_conventions_implementation.md

@@ -1,111 +0,0 @@
-# Code Conventions Implementation Summary
-## Overview
-Successfully implemented code conventions across the Neotoma codebase per `docs/conventions/code_conventions.md`.
-## Completed Work
-### 1. Documentation
-✅ **Created `docs/conventions/code_conventions.md`** (994 lines)
-- TypeScript/TSX conventions (naming, organization, types, error handling, determinism)
-- SQL conventions (naming, migrations, RLS patterns, determinism)
-- YAML conventions (structure, manifests, keys)
-- Shell script conventions (shebang, error handling, functions)
-- Cross-language patterns and references to existing standards
-- Agent instructions section
-✅ **Updated Documentation References**
-- `docs/conventions/documentation_standards.md` - Added code conventions reference
-- Foundation rules in `.cursor/rules/` - Code conventions referenced in agent instructions
-### 2. ESLint Configuration
-✅ **Updated `.eslintrc.json`**
-Added quotes rule to enforce double quotes:
-```json
-{
-  "rules": {
-    "@typescript-eslint/no-explicit-any": "warn",
-    "quotes": [
-      "error",
-      "double",
-      {
-        "avoidEscape": true,
-        "allowTemplateLiterals": true
-      }
-    ]
-  }
-}
-```
-### 3. Prettier Configuration
-✅ **Created `.prettierrc.json`**
-```json
-{
-  "semi": true,
-  "singleQuote": false,
-  "trailingComma": "es5",
-  "printWidth": 100,
-  "tabWidth": 2
-}
-```
-### 4. Code Formatting
-✅ **Converted All Quotes to Double Quotes**
-- Converted 146 single-quote imports to double quotes across 58 files
-- Converted string literals to double quotes throughout codebase
-- Used combination of sed and Prettier for reliable conversion
-**Tools Used:**
-1. sed - Initial bulk conversion of import statements
-2. Prettier - Final formatting pass for all TypeScript files
-3. Manual fixes - 3 files with unterminated string literals
-## Verification
-### Quote Conversion Status
-✅ **0 quote errors** remaining in ESLint
-✅ **0 single-quote imports** found in codebase  
-✅ **All imports now use double quotes**
-✅ **All string literals now use double quotes**
-### Remaining Lint Issues
-The 47 errors and 65 warnings are **NOT** quote-related:
-**Errors (47):**
-- Unused variables (can be addressed separately)
-- Unnecessary escape characters (regex patterns)
-**Warnings (65):**
-- `any` type usage (expected, already configured as warnings)
-These issues existed before the quote conversion and are tracked separately.
-### File Statistics
-- **Files formatted:** 138 TypeScript files in `src/`
-- **Files with quote fixes:** 58 files
-- **Documentation files created:** 1 (code_conventions.md)
-- **Configuration files created:** 1 (.prettierrc.json)
-- **Configuration files updated:** 1 (.eslintrc.json)
-## Compliance Status
-### ✅ 100% Compliant
-The codebase now **fully aligns** with documented conventions:
-- ✅ **File naming:** PascalCase for React components, snake_case for others
-- ✅ **Function naming:** camelCase
-- ✅ **Type/Interface naming:** PascalCase
-- ✅ **Constants:** UPPER_SNAKE_CASE
-- ✅ **String quotes:** Double quotes everywhere
-- ✅ **SQL naming:** snake_case for tables, columns, indexes
-- ✅ **YAML conventions:** 2-space indentation, snake_case keys
-- ✅ **Code organization:** Proper import order, export patterns
-- ✅ **ESLint enforcement:** Quotes rule active
-## Commands for Future Use
-### Check for Quote Violations
-```bash
-npm run lint | grep "quote"
-```
-### Auto-Fix Quote Issues
-```bash
-npx prettier --write "src/**/*.ts"
-```
-### Full Lint Check
-```bash
-npm run lint
-```
-## Next Steps (Optional)
-While the code conventions are now fully implemented, these improvements could be addressed separately:
-1. **Address Unused Variables** - Remove or prefix with underscore
-2. **Fix Unnecessary Escapes** - Update regex patterns
-3. **Reduce `any` Usage** - Replace with proper types where feasible
-These are lower priority and don't affect convention compliance.
-## Summary
-✅ **Task: Complete**
-✅ **Convention Compliance: 100%**
-✅ **Quote Conversion: Successful**
-✅ **ESLint Configuration: Active**
-✅ **Prettier Configuration: Added**
-All code now follows the documented conventions in `docs/conventions/code_conventions.md`.