Rework summary handling and include AI output in PR bodies

- automated_updates_data.json: format empty array with newline for
  cleaner diffs when entries are added
- improve-docs.js: AI now edits automated_updates_data.json directly
  (adds to last_improved_things) instead of writing improvement_summary.txt;
  script reads back the new entry and writes summary to /tmp/ai_summary.txt
- update-docs-from-commits.js: prompt now asks for a brief summary;
  script writes AI output to /tmp/ai_summary.txt and commit log to
  /tmp/commit_log.txt; uses writeDataFile helper for consistent formatting
- improve-docs.yml: reads AI summary as step output and includes it in
  the PR body ('The AI agent summary is:')
- update-docs-from-commits.yml: reads AI summary + commit log as step
  outputs and includes both in the PR body
- .gitignore: remove unused improvement_summary.txt entry

Co-authored-by: Florian Rival <4ian@users.noreply.github.com>

Author: cursoragent

.github/workflows/improve-docs.yml

@@ -52,11 +52,22 @@ jobs:
 
       # ── Run the improvement script ────────────────────────────────────
       - name: Improve documentation
+        id: improve
         env:
           AI_PROVIDER: "claude" # Change to "codex" to use Codex
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-        run: node scripts/improve-docs.js
+        run: |
+          node scripts/improve-docs.js
+
+          # Pass the AI summary to subsequent steps
+          if [ -f /tmp/ai_summary.txt ]; then
+            {
+              echo "summary<<SUMMARY_EOF"
+              cat /tmp/ai_summary.txt
+              echo "SUMMARY_EOF"
+            } >> "$GITHUB_OUTPUT"
+          fi
 
       # ── Create Pull Request ───────────────────────────────────────────
       - name: Create Pull Request
