## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

## title: Vapora Tracking System - Quick Start Guide date: 2025-11-10 status: READY type: tracking-quickstart

# 🚀 Vapora Tracking System - Quick Start Guide

⏱️ Time to get running: 5-10 minutes

This guide walks you through installing and getting started with the Vapora tracking system component in the simplest way possible.

Note: This guide is for the tracking system only. For complete Vapora project setup, see `QUICKSTART.md`.

## 📋 Prerequisites

You need:

- ✅ Rust 1.70+ (install from https://rustup.rs)
- ✅ Cargo (comes with Rust)
- ✅ Git
- ✅ 500MB free disk space
- ✅ Bash or Zsh shell

Check if you have everything:

    rustc --version    # Should show Rust 1.70+
    cargo --version    # Should show Cargo 1.70+
    which git          # Should show /usr/bin/git or similar

## 🎯 5-Minute Quick Start

### Step 1: Build the Tracking System

    # Build the tracking crate
    cargo build -p vapora-tracking

    # Or with backend integration
    cargo build -p vapora-backend

Expected output:

        Finished `dev` profile [unoptimized + debuginfo] target(s) in X.XXs

### Step 3: Run Tests

    # Verify everything works
    cargo test -p vapora-tracking --lib

    # Should show: test result: ok. 20 passed

### Step 4: Start Using It

Option A: Using Slash Commands (Easiest)

    # In Claude Code, use the commands:
    /log-change "Fixed bug in parser" --impact backend --files 3
    /add-todo "Refactor database" --priority H --estimate M
    /track-status --project vapora --limit 10

Option B: Using Scripts (Manual Sync)

    # Start the tracking service
    ./scripts/start-tracking-service.nu --verbose

    # In another terminal, sync projects (replace with your development directory)
    ./scripts/sync-tracking.nu --projects-dir ~ --verbose

    # Check status
    /track-status

Option C: Using API (Integration)

    # Query the API
    curl http://localhost:3000/api/v1/tracking/summary
    curl http://localhost:3000/api/v1/tracking/entries?limit=10

## ✅ Verify Installation

After building, verify everything works:

### Test 1: Build Success

    cargo build -p vapora-tracking 2>&1 | tail -3
    # Should show: Finished `dev` profile [unoptimized + debuginfo]

### Test 2: Tests Pass

    cargo test -p vapora-tracking --lib 2>&1 | grep "test result"
    # Should show: test result: ok. 20 passed; 0 failed

### Test 3: Clippy Clean

    cargo clippy -p vapora-tracking --lib 2>&1 | grep "warning:" | wc -l
    # Should show: 1 (profile warning only, which is expected)

### Test 4: Commands Available

    ls ~/.claude/commands/ | grep -E "log-change|add-todo|track-status"
    # Should show all 3 commands

### Test 5: Skill Available

    ls ~/.claude/skills/tracking.md
    # Should show the file exists

If all 5 tests pass: ✅ Installation Complete!

## 🎬 First Time Usage

### Scenario 1: Log Your First Change

Using Slash Command (Easiest):

    /log-change "Implemented user authentication" \
      --impact backend \
      --files 5

What happens:

1. ✅ Change is logged to database
2. ✅ Timestamp added automatically
3. ✅ Can be queried with `/track-status`

### Scenario 2: Create Your First TODO

Using Slash Command:

    /add-todo "Review code changes" \
      --priority H \
      --estimate M \
      --due 2025-11-15

What happens:

1. ✅ TODO created in database
2. ✅ Can be tracked with `/track-status`
3. ✅ Shows up in exports

### Scenario 3: Check Your Status

Using Slash Command:

    /track-status --limit 5

Output:

    ✅ Summary
    Total entries: 3
    Changes: 1
    TODOs: 2

    🔄 Changes
    [2025-11-10T14:30:00Z] - Implemented user authentication
    Impact: backend | Breaking: no | Files: 5

    📋 TODOs
    [HIGH] Review code changes (Medium) - Due: 2025-11-15
    [HIGH] Write documentation (Small) - Due: 2025-11-12

## 📚 Next Steps After Installation

### Short Term (Today)

1. ✅ Log 2-3 changes you've made
2. ✅ Create 2-3 TODOs for upcoming work
3. ✅ Run `/track-status` to see results

### Medium Term (This Week)

1. 📝 Set up daily tracking in your workflow
2. 🔄 Sync multiple projects with `sync-tracking.nu`
3. 📊 Export your tracking data with `export-tracking.nu`

### Long Term (Ongoing)

1. 📈 Monitor project progress via `/track-status`
2. 🎯 Use for sprint planning and retrospectives
3. 📉 Generate reports from exported data
4. 🔗 Integrate with other Vapora services

## 🆘 Need More Help?

Question | Answer Location
--- | ---
How do I use the tracking system? | `TRACKING_SYSTEM_STATUS.md` (How to use section)
What are all the features? | `crates/vapora-tracking/README.md` (Features section)
How do I deploy it? | `crates/vapora-tracking/INTEGRATION.md` (Deployment section)
How do I fix an issue? | `SETUP_TRACKING.md` (Troubleshooting section)
What's the architecture? | `TRACKING_DOCUMENTATION_INDEX.md`

## ⚡ Super Quick Reference

    # Build
    cargo build -p vapora-tracking

    # Test
    cargo test -p vapora-tracking --lib

    # Use commands
    /log-change "Summary" --impact backend
    /add-todo "Task" --priority H --estimate M
    /track-status --limit 10

    # Use scripts
    ./scripts/sync-tracking.nu --verbose
    ./scripts/export-tracking.nu json --output report
    ./scripts/start-tracking-service.nu

    # Query API
    curl http://localhost:3000/api/v1/tracking/summary

## ✅ Installation Checklist

- Rust 1.75+ installed
- Vapora repo available
- `cargo build -p vapora-tracking` succeeds
- `cargo test -p vapora-tracking --lib` shows 20 passed
- Slash commands copied to `~/.claude/commands/`
- Skill copied to `~/.claude/skills/`
- `/log-change` command works
- `/track-status` shows results

All checked? ✅ You're ready to go!

For complete Vapora project setup: See `QUICKSTART.md`

For tracking system deep dive: See `SETUP_TRACKING.md`