baller-maester 0.3.0 → 0.4.0

package/dist/index.js

@@ -8,12 +8,384 @@ import { promisify } from 'util';
 import { simpleGit } from 'simple-git';
 import picomatch from 'picomatch';
 import matter from 'gray-matter';
+import TOML from '@iarna/toml';
+import { zodToJsonSchema } from 'zod-to-json-schema';
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
+
+// src/core/connectors/types.ts
+var ENVELOPE_SCHEMA_VERSION = 1;
+var CONNECTOR_ERROR_CODES = [
+  "missing-env-var",
+  "connector-not-found",
+  "unknown-operation",
+  "invalid-argument",
+  "auth-failed",
+  "remote-error",
+  "internal-error"
+];
+function defineConnectorOperation(opts) {
+  return opts;
+}
+
+// src/core/connectors/errors.ts
+var ConnectorError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "ConnectorError";
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/core/connectors/types/gitlab-issues/errors.ts
+function mapGitLabHttpError(input) {
+  const { status, body, headers, host, envVarName, context } = input;
+  if (status === 401 || status === 403) {
+    return new ConnectorError(
+      "auth-failed",
+      envVarName ? `GitLab rejected the token from ${envVarName} (HTTP ${status}) on ${host}.` : `GitLab returned HTTP ${status} on ${host}.`,
+      {
+        status,
+        ...envVarName ? { envVar: envVarName } : {},
+        host
+      }
+    );
+  }
+  if (status === 404) {
+    const message = context.iid !== void 0 ? `Issue ${context.iid} not found in project '${context.project}' on ${host}.` : `Project '${context.project}' not found on ${host}.`;
+    return new ConnectorError("remote-error", message, {
+      kind: "not-found",
+      status,
+      project: context.project,
+      ...context.iid !== void 0 ? { iid: context.iid } : {}
+    });
+  }
+  if (status === 429) {
+    const retryAfter = headers.get("retry-after");
+    return new ConnectorError(
+      "remote-error",
+      `GitLab rate-limited the request (HTTP 429) on ${host}.${retryAfter ? ` Retry after ${retryAfter}s.` : ""}`,
+      {
+        kind: "rate-limited",
+        status,
+        ...retryAfter ? { retryAfter } : {}
+      }
+    );
+  }
+  if (status >= 500 && status <= 599) {
+    return new ConnectorError("remote-error", `GitLab returned HTTP ${status} on ${host}.`, {
+      kind: "transport",
+      status
+    });
+  }
+  return new ConnectorError("remote-error", `Unexpected HTTP ${status} from GitLab on ${host}.`, {
+    kind: "unexpected",
+    status,
+    body: truncateBody(body)
+  });
+}
+function mapTransportError(err, host) {
+  const message = err instanceof Error ? err.message : String(err);
+  return new ConnectorError("remote-error", `Failed to reach GitLab at ${host}: ${message}`, {
+    kind: "transport",
+    cause: message
+  });
+}
+var BODY_EXCERPT_MAX = 1024;
+function truncateBody(body) {
+  if (body.length <= BODY_EXCERPT_MAX) return body;
+  return `${body.slice(0, BODY_EXCERPT_MAX)}\u2026`;
+}
+
+// src/core/connectors/types/gitlab-issues/output.ts
+var GITLAB_ISSUES_DATA_SCHEMA = 1;
+function projectIssue(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("Expected GitLab issue payload to be a JSON object.");
+  }
+  const r = raw;
+  return {
+    iid: requireNumber(r.iid, "iid"),
+    id: requireNumber(r.id, "id"),
+    title: requireString(r.title, "title"),
+    description: optionalString(r.description),
+    state: requireString(r.state, "state"),
+    labels: projectLabels(r.labels),
+    assignees: projectAssignees(r.assignees),
+    milestone: projectMilestone(r.milestone),
+    web_url: requireString(r.web_url, "web_url"),
+    created_at: requireString(r.created_at, "created_at"),
+    updated_at: requireString(r.updated_at, "updated_at"),
+    closed_at: optionalString(r.closed_at)
+  };
+}
+function requireNumber(value, field) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Expected GitLab issue field '${field}' to be a number.`);
+  }
+  return value;
+}
+function requireString(value, field) {
+  if (typeof value !== "string") {
+    throw new Error(`Expected GitLab issue field '${field}' to be a string.`);
+  }
+  return value;
+}
+function optionalString(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value !== "string") return null;
+  return value;
+}
+function projectLabels(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string").map((v) => v);
+}
+function projectAssignees(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const r = entry;
+    const username = typeof r.username === "string" ? r.username : null;
+    const name = typeof r.name === "string" ? r.name : null;
+    if (username === null || name === null) continue;
+    out.push({ username, name });
+  }
+  return out;
+}
+function projectMilestone(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const r = value;
+  const title = typeof r.title === "string" ? r.title : null;
+  const state = typeof r.state === "string" ? r.state : null;
+  if (title === null || state === null) return null;
+  return { title, state };
+}
+
+// src/core/connectors/types/gitlab-issues/client.ts
+var NUMERIC_ID_RE = /^\d+$/;
+async function listIssues(opts, params) {
+  const url = buildIssuesListUrl(opts, params);
+  const response = await performRequest(opts, url);
+  const issuesRaw = await response.json();
+  if (!Array.isArray(issuesRaw)) {
+    throw new ConnectorError("remote-error", "GitLab list-issues response was not a JSON array.", {
+      kind: "unexpected"
+    });
+  }
+  const issues = issuesRaw.map((raw) => projectIssue(raw));
+  return {
+    issues,
+    totalPages: readIntegerHeader(response.headers, "x-total-pages"),
+    total: readIntegerHeader(response.headers, "x-total")
+  };
+}
+async function getIssue(opts, iid) {
+  const url = buildIssueUrl(opts, iid);
+  const response = await performRequest(opts, url, { iid });
+  const raw = await response.json();
+  return projectIssue(raw);
+}
+function buildIssuesListUrl(opts, params) {
+  const url = new URL(`${opts.host}/api/v4/projects/${encodeProjectSegment(opts.project)}/issues`);
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("page", String(params.page));
+  url.searchParams.set("per_page", String(params.per_page));
+  if (params.labels !== void 0) url.searchParams.set("labels", params.labels);
+  if (params.assignee !== void 0) {
+    const param = gitlabAssigneeParam(params.assignee);
+    url.searchParams.set(param.key, param.value);
+  }
+  if (params.milestone !== void 0) url.searchParams.set("milestone", params.milestone);
+  if (params.search !== void 0) url.searchParams.set("search", params.search);
+  return url;
+}
+function buildIssueUrl(opts, iid) {
+  return new URL(
+    `${opts.host}/api/v4/projects/${encodeProjectSegment(opts.project)}/issues/${iid}`
+  );
+}
+function encodeProjectSegment(project) {
+  if (NUMERIC_ID_RE.test(project)) return project;
+  return encodeURIComponent(project);
+}
+async function performRequest(opts, url, context = {}) {
+  const headers = {
+    Accept: "application/json"
+  };
+  if (opts.token !== void 0) {
+    headers["PRIVATE-TOKEN"] = opts.token;
+  }
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  let response;
+  try {
+    response = await fetchImpl(url, { method: "GET", headers });
+  } catch (err) {
+    throw mapTransportError(err, opts.host);
+  }
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw mapGitLabHttpError({
+      status: response.status,
+      body,
+      headers: response.headers,
+      host: opts.host,
+      envVarName: opts.envVarName,
+      context: {
+        project: opts.project,
+        ...context.iid !== void 0 ? { iid: context.iid } : {}
+      }
+    });
+  }
+  return response;
+}
+function readIntegerHeader(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null || raw.length === 0) return null;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function gitlabAssigneeParam(value) {
+  return { key: "assignee_username", value };
+}
+
+// src/core/connectors/types/gitlab-issues/operations.ts
+var PER_PAGE_CAP = 100;
+var listIssuesArgsSchema = z.object({
+  state: z.enum(["opened", "closed", "all"]).default("opened"),
+  labels: z.string().min(1).optional(),
+  assignee: z.string().min(1).optional(),
+  milestone: z.string().min(1).optional(),
+  search: z.string().min(1).optional(),
+  page: z.coerce.number().int().positive("page must be a positive integer").default(1),
+  per_page: z.coerce.number().int().positive("per_page must be a positive integer").default(20)
+}).strict();
+var getIssueArgsSchema = z.object({
+  iid: z.coerce.number().int().positive("iid must be a positive integer")
+}).strict();
+var listIssuesOperation = defineConnectorOperation({
+  name: "list-issues",
+  argsSchema: listIssuesArgsSchema,
+  dataSchemaVersion: GITLAB_ISSUES_DATA_SCHEMA,
+  handler: async (args, ctx) => {
+    const requestedPerPage = args.per_page;
+    const clamped = requestedPerPage > PER_PAGE_CAP;
+    const effectivePerPage = clamped ? PER_PAGE_CAP : requestedPerPage;
+    const params = {
+      state: args.state,
+      page: args.page,
+      per_page: effectivePerPage,
+      ...args.labels !== void 0 ? { labels: args.labels } : {},
+      ...args.assignee !== void 0 ? { assignee: args.assignee } : {},
+      ...args.milestone !== void 0 ? { milestone: args.milestone } : {},
+      ...args.search !== void 0 ? { search: args.search } : {}
+    };
+    const client = clientFromContext(ctx);
+    const response = await listIssues(client, params);
+    return {
+      data: {
+        issues: response.issues,
+        meta: {
+          page: args.page,
+          per_page: effectivePerPage,
+          total_pages: response.totalPages,
+          total: response.total,
+          clamped
+        }
+      }
+    };
+  }
+});
+var getIssueOperation = defineConnectorOperation({
+  name: "get-issue",
+  argsSchema: getIssueArgsSchema,
+  dataSchemaVersion: GITLAB_ISSUES_DATA_SCHEMA,
+  handler: async (args, ctx) => {
+    const client = clientFromContext(ctx);
+    const issue = await getIssue(client, args.iid);
+    return { data: { issue } };
+  }
+});
+function clientFromContext(ctx) {
+  return {
+    host: ctx.config.host,
+    project: ctx.config.project,
+    token: ctx.token,
+    envVarName: ctx.auth.type === "token" ? ctx.auth.envVar : void 0
+  };
+}
+var DEFAULT_HOST = "https://gitlab.com";
+function isHttpsUrl(value) {
+  if (/\s/.test(value)) return false;
+  if (!/^https:\/\/[^/]+/i.test(value)) return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function normalizeHost(value) {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+var GitLabIssuesConfigSchema = z.object({
+  host: z.string().refine(isHttpsUrl, "host must be an HTTPS URL (e.g. https://gitlab.com)").transform(normalizeHost).optional().default(DEFAULT_HOST),
+  project: z.string().min(1, "project is required").refine((v) => !/\s/.test(v), "project must not contain whitespace"),
+  apiVersion: z.literal(4).optional().default(4)
+}).strict();
+
+// src/core/connectors/types/gitlab-issues/index.ts
+var GITLAB_ISSUES_TYPE_ID = "gitlab-issues";
+var gitlabIssuesType = {
+  id: GITLAB_ISSUES_TYPE_ID,
+  label: "GitLab Issues",
+  configSchema: GitLabIssuesConfigSchema,
+  operations: {
+    [listIssuesOperation.name]: listIssuesOperation,
+    [getIssueOperation.name]: getIssueOperation
+  },
+  describeTool: (operation, resolvedConfig) => {
+    const host = stripScheme(resolvedConfig.host);
+    const project = resolvedConfig.project;
+    switch (operation.name) {
+      case "list-issues":
+        return `List GitLab issues for project ${project} on ${host}. Supports filtering by state (opened/closed/all), labels, assignee, milestone, free-text search, and page/per_page pagination. Returns at most 100 issues per call.`;
+      case "get-issue":
+        return `Fetch a single GitLab issue from project ${project} on ${host} by its project-scoped iid. Returns the issue's title, description, state, labels, assignees, milestone, timestamps, and web_url.`;
+      default:
+        return `GitLab Issues operation '${operation.name}' for project ${project} on ${host}.`;
+    }
+  }
+};
+function stripScheme(host) {
+  return host.replace(/^https?:\/\//i, "");
+}
+
+// src/core/connectors/registry.ts
+var REGISTRY = /* @__PURE__ */ new Map();
+REGISTRY.set(gitlabIssuesType.id, gitlabIssuesType);
+function listConnectorTypes() {
+  return [...REGISTRY.values()];
+}
+function lookupConnectorType(id) {
+  return REGISTRY.get(id);
+}
+function hasConnectorType(id) {
+  return REGISTRY.has(id);
+}
+function registerConnectorType(type) {
+  if (REGISTRY.has(type.id)) {
+    throw new Error(`Connector type '${type.id}' is already registered.`);
+  }
+  REGISTRY.set(type.id, type);
+}
 var STATE_VALUES = ["draft", "canon"];
 var StateSchema = z.enum(STATE_VALUES);
 var DEFAULT_STATE = "draft";
@@ -78,6 +450,13 @@ var SourceSchema = z.object({
   description: z.string().min(1).optional(),
   tags: z.array(z.string().min(1).regex(SLUG_RE, "tags must be slugs")).optional()
 }).strict();
+var ConnectorBaseSchema = z.object({
+  name: z.string().min(1).regex(SLUG_RE, "name must be a kebab-case slug starting with a letter or digit"),
+  type: z.string().min(1),
+  auth: AuthRefSchema.optional(),
+  description: z.string().min(1).optional(),
+  config: z.unknown().optional()
+}).strict();
 var DEFAULT_BASE_DIR = "citadel";
 function applyCombinedInvariants(data, ctx) {
   if (data.sources.length === 0) {
@@ -116,11 +495,46 @@ function applyCombinedInvariants(data, ctx) {
       destsSeen.set(resolved, { index: i, name: entry.name });
     }
   }
+  const connectorNames = /* @__PURE__ */ new Map();
+  const connectors = data.connectors ?? [];
+  for (let i = 0; i < connectors.length; i++) {
+    const entry = connectors[i];
+    if (!entry?.name) continue;
+    const priorIndex = connectorNames.get(entry.name);
+    if (priorIndex !== void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `duplicate connector name '${entry.name}' \u2014 also used by connectors[${priorIndex}]`,
+        path: ["connectors", i, "name"]
+      });
+    } else {
+      connectorNames.set(entry.name, i);
+    }
+    const type = lookupConnectorType(entry.type);
+    if (!type) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `unknown connector type '${entry.type}' for connector '${entry.name}'`,
+        path: ["connectors", i, "type"]
+      });
+      continue;
+    }
+    const configResult = type.configSchema.safeParse(entry.config ?? {});
+    if (!configResult.success) {
+      for (const issue of configResult.error.issues) {
+        ctx.addIssue({
+          ...issue,
+          path: ["connectors", i, "config", ...issue.path]
+        });
+      }
+    }
+  }
 }
 var CitadelConfigSchema = z.object({
   schemaVersion: z.literal(1),
   baseDir: z.string().min(1).refine(isSafeRelativePath, "baseDir must be a repo-relative path with no '..' segments").optional(),
-  sources: z.array(SourceSchema).optional().default([])
+  sources: z.array(SourceSchema).optional().default([]),
+  connectors: z.array(ConnectorBaseSchema).optional()
 }).strict().superRefine((data, ctx) => {
   applyCombinedInvariants(data, ctx);
 });
