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

"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:

# 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

```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:

---
title: "First Document"
status: "draft"
priority: "high"
tags: ["test"]
---

doc2.md:

---
title: "Second Document"
status: "review"
priority: "medium"
tags: ["test", "review"]
---

2. Create Test Query

```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