Created AGENTS.md file

Author: eduardodoria

editor/Exporter.cpp

@@ -104,6 +104,10 @@ fs::path editor::Exporter::getExportProjectRoot() const {
     return config.targetDir / "project";
 }
 
+bool editor::Exporter::shouldSkipExportSupportFile(const fs::path& relativePath) {
+    return relativePath == "CMakeLists.txt" || relativePath.filename() == "AGENTS.md";
+}
+
 bool editor::Exporter::checkTargetDir() {
     setProgress("Checking target directory...", 0.0f);
 
@@ -295,12 +299,21 @@ bool editor::Exporter::copyGenerated() {
     // Also copy scene_scripts.cpp
     fs::path sceneScriptsSrc = project->getProjectInternalPath() / "scene_scripts.cpp";
     if (fs::exists(sceneScriptsSrc, ec)) {
-        fs::copy_file(sceneScriptsSrc, generatedDst / "scene_scripts.cpp",
-                      fs::copy_options::overwrite_existing, ec);
-        if (ec) {
-            setError("Failed to copy scene_scripts.cpp: " + ec.message());
+        std::ifstream ifs(sceneScriptsSrc, std::ios::in | std::ios::binary);
+        if (!ifs) {
+            setError("Failed to read generated scene_scripts.cpp");
             return false;
         }
+
+        std::string content((std::istreambuf_iterator<char>(ifs)), std::istreambuf_iterator<char>());
+        const std::string editorOnlyComment = "// Doriax API headers for this project are provided by .doriax/engine-api; see generated CMakeLists.txt for local and upstream source references.\n";
+        const std::string exportComment = "// This file binds scene script metadata to compiled C++ and Lua scripts for the current build configuration.\n";
+        size_t commentPos = content.find(editorOnlyComment);
+        if (commentPos != std::string::npos) {
+            content.replace(commentPos, editorOnlyComment.size(), exportComment);
+        }
+
+        FileUtils::writeIfChanged(generatedDst / "scene_scripts.cpp", content);
     }
 
     return true;
@@ -355,8 +368,8 @@ bool editor::Exporter::copyAssets() {
             std::string firstComponent = relPath.begin()->string();
             if (!firstComponent.empty() && firstComponent[0] == '.') continue;
 
-            // Skip CMakeLists.txt at root level
-            if (relPath == "CMakeLists.txt") continue;
+            // Skip project support files that should not ship as assets
+            if (shouldSkipExportSupportFile(relPath)) continue;
 
             // Skip C++ script files (handled by copyCppScripts)
             if (entry.is_regular_file() && scriptPaths.count(fs::weakly_canonical(entry.path(), ec))) continue;
@@ -450,8 +463,8 @@ bool editor::Exporter::copyLua() {
         std::string firstComponent = relPath.begin()->string();
         if (!firstComponent.empty() && firstComponent[0] == '.') { it.disable_recursion_pending(); continue; }
 
-        // Skip CMakeLists.txt at root level
-        if (relPath == "CMakeLists.txt") continue;
+        // Skip project support files that should not ship in the Lua directory
+        if (shouldSkipExportSupportFile(relPath)) continue;
 
         // Skip terrain_maps directory (handled by copyAssets)
         if (entry.is_directory()) {

editor/Exporter.h

@@ -54,6 +54,7 @@ namespace doriax::editor {
         bool isCancelled() const;
 
         fs::path getExportProjectRoot() const;
+        static bool shouldSkipExportSupportFile(const fs::path& relativePath);
 
         bool checkTargetDir();
         bool clearGenerated();

editor/Generator.cpp

@@ -739,6 +739,9 @@ void editor::Generator::writeSourceFiles(const fs::path& projectPath, const fs::
     cmakeContent += "project(" + libName + ")\n\n";
     cmakeContent += "set(PROJECT_ROOT ${CMAKE_CURRENT_SOURCE_DIR})\n";
     cmakeContent += "set(INTERNAL_DIR ${PROJECT_ROOT}/.doriax)\n\n";
+    cmakeContent += "# Doriax runtime API headers for this project come from ${INTERNAL_DIR}/engine-api.\n";
+    cmakeContent += "# Local engine API source used by this editor build: " + (exePath / "engine").generic_string() + "\n";
+    cmakeContent += "# Full engine + editor source (including YAML serialization for *.scene/*.bundle/project.yaml): https://github.com/doriaxengine/doriax\n\n";
 
     cmakeContent += "# Specify C++ standard\n";
     cmakeContent += "set(CMAKE_CXX_STANDARD 17)\n";
@@ -808,7 +811,7 @@ void editor::Generator::writeSourceFiles(const fs::path& projectPath, const fs::
     cmakeContent += "    " + engineApiPathStr + "/core/util\n";
     cmakeContent += ")\n\n";
 
-    cmakeContent += "# Default DORIAX_LIB_DIR if not provided\n";
+    cmakeContent += "# libdoriax is searched in DORIAX_LIB_DIR; by default it points to the Doriax editor executable directory.\n";
     cmakeContent += "if(NOT DEFINED DORIAX_LIB_DIR OR DORIAX_LIB_DIR STREQUAL \"\")\n";
     cmakeContent += "    set(DORIAX_LIB_DIR \"" + exePath.generic_string() + "\")\n";
     cmakeContent += "    # Must be the same as the editor's library to not ODR violation / ABI mismatch\n";
@@ -845,6 +848,7 @@ void editor::Generator::writeSourceFiles(const fs::path& projectPath, const fs::
     // Build C++ source content
     std::string sourceContent;
     sourceContent += "// This file is auto-generated by Doriax Editor. Do not edit manually.\n\n";
+    sourceContent += "// This file binds scene script metadata to compiled C++ and Lua scripts for the current build configuration.\n\n";
     sourceContent += "#include <vector>\n";
     sourceContent += "#include <string>\n";
     sourceContent += "#include <stdio.h>\n";
@@ -884,6 +888,38 @@ void editor::Generator::writeSourceFiles(const fs::path& projectPath, const fs::
         settingsContent += "}\n";
         FileUtils::writeIfChanged(settingsFile, settingsContent);
     }
+
+    fs::path agentsFile = projectPath / "AGENTS.md";
+    std::string agentsContent;
+    agentsContent += "<!-- This file is auto-generated by Doriax Editor. -->\n\n";
+    agentsContent += "# Doriax Project Context\n\n";
+    agentsContent += "This project was generated by Doriax Editor.\n\n";
+    agentsContent += "## Source references\n\n";
+    agentsContent += "- Runtime API headers used by this project (snapshot): `" + engineApiRelativePath.generic_string() + "`\n";
+    agentsContent += "- Local engine API source used by this editor build: `" + (exePath / "engine").generic_string() + "`\n";
+    agentsContent += "- Full engine **and editor** source (upstream): https://github.com/doriaxengine/doriax\n\n";
+    agentsContent += "The two local paths above contain only the runtime engine API (what user code links against).\n";
+    agentsContent += "They do **not** include the editor itself. To understand the YAML schema of `*.scene`, `*.bundle`, and `project.yaml`, or how the generator/factory produces C++, consult the upstream repository — specifically the `editor/` directory.\n\n";
+    agentsContent += "## Generated files\n\n";
+    agentsContent += "These files are produced by the editor when a scene is played/run and are intended for **in-editor testing only**. Project export/distribution uses a separate pipeline and does not reuse these files. Do not edit them manually — they will be overwritten on the next generation:\n\n";
+    agentsContent += "- `CMakeLists.txt` (project root)\n";
+    agentsContent += "- `" + relativeInternalPath.generic_string() + "/scene_scripts.cpp`\n";
+    agentsContent += "- `" + relativeInternalPath.generic_string() + "/generated/` (scene factories, bundle factories, `main.cpp`, `PlatformEditor.h`, `PlatformEditor.cpp`)\n";
+    agentsContent += "- `" + engineApiRelativePath.generic_string() + "/` (engine API snapshot copied from the editor)\n\n";
+    agentsContent += "## Regenerating C++ code\n\n";
+    agentsContent += "The generated C++ sources (scene factories, script bindings) are derived from `*.scene`, `*.bundle`, and `project.yaml` files.\n";
+    agentsContent += "If you modify any `*.scene`, `*.bundle`, or `project.yaml` file, **you must return to Doriax Editor and play/run the scene** so the editor regenerates all C++ code under `" + relativeInternalPath.generic_string() + "/generated`.\n\n";
+    agentsContent += "## C++ Scripts\n\n";
+    agentsContent += "User C++ script files (`.h`/`.cpp`) can be placed anywhere in the project outside of `" + relativeInternalPath.generic_string() + "/`.\n";
+    agentsContent += "Each script class must inherit from `doriax::Script`. "
+                     "The editor discovers and registers scripts automatically; "
+                     "they are added to `SCRIPT_SOURCES` in the generated `CMakeLists.txt` and compiled into the project.\n";
+    agentsContent += "Lua scripts (`.lua`) are separate — they are loaded at runtime and are not compiled into the binary.\n\n";
+    agentsContent += "## Build modes\n\n";
+    agentsContent += "- **Editor mode** (`DORIAX_EDITOR_PLUGIN=ON`): builds as a shared library; `main.cpp` and Factory-generated scene sources are excluded. Used by the editor to hot-reload the project.\n";
+    agentsContent += "- **Standalone mode** (`DORIAX_EDITOR_PLUGIN=OFF`, default): builds as an executable; includes `main.cpp` and all Factory sources. This standalone build is for local testing only — production distribution uses the editor's separate export pipeline.\n";
+
+    FileUtils::writeIfChanged(agentsFile, agentsContent);
 }
 
 void editor::Generator::terminateCurrentProcess() {