caplets 0.5.1 → 0.6.0

package/README.md

@@ -129,6 +129,15 @@ CAPLETS_CONFIG=/path/to/config.json caplets init
 CAPLETS_CONFIG=/path/to/config.json caplets serve
 ```
 
+Inspect the installed CLI version and resolved config locations:
+
+```sh
+caplets --version
+caplets config path
+caplets config paths
+caplets config paths --json
+```
+
 Caplets validates this file at startup. Config changes take effect after restarting the
 Caplets MCP server.
 
@@ -201,6 +210,30 @@ Top-level files derive their Caplet ID from the filename. Directory-style Caplet
 `linear/CAPLET.md`, which is exposed as `linear`; sibling files can be referenced with
 normal Markdown links from `CAPLET.md`.
 
+This repository includes polished working examples under [`caplets/`](caplets/):
+
+- `github`: GitHub's official MCP server container, using `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- `linear`: Linear's hosted OAuth MCP endpoint.
+- `context7`: Context7 documentation lookup through `@upstash/context7-mcp`.
+
+Install every example from a repo's `caplets/` directory:
+
+```sh
+caplets install spiritledsoftware/caplets
+```
+
+Install one or more individual Caplets by ID:
+
+```sh
+caplets install spiritledsoftware/caplets github
+caplets install spiritledsoftware/caplets github linear
+```
+
+`caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
+It installs into your user Caplets root, which is `~/.caplets` by default or the parent directory
+of `CAPLETS_CONFIG` when that environment variable is set. Existing Caplets are not overwritten
+unless `--force` is passed.
+
 Caplets always loads user Caplet files from `~/.caplets`. Project `./.caplets/config.json`
 is still loaded as project config, but project Markdown Caplet files are executable
 configuration and are ignored unless explicitly trusted:
@@ -390,6 +423,14 @@ caplets auth list
 caplets auth logout <server>
 ```
 
+To list configured Caplets without starting downstream backends:
+
+```sh
+caplets list
+caplets list --all
+caplets list --json
+```
+
 ### Optional Server Settings
 
 Every server can set:

package/caplets/context7.md

@@ -0,0 +1,33 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Context7 Documentation
+description: Fetch current library and framework documentation through Context7 before using version-sensitive APIs.
+tags:
+  - docs
+  - libraries
+  - frameworks
+  - api-reference
+mcpServer:
+  command: npx
+  args:
+    - -y
+    - "@upstash/context7-mcp"
+---
+
+# Context7 Documentation
+
+Use this Caplet when the agent needs up-to-date library, SDK, framework, CLI, or cloud-service
+documentation before writing code or giving technical instructions.
+
+## Good Fits
+
+- Check current API signatures for fast-moving JavaScript, TypeScript, Python, or cloud libraries.
+- Look up migration notes before changing framework configuration.
+- Retrieve official examples for a specific package version.
+- Resolve uncertainty about CLI flags, config files, or SDK initialization.
+
+## Use Carefully
+
+- Prefer primary documentation over snippets when implementation risk is high.
+- Record the library or package name clearly before searching.
+- Do not use this as a substitute for project-local types and tests.

package/caplets/github/CAPLET.md

