`CLAUDE.md`

102 lines
# Letsbegin - PRD & Ralph Automation UI

## Quick Reference

- **URL**: http://45.61.58.125:7300
- **Auth**: configured by `AUTH_PASSWORD`
- **PM2**: letsbegin
- **Port**: 7300
- **Skill**: ~/.claude/skills/letsbegin/SKILL.md

## Tech Stack

- Next.js 16 + React 19
- TailwindCSS 4
- PostgreSQL (via pg)
- **Gemini 2.0 Flash API** (FREE - no credits needed!)

## AI Configuration

**ALL AI features use Gemini 2.0 Flash - NO Anthropic API required!**

(Updated 2026-04-30) Ralph's previous `claude --dangerously-skip-permissions` subprocess was replaced with `scripts/ralph-llm-runner.js`, a local-LLM story executor. **Default backend: Ollama qwen3:14b on `http://localhost:11434`** (free, private, no quota). Set `RALPH_LLM=gemini` to fall back to Gemini 2.0 Flash. Per-story flow: model receives the story + project context (tree, package.json, tsconfig, CLAUDE.md) and returns strict JSON `{files: [{path, content}], shell: [], done, summary}`. The runner strips qwen3 `<think>` blocks + JSON fences, writes each file, runs typecheck (`./node_modules/.bin/tsc --noEmit` if present, otherwise skipped honestly), and exits 0/1. Honest limit: both backends are single-shot, not agentic — stories needing iterative read-edit-test loops will fail more often than under Claude. Best for "implement this single file" stories. Smoke-tested 2026-04-30 with `RALPH_SMOKE_OK` marker — Ollama qwen3:14b succeeded.

```typescript
// Text generation
const GEMINI_API_KEY = process.env.GEMINI_API_KEY
const GEMINI_ENDPOINT = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent'

// Image analysis (lib/gemini-image.ts)
import { analyzeImage, analyzeWallcovering } from '@/lib/gemini-image'
```

**Routes using Gemini:**
- `/api/prd/clarify` - Clarifying questions
- `/api/prd/generate` - PRD generation
- `/api/ralph/convert` - User story conversion
- `/api/claude/suggest` - Form suggestions
- `/api/url-info` - URL analysis
- `/api/processes/analyze` - Error analysis
- `/api/processes/fix` - Auto-fix generation

## Key Features

1. **Quick Mode** - Fast PRD generation from plain text
2. **PRD Generator** - Full form-based PRD creation
3. **Ralph Converter** - Convert PRDs to user stories
4. **Ralphy Boy Runner** - Execute tasks with AI

## API Routes

```
/api/ralph/run      - Start Ralph (fresh)
/api/ralph/continue - Continue Ralph (pending only) ← USE THIS
/api/ralph/stop     - Stop Ralph
/api/ralph/status   - Get status
/api/ralph/convert  - Convert PRD to tasks
/api/projects       - List projects
/api/prd            - Generate PRD
/api/quickmode      - Quick mode PRD
/api/processes      - PM2 processes
/api/live           - Live monitoring
```

## Critical Rules

1. **ALWAYS use CONTINUE, not RUN** when resuming Ralph
2. Never restart from scratch unless explicitly requested
3. Check `/api/ralph/status` before starting
4. Monitor progress at `/live`

## Development

```bash
# Dev mode
cd /root/Projects/Letsbegin
npm run dev

# Production
pm2 restart letsbegin

# Logs
pm2 logs letsbegin --lines 50
```

## File Structure

```
app/
├── api/ralph/     # Ralph control APIs
├── api/prd/       # PRD generation
├── api/projects/  # Project listing
├── live/          # Live monitoring page
└── page.tsx       # Main UI

components/
├── QuickModeStep.tsx
├── PRDGeneratorStep.tsx
├── RalphConverterStep.tsx
├── RalphyBoyStep.tsx
└── ProcessStatusBar.tsx
```