neotoma 0.3.0 → 0.3.2

package/docs/conventions/readme_generation_framework.md

@@ -1,230 +0,0 @@
-# README Generation Framework
-**Reference:** `README.md` — Project overview and entry point
-## README Purpose and Audience
-**Primary Audiences:**
-1. **New developers** — Quick onboarding, setup, understanding what Neotoma is
-2. **Potential users** — Understanding value proposition, capabilities, differentiation
-3. **Contributors** — Development workflow, testing, architecture overview
-4. **AI agents** — Quick reference for project scope and capabilities
-**README Should:**
-- Provide clear value proposition in first 100 words
-- Enable quick setup and first run
-- Link to comprehensive documentation
-- Reflect current project status accurately
-- Lead with confident, positive positioning (not defensive)
-**README Should NOT:**
-- Duplicate detailed technical documentation
-- Include implementation specifics
-- Be defensive or competitive-focused (comparisons are contextual, not primary)
-- Exceed ~350 lines (maintain scannability)
-## README Structure
-### Required Sections (In Order)
-1. **Title and Tagline** (1-2 lines)
-   - Project name: "Neotoma — Truth Layer for AI Memory"
-   - One-sentence description: deterministic truth layer that transforms fragmented personal data
-2. **What It Does** (3-5 paragraphs)
-   - Core value proposition
-   - How it works (high-level workflow)
-   - Key outcome: unified memory graph
-3. **Neotoma's Structured Personal Data Memory** (Architectural Foundations)
-   - Three architectural foundations (Privacy-First, Deterministic, Cross-Platform)
-   - What these foundations enable (capabilities)
-   - Confident, positive framing
-4. **Problems Solved** (Table format)
-   - Problem → Solution mapping
-   - Focus on user value, not competitive positioning
-5. **Who Neotoma Is For** (Target Users)
-   - ICP profiles (AI-Native Operators, Knowledge Workers, Small Teams)
-   - Why they choose Neotoma (benefits-focused)
-6. **Comparison with Provider Memory** (Contextual, Not Defensive)
-   - What Neotoma provides (positive framing)
-   - Provider memory context (brief, factual)
-   - Lead with capabilities, not limitations
-7. **Core Workflow** (9-step process)
-   - Ingestion → Extraction → Schema → Entity Resolution → Observations → Reducers → Events → Graph → AI Access
-8. **Architecture** (High-level overview)
-   - Five-layer architecture
-   - Truth Layer positioning
-   - Link to detailed architecture docs
-9. **Releases** (All releases)
-   - Current releases with status and links
-   - Organized by release version
-   - Include status, name, and brief description
-10. **Quick Links** (Documentation navigation)
-    - Getting Started
-    - Documentation categories
-    - Development resources
-11. **Interactive Prototype** (Demo instructions)
-    - Command to run prototype
-    - Link to prototype docs
-12. **Development** (Setup and workflow)
-    - Prerequisites
-    - Setup commands
-    - Development servers
-    - Testing commands
-13. **Documentation Structure** (Complete map)
-- Core Documentation (Foundation, Specs, Architecture, Subsystems, Feature Units, Releases)
-- Developer Resources (Developer, Testing, Integrations, Infrastructure, Operations, Observability, API, Reference)
-- Design & UI (UI, Prototypes)
-- Additional Resources (Context, Conventions, Legal, Migration, Templates, Vocabulary)
-- Primary entry point: Foundation rules in `.cursor/rules/`
-14. **Core Principles** (12 principles)
-- Deterministic, Schema-first, Explainable, Entity-unified, Timeline-aware, Cross-platform, Privacy-first, Immutable, Provenance, Dual-path ingestion, Four-layer model, Event-sourced
-15. **Testing** (Testing approach)
-- Test types and coverage
-16. **License** (MIT)
-## Content Guidelines
-### Tone and Style
-- **Confident and positive** — Lead with what Neotoma provides, not what competitors lack
-- **Clear and direct** — Avoid jargon, use plain language where possible
-- **Scannable** — Use headers, bullets, tables for quick navigation
-- **Accurate** — Must match current documentation exactly
-### Competitive Comparisons
-- **Include but don't lead with** — Comparisons provide context, not primary positioning
-- **Positive framing** — "Neotoma provides X" not "Providers don't provide X"
-- **Factual and brief** — State capabilities, avoid defensive explanations
-### Architectural Foundations
-- **Lead with capabilities** — What these foundations enable
-- **Avoid defensive language** — Don't explain why competitors can't pursue (that's internal strategy)
-- **Confident positioning** — These are architectural choices, not defensive measures
-### Feature Lists
-- **MVP clearly separated** — What's available now vs. planned
-- **User-focused** — Describe what users can do, not technical implementation
-- **Accurate** — Must match current specs exactly
-### Links and References
-- **All links must work** — Verify relative paths
-- **Link to comprehensive docs** — README is overview, not replacement
-- **Organize by audience** — Getting Started vs. Deep Dives
-## Information Sources
-### Primary Sources (In Priority Order)
-1. **`docs/foundation/core_identity.md`**
-   - What Neotoma is/is not
-   - Core responsibilities
-   - Architectural choices
-2. **`docs/foundation/product_positioning.md`**
-   - Positioning and differentiation
-   - Defensible differentiators
-   - Feature capabilities
-3. **`docs/foundation/problem_statement.md`**
-   - Problems solved
-   - User pain points
-4. **`docs/specs/MVP_OVERVIEW.md`**
-   - MVP capabilities
-   - Feature lists
-   - Architecture overview
-5. **`docs/architecture/architecture.md`**
-   - System architecture
-   - Layer descriptions
-6. **`docs/specs/ICP_PROFILES.md`**
-   - Target user profiles
-   - Use cases
-7. **`docs/releases/in_progress/`**
-   - Current release status
-   - Active versions
-   - Release names, status, and descriptions
-8. **`package.json`**
-   - Scripts and commands
-   - Dependencies context
-9. **Foundation rules in `.cursor/rules/`**
-   - Documentation structure
-   - Organization
-### Secondary Sources
-- `docs/foundation/philosophy.md` — Core principles (extracted for README)
-- `docs/specs/MCP_SPEC.md` — MCP integration details
-- `docs/testing/testing_standard.md` — Testing approach
-**Note:** Integration providers are not listed in README; users are directed to `docs/integrations/` via Quick Links.
-## Generation Process
-### Step 1: Gather Information
-1. Read primary source documents
-2. Extract key information:
-   - Value proposition
-   - Architectural foundations
-   - Problems solved
-   - Target users
-   - MVP features
-   - Architecture overview
-   - Development setup
-   - Documentation structure
-### Step 2: Structure Content
-1. Follow required section order
-2. Apply content guidelines (tone, style)
-3. Ensure positive, confident framing
-4. Verify accuracy against source docs
-### Step 3: Generate README
-1. Write each section following structure
-2. Include all required sections
-3. Maintain ~350 line target
-4. Verify all links work
-5. Check consistency with docs
-### Step 4: Validate
-1. **Accuracy check:**
-   - Features match MVP_OVERVIEW.md
-   - Architecture matches architecture.md
-   - Principles match philosophy.md
-   - Status matches releases/
-2. **Link validation:**
-   - All relative paths resolve
-   - Documentation links correct
-   - No broken references
-3. **Tone check:**
-   - Confident, not defensive
-   - Positive framing throughout
-   - Clear value proposition
-4. **Completeness:**
-   - All required sections present
-   - Key information included
-   - Nothing critical missing
-## Update Triggers
-**CRITICAL:** README must be **regenerated** (not patched) whenever documentation changes in materially affecting ways.
-### Material Changes (Require Full Regeneration)
-README must be regenerated when:
-1. **Core identity changes** — `docs/foundation/core_identity.md` modified
-2. **Product positioning changes** — `docs/foundation/product_positioning.md` modified
-3. **MVP scope changes** — `docs/specs/MVP_OVERVIEW.md` modified
-4. **Architecture changes** — `docs/architecture/architecture.md` modified
-5. **New features added** — Feature specs updated
-6. **Release status changes** — New releases or status updates
-7. **Documentation structure changes** — New doc categories added
-8. **Development workflow changes** — Setup or scripts modified
-9. **Integration changes** — New providers added
-10. **Philosophy/principles changes** — `docs/foundation/philosophy.md` modified
-11. **Problem statement changes** — `docs/foundation/problem_statement.md` modified
-12. **Target user changes** — `docs/specs/ICP_PROFILES.md` modified
-13. **User explicitly requests** — "regenerate README" or similar
-### What Constitutes "Materially Affecting"
-A documentation change is "materially affecting" if it:
-- Changes what Neotoma is or does (core identity)
-- Changes how Neotoma is positioned or differentiated
-- Adds or removes MVP features
-- Changes architectural description or layer structure
-- Modifies target users or use cases
-- Updates core principles or philosophy
-- Changes problems solved or value proposition
-- Adds or removes integrations
-- Updates release status or roadmap
-- Reorganizes documentation structure significantly
-**When in doubt, regenerate.** It's safer to regenerate than to patch and miss inconsistencies.
-## Maintenance Rules
-1. **Always regenerate for material changes** — When any trigger occurs, regenerate entire README from framework using primary sources
-2. **Never patch incrementally** — Don't update individual sections; regenerate whole README to ensure consistency
-3. **Verify against sources** — Check each section against primary sources after regeneration
-4. **Maintain structure** — Keep required section order exactly as defined
-5. **Preserve links** — Ensure all documentation links remain functional
-6. **Update status** — Keep current release status accurate
-7. **Check tone** — Ensure confident, positive positioning throughout
-8. **Same tool call batch** — Regenerate README in same tool call batch as documentation changes
-## Example: Section Generation
-### "What It Does" Section
-**Source:** `docs/foundation/core_identity.md`, `docs/foundation/product_positioning.md`
-**Guidelines:**
-- 3-5 paragraphs
-- Lead with value proposition
-- Explain dual-path ingestion
-- Describe memory graph outcome
-- Link to MCP access
-**Generated Content:**
-```
-Neotoma builds persistent structured memory for AI agents through **dual-path ingestion**: upload documents (PDFs, images, receipts, contracts) that get automatically structured, or provide contextual information during agent conversations that gets remembered for future sessions. As you interact with ChatGPT, Claude, or Cursor, agents can both read your accumulated memory and write new structured data, creating an incremental knowledge base that grows more accurate and comprehensive over time.
-The system transforms fragmented personal data into a unified memory graph—connecting people, companies, events, and relationships across all your data. Every fact traces back to its source, dates automatically create timelines, and entities are unified across all records so "Acme Corp" in one invoice matches "Acme Corp" in agent-created data, regardless of when you created them.
-All memory is exposed to AI tools via Model Context Protocol (MCP), ensuring agents have structured, validated access to your truth layer. This enables agents to maintain context across sessions, answer questions about your personal data, and build on previous interactions—turning fragmented personal data into a persistent, queryable memory that scales with your agent usage.
-```

package/docs/conventions/time_tracking_template.md

@@ -1,60 +0,0 @@
-# Time Tracking Template
-## Purpose
-This template provides the standard format for recording time tracking data in release `status.md` files. Time tracking enables:
-- Comparison of actual vs estimated development time
-- Calibration of future estimates
-- Velocity baseline updates
-- Identification of estimation patterns
-## Template Section (Add to `status.md` Section 1.1)
-```markdown
-### 1.1 Time Tracking
-- **Development Start Date**: _[YYYY-MM-DD] (Recorded when status changes to `in_progress`)_
-- **Development Finish Date**: _[YYYY-MM-DD] (Recorded when status changes to `ready_for_deployment`)_
-- **Deployment Date**: _[YYYY-MM-DD] (Recorded when status changes to `deployed`)_
-- **Completion Date**: _[YYYY-MM-DD] (Recorded when status changes to `completed`)_
-- **Estimated Development Time**: _[X days] (From `execution_schedule.md`)_
-- **Actual Development Time**: _[X days] (Calculated: Development Finish Date - Development Start Date)_
-- **Estimation Accuracy**: _[X%] (Calculated: (Actual / Estimated) × 100%)_
-```
-## Recording Instructions
-### When Status Changes to `in_progress`
-1. Record **Development Start Date** = current date/time
-2. Format: `YYYY-MM-DD` (e.g., `2025-12-11`)
-### When Status Changes to `ready_for_deployment`
-1. Record **Development Finish Date** = current date/time
-2. Calculate **Actual Development Time** = Development Finish Date - Development Start Date
-3. Calculate **Estimation Accuracy** = (Actual Development Time / Estimated Development Time) × 100%
-4. If accuracy < 80% or > 120%, note in Decision Log for methodology review
-### When Status Changes to `deployed`
-1. Record **Deployment Date** = current date/time
-### When Status Changes to `completed`
-1. Record **Completion Date** = current date/time
-2. Generate time tracking summary comparing actual vs estimated times
-## Example: v0.1.0 Time Tracking
-```markdown
-### 1.1 Time Tracking
-- **Development Start Date**: 2025-12-09 _(Estimated based on remediation date)_
-- **Development Finish Date**: 2025-12-11
-- **Deployment Date**: _[To be recorded when deployed]_
-- **Completion Date**: _[To be recorded when status changes to `completed`]_
-- **Estimated Development Time**: _[Not recorded in original plan]_
-- **Actual Development Time**: ~2-3 days (Dec 9-11, 2025)
-- **Estimation Accuracy**: _[Baseline established for future estimates]_
-```
-## Using Time Tracking Data
-### For Estimation Calibration
-1. **After each release completion:**
-   - Compare Actual vs Estimated times
-   - If accuracy < 80% or > 120%, review estimation methodology
-   - Update velocity baseline if significantly different
-2. **For future releases:**
-   - Reference previous release actual times
-   - Adjust estimates based on historical accuracy
-   - Account for scope differences
-### For Velocity Baseline Updates
-1. **Calculate new velocity:**
-   - Total FUs completed / Actual Development Time
-   - Compare to previous baseline (v0.1.0: ~8-13 FUs/day)
-2. **Update methodology:**
-   - If velocity significantly different, update `estimation_methodology.md`
-   - Adjust complexity classifications if needed

package/docs/conventions/writing_style_guide.md

@@ -1,252 +0,0 @@
-# Neotoma Documentation Writing Style Guide
-This guide defines writing style rules for all Neotoma documentation. Always apply these rules when creating or editing documentation.
-## Purpose
-This guide ensures consistent, professional technical writing that avoids AI-generated patterns and maintains clarity and precision across all Neotoma 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."
-❌ "Neotoma provides persistent structured memory—ensuring agents can access truth layer data—with full provenance tracking."
-✅ "Neotoma provides persistent structured memory with full provenance tracking. Agents can access truth layer data via MCP."
-### 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
-**Example:**
-❌ "Neotoma provides cross-platform memory that works with ChatGPT, Claude, Cursor, and other AI tools. Agents can access and update structured personal data regardless of platform. This dual-path ingestion supports both file uploads and agent interactions. Memory grows incrementally as agent usage scales. The system creates a persistent knowledge graph that survives individual conversations and tool sessions. Unlike provider memory, which is ephemeral and platform-locked, Neotoma's memory persists across all AI interactions. This makes it the foundation for agent-native personal computing."
-✅ "Neotoma provides cross-platform memory that works with ChatGPT, Claude, Cursor, and other AI tools. Agents can access and update structured personal data regardless of platform. This dual-path ingestion supports both file uploads and agent interactions. Memory grows incrementally as agent usage scales. The system creates a persistent knowledge graph that survives individual conversations and tool sessions. Unlike provider memory, which is ephemeral and platform-locked, the system's memory persists across all AI interactions. This makes it the foundation for agent-native personal computing."
-**Better example with formatting:**
-✅ "Neotoma provides cross-platform memory that works with ChatGPT, Claude, Cursor, and other AI tools. The system enables the agentic web through several key capabilities:
-- **Cross-platform access**: Agents can access and update structured personal data regardless of platform
-- **Dual-path ingestion**: Supports both file uploads and agent interactions
-- **Incremental growth**: Memory scales as agent usage increases
-- **Persistent knowledge graph**: Survives individual conversations and tool sessions
-Unlike provider memory, which is ephemeral and platform-locked, the system's memory persists across all AI interactions. This makes it the foundation for agent-native personal computing."
-### 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
-**Examples:**
-❌ "Neotoma provides cross-platform memory. Neotoma works with ChatGPT, Claude, and Cursor. Neotoma enables agents to access structured data."
-✅ "Neotoma provides cross-platform memory. It works with ChatGPT, Claude, and Cursor. The system enables agents to access structured data."
-❌ "MCP integration enables cross-platform access. MCP provides a standard protocol. MCP works with multiple AI tools."
-✅ "MCP integration enables cross-platform access. The protocol provides a standard interface. It works with multiple AI tools."
-**Better example showing balanced usage:**
-✅ "Neotoma provides cross-platform memory that works with ChatGPT, Claude, and Cursor. The system enables agents to access structured data regardless of platform. Memory grows incrementally as agent usage scales. Neotoma creates a persistent knowledge graph that survives individual conversations. Unlike provider memory, which is ephemeral and platform-locked, the system's memory persists across all AI interactions."
-**Why this works:**
-- Uses "Neotoma" at paragraph start and when introducing a new concept
-- Uses "the system" and pronouns within the paragraph to vary structure
-- Avoids immediate consecutive repetition while maintaining clarity
-## 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
-**Example:**
-❌ "The system provides entity resolution, timeline generation, structured extraction, and cross-platform access. These features enable agents to reason across personal data."
-✅ "The system provides several key capabilities:
-- **Entity resolution**: Deterministic hash-based canonical IDs
-- **Timeline generation**: Automatic chronological ordering
-- **Structured extraction**: Schema-first field extraction
-- **Cross-platform access**: Works with all AI tools via MCP
-These features enable agents to reason across personal data."
-### 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."
-## Application Checklist
-When writing or editing documentation, 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)
-## Integration with Documentation Standards
-This style guide complements `docs/conventions/documentation_standards.md`. Apply both:
-- **Documentation Standards**: Structure, format, required sections, diagrams
-- **Writing Style Guide**: Language patterns, punctuation, tone
-Always load both documents when creating or editing documentation.
-## Agent Instructions
-### When to Load This Document
-Load this document whenever:
-- Creating new documentation
-- Editing existing documentation
-- Reviewing documentation for style consistency
-### Required Co-Loaded Documents
-- `docs/conventions/documentation_standards.md` (always)
-- `docs/NEOTOMA_MANIFEST.md` (when creating new docs)
-### Constraints Agents Must Enforce
-1. No em dashes or en dashes anywhere in documentation
-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
-### 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