@better-openclaw/core 1.0.26 → 1.0.30

package/src/generators/readme.ts

@@ -1,3 +1,4 @@
+import { getFrameworkById } from "../frameworks/index.js";
 import type { ResolverOutput } from "../types.js";
 
 /**
@@ -13,6 +14,8 @@ export interface ReadmeOptions {
 	hasNativeServices?: boolean;
 	/** How OpenClaw itself is installed: docker (container) or direct (host). */
 	openclawInstallMethod?: "docker" | "direct";
+	/** Primary agent framework (defaults to "openclaw"). */
+	primaryFramework?: string;
 }
 
 /**
@@ -22,19 +25,29 @@ export interface ReadmeOptions {
  * service URLs, skill packs, and scripts documentation.
  */
 export function generateReadme(resolved: ResolverOutput, options: ReadmeOptions): string {
-	const { projectName, domain, proxy, deploymentType, hasNativeServices, openclawInstallMethod } =
-		options;
+	const {
+		projectName,
+		domain,
+		proxy,
+		deploymentType,
+		hasNativeServices,
+		openclawInstallMethod,
+		primaryFramework,
+	} = options;
 	const isDirectInstall = openclawInstallMethod === "direct";
+	const framework = getFrameworkById(primaryFramework ?? "openclaw");
+	const frameworkName = framework?.name ?? "OpenClaw";
+	const isOpenClaw = (primaryFramework ?? "openclaw") === "openclaw";
 	const sections: string[] = [];
 
 	// ── Title & Description ─────────────────────────────────────────────────
 
 	sections.push(`# ${projectName}
 
-> Self-hosted AI agent infrastructure powered by [OpenClaw](https://openclaw.dev).
+> Self-hosted AI agent infrastructure powered by **${frameworkName}**${isOpenClaw ? " — [openclaw.dev](https://openclaw.dev)" : ""}.
 
-This project provides a fully configured Docker Compose stack with ${resolved.services.length} services, ready to deploy on any server.${isDirectInstall ? " OpenClaw itself runs directly on the host (not in Docker)." : ""}
-${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." : ""}
+This project provides a fully configured Docker Compose stack with ${resolved.services.length} services, ready to deploy on any server.${isDirectInstall ? ` ${frameworkName} itself runs directly on the host (not in Docker).` : ""}
+${deploymentType === "bare-metal" && hasNativeServices ? `\n\n**Bare-metal (native + Docker):** Some services run natively on the host; the rest (including the ${frameworkName} gateway) run in Docker. Use the top-level \`install.sh\` or \`install.ps1\` to install/start native services first, then start the Docker stack.` : ""}
 
 ---`);
 
@@ -131,7 +144,7 @@ docker compose ps
 ### 5. View Logs
 
 \`\`\`bash
-docker compose logs -f openclaw-gateway
+docker compose logs -f ${primaryFramework ?? "openclaw"}-gateway
 \`\`\`
 `
 }
@@ -218,10 +231,63 @@ Skills are located in \`openclaw/workspace/skills/\`. Each skill provides a \`SK
 `);
 	}
 
+	// ── AI Memory Integration ──────────────────────────────────────────────
+
+	const memoryServiceIds = ["mem0", "memu", "hindsight"];
+	const vectorDbIds = ["qdrant", "chromadb", "weaviate", "milvus"];
+
+	const memoryServices = resolved.services.filter(({ definition }) =>
+		memoryServiceIds.includes(definition.id),
+	);
+	const vectorDbs = resolved.services.filter(({ definition }) =>
+		vectorDbIds.includes(definition.id),
+	);
+
+	if (memoryServices.length > 0 || vectorDbs.length > 0) {
+		let memSection = `## AI Memory Integration
+
+This stack includes integrated AI memory services. The ${frameworkName} agent framework is automatically configured to use them via \`openclaw/config/openclaw.json\`.
+`;
+
+		if (memoryServices.length > 0) {
+			const memList = memoryServices
+				.map(
+					({ definition }) =>
+						`- ${definition.icon} **${definition.name}** — ${definition.description.split(".")[0]}`,
+				)
+				.join("\n");
+			memSection += `
+### Memory Services
+
+${memList}
+`;
+		}
+
+		if (vectorDbs.length > 0) {
+			const vecList = vectorDbs
+				.map(
+					({ definition }) =>
+						`- ${definition.icon} **${definition.name}** — ${definition.description.split(".")[0]}`,
+				)
+				.join("\n");
+			memSection += `
+### Vector Databases
+
+${vecList}
+`;
+		}
+
+		memSection += `
+Skills for interacting with these services are in \`openclaw/workspace/skills/\`.
+`;
+
+		sections.push(memSection);
+	}
+
 	// ── Onboarding & Channels ──────────────────────────────────────────────
