CAD-Documenter/docs/KB-CAPTURE.md

# KB Capture v2

**Clip-based recording for engineering knowledge capture.**

## Overview

KB Capture is a lightweight recording tool that captures your CAD/FEM work as short clips, not one long video. Record what matters, delete mistakes, keep the good stuff.

## Quick Start

```bash
# Install
cd CAD-Documenter
uv sync
uv pip install customtkinter keyboard

# Launch
uv run kb-capture
```

## Workflow

### 1. Start Session
- Open KB Capture (GUI)
- **Select project** from dropdown (scans your projects folder)
- Enter session description (e.g., "Vertical support refinement")
- Select type: **Design** (CAD) or **Analysis** (FEA)
- Click **Start Session**

> Projects are auto-discovered from your projects folder (D:/ATODrive/Projects on Windows)

### 2. Record Clips
While working in NX/CAD:
- Press **Ctrl+Shift+R** to start recording
- Narrate what you're doing
- Say "screenshot" when you want a frame captured
- Press **Ctrl+Shift+R** again to stop

### 3. Review Clips
After each clip:
- **Keep (K)**: Keep the clip
- **Delete (D)**: Discard the clip (bad take)
- Or just start recording again (auto-keeps previous)

### 4. End Session
- Press **Ctrl+Shift+E** or click **End Session**
- Clips are merged and transcribed
- Exported to `clawdbot_export/` for Mario processing

## Keyboard Shortcuts

| Action | Shortcut |
|--------|----------|
| Start/Stop Recording | Ctrl+Shift+R |
| Keep Last Clip | Ctrl+Shift+K |
| Delete Last Clip | Ctrl+Shift+D |
| End Session | Ctrl+Shift+E |

## Session Types

| Type | Updates | Use For |
|------|---------|---------|
| **Design** | KB/Design/ | CAD work, component design, assembly |
| **Analysis** | KB/Analysis/ | FEA setup, mesh, BCs, results |

## Output

Sessions are stored **inside the project folder**:

```
/2-Projects/<ProjectName>/
├── KB/
│   └── dev/                      # Mario creates gen-XXX.md here
├── Images/
│   └── screenshot-sessions/      # Mario moves frames here
└── _capture/                     # Session staging area
    └── <session-id>/
        ├── clips/
        │   ├── clip-001.mp4
        │   └── ...
        ├── session.json
        └── clawdbot_export/      # Ready for Mario
            ├── merged.mp4
            ├── transcript.json
            ├── frames/
            │   ├── 01_00-30.png
            │   └── ...
            └── metadata.json
```

**Key insight:** Sessions belong to PROJECTS, not to KB Capture. This means:
- All project data stays together
- Mario knows which KB to update
- Easy to archive/delete projects

## What Happens Next

1. **Syncthing** syncs `clawdbot_export/` to Clawdbot
2. **Mario** detects new session
3. **Vision analysis** categorizes frames
4. **KB updated** with new information
5. **Slack notification** when complete

## Tips

### Recording
- Narrate naturally — explain what you're doing
- Say "screenshot" before important views
- Keep clips short (30s - 2min)
- It's okay to delete bad takes

### Organization
- One session per work block (30-60 min)
- Use descriptive session names
- Match project name to your PKM folder

### Quality
- Close unnecessary windows before recording
- Undock NX 3D viewport for clean captures
- Speak clearly for better transcription

## Troubleshooting

### Hotkeys not working
- Run as Administrator (Windows)
- Check for conflicts with other apps
- Try restarting KB Capture

### Recording fails
- Ensure FFmpeg is installed: `choco install ffmpeg`
- Check disk space
- Check microphone permissions

### No transcription
- Whisper needs ~2GB RAM for 'base' model
- Try 'tiny' model: `--whisper-model tiny`
- Check CUDA/GPU drivers for faster processing

## Architecture

```
┌─────────────────────────────────────────┐
│           KB Capture (Windows)          │
├─────────────────────────────────────────┤
│  ┌───────────┐  ┌──────────────────┐   │
│  │  Hotkeys  │  │  GUI (optional)  │   │
│  └─────┬─────┘  └────────┬─────────┘   │
│        │                 │              │
│        ▼                 ▼              │
│  ┌─────────────────────────────────┐   │
│  │       Session Manager           │   │
│  │  (clips, keep/delete, merge)    │   │
│  └─────────────┬───────────────────┘   │
│                │                        │
│  ┌─────────────┼───────────────────┐   │
│  │             ▼                   │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │     Screen Recorder     │   │   │
│  │  │     (FFmpeg gdigrab)    │   │   │
│  │  └─────────────────────────┘   │   │
│  │                                 │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │   Whisper Transcriber   │   │   │
│  │  │      (local GPU)        │   │   │
│  │  └─────────────────────────┘   │   │
│  └─────────────────────────────────┘   │
│                │                        │
│                ▼                        │
│  ┌─────────────────────────────────┐   │
│  │      clawdbot_export/           │   │
│  │  merged.mp4 + transcript.json   │   │
│  └─────────────┬───────────────────┘   │
└────────────────┼────────────────────────┘
                 │ Syncthing
                 ▼
┌─────────────────────────────────────────┐
│            Clawdbot (Mario)             │
│  Vision analysis → KB update → Notify   │
└─────────────────────────────────────────┘
```

## Requirements

- Windows 10/11
- Python 3.12+
- FFmpeg (`choco install ffmpeg`)
- CUDA GPU (recommended for Whisper)
- ~4GB RAM (for Whisper 'base' model)

## Related

- [CAD-Documenter README](../README.md) — Original project overview
- [Knowledge Base Skill](http://100.80.199.40:3000/Antoine/clawdbot-shared-skills) — How Mario processes sessions