Preserve language docs and handle newer templates

Author: Frotty

src/main/kotlin/file/SetupApp.kt

@@ -936,6 +936,17 @@ object SetupApp {
         if (markerLine == AGENTS_TEMPLATE_MARKER) {
             return null
         }
+        if (markerLine != null) {
+            val markerVersion = markerLine
+                .removePrefix(AGENTS_TEMPLATE_MARKER_PREFIX)
+                .removeSuffix("-->")
+                .trim()
+            // Template versions are ISO dates, so lexical ordering is chronological. A newer
+            // downloaded template is valid even when this older Grill binary cannot recognize it.
+            if (markerVersion > AGENTS_TEMPLATE_VERSION) {
+                return null
+            }
+        }
         if (markerLine != null) {
             return "AGENTS.md was generated from an older WurstSetup template ($markerLine). Consider refreshing it from templates/AGENTS.md and re-applying project-local notes."
         }

src/main/kotlin/global/InstallationManager.kt

@@ -9,6 +9,8 @@ import net.NetStatus
 import java.nio.file.Files
 import java.nio.file.Path
 import java.nio.file.Paths
+import java.nio.file.StandardCopyOption
+import java.util.jar.JarFile
 import java.util.regex.Pattern
 
 
@@ -19,6 +21,7 @@ object InstallationManager {
     private val log = KotlinLogging.logger {}
     private const val FOLDER_PATH = ".wurst"
     private const val COMPILER_FILE_NAME = "wurstscript.jar"
+    private const val LANGUAGE_AGENT_DOC_ENTRY = "agent-docs/WURST_LANGUAGE.md"
     private const val GRILL_JAR_NAME = "grill.jar"
     private const val LEGACY_GRILL_JAR_NAME = "WurstSetup.jar"
 
@@ -49,6 +52,7 @@ object InstallationManager {
         log.info("verifyInstallation: detectedCompilerJar=$detectedCompilerJar exists=${detectedCompilerJar?.let { Files.exists(it) }}")
         if (detectedCompilerJar != null) {
             log.info("Found installation at $detectedCompilerJar")
+            ensureCompilerAgentDocs(detectedCompilerJar)
             status = InstallationStatus.INSTALLED_UNKNOWN
             try {
                 if (!Files.isWritable(detectedCompilerJar)) {
@@ -94,9 +98,11 @@ object InstallationManager {
             log.info("\t📦 Extracting..")
 			ZipArchiveExtractor.extractArchive(it, installDir)
 			Files.delete(it)
-            if (detectCompilerJar() == null) {
+            val compilerJar = detectCompilerJar()
+            if (compilerJar == null) {
                 log.error("❌ Compiler not found after extraction.")
             } else {
+                ensureCompilerAgentDocs(compilerJar)
                 if (isFreshInstall) { wurstConfig = WurstConfigData() }
                 ensureGrillJarInstalled()
                 setLaunchersExecutable()
@@ -193,6 +199,25 @@ object InstallationManager {
         }
     }
 
+    private fun ensureCompilerAgentDocs(compilerJar: Path) {
+        try {
+            JarFile(compilerJar.toFile()).use { jar ->
+                val entry = jar.getJarEntry(LANGUAGE_AGENT_DOC_ENTRY) ?: return
+                val docsDir = compilerDir.resolve("agent-docs")
+                Files.createDirectories(docsDir)
+                jar.getInputStream(entry).use { input ->
+                    Files.copy(
+                        input,
+                        docsDir.resolve("WURST_LANGUAGE.md"),
+                        StandardCopyOption.REPLACE_EXISTING
+                    )
+                }
+            }
+        } catch (e: Exception) {
+            log.warn("Could not extract compiler agent docs: ${e.message}")
+        }
+    }
+
     private fun resolveOwnJar(): Path? {
         return try {
             val url = InstallationManager::class.java.protectionDomain.codeSource.location

src/test/kotlin/AgentsTemplateTests.kt

@@ -1,3 +1,4 @@
+import file.SetupApp
 import org.testng.Assert
 import org.testng.annotations.Test
 import java.nio.file.Files
@@ -26,4 +27,11 @@ class AgentsTemplateTests {
         Assert.assertTrue(localIndex >= 0, "Missing compiler-matched local language reference")
         Assert.assertTrue(onlineIndex > localIndex, "Online manual must remain a fallback after the local reference")
     }
+
+    @Test
+    fun testNewerTemplateDoesNotLookStaleToOlderGrill() {
+        val newerMarked = "<!-- WURST_AGENTS_TEMPLATE_VERSION: 2099-01-01 -->\n# AGENTS.md\n"
+
+        Assert.assertNull(SetupApp.agentsTemplateWarning(newerMarked))
+    }
 }