@better-openclaw/core 1.0.0

package/src/generators/n8n-workflows.ts

@@ -0,0 +1,88 @@
+import type { ResolverOutput } from "../types.js";
+
+/**
+ * Generates n8n workflow template files.
+ * Returns a map of file paths to JSON content strings.
+ */
+export function generateN8nWorkflows(resolved: ResolverOutput): Record<string, string> {
+	const files: Record<string, string> = {};
+
+	// Only generate if n8n is in the stack
+	const hasN8n = resolved.services.some((s) => s.definition.id === "n8n");
+	if (!hasN8n) return files;
+
+	files["n8n/workflows/openclaw-webhook-handler.json"] = JSON.stringify(
+		createWebhookHandlerWorkflow(resolved),
+		null,
+		2,
+	);
+
+	return files;
+}
+
+function createWebhookHandlerWorkflow(resolved: ResolverOutput) {
+	// Create a basic n8n workflow JSON that:
+	// 1. Has a Webhook trigger node listening on /openclaw-webhook
+	// 2. Has a Function node that processes the payload
+	// 3. Outputs to a Respond to Webhook node
+	const serviceNames = resolved.services.map((s) => s.definition.name).join(", ");
+
+	return {
+		name: "OpenClaw Webhook Handler",
+		nodes: [
+			{
+				parameters: {
+					httpMethod: "POST",
+					path: "openclaw-webhook",
+					responseMode: "responseNode",
+					options: {},
+				},
+				id: "webhook-trigger",
+				name: "Webhook",
+				type: "n8n-nodes-base.webhook",
+				typeVersion: 2,
+				position: [250, 300],
+			},
+			{
+				parameters: {
+					jsCode:
+						"// Process OpenClaw webhook payload\n" +
+						"const payload = $input.all()[0].json;\n" +
+						"\n" +
+						"// Available services in this stack:\n" +
+						`// ${serviceNames}\n` +
+						"\n" +
+						"return [{ json: { received: true, timestamp: new Date().toISOString(), payload } }];",
+				},
+				id: "process-payload",
+				name: "Process Payload",
+				type: "n8n-nodes-base.code",
+				typeVersion: 2,
+				position: [470, 300],
+			},
+			{
+				parameters: {
+					respondWith: "json",
+					responseBody: "={{ JSON.stringify($json) }}",
+					options: {},
+				},
+				id: "respond",
+				name: "Respond to Webhook",
+				type: "n8n-nodes-base.respondToWebhook",
+				typeVersion: 1,
+				position: [690, 300],
+			},
+		],
+		connections: {
+			Webhook: {
+				main: [[{ node: "Process Payload", type: "main", index: 0 }]],
+			},
+			"Process Payload": {
+				main: [[{ node: "Respond to Webhook", type: "main", index: 0 }]],
+			},
+		},
+		active: false,
+		settings: { executionOrder: "v1" },
+		tags: [{ name: "openclaw" }],
+	};
+}

package/src/generators/native-services.ts