@@ -0,0 +1,54 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: GitHub
+description: Inspect and manage GitHub repositories, issues, pull requests, branches, commits, and code review workflows.
+tags:
+  - code
+  - github
+  - pull-requests
+  - issues
+  - reviews
+mcpServer:
+  command: docker
+  args:
+    - run
+    - -i
+    - --rm
+    - -e
+    - GITHUB_PERSONAL_ACCESS_TOKEN
+    - ghcr.io/github/github-mcp-server
+  env:
+    GITHUB_PERSONAL_ACCESS_TOKEN: $env:GITHUB_PERSONAL_ACCESS_TOKEN
+---
+
+# GitHub
+
+Use this Caplet when the agent needs live GitHub repository context or needs to act on
+issues, pull requests, branches, commits, or review feedback.
+
+## Good Fits
+
+- Summarize recent pull request activity before a code review.
+- Inspect open issues and identify implementation work.
+- Create or update issues from an implementation plan.
+- Compare branches, inspect commits, or review pull request files.
+- Leave review comments after the agent has inspected the relevant diff.
+
+## Use Carefully
+
+- Mutating operations can affect real repositories. Prefer read operations first.
+- Use a least-privilege `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- Do not ask the agent to expose token values, repository secrets, or private issue contents outside
+  the intended conversation.
+
+## Setup
+
+Create a GitHub personal access token with the minimum repository scopes needed for your workflow,
+then export it before starting Caplets:
+
+```sh
+export GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_...
+caplets serve
+```
+
+This Caplet uses GitHub's official MCP server container, so Docker must be available on the host.

package/caplets/github/README.md

@@ -0,0 +1,13 @@
+# GitHub Caplet
+
+This Caplet wraps GitHub's official MCP server container:
+
+```sh
+docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
+```
+
+Install it from this repo:
+
+```sh
+caplets install spiritledsoftware/caplets github
+```

package/caplets/linear/CAPLET.md

@@ -0,0 +1,50 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Linear
+description: Plan and track product work in Linear by reading teams, projects, cycles, issues, comments, and workflow state.
+tags:
+  - planning
+  - linear
+  - issues
+  - projects
+  - triage
+mcpServer:
+  transport: http
+  url: https://mcp.linear.app/mcp
+  auth:
+    type: oauth2
+---
+
+# Linear
+
+Use this Caplet when the agent needs live product planning context from Linear or needs to keep
+implementation work synchronized with issues, projects, and team workflows.
+
+## Good Fits
+
+- Find the current issue or project that matches a requested feature.
+- Summarize open work by team, project, cycle, label, or assignee.
+- Draft issue breakdowns from a technical plan.
+- Add implementation notes or status comments after code changes.
+- Check whether a bug or feature already has active work before creating a new issue.
+
+## Reference Files
+
+- [Workflows](./workflows.md): recommended lookup, planning, status update, and triage flows.
+
+## Use Carefully
+
+- Linear issue updates are visible to teammates. Read first, then write deliberately.
+- Keep issue titles and comments concise; use links to detailed implementation artifacts when useful.
+- Avoid broad, noisy searches when a team key, issue ID, project, or label is available.
+
+## Setup
+
+Authenticate once through Caplets:
+
+```sh
+caplets auth login linear
+```
+
+The Linear MCP endpoint supports OAuth. Caplets stores the resulting token bundle in your local
+Caplets auth store.

package/caplets/linear/workflows.md

@@ -0,0 +1,9 @@
+# Linear Workflows
+
+Useful agent flows:
+
+- **Issue lookup**: search by issue key first, then by title or project if no key is provided.
+- **Planning**: read project context, summarize constraints, then create child issues only when the
+  requested breakdown is clear.
+- **Status updates**: comment with what changed, verification run, and remaining risk.
+- **Triage**: group candidate issues by urgency, owner, and whether they are blocked.

package/dist/index.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import minproc, { stdin, stdout, default as process$1 } from "node:process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import minpath, { basename, dirname, extname, isAbsolute, join } from "node:path";
+import { accessSync, chmodSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import minpath, { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath as urlToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
 import { PassThrough } from "node:stream";
 import { createServer } from "node:http";
 import { createHash, randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -19848,7 +19849,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 } };
 //#endregion
 //#region package.json
-var version = "0.5.1";
+var version = "0.6.0";
 //#endregion
 //#region node_modules/.pnpm/@modelcontextprotocol+sdk@1.29.0_zod@4.4.3/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
 /**
@@ -27413,6 +27414,42 @@ function matter(file, options) {
 	} else file.data.matter = {};
 }
 //#endregion
+//#region src/config/validation.ts
+const SERVER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const FORBIDDEN_HEADERS = new Set([
+	"accept",
+	"authorization",
+	"connection",
+	"content-length",
+	"content-type",
+	"host",
+	"keep-alive",
+	"mcp-protocol-version",
+	"mcp-session-id",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+]);
+function isAllowedRemoteUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	if (url.protocol === "https:") return true;
+	return url.protocol === "http:" && [
+		"localhost",
+		"127.0.0.1",
+		"[::1]",
+		"::1"
+	].includes(url.hostname);
+}
+//#endregion
 //#region src/errors.ts
 var CapletsError = class extends Error {
 	code;
@@ -27465,25 +27502,6 @@ function errorResult(error, fallback) {
 //#region src/caplet-files.ts
 const MAX_CAPLET_FILE_BYTES = 128 * 1024;
 const MAX_CAPLET_BODY_CHARS = 64 * 1024;
-const SERVER_ID_PATTERN$1 = /^[a-zA-Z0-9_-]{1,64}$/;
-const HEADER_NAME_PATTERN$1 = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-const FORBIDDEN_HEADERS$1 = new Set([
-	"accept",
-	"authorization",
-	"connection",
-	"content-length",
-	"content-type",
-	"host",
-	"keep-alive",
-	"mcp-protocol-version",
-	"mcp-session-id",
-	"proxy-authenticate",
-	"proxy-authorization",
-	"te",
-	"trailer",
-	"transfer-encoding",
-	"upgrade"
-]);
 const capletRemoteAuthSchema = discriminatedUnion("type", [
 	object({ type: literal("none") }).strict(),
 	object({
@@ -27590,7 +27608,7 @@ const capletMcpServerSchema = object({
 		path: ["url"],
 		message: "remote servers require url"
 	});
-	if (server.url && !hasEnvReference$1(server.url) && !isAllowedRemoteUrl$1(server.url)) ctx.addIssue({
+	if (server.url && !hasEnvReference$1(server.url) && !isAllowedRemoteUrl(server.url)) ctx.addIssue({
 		code: "custom",
 		path: ["url"],
 		message: "remote url must use https except loopback development urls"
@@ -27610,7 +27628,7 @@ const capletMcpServerSchema = object({
 	}
 	if (server.auth?.type === "headers") for (const headerName of Object.keys(server.auth.headers)) {
 		const normalized = headerName.toLowerCase();
-		if (!HEADER_NAME_PATTERN$1.test(headerName) || FORBIDDEN_HEADERS$1.has(normalized)) ctx.addIssue({
+		if (!HEADER_NAME_PATTERN.test(headerName) || FORBIDDEN_HEADERS.has(normalized)) ctx.addIssue({
 			code: "custom",
 			path: [
 				"auth",
@@ -27634,12 +27652,12 @@ const capletOpenApiEndpointSchema = object({
 		code: "custom",
 		message: "openapiEndpoint must define exactly one spec source: specPath or specUrl"
 	});
-	if (endpoint.specUrl && !hasEnvReference$1(endpoint.specUrl) && !isAllowedRemoteUrl$1(endpoint.specUrl)) ctx.addIssue({
+	if (endpoint.specUrl && !hasEnvReference$1(endpoint.specUrl) && !isAllowedRemoteUrl(endpoint.specUrl)) ctx.addIssue({
 		code: "custom",
 		path: ["specUrl"],
 		message: "OpenAPI specUrl must use https except loopback development urls"
 	});
-	if (endpoint.baseUrl && !hasEnvReference$1(endpoint.baseUrl) && !isAllowedRemoteUrl$1(endpoint.baseUrl)) ctx.addIssue({
+	if (endpoint.baseUrl && !hasEnvReference$1(endpoint.baseUrl) && !isAllowedRemoteUrl(endpoint.baseUrl)) ctx.addIssue({
 		code: "custom",
 		path: ["baseUrl"],
 		message: "OpenAPI baseUrl must use https except loopback development urls"
@@ -27662,7 +27680,7 @@ const capletGraphQlEndpointSchema = object({
 	schemaPath: string().min(1).optional().describe("Local GraphQL SDL or introspection path."),
 	schemaUrl: string().min(1).optional().describe("Remote GraphQL SDL or introspection URL."),
 	introspection: literal(true).optional().describe("Load schema through endpoint introspection."),
-	operations: record(string().regex(SERVER_ID_PATTERN$1), capletGraphQlOperationSchema).optional().describe("Configured GraphQL operations keyed by stable tool name."),
+	operations: record(string().regex(SERVER_ID_PATTERN), capletGraphQlOperationSchema).optional().describe("Configured GraphQL operations keyed by stable tool name."),
 	auth: capletEndpointAuthSchema.describe("Explicit GraphQL request auth config. Use {\"type\":\"none\"} for public APIs."),
 	requestTimeoutMs: number$1().int().positive().optional().describe("Timeout in milliseconds for GraphQL HTTP requests."),
 	operationCacheTtlMs: number$1().int().nonnegative().optional().describe("Milliseconds GraphQL operation metadata stays fresh. Set 0 to refresh every time."),
@@ -27673,12 +27691,12 @@ const capletGraphQlEndpointSchema = object({
 		code: "custom",
 		message: "graphqlEndpoint must define exactly one schema source: schemaPath, schemaUrl, or introspection"
 	});
-	if (endpoint.endpointUrl && !hasEnvReference$1(endpoint.endpointUrl) && !isAllowedRemoteUrl$1(endpoint.endpointUrl)) ctx.addIssue({
+	if (endpoint.endpointUrl && !hasEnvReference$1(endpoint.endpointUrl) && !isAllowedRemoteUrl(endpoint.endpointUrl)) ctx.addIssue({
 		code: "custom",
 		path: ["endpointUrl"],
 		message: "GraphQL endpointUrl must use https except loopback development urls"
 	});
-	if (endpoint.schemaUrl && !hasEnvReference$1(endpoint.schemaUrl) && !isAllowedRemoteUrl$1(endpoint.schemaUrl)) ctx.addIssue({
+	if (endpoint.schemaUrl && !hasEnvReference$1(endpoint.schemaUrl) && !isAllowedRemoteUrl(endpoint.schemaUrl)) ctx.addIssue({
 		code: "custom",
 		path: ["schemaUrl"],
 		message: "GraphQL schemaUrl must use https except loopback development urls"
@@ -27756,6 +27774,9 @@ function readCapletFile(path) {
 	if (!parsed.success) throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} has invalid frontmatter`, parsed.error.issues);
 	return capletToServerConfig(parsed.data, body, dirname(path));
 }
