Major Enhancement: Production-Ready TypeScript Refactor with Testing, CI/CD, and New Features

.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v2
+      with:
+        bun-version: latest
+
+    - name: Install dependencies
+      run: bun install
+
+    - name: Run tests
+      run: bun test
+
+    - name: Run tests with coverage
+      run: bun test --coverage
+      continue-on-error: true

.gitignore

@@ -4,6 +4,16 @@ node_modules/
 archive/
 texts/
 .cursor/
+research/
 *.md
-!README.md
+!docs/dev/README.md
 !CLAUDE.md
+!BUILD.md
+!*PLAN*.md
+!*STRATEGY*.md
+!*SUMMARY*.md
+!docs/dev/ARCHITECTURE.md
+!SQL_SAFETY.md
+!docs/**/*.md
+.beads/
+builds/

BUILD.md

@@ -0,0 +1,121 @@
+# QMD Build Process
+
+## TL;DR: Compilation Doesn't Work
+
+❌ **`bun build --compile` does NOT work for QMD**
+✅ **Use the existing shell wrapper approach**
+
+## What We Tested
+
+### Test 1: Compiled Binary (`bun run build`)
+```bash
+bun build bin/run --compile --outfile builds/qmd
+```
+
+**Result:**
+- ✅ Binary created (101MB)
+- ✅ Runs without errors (exit code 0)
+- ❌ **Produces NO output**
+- ❌ All commands fail silently
+
+**Issue:** Bun's `--compile` flag doesn't properly handle oclif's dynamic imports and output streams.
+
+### Test 2: Bundled Version (`bun run build:bundle`)
+```bash
+bun build bin/run --target bun --outdir builds
+```
+
+**Result:**
+- ❌ Doesn't properly bundle the code
+- Creates only a stub file with asset reference
+- oclif's dynamic command loading isn't compatible with Bun's bundler
+
+## Why Compilation Fails
+
+1. **oclif uses dynamic imports** for command discovery
+2. **stdout/stderr handling** in compiled Bun binaries has issues
+3. **Bun's bundler** can't properly handle oclif's architecture
+4. **Not specifically a sqlite-vec issue** - the entire binary doesn't work
+
+## Working Solution: Current Setup
+
+The existing setup works perfectly:
+
+```
+./qmd (shell wrapper)
+  ↓
+bin/run (Bun script)
+  ↓
+@oclif/core
+  ↓
+src/commands/*
+```
+
+**Benefits:**
+- ✅ All features work (including sqlite-vec)
+- ✅ Fast startup time
+- ✅ Easy debugging
+- ✅ Simple updates
+
+## Distribution Options
+
+### Option 1: Require Bun on Target Machine (Recommended)
+```bash
+# On target machine:
+curl -fsSL https://bun.sh/install | bash
+git clone <repo>
+cd qmd
+bun install
+bun link  # or use ./qmd directly
+```
+
+**Pros:**
+- Everything works
+- Bun installs in seconds
+- sqlite-vec works perfectly
+
+### Option 2: Docker Container
+```dockerfile
+FROM oven/bun:1
+WORKDIR /app
+COPY . .
+RUN bun install
+ENTRYPOINT ["./qmd"]
+```
+
+**Pros:**
+- Portable across machines
+- No Bun installation needed on host
+- Consistent environment
+
+### Option 3: Package Manager Installation
+Publish to npm/bun registry with Bun as peer dependency.
+
+## Build Scripts
+
+Available in `package.json`:
+
+```bash
+bun run build         # Compile binary (doesn't work)
+bun run build:bundle  # Bundle code (doesn't work)
+```
+
+These are included for testing/experimentation, but **not recommended for production use**.
+
+## Conclusion
+
+**For now, stick with the shell wrapper approach.** It's simple, works perfectly, and requires minimal dependencies (just Bun).
+
+If Bun improves `--compile` support for oclif in the future, we can revisit this.
+
+## Testing Results
+
+- **Compiled binary**: Exits with code 0 but produces no output
+- **Regular wrapper**: Full output with formatting ✓
+- **sqlite-vec**: Works in regular setup, untestable in compiled binary (no output at all)
+
+---
+
+**Last Updated:** 2025-12-11
+**Bun Version:** 1.3.0
+**oclif Version:** 4.8.0

