neotoma 0.3.0 → 0.3.2

package/docs/ui/design_system/settings_components.md

@@ -1,29 +0,0 @@
-# Settings Components
-
-## Settings Page (FU-306)
-
-**Layout:**
-
-- Sidebar navigation (settings sections)
-- Main content area (form sections)
-- Sections: Preferences, Integrations, Account, Billing
-
-**Form Controls:**
-
-- Locale selector: Dropdown (Select component)
-- Theme toggle: Toggle switch (light/dark)
-- Connected integrations: List with disconnect buttons
-- Save button: Primary, sticky footer
-
-**Integration List:**
-
-- Provider name, icon
-- Status badge (Connected, Disconnected, Error)
-- Last sync timestamp (small, muted)
-- Disconnect button (ghost, destructive on hover)
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`component_styles.md`](./component_styles.md) - Form control styles
-- [`implementation_notes.md`](./implementation_notes.md) - Component library recommendations

package/docs/ui/design_system/spacing_and_layout.md

@@ -1,67 +0,0 @@
-# Spacing and Layout
-
-## Spacing Scale
-
-```yaml
-spacing:
-  xs: "0.25rem" # 4px
-  sm: "0.5rem" # 8px
-  md: "1rem" # 16px
-  lg: "1.5rem" # 24px
-  xl: "2rem" # 32px
-  "2xl": "3rem" # 48px
-  "3xl": "4rem" # 64px
-```
-
-**Usage:**
-
-- **xs:** Tight spacing (icon + text, inline elements)
-- **sm:** Component internal padding, small gaps
-- **md:** Standard spacing (between sections, component padding)
-- **lg:** Section spacing, card padding
-- **xl:** Major section separation
-- **2xl/3xl:** Page-level spacing
-
-## Layout Density
-
-**Default: Comfortable**
-
-```yaml
-comfortable:
-  row_height: "40px" # Table rows, list items
-  component_padding: "8px 12px" # Buttons, inputs
-  section_spacing: "1.5rem" # Between sections
-  card_padding: "1rem" # Card internal padding
-```
-
-**Compact (Optional):**
-
-```yaml
-compact:
-  row_height: "32px"
-  component_padding: "6px 10px"
-  section_spacing: "1rem"
-  card_padding: "0.75rem"
-```
-
-**Rationale:** Comfortable density matches professional tools (Zotero, legal platforms); allows information density without feeling cramped.
-
-## Grid System
-
-```yaml
-grid:
-  columns: 12
-  gutter: "1rem" # 16px between columns
-  container_max_width: "1280px" # Max content width
-  breakpoints:
-    mobile: "640px"
-    tablet: "768px"
-    desktop: "1024px"
-    wide: "1280px"
-```
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`responsive_design.md`](./responsive_design.md) - Responsive breakpoints and mobile considerations
-- [`component_styles.md`](./component_styles.md) - Component spacing usage

package/docs/ui/design_system/style_guide.md

