mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-16 18:59:40 +02:00
8e414c12ba
- Integrate worldream (text-first world-building platform) into games/ - Configure as @worldream/web workspace package - Remove standalone git repo, now part of monorepo 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
157 lines
5 KiB
Markdown
157 lines
5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Worldream** is a text-first platform for building and managing fictional worlds. It allows users to create and manage Characters, Objects, Places, and Stories as text-based entities that can be referenced and combined using @slug notation.
|
|
|
|
Key Concepts:
|
|
|
|
- **Content Nodes**: Unified entities representing worlds, characters, objects, places, and stories
|
|
- **@slug References**: Human-readable way to link entities within text (e.g., `@mira`, `@neo_station`)
|
|
- **Text-First Design**: All content is primarily text/markdown with optional attachments
|
|
- **LLM-Friendly**: Designed to work well with language models through clear text formats and prompt guidelines
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Install dependencies (using pnpm)
|
|
pnpm install
|
|
|
|
# Start development server
|
|
pnpm dev
|
|
# or with browser auto-open
|
|
pnpm dev -- --open
|
|
|
|
# Build for production
|
|
pnpm build
|
|
|
|
# Preview production build
|
|
pnpm preview
|
|
|
|
# Type checking
|
|
pnpm check
|
|
# Watch mode for type checking
|
|
pnpm check:watch
|
|
|
|
# Linting and formatting
|
|
pnpm lint # Check formatting and run ESLint
|
|
pnpm format # Auto-format with Prettier
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Tech Stack
|
|
|
|
- **Framework**: SvelteKit with TypeScript und Svelte 5 (Runes Syntax)
|
|
- **Styling**: Tailwind CSS v4 (configured via Vite plugin)
|
|
- **Preprocessors**: Vite preprocessing for Svelte
|
|
- **Adapter**: Node.js adapter for deployment flexibility
|
|
- **Package Manager**: pnpm with workspace optimization
|
|
- **AI Integration**:
|
|
- OpenAI API mit GPT-5-mini für Text-Generierung (siehe wichtige Hinweise unten!)
|
|
- Google Gemini gemini-2.5-flash-image-preview für Bild-Generierung
|
|
|
|
### Project Structure
|
|
|
|
- `/src/routes/` - SvelteKit pages and API endpoints
|
|
- `/src/lib/` - Shared components and utilities
|
|
- `/src/app.css` - Global styles with Tailwind imports
|
|
- `/src/app.d.ts` - TypeScript ambient declarations
|
|
- `/static/` - Static assets
|
|
|
|
### Configuration Files
|
|
|
|
- `svelte.config.js` - SvelteKit configuration with Node adapter
|
|
- `vite.config.ts` - Vite config with Tailwind and SvelteKit plugins
|
|
- `tsconfig.json` - TypeScript config extending SvelteKit defaults (strict mode enabled)
|
|
- `eslint.config.js` - ESLint flat config with TypeScript and Svelte support
|
|
|
|
### Planned Data Model (from docs/ProjectPlan.md)
|
|
|
|
The project will use a unified `content_nodes` table with:
|
|
|
|
- Meta fields: id, kind, slug, title, summary, visibility, tags, etc.
|
|
- Content stored as JSONB with standardized keys across all entity types
|
|
- Full-text search via PostgreSQL tsvector
|
|
- Optional versioning via `node_revisions` table
|
|
- Story entries as separate timeline items
|
|
|
|
## Development Guidelines
|
|
|
|
### Svelte 5 Runes Syntax
|
|
|
|
This project uses Svelte 5 with runes - WICHTIG: Keine Legacy-Syntax verwenden!
|
|
|
|
- Use `$state()` for reactive state
|
|
- Use `$derived()` for computed values (NOT `$:` reactive statements)
|
|
- Use `$effect()` for side effects
|
|
- Use `$props()` for component props
|
|
- Use `{@render}` for rendering children/snippets
|
|
- Components use TypeScript with `<script lang="ts">`
|
|
|
|
### Import Aliases
|
|
|
|
- `$lib` maps to `/src/lib/`
|
|
- Additional aliases can be configured in svelte.config.js
|
|
|
|
### Database Integration (Implemented)
|
|
|
|
- Uses Supabase (PostgreSQL) with hybrid schema
|
|
- Content stored as JSONB for flexibility
|
|
- Row Level Security (RLS) based on owner_id and visibility
|
|
- Full-text search via generated tsvector columns
|
|
- World-centric navigation: All content is created within a world context
|
|
|
|
## ⚠️ KRITISCH: GPT-5-mini API Einschränkungen
|
|
|
|
**WICHTIG**: Dieses Projekt nutzt GPT-5-mini, ein spezielles OpenAI-Modell mit strikten Einschränkungen:
|
|
|
|
### Parameter-Einschränkungen
|
|
|
|
1. **Temperature**:
|
|
- **NUR `temperature: 1.0` wird unterstützt!**
|
|
- Andere Werte (0.7, 0.8, etc.) führen zu einem 400 Error
|
|
- Am besten den Parameter komplett weglassen (1.0 ist default)
|
|
|
|
2. **Token Limits**:
|
|
- **MUSS `max_completion_tokens` verwenden, NICHT `max_tokens`!**
|
|
- `max_tokens` führt zu einem 400 Error
|
|
- Typische Werte: 1000-5000 für normale Generierung
|
|
|
|
### Korrekte Verwendung
|
|
|
|
```typescript
|
|
// ✅ RICHTIG
|
|
const completion = await openai.chat.completions.create({
|
|
model: 'gpt-5-mini',
|
|
messages: [...],
|
|
// temperature weglassen oder 1.0
|
|
max_completion_tokens: 2000 // NICHT max_tokens!
|
|
});
|
|
|
|
// ❌ FALSCH - führt zu 400 Error
|
|
const completion = await openai.chat.completions.create({
|
|
model: 'gpt-5-mini',
|
|
messages: [...],
|
|
temperature: 0.7, // ERROR!
|
|
max_tokens: 2000 // ERROR! Muss max_completion_tokens sein
|
|
});
|
|
```
|
|
|
|
### Modell-Details
|
|
|
|
- **Knowledge Cutoff**: Mai 30, 2024
|
|
- **Kosten**: $0.25/1M Input, $2.00/1M Output
|
|
- **Features**: Unterstützt JSON mode, Streaming, Tools, Vision
|
|
- **Performance**: Gute Balance zwischen Geschwindigkeit und Qualität
|
|
|
|
### Debugging
|
|
|
|
Wenn API-Calls fehlschlagen:
|
|
1. Prüfe ob `temperature` != 1.0 gesetzt ist
|
|
2. Prüfe ob `max_tokens` statt `max_completion_tokens` verwendet wird
|
|
3. Prüfe die Console für detaillierte Fehlermeldungen
|
|
|
|
Weitere Details siehe `/docs/GPT5-MINI.md`
|