caplets 0.17.3 → 0.17.5

package/README.md

@@ -219,6 +219,12 @@ opencode
 
 For MCP-backed Codex or Claude Code configs, point the agent's MCP server entry at the derived `/mcp` URL using that agent's supported HTTP MCP configuration. If Basic Auth is needed, use the agent's secure secret or environment interpolation mechanism rather than hardcoding credentials.
 
+In `CAPLETS_MODE=remote`, read and execute commands use a merged Caplets view. Remote server rows load first, user-global local Caplets overlay them, and project-local Caplets have the highest priority. A local Caplet with the same ID shadows the remote one, runs locally, and prints a warning such as `Warning: project Caplet shared shadows remote Caplet`; remote-only IDs continue through remote control.
+
+Local overlays in remote mode are best-effort. Invalid local config sources warn and are ignored while remaining valid layers still load; invalid Caplet files warn and are skipped individually. For sibling file layouts, `foo/CAPLET.md` wins over `foo.md` and warns that `foo.md` was shadowed; if the winning `CAPLET.md` is invalid, that local ID is skipped instead of falling back to `foo.md`.
+
+Mutating commands do not automatically write to the server just because remote mode is active. `caplets init`, `caplets add ...`, and `caplets install ...` write project-local by default, `--project` is the explicit project-local target, `--global` writes user-global local files, and `--remote` sends the mutation to the remote Caplets server. Target flags are mutually exclusive.
+
 ## Convert Existing Tooling
 
 Caplets is designed to convert what you already use into agent-friendly capability domains.
@@ -299,7 +305,7 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## Capabilities
 
-- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, explicit HTTP API action definitions, and curated CLI tool definitions from the user config file.
+- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, explicit HTTP API action definitions, and curated CLI tool definitions from user and project config sources.
 - Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, or CLI tools backend.
 - Uses the configured server ID as the generated tool name.
 - Uses the configured `name` and `description` as the capability card shown to agents.
@@ -316,12 +322,20 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## Configure
 
-Create a starter user config at `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows:
+Create a starter project config at `./.caplets/config.json`:
 
 ```sh
 caplets init
 ```
 
+To create a starter user config instead, pass `--global`. The user config path is
+`${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms and
+`%APPDATA%\caplets\config.json` on Windows:
+
+```sh
+caplets init --global
+```
+
 The generated config includes a disabled example server. Replace it with the MCP servers
 you want Caplets to expose:
 
@@ -406,10 +420,12 @@ you want Caplets to expose:
 }
 ```
 
-The default config path is `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms and `%APPDATA%\caplets\config.json` on Windows. It can be overridden with `CAPLETS_CONFIG`:
+The user config path can be overridden with `CAPLETS_CONFIG`; the project config path can be
+overridden with `CAPLETS_PROJECT_CONFIG`:
 
 ```sh
-CAPLETS_CONFIG=/path/to/config.json caplets init
+CAPLETS_PROJECT_CONFIG=/path/to/project/.caplets/config.json caplets init
+CAPLETS_CONFIG=/path/to/user/config.json caplets init --global
 CAPLETS_CONFIG=/path/to/config.json caplets serve
 ```
 
@@ -422,10 +438,9 @@ caplets config paths
 caplets config paths --json
 ```
 
-Caplets validates this file at startup and hot reloads config changes while `caplets serve`
+Caplets validates config files at startup and hot reloads config changes while `caplets serve`
 is running. Invalid edits are ignored until fixed, so the MCP server keeps serving the last
-known-good config instead of dropping every tool because of a transient JSON or validation
-error.
+known-good config instead of dropping every tool because of a transient JSON or validation error.
 
 The optional `$schema` field points editors at the generated JSON Schema in
 [`schemas/caplets-config.schema.json`](schemas/caplets-config.schema.json). CI verifies that
@@ -591,12 +606,14 @@ That means a project-local Caplet can intentionally replace a user-level Caplet
 Use `caplets list` to see each Caplet's winning source; when a project Caplet shadows a user-level
 Caplet, the list output includes a warning naming the shadowed path.
 
-`caplets init` refuses to overwrite an existing config. To intentionally replace the file:
+`caplets init` refuses to overwrite an existing project config. To intentionally replace the file:
 
 ```sh
 caplets init --force
 ```
 
+Use `caplets init --global --force` to replace the user config instead.
+
 ### Caplet IDs
 
 Each key under `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, or `capletSets` is the