-	// Based on openclaw_docker-setup.sh post-deploy instructions
+	// Only show OpenClaw-specific onboarding instructions for OpenClaw stacks
 
-	if (isDirectInstall) {
+	if (isOpenClaw && isDirectInstall) {
 		sections.push(`## OpenClaw Setup
 
 OpenClaw is installed directly on the host (not in Docker). After running the install script:\n
@@ -253,7 +319,7 @@ openclaw channels add --channel discord --token <BOT_TOKEN>
 
 See [Channel Docs](https://docs.openclaw.ai/channels) for more providers.
 `);
-	} else {
+	} else if (isOpenClaw) {
 		sections.push(`## Onboarding & Channel Setup
 
 After starting the stack, complete the gateway onboarding:

package/src/generators/scripts.test.ts

@@ -20,7 +20,7 @@ describe("generateScripts", () => {
 
 		for (const script of expectedScripts) {
 			expect(result).toHaveProperty(script);
-			expect(result[script]!.length).toBeGreaterThan(0);
+			expect(result[script]?.length).toBeGreaterThan(0);
 		}
 	});
 

package/src/generators/skills.ts

@@ -8,6 +8,78 @@ import type { ResolverOutput } from "../types.js";
  * service's `openclawEnvVars` array at generation time.
  */
 const skillTemplates: Record<string, string> = {
+	"agent-browse": `---
+name: agent-browse
+description: "AI-optimized browser automation with snapshot + ref workflow for deterministic element targeting"
+metadata:
+  openclaw:
+    emoji: "🌍"
+---
+
+# Agent Browser
+
+AI-optimized headless browser available at \`{{AGENT_BROWSER_HOST}}\` with CDP on port \`{{AGENT_BROWSER_CDP_PORT}}\` and live viewport streaming on port \`{{AGENT_BROWSER_STREAM_PORT}}\`.
+
+## Core Workflow: Snapshot → Reason → Act
+
+Agent Browser uses a **ref-based workflow** designed for LLMs. Each interactive element gets a deterministic ref like \`@e1\`, \`@e2\` that you can target directly — no CSS selectors needed.
+
+1. **Navigate:** \`agent-browser open https://example.com\`
+2. **Snapshot:** \`agent-browser snapshot\` → returns accessibility tree with refs
+3. **Reason:** Identify the target element by its ref (e.g. \`@e5\` is the search input)
+4. **Act:** \`agent-browser click @e5\` or \`agent-browser type @e5 "search query"\`
+5. **Verify:** \`agent-browser screenshot\` to capture the result
+
+## Key Commands
+
+| Command | Description |
+|---------|-------------|
+| \`agent-browser open <url>\` | Navigate to a URL |
+| \`agent-browser snapshot\` | Get accessibility tree with @refs |
+| \`agent-browser click @ref\` | Click an element by ref |
+| \`agent-browser type @ref "text"\` | Type text into an input |
+| \`agent-browser select @ref "value"\` | Select a dropdown option |
+| \`agent-browser screenshot [--path file.png]\` | Capture viewport screenshot |
+| \`agent-browser scroll down\\|up\` | Scroll the viewport |
+| \`agent-browser wait <selector\\|ms>\` | Wait for element or time |
+| \`agent-browser extract\` | Extract page content as clean text |
+| \`agent-browser pdf [--path file.pdf]\` | Save page as PDF |
+
+## Snapshot Output Example
+
+\`\`\`
+@e1 heading "Welcome to Example"
+@e2 link "Sign In" [href="/login"]
+@e3 input[text] "Search..." [placeholder]
+@e4 button "Search"
+@e5 link "Learn More" [href="/docs"]
+\`\`\`
+
+Each \`@ref\` is stable within a page state — use it directly: \`agent-browser click @e2\`
+
+## Content Boundaries
+
+Output is wrapped in boundary markers (\`---CONTENT_START---\` / \`---CONTENT_END---\`) to prevent prompt injection from page content. This is enabled by default.
+
+## Session Persistence
+
+\`\`\`bash
+# Save/restore login state across sessions
+agent-browser --session-name my-app open https://app.example.com
+agent-browser --session-name my-app snapshot
+\`\`\`
+
+## Live Viewport Streaming
+
+WebSocket stream at \`ws://{{AGENT_BROWSER_HOST}}:{{AGENT_BROWSER_STREAM_PORT}}\` for real-time viewport watching (pair browsing). Receives JPEG frames with metadata.
+
+## Security
+
+- **Domain allowlist:** Set \`AGENT_BROWSER_ALLOWED_DOMAINS\` to restrict navigation
+- **Action policies:** JSON policy files to require confirmation for specific action categories
+- **Content boundaries:** Prevent LLM prompt injection from page content
+`,
+
 	"redis-cache": `---
 name: redis-cache
 description: "Cache data and manage key-value state using Redis"
@@ -677,6 +749,250 @@ curl -X POST http://{{OPENSANDBOX_HOST}}:{{OPENSANDBOX_PORT}}/v1/sandboxes/{id}/
 - No outbound network access by default (egress blocked)
 - Max 512 PIDs per sandbox (fork bomb protection)
 - Memory capped per sandbox (default 512MB)
+`,
+
+	"mem0-memory": `---
+name: mem0-memory
+description: "Store and retrieve long-term memories for AI agents using Mem0"
+metadata:
+  openclaw:
+    emoji: "🧠"
+---
+
+# Mem0 AI Memory
+
+Use Mem0 as a long-term memory layer for AI agents. Mem0 automatically extracts, stores, and retrieves memories across conversations using pgvector embeddings and Neo4j knowledge graphs.
+
+## Connection Details
+
+- **Host:** \`{{MEM0_HOST}}\`
+- **Port:** \`{{MEM0_PORT}}\`
+
+## Example API Calls
+
+### Add a memory
+\`\`\`bash
+curl -X POST "http://{{MEM0_HOST}}:{{MEM0_PORT}}/v1/memories/" \\
+  -H "Content-Type: application/json" \\
+  -d '{"messages": [{"role": "user", "content": "I prefer dark mode in all applications"}], "user_id": "agent-1"}'
+\`\`\`
+
+### Search memories
+\`\`\`bash
+curl -X POST "http://{{MEM0_HOST}}:{{MEM0_PORT}}/v1/memories/search/" \\
+  -H "Content-Type: application/json" \\
+  -d '{"query": "What are the user preferences?", "user_id": "agent-1"}'
+\`\`\`
+
+### Get all memories for a user
+\`\`\`bash
+curl "http://{{MEM0_HOST}}:{{MEM0_PORT}}/v1/memories/?user_id=agent-1"
+\`\`\`
+
+### Delete a memory
+\`\`\`bash
+curl -X DELETE "http://{{MEM0_HOST}}:{{MEM0_PORT}}/v1/memories/<memory_id>/"
+\`\`\`
+
+## Usage Notes
+
+- Mem0 automatically extracts facts and preferences from conversation messages.
+- Memories are stored as vector embeddings in pgvector and as entity relationships in Neo4j.
+- Use \`user_id\` to isolate memories per agent or per conversation context.
+- Mem0 handles deduplication and conflict resolution automatically.
+`,
+
+	"memu-memory": `---
+name: memu-memory
+description: "Persistent memory framework for proactive AI agents using MemU"
+metadata:
+  openclaw:
+    emoji: "🧠"
+---
+
+# MemU Persistent Memory
+
+Use MemU as a persistent memory framework for 24/7 proactive AI agents. MemU extracts structured memory from multimodal inputs and organizes it into a hierarchical knowledge graph.
+
+## Connection Details
+
+- **Host:** \`{{MEMU_HOST}}\`
+- **Port:** \`{{MEMU_PORT}}\`
+
+## Example API Calls
+
+### Store a memory
+\`\`\`bash
+curl -X POST "http://{{MEMU_HOST}}:{{MEMU_PORT}}/api/v1/memories" \\
+  -H "Content-Type: application/json" \\
+  -d '{"content": "User prefers TypeScript over JavaScript", "agent_id": "agent-1", "type": "preference"}'
+\`\`\`
+
+### Recall memories
+\`\`\`bash
+curl -X POST "http://{{MEMU_HOST}}:{{MEMU_PORT}}/api/v1/recall" \\
+  -H "Content-Type: application/json" \\
+  -d '{"query": "What programming languages does the user prefer?", "agent_id": "agent-1"}'
+\`\`\`
+
+### Get memory graph
+\`\`\`bash
+curl "http://{{MEMU_HOST}}:{{MEMU_PORT}}/api/v1/graph?agent_id=agent-1"
+\`\`\`
+
+## Usage Notes
+
+- MemU organizes memories into a hierarchical knowledge graph backed by pgvector.
+- Supports multimodal inputs (text, images, structured data).
+- Use \`agent_id\` to partition memories across different agents.
+`,
+
+	"hindsight-memory": `---
+name: hindsight-memory
+description: "Agent memory with Retain/Recall/Reflect operations using Hindsight"
+metadata:
+  openclaw:
+    emoji: "🧠"
+---
+
+# Hindsight Agent Memory
+
+Use Hindsight for agent memory with three core operations: Retain (store), Recall (retrieve), and Reflect (synthesize). Supports multi-strategy retrieval including semantic, keyword, graph, and temporal search.
+
+## Connection Details
+
+- **Host:** \`{{HINDSIGHT_HOST}}\`
+- **Port:** \`{{HINDSIGHT_API_PORT}}\`
+
+## Example API Calls
+
+### Retain (store a memory)
+\`\`\`bash
+curl -X POST "http://{{HINDSIGHT_HOST}}:{{HINDSIGHT_API_PORT}}/api/v1/retain" \\
+  -H "Content-Type: application/json" \\
+  -d '{"namespace": "agent-1", "content": "The deployment uses Kubernetes on AWS EKS", "metadata": {"source": "conversation"}}'
+\`\`\`
+
+### Recall (retrieve memories)
+\`\`\`bash
+curl -X POST "http://{{HINDSIGHT_HOST}}:{{HINDSIGHT_API_PORT}}/api/v1/recall" \\
+  -H "Content-Type: application/json" \\
+  -d '{"namespace": "agent-1", "query": "What infrastructure is used?", "strategies": ["semantic", "keyword"], "limit": 5}'
+\`\`\`
+
+### Reflect (synthesize memories)
+\`\`\`bash
+curl -X POST "http://{{HINDSIGHT_HOST}}:{{HINDSIGHT_API_PORT}}/api/v1/reflect" \\
+  -H "Content-Type: application/json" \\
+  -d '{"namespace": "agent-1", "query": "Summarize all infrastructure decisions"}'
+\`\`\`
+
+## MCP Integration
+
+Hindsight also exposes an MCP server. Configure your agent to connect via:
+\`\`\`
+http://{{HINDSIGHT_HOST}}:{{HINDSIGHT_API_PORT}}/mcp
+\`\`\`
+
+## Usage Notes
+
+- Use namespaces to isolate memories per agent, project, or session.
+- Retrieval strategies: semantic (embedding similarity), keyword (BM25), graph (entity relationships), temporal (time-based).
+- The Reflect operation uses LLM-powered synthesis to generate insights from stored memories.
+`,
+
+	"chromadb-memory": `---
+name: chromadb-memory
+description: "Store and retrieve vector embeddings using ChromaDB"
+metadata:
+  openclaw:
+    emoji: "🎨"
+---
+
+# ChromaDB Vector Memory
+
+Use ChromaDB as a vector database for storing embeddings, enabling semantic search and retrieval-augmented generation (RAG).
+
+## Connection Details
+
+- **Host:** \`{{CHROMADB_HOST}}\`
+- **Port:** \`{{CHROMADB_PORT}}\`
+
+## Example API Calls
+
+### Create a collection
+\`\`\`bash
+curl -X POST "http://{{CHROMADB_HOST}}:{{CHROMADB_PORT}}/api/v1/collections" \\
+  -H "Content-Type: application/json" \\
+  -d '{"name": "my_collection", "metadata": {"hnsw:space": "cosine"}}'
+\`\`\`
+
+### Add documents
+\`\`\`bash
+curl -X POST "http://{{CHROMADB_HOST}}:{{CHROMADB_PORT}}/api/v1/collections/<collection_id>/add" \\
+  -H "Content-Type: application/json" \\
+  -d '{"ids": ["doc1"], "documents": ["Hello world"], "metadatas": [{"source": "test"}]}'
+\`\`\`
+
+### Query similar documents
+\`\`\`bash
+curl -X POST "http://{{CHROMADB_HOST}}:{{CHROMADB_PORT}}/api/v1/collections/<collection_id>/query" \\
+  -H "Content-Type: application/json" \\
+  -d '{"query_texts": ["greeting"], "n_results": 5}'
+\`\`\`
+
+## Usage Notes
+
+- ChromaDB can auto-generate embeddings from documents if configured with an embedding function.
+- Supports metadata filtering on queries for precise retrieval.
+- Collections are isolated namespaces for different data domains.
+`,
+
+	"weaviate-memory": `---
+name: weaviate-memory
+description: "Store and search vectors with hybrid search using Weaviate"
+metadata:
+  openclaw:
+    emoji: "🔷"
+---
+
+# Weaviate Vector Memory
+
+Use Weaviate for vector storage with built-in hybrid search (combining vector similarity and keyword/BM25 search) and a GraphQL API.
+
+## Connection Details
+
+- **Host:** \`{{WEAVIATE_HOST}}\`
+- **Port:** \`{{WEAVIATE_PORT}}\`
+
+## Example API Calls
+
+### Create a class (schema)
+\`\`\`bash
+curl -X POST "http://{{WEAVIATE_HOST}}:{{WEAVIATE_PORT}}/v1/schema" \\
+  -H "Content-Type: application/json" \\
+  -d '{"class": "Document", "vectorizer": "none", "properties": [{"name": "content", "dataType": ["text"]}]}'
+\`\`\`
+
+### Add an object with vector
+\`\`\`bash
+curl -X POST "http://{{WEAVIATE_HOST}}:{{WEAVIATE_PORT}}/v1/objects" \\
+  -H "Content-Type: application/json" \\
+  -d '{"class": "Document", "properties": {"content": "Hello world"}, "vector": [0.1, 0.2, 0.3]}'
+\`\`\`
+
+### Hybrid search (vector + keyword)
+\`\`\`bash
+curl -X POST "http://{{WEAVIATE_HOST}}:{{WEAVIATE_PORT}}/v1/graphql" \\
+  -H "Content-Type: application/json" \\
+  -d '{"query": "{ Get { Document(hybrid: { query: \\"hello\\" alpha: 0.5 }) { content _additional { score } } } }"}'
+\`\`\`
+
+## Usage Notes
+
+- Weaviate supports hybrid search combining BM25 keyword search with vector similarity.
+- Use the alpha parameter to balance between keyword (0.0) and vector (1.0) search.
+- GraphQL API provides flexible querying with filters, aggregations, and cross-references.
 `,
 };
 

package/src/generators/traefik.test.ts

@@ -27,11 +27,11 @@ describe("generateTraefikConfig", () => {
 
 		const redisLabels = serviceLabels.get("redis");
 		expect(redisLabels).toBeDefined();
-		expect(redisLabels!["traefik.enable"]).toBe("true");
-		expect(redisLabels!["traefik.http.routers.redis.rule"]).toBe("Host(`redis.example.com`)");
-		expect(redisLabels!["traefik.http.routers.redis.entrypoints"]).toBe("websecure");
-		expect(redisLabels!["traefik.http.routers.redis.tls.certresolver"]).toBe("letsencrypt");
-		expect(redisLabels!["traefik.http.services.redis.loadbalancer.server.port"]).toBe("6379");
+		expect(redisLabels?.["traefik.enable"]).toBe("true");
+		expect(redisLabels?.["traefik.http.routers.redis.rule"]).toBe("Host(`redis.example.com`)");
+		expect(redisLabels?.["traefik.http.routers.redis.entrypoints"]).toBe("websecure");
+		expect(redisLabels?.["traefik.http.routers.redis.tls.certresolver"]).toBe("letsencrypt");
+		expect(redisLabels?.["traefik.http.services.redis.loadbalancer.server.port"]).toBe("6379");
 	});
 
 	it("generates HTTP to HTTPS redirect labels", () => {
@@ -49,8 +49,8 @@ describe("generateTraefikConfig", () => {
 
 		const gwLabels = serviceLabels.get("openclaw-gateway");
 		expect(gwLabels).toBeDefined();
-		expect(gwLabels!["traefik.http.routers.gateway.rule"]).toBe("Host(`example.com`)");
-		expect(gwLabels!["traefik.http.services.gateway.loadbalancer.server.port"]).toBe("18789");
+		expect(gwLabels?.["traefik.http.routers.gateway.rule"]).toBe("Host(`example.com`)");
+		expect(gwLabels?.["traefik.http.services.gateway.loadbalancer.server.port"]).toBe("18789");
 	});
 
 	it("adds global redirect middleware on traefik service", () => {
@@ -59,11 +59,11 @@ describe("generateTraefikConfig", () => {
 
 		const traefikLabels = serviceLabels.get("traefik");
 		expect(traefikLabels).toBeDefined();
-		expect(traefikLabels!["traefik.http.middlewares.redirect-to-https.redirectscheme.scheme"]).toBe(
-			"https",
-		);
 		expect(
-			traefikLabels!["traefik.http.middlewares.redirect-to-https.redirectscheme.permanent"],
+			traefikLabels?.["traefik.http.middlewares.redirect-to-https.redirectscheme.scheme"],
+		).toBe("https");
+		expect(
+			traefikLabels?.["traefik.http.middlewares.redirect-to-https.redirectscheme.permanent"],
 		).toBe("true");
 	});
 
@@ -74,7 +74,7 @@ describe("generateTraefikConfig", () => {
 		// ffmpeg has no exposed ports
 		expect(serviceLabels.has("ffmpeg")).toBe(false);
 		// traefik itself is handled separately (not as a regular service)
-		expect(serviceLabels.get("traefik")!["traefik.http.routers.traefik.rule"]).toBeUndefined();
+		expect(serviceLabels.get("traefik")?.["traefik.http.routers.traefik.rule"]).toBeUndefined();
 	});
 
 	it("sanitizes service names with hyphens in router names", () => {
@@ -84,6 +84,6 @@ describe("generateTraefikConfig", () => {
 		const labels = serviceLabels.get("open-webui");
 		expect(labels).toBeDefined();
 		// Router name has hyphens removed
-		expect(labels!["traefik.http.routers.openwebui.rule"]).toBe("Host(`open-webui.example.com`)");
+		expect(labels?.["traefik.http.routers.openwebui.rule"]).toBe("Host(`open-webui.example.com`)");
 	});
 });

package/src/index.ts

@@ -1,6 +1,5 @@
 // ─── Addon Stack (Clawexa) ──────────────────────────────────────────────────
 export { generateAddonStack, updateAddonStack } from "./addon-stack.js";
-
 // ─── Core Engines ───────────────────────────────────────────────────────────
 export {
 	partitionBareMetal,
@@ -8,7 +7,14 @@ export {
 	resolvedWithOnlyServices,
 } from "./bare-metal-partition.js";
 export type { ComposeResult } from "./composer.js";
-export { buildCompanionService, buildPostgresSetup, compose, composeMultiFile, quotedStr, YAML_OPTIONS } from "./composer.js";
+export {
+	buildCompanionService,
+	buildPostgresSetup,
+	compose,
+	composeMultiFile,
+	quotedStr,
+	YAML_OPTIONS,
+} from "./composer.js";
 // ─── PaaS Deployers ─────────────────────────────────────────────────────────
 export type {
 	DeployInput as PaasDeployInput,
@@ -27,6 +33,18 @@ export {
 } from "./deployers/index.js";
 // ─── Errors ─────────────────────────────────────────────────────────────────
 export { StackConfigError, ValidationError } from "./errors.js";
+// ─── Agent Frameworks ───────────────────────────────────────────────────────
+export type {
+	AgentFrameworkDefinition,
+	AgentFrameworkId,
+} from "./frameworks/index.js";
+export {
+	getAllFrameworks,
+	getCompanionFrameworks,
+	getFrameworkById,
+	getPrimaryFrameworks,
+	registerFramework,
+} from "./frameworks/index.js";
 export { generate, generateServicesDoc } from "./generate.js";
 export { generateCaddyfile } from "./generators/caddy.js";
 export { generateCloneScripts } from "./generators/clone-repos.js";
@@ -46,15 +64,31 @@ export { generatePrometheusConfig } from "./generators/prometheus.js";
 export { generateReadme } from "./generators/readme.js";
 export { generateScripts } from "./generators/scripts.js";
 export { generateSkillFiles } from "./generators/skills.js";
-// ─── Analytics ─────────────────────────────────────────────────────────────
-export type { AnalyticsPayload } from "./track-analytics.js";
-export { buildAnalyticsPayload, trackAnalytics } from "./track-analytics.js";
 export type {
 	StackManifest,
 	StackManifestService,
 	StackManifestSkill,
 } from "./generators/stack-manifest.js";
 export { generateStackManifest } from "./generators/stack-manifest.js";
+export type {
+	LogLevel,
+	LogSink,
+	LogSource,
+	OperationCategory,
+	OperationOutcome,
+	OperationStep,
+	OperationsLogEntry,
+	OperationsLoggerOptions,
+} from "./logger/index.js";
+// ─── Operations Logger ─────────────────────────────────────────────────────
+export {
+	CallbackSink,
+	ConsoleSink,
+	FileSink,
+	OperationsLogger,
+	StepTracker,
+} from "./logger/index.js";
+export type { FileSinkOptions } from "./logger/sinks/file-sink.js";
 // ─── Config Migrations ──────────────────────────────────────────────────────
 export {
 	CURRENT_CONFIG_VERSION,
@@ -72,11 +106,12 @@ export {
 } from "./presets/registry.js";
 export { resolve } from "./resolver.js";
 export {
+	AddedDependencySchema,
 	AddonStackInputSchema,
 	AddonStackResultSchema,
 	AddonStackUpdateInputSchema,
 	AddonStackUpdateResultSchema,
-	AddedDependencySchema,
+	AgentFrameworkSchema,
 	ApiErrorSchema,
 	BuildContextSchema,
 	ComposeOptionsSchema,
@@ -138,13 +173,17 @@ export {
 	getManifestSkillById,
 	getManifestSkillCount,
 } from "./skills/skill-manifest.js";
+// ─── Analytics ─────────────────────────────────────────────────────────────
+export type { AnalyticsPayload } from "./track-analytics.js";
+export { buildAnalyticsPayload, trackAnalytics } from "./track-analytics.js";
 // ─── Types ──────────────────────────────────────────────────────────────────
 export type {
+	AddedDependency,
 	AddonStackInput,
 	AddonStackResult,
 	AddonStackUpdateInput,
 	AddonStackUpdateResult,
-	AddedDependency,
+	AgentFramework,
 	AiProvider,
 	ApiError,
 	BuildContext,