@@ -1,395 +0,0 @@
-# Style Guide
-
-_(UI Copy Rules for Neotoma)_
-
-## Purpose
-
-This guide defines writing style rules for all Neotoma UI copy (labels, buttons, messages, placeholders, tooltips, errors, empty states). These rules ensure consistent, professional text that avoids AI-generated patterns and maintains clarity across all user-facing text.
-
-This guide adapts `docs/conventions/writing_style_guide.md` for in-app text. Apply both when writing UI copy and documentation.
-
-## Core Principles
-
-1. **Direct and declarative**: Use simple, clear statements
-2. **Active voice**: Prefer "The system processes files" over "Files are processed by the system"
-3. **One idea per sentence**: Break complex thoughts into multiple sentences
-4. **No AI-generated patterns**: Avoid machine-written stylistic quirks
-5. **Professional tone**: Technical and precise, not conversational
-
-## Prohibited Patterns
-
-### Em Dashes and En Dashes
-
-**NEVER use:**
-- Em dashes (—)
-- En dashes (–)
-
-**Use instead:**
-- Commas for appositives and lists: "files, records, and entities"
-- Periods to separate ideas: "The system processes files. It then validates them."
-- Colons to introduce lists or explanations: "Three steps: processing, validation, and storage"
-- Standard hyphens (-) for compound words and ranges: "file-based", "v0.1.0-v0.2.0"
-
-**Examples:**
-❌ "Neotoma transforms fragmented personal data—connecting people, companies, and events—into a unified memory graph."
-✅ "Neotoma transforms fragmented personal data into a unified memory graph. The graph connects people, companies, and events."
-
-❌ "The system processes files—validates them—and stores records."
-✅ "The system processes files, validates them, and stores records."
-
-### Conversational Transitions
-
-**NEVER use:**
-- "Now, let's..."
-- "So, you might..."
-- "Interestingly..."
-- "As you can see..."
-- "Keep in mind that..."
-
-**Use instead:**
-- Direct statements without transition words
-- "The system..." instead of "Now, the system..."
-- Start with the subject directly
-
-### Soft Questions and Offers
-
-**NEVER use:**
-- "Would you like to...?"
-- "Have you considered...?"
-- "Want to try...?"
-- "Need help with...?"
-
-**Use instead:**
-- Direct instructions: "Use the `store_record` action to..."
-- Declarative statements: "The system supports..."
-
-### Motivational Language
-
-**NEVER use:**
-- "Get started!"
-- "Try it now!"
-- "You're all set!"
-- "Ready to go!"
-- "Let's dive in!"
-
-**Use instead:**
-- Neutral completion statements: "Setup is complete."
-- Direct next steps: "Next, configure environment variables."
-
-### Excessive Parentheticals
-
-**NEVER use:**
-- Multiple parenthetical asides in one sentence
-- Long explanatory parentheticals that break flow
-
-**Use instead:**
-- Separate sentences for explanations
-- Commas for brief clarifications
-
-**Example:**
-❌ "The system processes files (which can be PDFs, images, or documents) and extracts data (using deterministic rules) before storing records (in the PostgreSQL database)."
-✅ "The system processes files. Supported formats include PDFs, images, and documents. It extracts data using deterministic rules and stores records in the PostgreSQL database."
-
-### Redundant Qualifiers
-
-**NEVER use:**
-- "very", "quite", "rather", "somewhat", "pretty"
-- "incredibly", "extremely", "highly"
-
-**Use instead:**
-- Direct adjectives: "fast" not "very fast"
-- Specific measurements when available: "processes 100 files/second" not "very quickly"
-
-### Complex Sentence Structures
-
-**NEVER use:**
-- Overly nested clauses
-- Multiple dependent clauses in one sentence
-- Sentences over 25 words
-
-**Use instead:**
-- Simple, short sentences (15-20 words)
-- One idea per sentence
-- Break complex thoughts into multiple sentences
-
-### Long Paragraphs
-
-**NEVER use:**
-- Paragraphs over 5 sentences
-- Dense blocks of text without breaks
-- Multiple distinct ideas in one paragraph
-- Long series of related points in paragraph form
-
-**Use instead:**
-- Short paragraphs (3-4 sentences, maximum 5)
-- One main idea per paragraph
-- Break long paragraphs into multiple focused paragraphs
-- Use formatting techniques for complex topics: lists, subheadings, or structured sections
-- Convert series of related points into bulleted or numbered lists
-- Use lists when presenting multiple items, features, or concepts
-
-**When to use formatting techniques:**
-- **Lists**: When presenting 3+ related items, features, capabilities, or concepts
-- **Subheadings**: When organizing multiple distinct topics or sections
-- **Structured sections**: When breaking down complex explanations into digestible parts
-
-### Immediate Repetition of Proper Nouns
-
-**NEVER use:**
-- Repeating the same proper noun in consecutive sentences
-- Starting multiple consecutive sentences with the same proper noun
-- Overusing proper nouns when pronouns or descriptive terms would work better
-
-**Use instead:**
-- Use the proper noun when needed for clarity, emphasis, or after a paragraph break
-- Use pronouns (it, they, them) after first mention within the same paragraph
-- Use descriptive terms (the system, the platform, the service) to vary sentence structure
-- Vary sentence structure to avoid repetitive openings
-
-**Guidelines for proper noun usage:**
-- **Use the proper noun**: At the start of a new paragraph, when clarity is needed, or when emphasizing the subject
-- **Use pronouns/descriptive terms**: Within the same paragraph after first mention, or when the subject is clear from context
-- **Avoid**: Repeating the proper noun in consecutive sentences within the same paragraph
-
-## Preferred Patterns
-
-### Formatting Techniques
-
-**Use formatting to improve readability:**
-- **Lists**: Convert series of related points into bulleted or numbered lists
-- **Subheadings**: Break long sections into focused subsections
-- **Bold text**: Emphasize key terms or concepts (sparingly)
-- **Structured sections**: Organize complex topics into digestible parts
-
-**When to use lists:**
-- Presenting 3+ related items, features, or capabilities
-- Explaining multiple steps or components
-- Comparing or contrasting multiple concepts
-- Listing examples or use cases
-
-### Punctuation
-
-- **Commas**: For lists, appositives, and joining related clauses
-- **Periods**: To end sentences and separate distinct ideas
-- **Colons**: To introduce lists, explanations, or definitions
-- **Semicolons**: Sparingly, only to connect closely related independent clauses
-- **Hyphens**: For compound words (file-based, user-controlled) and ranges (v0.1.0-v0.2.0)
-
-### List Formatting
-
-**For descriptions after list items, use colons:**
-✅
-```
-- **Structured extraction**: Deterministic field extraction from documents
-- **Entity resolution**: Hash-based canonical IDs unify entities
-```
-❌
-```
-- **Structured extraction** — Deterministic field extraction from documents
-- **Entity resolution** — Hash-based canonical IDs unify entities
-```
-
-### Sentence Structure
-
-**Preferred:**
-- Active voice: "The system validates input"
-- Simple subject-verb-object structure
-- Present tense for descriptions
-- Past tense only for historical events or completed actions
-
-**Example:**
-✅ "The system processes files, validates them, and stores records."
-❌ "Files are processed by the system (which validates them) and then stored in records—creating a unified memory graph."
-
-## Context-Specific Guidelines
-
-### Button Labels
-
-**Prefer:**
-- Imperative, verb-led: "Save", "Upload document", "Retry", "Cancel"
-- Action-oriented: "Create source", "Delete entity", "Export data"
-
-**Avoid:**
-- Soft questions: "Would you like to save?"
-- Noun-led actions: "Submit form" (prefer "Submit")
-- Motivational language: "Get started!", "Try it now!"
-
-### Error Messages
-
-**Prefer:**
-- Direct, actionable: "File too large. Maximum size 10 MB."
-- Specific: "Invalid file format. Supported formats: PDF, PNG, JPG."
-- Clear next steps: "Authentication failed. Check your credentials and try again."
-
-**Avoid:**
-- Generic: "Oops! Something went wrong. Please try again!"
-- Motivational: "Don't worry, we'll fix this!"
-- Soft questions: "Would you like to try again?"
-
-### Empty States
-
-**Prefer:**
-- Neutral, factual: "No sources yet.", "No entities found.", "No timeline events."
-- Brief, informative: "Upload your first document to get started."
-
-**Avoid:**
-- Motivational: "Get started! Upload your first file!"
-- Conversational: "Looks like you haven't uploaded anything yet!"
-- Soft questions: "Want to upload a file?"
-
-### Placeholders
-
-**Prefer:**
-- Brief, example-style: "e.g. invoice.pdf", "Enter entity name"
-- Clear, concise: "Search sources...", "Filter by type"
-
-**Avoid:**
-- Long explanations: "Enter your file name here (e.g. my file)"
-- Conversational: "What would you like to search for?"
-- Parentheticals: "File name (optional)"
-
-### Tooltips
-
-**Prefer:**
-- One clear idea; no filler
-- Brief explanations: "Deterministic hash-based ID"
-- Actionable when relevant: "Click to view details"
-
-**Avoid:**
-- Long explanations or promotional text
-- Conversational transitions
-- Multiple ideas in one tooltip
-
-### Success Messages
-
-**Prefer:**
-- Neutral completion: "Upload complete.", "Entity saved.", "Export started."
-- Brief confirmation: "Source processed successfully."
-
-**Avoid:**
-- Motivational: "You're all set! Great job!"
-- Conversational: "Awesome! Your file is ready!"
-- Soft questions: "Want to view it now?"
-
-### Form Labels
-
-**Prefer:**
-- Clear, concise: "Entity type", "Source name", "Date range"
-- Descriptive: "Upload file", "Select format"
-
-**Avoid:**
-- Redundant qualifiers: "Very important field"
-- Conversational: "What type of entity is this?"
-- Long explanations in labels (use tooltips or help text)
-
-### Navigation Labels
-
-**Prefer:**
-- Short, clear: "Sources", "Entities", "Timeline", "Settings"
-- Consistent terminology: Use canonical terms from `docs/vocabulary/canonical_terms.md`
-
-**Avoid:**
-- Marketing language: "Explore", "Discover"
-- Conversational: "Check out your sources"
-- Inconsistent terms: Mixing "records" and "sources"
-
-## Application Checklist
-
-When writing or editing UI copy, verify:
-
-- [ ] No em dashes (—) or en dashes (–)
-- [ ] No conversational transitions ("Now, let's...", "So, you might...")
-- [ ] No soft questions ("Would you like to...?", "Have you considered...?")
-- [ ] No motivational language ("Get started!", "Try it now!")
-- [ ] No excessive parentheticals
-- [ ] No redundant qualifiers ("very", "quite", "rather")
-- [ ] Simple, declarative sentences
-- [ ] Active voice preferred
-- [ ] One idea per sentence
-- [ ] Colons used for list descriptions, not dashes
-- [ ] Paragraphs are short (3-4 sentences, maximum 5)
-- [ ] No immediate repetition of proper nouns in consecutive sentences
-- [ ] Lists used for 3+ related items or concepts
-- [ ] Formatting techniques applied where appropriate (lists, subheadings)
-- [ ] Context-appropriate patterns (button labels imperative, error messages actionable, etc.)
-
-## Integration with Documentation Standards
-
-This style guide complements:
-- **`docs/conventions/writing_style_guide.md`**: Full documentation writing rules (punctuation, sentence structure, list formatting, forbidden patterns)
-- **`docs/conventions/documentation_standards.md`**: Documentation structure, format, required sections, diagrams
-- **`docs/vocabulary/canonical_terms.md`**: Domain vocabulary and terminology
-
-Apply all three when writing UI copy and documentation.
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load this document whenever:
-- Writing or reviewing UI copy (labels, buttons, messages, placeholders, tooltips, errors, empty states)
-- Creating new UI components with text content
-- Editing existing UI components
-- Reviewing UI copy for style consistency
-
-### Required Co-Loaded Documents
-
-- `docs/conventions/writing_style_guide.md` (always)
-- `docs/conventions/documentation_standards.md` (when creating documentation)
-- `docs/vocabulary/canonical_terms.md` (when using domain terminology)
-- `docs/ui/design_system.md` (for design system context)
-
-### Constraints Agents Must Enforce
-
-1. No em dashes or en dashes anywhere in UI copy
-2. Use commas, periods, or colons instead of dashes
-3. No conversational transitions or soft questions
-4. No motivational language
-5. Simple, declarative sentences with active voice
-6. One idea per sentence
-7. Keep paragraphs short (3-4 sentences, maximum 5)
-8. Avoid immediate repetition of proper nouns in consecutive sentences within the same paragraph
-9. Use proper nouns when needed for clarity, emphasis, or at paragraph starts
-10. Use formatting techniques (lists, subheadings) for complex topics
-11. Convert series of related points into lists when appropriate
-12. Apply context-specific guidelines (button labels imperative, error messages actionable, etc.)
-
-### Forbidden Patterns
-
-- Em dashes (—)
-- En dashes (–)
-- Conversational transitions
-- Soft questions
-- Motivational language
-- Excessive parentheticals
-- Redundant qualifiers
-- Complex nested sentence structures
-- Long paragraphs (over 5 sentences)
-- Immediate repetition of proper nouns in consecutive sentences within the same paragraph
-- Overusing proper nouns when pronouns or descriptive terms would work better
-- Long series of related points in paragraph form (use lists instead)
-
-### Validation Checklist
-
-- [ ] No em dashes found (search for "—")
-- [ ] No en dashes found (search for "–")
-- [ ] No conversational transitions
-- [ ] No soft questions
-- [ ] No motivational language
-- [ ] Simple, declarative sentences
-- [ ] Active voice used
-- [ ] Colons used for list descriptions
-- [ ] Paragraphs are short (3-4 sentences, maximum 5)
-- [ ] No immediate repetition of proper nouns in consecutive sentences within the same paragraph
-- [ ] Proper nouns used appropriately (for clarity, emphasis, or at paragraph starts)
-- [ ] Pronouns and descriptive terms used to vary sentence structure
-- [ ] Lists used for 3+ related items or concepts
-- [ ] Formatting techniques applied where appropriate
-- [ ] Context-specific guidelines applied (button labels, error messages, empty states, etc.)
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`../../conventions/writing_style_guide.md`](../../conventions/writing_style_guide.md) - Full writing style guide
-- [`../../conventions/documentation_standards.md`](../../conventions/documentation_standards.md) - Documentation standards
-- [`../../vocabulary/canonical_terms.md`](../../vocabulary/canonical_terms.md) - Domain vocabulary

