feat(schema): multi-language path restructure + languages table

Phase B of the big plot migration. Layers {language} into every path so
future R, JavaScript, Julia implementations fit without another schema
change — today {language} is always "python".

Filesystem: 5354 files moved via `git mv` (blame preserved).
- plots/{spec}/implementations/{library}.py
    → plots/{spec}/implementations/python/{library}.py
- plots/{spec}/metadata/{library}.yaml
    → plots/{spec}/metadata/python/{library}.yaml
- Migration script: automation/scripts/migrate_paths_to_language.py
  (idempotent, re-runnable, used for this commit).

Database: Alembic migration f2d9c8a1b4e0 creates:
- `languages` table (analog `libraries`) with Python seed.
- `libraries.language` (String) → `libraries.language_id` (FK → languages.id)
  — models.py adds a synonym so `library.language` keeps working.
- `impls.language_id` FK with backfill to "python"; UQ broadened from
  (spec_id, library_id) to (spec_id, language_id, library_id).
- `preview_url` → `preview_url_light`; new `preview_url_dark`,
  `preview_html_light`, `preview_html_dark` (Phase C will fill the dark
  variants). `Impl.preview_url` kept as synonym for preview_url_light so
  existing callers continue to work.

Sync pipeline (`automation/scripts/sync_to_postgres.py`): language-aware
discovery that iterates `implementations/{language}/` subdirs, preserves
the legacy flat layout as fallback during transition, reads from
`metadata/{language}/{library}.yaml`, and upserts using the new
three-key constraint. LANGUAGES_METADATA now seeds the languages table
before libraries.

Workflows (`impl-generate`, `impl-merge`, `impl-repair`, `impl-review`):
export `LANGUAGE=python` and thread it through every filesystem + GCS
path. staging and production GCS paths now include the language segment:
gs://anyplot-images/{staging,plots}/{spec}/{language}/{library}/...
`sync-labels.yml` regex updated for the new path depth;
`spec-create.yml` creates empty `python/` subdirs for new specs.

Prompts (`impl-generate-claude.md`, `impl-repair-claude.md`): the
{LANGUAGE} variable is declared and substituted into every path template.

The change is strictly additive for existing data — all backfilled rows
have language_id="python" and preview_url_light pointing at the current
plot.png URLs. GCS objects stay at their current paths until Phase D
regenerates each spec into the new {language}/{library}/plot-{theme}.png
layout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarkusNeusinger

.github/workflows/impl-generate.yml

@@ -106,12 +106,16 @@ jobs:
           DEPS_VAR="DEPS_${LIBRARY}"
           DEPS="${!DEPS_VAR}"
 
+          # Language: only python supported today. Future multi-language work will derive this per spec.
+          LANGUAGE="python"
+
           echo "specification_id=$SPEC_ID" >> $GITHUB_OUTPUT
           echo "library=$LIBRARY" >> $GITHUB_OUTPUT
+          echo "language=$LANGUAGE" >> $GITHUB_OUTPUT
           echo "issue_number=$ISSUE" >> $GITHUB_OUTPUT
           echo "deps=$DEPS" >> $GITHUB_OUTPUT
 
-          echo "::notice::Generating $LIBRARY for $SPEC_ID (issue: ${ISSUE:-none})"
+          echo "::notice::Generating $LANGUAGE/$LIBRARY for $SPEC_ID (issue: ${ISSUE:-none})"
 
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -232,10 +236,11 @@ jobs:
         id: existing
         env:
           SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
+          LANGUAGE: ${{ steps.inputs.outputs.language }}
           LIBRARY: ${{ steps.inputs.outputs.library }}
         run: |
-          METADATA_FILE="plots/${SPEC_ID}/metadata/${LIBRARY}.yaml"
-          IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
+          METADATA_FILE="plots/${SPEC_ID}/metadata/${LANGUAGE}/${LIBRARY}.yaml"
+          IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}.py"
 
           if [ -f "$METADATA_FILE" ] && [ -f "$IMPL_FILE" ]; then
             echo "is_regeneration=true" >> $GITHUB_OUTPUT
@@ -244,13 +249,14 @@ jobs:
             echo "is_regeneration=false" >> $GITHUB_OUTPUT
           fi
 
-      - name: Ensure implementations directory exists
+      - name: Ensure implementation directories exist
         env:
           SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
