kdb/SETUP.md

# Setup Guide for sflabs Projects

## Quick Start

### 1. Clone the KDB

```bash
cd /home/tr/.qwen/projects/
git clone https://teashop.invaliddevice.com/SFLabs/kdb.git memory
```

### 2. Install Obsidian (optional but recommended)

```bash
# Download from https://obsidian.md
# Or use the AppImage:
cd /tmp
wget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.7.6/Obsidian-1.7.6.AppImage
chmod +x Obsidian-1.7.6.AppImage
mv Obsidian-1.7.6.AppImage ~/.local/bin/obsidian.AppImage
```

### 3. Open the KDB

```bash
obsidian /home/tr/.qwen/projects/-home-tr-work-kdb/memory
```

Or use the helper script:

```bash
sflabs-kdb open
```

## Git Credentials

### Option 1: HTTPS with Personal Access Token

1. Generate PAT on Gitea: `teashop.invaliddevice.com/user/settings/applications`
2. Configure git:

```bash
git config --global credential.helper store
# Then run any git command and enter credentials when prompted
```

### Option 2: SSH Keys

```bash
# Generate SSH key if you don't have one
ssh-keygen -t ed25519 -C "your-email@example.com"

# Add to Gitea: teashop.invaliddevice.com/user/settings/keys
# Clone with SSH:
git clone git@teashop.invaliddevice.com:sflabs/kdb.git memory
```

## Workflow

### Before Starting Work

```bash
sflabs-kdb pull
```

### After Completing Work

```bash
# Review changes
sflabs-kdb status

# Commit and push
git add .
git commit -m "Describe your changes"
sflabs-kdb push
```

### Full Sync

```bash
sflabs-kdb sync
```

## Multi-Project Access

### For Other sflabs Projects

Add this to your project's `.qwen/settings.json`:

```json
{
  "mcpServers": {
    "sflabs-kdb": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/tr/.qwen/projects/-home-tr-work-kdb/memory"
      ]
    }
  }
}
```

### Using the Skill

In Qwen Code:

```
/skill sflabs-kdb pull
/skill sflabs-kdb push
/skill sflabs-kdb sync
```

## Conflict Resolution

If you get merge conflicts:

```bash
# Pull and check for conflicts
git pull

# Resolve conflicts in Obsidian or your editor
# Then commit
git add .
git commit -m "Resolve merge conflicts"
git push
```

## Best Practices

1. **Sync often** - Pull before starting, push after finishing
2. **Small commits** - One logical change per commit
3. **Descriptive messages** - Explain what and why
4. **Check status** - Always review before pushing
5. **Use templates** - Maintain consistent structure

## Troubleshooting

### "Permission denied" on push

- Check your Gitea credentials
- Verify SSH key is added (if using SSH)
- Ensure you have write access to the repo

### "Repository not found"

- Verify URL: `https://teashop.invaliddevice.com/sflabs/kdb`
- Check repo exists on Gitea
- Ensure network connectivity

### Obsidian won't open

```bash
# Check if AppImage is executable
ls -la ~/.local/bin/obsidian.AppImage

# Try running directly
~/.local/bin/obsidian.AppImage /home/tr/.qwen/projects/-home-tr-work-kdb/memory
```

## Help

- Skill docs: `/home/tr/.qwen/skills/sflabs-kdb/README.md`
- Script help: `sflabs-kdb help`
- Git help: `git help`

---

**Repo:** teashop.invaliddevice.com/SFLabs/kdb
**Skill:** `sflabs-kdb`