ColdBox · lmajano · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026
diff --git a/models/AgentRegistry.cfc b/models/AgentRegistry.cfc
@@ -28,7 +28,10 @@ component singleton {
 			"gemini"   : "GEMINI.md",
 			"opencode" : "AGENTS.md"
 		}
-		AGENT_OPTIONS = [
+		// Demarcation markers that wrap the ColdBox CLI-managed section
+		MANAGED_SECTION_START = "<!-- COLDBOX-CLI:START -->"
+		MANAGED_SECTION_END   = "<!-- COLDBOX-CLI:END -->"
+		AGENT_OPTIONS         = [
 			{
 				display : "Claude (Anthropic) - Recommended for general development",
 				value   : "claude"
@@ -126,6 +129,61 @@ component singleton {
 	// Private Helpers
 	// ========================================
 
+	/**
+	 * Merges newly generated managed content with any user-authored content from an existing file.
+	 *
+	 * The managed section is delimited by COLDBOX-CLI:START and COLDBOX-CLI:END HTML comment
+	 * markers. On refresh, only the content between those markers is replaced; everything after
+	 * the end marker (i.e. the user's custom documentation) is preserved unchanged.
+	 *
+	 * Behavior:
+	 * - File does not exist → return newContent as-is (first-time write).
+	 * - File exists but has no end marker → return newContent as-is (old format, no user section to preserve).
+	 * - File exists with end marker → replace managed section, keep user section intact.
+	 *
+	 * @filePath   Absolute path to the existing agent config file (may not exist yet).
+	 * @newContent Freshly generated content that includes both START and END markers.
+	 *
+	 * @return Combined content with updated managed section and preserved user section.
+	 */
+	private string function mergeUserContent(
+		required string filePath,
+		required string newContent
+	){
+		var endMarker = static.MANAGED_SECTION_END
+
+		// Nothing to preserve — first-time write
+		if ( !fileExists( filePath ) ) {
+			return newContent
+		}
+
+		var existingContent = fileRead( filePath )
+
+		// Find the end marker in the existing file
+		var endPos = findNoCase( endMarker, existingContent )
+
+		// Old-format file (no markers) — write fresh content, no user section to preserve
+		if ( !endPos ) {
+			return newContent
+		}
+
+		// Extract user content: everything that comes after the end marker
+		var userStartPos = endPos + len( endMarker )
+		var userContent  = mid( existingContent, userStartPos, len( existingContent ) - userStartPos + 1 )
+
+		// Find the end marker position in the newly generated content
+		var newEndPos = findNoCase( endMarker, newContent )
+		if ( !newEndPos ) {
+			// New template has no end marker — return new content plus preserved user section
+			return newContent & userContent
+		}
+
+		// Slice off the managed portion of the new content (up to and including the end marker)
+		var managedContent = left( newContent, newEndPos + len( endMarker ) - 1 )
+
+		return managedContent & userContent
+	}
+
 	/**
 	 * Configure a single agent
 	 *
@@ -156,13 +214,14 @@ component singleton {
 		// For Claude, write the full content to AGENTS.md and make CLAUDE.md point to it
 		if ( arguments.agent == "claude" ) {
 			var agentsFilePath = getDirectoryFromPath( configPath ) & "AGENTS.md"
-			fileWrite( agentsFilePath, content )
+			var mergedContent  = mergeUserContent( agentsFilePath, content )
+			fileWrite( agentsFilePath, mergedContent )
 			fileWrite( configPath, "@AGENTS.md" )
 			return
 		}
 
-		// Write agent config file
-		fileWrite( configPath, content )
+		// Write agent config file, preserving any user-authored content outside the managed section
+		fileWrite( configPath, mergeUserContent( configPath, content ) )
 	}
 
 	/**

diff --git a/templates/ai/agents/agent-flat-instructions.md b/templates/ai/agents/agent-flat-instructions.md
@@ -1,3 +1,7 @@
+<!-- COLDBOX-CLI:START -->
+<!-- ⚡ This section is managed by ColdBox CLI and will be refreshed on `coldbox ai refresh`. -->
+<!-- ⚠️  Do NOT edit content between COLDBOX-CLI:START and COLDBOX-CLI:END markers — changes will be overwritten. -->
+
 # |PROJECT_NAME| - AI Agent Instructions
 
 This is a ColdBox HMVC application using the **flat template structure** where all application code lives in the webroot. Compatible with Adobe ColdFusion 2018+, Lucee 5.x+, and BoxLang 1.0+.
@@ -88,34 +92,6 @@ box testbox run
 /?fwreinit=true
 ```
 
-## Custom Application Details
-
-<!-- Add project-specific information below -->
-
-### Business Domain
-
-<!-- Describe what this application does -->
-
-### Key Services/Models
-
-<!-- List important services and their responsibilities -->
-
-### Authentication/Security
-
-<!-- Describe authentication approach if applicable -->
-
-### API Endpoints
-
-<!-- Document REST API routes if applicable -->
-
-### Deployment
-
-<!-- Document deployment process -->
-
-### Third-Party Integrations
-
-<!-- List external services, APIs, or integrations -->
-
 ## AI Integration
 
 This project includes AI-powered development assistance with guidelines, skills, and MCP documentation servers.
@@ -195,3 +171,35 @@ This project has access to the following Model Context Protocol (MCP) documentat
 - ColdBox Docs: https://coldbox.ortusbooks.com
 - TestBox: https://testbox.ortusbooks.com
 - WireBox: https://wirebox.ortusbooks.com
+
+<!-- COLDBOX-CLI:END -->
+
+<!-- ℹ️ YOUR PROJECT DOCUMENTATION — Add your custom details below. ColdBox CLI will NOT overwrite this section. -->
+
+## Custom Application Details
+
+<!-- Add project-specific information below -->
+
+### Business Domain
+
+<!-- Describe what this application does -->
+
+### Key Services/Models
+
+<!-- List important services and their responsibilities -->
+
+### Authentication/Security
+
+<!-- Describe authentication approach if applicable -->
+
+### API Endpoints
+
+<!-- Document REST API routes if applicable -->
+
+### Deployment
+
+<!-- Document deployment process -->
+
+### Third-Party Integrations
+
+<!-- List external services, APIs, or integrations -->
diff --git a/templates/ai/agents/agent-modern-instructions.md b/templates/ai/agents/agent-modern-instructions.md
@@ -1,3 +1,7 @@
+<!-- COLDBOX-CLI:START -->
+<!-- ⚡ This section is managed by ColdBox CLI and will be refreshed on `coldbox ai refresh`. -->
+<!-- ⚠️  Do NOT edit content between COLDBOX-CLI:START and COLDBOX-CLI:END markers — changes will be overwritten. -->
+
 # |PROJECT_NAME| - AI Agent Instructions
 
 This is a ColdBox HMVC application using the **modern template structure** with application code separated from the public webroot. Compatible with Adobe ColdFusion 2018+, Lucee 5.x+, and BoxLang 1.0+.
@@ -125,38 +129,6 @@ docker-compose logs -f
 - **ORM:** |ORM_ENABLED| - Object-Relational Mapping via CBORM or Quick
 - **Migrations:** |MIGRATIONS_ENABLED| - Database version control with CommandBox Migrations
 
-## Custom Application Details
-
-<!-- Add project-specific information below -->
-
-### Business Domain
-
-<!-- Describe what this application does -->
-
-### Key Services/Models
-
-<!-- List important services and their responsibilities -->
-
-### Authentication/Security
-
-<!-- Describe authentication approach if applicable -->
-
-### API Endpoints
-
-<!-- Document REST API routes if applicable -->
-
-### Database
-
-<!-- Document database setup, migrations, seeders if applicable -->
-
-### Deployment
-
-<!-- Document deployment process -->
-
-### Third-Party Integrations
-
-<!-- List external services, APIs, or integrations -->
-
 ## AI Integration
 
 This project includes AI-powered development assistance with guidelines, skills, and MCP documentation servers.
@@ -238,3 +210,39 @@ This project has access to the following Model Context Protocol (MCP) documentat
 - ColdBox Docs: https://coldbox.ortusbooks.com
 - TestBox: https://testbox.ortusbooks.com
 - WireBox: https://wirebox.ortusbooks.com
+
+<!-- COLDBOX-CLI:END -->
+
+<!-- ℹ️ YOUR PROJECT DOCUMENTATION — Add your custom details below. ColdBox CLI will NOT overwrite this section. -->
+
+## Custom Application Details
+
+<!-- Add project-specific information below -->
+
+### Business Domain
+
+<!-- Describe what this application does -->
+
+### Key Services/Models
+
+<!-- List important services and their responsibilities -->
+
+### Authentication/Security
+
+<!-- Describe authentication approach if applicable -->
+
+### API Endpoints
+
+<!-- Document REST API routes if applicable -->
+
+### Database
+
+<!-- Document database setup, migrations, seeders if applicable -->
+
+### Deployment
+
+<!-- Document deployment process -->
+
+### Third-Party Integrations
+
+<!-- List external services, APIs, or integrations -->