+          LANGUAGE: ${{ steps.inputs.outputs.language }}
         run: |
-          # Create implementations directory if it doesn't exist (for new specs)
-          mkdir -p "plots/${SPEC_ID}/implementations"
-          echo "::notice::Ensured implementations directory exists"
+          mkdir -p "plots/${SPEC_ID}/implementations/${LANGUAGE}"
+          mkdir -p "plots/${SPEC_ID}/metadata/${LANGUAGE}"
+          echo "::notice::Ensured implementation + metadata directories exist for language '${LANGUAGE}'"
 
       - name: Run Claude Code to generate implementation
         id: claude
@@ -264,6 +270,7 @@ jobs:
             Read `prompts/workflow-prompts/impl-generate-claude.md` and follow those instructions.
 
             Variables for this run:
+            - LANGUAGE: ${{ steps.inputs.outputs.language }}
             - LIBRARY: ${{ steps.inputs.outputs.library }}
             - SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
             - IS_REGENERATION: ${{ steps.existing.outputs.is_regeneration }}
@@ -280,6 +287,7 @@ jobs:
             Read `prompts/workflow-prompts/impl-generate-claude.md` and follow those instructions.
 
             Variables for this run:
+            - LANGUAGE: ${{ steps.inputs.outputs.language }}
             - LIBRARY: ${{ steps.inputs.outputs.library }}
             - SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
             - IS_REGENERATION: ${{ steps.existing.outputs.is_regeneration }}
@@ -291,13 +299,16 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
+          LANGUAGE: ${{ steps.inputs.outputs.language }}
           LIBRARY: ${{ steps.inputs.outputs.library }}
           ISSUE: ${{ steps.issue.outputs.number }}
           BRANCH: ${{ steps.branch.outputs.branch }}
         run: |
+          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
+
           # Save plot files before git operations (they are not committed and would be lost)
-          cp "plots/${SPEC_ID}/implementations/plot.png" "/tmp/plot.png" 2>/dev/null || true
-          cp "plots/${SPEC_ID}/implementations/plot.html" "/tmp/plot.html" 2>/dev/null || true
+          cp "${IMPL_DIR}/plot.png" "/tmp/plot.png" 2>/dev/null || true
+          cp "${IMPL_DIR}/plot.html" "/tmp/plot.html" 2>/dev/null || true
 
           # Configure git auth (Claude's action configured it, but it's gone now)
           git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
@@ -315,11 +326,13 @@ jobs:
           fi
 
           # Restore plot files after git operations
-          cp "/tmp/plot.png" "plots/${SPEC_ID}/implementations/plot.png" 2>/dev/null || true
-          cp "/tmp/plot.html" "plots/${SPEC_ID}/implementations/plot.html" 2>/dev/null || true
+          mkdir -p "${IMPL_DIR}"
+          cp "/tmp/plot.png" "${IMPL_DIR}/plot.png" 2>/dev/null || true
+          cp "/tmp/plot.html" "${IMPL_DIR}/plot.html" 2>/dev/null || true
 
           # Now create metadata file
-          METADATA_DIR="plots/${SPEC_ID}/metadata"
+          METADATA_DIR="plots/${SPEC_ID}/metadata/${LANGUAGE}"
+          mkdir -p "${METADATA_DIR}"
           METADATA_FILE="${METADATA_DIR}/${LIBRARY}.yaml"
           TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
@@ -363,7 +376,7 @@ jobs:
           PREVIEW_HTML="null"
           case "$LIBRARY" in
             plotly|bokeh|altair|highcharts|pygal|letsplot)
-              PREVIEW_HTML="https://storage.googleapis.com/anyplot-images/plots/${SPEC_ID}/${LIBRARY}/plot.html"
+              PREVIEW_HTML="https://storage.googleapis.com/anyplot-images/plots/${SPEC_ID}/${LANGUAGE}/${LIBRARY}/plot.html"
               ;;
           esac
 
@@ -373,6 +386,7 @@ jobs:
           import yaml
           lib = '$LIBRARY'
           spec = '$SPEC_ID'
+          language = '$LANGUAGE'
           ts = '$TIMESTAMP'
           run_id = ${{ github.run_id }}
           issue = int('$ISSUE' or '0')