@@ -235,26 +649,26 @@ function defaultDestinationFor(repoRoot, sourceName, baseDir) {
 
 // src/core/config/loader.ts
 async function loadCitadelConfig(repoRoot) {
-  const path4 = citadelConfigPath(repoRoot);
-  if (!existsSync(path4)) {
+  const path8 = citadelConfigPath(repoRoot);
+  if (!existsSync(path8)) {
     throw new ConfigError(
       "No citadel.yaml found at the repository root. Run `npx maester init` to create one.",
-      { filePath: path4 }
+      { filePath: path8 }
     );
   }
-  const raw = await readFile(path4, "utf8");
-  return parseAndValidate(raw, CitadelConfigSchema, path4);
+  const raw = await readFile(path8, "utf8");
+  return parseAndValidate(raw, CitadelConfigSchema, path8);
 }
 async function loadMaesterConfig(repoRoot) {
-  const path4 = maesterConfigPath(repoRoot);
-  if (!existsSync(path4)) {
+  const path8 = maesterConfigPath(repoRoot);
+  if (!existsSync(path8)) {
     throw new ConfigError(
       "No maester.yaml found at the repository root. Run `npx maester publish` to create one.",
-      { filePath: path4 }
+      { filePath: path8 }
     );
   }
-  const raw = await readFile(path4, "utf8");
-  return parseAndValidate(raw, MaesterConfigSchema, path4);
+  const raw = await readFile(path8, "utf8");
+  return parseAndValidate(raw, MaesterConfigSchema, path8);
 }
 function parseAndValidate(raw, schema, filePath) {
   const data = parseYaml(raw, filePath);
@@ -312,7 +726,7 @@ function resolveAuth(auth, env = process.env) {
       `${auth.envVar} is not set. Define it in your shell, .env loader, or CI secret manager before syncing.`
     );
   }
-  return { type: "token", value };
+  return { type: "token", value, envVar: auth.envVar };
 }
 var execFile = promisify(execFile$1);
 var cachedCapabilities;
@@ -545,10 +959,10 @@ function manifestError(name, reason) {
   );
 }
 async function discoverManifestFromCache(cacheDir) {
-  const path4 = resolve(cacheDir, MAESTER_MANIFEST_FILENAME);
-  if (!existsSync(path4)) return { mode: "no-manifest", reason: "absent" };
+  const path8 = resolve(cacheDir, MAESTER_MANIFEST_FILENAME);
+  if (!existsSync(path8)) return { mode: "no-manifest", reason: "absent" };
   try {
-    const raw = await readFile(path4, "utf8");
+    const raw = await readFile(path8, "utf8");
     const doc = parseDocument(raw);
     if (doc.errors.length > 0) return { mode: "no-manifest", reason: "invalid" };
     const parsed = MaesterConfigSchema.safeParse(doc.toJS({ maxAliasCount: -1 }));
@@ -885,17 +1299,17 @@ async function applyState(stagedDir, rules) {
 }
 var PROVENANCE_FILENAME = ".maester-source.json";
 async function writeProvenanceMarker(destination, marker) {
-  const path4 = resolve(destination, PROVENANCE_FILENAME);
+  const path8 = resolve(destination, PROVENANCE_FILENAME);
   const body = `${JSON.stringify(marker, null, 2)}
 `;
-  await writeFile(path4, body, "utf8");
-  return path4;
+  await writeFile(path8, body, "utf8");
+  return path8;
 }
 async function readProvenanceMarker(destination) {
-  const path4 = resolve(destination, PROVENANCE_FILENAME);
-  if (!existsSync(path4)) return void 0;
+  const path8 = resolve(destination, PROVENANCE_FILENAME);
+  if (!existsSync(path8)) return void 0;
   try {
-    const text = await readFile(path4, "utf8");
+    const text = await readFile(path8, "utf8");
     const parsed = JSON.parse(text);
     if (typeof parsed.sourceName !== "string" || typeof parsed.sourceUrl !== "string" || typeof parsed.commitSha !== "string" || !Array.isArray(parsed.filterSet)) {
       return void 0;
@@ -1301,7 +1715,7 @@ function renderManagedRegion(body, version) {
 ${inner}
 ${END_MARKER_LITERAL}`;
 }
-function replaceJsonMaesterKey(existingText, maesterBlock) {
+function replaceJsonMaesterKey(existingText, maesterBlock2) {
   const parsed = existingText && existingText.trim().length > 0 ? JSON.parse(existingText) : {};
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new Error("Expected .claude/settings.json to be a JSON object at the top level.");
@@ -1310,14 +1724,14 @@ function replaceJsonMaesterKey(existingText, maesterBlock) {
   let placed = false;
   for (const [key, value] of Object.entries(parsed)) {
     if (key === "maester") {
-      rebuilt[key] = maesterBlock;
+      rebuilt[key] = maesterBlock2;
       placed = true;
     } else {
       rebuilt[key] = value;
     }
   }
   if (!placed) {
-    rebuilt.maester = maesterBlock;
+    rebuilt.maester = maesterBlock2;
   }
   return `${JSON.stringify(rebuilt, null, 2)}
 `;
@@ -1339,6 +1753,9 @@ function readJsonMaesterKey(existingText) {
 // src/core/skill/templates/content/citadel-awareness.md
 var citadel_awareness_default = '## Citadel awareness\n\nThis repository is a **citadel** \u2014 it pulls curated documentation from multiple\nremote sources into a single tree, managed by the `maester` CLI.\n\n- The citadel\'s aggregated content lives under `{{baseDir}}/` at the repository\n  root. Each direct subdirectory of `{{baseDir}}/` corresponds to one remote\n  source declared in `citadel.yaml` (`{{baseDir}}/<source-name>/...`).\n- The configuration that declares those sources is in `citadel.yaml` at the\n  repository root. It names each source, the git remote it pulls from, and the\n  ref it pins to.\n- When answering questions about anything the citadel covers, prefer citing\n  files under `{{baseDir}}/` over external knowledge. Cite the file path\n  relative to the repository root so the user can open it.\n- Each materialized file may carry a `state` value in its frontmatter or\n  inline (see "State awareness" below). Surface that state alongside any\n  citation so the user knows whether the source is canonical or draft.\n';
 
+// src/core/skill/templates/content/connector-policy.md
+var connector_policy_default = "## Connector tools (traveling maesters)\n\nThis citadel may expose one or more **traveling maesters** as MCP tools whose\nnames begin with the connector slug (e.g. `team_gl__list_issues`).\n\n- Their output is **live, point-in-time data** from an external service. Cite\n  specific identifiers (issue iids, ticket numbers) when surfacing it, do not\n  treat it as a stable corpus, and flag the **freshness verdict** in your\n  answer when it is not `up-to-date`.\n- The tools' arguments and return shapes are described in MCP `tools/list`;\n  do not assume undocumented fields.\n- Connector tool results are JSON envelopes carrying a `dataSchema` version\n  alongside the payload \u2014 if your reading of the data depends on a specific\n  shape, branch on `dataSchema`.\n";
+
 // src/core/skill/templates/content/freshness-awareness.md
 var freshness_awareness_default = '## Freshness awareness\n\nCitadel content can drift out of date when remote sources advance after the\nlast sync. The Grand Maester is **auto-sync directed**: when the citadel is\nbehind, refresh it before reading rather than relying on stale content.\n\n**Auto-sync policy**\n\nWhen you discover that the citadel is behind \u2014 either from the Claude Code\npre-read hook\'s `additionalContext` message, or from a manual run of\n`npx maester status` \u2014 follow these steps without prompting the user:\n\n1. Run `npx maester sync` to refresh every configured source.\n   - Exits 0 on success.\n   - Exits non-zero if any source failed (missing auth env var, ref typo,\n     network error). Report the failure to the user and proceed cautiously.\n2. **Invalidate the pre-read hook\'s debounce cache** so the next read\n   observes fresh state instead of the stale verdict captured before the\n   sync:\n   ```\n   rm -f .maester/.skill-cache.json\n   ```\n3. Proceed with the original read of the citadel file.\n\nYou do not need to ask the user before syncing. `maester sync` is read-only\nagainst the remote sources it pulls from; it only materializes content the\n`citadel.yaml` already declared. The same sync the user would run manually.\n\n**Don\'t loop on failures.** If `maester sync` fails (or the hook reports a\n`failed` verdict from `maester status`), do **not** retry sync repeatedly.\nSurface the failure to the user, proceed with the read, and flag that cited\ncontent may be stale.\n\n**Avoid redundant syncs within a session.** Once you have synced and\ninvalidated the cache, ignore any further "citadel is behind" messages that\narrive before you have done another citadel read \u2014 they are cached signals\ncaptured before your sync completed.\n\n**Manual status check**\n\n```\nnpx maester status\n```\n\nExit codes:\n\n- **`0`** \u2014 every source is up to date.\n- **`1`** \u2014 at least one source is behind (remote advanced, manifest\n  changed, or never-synced). Run the auto-sync policy above.\n- **`2`** \u2014 the status check itself failed. Surface to the user; proceed\n  with a caveat that staleness cannot be verified.\n\nFor machine-readable output, pass `--json` and parse the NDJSON stream on\nstdout. The final line contains `{ "type": "summary", "upToDate": N,\n"behind": N, "failed": N }`.\n\n**On Claude Code specifically**, a `PreToolUse` hook installed by\n`maester skill install` runs the status check automatically before any\n`Read`, `Glob`, or `Grep` targeting a path under `{{baseDir}}/`. The\nhook debounces (default 300s, override with `MAESTER_SKILL_STATUS_TTL`) so\nthe check does not run more than once per session for routine reads.\n';
 
@@ -1358,7 +1775,9 @@ function renderClaudeSkillBody(opts) {
     "",
     interpolate(state_awareness_default, opts),
     "",
-    interpolate(freshness_awareness_default, opts)
+    interpolate(freshness_awareness_default, opts),
+    "",
+    interpolate(connector_policy_default, opts)
   ].join("\n");
 }
 function renderClaudeSkillFile(body) {
@@ -1458,53 +1877,66 @@ function combineActions(a, b) {
   return "unchanged";
 }
 
-// src/core/skill/templates/shells/agents-md.ts
-var PREAMBLE = `# AGENTS.md
-
-This file contains agent instructions for working in this repository. The
-section between the maester managed-region markers is generated by
-\`maester skill install\` and refreshed by \`maester skill upgrade\`. Anything
-you write outside that region is preserved across upgrades.
-`;
-function renderAgentsMdBody(opts) {
+// src/core/skill/templates/shells/codex.ts
+var SKILL_FRONTMATTER_DESCRIPTION2 = "Citadel-aware guidance for reading aggregated documentation under the citadel base directory. Prefers canon files over draft and runs maester status before substantial citadel reads.";
+function renderCodexSkillBody(opts) {
   return [
-    "# Grand Maester guidance",
+    "# Grand Maester (Codex CLI skill)",
     "",
-    "This repository is set up to aggregate documentation from remote sources",
-    "into a local citadel. When you reason about citadel content, follow the",
-    "guidance below.",
+    "Use this guidance whenever you read files under the citadel base directory",
+    `(\`${opts.baseDir}/\`) in this repository.`,
     "",
     interpolate2(citadel_awareness_default, opts),
     "",
     interpolate2(state_awareness_default, opts),
     "",
-    interpolate2(freshness_awareness_default, opts)
+    interpolate2(freshness_awareness_default, opts),
+    "",
+    interpolate2(connector_policy_default, opts)
   ].join("\n");
 }
-function agentsMdPreamble() {
-  return PREAMBLE;
+function renderCodexSkillFile(body) {
+  return [
+    "---",
+    "name: grand-maester",
+    `description: ${SKILL_FRONTMATTER_DESCRIPTION2}`,
+    "---",
+    "",
+    body
+  ].join("\n");
 }
 function interpolate2(template, opts) {
   return template.replace(/\{\{baseDir\}\}/g, opts.baseDir);
 }
 
-// src/core/skill/targets/agents-md-writer.ts
-var AGENTS_MD_ARTIFACT_PATH = "AGENTS.md";
-async function writeAgentsMd(input) {
-  const filePath = path.join(input.repoRoot, AGENTS_MD_ARTIFACT_PATH);
-  const existingText = await readTextOrUndefined2(filePath);
-  const previousVersion = existingText ? extractMarkdownRegion(existingText)?.version : void 0;
-  const body = renderAgentsMdBody({ baseDir: input.citadelBaseDir });
-  const next = replaceMarkdownRegion(existingText, body, input.skillVersion, agentsMdPreamble());
-  const action = decideAction(existingText, previousVersion, input.skillVersion, next);
+// src/core/skill/targets/codex.ts
+var SKILL_MD_PATH2 = ".agents/skills/grand-maester/SKILL.md";
+var codexTarget = {
+  id: "codex",
+  label: "Codex CLI",
+  artifactPaths: [SKILL_MD_PATH2],
+  writerKey: "codex",
+  write: writeCodex,
+  readInstalledVersion: readInstalledVersion2
+};
+async function writeCodex(input) {
+  const filePath = path.join(input.repoRoot, SKILL_MD_PATH2);
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  const existing = await readTextOrUndefined2(filePath);
+  const previousVersion = existing ? extractMarkdownRegion(existing)?.version : void 0;
+  const body = renderCodexSkillBody({ baseDir: input.citadelBaseDir });
+  const managedRegion = replaceMarkdownRegion(void 0, body, input.skillVersion).trimEnd();
+  const fileContent = existing ? replaceMarkdownRegion(existing, body, input.skillVersion) : `${renderCodexSkillFile(managedRegion)}
+`;
+  const action = decideAction(existing, previousVersion, input.skillVersion, fileContent);
   if (action === "unchanged") {
     return previousVersion !== void 0 ? { action, installedVersion: previousVersion } : { action };
   }
-  await promises.writeFile(filePath, next, "utf8");
+  await promises.writeFile(filePath, fileContent, "utf8");
   return { action, installedVersion: input.skillVersion };
 }
-async function readAgentsMdInstalledVersion(repoRoot) {
-  const filePath = path.join(repoRoot, AGENTS_MD_ARTIFACT_PATH);
+async function readInstalledVersion2(repoRoot) {
+  const filePath = path.join(repoRoot, SKILL_MD_PATH2);
   const text = await readTextOrUndefined2(filePath);
   if (!text) return void 0;
   return extractMarkdownRegion(text)?.version;
@@ -1525,16 +1957,6 @@ function decideAction(existing, previousVersion, newVersion, newContent) {
   return "upgraded";
 }
 
-// src/core/skill/targets/codex.ts
-var codexTarget = {
-  id: "codex",
-  label: "Codex CLI",
-  artifactPaths: [AGENTS_MD_ARTIFACT_PATH],
-  writerKey: "agents-md",
-  write: writeAgentsMd,
-  readInstalledVersion: readAgentsMdInstalledVersion
-};
-
 // src/core/skill/templates/shells/cursor.ts
 var DESCRIPTION = "Citadel-aware guidance for reading aggregated documentation under the citadel base directory.";
 function renderCursorRuleBody(opts) {
@@ -1548,7 +1970,9 @@ function renderCursorRuleBody(opts) {
     "",
     interpolate3(state_awareness_default, opts),
     "",
-    interpolate3(freshness_awareness_default, opts)
+    interpolate3(freshness_awareness_default, opts),
+    "",
+    interpolate3(connector_policy_default, opts)
   ].join("\n");
 }
 function renderCursorRuleFile(body, opts) {
@@ -1574,7 +1998,7 @@ var cursorTarget = {
   artifactPaths: [CURSOR_RULE_PATH],
   writerKey: "cursor",
   write: writeCursor,
-  readInstalledVersion: readInstalledVersion2
+  readInstalledVersion: readInstalledVersion3
 };
 async function writeCursor(input) {
   const filePath = path.join(input.repoRoot, CURSOR_RULE_PATH);
@@ -1596,7 +2020,7 @@ async function writeCursor(input) {
   await promises.writeFile(filePath, next, "utf8");
   return { action, installedVersion: input.skillVersion };
 }
-async function readInstalledVersion2(repoRoot) {
+async function readInstalledVersion3(repoRoot) {
   const filePath = path.join(repoRoot, CURSOR_RULE_PATH);
   const text = await readTextOrUndefined3(filePath);
   if (!text) return void 0;
@@ -1618,6 +2042,78 @@ function decideAction2(existing, previousVersion, newVersion, newContent) {
   return "upgraded";
 }
 
+// src/core/skill/templates/content/connector-policy-fallback.md
+var connector_policy_fallback_default = "## Connector tools (traveling maesters)\n\nThis citadel may expose one or more **traveling maesters** as connectors. Your\nagent platform does not speak MCP, so connector operations are reached via the\nfallback CLI:\n\n```\nnpx maester connector list\nnpx maester connector exec <connector-name> <operation> [--key value]...\n```\n\n- `connector list` prints the configured connectors and the operations they\n  expose.\n- `connector exec` invokes an operation and writes a JSON envelope to stdout.\n  Exit code `0` is success, `1` is a connector-level failure (auth, remote\n  error, invalid args), `2` is an invocation-level error (no such connector,\n  no citadel.yaml).\n\nTreat the data the same way as MCP tool output: live, point-in-time, cite\nspecific identifiers, flag freshness when it isn't `up-to-date`, and don't\nassume undocumented fields.\n";
+
+// src/core/skill/templates/shells/agents-md.ts
+var PREAMBLE = `# AGENTS.md
+
+This file contains agent instructions for working in this repository. The
+section between the maester managed-region markers is generated by
+\`maester skill install\` and refreshed by \`maester skill upgrade\`. Anything
+you write outside that region is preserved across upgrades.
+`;
+function renderAgentsMdBody(opts) {
+  return [
+    "# Grand Maester guidance",
+    "",
+    "This repository is set up to aggregate documentation from remote sources",
+    "into a local citadel. When you reason about citadel content, follow the",
+    "guidance below.",
+    "",
+    interpolate4(citadel_awareness_default, opts),
+    "",
+    interpolate4(state_awareness_default, opts),
+    "",
+    interpolate4(freshness_awareness_default, opts),
+    "",
+    interpolate4(connector_policy_fallback_default, opts)
+  ].join("\n");
+}
+function agentsMdPreamble() {
+  return PREAMBLE;
+}
+function interpolate4(template, opts) {
+  return template.replace(/\{\{baseDir\}\}/g, opts.baseDir);
+}
+
+// src/core/skill/targets/agents-md-writer.ts
+var AGENTS_MD_ARTIFACT_PATH = "AGENTS.md";
+async function writeAgentsMd(input) {
+  const filePath = path.join(input.repoRoot, AGENTS_MD_ARTIFACT_PATH);
+  const existingText = await readTextOrUndefined4(filePath);
+  const previousVersion = existingText ? extractMarkdownRegion(existingText)?.version : void 0;
+  const body = renderAgentsMdBody({ baseDir: input.citadelBaseDir });
+  const next = replaceMarkdownRegion(existingText, body, input.skillVersion, agentsMdPreamble());
+  const action = decideAction3(existingText, previousVersion, input.skillVersion, next);
+  if (action === "unchanged") {
+    return previousVersion !== void 0 ? { action, installedVersion: previousVersion } : { action };
+  }
+  await promises.writeFile(filePath, next, "utf8");
+  return { action, installedVersion: input.skillVersion };
+}
+async function readAgentsMdInstalledVersion(repoRoot) {
+  const filePath = path.join(repoRoot, AGENTS_MD_ARTIFACT_PATH);
+  const text = await readTextOrUndefined4(filePath);
+  if (!text) return void 0;
+  return extractMarkdownRegion(text)?.version;
+}
+async function readTextOrUndefined4(filePath) {
+  try {
+    return await promises.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+function decideAction3(existing, previousVersion, newVersion, newContent) {
+  if (existing === void 0) return "installed";
+  if (existing === newContent) return "unchanged";
+  if (previousVersion === void 0) return "installed";
+  if (previousVersion !== newVersion) return "upgraded";
+  return "upgraded";
+}
+
 // src/core/skill/targets/generic.ts
 var genericTarget = {
   id: "agents-md",
@@ -1629,20 +2125,20 @@ var genericTarget = {
 };
 
 // src/core/skill/targets/index.ts
-var REGISTRY = [
+var REGISTRY2 = [
   claudeCodeTarget,
   codexTarget,
   cursorTarget,
   genericTarget
 ];
 function listSkillTargets() {
-  return REGISTRY;
+  return REGISTRY2;
 }
 function getTarget(id) {
-  const found = REGISTRY.find((t) => t.id === id);
+  const found = REGISTRY2.find((t) => t.id === id);
   if (!found) {
     throw new Error(
-      `Unknown skill target '${id}'. Supported: ${REGISTRY.map((t) => t.id).join(", ")}`
+      `Unknown skill target '${id}'. Supported: ${REGISTRY2.map((t) => t.id).join(", ")}`
     );
   }
   return found;
@@ -1667,15 +2163,188 @@ function dedupeTargets(targets) {
   return [...groups.values()];
 }
 
+// src/core/mcp/registrations/command.ts
+function resolveMaesterLaunchCommand() {
+  return { command: "npx", args: ["-y", "baller-maester", "mcp"] };
+}
+
+// src/core/mcp/registrations/claude-code.ts
+var MCP_FILE = ".mcp.json";
+function maesterEntry(launch) {
+  return { command: launch.command, args: [...launch.args] };
+}
+async function writeClaudeCodeMcpEntry(repoRoot, options = {}) {
+  const launch = options.launch ?? resolveMaesterLaunchCommand();
+  return writeJsonMcpFile(path.join(repoRoot, MCP_FILE), launch);
+}
+async function writeJsonMcpFile(filePath, launch) {
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  const existingText = await readOrUndefined(filePath);
+  const newText = renderJsonWithMaesterEntry(existingText, launch);
+  if (existingText === newText) {
+    return { filePath, action: "unchanged" };
+  }
+  await promises.writeFile(filePath, newText, "utf8");
+  return { filePath, action: "written" };
+}
+function renderJsonWithMaesterEntry(existingText, launch) {
+  const parsed = parseOrEmpty(existingText);
+  const rebuilt = {};
+  let placed = false;
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === "mcpServers") {
+      rebuilt[key] = mutateMcpServers(value, launch);
+      placed = true;
+    } else {
+      rebuilt[key] = value;
+    }
+  }
+  if (!placed) {
+    rebuilt.mcpServers = mutateMcpServers(void 0, launch);
+  }
+  return `${JSON.stringify(rebuilt, null, 2)}
+`;
+}
+function mutateMcpServers(existing, launch) {
+  const map = isPlainObject(existing) ? { ...existing } : {};
+  const rebuilt = {};
+  let placed = false;
+  for (const [key, value] of Object.entries(map)) {
+    if (key === "maester") {
+      rebuilt[key] = maesterEntry(launch);
+      placed = true;
+    } else {
+      rebuilt[key] = value;
+    }
+  }
+  if (!placed) {
+    rebuilt.maester = maesterEntry(launch);
+  }
+  return rebuilt;
+}
+function parseOrEmpty(text) {
+  if (!text || text.trim().length === 0) return {};
+  const parsed = JSON.parse(text);
+  if (!isPlainObject(parsed)) {
+    throw new Error("Expected MCP config to be a JSON object at the top level.");
+  }
+  return parsed;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readOrUndefined(filePath) {
+  try {
+    return await promises.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+var CONFIG_FILE = path.join(".codex", "config.toml");
+function maesterBlock(repoRoot, launch) {
+  return { command: launch.command, args: [...launch.args], cwd: repoRoot };
+}
+async function writeCodexMcpEntry(repoRoot, options = {}) {
+  const filePath = path.join(repoRoot, CONFIG_FILE);
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  const existingText = await readOrUndefined2(filePath);
+  const launch = options.launch ?? resolveMaesterLaunchCommand();
+  const newText = renderTomlWithMaesterBlock(existingText, repoRoot, launch);
+  if (existingText === newText) {
+    return { filePath, action: "unchanged" };
+  }
+  await promises.writeFile(filePath, newText, "utf8");
+  return { filePath, action: "written" };
+}
+function renderTomlWithMaesterBlock(existingText, repoRoot, launch) {
+  const parsed = existingText && existingText.trim().length > 0 ? TOML.parse(existingText) : {};
+  const mcpServers = isJsonMap(parsed.mcp_servers) ? { ...parsed.mcp_servers } : {};
+  mcpServers.maester = maesterBlock(repoRoot, launch);
+  const next = { ...parsed, mcp_servers: mcpServers };
+  return TOML.stringify(next);
+}
+function isJsonMap(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readOrUndefined2(filePath) {
+  try {
+    return await promises.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+var MCP_FILE2 = path.join(".cursor", "mcp.json");
+async function writeCursorMcpEntry(repoRoot, options = {}) {
+  const launch = options.launch ?? resolveMaesterLaunchCommand();
+  return writeJsonMcpFile(path.join(repoRoot, MCP_FILE2), launch);
+}
+
+// src/core/mcp/registrations/index.ts
+async function refreshMcpRegistrations(repoRoot, options = {}) {
+  const targets = listSkillTargets().filter(
+    (t) => isMcpHost(t.id) && (!options.scopeTo || options.scopeTo.includes(t.id))
+  );
+  const outcomes = [];
+  for (const target of targets) {
+    const installedVersion = await target.readInstalledVersion(repoRoot);
+    if (installedVersion === void 0 && !options.scopeTo?.includes(target.id)) {
+      continue;
+    }
+    const outcome = await runWriter(target, repoRoot);
+    outcomes.push(outcome);
+  }
+  return outcomes;
+}
+function isMcpHost(id) {
+  return id === "claude-code" || id === "cursor" || id === "codex";
+}
+async function runWriter(target, repoRoot) {
+  try {
+    switch (target.id) {
+      case "claude-code": {
+        const r = await writeClaudeCodeMcpEntry(repoRoot);
+        return { host: "claude-code", filePath: r.filePath, action: r.action };
+      }
+      case "cursor": {
+        const r = await writeCursorMcpEntry(repoRoot);
+        return { host: "cursor", filePath: r.filePath, action: r.action };
+      }
+      case "codex": {
+        const r = await writeCodexMcpEntry(repoRoot);
+        return { host: "codex", filePath: r.filePath, action: r.action };
+      }
+      default:
+        return {
+          host: target.id,
+          filePath: "",
+          action: "skipped"
+        };
+    }
+  } catch (err) {
+    return {
+      host: target.id,
+      filePath: "",
+      action: "failed",
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+
 // package.json
 var package_default = {
-  version: "0.3.0"};
+  version: "0.4.0"};
 var PACKAGE_VERSION = package_default.version;
 
 // src/core/skill/version.ts
 var SKILL_VERSION = PACKAGE_VERSION;
 
 // src/core/skill/runner.ts
+var MCP_HOST_IDS = ["claude-code", "cursor", "codex"];
+function selectMcpHosts(targetIds) {
+  return targetIds.filter((id) => MCP_HOST_IDS.includes(id));
+}
 async function runSkillInstall(repoRoot, opts) {
   if (opts.targets.length === 0) {
     throw new Error("At least one target id must be supplied.");
@@ -1703,12 +2372,14 @@ async function runSkillInstall(repoRoot, opts) {
       });
     }
   }
-  return { outcomes, counts: countOutcomes(outcomes) };
+  const mcpHosts = selectMcpHosts(opts.targets);
+  const mcpRegistrations = mcpHosts.length > 0 ? await refreshMcpRegistrations(repoRoot, { scopeTo: mcpHosts }) : [];
+  return { outcomes, counts: countOutcomes(outcomes), mcpRegistrations };
 }
 async function runSkillUpgrade(repoRoot, opts) {
   const installedGroups = await findInstalledGroups(repoRoot);
   if (installedGroups.length === 0) {
-    return { outcomes: [], counts: countOutcomes([]) };
+    return { outcomes: [], counts: countOutcomes([]), mcpRegistrations: [] };
   }
   const outcomes = [];
   for (const group of installedGroups) {
@@ -1749,7 +2420,8 @@ async function runSkillUpgrade(repoRoot, opts) {
       });
     }
   }
-  return { outcomes, counts: countOutcomes(outcomes) };
+  const mcpRegistrations = opts.check === true ? [] : await refreshMcpRegistrations(repoRoot);
+  return { outcomes, counts: countOutcomes(outcomes), mcpRegistrations };
 }
 async function runSkillStatus(repoRoot) {
   const outcomes = [];
@@ -1814,6 +2486,204 @@ function countOutcomes(outcomes) {
   return { installed, upgraded, unchanged, failed };
 }
 
-export { AuthError, ConfigError, DestinationBlockedError, MaesterError, RefNotFoundError, SKILL_VERSION, listSkillTargets, loadCitadelConfig, loadMaesterConfig, runSkillInstall, runSkillStatus, runSkillUpgrade, runStatus, runSync };
+// src/core/connectors/envelope.ts
+function buildSuccessEnvelope(input) {
+  return {
+    schema: ENVELOPE_SCHEMA_VERSION,
+    connector: input.connector,
+    operation: input.operation,
+    ok: true,
+    data: { ...input.data, dataSchema: input.dataSchemaVersion }
+  };
+}
+function buildFailureEnvelope(input) {
+  return {
+    schema: ENVELOPE_SCHEMA_VERSION,
+    connector: input.connector,
+    operation: input.operation,
+    ok: false,
+    error: {
+      code: input.code,
+      message: input.message,
+      ...input.details ? { details: input.details } : {}
+    }
+  };
+}
+function argsSchemaToJsonSchema(schema) {
+  const raw = zodToJsonSchema(schema, {
+    $refStrategy: "none",
+    target: "jsonSchema7"
+  });
+  const {
+    $schema: _omitSchema,
+    definitions: _omitDefs,
+    ...rest
+  } = raw;
+  return rest;
+}
+
+// src/core/connectors/tool-name.ts
+var VALID_TOOL_NAME_RE = /^[a-z][a-z0-9_]*$/;
+function toolName(connectorName, operationName) {
+  const left = normalize(connectorName);
+  const right = normalize(operationName);
+  const result = `${left}__${right}`;
+  if (!VALID_TOOL_NAME_RE.test(result)) {
+    throw new Error(
+      `Invalid MCP tool name '${result}' (from connector '${connectorName}', operation '${operationName}'). Names must match /^[a-z][a-z0-9_]*$/ after normalization.`
+    );
+  }
+  return result;
+}
+function normalize(part) {
+  return part.toLowerCase().replace(/-/g, "_");
+}
+
+// src/core/connectors/dispatch.ts
+async function invokeOperation(input) {
+  const { connector, operationName, args, env } = input;
+  const type = lookupConnectorType(connector.type);
+  if (!type) {
+    return buildFailureEnvelope({
+      connector: connector.name,
+      operation: operationName,
+      code: "connector-not-found",
+      message: `No registered connector type '${connector.type}' for connector '${connector.name}'.`
+    });
+  }
+  const operation = type.operations[operationName];
+  if (!operation) {
+    const known = Object.keys(type.operations).sort();
+    return buildFailureEnvelope({
+      connector: connector.name,
+      operation: operationName,
+      code: "unknown-operation",
+      message: `Connector '${connector.name}' (type '${type.id}') has no operation '${operationName}'. Known operations: ${known.join(", ") || "(none)"}.`
+    });
+  }
+  let resolvedConfig;
+  try {
+    resolvedConfig = type.configSchema.parse(connector.config);
+  } catch (err) {
+    return buildFailureEnvelope({
+      connector: connector.name,
+      operation: operationName,
+      code: "invalid-argument",
+      message: `Connector '${connector.name}' has invalid per-type config for type '${type.id}'.`,
+      details: { cause: zodIssueDetails(err) }
+    });
+  }
+  let parsedArgs;
+  try {
+    parsedArgs = operation.argsSchema.parse(args ?? {});
+  } catch (err) {
+    return buildFailureEnvelope({
+      connector: connector.name,
+      operation: operationName,
+      code: "invalid-argument",
+      message: `Invalid arguments for operation '${operationName}'.`,
+      details: { cause: zodIssueDetails(err) }
+    });
+  }
+  let auth;
+  try {
+    auth = resolveAuth(connector.auth, env ?? process.env);
+  } catch (err) {
+    if (err instanceof AuthError) {
+      return buildFailureEnvelope({
+        connector: connector.name,
+        operation: operationName,
+        code: "missing-env-var",
+        message: `Environment variable '${err.envVar}' is not set; required by connector '${connector.name}'.`,
+        details: { envVar: err.envVar }
+      });
+    }
+    throw err;
+  }
+  try {
+    const result = await operation.handler(parsedArgs, {
+      config: resolvedConfig,
+      token: auth.type === "token" ? auth.value : void 0,
+      auth
+    });
+    return buildSuccessEnvelope({
+      connector: connector.name,
+      operation: operationName,
+      data: result.data,
+      dataSchemaVersion: operation.dataSchemaVersion
+    });
+  } catch (err) {
+    if (err instanceof ConnectorError) {
+      return buildFailureEnvelope({
+        connector: connector.name,
+        operation: operationName,
+        code: err.code,
+        message: err.message,
+        ...err.details ? { details: err.details } : {}
+      });
+    }
+    process.stderr.write(
+      `[maester] internal error in connector '${connector.name}'.${operationName}: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`
+    );
+    return buildFailureEnvelope({
+      connector: connector.name,
+      operation: operationName,
+      code: "internal-error",
+      message: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function buildToolDescription(connector, operation, resolvedConfig, type) {
+  const typeDescription = type.describeTool(operation, resolvedConfig);
+  const entryDescription = connector.description?.trim();
+  return entryDescription ? `${entryDescription} ${typeDescription}` : typeDescription;
+}
+function listConnectorTools(config) {
+  const descriptors = [];
+  const connectors = config.connectors ?? [];
+  for (const connector of connectors) {
+    const type = lookupConnectorType(connector.type);
+    if (!type) {
+      throw new Error(
+        `Connector '${connector.name}' references unregistered type '${connector.type}'. This indicates registry mutation after config load.`
+      );
+    }
+    const resolvedConfig = type.configSchema.parse(connector.config);
+    for (const operation of Object.values(type.operations)) {
+      descriptors.push({
+        name: toolName(connector.name, operation.name),
+        description: buildToolDescription(connector, operation, resolvedConfig, type),
+        inputSchema: argsSchemaToJsonSchema(operation.argsSchema)
+      });
+    }
+  }
+  return descriptors;
+}
+function findOperationByToolName(config, candidateToolName) {
+  const connectors = config.connectors ?? [];
+  for (const connector of connectors) {
+    const type = lookupConnectorType(connector.type);
+    if (!type) continue;
+    for (const operation of Object.values(type.operations)) {
+      if (toolName(connector.name, operation.name) === candidateToolName) {
+        return { connector, operationName: operation.name, type };
+      }
+    }
+  }
+  return void 0;
+}
+function zodIssueDetails(err) {
+  if (err instanceof z.ZodError) {
+    return err.issues.map((issue) => ({
+      path: issue.path,
+      message: issue.message,
+      code: issue.code
+    }));
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+export { AuthError, CONNECTOR_ERROR_CODES, ConfigError, ConnectorError, DestinationBlockedError, ENVELOPE_SCHEMA_VERSION, MaesterError, RefNotFoundError, SKILL_VERSION, buildToolDescription, defineConnectorOperation, findOperationByToolName, hasConnectorType, invokeOperation, listConnectorTools, listConnectorTypes, listSkillTargets, loadCitadelConfig, loadMaesterConfig, lookupConnectorType, registerConnectorType, runSkillInstall, runSkillStatus, runSkillUpgrade, runStatus, runSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map