package/docs/ui/design_system/typography.md

@@ -1,88 +0,0 @@
-# Typography
-
-## Font Families
-
-**Primary (UI):**
-
-```yaml
-sans_serif: "Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
-```
-
-- **Rationale:** Inter is widely used in professional tools (Linear, Notion, GitHub); excellent readability; neutral aesthetic
-
-**Monospace (Data/Code):**
-
-```yaml
-monospace: "'JetBrains Mono', 'Fira Code', 'Roboto Mono', 'Courier New', monospace"
-```
-
-- **Rationale:** JetBrains Mono preferred by developers; Fira Code for ligatures; fallbacks for system fonts
-
-## Type Scale
-
-**Headings:**
-
-```yaml
-h1:
-  font_size: "2rem" # 32px
-  font_weight: "700"
-  line_height: "1.2"
-  letter_spacing: "-0.02em"
-h2:
-  font_size: "1.5rem" # 24px
-  font_weight: "600"
-  line_height: "1.3"
-  letter_spacing: "-0.01em"
-h3:
-  font_size: "1.25rem" # 20px
-  font_weight: "600"
-  line_height: "1.4"
-h4:
-  font_size: "1rem" # 16px
-  font_weight: "600"
-  line_height: "1.5"
-```
-
-**Body:**
-
-```yaml
-body:
-  font_size: "0.9375rem" # 15px (slightly smaller for density)
-  font_weight: "400"
-  line_height: "1.6"
-body_large:
-  font_size: "1rem" # 16px
-  font_weight: "400"
-  line_height: "1.6"
-small:
-  font_size: "0.8125rem" # 13px
-  font_weight: "400"
-  line_height: "1.5"
-```
-
-**Monospace (Data Display):**
-
-```yaml
-mono:
-  font_size: "0.875rem" # 14px
-  font_weight: "400"
-  line_height: "1.5"
-  letter_spacing: "0"
-```
-
-## Typography Usage
-
-- **Headings:** Use sparingly; only for major sections
-- **Body:** Default for all UI text; comfortable reading size
-- **Small:** Metadata, timestamps, labels, secondary information
-- **Monospace:** Source IDs, entity IDs, observation IDs, timestamps, code snippets, extracted field values
-
-## UI Copy Style
-
-UI copy (labels, buttons, messages, placeholders, tooltips, errors) MUST follow consistent, professional text style. See [Style Guide](./style_guide.md) for complete UI copy rules.
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`./style_guide.md`](./style_guide.md) - UI copy style guide
-- [`../../conventions/writing_style_guide.md`](../../conventions/writing_style_guide.md) - Full documentation writing style guide