@@ -382,6 +396,7 @@ jobs:
           metadata_file = '$METADATA_FILE'
           data = {
               'library': lib,
+              'language': language,
               'specification_id': spec,
               'created': ts,
               'updated': ts,
@@ -390,7 +405,7 @@ jobs:
               'issue': issue,
               'python_version': py_ver,
               'library_version': lib_ver,
-              'preview_url': f'https://storage.googleapis.com/anyplot-images/plots/{spec}/{lib}/plot.png',
+              'preview_url': f'https://storage.googleapis.com/anyplot-images/plots/{spec}/{language}/{lib}/plot.png',
               'preview_html': preview_html if preview_html != 'null' else None,
               'quality_score': None,
               'review': {'strengths': [], 'weaknesses': []}
@@ -405,7 +420,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-          IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
+          IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}.py"
 
           # Verify implementation file exists in the repository (Claude should have committed it)
           if ! git ls-files --error-unmatch "$IMPL_FILE" >/dev/null 2>&1; then
@@ -437,11 +452,12 @@ jobs:
       - name: Process plot images
         env:
           SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
+          LANGUAGE: ${{ steps.inputs.outputs.language }}
         run: |
-          IMPL_DIR="plots/${SPEC_ID}/implementations"
+          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
 
           if [ ! -f "$IMPL_DIR/plot.png" ]; then
-            echo "::error::No plot.png found - implementation failed to generate image"
+            echo "::error::No plot.png found at ${IMPL_DIR}/plot.png - implementation failed to generate image"
             exit 1
           fi
 
@@ -466,6 +482,7 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
+          LANGUAGE: ${{ steps.inputs.outputs.language }}
           LIBRARY: ${{ steps.inputs.outputs.library }}
           ISSUE: ${{ steps.issue.outputs.number }}
           BRANCH: ${{ steps.branch.outputs.branch }}
@@ -481,11 +498,11 @@ jobs:
           fi
 
           # Create PR body
-          BODY="## Implementation: \`${SPEC_ID}\` - ${LIBRARY}
+          BODY="## Implementation: \`${SPEC_ID}\` - ${LANGUAGE}/${LIBRARY}
 
