Add AGENTS.md and GH action

Author: johnsamuelwrites

.github/workflows/docs-ci.yml

@@ -0,0 +1,46 @@
+name: Docs CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate-test-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest PyYAML multilingualprogramming
+
+      - name: Validate multilingual docs metadata
+        run: python scripts/validate_multilingual_docs.py --strict-freshness
+
+      - name: Run docs tests
+        run: python -m pytest _tests -q
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build Jekyll site
+        run: bundle exec jekyll build --baseurl "/docs"
+
+      - name: Check Pages artifact
+        run: python scripts/check_pages_artifact.py --site-dir _site --base-path /docs

.github/workflows/docs-deploy-pages.yml

@@ -0,0 +1,75 @@
+name: Docs Deploy Pages
+
+on:
+  workflow_run:
+    workflows:
+      - Docs CI
+    types:
+      - completed
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install PyYAML multilingualprogramming
+
+      - name: Validate multilingual docs metadata
+        run: python scripts/validate_multilingual_docs.py --strict-freshness
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build Jekyll site
+        run: bundle exec jekyll build --baseurl "/docs"
+
+      - name: Check Pages artifact
+        run: python scripts/check_pages_artifact.py --site-dir _site --base-path /docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md
+
+Repository guidance for LLM agents working in `docs/`.
+
+## Scope
+
+- This repository contains the documentation site for the `multilingualprogramming` project.
+- The public site is built with Jekyll from the top-level site files (`index.md`, `_layouts/`, `_includes/`, `assets/`, `_config.yml`).
+- The structured multilingual source of truth lives under `docs/` and currently supports English (`en`) and French (`fr`).
+
+## Primary Goal
+
+Help users write, explain, or update programs for the `multilingualprogramming` language using the documentation in this repository.
+
+For now, optimize for:
+
+- English code and explanations
+- French code and explanations
+- EN/FR documentation parity when editing docs assets
+
+## Source Of Truth
+
+When answering language or API questions, prefer these locations in order:
+
+1. `docs/content/en/` and `docs/content/fr/` for authored documentation
+2. `docs/snippets/<snippet_id>/en.code` and `docs/snippets/<snippet_id>/fr.code` for runnable examples
+3. `docs/routing/*.routes.yml` and `docs/i18n/*/ui.yml` for localized paths and UI labels
+4. Top-level Jekyll pages only when you need to understand the published site shell
+
+Do not invent syntax if the docs or snippets already show it.
+
+## Programming Guidance
+
+When a user asks for code in this language:
+
+- Pick the requested locale. If unspecified, default to English unless the user writes in French.
+- Keep one lexical style per file. Do not mix French and English keywords in the same example unless the user asks for comparison.
+- Prefer examples that match documented syntax from the repo.
+- For French examples, use documented forms such as `soit`, `afficher`, `si`, `sinon`, `pour`, `dans`, `fonction`, `retourner`, `classe`, `importer`.
+- For English examples, use documented forms such as `let`, `print`, `if`, `else`, `for`, `in`, `function`, `return`, `class`, `import`.
+- When helpful, provide parallel EN and FR versions of the same program.
+
+## Docs Editing Rules
+
+If you modify multilingual docs content:
+
+- Keep `page_id` identical across locales.
+- Keep `source_hash` synchronized from the English source to the French translation.
+- Keep `path_segments` localized per language.
+- Ensure every referenced `{{snippet:<id>}}` has both `en.code` and `fr.code`.
+- Do not add inline runnable Python blocks inside `docs/content/`; use snippet tokens instead.
+
+## Validation Commands
+
+Run these when your changes touch docs structure, snippets, or CI:
+
+```powershell
+python scripts/validate_multilingual_docs.py --strict-freshness
+python -m pytest _tests -q
+bundle exec jekyll build
+python scripts/check_pages_artifact.py --site-dir _site --base-path /docs
+```
+
+## CI Files
+
+- `.github/workflows/docs-ci.yml` validates docs metadata, runs tests, and builds the site.
+- `.github/workflows/docs-deploy-pages.yml` rebuilds and deploys the site to GitHub Pages after successful CI on `main`.
+
+## Known Constraint
+
+The `_tests/` suite exercises docs examples through the PyPI package `multilingualprogramming`.
+Install it with `pip install multilingualprogramming`.
+If that package is not installed in the current environment, those tests should be skipped rather than failing at import time.

README.md

@@ -32,9 +32,16 @@ This repository contains the Jekyll site source for the documentation portal, in
 
 Prerequisites:
 
+- Python 3.x
 - Ruby 3.x
 - Bundler
 
+Install the Python package used by the docs tests:
+
+```bash
+pip install multilingualprogramming
+```
+
 Install dependencies:
 
 ```bash

_tests/test_code_blocks.py

@@ -7,6 +7,7 @@
 Run buttons (Pyodide client-side).
 
 Run locally (requires multilingualprogramming installed):
+    pip install multilingualprogramming
     pytest _tests/ -v
 
 Each code block becomes its own parametrized test case, identified by
@@ -20,7 +21,10 @@
 
 import pytest
 
-from multilingualprogramming.codegen.executor import ProgramExecutor
+try:
+    from multilingualprogramming.codegen.executor import ProgramExecutor
+except ModuleNotFoundError:
+    ProgramExecutor = None
 
 # ---------------------------------------------------------------------------
 # Configuration — language tags that are not executable multilingual source.
@@ -100,7 +104,7 @@ def _collect_blocks():
 # Test
 # ---------------------------------------------------------------------------
 
-@pytest.mark.parametrize('code', _collect_blocks())
+@pytest.mark.parametrize('code', _collect_blocks() if ProgramExecutor is not None else [])
 def test_block(code):
     """
     Each executable code block in the docs must execute without errors
@@ -111,3 +115,13 @@ def test_block(code):
         f'ProgramExecutor reported failure:\n' +
         '\n'.join(result.errors or ['(no error details)'])
     )
+
+
+def test_program_executor_dependency_available():
+    """
+    Make dependency absence an explicit skip instead of a collection-time error.
+    """
+    if ProgramExecutor is None:
+        pytest.skip(
+            "Install multilingualprogramming from PyPI with 'pip install multilingualprogramming' to run docs code-block execution tests."
+        )