package/docs/ui/design_system/visual_hierarchy.md

@@ -1,64 +0,0 @@
-# Visual Hierarchy
-
-## Information Density
-
-**Principle:** High information density without clutter.
-
-**Techniques:**
-
-- Clear visual grouping (borders, spacing)
-- Consistent alignment (left-align text, right-align numbers)
-- Typography hierarchy (size, weight, color)
-- Subtle backgrounds for sections
-- Minimal decoration
-
-## Content Structure
-
-**Source List (SourceTable component):**
-
-- Table layout (high density)
-- Sortable columns
-- Row hover states
-- Clear column headers
-- Displays sources with file name, MIME type, created date
-
-**Entity List (EntityList component):**
-
-- Table layout (high density)
-- Entity type badges
-- Canonical name display
-- Observation count
-
-**Source Detail (SourceDetail component):**
-
-- Card-based sections
-- Clear section headers (h3)
-- Metadata in monospace
-- Tabs for: Source info, Interpretations, Observations, Entities
-
-**Entity Detail (EntityDetail component):**
-
-- Card-based sections
-- Clear section headers (h3)
-- Tabs for: Entity Snapshot, Schema, Sources, Interpretations, Timeline, Observations, Relationships
-- Snapshot fields with provenance tracking
-
-**Observation List (ObservationList component):**
-
-- Table layout showing observations
-- Entity type display
-- Source and interpretation references
-- Observation fields display
-
-**Timeline:**
-
-- Chronological list
-- Date markers (subtle)
-- Event type badges
-- Source links (navigates to SourceDetail)
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`component_styles.md`](./component_styles.md) - Component styling details
-- [`data_visualization.md`](./data_visualization.md) - Timeline and graph visualization