Initial vibecoded proof of concept

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

@@ -0,0 +1,192 @@
+# Quickstart Guide: Notex Relational Document System
+
+## Installation
+
+1. Install the plugin using your preferred Neovim plugin manager
+2. Ensure SQLite is available on your system
+3. Restart Neovim to load the plugin
+
+## Initial Setup
+
+### 1. Index Your Documents
+```vim
+"Notex will automatically scan for markdown files in your workspace
+"You can also manually trigger indexing:
+:NotexIndex /path/to/your/documents
+```
+
+### 2. Create Your First Query
+Open a markdown file and add a query block:
+
+```markdown
+# My Project Dashboard
+
+```notex-query
+status: "active"
+priority: "high"
+ORDER BY created_at DESC
+```
+```
+
+### 3. View Query Results
+- Hover over the query block with your cursor
+- Press `<leader>q` to open the query in a virtual buffer
+- The results will show all matching documents in a table format
+
+## Basic Usage
+
+### Querying Documents
+
+#### Simple Property Filter
+```markdown
+```notex-query
+status: "draft"
+```
+```
+
+#### Multiple Properties
+```markdown
+```notex-query
+status: "active"
+priority: "high"
+tags: ["urgent", "review"]
+```
+```
+
+#### Advanced Filtering
+```markdown
+```notex-query
+FROM priority: "high"
+WHERE created_at >= "2024-01-01"
+ORDER BY due_date ASC
+LIMIT 10
+```
+```
+
+### Working with Query Results
+
+#### Open Documents
+- Move cursor to any row in the results table
+- Press `<Enter>` to open the document in a new split
+- Press `o` to open in a new tab
+
+#### Edit Properties
+- Press `e` on any result row to enter edit mode
+- Change property values directly in the table
+- Press `<Enter>` to save changes to the source document
+
+#### Save Queries
+- Press `s` to save the current query for reuse
+- Give your query a name like "My Active Tasks"
+- Access saved queries with `:NotexQueries`
+
+## Document Properties
+
+### YAML Header Format
+```yaml
+---
+title: "Project Documentation"
+status: "active"
+priority: "high"
+tags: ["documentation", "project"]
+created_at: "2024-03-15"
+due_date: "2024-04-01"
+assignee: "john@example.com"
+progress: 75
+---
+```
+
+### Supported Property Types
+- **Text**: "draft", "documentation", "john@example.com"
+- **Numbers**: 75, 1.5, -10
+- **Booleans**: true, false
+- **Dates**: "2024-03-15", "2024-03-15T10:30:00Z"
+- **Arrays**: ["tag1", "tag2"], [1, 2, 3]
+
+## Advanced Features
+
+### Query Conditions
+```markdown
+```notex-query
+WHERE priority > 5 AND status != "archived"
+WHERE tags INCLUDES "urgent"
+WHERE created_at BEFORE "2024-01-01"
+WHERE title CONTAINS "important"
+```
+```
+
+### Grouping and Aggregation
+```markdown
+```notex-query
+GROUP BY status
+ORDER BY priority DESC
+```
+```
+
+### Custom Query Shortcuts
+Add to your Neovim config:
+```vim
+lua
+vim.keymap.set('n', '<leader>qt', ':NotexQuery<CR>')
+vim.keymap.set('n', '<leader>qr', ':NotexRefresh<CR>')
+vim.keymap.set('n', '<leader>qs', ':NotexSaveQuery<CR>')
+```
+
+## Testing Your Setup
+
+### 1. Create Test Documents
+Create two markdown files with YAML headers:
+
+`doc1.md`:
+```yaml
+---
+title: "First Document"
+status: "draft"
+priority: "high"
+tags: ["test"]
+---
+```
+
+`doc2.md`:
+```yaml
+---
+title: "Second Document"
+status: "review"
+priority: "medium"
+tags: ["test", "review"]
+---
+```
+
+### 2. Create Test Query
+```markdown
+```notex-query
+tags: "test"
+```
+```
+
+### 3. Verify Results
+The query should return both documents in a table format.
+
+## Troubleshooting
+
+### Query Not Working
+- Check that YAML headers are properly formatted with `---` delimiters
+- Ensure property names in queries match exactly with YAML keys
+- Verify that documents have been indexed (`:NotexStatus`)
+
+### Performance Issues
+- Use more specific filters to reduce result sets
+- Consider adding `LIMIT` to large queries
+- Check `:NotexStatus` for indexing performance metrics
+
+### File Not Found Errors
+- Ensure file paths in your workspace are accessible
+- Check file permissions for read/write access
+- Run `:NotexReindex` to refresh the document database
+
+## Next Steps
+
+- Explore the query syntax documentation for advanced filtering
+- Set up custom query templates for common workflows
+- Integrate with your existing Neovim workflow and plugins
+- Share queries with your team for consistent document management