docs(quick-260329-ua1): README.md erstellen (English, Open-Source Standard)
This commit is contained in:
+171
@@ -0,0 +1,171 @@
|
|||||||
|
---
|
||||||
|
phase: quick
|
||||||
|
plan: 260329-ua1
|
||||||
|
type: execute
|
||||||
|
wave: 1
|
||||||
|
depends_on: []
|
||||||
|
files_modified: [README.md]
|
||||||
|
autonomous: true
|
||||||
|
requirements: []
|
||||||
|
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "README.md exists at project root with English open-source content"
|
||||||
|
- "A developer can understand what the project does, how to set it up, and how to run it"
|
||||||
|
- "Gemini API key configuration is clearly documented"
|
||||||
|
artifacts:
|
||||||
|
- path: "README.md"
|
||||||
|
provides: "Project documentation for open-source audiences"
|
||||||
|
min_lines: 80
|
||||||
|
key_links: []
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
Create a comprehensive English README.md following open-source project conventions.
|
||||||
|
|
||||||
|
Purpose: Make the project approachable for English-speaking developers browsing the repo.
|
||||||
|
Output: README.md at project root
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
||||||
|
@$HOME/.claude/get-shit-done/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@.planning/PROJECT.md
|
||||||
|
@CLAUDE.md
|
||||||
|
@package.json
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Task 1: Create README.md with full open-source documentation</name>
|
||||||
|
<files>README.md</files>
|
||||||
|
<action>
|
||||||
|
Create README.md at project root in English. Structure it with these sections:
|
||||||
|
|
||||||
|
**Header area:**
|
||||||
|
- Project name "Zauberwald" with a one-line tagline: "A magical typing tutor that teaches touch typing through an AI-generated enchanted forest"
|
||||||
|
- Short paragraph explaining the concept: a web app for teaching a 7-year-old child touch typing via QWERTZ keyboard, combining structured typing exercises with a dynamically growing AI-generated forest world. Curiosity-driven, not score-driven.
|
||||||
|
- Screenshot placeholder: `<!--  -->`
|
||||||
|
|
||||||
|
**Features section** (bullet list):
|
||||||
|
- 10-finger touch typing with QWERTZ (DE/CH) on-screen keyboard with color-coded finger zones
|
||||||
|
- 3-phase micro-lessons: Discover, Practice, Build Words (90-120 seconds each)
|
||||||
|
- AI-generated forest rewards (Gemini API) — new forest elements appear after each lesson
|
||||||
|
- 4 companion characters (Fee Lila, Einhorn Stella, Fuchs Finn, Eule Elsa) with AI-generated dialogue
|
||||||
|
- Adaptive tempo that adjusts to the child's speed
|
||||||
|
- No visible scores, timers, or error counters — progress shown only through the growing forest
|
||||||
|
- Parent dashboard (Ctrl+Shift+E + code) with statistics, export/import, settings
|
||||||
|
- Audio feedback (key sounds, rewards) and optional speech output
|
||||||
|
- Offline-capable with IndexedDB storage (images cached as blobs)
|
||||||
|
- Watercolor pastel art style with gentle animations
|
||||||
|
|
||||||
|
**Tech Stack section:**
|
||||||
|
- Vanilla TypeScript (no framework)
|
||||||
|
- Vite 6.x (build tool)
|
||||||
|
- Biome (linting)
|
||||||
|
- Vitest (testing)
|
||||||
|
- Gemini API (text: gemini-2.5-flash, images: gemini-3.1-flash-image-preview)
|
||||||
|
- IndexedDB for client-side persistence
|
||||||
|
- Web Audio API + Web Speech API
|
||||||
|
|
||||||
|
**Prerequisites:**
|
||||||
|
- Node.js 18+
|
||||||
|
- npm
|
||||||
|
- Google Gemini API key (for AI features; app works with fallbacks without it)
|
||||||
|
|
||||||
|
**Getting Started:**
|
||||||
|
```bash
|
||||||
|
git clone <repo-url>
|
||||||
|
cd zauberwald
|
||||||
|
npm install
|
||||||
|
cp public/config.example.json public/config.json
|
||||||
|
# Edit public/config.json and add your Gemini API key
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
Then open http://localhost:5173
|
||||||
|
|
||||||
|
**Available Scripts** (table format from package.json):
|
||||||
|
- `npm run dev` — Start dev server (--host 0.0.0.0)
|
||||||
|
- `npm run build` — Type-check and build for production
|
||||||
|
- `npm run preview` — Preview production build (port 4173)
|
||||||
|
- `npm test` — Run tests
|
||||||
|
- `npm run lint` — Lint with Biome
|
||||||
|
- `npm run lint:fix` — Lint and auto-fix
|
||||||
|
- `npm run generate-assets` — Pre-generate companion character assets via Gemini
|
||||||
|
|
||||||
|
**Project Structure** (tree showing key directories):
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
api/ — Gemini API client and config loader
|
||||||
|
audio/ — Sound effects and speech synthesis
|
||||||
|
companion/ — Character definitions, AI dialogue, fallbacks
|
||||||
|
forest/ — Forest scene rendering and reward logic
|
||||||
|
game/ — Keyboard, levels, typing engine, word lists
|
||||||
|
storage/ — IndexedDB persistence layer
|
||||||
|
ui/ — Screen management and parent dashboard
|
||||||
|
styles/ — CSS (single main.css with custom properties)
|
||||||
|
assets/ — Companion avatars, character sheets, fallback SVGs
|
||||||
|
types.ts — Shared type definitions
|
||||||
|
main.ts — App entry point
|
||||||
|
app.ts — App initialization and routing
|
||||||
|
public/
|
||||||
|
config.json — Runtime config (API keys, not committed)
|
||||||
|
scripts/
|
||||||
|
generate-assets.ts — Pre-generate character images
|
||||||
|
```
|
||||||
|
|
||||||
|
**How It Works** section:
|
||||||
|
Explain the core loop in 2-3 paragraphs:
|
||||||
|
1. The child picks a companion and starts a level. Each level introduces new keys on the home row (levels 1-6 in MVP).
|
||||||
|
2. A micro-lesson has 3 phases: Discover (see new keys light up), Practice (type prompted letters with adaptive timing), Build Words (type simple words using learned keys).
|
||||||
|
3. After completing a lesson, the forest grows: the app generates a new forest element image via Gemini API (or uses SVG fallbacks). The child is motivated to continue because they want to see what appears next in their forest — not because of points or stars.
|
||||||
|
|
||||||
|
**Configuration** section:
|
||||||
|
- Copy `public/config.example.json` to `public/config.json`
|
||||||
|
- Add your Gemini API key
|
||||||
|
- Note: The app works without an API key using built-in fallback texts and SVG images
|
||||||
|
- Note: The API key is stored client-side — this is acceptable for private/single-user use
|
||||||
|
|
||||||
|
**Deployment** section:
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
# Serve the dist/ directory with any static file server
|
||||||
|
# For VPS preview:
|
||||||
|
npm run preview # serves on 0.0.0.0:4173
|
||||||
|
```
|
||||||
|
|
||||||
|
**Contributing** section:
|
||||||
|
"Contributions are welcome! Please open an issue first to discuss what you would like to change."
|
||||||
|
|
||||||
|
**License** section:
|
||||||
|
"This project is not yet licensed. Please contact the author for usage terms."
|
||||||
|
(Note: Do NOT create a LICENSE file, just mention status in README.)
|
||||||
|
|
||||||
|
Use clean markdown formatting. No emojis. Keep language concise and professional.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>test -f README.md && wc -l README.md | awk '{if ($1 >= 80) print "PASS: " $1 " lines"; else print "FAIL: only " $1 " lines"}'</automated>
|
||||||
|
</verify>
|
||||||
|
<done>README.md exists at project root with all specified sections, content is in English, at least 80 lines, accurate to the actual codebase</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
- README.md exists at project root
|
||||||
|
- Content is in English
|
||||||
|
- All sections present: features, tech stack, prerequisites, getting started, scripts, project structure, how it works, configuration, deployment, contributing, license
|
||||||
|
- File paths and commands match actual project structure
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
README.md is complete, accurate, and follows open-source conventions. A developer unfamiliar with the project can understand what it does, set it up, and run it.
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
After completion, create `.planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-SUMMARY.md`
|
||||||
|
</output>
|
||||||
Reference in New Issue
Block a user