-          Implements the **${LIBRARY}** version of \`${SPEC_ID}\`.
+          Implements the **${LANGUAGE}/${LIBRARY}** version of \`${SPEC_ID}\`.
 
-          **File:** \`plots/${SPEC_ID}/implementations/${LIBRARY}.py\`"
+          **File:** \`plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}.py\`"
 
           if [ -n "$ISSUE" ]; then
             BODY="${BODY}
@@ -527,11 +544,12 @@ jobs:
         if: steps.pr.outputs.pr_exists == 'true'
         env:
           SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
+          LANGUAGE: ${{ steps.inputs.outputs.language }}
           LIBRARY: ${{ steps.inputs.outputs.library }}
         run: |
-          IMPL_DIR="plots/${SPEC_ID}/implementations"
-          STAGING_PATH="gs://anyplot-images/staging/${SPEC_ID}/${LIBRARY}"
-          PUBLIC_URL="https://storage.googleapis.com/anyplot-images/staging/${SPEC_ID}/${LIBRARY}"
+          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
+          STAGING_PATH="gs://anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
+          PUBLIC_URL="https://storage.googleapis.com/anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
 
           # Upload all plot images (original + responsive variants)
           if [ -f "$IMPL_DIR/plot.png" ]; then

.github/workflows/impl-merge.yml

@@ -80,23 +80,29 @@ jobs:
           SPEC_ID=$(echo "$BRANCH" | cut -d'/' -f2)
           LIBRARY=$(echo "$BRANCH" | cut -d'/' -f3)
 
+          # Language: only python supported today. If future branches encode language,
+          # parse it from the branch name here.
+          LANGUAGE="python"
+
           echo "specification_id=$SPEC_ID" >> $GITHUB_OUTPUT
           echo "library=$LIBRARY" >> $GITHUB_OUTPUT
+          echo "language=$LANGUAGE" >> $GITHUB_OUTPUT
 
       - name: Validate PR completeness before merge
         if: steps.check.outputs.should_run == 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SPEC_ID: ${{ steps.extract.outputs.specification_id }}
+          LANGUAGE: ${{ steps.extract.outputs.language }}
           LIBRARY: ${{ steps.extract.outputs.library }}
           BRANCH: ${{ steps.check.outputs.branch }}
           PR_NUM: ${{ steps.check.outputs.pr_number }}
         run: |
           # Fetch the PR branch to check its contents
           git fetch origin "$BRANCH"
 
-          IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
-          META_FILE="plots/${SPEC_ID}/metadata/${LIBRARY}.yaml"
+          IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}.py"
+          META_FILE="plots/${SPEC_ID}/metadata/${LANGUAGE}/${LIBRARY}.yaml"
 
           # Check if implementation file exists on the PR branch
           if ! git show "origin/${BRANCH}:${IMPL_FILE}" &>/dev/null; then
@@ -198,10 +204,11 @@ jobs:
         if: steps.check.outputs.should_run == 'true'
         env:
           SPEC_ID: ${{ steps.extract.outputs.specification_id }}
+          LANGUAGE: ${{ steps.extract.outputs.language }}
           LIBRARY: ${{ steps.extract.outputs.library }}
         run: |
-          STAGING="gs://anyplot-images/staging/${SPEC_ID}/${LIBRARY}"
-          PRODUCTION="gs://anyplot-images/plots/${SPEC_ID}/${LIBRARY}"
+          STAGING="gs://anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
+          PRODUCTION="gs://anyplot-images/plots/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
 
           # Copy from staging to production
           gsutil -m -h "Cache-Control:public, max-age=604800" cp -r "${STAGING}/*" "${PRODUCTION}/" 2>/dev/null || echo "No staging files to promote"
@@ -235,6 +242,7 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ISSUE: ${{ steps.issue.outputs.number }}
+          LANGUAGE: ${{ steps.extract.outputs.language }}
           LIBRARY: ${{ steps.extract.outputs.library }}
           SPEC_ID: ${{ steps.extract.outputs.specification_id }}
           PR_NUM: ${{ steps.check.outputs.pr_number }}
@@ -253,7 +261,7 @@ jobs:
 
           BODY="${BODY}
 
-          **Preview:** [View image](https://storage.googleapis.com/anyplot-images/plots/${SPEC_ID}/${LIBRARY}/plot.png)
+          **Preview:** [View image](https://storage.googleapis.com/anyplot-images/plots/${SPEC_ID}/${LANGUAGE}/${LIBRARY}/plot.png)
 
           ---
           :robot: *[impl-merge](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"

.github/workflows/impl-repair.yml

@@ -121,6 +121,7 @@ jobs:
             Read `prompts/workflow-prompts/impl-repair-claude.md` and follow those instructions.
 
             Variables for this run:
+            - LANGUAGE: python
             - LIBRARY: ${{ inputs.library }}
             - SPEC_ID: ${{ inputs.specification_id }}
             - ATTEMPT: ${{ inputs.attempt }}
@@ -139,6 +140,7 @@ jobs:
             Read `prompts/workflow-prompts/impl-repair-claude.md` and follow those instructions.
 
             Variables for this run:
+            - LANGUAGE: python
             - LIBRARY: ${{ inputs.library }}
             - SPEC_ID: ${{ inputs.specification_id }}
             - ATTEMPT: ${{ inputs.attempt }}
@@ -149,8 +151,9 @@ jobs:
         env:
           SPEC_ID: ${{ inputs.specification_id }}
           LIBRARY: ${{ inputs.library }}
+          LANGUAGE: python
         run: |
-          IMPL_DIR="plots/${SPEC_ID}/implementations"
+          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
 
           if [ ! -f "$IMPL_DIR/plot.png" ]; then
             echo "::warning::No plot.png found after repair"
@@ -186,9 +189,10 @@ jobs:
         env:
           SPEC_ID: ${{ inputs.specification_id }}
           LIBRARY: ${{ inputs.library }}
+          LANGUAGE: python
         run: |
-          IMPL_DIR="plots/${SPEC_ID}/implementations"
-          STAGING_PATH="gs://anyplot-images/staging/${SPEC_ID}/${LIBRARY}"
+          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
+          STAGING_PATH="gs://anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
 
           # Upload all plot images (original + responsive variants)
           if [ -f "$IMPL_DIR/plot.png" ]; then

.github/workflows/impl-review.yml

@@ -102,9 +102,10 @@ jobs:
         env:
           SPEC_ID: ${{ steps.pr.outputs.specification_id }}
           LIBRARY: ${{ steps.pr.outputs.library }}
+          LANGUAGE: python
         run: |
           mkdir -p plot_images
-          gsutil -m cp "gs://anyplot-images/staging/${SPEC_ID}/${LIBRARY}/*" plot_images/ 2>/dev/null || true
+          gsutil -m cp "gs://anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}/*" plot_images/ 2>/dev/null || true
           ls -la plot_images/
 
       - name: Verify plot image exists
@@ -255,11 +256,12 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SPEC_ID: ${{ steps.pr.outputs.specification_id }}
           LIBRARY: ${{ steps.pr.outputs.library }}
+          LANGUAGE: python
           SCORE: ${{ steps.score.outputs.score }}
           BRANCH: ${{ steps.pr.outputs.branch }}
         run: |
-          METADATA_FILE="plots/${SPEC_ID}/metadata/${LIBRARY}.yaml"
-          IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
+          METADATA_FILE="plots/${SPEC_ID}/metadata/${LANGUAGE}/${LIBRARY}.yaml"
+          IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}.py"
 
           # Configure git auth and checkout the PR branch
           git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
@@ -462,6 +464,7 @@ jobs:
           PR_NUM: ${{ steps.pr.outputs.pr_number }}
           SPEC_ID: ${{ steps.pr.outputs.specification_id }}
           LIBRARY: ${{ steps.pr.outputs.library }}
+          LANGUAGE: python
           SCORE: ${{ steps.score.outputs.score }}
           ATTEMPT: ${{ steps.attempts.outputs.display }}
           ATTEMPT_COUNT: ${{ steps.attempts.outputs.count }}
@@ -542,8 +545,8 @@ jobs:
               gh pr close "$PR_NUM"
 
               # Remove old implementation from main if it exists
-              IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
-              META_FILE="plots/${SPEC_ID}/metadata/${LIBRARY}.yaml"
+              IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}.py"
+              META_FILE="plots/${SPEC_ID}/metadata/${LANGUAGE}/${LIBRARY}.yaml"
 
               git fetch origin main
               if git show origin/main:"$IMPL_FILE" &>/dev/null; then

.github/workflows/report-validate.yml

@@ -103,7 +103,8 @@ jobs:
 
             4. **If implementation issue, validate the library exists:**
                ```bash
