From 3360ca921b9eed5368ebc2cfdda3f58c77ffa31e Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 29 Mar 2026 21:51:44 +0200 Subject: [PATCH] docs(quick-260329-ua1): README.md erstellen (English, Open-Source Standard) --- .../260329-ua1-PLAN.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 .planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-PLAN.md diff --git a/.planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-PLAN.md b/.planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-PLAN.md new file mode 100644 index 0000000..1dbe91d --- /dev/null +++ b/.planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-PLAN.md @@ -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: [] +--- + + +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 + + + +@$HOME/.claude/get-shit-done/workflows/execute-plan.md +@$HOME/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@CLAUDE.md +@package.json + + + + + + Task 1: Create README.md with full open-source documentation + README.md + +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 +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. + + + test -f README.md && wc -l README.md | awk '{if ($1 >= 80) print "PASS: " $1 " lines"; else print "FAIL: only " $1 " lines"}' + + README.md exists at project root with all specified sections, content is in English, at least 80 lines, accurate to the actual codebase + + + + + +- 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 + + + +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. + + + +After completion, create `.planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-SUMMARY.md` +