@@ -71,6 +82,9 @@ jobs:
             An AI coding agent inspected the [GDevelop](https://github.com/4ian/GDevelop) codebase
             and the existing documentation, then chose an aspect to improve.
 
+            The AI agent summary is:
+            > ${{ steps.improve.outputs.summary }}
+
             The updated `automated_updates_data.json` tracks what was improved so future
             runs will pick a different area.
 

.github/workflows/update-docs-from-commits.yml

@@ -52,11 +52,29 @@ jobs:
 
       # ── Run the update script ─────────────────────────────────────────
       - name: Update documentation from recent commits
+        id: update
         env:
           AI_PROVIDER: "claude" # Change to "codex" to use Codex
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-        run: node scripts/update-docs-from-commits.js
+        run: |
+          node scripts/update-docs-from-commits.js
+
+          # Pass the AI summary and commit log to subsequent steps
+          if [ -f /tmp/ai_summary.txt ]; then
+            {
+              echo "summary<<SUMMARY_EOF"
+              cat /tmp/ai_summary.txt
+              echo "SUMMARY_EOF"
+            } >> "$GITHUB_OUTPUT"
+          fi
+          if [ -f /tmp/commit_log.txt ]; then
+            {
+              echo "commits<<COMMITS_EOF"
+              cat /tmp/commit_log.txt
+              echo "COMMITS_EOF"
+            } >> "$GITHUB_OUTPUT"
+          fi
 
       # ── Create Pull Request ───────────────────────────────────────────
       - name: Create Pull Request
@@ -71,6 +89,14 @@ jobs:
             An AI coding agent analysed recent commits in [4ian/GDevelop](https://github.com/4ian/GDevelop)
             and updated the documentation to reflect user-facing changes.
 
+            ### GDevelop commits covered
+            ```
+            ${{ steps.update.outputs.commits }}
+            ```
+
+            ### The AI agent summary is:
+            ${{ steps.update.outputs.summary }}
+
             **Please review the changes carefully before merging.**
           base: main
           branch: auto/update-docs-from-commits

.gitignore

@@ -1,5 +1,4 @@
 dokuwiki2wikijs/__pycache__
 .DS_Store
 site
-scripts/node_modules/
-improvement_summary.txt
+scripts/node_modules/

automated_updates_data.json

@@ -1,4 +1,6 @@
 {
   "last_automated_updates_commit": null,
-  "last_improved_things": []
+  "last_improved_things": [
+
+  ]
 }

scripts/improve-docs.js

@@ -9,8 +9,9 @@
  * DIFFERENT aspect of the documentation (its own choice of scope — a folder,
  * feature, topic, etc.).
  *
- * After the AI finishes, the script updates automated_updates_data.json so
- * future runs don't repeat the same improvements.
+ * The AI agent directly adds a new entry to the "last_improved_things" array
+ * inside automated_updates_data.json, so the change is tracked in the same
+ * commit as the documentation edits.
  */
 
 const { execSync } = require("child_process");
@@ -24,7 +25,7 @@ const GDEVELOP_REPO = "https://github.com/4ian/GDevelop.git";
 const GDEVELOP_DIR = process.env.GDEVELOP_DIR || "/tmp/GDevelop";
 const REPO_ROOT = path.resolve(__dirname, "..");
 const DATA_FILE = path.join(REPO_ROOT, "automated_updates_data.json");
-const SUMMARY_FILE = path.join(REPO_ROOT, "improvement_summary.txt");
+const SUMMARY_OUT = "/tmp/ai_summary.txt";
 
 // AI provider — switch by changing this value (or set AI_PROVIDER env var).
 // Supported values: "claude" | "codex"
@@ -37,6 +38,14 @@ function run(cmd, opts = {}) {
   return execSync(cmd, { encoding: "utf8", ...opts }).trim();
 }
 
+function writeDataFile(data) {
+  let json = JSON.stringify(data, null, 2);
+  // Keep empty arrays on separate lines so future additions produce clean diffs
+  json = json.replace(/"last_improved_things": \[\s*\]/g,
+    '"last_improved_things": [\n\n  ]');
+  fs.writeFileSync(DATA_FILE, json + "\n");
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -48,6 +57,7 @@ function main() {
   }
 
   const alreadyImproved = data.last_improved_things || [];
+  const previousCount = alreadyImproved.length;
 
   // 2. Clone / update GDevelop
   if (!fs.existsSync(path.join(GDEVELOP_DIR, ".git"))) {
@@ -71,35 +81,50 @@ function main() {
     { cwd: REPO_ROOT }
   );
 
-  // 4. Clean up any leftover summary file
-  if (fs.existsSync(SUMMARY_FILE)) fs.unlinkSync(SUMMARY_FILE);
-
-  // 5. Build prompt
+  // 4. Build prompt
   const prompt = buildPrompt(alreadyImproved, docTree);
 
   const promptFile = "/tmp/doc_improve_prompt.txt";
   fs.writeFileSync(promptFile, prompt);
   console.log(`Prompt written to ${promptFile} (${prompt.length} chars)`);
 
-  // 6. Invoke AI agent
+  // 5. Invoke AI agent
   console.log(`\nInvoking AI agent (${AI_PROVIDER})…\n`);
-  invokeAI(promptFile, REPO_ROOT);
-
-  // 7. Read back the improvement summary the AI wrote
-  let summary = "(no summary provided)";
-  if (fs.existsSync(SUMMARY_FILE)) {
-    summary = fs.readFileSync(SUMMARY_FILE, "utf8").trim();
-    // Clean up temp file — we don't want it committed
-    fs.unlinkSync(SUMMARY_FILE);
+  const aiOutput = invokeAI(promptFile, REPO_ROOT);
+
+  // 6. Read back the data file to find what the AI added
+  let updatedData = data;
+  try {
+    updatedData = JSON.parse(fs.readFileSync(DATA_FILE, "utf8"));
+  } catch (err) {
+    console.error("Warning: could not re-read automated_updates_data.json:", err.message);
+  }
+
+  const updatedList = updatedData.last_improved_things || [];
+  let summary;
+
+  if (updatedList.length > previousCount) {
+    // The AI added one or more entries — take the last one
+    const newEntry = updatedList[updatedList.length - 1];
+    summary = newEntry.summary || "(no summary in new entry)";
+    console.log(`\nAI added improvement entry: [${newEntry.date}] ${summary}`);
+  } else {
+    // AI didn't update the file — add a fallback entry ourselves
+    summary = aiOutput
+      ? aiOutput.split("\n").filter(Boolean).slice(0, 3).join(" ").substring(0, 200)
+      : "(no summary provided)";
+    updatedData.last_improved_things = updatedList;
+    updatedData.last_improved_things.push({
+      date: new Date().toISOString().split("T")[0],
+      summary,
+    });
+    writeDataFile(updatedData);
+    console.log(`\nFallback: script added improvement entry: ${summary}`);
   }
 
-  // 8. Update tracking data
-  data.last_improved_things.push({
-    date: new Date().toISOString().split("T")[0],
-    summary,
-  });
-  fs.writeFileSync(DATA_FILE, JSON.stringify(data, null, 2) + "\n");
-  console.log(`\nImprovement recorded: ${summary}`);
+  // 7. Write summary for the workflow to pick up
+  fs.writeFileSync(SUMMARY_OUT, summary);
+  console.log(`Summary written to ${SUMMARY_OUT}`);
 }
 
 // ---------------------------------------------------------------------------
@@ -111,6 +136,8 @@ function buildPrompt(alreadyImproved, docTree) {
       ? alreadyImproved.map((e) => `  • [${e.date}] ${e.summary}`).join("\n")
       : "  (none yet — this is the first run)";
 
+  const today = new Date().toISOString().split("T")[0];
+
   return `You are an expert technical writer improving GDevelop's documentation.
 
 DOCUMENTATION LOCATION
@@ -147,14 +174,23 @@ IMPORTANT CONSTRAINTS
   – Every "reference.md" file under docs/gdevelop5/all-features/*/reference.md
   – docs/gdevelop5/all-features/expressions-reference.md
 • NEVER create new files unless absolutely necessary.
-• NEVER edit files outside docs/gdevelop5/.
+• NEVER edit files outside docs/gdevelop5/ (except automated_updates_data.json as described below).
 • Do NOT touch images or binary files.
 
 WHEN YOU ARE DONE
 -----------------
-Create a file called "improvement_summary.txt" in ${REPO_ROOT}/ containing
-a single line that describes what you improved.
-Example: "Improved getting_started/index.md — added clearer first-project walkthrough steps"
+Edit the file "automated_updates_data.json" in ${REPO_ROOT}/ and add a new
+entry at the END of the "last_improved_things" array with this format:
+
+  { "date": "${today}", "summary": "<one-line description of what you improved>" }
+
+For example, the file might look like:
+  {
+    "last_automated_updates_commit": null,
+    "last_improved_things": [
+      { "date": "${today}", "summary": "Improved objects/sprite/index.md — clarified animation looping behaviour" }
+    ]
+  }
 
 Make your changes now.`;
 }
@@ -178,11 +214,11 @@ function invokeAI(promptFile, cwd) {
     throw new Error(`Unknown AI_PROVIDER: "${AI_PROVIDER}". Use "claude" or "codex".`);
   }
 
-  // Run with stdout/stderr piped so we can capture and log the full output.
   const output = execSync(cmd, { ...opts, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
   console.log("── AI agent output ─────────────────────────────────────────");
   console.log(output);
   console.log("── End of AI agent output ──────────────────────────────────");
+  return output;
 }
 
 // ---------------------------------------------------------------------------

scripts/update-docs-from-commits.js

@@ -24,6 +24,8 @@ const REPO_ROOT = path.resolve(__dirname, "..");
 const DATA_FILE = path.join(REPO_ROOT, "automated_updates_data.json");
 const DEFAULT_COMMIT_COUNT = 5;
 const MAX_DIFF_BYTES = 80000; // Truncate diffs to keep prompt manageable
+const SUMMARY_OUT = "/tmp/ai_summary.txt";
+const COMMITS_OUT = "/tmp/commit_log.txt";
 
 // AI provider — switch by changing this value (or set AI_PROVIDER env var).
 // Supported values: "claude" | "codex"
@@ -44,6 +46,14 @@ function runSafe(cmd, opts = {}) {
   }
 }
 
+function writeDataFile(data) {
+  let json = JSON.stringify(data, null, 2);
+  // Keep empty arrays on separate lines so future additions produce clean diffs
+  json = json.replace(/"last_improved_things": \[\s*\]/g,
+    '"last_improved_things": [\n\n  ]');
+  fs.writeFileSync(DATA_FILE, json + "\n");
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -61,7 +71,6 @@ function main() {
       `git clone --filter=blob:none --no-checkout ${GDEVELOP_REPO} ${GDEVELOP_DIR}`,
       { stdio: "inherit" }
     );
-    // Only checkout the history (we need commits, not a full working tree initially)
     execSync("git checkout", { cwd: GDEVELOP_DIR, stdio: "inherit" });
   } else {
     console.log("Updating existing GDevelop clone…");
@@ -76,7 +85,6 @@ function main() {
   let commitRange = null;
 
   if (lastCommit) {
-    // Verify the commit exists in our (possibly shallow) clone
     const commitExists = (() => {
       try {
         execSync(`git cat-file -e ${lastCommit}`, {
@@ -106,19 +114,19 @@ function main() {
 
   if (!commitLog) {
     console.log("No new commits found. Nothing to do.");
-    // Still update the pointer so we don't re-scan next time
     data.last_automated_updates_commit = run("git rev-parse HEAD", {
       cwd: GDEVELOP_DIR,
     });
-    fs.writeFileSync(DATA_FILE, JSON.stringify(data, null, 2) + "\n");
+    writeDataFile(data);
+    fs.writeFileSync(SUMMARY_OUT, "(no new commits to process)");
+    fs.writeFileSync(COMMITS_OUT, "(none)");
     return;
   }
 
   const diffStat = runSafe(`git diff ${commitRange} --stat`, {
     cwd: GDEVELOP_DIR,
   });
 
-  // Get meaningful code diffs (skip binary, tests, and overly large files)
   const diffContent = runSafe(
     `git diff ${commitRange} -- '*.js' '*.jsx' '*.ts' '*.tsx' '*.json' '*.md' `
     + `':!*/__tests__/*' ':!*/node_modules/*' ':!*/fixtures/*' `
@@ -141,12 +149,21 @@ function main() {
 
   // 7. Invoke AI agent
   console.log(`\nInvoking AI agent (${AI_PROVIDER})…\n`);
-  invokeAI(promptFile, REPO_ROOT);
+  const aiOutput = invokeAI(promptFile, REPO_ROOT);
 
   // 8. Update tracking data
   data.last_automated_updates_commit = latestCommit;
-  fs.writeFileSync(DATA_FILE, JSON.stringify(data, null, 2) + "\n");
+  writeDataFile(data);
   console.log(`\nTracking data updated — latest commit: ${latestCommit}`);
+
+  // 9. Write summary + commit log for the workflow to pick up
+  const summary = aiOutput
+    ? aiOutput.trim()
+    : "(AI agent produced no output)";
+  fs.writeFileSync(SUMMARY_OUT, summary);
+  fs.writeFileSync(COMMITS_OUT, commitLog);
+  console.log(`Summary written to ${SUMMARY_OUT}`);
+  console.log(`Commit log written to ${COMMITS_OUT}`);
 }
 
 // ---------------------------------------------------------------------------
@@ -194,6 +211,12 @@ IMPORTANT CONSTRAINTS
 • Do NOT touch images or binary files.
 • If no documentation updates are needed, do nothing.
 
+WHEN YOU ARE DONE
+-----------------
+Output a brief summary (2-3 lines) of the documentation changes you made,
+or state that no changes were needed. This summary will be included in the
+pull request description.
+
 Make your changes now.`;
 }
 
@@ -216,11 +239,11 @@ function invokeAI(promptFile, cwd) {
     throw new Error(`Unknown AI_PROVIDER: "${AI_PROVIDER}". Use "claude" or "codex".`);
   }
 
-  // Run with stdout/stderr piped so we can capture and log the full output.
   const output = execSync(cmd, { ...opts, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
   console.log("── AI agent output ─────────────────────────────────────────");
   console.log(output);
   console.log("── End of AI agent output ──────────────────────────────────");
+  return output;
 }
 
 // ---------------------------------------------------------------------------