-               ls plots/{spec_id}/implementations/{library}.py
+               # Language is python unless the report explicitly references another language
+               ls plots/{spec_id}/implementations/python/{library}.py
                ```
                If NOT found:
                - Post comment: "Implementation `{library}` not found for `{spec_id}`."
@@ -114,8 +115,8 @@ jobs:
             5. **Read relevant files:**
                - `plots/{spec_id}/specification.md`
                - `plots/{spec_id}/specification.yaml`
-               - `plots/{spec_id}/implementations/{library}.py` (if impl issue)
-               - `plots/{spec_id}/metadata/{library}.yaml` (if impl issue)
+               - `plots/{spec_id}/implementations/python/{library}.py` (if impl issue)
+               - `plots/{spec_id}/metadata/python/{library}.yaml` (if impl issue)
                - Optionally: read other files in `plots/{spec_id}/` if needed for analysis
 
             6. **Post structured analysis comment** following the format in the prompt file.

.github/workflows/spec-create.yml

@@ -135,8 +135,8 @@ jobs:
                  - `issue`: ${{ github.event.issue.number }}
                  - `suggested`: ${{ github.event.issue.user.login }}
                  - `tags`: Follow tagging-system.md guide (4 dimensions: plot_type, data_type, domain, features)
-               - Create empty folder: `plots/{specification-id}/implementations/`
-               - Create empty folder: `plots/{specification-id}/metadata/`
+               - Create empty folder: `plots/{specification-id}/implementations/python/`
+               - Create empty folder: `plots/{specification-id}/metadata/python/`
 
             8. **Commit and push:**
                ```bash
@@ -239,8 +239,8 @@ jobs:
                  - `issue`: ${{ github.event.issue.number }}
                  - `suggested`: ${{ github.event.issue.user.login }}
                  - `tags`: Follow tagging-system.md guide (4 dimensions: plot_type, data_type, domain, features)
-               - Create empty folder: `plots/{specification-id}/implementations/`
-               - Create empty folder: `plots/{specification-id}/metadata/`
+               - Create empty folder: `plots/{specification-id}/implementations/python/`
+               - Create empty folder: `plots/{specification-id}/metadata/python/`
 
             8. **Commit and push:**
                ```bash