@@ -914,11 +931,16 @@ caplets auth login <server> --no-open
 In local mode, OAuth/OIDC tokens are stored under
 `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json` on Unix-like platforms and
 `%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows. Token files use owner-only file
-permissions where the platform supports them. In `CAPLETS_MODE=remote`, `caplets auth list`,
-`caplets auth login <server>`, and `caplets auth logout <server>` operate on the configured Caplets
-server instead. Downstream OAuth/OIDC credentials are stored server-side and are not returned to the
-local client. Caplets supports well-known OAuth/OIDC discovery and dynamic client registration when
-advertised. When a token expires, run `caplets auth login <server>` again.
+permissions where the platform supports them. In `CAPLETS_MODE=remote`, `caplets auth list` shows
+local and remote auth targets with a `source` field. `caplets auth login <server>` and
+`caplets auth logout <server>` use the matching scope when it is unambiguous; if the same ID exists
+in multiple scopes, pass `--project`, `--global`, or `--remote`. Remote OAuth/OIDC credentials are
+stored server-side and are not returned to the local client. Caplets supports well-known OAuth/OIDC
+discovery and dynamic client registration when advertised. When a token expires, run
+`caplets auth login <server>` again.
+
+Auth target flags are mutually exclusive. `caplets auth list --project`,
+`caplets auth list --global`, and `caplets auth list --remote` filter the listing to one scope.
 
 To inspect or remove stored OAuth credentials:
 

package/dist/index.js

@@ -4709,7 +4709,7 @@ function generatedToolInputJsonSchema() {
 	return generatedToolInputJsonSchemaForCaplet({ backend: "tool" });
 }
 //#endregion
-//#region ../core/dist/options-j9p3L3r1.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$2(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$2(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;
@@ -57594,6 +57857,7 @@ var CapletsEngine = class {
 	watchDebounceMs;
 	watchEnabled;
 	writeErr;
+	configLoader;
 	reloadListeners = /* @__PURE__ */ new Set();
 	watchers = [];
 	reloadTimer;
@@ -57606,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));
@@ -57661,7 +57926,7 @@ var CapletsEngine = class {
 		}
 	}
 	async completeCliWords(words) {
-		const { completeCliWords } = await Promise.resolve().then(() => completion_Cq1z7ci2_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: {
@@ -57721,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`);
@@ -57999,8 +58264,8 @@ function hasEnv$1(value) {
 	return value !== void 0 && value.trim() !== "";
 }
 //#endregion
-//#region ../core/dist/completion-Cq1z7ci2.js
-var completion_Cq1z7ci2_exports = /* @__PURE__ */ __exportAll$1({
+//#region ../core/dist/completion-DRPTunQd.js
+var completion_DRPTunQd_exports = /* @__PURE__ */ __exportAll$1({
 	a: () => formatCapletList,
 	c: () => resolveCliConfigPaths,
 	i: () => trailingSpaceCompletionToken,
@@ -58122,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") {
@@ -58174,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
 	};
@@ -59863,7 +60129,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 	values: [],
 	hasMore: false
 } };
-var version$1 = "0.18.3";
+var version$1 = "0.18.5";
 var CapletsMcpSession = class {
 	engine;
 	server;
@@ -63379,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 = {
@@ -63401,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;
@@ -63442,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";
@@ -67942,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`);
 	});
@@ -67962,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;
@@ -67986,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)
@@ -68008,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)
@@ -68025,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" }, {
@@ -68293,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;
@@ -68301,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;
 }
@@ -68398,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;
@@ -68440,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);
@@ -68449,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;
@@ -68489,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
@@ -68501,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);
@@ -68861,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) {
@@ -68873,15 +69403,18 @@ function writeAddResult(writeOut, label, result) {
 }
 //#endregion
 //#region package.json
-var version = "0.17.3";
+var version = "0.17.5";
 //#endregion
 //#region src/index.ts
 async function main() {
 	await runCli(process.argv.slice(2), { version });
 }
 main().catch((error) => {
-	console.error(error);
+	process.stderr.write(`${errorMessage(error)}\n`);
 	process.exit(1);
 });
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caplets",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "description": "Progressive disclosure gateway CLI for MCP servers and native Caplets adapters.",
   "keywords": [
     "caplets",
@@ -34,11 +34,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@caplets/core": "0.18.3"
+    "@caplets/core": "0.18.5"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260519.1",
+    "@typescript/native-preview": "7.0.0-dev.20260523.1",
     "rolldown": "^1.0.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7"
@@ -47,8 +47,9 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "rm -rf dist && rolldown -c",
-    "build:watch": "rm -rf dist && rolldown -c --watch",
+    "clean": "rm -rf dist",
+    "build": "pnpm run clean && rolldown -c",
+    "build:watch": "pnpm run clean && rolldown -c --watch",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run"
   }