uncloseai-speech/docs/CLAUDE.md

# Instructions for Claude Code

**Project:** UncloseAI Speech - Raccoon Mission TTS System
**License:** AGPL v3 (must provide source code to network service users)

## Core Principles

### 1. Makefile-First Development

**ALWAYS prefer Makefile targets over manual commands.**

- ✅ DO: `make deploy`, `make voices`, `make test`
- ❌ DON'T: Manual ssh commands, docker commands, curl commands

**When adding new functionality:**
1. Add it to the Makefile first
2. Document it in `make help`
3. Test it works from scratch
4. Only then modify other files if needed

**Makefile is the source of truth** for all deployment and development tasks.

### 2. Work Locally, Deploy Remotely

- **Local development:** `/home/fox/git/openedai-speech/`
- **Remote server:** Configured in `vars.sh` (gitignored)
- **Never create remote directories manually** - let Makefile handle it
- **Always test from scratch** - `make clean` then `make deploy`

### 3. Configuration Management

- `vars.sh` - Deployment secrets (gitignored, never commit)
- `vars.sh.example` - Template for users (commit this)
- `sample.env` - Default environment (commit this)
- `speech.env` - Runtime environment (created automatically by Makefile)

**Never view or log secrets** - source them and use them.

### 4. Documentation Requirements

When adding features, update ALL relevant docs:
- `Makefile` help text
- `docs/MODELS.md` for new TTS engines
- `docs/MIRRORS.md` for binary downloads
- `docs/AUDIT.md` for file changes
- This file (`docs/CLAUDE.md`) for new patterns

## Common Tasks

### Full Deployment from Scratch

```bash
# 1. Clean everything
make clean

# 2. Deploy (syncs files, creates env, builds container)
make deploy

# 3. Download voices (Piper + XTTS samples)
make voices

# 4. Test
make test
make test-xtts
```

### Adding a New TTS Engine

1. Document it in `docs/MODELS.md` first
2. Add download target to Makefile (e.g., `voices-silero`)
3. Implement engine wrapper in `speech.py` or `src/engines/`
4. Add test target (e.g., `test-silero`)
5. Update `make voices` to include it
6. Test full cycle: `make clean && make deploy && make voices`

### Debugging Issues

```bash
make logs          # Tail live logs
make logs | grep ERROR  # Filter errors
```

Never use raw docker/ssh commands - extend Makefile if needed.

## File Organization

### Scripts vs Docs

- `scripts/` - Executable utilities (add_voice.py, download_samples.sh, etc.)
- `docs/` - Documentation ONLY (no executable code)
- Dockerfiles, startup.sh - Root level (build artifacts)
- Makefile - Root level (primary interface)

**Never put executable scripts in docs/ directory.**

### Current Structure (as of 2025-11-09)

```
uncloseai-speech/
├── Makefile              # PRIMARY INTERFACE - always update first
├── vars.sh               # Secrets (gitignored)
├── vars.sh.example       # Template
├── speech.py             # Main server (will refactor to src/)
├── openedai.py           # API models
├── voice_to_speaker.default.yaml  # Voice config
├── docs/
│   ├── CLAUDE.md         # This file
│   ├── AUDIT.md          # Repository audit
│   ├── MODELS.md         # TTS engines
│   └── MIRRORS.md        # Binary mirror strategy
├── scripts/
│   ├── add_voice.py
│   ├── say.py
│   ├── test_voices.sh
│   └── download_samples.sh
├── Dockerfile
├── docker-compose.yml
└── startup.sh
```

## TTS Engine Status

### Working
- ✅ Piper TTS (tts-1) - Fast, 100+ voices, absolute paths working
- ⚠️ XTTS v2 (tts-1-hd) - High quality, needs speaker samples

### High Priority Integration
- 🎯 Silero TTS - Active project, fast, good quality
- 🎯 StyleTTS2 - Best quality available
- 🎯 Fish Speech - Modern, multilingual

See `docs/MODELS.md` for complete roadmap.

## Deployment Workflow

```
Local:
  /home/fox/git/openedai-speech/

  ↓ make deploy (rsync)

Remote (ai.foxhop.net):
  ~/uncloseai-speech/

  ↓ docker compose up --build

Container:
  /app/
  ├── speech.py
  ├── voices/
  │   └── en/en_US/libritts_r/medium/*.onnx
  └── config/
      └── voice_to_speaker.yaml
```

## Testing Philosophy

**Always test the full stack:**
1. Clean state (`make clean`)
2. Fresh deploy (`make deploy`)
3. Voice download (`make voices`)
4. API test (`make test`, `make test-xtts`)

**Never assume** - if you changed something, test from scratch.

## Raccoon Mission Values

1. **Resilience** - Assume upstream dies, plan mirrors
2. **Simplicity** - Makefile > manual commands
3. **Documentation** - Write docs before code
4. **Liberation** - Keep TTS libre (AGPL v3)
5. **Unification** - All TTS engines, one API

## Common Mistakes to Avoid

❌ DON'T create directories with raw ssh
✅ DO add Makefile target for deployment

❌ DON'T assume container has changes after rsync
✅ DO rebuild with `make deploy` (runs docker compose up --build)

❌ DON'T put scripts in docs/
✅ DO put scripts in scripts/, reference from docs

❌ DON'T hardcode paths/hosts
✅ DO use vars.sh variables

❌ DON'T forget to test from scratch
✅ DO run `make clean && make deploy && make voices`

## When Things Break

1. Check `make logs` for errors
2. Verify Makefile was updated
3. Test from clean state
4. Check if container was rebuilt (`make deploy` does this)
5. Verify voices downloaded (`ls` in container via `make logs` approach)

## Future Refactoring (Planned)

- Move `speech.py`, `openedai.py`, `audio_reader.py` → `src/`
- Create engine abstraction layer in `src/engines/`
- Unified voice config with engine selection
- Binary mirror implementation (MinIO on ai.foxhop.net)

See `docs/AUDIT.md` for detailed refactoring plan.

---

**Remember:** Makefile first, documentation second, code third. Test from scratch every time.

🦝 **Raccoon Mission:** Keep TTS libre, rescue abandoned models, unify all engines.