+function validateCapletFile(path) {
+	readCapletFile(path);
+}
 function capletToServerConfig(frontmatter, body, baseDir) {
 	if (frontmatter.openapiEndpoint) return {
 		...frontmatter.openapiEndpoint,
@@ -27799,7 +27820,7 @@ function validateEndpointAuthHeaders$1(auth, ctx) {
 	if (auth?.type !== "headers") return;
 	for (const headerName of Object.keys(auth.headers)) {
 		const normalized = headerName.toLowerCase();
-		if (!HEADER_NAME_PATTERN$1.test(headerName) || FORBIDDEN_HEADERS$1.has(normalized)) ctx.addIssue({
+		if (!HEADER_NAME_PATTERN.test(headerName) || FORBIDDEN_HEADERS.has(normalized)) ctx.addIssue({
 			code: "custom",
 			path: [
 				"auth",
@@ -27831,7 +27852,7 @@ function isPlainObject$2(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function validateCapletId(id, path) {
-	if (!SERVER_ID_PATTERN$1.test(id)) throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} derives invalid ID ${id}; ID must match ^[a-zA-Z0-9_-]{1,64}$`);
+	if (!SERVER_ID_PATTERN.test(id)) throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} derives invalid ID ${id}; ID must match ^[a-zA-Z0-9_-]{1,64}$`);
 }
 function hasEnvReference$1(value) {
 	return /\$\{[A-Za-z_][A-Za-z0-9_]*\}|\$env:[A-Za-z_][A-Za-z0-9_]*/.test(value);
@@ -27844,48 +27865,35 @@ function isUrl(value) {
 		return false;
 	}
 }
-function isAllowedRemoteUrl$1(value) {
-	const url = new URL(value);
-	if (url.protocol === "https:") return true;
-	if (url.protocol !== "http:") return false;
-	return [
-		"localhost",
-		"127.0.0.1",
-		"[::1]",
-		"::1"
-	].includes(url.hostname);
+//#endregion
+//#region src/config/paths.ts
+const DEFAULT_CONFIG_PATH = join(homedir(), ".caplets", "config.json");
+const DEFAULT_AUTH_DIR = join(homedir(), ".caplets", "auth");
+const PROJECT_CONFIG_FILE = join(".caplets", "config.json");
+const TRUST_PROJECT_CAPLETS_ENV = "CAPLETS_TRUST_PROJECT_CAPLETS";
+function resolveConfigPath(path) {
+	return path ?? DEFAULT_CONFIG_PATH;
+}
+function resolveProjectConfigPath(cwd = process.cwd()) {
+	return join(cwd, PROJECT_CONFIG_FILE);
+}
+function resolveCapletsRoot(configPath = resolveConfigPath()) {
+	return dirname(configPath);
+}
+function resolveProjectCapletsRoot(cwd = process.cwd()) {
+	return join(cwd, ".caplets");
+}
+function isTrustedEnvEnabled(value) {
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
 }
 //#endregion
 //#region src/config.ts
-const SERVER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
-const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-const FORBIDDEN_HEADERS = new Set([
-	"accept",
-	"authorization",
-	"connection",
-	"content-length",
-	"content-type",
-	"host",
-	"keep-alive",
-	"mcp-protocol-version",
-	"mcp-session-id",
-	"proxy-authenticate",
-	"proxy-authorization",
-	"te",
-	"trailer",
-	"transfer-encoding",
-	"upgrade"
-]);
 const NON_INTERPOLATED_SERVER_FIELDS = new Set([
 	"name",
 	"description",
 	"tags",
 	"body"
 ]);
-join(homedir(), ".caplets", "config.json");
-join(homedir(), ".caplets", "auth");
-const PROJECT_CONFIG_FILE = join(".caplets", "config.json");
-const TRUST_PROJECT_CAPLETS_ENV = "CAPLETS_TRUST_PROJECT_CAPLETS";
 const remoteAuthSchema = discriminatedUnion("type", [
 	object({ type: literal("none") }).strict(),
 	object({
@@ -28192,15 +28200,6 @@ function configSchemaFor(serverValueSchema, openApiEndpointValueSchema, graphQlE
 }
 const configFileSchema = configSchemaFor(publicServerSchema, publicOpenApiEndpointSchema, publicGraphQlEndpointSchema);
 const normalizedConfigFileSchema = configSchemaFor(normalizedServerSchema, normalizedOpenApiEndpointSchema, normalizedGraphQlEndpointSchema);
-function resolveConfigPath(path) {
-	return path ?? join(homedir(), ".caplets", "config.json");
-}
-function resolveProjectConfigPath(cwd = process.cwd()) {
-	return join(cwd, PROJECT_CONFIG_FILE);
-}
-function resolveCapletsRoot(configPath = resolveConfigPath()) {
-	return dirname(configPath);
-}
 function loadConfig(path = resolveConfigPath(), projectPath = resolveProjectConfigPath()) {
 	const hasUserConfig = existsSync(path);
 	const hasProjectConfig = existsSync(projectPath);
@@ -28221,9 +28220,6 @@ function loadConfig(path = resolveConfigPath(), projectPath = resolveProjectConf
 function shouldLoadProjectCaplets() {
 	return isTrustedEnvEnabled(process.env[TRUST_PROJECT_CAPLETS_ENV]);
 }
-function isTrustedEnvEnabled(value) {
-	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
-}
 function readPublicConfigInput(path) {
 	try {
 		const normalized = normalizeLocalPaths(JSON.parse(readFileSync(path, "utf8")), dirname(path));
@@ -28369,17 +28365,6 @@ function hasEnvReference(value) {
 function interpolateEnv(value) {
 	return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => process.env[name] ?? "").replace(/\$env:([A-Za-z_][A-Za-z0-9_]*)/g, (_match, name) => process.env[name] ?? "");
 }
-function isAllowedRemoteUrl(value) {
-	const url = new URL(value);
-	if (url.protocol === "https:") return true;
-	if (url.protocol !== "http:") return false;
-	return [
-		"localhost",
-		"127.0.0.1",
-		"[::1]",
-		"::1"
-	].includes(url.hostname);
-}
 //#endregion
 //#region node_modules/.pnpm/@modelcontextprotocol+sdk@1.29.0_zod@4.4.3/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/client.js
 /**
@@ -31574,14 +31559,22 @@ var SSEClientTransport = class {
 	}
 };
 //#endregion
-//#region src/auth.ts
+//#region src/auth/store.ts
 function authStorePath(server, authDir = join(homedir(), ".caplets", "auth")) {
-	return join(authDir, `${server}.json`);
+	if (!server || server.includes("/") || server.includes("\\") || server.includes("..")) throw new CapletsError("REQUEST_INVALID", `Invalid auth store server name ${server}`);
+	const authRoot = resolve(authDir);
+	const candidate = resolve(authRoot, `${server}.json`);
+	if (candidate !== authRoot && candidate.startsWith(`${authRoot}${sep}`)) return candidate;
+	throw new CapletsError("REQUEST_INVALID", `Invalid auth store server name ${server}`);
 }
 function readTokenBundle(server, authDir) {
 	const path = authStorePath(server, authDir);
 	if (!existsSync(path)) return;
-	return JSON.parse(readFileSync(path, "utf8"));
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
 }
 function deleteTokenBundle(server, authDir) {
 	const path = authStorePath(server, authDir);
@@ -31605,6 +31598,8 @@ function writeTokenBundle(bundle, authDir) {
 	} catch {}
 	renameSync(tempPath, path);
 }
+//#endregion
+//#region src/auth.ts
 function staticRemoteHeaders(server) {
 	if (server.auth?.type === "bearer") return { authorization: `Bearer ${server.auth.token}` };
 	if (server.auth?.type === "headers") return server.auth.headers;
@@ -31714,8 +31709,11 @@ var FileOAuthProvider = class {
 	}
 	addClientAuthentication = async (headers, params) => {
 		if (this.server.auth?.type !== "oauth2" && this.server.auth?.type !== "oidc") return;
-		if (this.server.auth.clientId) params.set("client_id", this.server.auth.clientId);
-		if (this.server.auth.clientSecret) params.set("client_secret", this.server.auth.clientSecret);
+		const clientInformation = this.clientInformation();
+		const clientId = clientInformation?.client_id;
+		const clientSecret = clientInformation?.client_secret;
+		if (clientId) params.set("client_id", clientId);
+		if (clientSecret) params.set("client_secret", clientSecret);
 		headers.set("content-type", "application/x-www-form-urlencoded");
 	};
 };
@@ -45575,7 +45573,7 @@ var require_utilities = /* @__PURE__ */ __commonJSMin(((exports) => {
 	var _resolveSchemaCoordinate = require_resolveSchemaCoordinate();
 }));
 //#endregion
-//#region src/graphql.ts
+//#region src/http/utils.ts
 var import_graphql = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	Object.defineProperty(exports, "__esModule", { value: true });
 	Object.defineProperty(exports, "BREAK", {
@@ -46877,7 +46875,40 @@ var import_graphql = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	var _index5 = require_error$1();
 	var _index6 = require_utilities();
 })))();
-const MAX_RESPONSE_BYTES$1 = 1024 * 1024;
+function parseHttpBody(contentType, text) {
+	if (!text) return;
+	const mime = contentType.split(";")[0]?.toLowerCase().trim() ?? "";
+	if (mime !== "application/json" && !mime.endsWith("+json") && !mime.endsWith("/json")) return text;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+async function readLimitedText(response, options) {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let bytes = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value) {
+			bytes += value.byteLength;
+			if (bytes > (options.maxBytes ?? 1048576)) {
+				await reader.cancel();
+				throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", options.errorMessage);
+			}
+			chunks.push(value);
+		}
+	}
+	return new TextDecoder().decode(Buffer.concat(chunks));
+}
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+//#endregion
+//#region src/graphql.ts
 const GRAPHQL_METHOD = "POST";
 const SCALAR_JSON_SCHEMA = {
 	String: { type: "string" },
@@ -46963,7 +46994,7 @@ var GraphQLManager = class {
 				challenge: response.headers.get("www-authenticate") ? "[REDACTED]" : void 0,
 				...endpoint.auth.type === "oauth2" || endpoint.auth.type === "oidc" ? { nextAction: "run_caplets_auth_login" } : {}
 			});
-			const body = parseGraphQlBody(response.headers.get("content-type") ?? "", await readLimitedText$1(response));
+			const body = parseHttpBody(response.headers.get("content-type") ?? "", await readGraphQlText(response));
 			const result = {
 				status: response.status,
 				statusText: response.statusText,
@@ -46979,7 +47010,7 @@ var GraphQLManager = class {
 				isError: !response.ok || Boolean(body && typeof body === "object" && "errors" in body && body.errors)
 			};
 		} catch (error) {
-			if (isAbortError$1(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", `GraphQL request timed out for ${endpoint.server}/${toolName}`);
+			if (isAbortError(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", `GraphQL request timed out for ${endpoint.server}/${toolName}`);
 			if (error instanceof CapletsError) throw error;
 			throw new CapletsError("DOWNSTREAM_TOOL_ERROR", `GraphQL request failed for ${endpoint.server}/${toolName}`, toSafeError(error));
 		} finally {
@@ -47055,7 +47086,7 @@ async function loadSchema(endpoint, authDir) {
 	}
 	const response = await postGraphQl(endpoint, endpoint.endpointUrl, { query: (0, import_graphql.getIntrospectionQuery)() }, authDir);
 	if (!response.ok) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "GraphQL introspection request failed", { status: response.status });
-	const parsed = JSON.parse(await readLimitedText$1(response));
+	const parsed = JSON.parse(await readGraphQlText(response));
 	if (parsed.errors || !parsed.data) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "GraphQL introspection returned errors");
 	return (0, import_graphql.buildClientSchema)(parsed.data);
 }
@@ -47237,7 +47268,7 @@ async function postGraphQl(endpoint, url, payload, authDir) {
 			body: JSON.stringify(payload)
 		});
 	} catch (error) {
-		if (isAbortError$1(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", "GraphQL request timed out");
+		if (isAbortError(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", "GraphQL request timed out");
 		throw error;
 	} finally {
 		clearTimeout(timeout);
@@ -47254,14 +47285,14 @@ async function fetchGraphQlText(endpoint, url, authDir, sendAuth = true) {
 			headers: { ...sendAuth ? schemaAuthHeaders(endpoint, authDir) : {} }
 		});
 	} catch (error) {
-		if (isAbortError$1(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", "GraphQL schema request timed out");
+		if (isAbortError(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", "GraphQL schema request timed out");
 		throw error;
 	} finally {
 		clearTimeout(timeout);
 	}
 	if (response.status >= 300 && response.status < 400) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "GraphQL schema request returned a redirect");
 	if (!response.ok) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "GraphQL schema request failed", { status: response.status });
-	return readLimitedText$1(response);
+	return readGraphQlText(response);
 }
 function schemaAuthHeaders(endpoint, authDir) {
 	return {
@@ -47283,48 +47314,13 @@ function staticHeaders(endpoint) {
 function shouldSendSchemaAuth(endpoint) {
 	return Boolean(endpoint.schemaUrl && new URL(endpoint.schemaUrl).origin === new URL(endpoint.endpointUrl).origin);
 }
-function parseGraphQlBody(contentType, text) {
-	if (!text) return;
-	if (!contentType.includes("application/json")) return text;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
-}
-async function readLimitedText$1(response) {
-	if (!response.body) return "";
-	const reader = response.body.getReader();
-	const chunks = [];
-	let bytes = 0;
-	while (true) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		if (value) {
-			bytes += value.byteLength;
-			if (bytes > MAX_RESPONSE_BYTES$1) {
-				await reader.cancel();
-				throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "GraphQL response exceeded byte limit");
-			}
-			chunks.push(value);
-		}
-	}
-	return new TextDecoder().decode(Buffer.concat(chunks));
+async function readGraphQlText(response) {
+	return readLimitedText(response, { errorMessage: "GraphQL response exceeded byte limit" });
 }
 function validateEndpointUrl(value) {
-	const url = new URL(value);
-	if (url.protocol === "https:") return;
-	if (url.protocol === "http:" && [
-		"localhost",
-		"127.0.0.1",
-		"[::1]",
-		"::1"
-	].includes(url.hostname)) return;
+	if (isAllowedRemoteUrl(value)) return;
 	throw new CapletsError("CONFIG_INVALID", "GraphQL URLs must use https except loopback development urls");
 }
-function isAbortError$1(error) {
-	return error instanceof DOMException && error.name === "AbortError";
-}
 function graphQlCacheKey(endpoint) {
 	return JSON.stringify({
 		endpointUrl: endpoint.endpointUrl,
@@ -56838,7 +56834,6 @@ const HTTP_METHODS = [
 	"trace"
 ];
 const JSON_CONTENT_TYPES = ["application/json"];
-const MAX_RESPONSE_BYTES = 1024 * 1024;
 const FORBIDDEN_ARGUMENT_HEADERS = new Set([
 	"accept",
 	"authorization",
@@ -57159,7 +57154,7 @@ function shouldSendSpecAuth(endpoint) {
 }
 async function readResponse(response) {
 	const contentType = response.headers.get("content-type") ?? "";
-	const body = parseResponseBody(contentType, await readLimitedText(response));
+	const body = parseHttpBody(contentType, await readLimitedText(response, { errorMessage: "OpenAPI response exceeded byte limit" }));
 	return {
 		status: response.status,
 		statusText: response.statusText,
@@ -57167,34 +57162,6 @@ async function readResponse(response) {
 		...body === void 0 ? {} : { body }
 	};
 }
-function parseResponseBody(contentType, text) {
-	if (!text) return;
-	if (!contentType.includes("application/json")) return text;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
-}
-async function readLimitedText(response) {
-	if (!response.body) return "";
-	const reader = response.body.getReader();
-	const chunks = [];
-	let bytes = 0;
-	while (true) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		if (value) {
-			bytes += value.byteLength;
-			if (bytes > MAX_RESPONSE_BYTES) {
-				await reader.cancel();
-				throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "OpenAPI response exceeded byte limit");
-			}
-			chunks.push(value);
-		}
-	}
-	return new TextDecoder().decode(Buffer.concat(chunks));
-}
 async function fetchWithLimit(url, timeoutMs, headers = {}) {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -57206,7 +57173,7 @@ async function fetchWithLimit(url, timeoutMs, headers = {}) {
 		});
 		if (response.status >= 300 && response.status < 400) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "OpenAPI spec request returned a redirect");
 		if (!response.ok) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "OpenAPI spec request failed", { status: response.status });
-		return await readLimitedText(response);
+		return await readLimitedText(response, { errorMessage: "OpenAPI response exceeded byte limit" });
 	} catch (error) {
 		if (isAbortError(error)) throw new CapletsError("TOOL_CALL_TIMEOUT", "OpenAPI spec request timed out");
 		throw error;
@@ -57217,7 +57184,7 @@ async function fetchWithLimit(url, timeoutMs, headers = {}) {
 function validateOperationBaseUrl(endpoint, base) {
 	if (!base) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} is missing OpenAPI baseUrl`);
 	if (endpoint.specUrl && !endpoint.baseUrl) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} must configure baseUrl when using remote specUrl`);
-	if (!isAllowedRequestBaseUrl(base)) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} OpenAPI baseUrl is not allowed`);
+	if (!isAllowedRemoteUrl(base)) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} OpenAPI baseUrl is not allowed`);
 	const url = new URL(base);
 	if (url.username || url.password || url.search || url.hash) throw new CapletsError("CONFIG_INVALID", `${endpoint.server} OpenAPI baseUrl must not include credentials, query, or fragment`);
 }
@@ -57227,20 +57194,6 @@ function buildOperationUrl(base, operationPath) {
 	baseUrl.pathname = [baseUrl.pathname.replace(/\/+$/, ""), operationPath.replace(/^\/+/, "")].filter(Boolean).join("/");
 	return baseUrl;
 }
-function isAbortError(error) {
-	return error instanceof DOMException && error.name === "AbortError";
-}
-function isAllowedRequestBaseUrl(value) {
-	const url = new URL(value);
-	if (url.protocol === "https:") return true;
-	if (url.protocol !== "http:") return false;
-	return [
-		"localhost",
-		"127.0.0.1",
-		"[::1]",
-		"::1"
-	].includes(url.hostname);
-}
 function openApiCacheKey(endpoint) {
 	return JSON.stringify({
 		specPath: endpoint.specPath,
@@ -60522,75 +60475,9 @@ const { program, createCommand, createArgument, createOption, CommanderError, In
 	exports.InvalidOptionArgumentError = InvalidArgumentError;
 })))(), 1)).default;
 //#endregion
-//#region src/cli.ts
-async function runCli(args, io = {}) {
-	const program = createProgram(io);
-	try {
-		await program.parseAsync([
-			"node",
-			"caplets",
-			...args
-		]);
-	} catch (error) {
-		if (error instanceof CommanderError) {
-			if (error.code === "commander.helpDisplayed" || error.code === "commander.version") return;
-			throw new CapletsError("REQUEST_INVALID", error.message);
-		}
-		throw error;
-	}
-}
-function createProgram(io = {}) {
-	const writeOut = io.writeOut ?? ((value) => process.stdout.write(value));
-	const writeErr = io.writeErr ?? ((value) => process.stderr.write(value));
-	const program = new Command();
-	program.name("caplets").description("Progressive-disclosure gateway for MCP servers.").exitOverride().configureOutput({
-		writeOut,
-		writeErr,
-		outputError: (value, write) => write(value)
-	});
-	program.command("init").description("Create a starter Caplets config file.").option("--force", "overwrite an existing config file").action((options) => {
-		const configPath = envConfigPath();
-		writeOut(`Created Caplets config at ${initConfig({
-			...configPath ? { path: configPath } : {},
-			force: Boolean(options.force)
-		})}\n`);
-	});
-	const auth = program.command("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) => {
-		await loginAuth(serverId, {
-			noOpen: options.open === false,
-			writeOut,
-			writeErr,
-			...io.authDir ? { authDir: io.authDir } : {}
-		});
-	});
-	auth.command("logout").description("Delete stored OAuth credentials for a server.").argument("<server>", "configured server ID").action((serverId) => {
-		assertLoginTarget(findAuthTarget(serverId), serverId);
-		if (deleteTokenBundle(serverId, io.authDir)) writeOut(`Deleted OAuth credentials for ${serverId}\n`);
-		else writeOut(`No OAuth credentials found for ${serverId}\n`);
-	});
-	auth.command("list").description("List servers with stored OAuth credentials.").action(() => {
-		const servers = authTargets(loadConfig(envConfigPath())).sort((left, right) => left.server.localeCompare(right.server));
-		if (servers.length === 0) {
-			writeOut("No configured remote OAuth servers found.\n");
-			return;
-		}
-		for (const server of servers) {
-			const bundle = readTokenBundle(server.server, io.authDir);
-			const status = !bundle ? "missing" : isTokenBundleExpired(bundle) ? "expired" : "authenticated";
-			writeOut([
-				server.server,
-				status,
-				bundle?.expiresAt ? `expires ${bundle.expiresAt}` : void 0,
-				bundle?.scope ? `scope ${bundle.scope}` : void 0
-			].filter(Boolean).join("	"));
-			writeOut("\n");
-		}
-	});
-	return program;
-}
+//#region src/cli/auth.ts
 async function loginAuth(serverId, options) {
-	const server = findAuthTarget(serverId, loadConfig(envConfigPath()));
+	const server = findAuthTarget(serverId, loadConfig(options.configPath));
 	assertLoginTarget(server, serverId);
 	try {
 		const flowOptions = {
@@ -60607,21 +60494,63 @@ async function loginAuth(serverId, options) {
 		process.exitCode = 1;
 	}
 }
-function findAuthTarget(serverId, config = loadConfig(envConfigPath())) {
+function logoutAuth(serverId, options) {
+	assertLoginTarget(findAuthTarget(serverId, loadConfig(options.configPath)), serverId);
+	if (deleteTokenBundle(serverId, options.authDir)) options.writeOut(`Deleted OAuth credentials for ${serverId}\n`);
+	else options.writeOut(`No OAuth credentials found for ${serverId}\n`);
+}
+function listAuth(options) {
+	const servers = authTargets(loadConfig(options.configPath)).sort((left, right) => left.server.localeCompare(right.server));
+	if (servers.length === 0) {
+		options.writeOut("No configured remote OAuth servers found.\n");
+		return;
+	}
+	for (const server of servers) {
+		const bundle = readTokenBundle(server.server, options.authDir);
+		const status = !bundle ? "missing" : isTokenBundleExpired(bundle) ? "expired" : "authenticated";
+		options.writeOut([
+			server.server,
+			status,
+			bundle?.expiresAt ? `expires ${bundle.expiresAt}` : void 0,
+			bundle?.scope ? `scope ${bundle.scope}` : void 0
+		].filter(Boolean).join("	"));
+		options.writeOut("\n");
+	}
+}
+function findAuthTarget(serverId, config = loadConfig()) {
 	return authTargets(config).find((server) => server.server === serverId);
 }
 function authTargets(config) {
-	const graphqlEndpoints = config.graphqlEndpoints;
 	return [
 		...Object.values(config.mcpServers).filter((server) => server.transport !== "stdio" && (server.auth?.type === "oauth2" || server.auth?.type === "oidc")),
 		...Object.values(config.openapiEndpoints).filter((endpoint) => endpoint.auth?.type === "oauth2" || endpoint.auth?.type === "oidc"),
-		...Object.values(graphqlEndpoints ?? {}).filter((endpoint) => endpoint.auth?.type === "oauth2" || endpoint.auth?.type === "oidc")
+		...Object.values(config.graphqlEndpoints).filter((endpoint) => endpoint.auth?.type === "oauth2" || endpoint.auth?.type === "oidc").map(graphQlAuthTarget)
 	];
 }
+function graphQlAuthTarget(endpoint) {
+	return {
+		...endpoint,
+		url: endpoint.endpointUrl
+	};
+}
 function assertLoginTarget(target, serverId) {
 	if (!target) throw new CapletsError("SERVER_NOT_FOUND", `Server ${serverId} is not configured for OAuth`);
 	if ("disabled" in target && target.disabled) throw new CapletsError("SERVER_UNAVAILABLE", `Server ${serverId} is disabled`);
 }
+async function maybeReadManualInput() {
+	if (!stdin.isTTY) return;
+	const rl = createInterface({
+		input: stdin,
+		output: stdout
+	});
+	try {
+		return (await rl.question("Paste callback URL or authorization code after completing authorization, or press Enter to wait for loopback callback: ")).trim() || void 0;
+	} finally {
+		rl.close();
+	}
+}
+//#endregion
+//#region src/cli/init.ts
 function initConfig(options = {}) {
 	const path = resolveConfigPath(options.path);
 	if (existsSync(path) && !options.force) throw new CapletsError("CONFIG_EXISTS", `Caplets config already exists at ${path}; pass --force to overwrite it`);
@@ -60653,21 +60582,306 @@ function starterConfig() {
 		} }
 	}, null, 2);
 }
-function envConfigPath() {
-	return process.env.CAPLETS_CONFIG?.trim() || void 0;
+//#endregion
+//#region src/cli/inspection.ts
+function listCaplets(config, options) {
+	return allCaplets(config).filter((server) => options.includeDisabled || !server.disabled).map((server) => ({
+		server: server.server,
+		backend: server.backend,
+		name: server.name,
+		description: server.description,
+		disabled: server.disabled,
+		status: initialServerStatus(server)
+	})).sort((left, right) => left.server.localeCompare(right.server));
 }
-async function maybeReadManualInput() {
-	if (!stdin.isTTY) return;
-	const rl = createInterface({
-		input: stdin,
-		output: stdout
-	});
+function initialServerStatus(server) {
+	return server.disabled ? "disabled" : "not_started";
+}
+function allCaplets(config) {
+	return [
+		...Object.values(config.mcpServers),
+		...Object.values(config.openapiEndpoints),
+		...Object.values(config.graphqlEndpoints)
+	];
+}
+function formatCapletList(rows) {
+	if (rows.length === 0) return "No configured Caplets found.\n";
+	return `${formatTable([[
+		"server",
+		"backend",
+		"status",
+		"name"
+	], ...rows.map((row) => [
+		row.server,
+		row.backend,
+		row.status,
+		row.name
+	])])}\n`;
+}
+function resolveCliConfigPaths(envConfigPath, authDir) {
+	const configPath = resolveConfigPath(envConfigPath);
+	return {
+		userConfig: configPath,
+		projectConfig: resolveProjectConfigPath(),
+		userRoot: resolveCapletsRoot(configPath),
+		projectRoot: resolveProjectCapletsRoot(),
+		authDir: authDir ?? DEFAULT_AUTH_DIR,
+		envConfig: envConfigPath ?? null,
+		projectCapletsTrusted: isTrustedProjectCapletsEnabled()
+	};
+}
+function formatConfigPaths(paths) {
+	return [
+		`userConfig: ${paths.userConfig}`,
+		`projectConfig: ${paths.projectConfig}`,
+		`userRoot: ${paths.userRoot}`,
+		`projectRoot: ${paths.projectRoot}`,
+		`authDir: ${paths.authDir}`,
+		`envConfig: ${paths.envConfig ?? "unset"}`,
+		`projectCapletsTrusted: ${paths.projectCapletsTrusted}`
+	].join("\n") + "\n";
+}
+function isTrustedProjectCapletsEnabled() {
+	return isTrustedEnvEnabled(process.env[TRUST_PROJECT_CAPLETS_ENV]);
+}
+function formatTable(rows) {
+	const firstRow = rows[0];
+	if (!firstRow) return "";
+	const widths = firstRow.map((_, column) => Math.max(...rows.map((row) => row[column]?.length ?? 0)));
+	return rows.map((row) => formatTableRow(row, widths)).join("\n");
+}
+function formatTableRow(row, widths) {
+	return row.map((value, column) => {
+		if (column === row.length - 1) return value;
+		return value.padEnd((widths[column] ?? 0) + 2);
+	}).join("").trimEnd();
+}
+//#endregion
+//#region src/cli/install.ts
+function installCaplets(repo, options = {}) {
+	const source = resolveInstallSource(repo);
 	try {
-		return (await rl.question("Paste callback URL or authorization code after completing authorization, or press Enter to wait for loopback callback: ")).trim() || void 0;
+		const sourceRoot = join(source.repoRoot, "caplets");
+		if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) throw new CapletsError("CONFIG_NOT_FOUND", `No caplets directory found at ${sourceRoot}`);
+		const selectedIds = new Set(options.capletIds ?? []);
+		const destinationRoot = options.destinationRoot ?? resolveCapletsRoot(resolveConfigPath());
+		const available = selectedIds.size === 0 ? discoverCapletFiles(sourceRoot) : discoverSelectedCapletFiles(sourceRoot, selectedIds);
+		const selected = available.filter((caplet) => selectedIds.size === 0 || selectedIds.has(caplet.id));
+		const missing = [...selectedIds].filter((id) => !available.some((caplet) => caplet.id === id));
+		if (missing.length > 0) throw new CapletsError("CONFIG_NOT_FOUND", `Caplet ${missing.join(", ")} not found in ${sourceRoot}`);
+		if (selected.length === 0) throw new CapletsError("CONFIG_NOT_FOUND", `No Caplets found in ${sourceRoot}`);
+		for (const caplet of selected) validateCapletFile(caplet.path);
+		return { installed: preflightInstallCaplets(selected, {
+			destinationRoot,
+			force: Boolean(options.force),
+			repoRoot: source.repoRoot,
+			sourceId: source.id
+		}).map((plan) => installOneCaplet(plan, { force: Boolean(options.force) })) };
 	} finally {
-		rl.close();
+		source.cleanup();
+	}
+}
+function discoverSelectedCapletFiles(sourceRoot, selectedIds) {
+	const candidates = [];
+	for (const id of selectedIds) {
+		if (!SERVER_ID_PATTERN.test(id)) continue;
+		const filePath = join(sourceRoot, `${id}.md`);
+		if (existsSync(filePath) && statSync(filePath).isFile()) candidates.push({
+			id,
+			path: filePath
+		});
+		const directoryPath = join(sourceRoot, id, "CAPLET.md");
+		if (existsSync(directoryPath) && statSync(directoryPath).isFile()) candidates.push({
+			id,
+			path: directoryPath
+		});
+	}
+	return candidates.sort((left, right) => left.id.localeCompare(right.id));
+}
+function resolveInstallSource(repo) {
+	if (existsSync(repo) && statSync(repo).isDirectory()) return {
+		id: repo,
+		repoRoot: repo,
+		cleanup: () => {}
+	};
+	const normalizedRepo = normalizeGitRepo(repo);
+	const repoRoot = mkdtempSync(join(tmpdir(), "caplets-install-"));
+	try {
+		execFileSync("git", [
+			"clone",
+			"--depth",
+			"1",
+			"--",
+			normalizedRepo,
+			repoRoot
+		], {
+			stdio: "ignore",
+			timeout: 6e4
+		});
+		return {
+			id: normalizedRepo,
+			repoRoot,
+			cleanup: () => rmSync(repoRoot, {
+				recursive: true,
+				force: true
+			})
+		};
+	} catch (error) {
+		rmSync(repoRoot, {
+			recursive: true,
+			force: true
+		});
+		throw new CapletsError("CONFIG_NOT_FOUND", `Could not clone repo ${repo}`, toSafeError(error));
+	}
+}
+function normalizeGitRepo(repo) {
+	if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) return `https://github.com/${repo.endsWith(".git") ? repo.slice(0, -4) : repo}.git`;
+	return repo;
+}
+function preflightInstallCaplets(caplets, options) {
+	const plans = caplets.map((caplet) => installPlan(caplet, options));
+	for (const plan of plans) if (existsSync(plan.destination) && !options.force) throw new CapletsError("CONFIG_EXISTS", `Caplet ${plan.id} already exists at ${plan.destination}; pass --force to overwrite it`);
+	accessSync(nearestExistingParent(options.destinationRoot), constants.W_OK);
+	for (const plan of plans) accessSync(existsSync(plan.destination) ? dirname(plan.destination) : nearestExistingParent(dirname(plan.destination)), constants.W_OK);
+	mkdirSync(options.destinationRoot, {
+		recursive: true,
+		mode: 448
+	});
+	return plans;
+}
+function installPlan(caplet, options) {
+	const isDirectory = basename(caplet.path) === "CAPLET.md";
+	const sourcePath = isDirectory ? dirname(caplet.path) : caplet.path;
+	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,
+		destination,
+		kind: isDirectory ? "directory" : "file"
+	};
+}
+function installOneCaplet(plan, options) {
+	if (existsSync(plan.destination)) {
+		if (!options.force) throw new CapletsError("CONFIG_EXISTS", `Caplet ${plan.id} already exists at ${plan.destination}; pass --force to overwrite it`);
+		rmSync(plan.destination, {
+			recursive: true,
+			force: true
+		});
+	}
+	cpSync(plan.sourcePath, plan.destination, {
+		recursive: plan.kind === "directory",
+		force: false,
+		errorOnExist: true
+	});
+	return {
+		id: plan.id,
+		source: plan.source,
+		destination: plan.destination,
+		kind: plan.kind
+	};
+}
+function nearestExistingParent(path) {
+	if (existsSync(path)) return path;
+	const parent = dirname(path);
+	if (parent === path) return parent;
+	return nearestExistingParent(parent);
+}
+//#endregion
+//#region src/cli.ts
+async function runCli(args, io = {}) {
+	const program = createProgram(io);
+	try {
+		await program.parseAsync([
+			"node",
+			"caplets",
+			...args
+		]);
+	} catch (error) {
+		if (error instanceof CommanderError) {
+			if (error.code === "commander.helpDisplayed" || error.code === "commander.version") return;
+			throw new CapletsError("REQUEST_INVALID", error.message);
+		}
+		throw error;
 	}
 }
+function createProgram(io = {}) {
+	const writeOut = io.writeOut ?? ((value) => process.stdout.write(value));
+	const writeErr = io.writeErr ?? ((value) => process.stderr.write(value));
+	const program = new Command();
+	program.name("caplets").description("Progressive-disclosure gateway for MCP servers.").version(version).exitOverride().configureOutput({
+		writeOut,
+		writeErr,
+		outputError: (value, write) => write(value)
+	});
+	program.command("init").description("Create a starter Caplets config file.").option("--force", "overwrite an existing config file").action((options) => {
+		const configPath = envConfigPath();
+		writeOut(`Created Caplets config at ${initConfig({
+			...configPath ? { path: configPath } : {},
+			force: Boolean(options.force)
+		})}\n`);
+	});
+	program.command("list").description("List configured Caplets.").option("--all", "include disabled Caplets").option("--json", "print JSON output").action((options) => {
+		const rows = listCaplets(loadConfig(envConfigPath()), { includeDisabled: Boolean(options.all) });
+		if (options.json) {
+			writeOut(`${JSON.stringify(rows, null, 2)}\n`);
+			return;
+		}
+		writeOut(formatCapletList(rows));
+	});
+	program.command("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("--force", "overwrite installed Caplets").action((repo, capletIds, options) => {
+		const result = installCaplets(repo, {
+			capletIds,
+			force: Boolean(options.force),
+			destinationRoot: resolveCapletsRoot(resolveConfigPath(envConfigPath()))
+		});
+		for (const caplet of result.installed) writeOut(`Installed ${caplet.id} to ${caplet.destination}\n`);
+	});
+	const config = program.command("config").description("Inspect Caplets config locations.");
+	config.command("path").description("Print the effective user config path.").action(() => {
+		writeOut(`${resolveConfigPath(envConfigPath())}\n`);
+	});
+	config.command("paths").description("Print resolved Caplets config, root, and auth paths.").option("--json", "print JSON output").action((options) => {
+		const paths = resolveCliConfigPaths(envConfigPath(), io.authDir);
+		if (options.json) {
+			writeOut(`${JSON.stringify(paths, null, 2)}\n`);
+			return;
+		}
+		writeOut(formatConfigPaths(paths));
+	});
+	const auth = program.command("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 configPath = envConfigPath();
+		await loginAuth(serverId, {
+			noOpen: options.open === false,
+			writeOut,
+			writeErr,
+			...configPath ? { configPath } : {},
+			...io.authDir ? { authDir: io.authDir } : {}
+		});
+	});
+	auth.command("logout").description("Delete stored OAuth credentials for a server.").argument("<server>", "configured server ID").action((serverId) => {
+		const configPath = envConfigPath();
+		logoutAuth(serverId, {
+			writeOut,
+			...configPath ? { configPath } : {},
+			...io.authDir ? { authDir: io.authDir } : {}
+		});
+	});
+	auth.command("list").description("List servers with stored OAuth credentials.").action(() => {
+		const configPath = envConfigPath();
+		listAuth({
+			writeOut,
+			...configPath ? { configPath } : {},
+			...io.authDir ? { authDir: io.authDir } : {}
+		});
+	});
+	return program;
+}
+function envConfigPath() {
+	return process.env.CAPLETS_CONFIG?.trim() || void 0;
+}
 //#endregion
 //#region src/index.ts
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caplets",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Progressive disclosure gateway for MCP servers.",
   "keywords": [
     "caplets",
@@ -24,6 +24,7 @@
   },
   "files": [
     "dist",
+    "caplets",
     "schemas",
     "README.md",
     "LICENSE"