@@ -0,0 +1,103 @@
+import type { NativePlatform, ResolvedService } from "../types.js";
+
+export interface NativeServicesGeneratorOptions {
+	nativeServices: ResolvedService[];
+	platform: NativePlatform;
+	projectName: string;
+}
+
+/**
+ * Generates native install/run scripts for services that have a native recipe.
+ * Returns e.g. native/install-linux.sh (or native/install.ps1 for Windows).
+ * Scripts source .env and run install steps then start commands in dependency order.
+ */
+export function generateNativeInstallScripts(
+	options: NativeServicesGeneratorOptions,
+): Record<string, string> {
+	const { nativeServices, platform } = options;
+	const files: Record<string, string> = {};
+
+	if (platform === "linux") {
+		files["native/install-linux.sh"] = buildLinuxNativeScript(nativeServices);
+	} else if (platform === "windows") {
+		files["native/install-windows.ps1"] = buildWindowsNativeScript(nativeServices);
+	} else {
+		// macos: use bash script similar to linux
+		files["native/install-macos.sh"] = buildLinuxNativeScript(nativeServices);
+	}
+
+	return files;
+}
+
+function buildLinuxNativeScript(nativeServices: ResolvedService[]): string {
+	const lines: string[] = [
+		"#!/usr/bin/env bash",
+		"set -euo pipefail",
+		"# OpenClaw native services — install and start (Linux). Run from project root. Source .env first.",
+		"",
+		'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+		'PROJECT_DIR="$(dirname "$SCRIPT_DIR")"',
+		'cd "$PROJECT_DIR"',
+		"",
+		"if [ -f .env ]; then set -a; source .env; set +a; fi",
+		"",
+	];
+
+	for (const { definition: def } of nativeServices) {
+		const recipe = def.nativeRecipes?.find((r) => r.platform === "linux");
+		if (!recipe) continue;
+
+		lines.push(`# ─── ${def.icon} ${def.name} ─────────────────────────────────────────`);
+		lines.push("");
+
+		if (recipe.configPath && recipe.configTemplate) {
+			const delim = `ENDOF_${def.id.toUpperCase().replace(/-/g, "_")}_CONF`;
+			lines.push(`# Write config for ${def.id}`);
+			lines.push(`sudo mkdir -p "$(dirname "${recipe.configPath}")" 2>/dev/null || true`);
+			lines.push(`sudo tee "${recipe.configPath}" > /dev/null << ${delim}`);
+			lines.push(recipe.configTemplate.trim());
+			lines.push(delim);
+			lines.push("");
+		}
+
+		for (const step of recipe.installSteps) {
+			lines.push(`# Install: ${def.id}`);
+			lines.push(step);
+			lines.push("");
+		}
+
+		lines.push(`# Start: ${def.id}`);
+		lines.push(recipe.startCommand);
+		lines.push("");
+	}
+
+	lines.push("echo 'Native services started.'");
+	return lines.join("\n");
+}
+
+function buildWindowsNativeScript(nativeServices: ResolvedService[]): string {
+	const lines: string[] = [
+		"# OpenClaw native services — install and start (Windows). Run from project root.",
+		"$ErrorActionPreference = 'Stop'",
+		"$ProjectDir = (Get-Item $PSScriptRoot).Parent.FullName",
+		"Set-Location $ProjectDir",
+		"",
+		"if (Test-Path .env) { Get-Content .env | ForEach-Object { if ($_ -match '^([^#=]+)=(.*)$') { [System.Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), 'Process') } } }",
+		"",
+	];
+
+	for (const { definition: def } of nativeServices) {
+		const recipe = def.nativeRecipes?.find((r) => r.platform === "windows");
+		if (!recipe) continue;
+
+		lines.push(`# ${def.name}`);
+		for (const step of recipe.installSteps) {
+			lines.push(`Invoke-Expression "${step.replace(/"/g, '`"')}"`);
+		}
+		lines.push(recipe.startCommand);
+		lines.push("");
+	}
+
+	lines.push("Write-Host 'Native services started.'");
+	return lines.join("\n");
+}

package/src/generators/postgres-init.ts

@@ -0,0 +1,137 @@
+import type { ResolverOutput } from "../types.js";
+
+/**
+ * Database requirement descriptor for a service.
+ */
+interface DbRequirement {
+	serviceId: string;
+	serviceName: string;
+	dbName: string;
+	dbUser: string;
+	passwordEnvVar: string;
+}
+
+/**
+ * Known database requirements for services that need their own PostgreSQL database.
+ * Maps service ID to the DB name, user, and password env var they expect.
+ */
+const DB_REQUIREMENTS: Record<string, Omit<DbRequirement, "serviceId" | "serviceName">> = {
+	n8n: { dbName: "n8n", dbUser: "n8n", passwordEnvVar: "N8N_DB_PASSWORD" },
+	postiz: { dbName: "postiz", dbUser: "postiz", passwordEnvVar: "POSTIZ_DB_PASSWORD" },
+	outline: { dbName: "outline", dbUser: "outline", passwordEnvVar: "OUTLINE_DB_PASSWORD" },
+	dify: { dbName: "dify", dbUser: "dify", passwordEnvVar: "DIFY_DB_PASSWORD" },
+	temporal: { dbName: "temporal", dbUser: "temporal", passwordEnvVar: "TEMPORAL_DB_PASSWORD" },
+	mattermost: {
+		dbName: "mattermost",
+		dbUser: "mattermost",
+		passwordEnvVar: "MATTERMOST_DB_PASSWORD",
+	},
+	"matrix-synapse": { dbName: "synapse", dbUser: "synapse", passwordEnvVar: "SYNAPSE_DB_PASSWORD" },
+	"paperless-ngx": {
+		dbName: "paperless",
+		dbUser: "paperless",
+		passwordEnvVar: "PAPERLESS_DB_PASSWORD",
+	},
+	umami: { dbName: "umami", dbUser: "umami", passwordEnvVar: "UMAMI_DB_PASSWORD" },
+	matomo: { dbName: "matomo", dbUser: "matomo", passwordEnvVar: "MATOMO_DB_PASSWORD" },
+	mixpost: { dbName: "mixpost", dbUser: "mixpost", passwordEnvVar: "MIXPOST_DB_PASSWORD" },
+};
+
+/**
+ * Get the list of database requirements for all resolved services.
+ * Exported so other generators (env, composer) can access the same data.
+ */
+export function getDbRequirements(resolved: ResolverOutput): DbRequirement[] {
+	const reqs: DbRequirement[] = [];
+	for (const { definition } of resolved.services) {
+		const req = DB_REQUIREMENTS[definition.id];
+		if (req) {
+			reqs.push({
+				serviceId: definition.id,
+				serviceName: definition.name,
+				...req,
+			});
+		}
+	}
+	return reqs;
+}
+
+/**
+ * Generates a PostgreSQL initialization script that creates databases and users
+ * for all companion services that need their own DB.
+ *
+ * Returns null if PostgreSQL is not in the resolved stack or no services need extra DBs.
+ * The script is designed to be mounted at /docker-entrypoint-initdb.d/init-databases.sh
+ * and runs automatically during PostgreSQL's first initialization.
+ */
+export function generatePostgresInit(resolved: ResolverOutput): string | null {
+	const hasPostgres = resolved.services.some((s) => s.definition.id === "postgresql");
+	if (!hasPostgres) return null;
+
+	const reqs = getDbRequirements(resolved);
+	if (reqs.length === 0) return null;
+
+	const createCalls = reqs
+		.map(
+			(r) =>
+				`create_db_and_user "${r.dbName}" "${r.dbUser}" "\${${r.passwordEnvVar}:-$POSTGRES_PASSWORD}"`,
+		)
+		.join("\n");
+
+	return `#!/bin/bash
+set -e
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PostgreSQL Initialization Script
+# Generated by better-openclaw
+#
+# This script runs automatically during PostgreSQL's first initialization.
+# It creates databases and users for all companion services in your stack.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+create_db_and_user() {
+  local db="$1"
+  local user="$2"
+  local password="$3"
+
+  echo ">>> Creating database '$db' with user '$user'..."
+
+  psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
+    -- Create user if not exists
+    DO \\$\\$
+    BEGIN
+      IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '$user') THEN
+        CREATE ROLE "$user" WITH LOGIN PASSWORD '$password';
+        RAISE NOTICE 'Created user: $user';
+      ELSE
+        -- Update password in case it changed
+        ALTER ROLE "$user" WITH PASSWORD '$password';
+        RAISE NOTICE 'User already exists, updated password: $user';
+      END IF;
+    END
+    \\$\\$;
+
+    -- Create database if not exists
+    SELECT 'CREATE DATABASE "$db" OWNER "$user"'
+    WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$db')\\gexec
+
+    -- Grant privileges
+    GRANT ALL PRIVILEGES ON DATABASE "$db" TO "$user";
+EOSQL
+
+  echo ">>> Done: database '$db' with user '$user'"
+}
+
+echo "═══════════════════════════════════════════════════════════"
+echo " Initializing databases for companion services..."
+echo "═══════════════════════════════════════════════════════════"
+
+${createCalls}
+
+echo ""
+echo "═══════════════════════════════════════════════════════════"
+echo " All databases initialized successfully!"
+echo " Services: ${reqs.map((r) => r.serviceName).join(", ")}"
+echo "═══════════════════════════════════════════════════════════"
+`;
+}

package/src/generators/prometheus.ts

@@ -0,0 +1,89 @@
+import type { ResolverOutput } from "../types.js";
+
+/**
+ * Well-known metrics endpoints for services.
+ *
+ * Services that expose Prometheus-compatible metrics are listed here
+ * with their metrics path and port.
+ */
+const metricsEndpoints: Record<string, { path: string; port: number }> = {
+	redis: { path: "/metrics", port: 9121 },
+	postgresql: { path: "/metrics", port: 9187 },
+	minio: { path: "/minio/v2/metrics/cluster", port: 9000 },
+	n8n: { path: "/metrics", port: 5678 },
+	grafana: { path: "/metrics", port: 3000 },
+	caddy: { path: "/metrics", port: 2019 },
+	traefik: { path: "/metrics", port: 8082 },
+	qdrant: { path: "/metrics", port: 6333 },
+	"uptime-kuma": { path: "/metrics", port: 3001 },
+	ollama: { path: "/metrics", port: 11434 },
+};
+
+/**
+ * Generates a Prometheus configuration YAML file with scrape configs
+ * for all services that expose metrics endpoints.
+ *
+ * @param resolved - The resolved service configuration
+ * @returns The prometheus.yml content as a string
+ */
+export function generatePrometheusConfig(resolved: ResolverOutput): string {
+	const sections: string[] = [];
+
+	// ── Header ──────────────────────────────────────────────────────────────
+
+	sections.push(`# ═══════════════════════════════════════════════════════════════════════════════
+# Prometheus Configuration — Auto-generated by OpenClaw
+# ═══════════════════════════════════════════════════════════════════════════════
+
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+  scrape_timeout: 10s
+
+# ─── Scrape Configs ──────────────────────────────────────────────────────────
+
+scrape_configs:
+  # Prometheus self-monitoring
+  - job_name: "prometheus"
+    static_configs:
+      - targets: ["localhost:9090"]
+        labels:
+          service: "prometheus"
+          component: "monitoring"`);
+
+	// ── Service Scrape Configs ───────────────────────────────────────────────
+
+	for (const { definition } of resolved.services) {
+		// Skip prometheus itself (already included above)
+		if (definition.id === "prometheus") continue;
+
+		const endpoint = metricsEndpoints[definition.id];
+		if (!endpoint) continue;
+
+		sections.push(`
+  # ${definition.icon} ${definition.name}
+  - job_name: "${definition.id}"
+    metrics_path: "${endpoint.path}"
+    static_configs:
+      - targets: ["${definition.id}:${endpoint.port}"]
+        labels:
+          service: "${definition.id}"
+          component: "${definition.category}"`);
+	}
+
+	// ── OpenClaw Gateway Metrics ────────────────────────────────────────────
+
+	sections.push(`
+  # 🐾 OpenClaw Gateway
+  - job_name: "openclaw-gateway"
+    metrics_path: "/metrics"
+    static_configs:
+      - targets: ["openclaw:18789"]
+        labels:
+          service: "openclaw"
+          component: "core"`);
+
+	sections.push("");
+
+	return sections.join("\n");
+}

package/src/generators/readme.ts

@@ -0,0 +1,274 @@
+import type { ResolverOutput } from "../types.js";
+
+/**
+ * Options for README generation.
+ */
+export interface ReadmeOptions {
+	projectName: string;
+	domain?: string;
+	proxy?: string;
+	/** When "bare-metal", the stack uses native + Docker hybrid. */
+	deploymentType?: "docker" | "bare-metal";
+	/** True when some services run natively on the host (bare-metal only). */
+	hasNativeServices?: boolean;
+}
+
+/**
+ * Generates a comprehensive README.md for the OpenClaw project.
+ *
+ * Includes: project description, service table, quick start instructions,
+ * service URLs, skill packs, and scripts documentation.
+ */
+export function generateReadme(resolved: ResolverOutput, options: ReadmeOptions): string {
+	const { projectName, domain, proxy, deploymentType, hasNativeServices } = options;
+	const sections: string[] = [];
+
+	// ── Title & Description ─────────────────────────────────────────────────
+
+	sections.push(`# ${projectName}
+
+> Self-hosted AI agent infrastructure powered by [OpenClaw](https://openclaw.dev).
+
+This project provides a fully configured Docker Compose stack with ${resolved.services.length} services, ready to deploy on any server.
+${deploymentType === "bare-metal" && hasNativeServices ? "\n\n**Bare-metal (native + Docker):** Some services run natively on the host; the rest (including the OpenClaw gateway) run in Docker. Use the top-level `install.sh` or `install.ps1` to install/start native services first, then start the Docker stack." : ""}
+
+---`);
+
+	// ── Service Table ────────────────────────────────────────────────────────
+
+	const serviceRows = resolved.services
+		.map(({ definition }) => {
+			const mainPort = definition.ports.find((p) => p.exposed);
+			const url = mainPort
+				? domain
+					? `https://${definition.id}.${domain}`
+					: `http://localhost:${mainPort.host}`
+				: "N/A (internal)";
+			return `| ${definition.icon} | **${definition.name}** | ${url} | ${definition.description} |`;
+		})
+		.join("\n");
+
+	sections.push(`## Services
+
+| | Service | URL | Description |
+|---|---------|-----|-------------|
+${serviceRows}
+`);
+
+	// ── Quick Start ──────────────────────────────────────────────────────────
+
+	sections.push(`## Quick Start
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) (v24+)
+- [Docker Compose](https://docs.docker.com/compose/install/) (v2+)
+- At least ${Math.ceil(resolved.estimatedMemoryMB / 1024)}GB of RAM available
+
+### 1. Extract the ZIP
+
+\`\`\`bash
+unzip ${projectName}.zip
+cd ${projectName}
+\`\`\`
+
+### 2. Configure Environment
+
+\`\`\`bash
+cp .env.example .env
+\`\`\`
+
+Edit \`.env\` and update any values as needed. Secret values have been pre-generated — review and change them for production use.
+
+### 3. Start Services
+
+\`\`\`bash
+docker compose up -d
+\`\`\`
+
+Or use the provided start script:
+
+\`\`\`bash
+chmod +x scripts/*.sh
+./scripts/start.sh
+\`\`\`
+
+### 4. Check Status
+
+\`\`\`bash
+docker compose ps
+\`\`\`
+
+### 5. View Logs
+
+\`\`\`bash
+docker compose logs -f openclaw-gateway
+\`\`\`
+
+All services should show a healthy status within 1–2 minutes.
+`);
+
+	// ── Docker Compose Profiles ──────────────────────────────────────────────
+
+	sections.push(`## Using Docker Compose Profiles
+
+Your stack may include profile-based compose files for optional service groups. Only the base services start by default — use profiles to activate additional groups:
+
+\`\`\`bash
+# Start base services only
+docker compose up -d
+
+# Start base + AI services (Ollama, Open WebUI, etc.)
+docker compose -f docker-compose.yml -f docker-compose.ai.yml --profile ai up -d
+
+# Start base + monitoring (Grafana, Prometheus, Uptime Kuma)
+docker compose -f docker-compose.yml -f docker-compose.monitoring.yml --profile monitoring up -d
+
+# Start base + AI + dev tools
+docker compose -f docker-compose.yml -f docker-compose.ai.yml -f docker-compose.tools.yml --profile ai --profile tools up -d
+\`\`\`
+
+Available profile files (if generated):
+| File | Profile | Services |
+|------|---------|----------|
+| \`docker-compose.ai.yml\` | \`ai\` | AI models, chat UIs, LLM platforms |
+| \`docker-compose.media.yml\` | \`media\` | FFmpeg, Remotion, Motion Canvas |
+| \`docker-compose.monitoring.yml\` | \`monitoring\` | Grafana, Prometheus, Uptime Kuma, analytics |
+| \`docker-compose.tools.yml\` | \`tools\` | Gitea, code-server, Portainer, coding agents |
+| \`docker-compose.social.yml\` | \`social\` | Postiz, Mixpost |
+| \`docker-compose.knowledge.yml\` | \`knowledge\` | Outline, Paperless-ngx, NocoDB |
+| \`docker-compose.communication.yml\` | \`communication\` | Matrix, Rocket.Chat, Mattermost |
+`);
+
+	// ── Service URLs & Ports ─────────────────────────────────────────────────
+
+	const portRows = resolved.services
+		.filter(({ definition }) => definition.ports.length > 0)
+		.map(({ definition }) => {
+			const ports = definition.ports
+				.map((p) => `\`${p.host}\` → \`${p.container}\` (${p.description})`)
+				.join(", ");
+			return `| ${definition.icon} ${definition.name} | ${ports} |`;
+		})
+		.join("\n");
+
+	if (portRows) {
+		sections.push(`## Ports
+
+| Service | Ports |
+|---------|-------|
+${portRows}
+`);
+	}
+
+	// ── Skill Packs ─────────────────────────────────────────────────────────
+
+	const allSkills = resolved.services.flatMap(({ definition }) =>
+		definition.skills.map((s) => ({
+			skillId: s.skillId,
+			serviceName: definition.name,
+			serviceIcon: definition.icon,
+		})),
+	);
+
+	if (allSkills.length > 0) {
+		const skillRows = allSkills
+			.map((s) => `| \`${s.skillId}\` | ${s.serviceIcon} ${s.serviceName} |`)
+			.join("\n");
+
+		sections.push(`## Skills
+
+The following OpenClaw skills are automatically installed:
+
+| Skill | Service |
+|-------|---------|
+${skillRows}
+
+Skills are located in \`openclaw/workspace/skills/\`. Each skill provides a \`SKILL.md\` with usage instructions.
+`);
+	}
+
+	// ── Proxy Configuration ─────────────────────────────────────────────────
+
+	if (proxy && proxy !== "none") {
+		const proxyName = proxy === "caddy" ? "Caddy" : "Traefik";
+		sections.push(`## Reverse Proxy
+
+This stack uses **${proxyName}** as a reverse proxy.${domain ? ` All services are available under \`${domain}\`.` : ""}
+
+${proxy === "caddy" ? "The Caddyfile is located at `config/Caddyfile`." : "Traefik configuration is handled via Docker labels."}
+`);
+	}
+
+	// ── Scripts ──────────────────────────────────────────────────────────────
+
+	sections.push(`## Management Scripts
+
+\`\`\`bash
+chmod +x scripts/*.sh     # Make scripts executable (first time only)
+\`\`\`
+
+| Script | Description |
+|--------|-------------|
+| \`./scripts/start.sh\` | Validates .env, auto-generates gateway token, creates dirs, starts all services with health checks |
+| \`./scripts/stop.sh\` | Gracefully stops all services |
+| \`./scripts/update.sh\` | Pulls latest Docker images and restarts services |
+| \`./scripts/backup.sh\` | Backs up all named Docker volumes to timestamped archives |
+| \`./scripts/status.sh\` | Shows current service status, resource usage, and disk |
+`);
+
+	// ── Data & Volumes ──────────────────────────────────────────────────────
+
+	const volumeRows = resolved.services.flatMap(({ definition }) =>
+		definition.volumes.map((v) => ({
+			name: v.name,
+			path: v.containerPath,
+			description: v.description,
+			serviceName: definition.name,
+		})),
+	);
+
+	if (volumeRows.length > 0) {
+		const rows = volumeRows
+			.map((v) => `| \`${v.name}\` | ${v.serviceName} | ${v.description} |`)
+			.join("\n");
+
+		sections.push(`## Volumes
+
+| Volume | Service | Description |
+|--------|---------|-------------|
+${rows}
+
+> **Tip:** Use \`scripts/backup.sh\` to back up all volumes before updates.
+`);
+	}
+
+	// ── Estimated Resources ─────────────────────────────────────────────────
+
+	sections.push(`## Resource Estimates
+
+- **Services:** ${resolved.services.length}
+- **Estimated RAM:** ~${(resolved.estimatedMemoryMB / 1024).toFixed(1)}GB
+- **Recommended minimum:** ${Math.ceil(resolved.estimatedMemoryMB / 1024) + 2}GB RAM
+`);
+
+	// ── Warnings ─────────────────────────────────────────────────────────────
+
+	if (resolved.warnings.length > 0) {
+		const warningList = resolved.warnings.map((w) => `- ⚠️ ${w.message}`).join("\n");
+
+		sections.push(`## Warnings
+
+${warningList}
+`);
+	}
+
+	// ── Footer ──────────────────────────────────────────────────────────────
+
+	sections.push(`---
+
+Generated by [OpenClaw](https://openclaw.dev) • ${new Date().toISOString().split("T")[0]}
+`);
+
+	return sections.join("\n");
+}