docs: refactor documentation and fix inconsistencies (#3178)

## Summary

- Refactored documentation structure for clarity and accuracy
- Fixed inconsistencies between docs and actual workflow implementations
- Translated German text to English
- Updated outdated references

## Key Changes

### Documentation Fixes
- **docs/contributing.md**: Fixed GitHub link (`your-repo` →
`MarkusNeusinger/pyplots`)
- **docs/workflows/overview.md**: 
  - Fixed quality score logic (`>= 90, or >= 50 after 3 attempts`)
- Fixed metadata creation workflow (impl-generate creates, impl-review
updates, impl-merge does NOT create)
- **docs/database.md**: Corrected quality reports location (metadata
files, not GitHub Issues)
- **docs/plot-types-catalog.md**: Translated German descriptions to
English

### Instruction Files
- **CLAUDE.md**: Fixed quality reports references (metadata, not GitHub
Issues)
- **copilot-instructions.md**: Updated quality score label description
- **prompts/README.md**: Fixed workflow names and file paths
  - `gen-library-impl.yml` → `impl-generate.yml`
  - `gen-update-plot.yml` → `impl-repair.yml`
  - `bot-ai-review.yml` → `impl-review.yml`
  - `spec.md` → `specification.md`

### New Files
- **docs/development.md**: New human-focused development guide
(separated from CLAUDE.md which is AI-only)

## Test plan
- [x] All documentation references verified against actual code
- [x] Workflow diagrams match actual workflow implementations
- [x] No broken internal links

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

.claude/commands/prime.md

@@ -10,9 +10,9 @@ git ls-files
 
 @README.md
 @pyproject.toml
-@docs/vision.md
-@docs/workflow.md
-@docs/architecture/repository.md
+@docs/concepts/vision.md
+@docs/workflows/overview.md
+@docs/reference/repository.md
 
 ## Read and Execute
 

.github/copilot-instructions.md

@@ -38,7 +38,7 @@ This file provides guidance to GitHub Copilot when working with code in this rep
 **Supported Libraries** (9 total):
 - matplotlib, seaborn, plotly, bokeh, altair, plotnine, pygal, highcharts, lets-plot
 
-**Core Principle**: Community proposes plot ideas via GitHub Issues → AI generates code → Multi-LLM quality checks → Deployed.
+**Core Principle**: Community proposes plot ideas via GitHub Issues → AI generates code → AI quality review → Deployed.
 
 ## Development Setup
 
@@ -135,8 +135,8 @@ Examples: `scatter-basic`, `scatter-color-mapped`, `bar-grouped-horizontal`, `he
 ### PR Labels (set by workflows)
 
 - **`approved`** - Human approved specification for merge
-- **`ai-approved`** - AI quality check passed (score >= 90)
-- **`ai-rejected`** - AI quality check failed (score < 90)
+- **`ai-approved`** - AI quality check passed (score >= 90, or >= 50 after 3 attempts)
+- **`ai-rejected`** - AI quality check failed (score < 90), triggers repair loop
 - **`quality:XX`** - Quality score (e.g., `quality:92`)
 
 **Specification Lifecycle:**
@@ -146,8 +146,8 @@ Examples: `scatter-basic`, `scatter-color-mapped`, `bar-grouped-horizontal`, `he
 
 **Implementation PR Lifecycle:**
 ```
-[open] → impl-review → ai-approved → impl-merge → impl:{library}:done
-                     → ai-rejected → impl-repair (×3)
+[open] → impl-review → ai-approved (≥90) → impl-merge → impl:{library}:done
+                     → ai-rejected (<90) → impl-repair (×3) → ai-approved (≥50) or failed (<50)
 ```
 
 ## Code Standards
@@ -205,8 +205,7 @@ plt.savefig('plot.png', dpi=300, bbox_inches='tight')
 
 ### Anti-Patterns to Avoid
 
-- No `preview.png` files in repository (use GCS)
-- No `quality_report.json` files (use GitHub Issues)
+- No `preview.png` files in repository (stored in GCS)
 - No hardcoded API keys (use environment variables)
 
 ## Tech Stack

.github/workflows/spec-create.yml

@@ -117,7 +117,7 @@ jobs:
             6. **Create specification files:**
                - Read template: `prompts/templates/specification.md`
                - Read metadata template: `prompts/templates/specification.yaml`
-               - Read tagging guide: `docs/concepts/tagging-system.md`
+               - Read tagging guide: `docs/reference/tagging-system.md`
                - Create directory: `plots/{specification-id}/`
                - Create: `plots/{specification-id}/specification.md` (follow template structure)
                - Create: `plots/{specification-id}/specification.yaml` with:
@@ -213,7 +213,7 @@ jobs:
             6. **Create specification files:**
                - Read template: `prompts/templates/specification.md`
                - Read metadata template: `prompts/templates/specification.yaml`
-               - Read tagging guide: `docs/concepts/tagging-system.md`
+               - Read tagging guide: `docs/reference/tagging-system.md`
                - Create directory: `plots/{specification-id}/`
                - Create: `plots/{specification-id}/specification.md` (follow template structure)
                - Create: `plots/{specification-id}/specification.yaml` with:

CLAUDE.md

@@ -109,7 +109,7 @@ done
 - **highcharts** - Interactive web charts, stock charts (requires license for commercial use)
 - **lets-plot** - ggplot2 grammar of graphics by JetBrains, interactive
 
-**Core Principle**: Community proposes plot ideas via GitHub Issues → AI generates code → Multi-LLM quality checks → Deployed.
+**Core Principle**: Community proposes plot ideas via GitHub Issues → AI generates code → AI quality review → Deployed.
 
 ## Essential Commands
 
@@ -261,7 +261,7 @@ Example: `plots/scatter-basic/` contains everything for the basic scatter plot.
 
 1. **Repository Pattern**: Data access layer in `core/repositories/`
 2. **Async Everything**: FastAPI + SQLAlchemy async + asyncpg
-3. **Clean Repo**: Only production code in git. Quality reports → GitHub Issues. Preview images → GCS.
+3. **Clean Repo**: Only production code in git. Quality reports → `metadata/{library}.yaml`. Preview images → GCS.
 4. **Issue-Based Workflow**: GitHub Issues as state machine for plot lifecycle
 
 ### Metadata System
@@ -399,8 +399,8 @@ gs://pyplots-images/
 - **Plotting**: matplotlib, seaborn, plotly, bokeh, altair, plotnine, pygal, highcharts, lets-plot
 - **Package Manager**: uv (fast Python installer)
 - **Infrastructure**: Google Cloud Run, Cloud SQL, Cloud Storage
-- **Automation**: GitHub Actions (code workflows) + n8n Cloud (external services)
-- **AI**: Claude (code generation), Vertex AI (multi-LLM quality checks)
+- **Automation**: GitHub Actions
+- **AI**: Claude (code generation + quality review)
 
 ## Code Standards
 
@@ -475,7 +475,6 @@ uv run python -c "from core.database import is_db_configured; print(is_db_config
 - Implementation code (full Python source)
 - Implementation metadata (library, variant, quality score, generation info from metadata/*.yaml)
 - GCS URLs for preview images
-- Social media promotion queue
 
 **What's in Repository** (source of truth):
 - Everything in `plots/{specification-id}/`:
@@ -486,7 +485,6 @@ uv run python -c "from core.database import is_db_configured; print(is_db_config
 
 **What's NOT Stored in DB**:
 - Preview images (in GCS)
-- Detailed quality reports (in GitHub Issues, summary in metadata)
 
 **Migrations**: Managed with Alembic
 ```bash
@@ -511,8 +509,7 @@ The `prompts/` directory contains AI agent prompts for code generation, quality
 | `plot-generator.md` | Base rules for all plot implementations |
 | `library/*.md` | Library-specific rules (9 files) |
 | `quality-criteria.md` | Definition of code/visual quality |
-| `quality-evaluator.md` | Multi-LLM evaluation prompt |
-| `auto-tagger.md` | Automatic tagging across 5 dimensions |
+| `quality-evaluator.md` | AI quality evaluation prompt |
 | `spec-validator.md` | Validates plot request issues |
 | `spec-id-generator.md` | Assigns unique spec IDs |
 
@@ -918,12 +915,12 @@ pytest --pdb       # Debug on failure
 
 ## Key Documentation Files
 
-- **docs/development.md**: Development setup, testing, deployment
-- **docs/workflow.md**: Automation flows (Discovery → Deployment → Social)
-- **docs/specs-guide.md**: How to write plot specifications
-- **docs/architecture/repository.md**: Directory structure
-- **docs/architecture/api.md**: API endpoints reference
-- **docs/architecture/database.md**: Database schema
+- **docs/contributing.md**: How to add/improve specs and implementations
+- **docs/workflows/overview.md**: Automation flows and label system
+- **docs/concepts/vision.md**: Product vision
+- **docs/reference/repository.md**: Directory structure
+- **docs/reference/api.md**: API endpoints reference
+- **docs/reference/database.md**: Database schema
 - **prompts/README.md**: AI agent prompt system
 
 ## Project Philosophy
@@ -932,5 +929,5 @@ pytest --pdb       # Debug on failure
 - **Spec improvements over code fixes**: If a plot has issues, improve the spec, not the code
 - **Your data first**: Examples work with real user data, not fake data
 - **Community-driven**: Anyone can propose plots via GitHub Issues
-- **Multi-LLM quality**: Claude + Gemini + GPT ensure quality (score ≥90 required)
-- **Full transparency**: All feedback documented in GitHub Issues, not hidden in repo files
+- **AI quality review**: Claude evaluates quality (≥90 instant merge, <90 repair loop, ≥50 minimum)
+- **Full transparency**: All quality feedback stored in repository (`metadata/{library}.yaml`)

README.md

@@ -18,7 +18,7 @@
 maintains plotting examples. Browse hundreds of plots across all major Python libraries - matplotlib, seaborn, plotly,
 bokeh, altair, plotnine, pygal, highcharts, and lets-plot.
 
-**Community-driven, AI-maintained** - Propose plot ideas via GitHub Issues, AI generates the code, multi-LLM quality
+**Community-driven, AI-maintained** - Propose plot ideas via GitHub Issues, AI generates the code, automated quality
 checks ensure excellence. Zero manual coding required.
 
 ---
@@ -29,37 +29,11 @@ checks ensure excellence. Zero manual coding required.
 - **Compare libraries** - View matplotlib, seaborn, plotly side-by-side for the same plot
 - **Always current** - AI agents continuously update examples with latest library versions
 - **Natural language search** - Find plots by asking "show correlation between variables"
-- **Multi-LLM quality checks** - Claude + Gemini + GPT ensure every plot meets quality standards
+- **AI quality review** - Claude evaluates every plot against quality standards (score ≥ 50 required)
 - **Open source** - Community proposes ideas via Issues, AI generates the code
 
 ---
 
-## Quick Start
-
-```bash
-# Clone repository
-git clone https://github.com/MarkusNeusinger/pyplots.git
-cd pyplots
-
-# Install dependencies with uv (fast!)
-curl -LsSf https://astral.sh/uv/install.sh | sh
-uv sync --all-extras
-
-# Database setup (optional - API works without DB in limited mode)
-cp .env.example .env
-# Edit .env with your DATABASE_URL
-
-# Run migrations
-uv run alembic upgrade head
-
-# Start backend
-uv run uvicorn api.main:app --reload
-
-# Visit http://localhost:8000/docs
-```
-
----
-
 ## Architecture
 
 **Specification-first design**: Every plot starts as a Markdown spec (library-agnostic), then AI generates
@@ -81,9 +55,9 @@ plots/scatter-basic/
 
 **Issue-based workflow**: GitHub Issues as state machine for plot lifecycle. Status tracked via live-updating table (no sub-issues). Each library generates in parallel, creating PRs to a feature branch.
 
-**AI quality review**: Claude evaluates generated plots (score ≥ 90 required). Automatic feedback loops (max 3 attempts per library). Quality scores flow via PR labels → per-library metadata files.
+**AI quality review**: Claude evaluates generated plots. Score ≥ 90 → immediate merge. Score < 90 → repair loop (max 3 attempts). After 3 attempts: ≥ 50 → merge, < 50 → failed.
 
-See [docs/architecture/](docs/architecture/) for details.
+See [docs/reference/](docs/reference/) for details.
 
 ---
 
@@ -97,9 +71,9 @@ See [docs/architecture/](docs/architecture/) for details.
 
 **Infrastructure**: Google Cloud Run • Cloud SQL • Cloud Storage
 
-**Automation**: GitHub Actions • n8n Cloud Pro
+**Automation**: GitHub Actions
 
-**AI**: Claude (Code Max) • Vertex AI (Multi-LLM)
+**AI**: Claude (code generation + quality review)
 
 ---
 
@@ -115,31 +89,28 @@ Most plotting libraries are fully open source. Note these exceptions:
 
 ```
 pyplots/
-├── plots/              # Plot-centric directories (spec + metadata + implementations)
-│   └── {spec-id}/
-│       ├── specification.md
-│       ├── specification.yaml
-│       ├── metadata/
-│       └── implementations/
+├── plots/              # Plot specs + metadata + implementations
 ├── prompts/            # AI agent prompts
-├── core/               # Shared business logic
 ├── api/                # FastAPI backend
-├── app/                # React frontend (Vite + MUI)
-├── tests/              # Test suite (pytest)
-└── docs/               # Documentation
+├── app/                # React frontend
+├── core/               # Shared business logic
+├── automation/         # Workflow scripts (sync, labels)
+├── tests/              # Test suite (unit, integration, e2e)
+├── alembic/            # Database migrations
+├── docs/               # Documentation
+└── .github/workflows/  # GitHub Actions
 ```
 
-**For detailed structure and file organization**, see [Repository Structure](docs/architecture/repository.md)
+**For details**, see [Repository Structure](docs/reference/repository.md)
 
 ---
 
 ## Documentation
 
-- **[Vision](docs/vision.md)** - Product vision and mission
-- **[Workflow](docs/workflow.md)** - Automation flows (Discovery → Deployment → Social Media)
-- **[Development](docs/development.md)** - Local setup, testing, deployment
-- **[Specs Guide](docs/specs-guide.md)** - How to write plot specifications
-- **[Architecture](docs/architecture/)** - API, database, repository structure
+- **[Vision](docs/concepts/vision.md)** - Product vision and mission
+- **[Contributing](docs/contributing.md)** - How to add/improve specs and implementations
+- **[Workflows](docs/workflows/overview.md)** - Automation flows and label system
+- **[Reference](docs/reference/)** - API, database, repository structure
 
 ---
 
@@ -160,32 +131,19 @@ We welcome contributions! **All code is AI-generated** - you propose ideas, AI i
 2. AI generates spec, creates feature branch
 3. Maintainer reviews and adds `approved` label
 4. 9 library implementations generate in parallel (tracked via live status table)
-5. AI quality review per library (score ≥ 90 required)
+5. AI quality review per library (≥ 90 instant, < 90 repair loop, ≥ 50 final threshold)
 6. Auto-merge to feature branch, then to main
 
 **Important**: Don't submit code directly! If a plot has quality issues, it means the spec needs improvement, not the
 code.
 
-See [development.md](docs/development.md) for details.
+See [contributing.md](docs/contributing.md) for details.
 
 ---
 
 ## Development
 
-```bash
-# Install dependencies (uv is a fast Python package installer)
-uv sync --all-extras
-
-# Run tests
-uv run pytest
-
-# Start backend
-uv run uvicorn api.main:app --reload
-```
-
-**For detailed development setup, testing, and code quality tools**, see [Development Guide](docs/development.md)
-
-**Python versions**: 3.10+ | **Coverage target**: 90%+
+See **[Development Guide](docs/development.md)** for local setup instructions.
 
 ---