Initial vibecoded proof of concept

specs/002-notex-is-a/research.md

@@ -0,0 +1,43 @@
+# Research: Relational Document System for Neovim
+
+## SQLite Integration
+**Decision**: Use lsqlite3 for SQLite database operations
+**Rationale**: lsqlite3 is the most mature and widely used SQLite binding for Lua, with excellent Neovim compatibility and minimal dependencies
+**Alternatives considered**:
+- lua-sqlite3 (less mature, fewer updates)
+- Custom file-based indexing (limited query capabilities)
+
+## YAML Parsing
+**Decision**: Use lyaml for YAML header parsing
+**Rationale**: lyaml provides robust YAML parsing with proper error handling for malformed headers, essential for document reliability
+**Alternatives considered**:
+- Custom regex parsing (brittle, fails with complex YAML)
+- yaml.lua (less maintained than lyaml)
+
+## Virtual Buffer Management
+**Decision**: Use Neovim's native nvim_buf_ API
+**Rationale**: Native API provides the most seamless integration with Neovim's buffer system, ensuring compatibility with existing plugins and user workflows
+**Alternatives considered**:
+- Floating windows (less persistent, not ideal for editing)
+- External terminal buffers (breaks Neovim integration)
+
+## Query Syntax Design
+**Decision**: Custom block syntax similar to code blocks
+**Rationale**: Block syntax is familiar to markdown users and provides clear delimiters for query parsing while maintaining readability
+**Alternatives considered**:
+- Inline syntax (cluttered, hard to parse)
+- Special comments (not intuitive for query visualization)
+
+## Performance Optimization
+**Decision**: Hybrid indexing approach (SQLite + in-memory cache)
+**Rationale**: SQLite provides persistent storage and complex query capabilities, while in-memory caching ensures sub-100ms response times for frequently accessed data
+**Alternatives considered**:
+- Pure file-based indexing (slow for large document sets)
+- Pure in-memory (data loss on restart)
+
+## Testing Framework
+**Decision**: busted with nvim-test plugin
+**Rationale**: busted provides comprehensive testing capabilities with good async support, while nvim-test enables Neovim-specific testing scenarios
+**Alternatives considered**:
+- luaunit (limited Neovim integration)
+- Custom testing harness (maintenance overhead)