feat: embed agent-ready docs and AGENTS.md in framework distributions

.github/scripts/deploy-appstarter

@@ -29,6 +29,9 @@ done
 # Copy repo-specific files
 cp -Rf ${SOURCE}/admin/starter/. ./
 
+# Reuse the framework AGENTS.md at the project root
+cp -Rf ${SOURCE}/admin/framework/AGENTS.md ./AGENTS.md
+
 # Commit the changes
 git add .
 git commit -m "Release ${RELEASE}"

.github/workflows/deploy-distributables.yml

@@ -66,6 +66,30 @@ jobs:
       - name: Chmod
         run: chmod +x ./source/.github/scripts/deploy-framework
 
+      - name: Setup Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3861523e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+
+      - name: Install Sphinx
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r ./source/user_guide_src/requirements.txt
+
+      # Convert the User Guide to Markdown so coding agents get
+      # version-matched docs embedded in system/Docs
+      - name: Build Markdown Docs for agents
+        run: sphinx-build -b markdown -D exclude_patterns=_static/*,changelogs/*,images/* source build/markdown
+        working-directory: ./source/user_guide_src
+
+      - name: Embed Markdown Docs into system/Docs
+        run: |
+          mkdir -p ./source/system/Docs
+          cp -Rf ./source/user_guide_src/build/markdown/. ./source/system/Docs/
+
+      - name: Verify embedded docs
+        run: test -f ./source/system/Docs/index.md
+
       - name: Deploy
         env:
           PUSH_TOKEN: ${{ secrets.ACCESS_TOKEN }}

admin/framework/AGENTS.md

@@ -0,0 +1,7 @@
+<!-- BEGIN:codeigniter-agent-rules -->
+
+## This is NOT the CodeIgniter you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `system/Docs/` (framework distribution) or `vendor/codeigniter4/framework/system/Docs/` (app starter installed via Composer) before writing any code. Heed deprecation notices.
+
+<!-- END:codeigniter-agent-rules -->

user_guide_src/requirements.txt

@@ -1,4 +1,5 @@
 sphinx>=8.0.0,<9.0.0
+sphinx-markdown-builder>=0.6.0
 sphinxcontrib-phpdomain>=0.11.0
 docutils>=0.19
 sphinx-rtd-theme>=3.0.0