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

# 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 — Original project overview
• Knowledge Base Skill — How Mario processes sessions