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

# 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