caplets 0.17.2 → 0.17.4

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { accessSync, chmodSync, closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync, writeSync } from "node:fs";
-import minpath, { basename, delimiter, dirname, extname, isAbsolute, join, parse, posix, relative, resolve, win32 } from "node:path";
+import { accessSync, chmodSync, closeSync, constants, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync, writeSync } from "node:fs";
+import minpath, { basename, delimiter, dirname, extname, isAbsolute, join, parse, posix, relative, resolve, sep, win32 } from "node:path";
 import { execFileSync, spawn } from "node:child_process";
 import process$1, { stdin, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
@@ -4709,7 +4709,7 @@ function generatedToolInputJsonSchema() {
 	return generatedToolInputJsonSchemaForCaplet({ backend: "tool" });
 }
 //#endregion
-//#region ../core/dist/options-bnsSREid.js
+//#region ../core/dist/options-BlNyqF_E.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -12911,6 +12911,82 @@ function loadCapletFilesWithPaths(root) {
 		paths
 	} : void 0;
 }
+function loadCapletFilesWithPathsBestEffort(root) {
+	if (!existsSync(root)) return;
+	const warnings = [];
+	return buildCapletFileLoadResult(root, discoverCapletFilesBestEffort(root, warnings), warnings);
+}
+function buildCapletFileLoadResult(root, candidates, warnings) {
+	const servers = {};
+	const openapiEndpoints = {};
+	const graphqlEndpoints = {};
+	const httpApis = {};
+	const cliTools = {};
+	const capletSets = {};
+	const paths = {};
+	function hasId(id) {
+		return Boolean(servers[id] || openapiEndpoints[id] || graphqlEndpoints[id] || httpApis[id] || cliTools[id] || capletSets[id]);
+	}
+	for (const candidate of candidates) {
+		if (hasId(candidate.id)) {
+			const message = `Duplicate Caplet ID ${candidate.id} under ${root}`;
+			if (!warnings) throw new CapletsError("CONFIG_INVALID", message);
+			warnings.push({
+				path: candidate.path,
+				message: `${message}; skipping duplicate at ${candidate.path}`
+			});
+			continue;
+		}
+		let config;
+		try {
+			config = readCapletFile(candidate.path);
+		} catch (error) {
+			if (!warnings) throw error;
+			warnings.push({
+				path: candidate.path,
+				message: `Skipping invalid Caplet file at ${candidate.path}: ${errorMessage$1(error)}`
+			});
+			continue;
+		}
+		paths[candidate.id] = candidate.path;
+		if (isPlainObject$5(config) && config.backend === "openapi") {
+			const { backend: _backend, ...endpoint } = config;
+			openapiEndpoints[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "graphql") {
+			const { backend: _backend, ...endpoint } = config;
+			graphqlEndpoints[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "http") {
+			const { backend: _backend, ...endpoint } = config;
+			httpApis[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "cli") {
+			const { backend: _backend, ...endpoint } = config;
+			cliTools[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "caplets") {
+			const { backend: _backend, ...endpoint } = config;
+			capletSets[candidate.id] = endpoint;
+		} else servers[candidate.id] = config;
+	}
+	const hasServers = Object.keys(servers).length > 0;
+	const hasOpenApi = Object.keys(openapiEndpoints).length > 0;
+	const hasGraphQl = Object.keys(graphqlEndpoints).length > 0;
+	const hasHttpApis = Object.keys(httpApis).length > 0;
+	const hasCliTools = Object.keys(cliTools).length > 0;
+	const hasCapletSets = Object.keys(capletSets).length > 0;
+	const config = {
+		...hasServers ? { mcpServers: servers } : {},
+		...hasOpenApi ? { openapiEndpoints } : {},
+		...hasGraphQl ? { graphqlEndpoints } : {},
+		...hasHttpApis ? { httpApis } : {},
+		...hasCliTools ? { cliTools } : {},
+		...hasCapletSets ? { capletSets } : {}
+	};
+	if (!(Object.keys(config).length > 0) && warnings?.length === 0) return;
+	return {
+		config,
+		paths,
+		warnings: warnings ?? []
+	};
+}
 function discoverCapletFiles(root) {
 	const entries = readdirSync(root, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
 	const candidates = [];
@@ -12935,6 +13011,82 @@ function discoverCapletFiles(root) {
 	}
 	return candidates;
 }
+function discoverCapletFilesBestEffort(root, warnings) {
+	const entries = readdirSync(root, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+	const byId = /* @__PURE__ */ new Map();
+	const duplicateIds = /* @__PURE__ */ new Set();
+	function addCandidate(id, path, isDirectoryCaplet) {
+		try {
+			validateCapletId(id, path);
+		} catch (error) {
+			warnings.push({
+				path,
+				message: `Skipping invalid Caplet file at ${path}: ${errorMessage$1(error)}`
+			});
+			return;
+		}
+		if (duplicateIds.has(id)) {
+			warnings.push({
+				path,
+				message: `Duplicate Caplet ID ${id} under ${root}; skipping duplicate at ${path}`
+			});
+			return;
+		}
+		const existing = byId.get(id);
+		if (!existing) {
+			byId.set(id, {
+				id,
+				path,
+				isDirectoryCaplet
+			});
+			return;
+		}
+		if (isDirectoryCaplet && !existing.isDirectoryCaplet) {
+			warnings.push({
+				path: existing.path,
+				message: `Caplet file at ${existing.path} was shadowed by ${path}`
+			});
+			byId.set(id, {
+				id,
+				path,
+				isDirectoryCaplet
+			});
+			return;
+		}
+		if (!isDirectoryCaplet && existing.isDirectoryCaplet) {
+			warnings.push({
+				path,
+				message: `Caplet file at ${path} was shadowed by ${existing.path}`
+			});
+			return;
+		}
+		warnings.push({
+			path,
+			message: `Duplicate Caplet ID ${id} under ${root}; skipping ${existing.path} and ${path}`
+		});
+		byId.delete(id);
+		duplicateIds.add(id);
+	}
+	for (const entry of entries) {
+		if (entry.name === "auth" || entry.name === "config.json") continue;
+		const path = join(root, entry.name);
+		if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") {
+			addCandidate(basename(entry.name, extname(entry.name)), path, false);
+			continue;
+		}
+		if (entry.isDirectory()) {
+			const capletPath = join(path, "CAPLET.md");
+			if (existsSync(capletPath) && statSync(capletPath).isFile()) addCandidate(entry.name, capletPath, true);
+		}
+	}
+	return Array.from(byId.values()).map(({ id, path }) => ({
+		id,
+		path
+	}));
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function readCapletFile(path) {
 	if (statSync(path).size > MAX_CAPLET_FILE_BYTES) throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} exceeds the ${MAX_CAPLET_FILE_BYTES} byte limit`);
 	const { frontmatter, body } = parseFrontmatter(readFileSync(path, "utf8"), path);
@@ -13611,35 +13763,78 @@ function loadConfigWithSources(path = resolveConfigPath(), projectPath = resolve
 	const projectConfig = hasProjectConfig ? rejectProjectConfigExecutableBackendMaps(readPublicConfigInput(projectPath), projectPath) : void 0;
 	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath$1(projectPath);
 	const projectCaplets = projectCapletsRoot ? loadCapletFilesWithPaths(projectCapletsRoot) : void 0;
-	if (!hasUserConfig && !hasProjectConfig && !userCaplets && !projectCaplets) throw new CapletsError("CONFIG_NOT_FOUND", `Caplets config not found at ${path} or ${projectPath}`);
-	try {
-		const { input, sources, shadows } = mergeConfigInputsWithSources({
+	return buildConfigWithSources([
+		{
 			input: userConfig,
 			source: {
 				kind: "global-config",
 				path
 			}
-		}, userCaplets ? {
+		},
+		userCaplets ? {
 			input: userCaplets.config,
 			source: {
 				kind: "global-file",
 				path: userCaplets.paths
 			}
-		} : void 0, {
+		} : void 0,
+		{
 			input: projectConfig,
 			source: {
 				kind: "project-config",
 				path: projectPath
 			}
-		}, projectCaplets ? {
+		},
+		projectCaplets ? {
 			input: projectCaplets.config,
 			source: {
 				kind: "project-file",
 				path: projectCaplets.paths
 			}
-		} : void 0);
+		} : void 0
+	], `Caplets config not found at ${path} or ${projectPath}`, "Caplets config must define at least one MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, CLI tools backend, or Caplet set");
+}
+function loadGlobalConfig(path = resolveConfigPath()) {
+	const userConfig = existsSync(path) ? readPublicConfigInput(path) : void 0;
+	const userCaplets = loadCapletFilesWithPaths(resolveCapletsRoot(path));
+	return buildConfigWithSources([{
+		input: userConfig,
+		source: {
+			kind: "global-config",
+			path
+		}
+	}, userCaplets ? {
+		input: userCaplets.config,
+		source: {
+			kind: "global-file",
+			path: userCaplets.paths
+		}
+	} : void 0], `Caplets user config not found at ${path}`, void 0).config;
+}
+function loadProjectConfig(projectPath = resolveProjectConfigPath()) {
+	const projectConfig = existsSync(projectPath) ? rejectProjectConfigExecutableBackendMaps(readPublicConfigInput(projectPath), projectPath) : void 0;
+	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath$1(projectPath);
+	const projectCaplets = projectCapletsRoot ? loadCapletFilesWithPaths(projectCapletsRoot) : void 0;
+	return buildConfigWithSources([{
+		input: projectConfig,
+		source: {
+			kind: "project-config",
+			path: projectPath
+		}
+	}, projectCaplets ? {
+		input: projectCaplets.config,
+		source: {
+			kind: "project-file",
+			path: projectCaplets.paths
+		}
+	} : void 0], `Caplets project config not found at ${projectPath}`, void 0).config;
+}
+function buildConfigWithSources(inputs, notFoundMessage, emptyMessage) {
+	if (!inputs.some((entry) => entry?.input !== void 0)) throw new CapletsError("CONFIG_NOT_FOUND", notFoundMessage);
+	try {
+		const { input, sources, shadows } = mergeConfigInputsWithSources(...inputs);
 		const config = parseConfig(input);
-		if (Object.keys(config.mcpServers).length === 0 && Object.keys(config.openapiEndpoints).length === 0 && Object.keys(config.graphqlEndpoints).length === 0 && Object.keys(config.httpApis).length === 0 && Object.keys(config.cliTools).length === 0 && Object.keys(config.capletSets).length === 0) throw new CapletsError("CONFIG_INVALID", "Caplets config must define at least one MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, CLI tools backend, or Caplet set");
+		if (emptyMessage && Object.keys(config.mcpServers).length === 0 && Object.keys(config.openapiEndpoints).length === 0 && Object.keys(config.graphqlEndpoints).length === 0 && Object.keys(config.httpApis).length === 0 && Object.keys(config.cliTools).length === 0 && Object.keys(config.capletSets).length === 0) throw new CapletsError("CONFIG_INVALID", emptyMessage);
 		return {
 			config,
 			sources,
@@ -13650,6 +13845,74 @@ function loadConfigWithSources(path = resolveConfigPath(), projectPath = resolve
 		throw new CapletsError("CONFIG_INVALID", "Caplets config is not valid JSON", redactSecrets(error));
 	}
 }
+function loadLocalOverlayConfigWithSources(path = resolveConfigPath(), projectPath = resolveProjectConfigPath()) {
+	const warnings = [];
+	const userConfig = existsSync(path) ? readBestEffortConfigInput(path, "global-config", warnings) : void 0;
+	const userCaplets = loadBestEffortCapletFiles(resolveCapletsRoot(path), "global-file", warnings);
+	const projectConfig = existsSync(projectPath) ? readBestEffortConfigInput(projectPath, "project-config", warnings, (input) => rejectProjectConfigExecutableBackendMaps(input, projectPath)) : void 0;
+	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath$1(projectPath);
+	const projectCaplets = projectCapletsRoot ? loadBestEffortCapletFiles(projectCapletsRoot, "project-file", warnings) : void 0;
+	const { input, sources, shadows } = mergeConfigInputsWithSources({
+		input: userConfig,
+		source: {
+			kind: "global-config",
+			path
+		}
+	}, userCaplets ? {
+		input: userCaplets.config,
+		source: {
+			kind: "global-file",
+			path: userCaplets.paths
+		}
+	} : void 0, {
+		input: projectConfig,
+		source: {
+			kind: "project-config",
+			path: projectPath
+		}
+	}, projectCaplets ? {
+		input: projectCaplets.config,
+		source: {
+			kind: "project-file",
+			path: projectCaplets.paths
+		}
+	} : void 0);
+	return {
+		config: parseConfig(input),
+		sources,
+		shadows,
+		warnings
+	};
+}
+function readBestEffortConfigInput(path, kind, warnings, transform) {
+	try {
+		const input = readPublicConfigInput(path);
+		return transform ? transform(input) : input;
+	} catch (error) {
+		warnings.push({
+			kind,
+			path,
+			message: errorMessage(error)
+		});
+		return;
+	}
+}
+function loadBestEffortCapletFiles(root, kind, warnings) {
+	const result = loadCapletFilesWithPathsBestEffort(root);
+	if (!result) return;
+	for (const warning of result.warnings) warnings.push({
+		kind,
+		path: warning.path ?? root,
+		message: warning.message
+	});
+	return {
+		config: result.config,
+		paths: result.paths
+	};
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function loadIsolatedConfig(options) {
 	if (!options.configPath && !options.capletsRoot) throw new CapletsError("CONFIG_INVALID", "Nested Caplet set must define at least one source: configPath or capletsRoot");
 	const configInput = options.configPath ? readPublicConfigInput(options.configPath) : void 0;
@@ -56439,8 +56702,21 @@ async function loadOpenApiSource(endpoint, authDir) {
 	if (endpoint.specPath) return endpoint.specPath;
 	if (!endpoint.specUrl) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} is missing OpenAPI spec source`);
 	if (!endpoint.baseUrl) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} must configure baseUrl when using remote specUrl`);
-	const response = await fetchWithLimit(endpoint.specUrl, endpoint.requestTimeoutMs, shouldSendSpecAuth(endpoint) ? authHeaders(endpoint, authDir) : {});
-	return JSON.parse(response);
+	return parseOpenApiSourceText(await fetchWithLimit(endpoint.specUrl, endpoint.requestTimeoutMs, shouldSendSpecAuth(endpoint) ? authHeaders(endpoint, authDir) : {}));
+}
+function parseOpenApiSourceText(source) {
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch (jsonError) {
+		try {
+			parsed = (0, import_dist$1.parse)(source);
+		} catch {
+			throw jsonError instanceof Error ? jsonError : new Error(String(jsonError));
+		}
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI source must parse to an object");
+	return parsed;
 }
 function extractOperations(endpoint, document) {
 	const operations = [];
@@ -56458,6 +56734,7 @@ function extractOperations(endpoint, document) {
 			const requestBody = requestBodyFor(operation);
 			const outputSchema = outputSchemaFor(operation);
 			const baseUrl = endpoint.baseUrl ?? firstServerUrl(document);
+			const staticHeaders = staticHeaderDefaultsFor(endpoint, parameters);
 			validateOperationBaseUrl(endpoint, baseUrl);
 			operations.push({
 				name,
@@ -56465,15 +56742,32 @@ function extractOperations(endpoint, document) {
 				path,
 				...typeof operation.summary === "string" ? { summary: operation.summary } : {},
 				...typeof operation.description === "string" ? { description: operation.description } : {},
-				inputSchema: inputSchemaFor(parameters, requestBody),
+				inputSchema: inputSchemaFor(parameters, requestBody, staticHeaders),
 				...outputSchema ? { outputSchema } : {},
 				...requestBody?.contentType ? { requestBodyContentType: requestBody.contentType } : {},
-				...baseUrl ? { baseUrl } : {}
+				...baseUrl ? { baseUrl } : {},
+				...Object.keys(staticHeaders).length ? { staticHeaders } : {}
 			});
 		}
 	}
 	return operations.sort((left, right) => left.name.localeCompare(right.name));
 }
+function staticHeaderDefaultsFor(endpoint, parameters) {
+	const configuredHeaderNames = configuredAuthHeaderNames(endpoint);
+	const headers = {};
+	for (const parameter of parameters) {
+		if (parameter?.in !== "header" || typeof parameter.name !== "string") continue;
+		const normalized = parameter.name.toLowerCase();
+		if (configuredHeaderNames.has(normalized) || FORBIDDEN_ARGUMENT_HEADERS.has(normalized) && normalized !== "accept") continue;
+		const defaultValue = parameter.schema?.default;
+		if ([
+			"string",
+			"number",
+			"boolean"
+		].includes(typeof defaultValue)) headers[parameter.name] = String(defaultValue);
+	}
+	return headers;
+}
 function requestBodyFor(operation) {
 	const requestBody = operation.requestBody;
 	if (!requestBody || typeof requestBody !== "object") return;
@@ -56534,19 +56828,20 @@ function structuredOutputSchema(bodySchema) {
 		}
 	};
 }
-function inputSchemaFor(parameters, requestBody) {
+function inputSchemaFor(parameters, requestBody, staticHeaders = {}) {
 	const schema = {
 		type: "object",
 		additionalProperties: false,
 		properties: {}
 	};
 	const required = [];
+	const protectedStaticHeaders = new Set(Object.keys(staticHeaders).map((key) => key.toLowerCase()).filter((key) => FORBIDDEN_ARGUMENT_HEADERS.has(key)));
 	for (const location of [
 		"path",
 		"query",
 		"header"
 	]) {
-		const locationParameters = parameters.filter((parameter) => parameter?.in === location);
+		const locationParameters = parameters.filter((parameter) => parameter?.in === location && !(location === "header" && protectedStaticHeaders.has(parameter.name?.toLowerCase())));
 		if (locationParameters.length === 0) continue;
 		const nestedRequired = locationParameters.filter((parameter) => parameter.required === true || location === "path").map((parameter) => parameter.name);
 		schema.properties[location] = {
@@ -56585,7 +56880,8 @@ function buildRequest(endpoint, operation, args, authDir) {
 	for (const [key, value] of Object.entries(asRecord(args.query))) if (value !== void 0 && value !== null) url.searchParams.append(key, serializeHttpValue("query", key, value));
 	const headers = new Headers();
 	applyAuth(headers, endpoint, authDir);
-	const configuredHeaderNames = endpoint.auth.type === "headers" ? new Set(Object.keys(endpoint.auth.headers).map((key) => key.toLowerCase())) : /* @__PURE__ */ new Set();
+	const configuredHeaderNames = configuredAuthHeaderNames(endpoint);
+	for (const [key, value] of Object.entries(operation.staticHeaders ?? {})) if (!headers.has(key) && !configuredHeaderNames.has(key.toLowerCase())) headers.set(key, value);
 	for (const [key, value] of Object.entries(asRecord(args.header))) if (value !== void 0 && value !== null) {
 		const normalized = key.toLowerCase();
 		if (FORBIDDEN_ARGUMENT_HEADERS.has(normalized) || configuredHeaderNames.has(normalized)) throw new CapletsError("REQUEST_INVALID", `Header ${key} cannot be supplied by arguments`);
@@ -56631,6 +56927,9 @@ function asRecord(value) {
 function applyAuth(headers, endpoint, authDir) {
 	for (const [key, value] of Object.entries(authHeaders(endpoint, authDir))) headers.set(key, value);
 }
+function configuredAuthHeaderNames(endpoint) {
+	return endpoint.auth.type === "headers" ? new Set(Object.keys(endpoint.auth.headers).map((key) => key.toLowerCase())) : /* @__PURE__ */ new Set();
+}
 function authHeaders(endpoint, authDir) {
 	switch (endpoint.auth.type) {
 		case "none": return {};
@@ -57558,6 +57857,7 @@ var CapletsEngine = class {
 	watchDebounceMs;
 	watchEnabled;
 	writeErr;
+	configLoader;
 	reloadListeners = /* @__PURE__ */ new Set();
 	watchers = [];
 	reloadTimer;
@@ -57570,7 +57870,8 @@ var CapletsEngine = class {
 			configPath: resolveConfigPath(options.configPath),
 			projectConfigPath: options.projectConfigPath ?? resolveProjectConfigPath()
 		};
-		const config = loadConfig(this.paths.configPath, this.paths.projectConfigPath);
+		this.configLoader = options.configLoader ?? loadConfig;
+		const config = this.configLoader(this.paths.configPath, this.paths.projectConfigPath);
 		this.registry = new ServerRegistry(config);
 		this.downstream = new DownstreamManager(this.registry, selectAuthOptions(options.authDir));
 		this.openapi = new OpenApiManager(this.registry, selectAuthOptions(options.authDir));
@@ -57625,7 +57926,7 @@ var CapletsEngine = class {
 		}
 	}
 	async completeCliWords(words) {
-		const { completeCliWords } = await Promise.resolve().then(() => completion_L23s2FGB_exports).then((n) => n.r);
+		const { completeCliWords } = await Promise.resolve().then(() => completion_DRPTunQd_exports).then((n) => n.r);
 		return await completeCliWords(words, {
 			config: this.registry.config,
 			managers: {
@@ -57685,7 +57986,7 @@ var CapletsEngine = class {
 		if (this.closed) return false;
 		let nextConfig;
 		try {
-			nextConfig = loadConfig(this.paths.configPath, this.paths.projectConfigPath);
+			nextConfig = this.configLoader(this.paths.configPath, this.paths.projectConfigPath);
 		} catch (error) {
 			this.writeErr(`Caplets config reload failed; keeping last known-good config.\n`);
 			this.writeErr(`${JSON.stringify(toSafeError(error, "CONFIG_INVALID"), null, 2)}\n`);
@@ -57963,8 +58264,8 @@ function hasEnv$1(value) {
 	return value !== void 0 && value.trim() !== "";
 }
 //#endregion
-//#region ../core/dist/completion-L23s2FGB.js
-var completion_L23s2FGB_exports = /* @__PURE__ */ __exportAll$1({
+//#region ../core/dist/completion-DRPTunQd.js
+var completion_DRPTunQd_exports = /* @__PURE__ */ __exportAll$1({
 	a: () => formatCapletList,
 	c: () => resolveCliConfigPaths,
 	i: () => trailingSpaceCompletionToken,
@@ -58086,7 +58387,8 @@ function allCaplets(config) {
 		...Object.values(config.openapiEndpoints),
 		...Object.values(config.graphqlEndpoints),
 		...Object.values(config.httpApis),
-		...Object.values(config.cliTools)
+		...Object.values(config.cliTools),
+		...Object.values(config.capletSets)
 	];
 }
 function formatCapletList(rows, format = "plain") {
@@ -58138,15 +58440,15 @@ function formatSourceKind(kind) {
 	if (kind.startsWith("global")) return "global";
 	return kind;
 }
-function resolveCliConfigPaths(envConfigPath, authDir) {
+function resolveCliConfigPaths(envConfigPath, projectConfigPath = resolveProjectConfigPath(), authDir) {
 	const configPath = resolveConfigPath(envConfigPath);
 	const effectiveAuthDir = authDir ?? DEFAULT_AUTH_DIR;
 	return {
 		userConfig: configPath,
-		projectConfig: resolveProjectConfigPath(),
+		projectConfig: projectConfigPath,
 		userRoot: resolveCapletsRoot(configPath),
 		stateRoot: dirname(effectiveAuthDir),
-		projectRoot: resolveProjectCapletsRoot(),
+		projectRoot: dirname(projectConfigPath),
 		authDir: effectiveAuthDir,
 		envConfig: envConfigPath ?? null
 	};
@@ -59827,7 +60129,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 	values: [],
 	hasMore: false
 } };
-var version$1 = "0.18.2";
+var version$1 = "0.18.4";
 var CapletsMcpSession = class {
 	engine;
 	server;
@@ -63343,7 +63645,7 @@ function isUrlLike(value) {
 	return /^https?:\/\//i.test(value);
 }
 async function loginAuth(serverId, options) {
-	const server = findAuthTarget(serverId, loadConfig(options.configPath));
+	const server = findAuthTarget(serverId, options.config ?? loadConfig(options.configPath));
 	assertLoginTarget(server, serverId);
 	try {
 		const flowOptions = {
@@ -63365,40 +63667,64 @@ function logoutAuth(serverId, options) {
 	else options.writeOut(`No OAuth credentials found for \`${serverId}\`.\n`);
 }
 function logoutAuthResult(serverId, options) {
-	assertLoginTarget(findAuthTarget(serverId, loadConfig(options.configPath)), serverId);
+	assertLoginTarget(findAuthTarget(serverId, options.config ?? loadConfig(options.configPath)), serverId);
 	return {
 		server: serverId,
 		deleted: deleteTokenBundle(serverId, options.authDir)
 	};
 }
-function listAuth(options) {
-	const rows = listAuthRows(options);
-	const format = options.format ?? "plain";
-	if (format === "json") {
-		options.writeOut(`${JSON.stringify(rows, null, 2)}\n`);
-		return;
+function listAuthRows(options) {
+	return authRowsForTargets(authTargets(loadConfig(options.configPath)), options.authDir);
+}
+function listLocalAuthRows(options) {
+	return authRowsForTargets(localAuthTargets(options), options.authDir);
+}
+function localAuthTargets(options) {
+	return [...options.source === "project" ? [] : authTargetsForSource("global", options), ...options.source === "global" ? [] : authTargetsForSource("project", options)].filter((target) => !options.source || target.source === options.source);
+}
+function localAuthConfigForTarget(options) {
+	assertLoginTarget(localAuthTargets(options).find((candidate) => candidate.server === options.serverId), options.serverId);
+	return loadConfigForSource(options.source, options);
+}
+function authTargetsForSource(source, options) {
+	try {
+		return authTargets(loadConfigForSource(source, options)).map((target) => ({
+			...target,
+			source
+		}));
+	} catch (error) {
+		if (error instanceof CapletsError && error.code === "CONFIG_NOT_FOUND") return [];
+		throw error;
 	}
-	options.writeOut(formatAuthRows(rows, format));
 }
-function listAuthRows(options) {
-	return authTargets(loadConfig(options.configPath)).sort((left, right) => left.server.localeCompare(right.server)).map((server) => {
-		const bundle = readTokenBundle(server.server, options.authDir);
+function loadConfigForSource(source, options) {
+	if (source === "global") return loadGlobalConfig(options.configPath);
+	return loadProjectConfig(options.projectConfigPath);
+}
+function authRowsForTargets(targets, authDir) {
+	return targets.sort((left, right) => left.server.localeCompare(right.server)).map((server) => {
+		const bundle = readTokenBundle(server.server, authDir);
 		const status = !bundle ? "missing" : isTokenBundleExpired(bundle) ? "expired" : "authenticated";
 		return {
 			server: server.server,
 			status,
 			...bundle?.expiresAt ? { expiresAt: bundle.expiresAt } : {},
-			...bundle?.scope ? { scope: bundle.scope } : {}
+			...bundle?.scope ? { scope: bundle.scope } : {},
+			...server.source ? { source: server.source } : {}
 		};
 	});
 }
 function formatAuthRows(rows, format) {
-	if (rows.length === 0) return format === "markdown" ? "## OAuth credentials\n\nNo configured remote OAuth servers found.\n" : "No configured remote OAuth servers found.\n";
+	if (rows.length === 0) return format === "markdown" ? "## OAuth credentials\n\nNo configured OAuth servers found.\n" : "No configured OAuth servers found.\n";
 	let output = "";
 	if (format === "markdown") output += "## OAuth credentials\n\n";
 	else output += "OAuth credentials\n\n";
 	for (const row of rows) {
-		const details = [row.expiresAt ? `expires ${row.expiresAt}` : void 0, row.scope ? `scope ${row.scope}` : void 0].filter(Boolean).join("; ");
+		const details = [
+			row.source ? `source ${row.source}` : void 0,
+			row.expiresAt ? `expires ${row.expiresAt}` : void 0,
+			row.scope ? `scope ${row.scope}` : void 0
+		].filter(Boolean).join("; ");
 		if (format === "markdown") {
 			output += `- \`${row.server}\` — ${row.status}${details ? ` (${details})` : ""}\n`;
 			continue;
@@ -63406,6 +63732,7 @@ function formatAuthRows(rows, format) {
 		output += [
 			row.server,
 			`  Status: ${row.status}`,
+			...row.source ? [`  Source: ${row.source}`] : [],
 			...row.expiresAt ? [`  Expires: ${row.expiresAt}`] : [],
 			...row.scope ? [`  Scope: ${row.scope}`] : []
 		].join("\n") + "\n\n";
@@ -63626,12 +63953,14 @@ function rejectCrossKindDestinationCollision(plan, destinationRoot) {
 function installPlan(caplet, options) {
 	const isDirectory = basename(caplet.path) === "CAPLET.md";
 	const sourcePath = isDirectory ? dirname(caplet.path) : caplet.path;
+	const sourceBoundary = dirname(sourcePath);
 	const sourcePathRelative = relative(options.repoRoot, sourcePath);
 	const destination = isDirectory ? join(options.destinationRoot, caplet.id) : join(options.destinationRoot, `${caplet.id}.md`);
 	return {
 		id: caplet.id,
 		source: `${options.sourceId}#${sourcePathRelative}`,
 		sourcePath,
+		sourceBoundary,
 		destination,
 		kind: isDirectory ? "directory" : "file"
 	};
@@ -63693,16 +64022,40 @@ function removeInstallPath(path, label, force) {
 }
 function copyInstallPath(plan) {
 	try {
+		if (plan.kind === "directory") {
+			copyDirectoryCaplet(plan.sourcePath, plan.destination, realpathSync(plan.sourceBoundary));
+			return;
+		}
 		cpSync(plan.sourcePath, plan.destination, {
-			recursive: plan.kind === "directory",
+			recursive: false,
 			force: false,
 			errorOnExist: true
 		});
 	} catch (error) {
+		if (error instanceof CapletsError) throw error;
 		if (isFsError(error, "EEXIST") || isFsError(error, "EISDIR")) throw new CapletsError("CONFIG_EXISTS", `Caplet ${plan.id} already exists at ${plan.destination}; pass --force to overwrite it`, toSafeError(error));
 		throw new CapletsError("CONFIG_INVALID", `Could not install Caplet ${plan.id} to ${plan.destination}`, toSafeError(error));
 	}
 }
+function copyDirectoryCaplet(source, destination, sourceBoundary, seenDirectories = /* @__PURE__ */ new Set()) {
+	const resolvedSource = lstatSync(source).isSymbolicLink() ? resolveDirectoryCapletSymlink(source, sourceBoundary) : source;
+	if (statSync(resolvedSource).isDirectory()) {
+		const realDirectory = realpathSync(resolvedSource);
+		if (seenDirectories.has(realDirectory)) throw new CapletsError("CONFIG_INVALID", `Directory Caplet symlink ${source} creates a copy cycle`);
+		const childSeenDirectories = new Set(seenDirectories);
+		childSeenDirectories.add(realDirectory);
+		mkdirSync(destination);
+		for (const entry of readdirSync(resolvedSource)) copyDirectoryCaplet(join(resolvedSource, entry), join(destination, entry), sourceBoundary, childSeenDirectories);
+		return;
+	}
+	copyFileSync(resolvedSource, destination);
+}
+function resolveDirectoryCapletSymlink(source, sourceBoundary) {
+	const target = readlinkSync(source);
+	const resolvedTarget = realpathSync(isAbsolute(target) ? target : resolve(dirname(source), target));
+	if (resolvedTarget !== sourceBoundary && !resolvedTarget.startsWith(`${sourceBoundary}${sep}`)) throw new CapletsError("CONFIG_INVALID", `Directory Caplet symlink ${source} resolves outside source Caplets boundary`);
+	return resolvedTarget;
+}
 function isFsError(error, code) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
@@ -67880,15 +68233,29 @@ function createProgram(io = {}) {
 		const completionWords = normalizeCompletionWords(words);
 		let suggestions = [];
 		try {
-			suggestions = remote ? await remote.request("complete_cli", {
-				shell,
-				words: completionWords
-			}) : await completeCliWordsLocally(completionWords, {
+			if (remote) {
+				const localOverlay = loadLocalOverlayForCli(io, () => {});
+				const localSuggestions = await completeCliWordsLocally(completionWords, {
+					...configPath ? { configPath } : {},
+					projectConfigPath: envProjectConfigPath(env),
+					...io.authDir ? { authDir: io.authDir } : {},
+					config: localOverlay.config
+				});
+				if (localShadowedCompletionTarget(completionWords, localOverlay.config)) suggestions = localSuggestions;
+				else suggestions = mergeCompletionSuggestions(localSuggestions, await remote.request("complete_cli", {
+					shell,
+					words: completionWords
+				}));
+			} else suggestions = await completeCliWordsLocally(completionWords, {
 				...configPath ? { configPath } : {},
+				projectConfigPath: envProjectConfigPath(env),
 				...io.authDir ? { authDir: io.authDir } : {}
 			});
 		} catch {
-			suggestions = remote ? [] : await completeCliWords(completionWords, configPath ? { configPath } : {});
+			suggestions = remote ? [] : await completeCliWords(completionWords, {
+				...configPath ? { configPath } : {},
+				projectConfigPath: envProjectConfigPath(env)
+			});
 		}
 		if (suggestions.length > 0) writeOut(`${suggestions.join("\n")}\n`);
 	});
@@ -67900,23 +68267,26 @@ function createProgram(io = {}) {
 			...io.authDir ? { authDir: io.authDir } : {}
 		}, writeErr)))(resolved);
 	});
-	program.command(cliCommands.init).description("Create a starter Caplets config file.").option("--force", "overwrite an existing config file").action(async (options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeOut(`Created remote Caplets config at ${(await remote.request("init", { force: Boolean(options.force) })).path}\n`);
+	program.command(cliCommands.init).description("Create a starter Caplets config file.").option("--project", "create the project Caplets config").option("-g, --global", "create the user Caplets config").option("--remote", "create the remote Caplets config").option("--force", "overwrite an existing config file").action(async (options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			writeOut(`Created remote Caplets config at ${(await requireRemoteClientForTarget(io).request("init", { force: Boolean(options.force) })).path}\n`);
 			return;
 		}
-		const configPath = currentConfigPath();
-		writeOut(`Created Caplets config at ${initConfig({
-			...configPath ? { path: configPath } : {},
+		const path = initConfig({
+			path: target === "global" ? resolveConfigPath(currentConfigPath()) : envProjectConfigPath(env),
 			force: Boolean(options.force)
-		})}\n`);
+		});
+		writeOut(`Created ${localMutationTargetLabel(target, io)}Caplets config at ${path}\n`);
 	});
 	program.command(cliCommands.list).description("List configured Caplets.").option("--all", "include disabled Caplets").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action(async (options) => {
 		const includeDisabled = Boolean(options.all);
 		const remote = remoteClientForCli(io);
 		if (remote) {
-			const rows = await remote.request("list", { includeDisabled });
+			const rows = mergeRemoteAndLocalRows(await remote.request("list", { includeDisabled }), tryLoadLocalOverlayForCli(io, writeErr), {
+				includeDisabled,
+				writeErr
+			});
 			if (options.json || options.format === "json") {
 				writeOut(`${JSON.stringify(rows, null, 2)}\n`);
 				return;
@@ -67924,18 +68294,17 @@ function createProgram(io = {}) {
 			writeOut(formatCapletList(rows, options.format ?? "plain"));
 			return;
 		}
-		const rows = listCaplets(loadConfigWithSources(currentConfigPath()), { includeDisabled });
+		const rows = listCaplets(loadConfigWithSources(currentConfigPath(), envProjectConfigPath(env)), { includeDisabled });
 		if (options.json || options.format === "json") {
 			writeOut(`${JSON.stringify(rows, null, 2)}\n`);
 			return;
 		}
 		writeOut(formatCapletList(rows, options.format ?? "plain"));
 	});
-	program.command(cliCommands.install).description("Install Caplets from a repo's caplets directory.").argument("<repo>", "local repo path, Git URL, or GitHub owner/repo").argument("[caplets...]", "optional Caplet IDs to install").option("-g, --global", "install to the user Caplets root").option("--force", "overwrite installed Caplets").action(async (repo, capletIds, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			if (options.global) writeErr("Warning: --global is not supported in remote mode; the server controls the installation destination.\n");
-			const result = await remote.request("install", {
+	program.command(cliCommands.install).description("Install Caplets from a repo's caplets directory.").argument("<repo>", "local repo path, Git URL, or GitHub owner/repo").argument("[caplets...]", "optional Caplet IDs to install").option("--project", "install to the project Caplets root").option("-g, --global", "install to the user Caplets root").option("--remote", "install through remote control").option("--force", "overwrite installed Caplets").action(async (repo, capletIds, options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			const result = await requireRemoteClientForTarget(io).request("install", {
 				repo,
 				capletIds,
 				force: Boolean(options.force)
@@ -67946,15 +68315,15 @@ function createProgram(io = {}) {
 		const result = installCaplets(repo, {
 			capletIds,
 			force: Boolean(options.force),
-			destinationRoot: options.global ? resolveCapletsRoot(resolveConfigPath(currentConfigPath())) : resolveProjectCapletsRoot()
+			destinationRoot: target === "global" ? resolveCapletsRoot(resolveConfigPath(currentConfigPath())) : envProjectCapletsRoot(env)
 		});
-		for (const caplet of result.installed) writeOut(`Installed ${caplet.id} to ${caplet.destination}\n`);
+		for (const caplet of result.installed) writeOut(`Installed ${caplet.id} to ${localMutationTargetLabel(target, io)}${caplet.destination}\n`);
 	});
 	const add = program.command(cliCommands.add).description("Add generated Caplet files.");
-	add.command("cli").description("Add a CLI tools Caplet.").argument("<id>", "Caplet ID/display seed").option("--repo <path>", "repository path to inspect").option("--include <items>", "comma-separated generators to include: git,gh,package").option("--command <name>", "single CLI command template to generate").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeAddResult(writeOut, "CLI", await remote.request("add", {
+	add.command("cli").description("Add a CLI tools Caplet.").argument("<id>", "Caplet ID/display seed").option("--repo <path>", "repository path to inspect").option("--include <items>", "comma-separated generators to include: git,gh,package").option("--command <name>", "single CLI command template to generate").option("--project", "write to the project Caplets root").option("-g, --global", "write to the user Caplets root").option("--remote", "add through remote control").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			writeAddResult(writeOut, "CLI", await requireRemoteClientForTarget(io).request("add", {
 				kind: "cli",
 				id,
 				options: remoteAddOptions(options)
@@ -67963,73 +68332,77 @@ function createProgram(io = {}) {
 		}
 		const result = addCliCaplet(id, {
 			...options,
-			destinationRoot: options.global ? resolveCapletsRoot(resolveConfigPath(currentConfigPath())) : resolveProjectCapletsRoot()
+			destinationRoot: target === "global" ? resolveCapletsRoot(resolveConfigPath(currentConfigPath())) : envProjectCapletsRoot(env)
 		});
 		if (result.path) {
-			writeOut(`Wrote CLI Caplet to ${result.path}\n`);
+			writeOut(`Wrote ${localMutationTargetLabel(target, io)}CLI Caplet to ${result.path}\n`);
 			return;
 		}
 		writeOut(result.text);
 	});
-	add.command("mcp").description("Add an MCP backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--command <name>", "stdio command").option("--arg <value>", "stdio command argument", collect, []).option("--cwd <path>", "stdio working directory").option("--env <KEY=VALUE>", "stdio environment variable", collect, []).option("--url <url>", "remote MCP server URL").option("--transport <transport>", "remote transport: http or sse").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeAddResult(writeOut, "MCP", await remote.request("add", {
+	add.command("mcp").description("Add an MCP backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--command <name>", "stdio command").option("--arg <value>", "stdio command argument", collect, []).option("--cwd <path>", "stdio working directory").option("--env <KEY=VALUE>", "stdio environment variable", collect, []).option("--url <url>", "remote MCP server URL").option("--transport <transport>", "remote transport: http or sse").option("--token-env <ENV>", "bearer token environment variable reference").option("--project", "write to the project Caplets root").option("-g, --global", "write to the user Caplets root").option("--remote", "add through remote control").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			writeAddResult(writeOut, "MCP", await requireRemoteClientForTarget(io).request("add", {
 				kind: "mcp",
 				id,
 				options: remoteAddOptions(options)
 			}));
 			return;
 		}
-		writeAddResult(writeOut, "MCP", addMcpCaplet(id, {
+		const result = addMcpCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options, currentConfigPath())
-		}));
+			destinationRoot: addDestinationRoot(target, currentConfigPath(), env)
+		});
+		writeAddResult(writeOut, `${localMutationTargetLabel(target, io)}MCP`, result);
 	});
-	add.command("openapi").description("Add an OpenAPI backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--spec <path-or-url>", "OpenAPI spec path or URL").option("--base-url <url>", "request base URL override").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeAddResult(writeOut, "OpenAPI", await remote.request("add", {
+	add.command("openapi").description("Add an OpenAPI backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--spec <path-or-url>", "OpenAPI spec path or URL").option("--base-url <url>", "request base URL override").option("--token-env <ENV>", "bearer token environment variable reference").option("--project", "write to the project Caplets root").option("-g, --global", "write to the user Caplets root").option("--remote", "add through remote control").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			writeAddResult(writeOut, "OpenAPI", await requireRemoteClientForTarget(io).request("add", {
 				kind: "openapi",
 				id,
 				options: remoteAddOptions(options)
 			}));
 			return;
 		}
-		writeAddResult(writeOut, "OpenAPI", addOpenApiCaplet(id, {
+		const result = addOpenApiCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options, currentConfigPath())
-		}));
+			destinationRoot: addDestinationRoot(target, currentConfigPath(), env)
+		});
+		writeAddResult(writeOut, `${localMutationTargetLabel(target, io)}OpenAPI`, result);
 	});
-	add.command("graphql").description("Add a GraphQL backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--endpoint-url <url>", "GraphQL endpoint URL").option("--schema <path-or-url>", "GraphQL schema path or URL").option("--introspection", "load schema through endpoint introspection").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeAddResult(writeOut, "GraphQL", await remote.request("add", {
+	add.command("graphql").description("Add a GraphQL backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--endpoint-url <url>", "GraphQL endpoint URL").option("--schema <path-or-url>", "GraphQL schema path or URL").option("--introspection", "load schema through endpoint introspection").option("--token-env <ENV>", "bearer token environment variable reference").option("--project", "write to the project Caplets root").option("-g, --global", "write to the user Caplets root").option("--remote", "add through remote control").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			writeAddResult(writeOut, "GraphQL", await requireRemoteClientForTarget(io).request("add", {
 				kind: "graphql",
 				id,
 				options: remoteAddOptions(options)
 			}));
 			return;
 		}
-		writeAddResult(writeOut, "GraphQL", addGraphqlCaplet(id, {
+		const result = addGraphqlCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options, currentConfigPath())
-		}));
+			destinationRoot: addDestinationRoot(target, currentConfigPath(), env)
+		});
+		writeAddResult(writeOut, `${localMutationTargetLabel(target, io)}GraphQL`, result);
 	});
-	add.command("http").description("Add an HTTP actions backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--base-url <url>", "HTTP API base URL").option("--action <name:METHOD:/path>", "HTTP action", collect, []).option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeAddResult(writeOut, "HTTP", await remote.request("add", {
+	add.command("http").description("Add an HTTP actions backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--base-url <url>", "HTTP API base URL").option("--action <name:METHOD:/path>", "HTTP action", collect, []).option("--token-env <ENV>", "bearer token environment variable reference").option("--project", "write to the project Caplets root").option("-g, --global", "write to the user Caplets root").option("--remote", "add through remote control").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const target = parseMutationTarget(options);
+		if (target === "remote") {
+			writeAddResult(writeOut, "HTTP", await requireRemoteClientForTarget(io).request("add", {
 				kind: "http",
 				id,
 				options: remoteAddOptions(options)
 			}));
 			return;
 		}
-		writeAddResult(writeOut, "HTTP", addHttpCaplet(id, {
+		const result = addHttpCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options, currentConfigPath())
-		}));
+			destinationRoot: addDestinationRoot(target, currentConfigPath(), env)
+		});
+		writeAddResult(writeOut, `${localMutationTargetLabel(target, io)}HTTP`, result);
 	});
 	program.command(cliCommands.getCaplet).description("Print a configured Caplet card.").argument("<caplet>", "configured Caplet ID").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => {
 		await executeOperation(caplet, { operation: "get_caplet" }, {
@@ -68231,7 +68604,7 @@ function createProgram(io = {}) {
 		writeOut(`${resolveConfigPath(currentConfigPath())}\n`);
 	});
 	config.command("paths").description("Print resolved Caplets config, root, and auth paths.").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action((options) => {
-		const paths = resolveCliConfigPaths(currentConfigPath(), io.authDir);
+		const paths = resolveCliConfigPaths(currentConfigPath(), envProjectConfigPath(env), io.authDir);
 		if (options.json || options.format === "json") {
 			writeOut(`${JSON.stringify(paths, null, 2)}\n`);
 			return;
@@ -68239,60 +68612,59 @@ function createProgram(io = {}) {
 		writeOut(formatConfigPaths(paths, options.format ?? "plain"));
 	});
 	const auth = program.command(cliCommands.auth).description("Manage OAuth credentials for remote servers.");
-	auth.command("login").description("Authenticate a configured remote OAuth server.").argument("<server>", "configured server ID").option("--no-open", "print the authorization URL without opening a browser").action(async (serverId, options) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			const started = await remote.request("auth_login_start", { server: serverId });
-			if (started.authorizationUrl) {
-				writeOut(`Open this URL to authorize ${serverId}:\n${started.authorizationUrl}\n`);
-				if (options.open !== false) await openBrowser(started.authorizationUrl);
-				writeOut("Complete authentication in your browser. The server callback will store credentials.\n");
-				return;
-			}
-			if (started.authenticated) writeOut(`Authenticated \`${serverId}\`.\n`);
+	auth.command("login").description("Authenticate a configured remote OAuth server.").argument("<server>", "configured server ID").option("--project", "authenticate using the project Caplets config").option("-g, --global", "authenticate using the user Caplets config").option("--remote", "authenticate using the remote server auth store").option("--no-open", "print the authorization URL without opening a browser").action(async (serverId, options) => {
+		const target = await resolveAuthTarget(serverId, options, io);
+		if (target === "remote") {
+			await remoteAuthLogin(requireRemoteClientForTarget(io), serverId, options.open !== false, writeOut);
 			return;
 		}
 		const configPath = currentConfigPath();
+		const projectConfigPath = envProjectConfigPath(env);
 		await loginAuth(serverId, {
 			noOpen: options.open === false,
 			writeOut,
 			writeErr,
 			...configPath ? { configPath } : {},
+			...projectConfigPath ? { projectConfigPath } : {},
+			config: localAuthConfigForTarget({
+				serverId,
+				...configPath ? { configPath } : {},
+				...projectConfigPath ? { projectConfigPath } : {},
+				source: target
+			}),
 			...io.authDir ? { authDir: io.authDir } : {}
 		});
 	});
-	auth.command("logout").description("Delete stored OAuth credentials for a server.").argument("<server>", "configured server ID").action(async (serverId) => {
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			writeOut((await remote.request("auth_logout", { server: serverId })).deleted ? `Deleted remote OAuth credentials for \`${serverId}\`.\n` : `No remote OAuth credentials found for \`${serverId}\`.\n`);
+	auth.command("logout").description("Delete stored OAuth credentials for a server.").argument("<server>", "configured server ID").option("--project", "delete credentials for the project Caplets config target").option("-g, --global", "delete credentials for the user Caplets config target").option("--remote", "delete credentials from the remote server auth store").action(async (serverId, options) => {
+		const target = await resolveAuthTarget(serverId, options, io);
+		if (target === "remote") {
+			writeOut((await requireRemoteClientForTarget(io).request("auth_logout", { server: serverId })).deleted ? `Deleted remote OAuth credentials for \`${serverId}\`.\n` : `No remote OAuth credentials found for \`${serverId}\`.\n`);
 			return;
 		}
 		const configPath = currentConfigPath();
+		const projectConfigPath = envProjectConfigPath(env);
 		logoutAuth(serverId, {
 			writeOut,
 			...configPath ? { configPath } : {},
+			config: localAuthConfigForTarget({
+				serverId,
+				...configPath ? { configPath } : {},
+				...projectConfigPath ? { projectConfigPath } : {},
+				source: target
+			}),
 			...io.authDir ? { authDir: io.authDir } : {}
 		});
 	});
-	auth.command("list").description("List servers with stored OAuth credentials.").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action(async (options) => {
+	auth.command("list").description("List servers with stored OAuth credentials.").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).option("--project", "list auth targets from the project Caplets config").option("-g, --global", "list auth targets from the user Caplets config").option("--remote", "list auth targets from the remote server auth store").action(async (options) => {
 		const configPath = currentConfigPath();
+		const projectConfigPath = envProjectConfigPath(env);
 		const format = options.json || options.format === "json" ? "json" : options.format ?? "plain";
-		const remote = remoteClientForCli(io);
-		if (remote) {
-			const rows = await remote.request("auth_list", {});
-			if (format === "json") {
-				writeOut(`${JSON.stringify(rows, null, 2)}\n`);
-				return;
-			}
-			writeOut(formatAuthRows(rows, format));
+		const rows = await authListRowsForCli(parseAuthFlagTarget(options), io, configPath, projectConfigPath);
+		if (format === "json") {
+			writeOut(`${JSON.stringify(rows, null, 2)}\n`);
 			return;
 		}
-		listAuth({
-			writeOut,
-			format,
-			...configPath ? { configPath } : {},
-			...io.authDir ? { authDir: io.authDir } : {}
-		});
+		writeOut(formatAuthRows(rows, format));
 	});
 	return program;
 }
@@ -68336,12 +68708,90 @@ function remoteCommandForOperation(operation) {
 	}
 }
 function remoteAddOptions(options) {
-	const { output, print, global, destinationRoot, ...remoteOptions } = options;
-	if (global) throw new CapletsError("REQUEST_INVALID", "--global is not supported in remote mode; the server controls the add destination.");
+	const { output, print, global, project, remote, destinationRoot, ...remoteOptions } = options;
 	if (print) throw new CapletsError("REQUEST_INVALID", "--print is not supported in remote mode; the server controls add output.");
 	if (output !== void 0) throw new CapletsError("REQUEST_INVALID", "--output is not supported in remote mode; the server controls the add destination.");
 	return remoteOptions;
 }
+function parseMutationTarget(options) {
+	const selected = [
+		options.project ? "--project" : void 0,
+		options.global ? "--global" : void 0,
+		options.remote ? "--remote" : void 0
+	].filter((value) => value !== void 0);
+	if (selected.length > 1) throw new CapletsError("REQUEST_INVALID", `Cannot combine mutation target flags: ${selected.join(", ")}`);
+	if (options.global) return "global";
+	if (options.remote) return "remote";
+	return "project";
+}
+function localMutationTargetLabel(target, io) {
+	return remoteClientForCli(io) ? `${target} ` : "";
+}
+function parseAuthFlagTarget(options) {
+	const selected = [
+		options.project ? "--project" : void 0,
+		options.global ? "--global" : void 0,
+		options.remote ? "--remote" : void 0
+	].filter((value) => value !== void 0);
+	if (selected.length > 1) throw new CapletsError("REQUEST_INVALID", `Cannot combine auth target flags: ${selected.join(", ")}`);
+	if (options.project) return "project";
+	if (options.global) return "global";
+	if (options.remote) return "remote";
+}
+async function resolveAuthTarget(serverId, options, io) {
+	const explicit = parseAuthFlagTarget(options);
+	if (explicit) return explicit;
+	const env = io.env ?? process.env;
+	const configPath = envConfigPath(env);
+	const projectConfigPath = envProjectConfigPath(env);
+	const matches = localAuthTargets({
+		...configPath ? { configPath } : {},
+		...projectConfigPath ? { projectConfigPath } : {}
+	}).filter((target) => target.server === serverId).map((target) => target.source);
+	const remote = remoteClientForCli(io);
+	if (remote) {
+		if (matches.length === 0) matches.push("remote");
+		else if ((await remoteAuthRows(remote)).some((row) => row.server === serverId)) matches.push("remote");
+	}
+	const unique = [...new Set(matches)];
+	if (unique.length === 1) return unique[0];
+	if (unique.length > 1) throw new CapletsError("REQUEST_INVALID", `Auth target \`${serverId}\` exists in multiple scopes. Pass --project, --global, or --remote.`);
+	throw new CapletsError("SERVER_NOT_FOUND", `Server ${serverId} is not configured for OAuth`);
+}
+async function authListRowsForCli(target, io, configPath, projectConfigPath) {
+	if (target === "remote") return remoteAuthRows(requireRemoteClientForTarget(io));
+	const localRows = listLocalAuthRows({
+		...configPath ? { configPath } : {},
+		...projectConfigPath ? { projectConfigPath } : {},
+		...io.authDir ? { authDir: io.authDir } : {},
+		...target ? { source: target } : {}
+	});
+	if (target) return localRows;
+	const remote = remoteClientForCli(io);
+	if (!remote) return localRows;
+	return [...localRows, ...await remoteAuthRows(remote)].sort((left, right) => left.server.localeCompare(right.server));
+}
+async function remoteAuthRows(remote) {
+	return (await remote.request("auth_list", {})).map((row) => ({
+		...row,
+		source: "remote"
+	}));
+}
+async function remoteAuthLogin(remote, serverId, open, writeOut) {
+	const started = await remote.request("auth_login_start", { server: serverId });
+	if (started.authorizationUrl) {
+		writeOut(`Open this URL to authorize ${serverId}:\n${started.authorizationUrl}\n`);
+		if (open) await openBrowser(started.authorizationUrl);
+		writeOut("Complete authentication in your browser. The server callback will store credentials.\n");
+		return;
+	}
+	if (started.authenticated) writeOut(`Authenticated \`${serverId}\`.\n`);
+}
+function requireRemoteClientForTarget(io) {
+	const remote = remoteClientForCli(io);
+	if (!remote) throw new CapletsError("REQUEST_INVALID", "--remote requires CAPLETS_MODE=remote and CAPLETS_SERVER_URL");
+	return remote;
+}
 function collect(value, previous) {
 	previous.push(value);
 	return previous;
@@ -68378,8 +68828,10 @@ function parseQualifiedTarget(capletOrTarget, toolArgument) {
 async function completeCliWordsLocally(words, options) {
 	const engine = new CapletsEngine({
 		...options.configPath ? { configPath: options.configPath } : {},
+		...options.projectConfigPath ? { projectConfigPath: options.projectConfigPath } : {},
 		...options.authDir ? { authDir: options.authDir } : {},
-		watch: false
+		watch: false,
+		...options.config ? { configLoader: () => options.config } : {}
 	});
 	try {
 		return await engine.completeCliWords(words);
@@ -68387,6 +68839,34 @@ async function completeCliWordsLocally(words, options) {
 		await engine.close();
 	}
 }
+function mergeCompletionSuggestions(...groups) {
+	return [...new Set(groups.flat())];
+}
+function localShadowedCompletionTarget(words, config) {
+	const command = words[0];
+	const target = words[1];
+	if (!command || !target || target.startsWith("-")) return;
+	const qualifiedCommands = new Set([
+		cliCommands.getTool,
+		cliCommands.callTool,
+		cliCommands.getPrompt
+	]);
+	const capletCommands = new Set([
+		cliCommands.getCaplet,
+		cliCommands.checkBackend,
+		cliCommands.listTools,
+		cliCommands.searchTools,
+		cliCommands.listResources,
+		cliCommands.searchResources,
+		cliCommands.listResourceTemplates,
+		cliCommands.readResource,
+		cliCommands.listPrompts,
+		cliCommands.searchPrompts,
+		cliCommands.complete
+	]);
+	const caplet = qualifiedCommands.has(command) ? target.slice(0, target.includes(".") ? target.indexOf(".") : target.length) : capletCommands.has(command) ? target : void 0;
+	return caplet && hasEnabledCaplet(config, caplet) ? caplet : void 0;
+}
 function parseCallToolArgs(value) {
 	if (value === void 0) return {};
 	let parsed;
@@ -68427,6 +68907,11 @@ function isPlainObject(value) {
 async function executeOperation(caplet, request, io) {
 	const command = remoteCommandForOperation(request.operation);
 	if (io.remote && command) {
+		const localOverlay = tryLoadLocalOverlayForCli(io, io.writeErr);
+		if (localOverlay && hasEnabledCaplet(localOverlay.config, caplet)) {
+			await executeLocalOperation(caplet, request, io, localOverlay.config);
+			return;
+		}
 		const result = await io.remote.request(command, {
 			caplet,
 			request
@@ -68439,12 +68924,119 @@ async function executeOperation(caplet, request, io) {
 		if (isPlainObject(result) && result.isError === true) io.setExitCode(1);
 		return;
 	}
+	await executeLocalOperation(caplet, request, io);
+}
+function loadLocalOverlayForCli(io, writeErr) {
+	const env = io.env ?? process.env;
+	const overlay = loadLocalOverlayConfigWithSources(resolveConfigPath(envConfigPath(env)), envProjectConfigPath(env));
+	for (const warning of overlay.warnings) writeErr(`Warning: ${warning.kind} at ${warning.path}: ${warning.message}\n`);
+	return overlay;
+}
+function tryLoadLocalOverlayForCli(io, writeErr) {
+	try {
+		return loadLocalOverlayForCli(io, writeErr);
+	} catch (error) {
+		writeErr(`Warning: Could not load local Caplets overlay: ${formatErrorMessage(error)}\n`);
+		return loadPartialLocalOverlayForCli(io, writeErr);
+	}
+}
+function loadPartialLocalOverlayForCli(io, writeErr) {
+	const env = io.env ?? process.env;
+	const configPath = resolveConfigPath(envConfigPath(env));
+	const projectConfigPath = envProjectConfigPath(env);
+	const absentProjectPath = join(dirname(configPath), ".caplets-overlay-recovery", "config.json");
+	const absentGlobalPath = join(dirname(projectConfigPath), ".caplets-overlay-recovery", "config.json");
+	const globalOverlay = tryLoadPartialOverlayLayer("global", configPath, absentProjectPath, writeErr);
+	const projectOverlay = tryLoadPartialOverlayLayer("project", absentGlobalPath, projectConfigPath, writeErr);
+	if (!globalOverlay) return projectOverlay;
+	if (!projectOverlay) return globalOverlay;
+	return mergePartialLocalOverlays(globalOverlay, projectOverlay);
+}
+function tryLoadPartialOverlayLayer(label, configPath, projectConfigPath, writeErr) {
+	try {
+		const overlay = loadLocalOverlayConfigWithSources(configPath, projectConfigPath);
+		for (const warning of overlay.warnings) writeErr(`Warning: ${warning.kind} at ${warning.path}: ${warning.message}\n`);
+		return overlay;
+	} catch (error) {
+		writeErr(`Warning: Could not load ${label} Caplets overlay: ${formatErrorMessage(error)}\n`);
+		return;
+	}
+}
+function mergePartialLocalOverlays(globalOverlay, projectOverlay) {
+	const config = { ...globalOverlay.config };
+	const sources = { ...globalOverlay.sources };
+	const shadows = { ...globalOverlay.shadows };
+	for (const kind of capletConfigKinds) config[kind] = { ...globalOverlay.config[kind] };
+	for (const kind of capletConfigKinds) for (const id of Object.keys(projectOverlay.config[kind])) {
+		removeCapletFromPartialOverlay(config, sources, shadows, id);
+		config[kind][id] = projectOverlay.config[kind][id];
+	}
+	for (const [id, source] of Object.entries(projectOverlay.sources)) sources[id] = source;
+	for (const [id, shadowedSources] of Object.entries(projectOverlay.shadows)) shadows[id] = [...shadows[id] ?? [], ...shadowedSources];
+	return {
+		config,
+		sources,
+		shadows,
+		warnings: [...globalOverlay.warnings, ...projectOverlay.warnings]
+	};
+}
+const capletConfigKinds = [
+	"mcpServers",
+	"openapiEndpoints",
+	"graphqlEndpoints",
+	"httpApis",
+	"cliTools",
+	"capletSets"
+];
+function removeCapletFromPartialOverlay(config, sources, shadows, id) {
+	for (const kind of capletConfigKinds) delete config[kind][id];
+	if (sources[id]) shadows[id] = [...shadows[id] ?? [], sources[id]];
+	delete sources[id];
+}
+function formatErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function envProjectConfigPath(env) {
+	return env.CAPLETS_PROJECT_CONFIG?.trim() || resolveProjectConfigPath();
+}
+function envProjectCapletsRoot(env) {
+	const projectConfigPath = env.CAPLETS_PROJECT_CONFIG?.trim();
+	return projectConfigPath ? dirname(projectConfigPath) : resolveProjectCapletsRoot();
+}
+function mergeRemoteAndLocalRows(remoteRows, localOverlay, options) {
+	const rows = /* @__PURE__ */ new Map();
+	for (const row of remoteRows) rows.set(row.server, {
+		...row,
+		source: "remote"
+	});
+	if (!localOverlay) return [...rows.values()].filter((row) => options.includeDisabled || !row.disabled).sort((left, right) => left.server.localeCompare(right.server));
+	for (const row of listCaplets(localOverlay, { includeDisabled: true })) {
+		if (rows.get(row.server)) {
+			if (row.disabled) continue;
+			options.writeErr(`Warning: ${formatOverlaySource(row.source)} Caplet ${row.server} shadows remote Caplet\n`);
+		}
+		rows.set(row.server, row);
+	}
+	return [...rows.values()].filter((row) => options.includeDisabled || !row.disabled).sort((left, right) => left.server.localeCompare(right.server));
+}
+function formatOverlaySource(kind) {
+	if (kind.startsWith("project")) return "project";
+	if (kind.startsWith("global")) return "global";
+	return kind;
+}
+function hasEnabledCaplet(config, id) {
+	const caplet = config.mcpServers[id] ?? config.openapiEndpoints[id] ?? config.graphqlEndpoints[id] ?? config.httpApis[id] ?? config.cliTools[id] ?? config.capletSets[id];
+	return Boolean(caplet && !caplet.disabled);
+}
+async function executeLocalOperation(caplet, request, io, config) {
 	const configPath = envConfigPath(io.env ?? process.env);
 	const engine = new CapletsEngine({
 		...configPath ? { configPath } : {},
+		projectConfigPath: envProjectConfigPath(io.env ?? process.env),
 		...io.authDir ? { authDir: io.authDir } : {},
 		watch: false,
-		writeErr: io.writeErr
+		writeErr: io.writeErr,
+		...config ? { configLoader: () => config } : {}
 	});
 	try {
 		const result = await engine.execute(caplet, request);
@@ -68799,8 +69391,8 @@ function schemaSummary(schema) {
 		required.length > 0 ? `required ${required.join(", ")}` : "no required fields"
 	].filter((part) => Boolean(part)).join("; ");
 }
-function addDestinationRoot(options, configPath) {
-	return options.global ? resolveCapletsRoot(resolveConfigPath(configPath)) : resolveProjectCapletsRoot();
+function addDestinationRoot(target, configPath, env) {
+	return target === "global" ? resolveCapletsRoot(resolveConfigPath(configPath)) : envProjectCapletsRoot(env);
 }
 function writeAddResult(writeOut, label, result) {
 	if (result.path) {
@@ -68811,7 +69403,7 @@ function writeAddResult(writeOut, label, result) {
 }
 //#endregion
 //#region package.json
-var version = "0.17.2";
+var version = "0.17.4";
 //#endregion
 //#region src/index.ts
 async function main() {