@omnidev-ai/core 0.6.2 → 0.8.0

package/dist/index.d.ts

@@ -190,12 +190,37 @@ interface McpToolSchema {
 	description: string;
 	inputSchema: Record<string, unknown>;
 }
+/**
+* MCP server configuration supporting multiple transport types:
+*
+* - **stdio**: Local process using stdin/stdout (default)
+*   - Requires: command
+*   - Optional: args, env, cwd
+*
+* - **http**: Remote HTTP server (recommended for remote servers)
+*   - Requires: url
+*   - Optional: headers (for authentication)
+*
+* - **sse**: Server-Sent Events (deprecated, use http instead)
+*   - Requires: url
+*   - Optional: headers (for authentication)
+*/
 interface McpConfig {
-	command: string;
+	/** Executable to run (required for stdio transport) */
+	command?: string;
+	/** Command arguments (stdio transport only) */
 	args?: string[];
+	/** Environment variables (stdio transport only) */
 	env?: Record<string, string>;
+	/** Working directory (stdio transport only) */
 	cwd?: string;
+	/** Transport type: stdio (default), http, or sse */
 	transport?: McpTransport;
+	/** URL for remote servers (required for http/sse transport) */
+	url?: string;
+	/** HTTP headers for authentication (http/sse transport only) */
+	headers?: Record<string, string>;
+	/** Tool schemas (optional, for documentation) */
 	tools?: McpToolSchema[];
 }
 interface Skill {
@@ -585,6 +610,12 @@ declare function validateEnv(declarations: Record<string, EnvDeclaration | Recor
 */
 declare function isSecretEnvVar(key: string, declarations: Record<string, EnvDeclaration | Record<string, never>>): boolean;
 /**
+* Load only the base config file (omni.toml) without merging local overrides.
+* Use this when you need to modify and write back to omni.toml.
+* @returns OmniConfig from omni.toml only
+*/
+declare function loadBaseConfig(): Promise<OmniConfig>;
+/**
 * Load and merge config and local configuration files
 * @returns Merged OmniConfig object
 *
@@ -697,14 +728,34 @@ declare function buildManifestFromCapabilities(capabilities: LoadedCapability[])
 */
 declare function cleanupStaleResources(previousManifest: ResourceManifest, currentCapabilityIds: Set<string>): Promise<CleanupResult>;
 /**
-* MCP server configuration in .mcp.json
+* MCP server configuration in .mcp.json for stdio transport
 */
-interface McpServerConfig {
+interface McpServerStdioConfig {
 	command: string;
 	args?: string[];
 	env?: Record<string, string>;
 }
 /**
+* MCP server configuration in .mcp.json for HTTP transport
+*/
+interface McpServerHttpConfig {
+	type: "http";
+	url: string;
+	headers?: Record<string, string>;
+}
+/**
+* MCP server configuration in .mcp.json for SSE transport
+*/
+interface McpServerSseConfig {
+	type: "sse";
+	url: string;
+	headers?: Record<string, string>;
+}
+/**
+* Union type for all MCP server configurations
+*/
+type McpServerConfig = McpServerStdioConfig | McpServerHttpConfig | McpServerSseConfig;
+/**
 * Structure of .mcp.json file
 */
 interface McpJsonConfig {
@@ -817,9 +868,15 @@ declare function generateClaudeTemplate(): string;
 */
 declare function generateInstructionsTemplate(): string;
 /**
+* Template for OMNI.md - the user's project instructions file.
+* This is the single source of truth that gets transformed into
+* provider-specific files (CLAUDE.md, AGENTS.md, etc.) during sync.
+*/
+declare function generateOmniMdTemplate(): string;
+/**
 * Debug logger that writes to stdout when OMNIDEV_DEBUG=1
 */
 declare function debug(message: string, data?: unknown): void;
 declare const version = "0.1.0";
 declare function getVersion(): string;
-export { writeRules, writeProviderConfig, writeMcpJson, writeEnabledProviders, writeConfig, writeActiveProfileState, version, validateEnv, syncMcpJson, syncAgentConfiguration, sourceToGitUrl, setProfile, setActiveProfile, saveManifest, saveLockFile, resolveEnabledCapabilities, readMcpJson, readEnabledProviders, readActiveProfileState, parseSourceConfig, parseProviderFlag, parseOmniConfig, parseCapabilityConfig, loadSubagents, loadSkills, loadRules, loadProviderConfig, loadProfileConfig, loadManifest, loadLockFile, loadEnvironment, loadDocs, loadConfig, loadCommands, loadCapabilityConfig, loadCapability, isSecretEnvVar, isProviderEnabled, installCapabilityDependencies, getVersion, getSourceCapabilityPath, getLockFilePath, getEnabledCapabilities, getActiveProviders, getActiveProfile, generateInstructionsTemplate, generateClaudeTemplate, generateAgentsTemplate, fetchCapabilitySource, fetchAllCapabilitySources, enableProvider, enableCapability, discoverCapabilities, disableProvider, disableCapability, debug, clearActiveProfileState, cleanupStaleResources, checkForUpdates, buildSyncBundle, buildRouteMap, buildManifestFromCapabilities, buildCommand, buildCapabilityRegistry, SyncResult, SyncOptions, SyncConfig, SyncBundle, SubagentPermissionMode, SubagentModel, SubagentHooks, SubagentHookConfig, SubagentExport, Subagent, SourceUpdateInfo, SkillExport, Skill, Rule, ResourceManifest, ProvidersState, ProviderSyncResult, ProviderManifest, ProviderInitResult, ProviderId, ProviderContext, ProviderConfig, ProviderAdapter, Provider, ProfileConfig, OmniConfig, McpTransport, McpToolSchema, McpServerConfig, McpJsonConfig, McpConfig, LoadedCapability, GitCapabilitySourceConfig, FileContent, FetchResult, EnvDeclaration, DocExport, Doc, DiscoveredContent, CommandExport, Command, CliConfig, CleanupResult, CapabilitySourceType, CapabilitySourceConfig, CapabilitySource, CapabilityResources, CapabilityRegistry, CapabilityMetadata, CapabilityLockEntry, CapabilityExports, CapabilityExport, CapabilityConfig, CapabilitiesLockFile, CapabilitiesConfig };
+export { writeRules, writeProviderConfig, writeMcpJson, writeEnabledProviders, writeConfig, writeActiveProfileState, version, validateEnv, syncMcpJson, syncAgentConfiguration, sourceToGitUrl, setProfile, setActiveProfile, saveManifest, saveLockFile, resolveEnabledCapabilities, readMcpJson, readEnabledProviders, readActiveProfileState, parseSourceConfig, parseProviderFlag, parseOmniConfig, parseCapabilityConfig, loadSubagents, loadSkills, loadRules, loadProviderConfig, loadProfileConfig, loadManifest, loadLockFile, loadEnvironment, loadDocs, loadConfig, loadCommands, loadCapabilityConfig, loadCapability, loadBaseConfig, isSecretEnvVar, isProviderEnabled, installCapabilityDependencies, getVersion, getSourceCapabilityPath, getLockFilePath, getEnabledCapabilities, getActiveProviders, getActiveProfile, generateOmniMdTemplate, generateInstructionsTemplate, generateClaudeTemplate, generateAgentsTemplate, fetchCapabilitySource, fetchAllCapabilitySources, enableProvider, enableCapability, discoverCapabilities, disableProvider, disableCapability, debug, clearActiveProfileState, cleanupStaleResources, checkForUpdates, buildSyncBundle, buildRouteMap, buildManifestFromCapabilities, buildCommand, buildCapabilityRegistry, SyncResult, SyncOptions, SyncConfig, SyncBundle, SubagentPermissionMode, SubagentModel, SubagentHooks, SubagentHookConfig, SubagentExport, Subagent, SourceUpdateInfo, SkillExport, Skill, Rule, ResourceManifest, ProvidersState, ProviderSyncResult, ProviderManifest, ProviderInitResult, ProviderId, ProviderContext, ProviderConfig, ProviderAdapter, Provider, ProfileConfig, OmniConfig, McpTransport, McpToolSchema, McpServerStdioConfig, McpServerSseConfig, McpServerHttpConfig, McpServerConfig, McpJsonConfig, McpConfig, LoadedCapability, GitCapabilitySourceConfig, FileContent, FetchResult, EnvDeclaration, DocExport, Doc, DiscoveredContent, CommandExport, Command, CliConfig, CleanupResult, CapabilitySourceType, CapabilitySourceConfig, CapabilitySource, CapabilityResources, CapabilityRegistry, CapabilityMetadata, CapabilityLockEntry, CapabilityExports, CapabilityExport, CapabilityConfig, CapabilitiesLockFile, CapabilitiesConfig };

package/dist/index.js

@@ -691,13 +691,16 @@ function mergeConfigs(base, override) {
   }
   return merged;
 }
-async function loadConfig() {
-  let baseConfig = {};
-  let localConfig = {};
+async function loadBaseConfig() {
   if (existsSync8(CONFIG_PATH)) {
     const content = await readFile8(CONFIG_PATH, "utf-8");
-    baseConfig = parseOmniConfig(content);
+    return parseOmniConfig(content);
   }
+  return {};
+}
+async function loadConfig() {
+  const baseConfig = await loadBaseConfig();
+  let localConfig = {};
   if (existsSync8(LOCAL_CONFIG)) {
     const content = await readFile8(LOCAL_CONFIG, "utf-8");
     localConfig = parseOmniConfig(content);
@@ -726,10 +729,6 @@ function generateConfigToml(config) {
   lines.push("#   3. Run: omnidev sync");
   lines.push("#   4. Switch profiles: omnidev profile use <name>");
   lines.push("");
-  if (config.project) {
-    lines.push(`project = "${config.project}"`);
-    lines.push("");
-  }
   if (config.providers?.enabled && config.providers.enabled.length > 0) {
     lines.push("# AI providers to enable (claude, codex, or both)");
     lines.push("[providers]");
@@ -759,16 +758,30 @@ function generateConfigToml(config) {
   lines.push("# Fetch capabilities from Git repositories. On sync, these are");
   lines.push("# cloned/updated and made available to your profiles.");
   lines.push("#");
-  lines.push("# [capabilities.sources]");
-  lines.push("# # GitHub shorthand (uses latest commit)");
-  lines.push('# tasks = "github:example-org/tasks-capability"');
-  lines.push("#");
-  lines.push("# # Version pinning (recommended for production)");
-  lines.push('# ralph = { source = "github:example-org/ralph", ref = "v1.2.0" }');
-  lines.push("#");
-  lines.push("# # Other Git sources");
-  lines.push('# private = "git@github.com:company/private-cap.git"');
-  lines.push('# gitlab = "https://gitlab.com/user/capability.git"');
+  const sources = config.capabilities?.sources;
+  if (sources && Object.keys(sources).length > 0) {
+    lines.push("[capabilities.sources]");
+    for (const [name, sourceConfig] of Object.entries(sources)) {
+      if (typeof sourceConfig === "string") {
+        lines.push(`${name} = "${sourceConfig}"`);
+      } else if (sourceConfig.path) {
+        lines.push(`${name} = { source = "${sourceConfig.source}", path = "${sourceConfig.path}" }`);
+      } else {
+        lines.push(`${name} = "${sourceConfig.source}"`);
+      }
+    }
+  } else {
+    lines.push("# [capabilities.sources]");
+    lines.push("# # GitHub shorthand (uses latest commit)");
+    lines.push('# tasks = "github:example-org/tasks-capability"');
+    lines.push("#");
+    lines.push("# # With subdirectory path");
+    lines.push('# ralph = { source = "github:example-org/ralph", path = "plugins/my-cap" }');
+    lines.push("#");
+    lines.push("# # Other Git sources");
+    lines.push('# private = "git@github.com:company/private-cap.git"');
+    lines.push('# gitlab = "https://gitlab.com/user/capability.git"');
+  }
   lines.push("");
   lines.push("# =============================================================================");
   lines.push("# MCP Servers");
@@ -776,25 +789,66 @@ function generateConfigToml(config) {
   lines.push("# Define MCP servers that automatically become capabilities.");
   lines.push('# Reference in profiles using the MCP name directly, e.g. capabilities = ["filesystem"]');
   lines.push("#");
-  lines.push("# [mcps.filesystem]");
-  lines.push('# command = "npx"');
-  lines.push('# args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]');
-  lines.push('# transport = "stdio"  # stdio (default), sse, or http');
-  lines.push("#");
-  lines.push("# [mcps.database]");
-  lines.push('# command = "node"');
-  lines.push('# args = ["./servers/database.js"]');
-  lines.push('# cwd = "./mcp-servers"');
-  lines.push("# [mcps.database.env]");
-  lines.push('# DB_URL = "${DATABASE_URL}"');
-  lines.push("");
+  const mcps = config.mcps;
+  if (mcps && Object.keys(mcps).length > 0) {
+    for (const [name, mcpConfig] of Object.entries(mcps)) {
+      lines.push(`[mcps.${name}]`);
+      if (mcpConfig.transport && mcpConfig.transport !== "stdio") {
+        lines.push(`transport = "${mcpConfig.transport}"`);
+      }
+      if (mcpConfig.command) {
+        lines.push(`command = "${mcpConfig.command}"`);
+      }
+      if (mcpConfig.args && mcpConfig.args.length > 0) {
+        const argsStr = mcpConfig.args.map((a) => `"${a}"`).join(", ");
+        lines.push(`args = [${argsStr}]`);
+      }
+      if (mcpConfig.cwd) {
+        lines.push(`cwd = "${mcpConfig.cwd}"`);
+      }
+      if (mcpConfig.url) {
+        lines.push(`url = "${mcpConfig.url}"`);
+      }
+      if (mcpConfig.env && Object.keys(mcpConfig.env).length > 0) {
+        lines.push(`[mcps.${name}.env]`);
+        for (const [key, value] of Object.entries(mcpConfig.env)) {
+          lines.push(`${key} = "${value}"`);
+        }
+      }
+      if (mcpConfig.headers && Object.keys(mcpConfig.headers).length > 0) {
+        lines.push(`[mcps.${name}.headers]`);
+        for (const [key, value] of Object.entries(mcpConfig.headers)) {
+          lines.push(`${key} = "${value}"`);
+        }
+      }
+      lines.push("");
+    }
+  } else {
+    lines.push("# [mcps.filesystem]");
+    lines.push('# command = "npx"');
+    lines.push('# args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]');
+    lines.push('# transport = "stdio"  # stdio (default), sse, or http');
+    lines.push("#");
+    lines.push("# [mcps.database]");
+    lines.push('# command = "node"');
+    lines.push('# args = ["./servers/database.js"]');
+    lines.push('# cwd = "./mcp-servers"');
+    lines.push("# [mcps.database.env]");
+    lines.push('# DB_URL = "${DATABASE_URL}"');
+    lines.push("");
+  }
   lines.push("# =============================================================================");
   lines.push("# Always Enabled Capabilities");
   lines.push("# =============================================================================");
   lines.push("# Capabilities that load in ALL profiles, regardless of profile config.");
   lines.push("# Useful for essential tools needed everywhere.");
   lines.push("#");
-  lines.push('# always_enabled_capabilities = ["git-tools", "linting"]');
+  if (config.always_enabled_capabilities && config.always_enabled_capabilities.length > 0) {
+    const caps = config.always_enabled_capabilities.map((c) => `"${c}"`).join(", ");
+    lines.push(`always_enabled_capabilities = [${caps}]`);
+  } else {
+    lines.push('# always_enabled_capabilities = ["git-tools", "linting"]');
+  }
   lines.push("");
   lines.push("# =============================================================================");
   lines.push("# Profiles");
@@ -883,7 +937,7 @@ async function getEnabledCapabilities() {
   return resolveEnabledCapabilities(config, activeProfile);
 }
 async function enableCapability(capabilityId) {
-  const config = await loadConfig();
+  const config = await loadBaseConfig();
   const activeProfile = await getActiveProfile() ?? config.active_profile ?? "default";
   if (!config.profiles) {
     config.profiles = {};
@@ -897,7 +951,7 @@ async function enableCapability(capabilityId) {
   await writeConfig(config);
 }
 async function disableCapability(capabilityId) {
-  const config = await loadConfig();
+  const config = await loadBaseConfig();
   const activeProfile = await getActiveProfile() ?? config.active_profile ?? "default";
   if (!config.profiles?.[activeProfile]) {
     return;
@@ -1389,6 +1443,8 @@ async function fetchCapabilitySource(id, sourceConfig, options) {
   return fetchGitCapabilitySource(id, config, options);
 }
 function generateMcpCapabilityTomlContent(id, mcpConfig) {
+  const transport = mcpConfig.transport ?? "stdio";
+  const isRemote = transport === "http" || transport === "sse";
   let tomlContent = `# Auto-generated by OmniDev from omni.toml [mcps] section - DO NOT EDIT
 
 [capability]
@@ -1402,21 +1458,42 @@ wrapped = true
 generated_from_omni_toml = true
 
 [mcp]
-command = "${mcpConfig.command}"
 `;
-  if (mcpConfig.args && mcpConfig.args.length > 0) {
-    tomlContent += `args = ${JSON.stringify(mcpConfig.args)}
+  if (isRemote) {
+    tomlContent += `transport = "${transport}"
 `;
-  }
-  if (mcpConfig.transport) {
-    tomlContent += `transport = "${mcpConfig.transport}"
+    if (mcpConfig.url) {
+      tomlContent += `url = "${mcpConfig.url}"
+`;
+    }
+  } else {
+    if (mcpConfig.command) {
+      tomlContent += `command = "${mcpConfig.command}"
+`;
+    }
+    if (mcpConfig.args && mcpConfig.args.length > 0) {
+      tomlContent += `args = ${JSON.stringify(mcpConfig.args)}
+`;
+    }
+    if (mcpConfig.transport) {
+      tomlContent += `transport = "${mcpConfig.transport}"
+`;
+    }
+    if (mcpConfig.cwd) {
+      tomlContent += `cwd = "${mcpConfig.cwd}"
 `;
+    }
   }
-  if (mcpConfig.cwd) {
-    tomlContent += `cwd = "${mcpConfig.cwd}"
+  if (isRemote && mcpConfig.headers && Object.keys(mcpConfig.headers).length > 0) {
+    tomlContent += `
+[mcp.headers]
 `;
+    for (const [key, value] of Object.entries(mcpConfig.headers)) {
+      tomlContent += `"${key}" = "${value}"
+`;
+    }
   }
-  if (mcpConfig.env && Object.keys(mcpConfig.env).length > 0) {
+  if (!isRemote && mcpConfig.env && Object.keys(mcpConfig.env).length > 0) {
     tomlContent += `
 [mcp.env]
 `;
@@ -1653,6 +1730,36 @@ async function writeMcpJson(config) {
 `, "utf-8");
 }
 function buildMcpServerConfig(mcp) {
+  const transport = mcp.transport ?? "stdio";
+  if (transport === "http") {
+    if (!mcp.url) {
+      throw new Error("HTTP transport requires a URL");
+    }
+    const config2 = {
+      type: "http",
+      url: mcp.url
+    };
+    if (mcp.headers && Object.keys(mcp.headers).length > 0) {
+      config2.headers = mcp.headers;
+    }
+    return config2;
+  }
+  if (transport === "sse") {
+    if (!mcp.url) {
+      throw new Error("SSE transport requires a URL");
+    }
+    const config2 = {
+      type: "sse",
+      url: mcp.url
+    };
+    if (mcp.headers && Object.keys(mcp.headers).length > 0) {
+      config2.headers = mcp.headers;
+    }
+    return config2;
+  }
+  if (!mcp.command) {
+    throw new Error("stdio transport requires a command");
+  }
   const config = {
     command: mcp.command
   };
@@ -2046,6 +2153,27 @@ No capabilities enabled yet. Run \`omnidev capability enable <name>\` to enable
 <!-- END OMNIDEV GENERATED CONTENT -->
 `;
 }
+// src/templates/omni.ts
+function generateOmniMdTemplate() {
+  return `# Project Instructions
+
+<!-- This file is your project's instruction manifest for AI agents. -->
+<!-- It will be combined with capability-generated content during sync. -->
+
+## Project Description
+
+<!-- TODO: Add 2-3 sentences describing your project -->
+[Describe what this project does and its main purpose]
+
+## Conventions
+
+<!-- Add your project conventions, coding standards, and guidelines here -->
+
+## Architecture
+
+<!-- Describe your project's architecture and key components -->
+`;
+}
 // src/types/index.ts
 function getActiveProviders(config) {
   if (config.providers)
@@ -2111,6 +2239,7 @@ export {
   loadCommands,
   loadCapabilityConfig,
   loadCapability,
+  loadBaseConfig,
   isSecretEnvVar,
   isProviderEnabled,
   installCapabilityDependencies,
@@ -2120,6 +2249,7 @@ export {
   getEnabledCapabilities,
   getActiveProviders,
   getActiveProfile,
+  generateOmniMdTemplate,
   generateInstructionsTemplate,
   generateClaudeTemplate,
   generateAgentsTemplate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnidev-ai/core",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/capability/sources.ts

@@ -752,6 +752,9 @@ function generateMcpCapabilityTomlContent(
 	id: string,
 	mcpConfig: import("../types/index.js").McpConfig,
 ): string {
+	const transport = mcpConfig.transport ?? "stdio";
+	const isRemote = transport === "http" || transport === "sse";
+
 	let tomlContent = `# Auto-generated by OmniDev from omni.toml [mcps] section - DO NOT EDIT
 
 [capability]
@@ -765,22 +768,43 @@ wrapped = true
 generated_from_omni_toml = true
 
 [mcp]
-command = "${mcpConfig.command}"
 `;
 
-	if (mcpConfig.args && mcpConfig.args.length > 0) {
-		tomlContent += `args = ${JSON.stringify(mcpConfig.args)}\n`;
-	}
+	// For remote transports (http/sse), url is required
+	if (isRemote) {
+		tomlContent += `transport = "${transport}"\n`;
+		if (mcpConfig.url) {
+			tomlContent += `url = "${mcpConfig.url}"\n`;
+		}
+	} else {
+		// For stdio transport, command is required
+		if (mcpConfig.command) {
+			tomlContent += `command = "${mcpConfig.command}"\n`;
+		}
 
-	if (mcpConfig.transport) {
-		tomlContent += `transport = "${mcpConfig.transport}"\n`;
+		if (mcpConfig.args && mcpConfig.args.length > 0) {
+			tomlContent += `args = ${JSON.stringify(mcpConfig.args)}\n`;
+		}
+
+		if (mcpConfig.transport) {
+			tomlContent += `transport = "${mcpConfig.transport}"\n`;
+		}
+
+		if (mcpConfig.cwd) {
+			tomlContent += `cwd = "${mcpConfig.cwd}"\n`;
+		}
 	}
 
-	if (mcpConfig.cwd) {
-		tomlContent += `cwd = "${mcpConfig.cwd}"\n`;
+	// Headers for remote transports
+	if (isRemote && mcpConfig.headers && Object.keys(mcpConfig.headers).length > 0) {
+		tomlContent += `\n[mcp.headers]\n`;
+		for (const [key, value] of Object.entries(mcpConfig.headers)) {
+			tomlContent += `"${key}" = "${value}"\n`;
+		}
 	}
 
-	if (mcpConfig.env && Object.keys(mcpConfig.env).length > 0) {
+	// Env variables for stdio transport
+	if (!isRemote && mcpConfig.env && Object.keys(mcpConfig.env).length > 0) {
 		tomlContent += `\n[mcp.env]\n`;
 		for (const [key, value] of Object.entries(mcpConfig.env)) {
 			tomlContent += `${key} = "${value}"\n`;

package/src/config/capabilities.ts

@@ -1,4 +1,4 @@
-import { loadConfig, writeConfig } from "./loader.js";
+import { loadBaseConfig, loadConfig, writeConfig } from "./loader.js";
 import { getActiveProfile, resolveEnabledCapabilities } from "./profiles.js";
 
 /**
@@ -17,7 +17,8 @@ export async function getEnabledCapabilities(): Promise<string[]> {
  * @param capabilityId - The ID of the capability to enable
  */
 export async function enableCapability(capabilityId: string): Promise<void> {
-	const config = await loadConfig();
+	// Use loadBaseConfig to avoid writing local overrides to omni.toml
+	const config = await loadBaseConfig();
 	const activeProfile = (await getActiveProfile()) ?? config.active_profile ?? "default";
 
 	if (!config.profiles) {
@@ -39,7 +40,8 @@ export async function enableCapability(capabilityId: string): Promise<void> {
  * @param capabilityId - The ID of the capability to disable
  */
 export async function disableCapability(capabilityId: string): Promise<void> {
-	const config = await loadConfig();
+	// Use loadBaseConfig to avoid writing local overrides to omni.toml
+	const config = await loadBaseConfig();
 	const activeProfile = (await getActiveProfile()) ?? config.active_profile ?? "default";
 
 	if (!config.profiles?.[activeProfile]) {

package/src/config/loader.ts

@@ -35,6 +35,19 @@ function mergeConfigs(base: OmniConfig, override: OmniConfig): OmniConfig {
 	return merged;
 }
 
+/**
+ * Load only the base config file (omni.toml) without merging local overrides.
+ * Use this when you need to modify and write back to omni.toml.
+ * @returns OmniConfig from omni.toml only
+ */
+export async function loadBaseConfig(): Promise<OmniConfig> {
+	if (existsSync(CONFIG_PATH)) {
+		const content = await readFile(CONFIG_PATH, "utf-8");
+		return parseOmniConfig(content);
+	}
+	return {};
+}
+
 /**
  * Load and merge config and local configuration files
  * @returns Merged OmniConfig object
@@ -43,14 +56,9 @@ function mergeConfigs(base: OmniConfig, override: OmniConfig): OmniConfig {
  * Local config takes precedence over main config. Missing files are treated as empty configs.
  */
 export async function loadConfig(): Promise<OmniConfig> {
-	let baseConfig: OmniConfig = {};
+	const baseConfig = await loadBaseConfig();
 	let localConfig: OmniConfig = {};
 
-	if (existsSync(CONFIG_PATH)) {
-		const content = await readFile(CONFIG_PATH, "utf-8");
-		baseConfig = parseOmniConfig(content);
-	}
-
 	if (existsSync(LOCAL_CONFIG)) {
 		const content = await readFile(LOCAL_CONFIG, "utf-8");
 		localConfig = parseOmniConfig(content);
@@ -93,12 +101,6 @@ function generateConfigToml(config: OmniConfig): string {
 	lines.push("#   4. Switch profiles: omnidev profile use <name>");
 	lines.push("");
 
-	// Project name
-	if (config.project) {
-		lines.push(`project = "${config.project}"`);
-		lines.push("");
-	}
-
 	// Note: active_profile is stored in .omni/state/active-profile, not in config.toml
 	// We still read it from config.toml for backwards compatibility, but don't write it here
 
@@ -132,26 +134,46 @@ function generateConfigToml(config: OmniConfig): string {
 	}
 	lines.push("");
 
-	// Capability sources (commented examples)
+	// Capability sources
 	lines.push("# =============================================================================");
 	lines.push("# Capability Sources");
 	lines.push("# =============================================================================");
 	lines.push("# Fetch capabilities from Git repositories. On sync, these are");
 	lines.push("# cloned/updated and made available to your profiles.");
 	lines.push("#");
-	lines.push("# [capabilities.sources]");
-	lines.push("# # GitHub shorthand (uses latest commit)");
-	lines.push('# tasks = "github:example-org/tasks-capability"');
-	lines.push("#");
-	lines.push("# # Version pinning (recommended for production)");
-	lines.push('# ralph = { source = "github:example-org/ralph", ref = "v1.2.0" }');
-	lines.push("#");
-	lines.push("# # Other Git sources");
-	lines.push('# private = "git@github.com:company/private-cap.git"');
-	lines.push('# gitlab = "https://gitlab.com/user/capability.git"');
+
+	const sources = config.capabilities?.sources;
+	if (sources && Object.keys(sources).length > 0) {
+		lines.push("[capabilities.sources]");
+		for (const [name, sourceConfig] of Object.entries(sources)) {
+			if (typeof sourceConfig === "string") {
+				// Simple string source
+				lines.push(`${name} = "${sourceConfig}"`);
+			} else if (sourceConfig.path) {
+				// Full config object with path
+				lines.push(
+					`${name} = { source = "${sourceConfig.source}", path = "${sourceConfig.path}" }`,
+				);
+			} else {
+				// Full config object without path - just write the source
+				lines.push(`${name} = "${sourceConfig.source}"`);
+			}
+		}
+	} else {
+		lines.push("# [capabilities.sources]");
+		lines.push("# # GitHub shorthand (uses latest commit)");
+		lines.push('# tasks = "github:example-org/tasks-capability"');
+		lines.push("#");
+		lines.push("# # With subdirectory path");
+		lines.push('# ralph = { source = "github:example-org/ralph", path = "plugins/my-cap" }');
+		lines.push("#");
+		lines.push("# # Other Git sources");
+		lines.push('# private = "git@github.com:company/private-cap.git"');
+		lines.push('# gitlab = "https://gitlab.com/user/capability.git"');
+	}
 	lines.push("");
 
-	// MCP servers (commented examples)
+	// MCP servers
 	lines.push("# =============================================================================");
 	lines.push("# MCP Servers");
 	lines.push("# =============================================================================");
@@ -160,19 +182,67 @@ function generateConfigToml(config: OmniConfig): string {
 		'# Reference in profiles using the MCP name directly, e.g. capabilities = ["filesystem"]',
 	);
 	lines.push("#");
-	lines.push("# [mcps.filesystem]");
-	lines.push('# command = "npx"');
-	lines.push('# args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]');
-	lines.push('# transport = "stdio"  # stdio (default), sse, or http');
-	lines.push("#");
-	lines.push("# [mcps.database]");
-	lines.push('# command = "node"');
-	lines.push('# args = ["./servers/database.js"]');
-	lines.push('# cwd = "./mcp-servers"');
-	lines.push("# [mcps.database.env]");
-	// biome-ignore lint/suspicious/noTemplateCurlyInString: Example of env var syntax
-	lines.push('# DB_URL = "${DATABASE_URL}"');
-	lines.push("");
+
+	const mcps = config.mcps;
+	if (mcps && Object.keys(mcps).length > 0) {
+		for (const [name, mcpConfig] of Object.entries(mcps)) {
+			lines.push(`[mcps.${name}]`);
+
+			// Transport type (default is stdio)
+			if (mcpConfig.transport && mcpConfig.transport !== "stdio") {
+				lines.push(`transport = "${mcpConfig.transport}"`);
+			}
+
+			// For stdio transport
+			if (mcpConfig.command) {
+				lines.push(`command = "${mcpConfig.command}"`);
+			}
+			if (mcpConfig.args && mcpConfig.args.length > 0) {
+				const argsStr = mcpConfig.args.map((a) => `"${a}"`).join(", ");
+				lines.push(`args = [${argsStr}]`);
+			}
+			if (mcpConfig.cwd) {
+				lines.push(`cwd = "${mcpConfig.cwd}"`);
+			}
+
+			// For http/sse transport
+			if (mcpConfig.url) {
+				lines.push(`url = "${mcpConfig.url}"`);
+			}
+
+			// Environment variables (sub-table)
+			if (mcpConfig.env && Object.keys(mcpConfig.env).length > 0) {
+				lines.push(`[mcps.${name}.env]`);
+				for (const [key, value] of Object.entries(mcpConfig.env)) {
+					lines.push(`${key} = "${value}"`);
+				}
+			}
+
+			// Headers (sub-table)
+			if (mcpConfig.headers && Object.keys(mcpConfig.headers).length > 0) {
+				lines.push(`[mcps.${name}.headers]`);
+				for (const [key, value] of Object.entries(mcpConfig.headers)) {
+					lines.push(`${key} = "${value}"`);
+				}
+			}
+
+			lines.push("");
+		}
+	} else {
+		lines.push("# [mcps.filesystem]");
+		lines.push('# command = "npx"');
+		lines.push('# args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]');
+		lines.push('# transport = "stdio"  # stdio (default), sse, or http');
+		lines.push("#");
+		lines.push("# [mcps.database]");
+		lines.push('# command = "node"');
+		lines.push('# args = ["./servers/database.js"]');
+		lines.push('# cwd = "./mcp-servers"');
+		lines.push("# [mcps.database.env]");
+		// biome-ignore lint/suspicious/noTemplateCurlyInString: Example of env var syntax
+		lines.push('# DB_URL = "${DATABASE_URL}"');
+		lines.push("");
+	}
 
 	// Always enabled capabilities
 	lines.push("# =============================================================================");
@@ -181,7 +251,12 @@ function generateConfigToml(config: OmniConfig): string {
 	lines.push("# Capabilities that load in ALL profiles, regardless of profile config.");
 	lines.push("# Useful for essential tools needed everywhere.");
 	lines.push("#");
-	lines.push('# always_enabled_capabilities = ["git-tools", "linting"]');
+	if (config.always_enabled_capabilities && config.always_enabled_capabilities.length > 0) {
+		const caps = config.always_enabled_capabilities.map((c) => `"${c}"`).join(", ");
+		lines.push(`always_enabled_capabilities = [${caps}]`);
+	} else {
+		lines.push('# always_enabled_capabilities = ["git-tools", "linting"]');
+	}
 	lines.push("");
 
 	// Profiles

package/src/index.ts

@@ -30,6 +30,7 @@ export * from "./sync";
 // Export templates
 export * from "./templates/agents";
 export * from "./templates/claude";
+export * from "./templates/omni";
 // Export core types
 export * from "./types";
 

package/src/mcp-json/manager.ts

@@ -4,14 +4,37 @@ import type { LoadedCapability, McpConfig } from "../types";
 import type { ResourceManifest } from "../state/manifest";
 
 /**
- * MCP server configuration in .mcp.json
+ * MCP server configuration in .mcp.json for stdio transport
  */
-export interface McpServerConfig {
+export interface McpServerStdioConfig {
 	command: string;
 	args?: string[];
 	env?: Record<string, string>;
 }
 
+/**
+ * MCP server configuration in .mcp.json for HTTP transport
+ */
+export interface McpServerHttpConfig {
+	type: "http";
+	url: string;
+	headers?: Record<string, string>;
+}
+
+/**
+ * MCP server configuration in .mcp.json for SSE transport
+ */
+export interface McpServerSseConfig {
+	type: "sse";
+	url: string;
+	headers?: Record<string, string>;
+}
+
+/**
+ * Union type for all MCP server configurations
+ */
+export type McpServerConfig = McpServerStdioConfig | McpServerHttpConfig | McpServerSseConfig;
+
 /**
  * Structure of .mcp.json file
  */
@@ -52,7 +75,43 @@ export async function writeMcpJson(config: McpJsonConfig): Promise<void> {
  * Build MCP server config from capability's mcp section
  */
 function buildMcpServerConfig(mcp: McpConfig): McpServerConfig {
-	const config: McpServerConfig = {
+	const transport = mcp.transport ?? "stdio";
+
+	// HTTP transport - remote server
+	if (transport === "http") {
+		if (!mcp.url) {
+			throw new Error("HTTP transport requires a URL");
+		}
+		const config: McpServerHttpConfig = {
+			type: "http",
+			url: mcp.url,
+		};
+		if (mcp.headers && Object.keys(mcp.headers).length > 0) {
+			config.headers = mcp.headers;
+		}
+		return config;
+	}
+
+	// SSE transport - remote server (deprecated)
+	if (transport === "sse") {
+		if (!mcp.url) {
+			throw new Error("SSE transport requires a URL");
+		}
+		const config: McpServerSseConfig = {
+			type: "sse",
+			url: mcp.url,
+		};
+		if (mcp.headers && Object.keys(mcp.headers).length > 0) {
+			config.headers = mcp.headers;
+		}
+		return config;
+	}
+
+	// stdio transport - local process (default)
+	if (!mcp.command) {
+		throw new Error("stdio transport requires a command");
+	}
+	const config: McpServerStdioConfig = {
 		command: mcp.command,
 	};
 	if (mcp.args) {

package/src/templates/omni.ts

@@ -0,0 +1,25 @@
+/**
+ * Template for OMNI.md - the user's project instructions file.
+ * This is the single source of truth that gets transformed into
+ * provider-specific files (CLAUDE.md, AGENTS.md, etc.) during sync.
+ */
+export function generateOmniMdTemplate(): string {
+	return `# Project Instructions
+
+<!-- This file is your project's instruction manifest for AI agents. -->
+<!-- It will be combined with capability-generated content during sync. -->
+
+## Project Description
+
+<!-- TODO: Add 2-3 sentences describing your project -->
+[Describe what this project does and its main purpose]
+
+## Conventions
+
+<!-- Add your project conventions, coding standards, and guidelines here -->
+
+## Architecture
+
+<!-- Describe your project's architecture and key components -->
+`;
+}

package/src/types/index.ts

@@ -62,12 +62,37 @@ export interface McpToolSchema {
 	inputSchema: Record<string, unknown>;
 }
 
+/**
+ * MCP server configuration supporting multiple transport types:
+ *
+ * - **stdio**: Local process using stdin/stdout (default)
+ *   - Requires: command
+ *   - Optional: args, env, cwd
+ *
+ * - **http**: Remote HTTP server (recommended for remote servers)
+ *   - Requires: url
+ *   - Optional: headers (for authentication)
+ *
+ * - **sse**: Server-Sent Events (deprecated, use http instead)
+ *   - Requires: url
+ *   - Optional: headers (for authentication)
+ */
 export interface McpConfig {
-	command: string;
+	/** Executable to run (required for stdio transport) */
+	command?: string;
+	/** Command arguments (stdio transport only) */
 	args?: string[];
+	/** Environment variables (stdio transport only) */
 	env?: Record<string, string>;
+	/** Working directory (stdio transport only) */
 	cwd?: string;
+	/** Transport type: stdio (default), http, or sse */
 	transport?: McpTransport;
+	/** URL for remote servers (required for http/sse transport) */
+	url?: string;
+	/** HTTP headers for authentication (http/sse transport only) */
+	headers?: Record<string, string>;
+	/** Tool schemas (optional, for documentation) */
 	tools?: McpToolSchema[];
 }