CLAUDE.md

@@ -5,9 +5,12 @@ Use Bun instead of Node.js (`bun` not `node`, `bun install` not `npm install`).
 ## Commands
 
 ```sh
+qmd init               # Initialize .qmd/ directory for project-local index
+qmd doctor             # Check system health and diagnose issues
 qmd add .              # Index markdown files in current directory
+qmd update             # Re-index all collections
+qmd update <id>        # Re-index specific collection by ID
 qmd status             # Show index status and collections
-qmd update-all         # Re-index all collections
 qmd embed              # Generate vector embeddings (requires Ollama)
 qmd search <query>     # BM25 full-text search
 qmd vsearch <query>    # Vector similarity search
@@ -25,17 +28,57 @@ bun link               # Install globally as 'qmd'
 
 - SQLite FTS5 for full-text search (BM25)
 - sqlite-vec for vector similarity search
-- Ollama for embeddings (embeddinggemma) and reranking (qwen3-reranker)
+- Ollama for embeddings (nomic-embed-text) and reranking (qwen3-reranker)
 - Reciprocal Rank Fusion (RRF) for combining results
+- Project-local indexes via `.qmd/` directory (like `.git/`)
+
+## Index Location Priority
+
+QMD searches for indexes in this order:
+1. **`.qmd/` directory** - Walks up from current directory (project-local)
+2. **`QMD_CACHE_DIR`** - Environment variable for custom location
+3. **`~/.cache/qmd/`** - Global default (respects `XDG_CACHE_HOME`)
+
+Example workflows:
+```sh
+# Project-local index (recommended)
+qmd init                    # Creates .qmd/ directory
+qmd add .                   # Uses .qmd/default.sqlite
+
+# Custom location via environment variable
+export QMD_CACHE_DIR=/custom/path
+qmd add .                   # Uses /custom/path/default.sqlite
+
+# Global index (no .qmd/ in tree)
+qmd add ~/Documents/notes   # Uses ~/.cache/qmd/default.sqlite
+```
 
 ## Important: Do NOT run automatically
 
-- Never run `qmd add`, `qmd add-context`, `qmd embed`, or `qmd update-all` automatically
+- Never run `qmd add`, `qmd init`, or `qmd embed` automatically
 - Never modify the SQLite database directly
 - Write out example commands for the user to run manually
-- Index is stored at `~/.cache/qmd/index.sqlite`
+- Index location: `.qmd/` (project-local) or `~/.cache/qmd/` (global default)
+
+## Build & Distribution
+
+### ⚠️ Compilation Does NOT Work
+- **Never use `bun build --compile`** - produces a binary that runs but outputs nothing
+- Not specifically a sqlite-vec issue - oclif's dynamic imports aren't compatible with Bun's compiler
+- See `BUILD.md` for detailed testing results
+
+### ✅ Working Distribution Methods
+1. **Install Bun on target machine** (recommended)
+   ```sh
+   curl -fsSL https://bun.sh/install | bash
+   git clone <repo> && cd qmd && bun install
+   ```
+2. **Docker container** - packages everything including Bun runtime
+3. **Package manager** - publish with Bun as peer dependency
 
-## Do NOT compile
+### Build Scripts (For Testing Only)
+- `bun run build` - Creates compiled binary (doesn't work)
+- `bun run build:bundle` - Attempts bundling (doesn't work)
+- `./builds/` directory is git-ignored
 
-- Never run `bun build --compile` - it overwrites the shell wrapper and breaks sqlite-vec
-- The `qmd` file is a shell script that runs `bun qmd.ts` - do not replace it
+The shell wrapper approach (`./qmd` → `bin/run`) is the correct solution.