baller-maester 0.2.1 → 0.4.0

package/dist/cli/main.js

@@ -1,16 +1,21 @@
 import { Command } from 'commander';
 import { existsSync, promises } from 'fs';
-import path4, { resolve, dirname, relative, extname } from 'path';
+import path8, { resolve, dirname, relative, extname } from 'path';
 import { z } from 'zod';
 import * as clack from '@clack/prompts';
 import { Chalk } from 'chalk';
 import { readFile, mkdir, writeFile, mkdtemp, rm, readdir, cp, rename } from 'fs/promises';
 import { parseDocument, isMap, stringify } from 'yaml';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import TOML from '@iarna/toml';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createConsola, consola } from 'consola';
 import { globby } from 'globby';
 import { execFile as execFile$1 } from 'child_process';
 import { promisify } from 'util';
 import { simpleGit } from 'simple-git';
-import { createConsola } from 'consola';
 import picomatch from 'picomatch';
 import matter from 'gray-matter';
 
@@ -19,6 +24,361 @@ 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;
+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);
+}
 var STATE_VALUES = ["draft", "canon"];
 var StateSchema = z.enum(STATE_VALUES);
 var DEFAULT_STATE = "draft";
@@ -83,6 +443,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) {
@@ -121,11 +488,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);
 });
@@ -551,216 +953,411 @@ function readColumns(stream = process.stdout) {
   if (typeof stream.columns === "number" && stream.columns > 0) return stream.columns;
   return DEFAULT_FALLBACK;
 }
-var CITADEL_HEADER = `# citadel.yaml
-#
-# This file declares the remote knowledge sources this repository pulls into
-# a local destination directory.
-#
-# Each source is a git repository. By default, the citadel fetches whatever
-# the source publishes in its own \`maester.yaml\` manifest. If a source does
-# not publish a manifest (or you want to override what gets pulled), declare
-# an \`includes\` list and the citadel will materialize exactly those paths
-# or globs instead.
-#
-# By default, every source is surfaced at \`<baseDir>/<source-name>/\` from the
-# repository root. The optional top-level \`baseDir\` field changes that parent
-# folder once for every source; when omitted, the default is \`citadel\`. A
-# per-source \`destination\` always wins over the configured base.
-#
-# Run \`maester sync\` (or \`npm run maester:sync\`) to refresh every source in
-# one pass. Generated by \`npx maester init\` and safe to commit. Secret
-# values are never stored here \u2014 only the names of environment variables
-# that hold them.
-
-`;
-var MAESTER_HEADER = `# maester.yaml
-#
-# This file declares the documents this repository publishes to any citadel
-# that pulls from it. It is a manifest only \u2014 the documents themselves live
-# wherever the \`path\` fields point, and \`maester\` does not modify them.
-#
-# Generated by \`npx maester publish\` and safe to commit.
+function isSafeRepoRelative(value) {
+  if (value.length === 0 || /^\s+$/.test(value)) return false;
+  if (value.startsWith("/")) return false;
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) return false;
+  return true;
+}
+var PublishedDocumentSchema = z.object({
+  path: z.string().min(1).refine(
+    isSafeRepoRelative,
+    "path must be a repo-relative file or glob; no leading '/' and no '..'"
+  ),
+  description: z.string().min(1).optional(),
+  category: z.string().min(1).regex(SLUG_RE, "category must be a kebab-case slug").optional(),
+  tags: z.array(z.string().min(1).regex(SLUG_RE, "tags must be slugs")).optional(),
+  state: StateSchema.optional()
+}).strict();
+var MaesterConfigSchema = z.object({
+  schemaVersion: z.literal(1),
+  documents: z.array(PublishedDocumentSchema).min(1, "at least one published document must be declared").superRefine((docs, ctx) => {
+    const seen = /* @__PURE__ */ new Map();
+    for (let i = 0; i < docs.length; i++) {
+      const p = docs[i]?.path;
+      if (!p) continue;
+      const prior = seen.get(p);
+      if (prior !== void 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `duplicate path '${p}' (also at index ${prior})`,
+          path: [i, "path"]
+        });
+      } else {
+        seen.set(p, i);
+      }
+    }
+  })
+}).strict();
 
-`;
-async function writeCitadelConfig(repoRoot, config) {
-  const path5 = citadelConfigPath(repoRoot);
-  const ordered = {
-    schemaVersion: config.schemaVersion,
-    ...config.baseDir ? { baseDir: config.baseDir } : {},
-    sources: config.sources
-  };
-  const body = stringify(ordered, { indent: 2, lineWidth: 100, singleQuote: false });
-  await writeFile(path5, `${CITADEL_HEADER}${body}`, "utf8");
-  return path5;
+// src/core/config/loader.ts
+async function loadCitadelConfig(repoRoot) {
+  const path9 = citadelConfigPath(repoRoot);
+  if (!existsSync(path9)) {
+    throw new ConfigError(
+      "No citadel.yaml found at the repository root. Run `npx maester init` to create one.",
+      { filePath: path9 }
+    );
+  }
+  const raw = await readFile(path9, "utf8");
+  return parseAndValidate(raw, CitadelConfigSchema, path9);
 }
-async function writeMaesterConfig(repoRoot, config) {
-  const path5 = maesterConfigPath(repoRoot);
-  const body = stringify(config, { indent: 2, lineWidth: 100, singleQuote: false });
-  await writeFile(path5, `${MAESTER_HEADER}${body}`, "utf8");
-  return path5;
+function parseAndValidate(raw, schema, filePath) {
+  const data = parseYaml(raw, filePath);
+  return runSchema(data, schema, filePath);
 }
-async function appendMissingGitignoreEntries(repoRoot, entries) {
-  const path5 = resolve(repoRoot, ".gitignore");
-  let existing = "";
-  if (existsSync(path5)) {
-    existing = await readFile(path5, "utf8");
-  }
-  const existingLines = new Set(
-    existing.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0)
-  );
-  const added = [];
-  const alreadyPresent = [];
-  for (const entry of entries) {
-    const normalized = entry.trim();
-    if (normalized.length === 0) continue;
-    if (existingLines.has(normalized)) {
-      alreadyPresent.push(normalized);
-    } else {
-      added.push(normalized);
-      existingLines.add(normalized);
-    }
+function parseYaml(raw, filePath) {
+  const doc = parseDocument(raw, { keepSourceTokens: false });
+  const yamlErrors = doc.errors;
+  if (yamlErrors.length > 0) {
+    const first = yamlErrors[0];
+    const pos = positionFromError(first, raw);
+    throw new ConfigError(`YAML parse error: ${first.message}`, {
+      filePath,
+      line: pos.line,
+      column: pos.column,
+      cause: first
+    });
   }
-  if (added.length === 0) {
-    return { added, alreadyPresent };
+  return doc.toJS({ maxAliasCount: -1 });
+}
+function runSchema(data, schema, filePath) {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const where = issue?.path?.length ? ` at \`${issue.path.join(".")}\`` : "";
+    throw new ConfigError(`${filePath}: ${issue?.message ?? "validation failed"}${where}`, {
+      filePath,
+      cause: result.error
+    });
   }
-  const needsTrailingNewline = existing.length > 0 && !existing.endsWith("\n");
-  const appendBlock = `${needsTrailingNewline ? "\n" : ""}${added.join("\n")}
-`;
-  await writeFile(path5, `${existing}${appendBlock}`, "utf8");
-  return { added, alreadyPresent };
+  return result.data;
 }
-async function ensureScript(repoRoot, scriptName, command) {
-  const path5 = resolve(repoRoot, "package.json");
-  if (!existsSync(path5)) {
-    return { added: false, reason: "no-package-json" };
+function positionFromError(err, raw) {
+  const pos = err.pos;
+  if (!pos) return { line: 1, column: 1 };
+  const offset = pos[0];
+  let line = 1;
+  let lastLineStart = 0;
+  for (let i = 0; i < offset && i < raw.length; i++) {
+    if (raw[i] === "\n") {
+      line++;
+      lastLineStart = i + 1;
+    }
   }
-  const raw = await readFile(path5, "utf8");
-  const trailingNewline = raw.endsWith("\n");
-  const parsed = JSON.parse(raw);
-  const scripts = parsed.scripts ?? {};
-  if (scripts[scriptName] === command) {
-    return { added: false, reason: "already-set" };
-  }
-  if (typeof scripts[scriptName] === "string" && scripts[scriptName] !== command) {
-    return { added: false, reason: "already-set" };
+  return { line, column: offset - lastLineStart + 1 };
+}
+
+// src/core/auth/resolver.ts
+function resolveAuth(auth, env = process.env) {
+  if (!auth || auth.type === "none") return { type: "delegated" };
+  const value = env[auth.envVar];
+  if (value === void 0 || value.length === 0) {
+    throw new AuthError(
+      auth.envVar,
+      `${auth.envVar} is not set. Define it in your shell, .env loader, or CI secret manager before syncing.`
+    );
   }
-  scripts[scriptName] = command;
-  parsed.scripts = scripts;
-  const serialized = JSON.stringify(parsed, null, 2) + (trailingNewline ? "\n" : "");
-  await writeFile(path5, serialized, "utf8");
-  return { added: true, reason: "added" };
+  return { type: "token", value, envVar: auth.envVar };
 }
 
-// src/core/init/finalize.ts
-async function finalizeCitadel(repoRoot, input) {
-  detectDestinationCollisions(repoRoot, input);
-  const config = {
-    schemaVersion: 1,
-    ...input.baseDir ? { baseDir: input.baseDir } : {},
-    sources: input.sources
-  };
-  const citadelPath = await writeCitadelConfig(repoRoot, config);
-  const gitignore = await appendMissingGitignoreEntries(repoRoot, [`${CACHE_DIR_NAME}/`]);
-  const script = await ensureScript(repoRoot, "maester:sync", "maester sync");
+// src/core/connectors/envelope.ts
+function buildSuccessEnvelope(input) {
   return {
-    citadelPath,
-    gitignoreAdded: gitignore.added,
-    packageJsonScript: script.reason
+    schema: ENVELOPE_SCHEMA_VERSION,
+    connector: input.connector,
+    operation: input.operation,
+    ok: true,
+    data: { ...input.data, dataSchema: input.dataSchemaVersion }
   };
 }
-function detectDestinationCollisions(repoRoot, input, baseDirArg) {
-  const baseDir = Array.isArray(input) ? baseDirArg : input.baseDir;
-  const entries = Array.isArray(input) ? input : input.sources.map((s) => ({ name: s.name, destination: s.destination }));
-  const byDest = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
-    const dest = entry.destination ? resolve(repoRoot, entry.destination) : defaultDestinationFor(repoRoot, entry.name, baseDir);
-    const prior = byDest.get(dest);
-    if (prior) {
-      throw new Error(
-        `sources '${entry.name}' and '${prior.name}' both resolve to destination '${dest}'. Set a unique destination for one of them.`
-      );
+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 } : {}
     }
-    byDest.set(dest, { name: entry.name });
-  }
+  };
+}
+function argsSchemaToJsonSchema(schema) {
+  const raw = zodToJsonSchema(schema, {
+    $refStrategy: "none",
+    target: "jsonSchema7"
+  });
+  const {
+    $schema: _omitSchema,
+    definitions: _omitDefs,
+    ...rest
+  } = raw;
+  return rest;
 }
 
-// src/core/init/validators.ts
-function validateSourceName(value) {
-  if (!value || value.length === 0) return { ok: false, reason: "Name cannot be empty." };
-  if (!SLUG_RE.test(value)) {
-    return {
-      ok: false,
-      reason: "Name must be a kebab-case slug (lowercase letters, digits, and hyphens)."
-    };
+// 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 { ok: true };
+  return result;
 }
-function validateGitUrl(value) {
-  if (!value || value.length === 0) return { ok: false, reason: "URL cannot be empty." };
-  if (/\s/.test(value)) return { ok: false, reason: "URL cannot contain whitespace." };
-  if (value.startsWith("https://") || value.startsWith("ssh://") || value.startsWith("file://")) {
-    return { ok: true };
-  }
-  if (/^git@[^\s:]+:\S+$/.test(value)) return { ok: true };
-  return {
-    ok: false,
-    reason: "URL must start with https://, ssh://, file://, or use the git@host:path form."
-  };
+function normalize(part) {
+  return part.toLowerCase().replace(/-/g, "_");
 }
-function validateEnvVarName(value) {
-  if (!value || value.length === 0) {
-    return { ok: false, reason: "Environment variable name cannot be empty." };
+
+// 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}'.`
+    });
   }
-  if (/\s/.test(value)) return { ok: false, reason: "Whitespace is not allowed." };
-  if (!ENV_VAR_RE.test(value)) {
-    return {
-      ok: false,
-      reason: "Environment variable name must be UPPER_SNAKE_CASE (e.g. MAESTER_DOCS_TOKEN)."
-    };
+  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)"}.`
+    });
   }
-  if (value.length >= 32 && !value.includes("_")) {
-    return {
-      ok: true,
-      warning: "That looks unusually long and has no underscores \u2014 make sure you entered the NAME of the env var, not its value."
-    };
+  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) }
+    });
   }
-  return { ok: true };
-}
-function validateDestination(value) {
-  if (!value || value.length === 0) return { ok: true };
-  if (value.startsWith("/"))
-    return { ok: false, reason: "Destination must be repo-relative (no leading '/')." };
-  if (value.split(/[\\/]+/).some((seg) => seg === "..")) {
-    return { ok: false, reason: "Destination cannot contain '..' segments." };
+  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)
+    });
   }
-  return { ok: true };
 }
-function validateBaseDir(value) {
-  if (!value || value.length === 0) return { ok: true };
-  if (value.startsWith("/"))
-    return { ok: false, reason: "Base directory must be repo-relative (no leading '/')." };
-  if (value.split(/[\\/]+/).some((seg) => seg === "..")) {
-    return { ok: false, reason: "Base directory cannot contain '..' segments." };
+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 { ok: true };
+  return descriptors;
 }
-function validateIncludesEntry(value) {
-  if (!value || value.length === 0) return { ok: false, reason: "Includes entry cannot be empty." };
-  if (/^\s+$/.test(value)) return { ok: false, reason: "Includes entry cannot be whitespace." };
-  if (value.startsWith("/")) {
-    return { ok: false, reason: "Includes entry must be repo-relative (no leading '/')." };
+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 };
+      }
+    }
   }
-  if (value.split(/[\\/]+/).some((seg) => seg === "..")) {
-    return { ok: false, reason: "Includes entry cannot contain '..' segments." };
+  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 { ok: true };
+  return err instanceof Error ? err.message : String(err);
 }
-function validateTag(value) {
-  if (!value || value.length === 0) return { ok: false, reason: "Tag cannot be empty." };
-  if (!SLUG_RE.test(value)) {
-    return { ok: false, reason: "Tag must be a kebab-case slug." };
+var CITADEL_HEADER = `# citadel.yaml
+#
+# This file declares the remote knowledge sources this repository pulls into
+# a local destination directory.
+#
+# Each source is a git repository. By default, the citadel fetches whatever
+# the source publishes in its own \`maester.yaml\` manifest. If a source does
+# not publish a manifest (or you want to override what gets pulled), declare
+# an \`includes\` list and the citadel will materialize exactly those paths
+# or globs instead.
+#
+# By default, every source is surfaced at \`<baseDir>/<source-name>/\` from the
+# repository root. The optional top-level \`baseDir\` field changes that parent
+# folder once for every source; when omitted, the default is \`citadel\`. A
+# per-source \`destination\` always wins over the configured base.
+#
+# Run \`maester sync\` (or \`npm run maester:sync\`) to refresh every source in
+# one pass. Generated by \`npx maester init\` and safe to commit. Secret
+# values are never stored here \u2014 only the names of environment variables
+# that hold them.
+
+`;
+var MAESTER_HEADER = `# maester.yaml
+#
+# This file declares the documents this repository publishes to any citadel
+# that pulls from it. It is a manifest only \u2014 the documents themselves live
+# wherever the \`path\` fields point, and \`maester\` does not modify them.
+#
+# Generated by \`npx maester publish\` and safe to commit.
+
+`;
+async function writeCitadelConfig(repoRoot, config) {
+  const path9 = citadelConfigPath(repoRoot);
+  const ordered = {
+    schemaVersion: config.schemaVersion,
+    ...config.baseDir ? { baseDir: config.baseDir } : {},
+    sources: config.sources,
+    ...config.connectors && config.connectors.length > 0 ? { connectors: config.connectors } : {}
+  };
+  const body = stringify(ordered, { indent: 2, lineWidth: 100, singleQuote: false });
+  await writeFile(path9, `${CITADEL_HEADER}${body}`, "utf8");
+  return path9;
+}
+async function writeMaesterConfig(repoRoot, config) {
+  const path9 = maesterConfigPath(repoRoot);
+  const body = stringify(config, { indent: 2, lineWidth: 100, singleQuote: false });
+  await writeFile(path9, `${MAESTER_HEADER}${body}`, "utf8");
+  return path9;
+}
+
+// src/core/init/connector-writer.ts
+var ConnectorNotFoundError = class extends MaesterError {
+  connectorName;
+  constructor(name) {
+    super("CONNECTOR_NOT_FOUND", `No connector named '${name}' is configured in citadel.yaml.`);
+    this.name = "ConnectorNotFoundError";
+    this.connectorName = name;
   }
-  return { ok: true };
+};
+var DuplicateConnectorError = class extends MaesterError {
+  connectorName;
+  constructor(name) {
+    super(
+      "DUPLICATE_CONNECTOR",
+      `A connector named '${name}' is already declared in citadel.yaml.`
+    );
+    this.name = "DuplicateConnectorError";
+    this.connectorName = name;
+  }
+};
+async function addConnectorToCitadel(repoRoot, connector) {
+  const config = await loadCitadelConfig(repoRoot);
+  const existing = config.connectors ?? [];
+  if (existing.some((c) => c.name === connector.name)) {
+    throw new DuplicateConnectorError(connector.name);
+  }
+  const next = {
+    ...config,
+    connectors: [...existing, connector]
+  };
+  const filePath = await writeCitadelConfig(repoRoot, next);
+  return { filePath, config: next };
+}
+async function removeConnectorFromCitadel(repoRoot, name) {
+  const config = await loadCitadelConfig(repoRoot);
+  const existing = config.connectors ?? [];
+  const index = existing.findIndex((c) => c.name === name);
+  if (index === -1) {
+    throw new ConnectorNotFoundError(name);
+  }
+  const next = {
+    ...config,
+    connectors: existing.filter((_, i) => i !== index)
+  };
+  const filePath = await writeCitadelConfig(repoRoot, next);
+  return { filePath, config: next };
+}
+async function listConnectorsFromCitadel(repoRoot) {
+  const config = await loadCitadelConfig(repoRoot);
+  return [...config.connectors ?? []];
 }
 
 // src/core/skill/managed-region.ts
@@ -804,7 +1401,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.");
@@ -813,14 +1410,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)}
 `;
@@ -842,6 +1439,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';
 
@@ -861,7 +1461,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) {
@@ -912,8 +1514,8 @@ async function writeClaudeCode(input) {
   };
 }
 async function writeSkillMd(input) {
-  const filePath = path4.join(input.repoRoot, SKILL_MD_PATH);
-  await promises.mkdir(path4.dirname(filePath), { recursive: true });
+  const filePath = path8.join(input.repoRoot, SKILL_MD_PATH);
+  await promises.mkdir(path8.dirname(filePath), { recursive: true });
   const existing = await readTextOrUndefined(filePath);
   const previousVersion = existing ? extractMarkdownRegion(existing)?.version : void 0;
   const body = renderClaudeSkillBody({ baseDir: input.citadelBaseDir });
@@ -927,8 +1529,8 @@ async function writeSkillMd(input) {
   return { action: "upgraded" };
 }
 async function writeSettingsJson(input) {
-  const filePath = path4.join(input.repoRoot, SETTINGS_JSON_PATH);
-  await promises.mkdir(path4.dirname(filePath), { recursive: true });
+  const filePath = path8.join(input.repoRoot, SETTINGS_JSON_PATH);
+  await promises.mkdir(path8.dirname(filePath), { recursive: true });
   const existing = await readTextOrUndefined(filePath);
   const previousBlock = readJsonMaesterKey(existing);
   const previousVersion = typeof previousBlock?.version === "string" ? previousBlock.version : void 0;
@@ -941,7 +1543,7 @@ async function writeSettingsJson(input) {
   return { action: "upgraded" };
 }
 async function readInstalledVersion(repoRoot) {
-  const skillPath = path4.join(repoRoot, SKILL_MD_PATH);
+  const skillPath = path8.join(repoRoot, SKILL_MD_PATH);
   const text2 = await readTextOrUndefined(skillPath);
   if (!text2) return void 0;
   return extractMarkdownRegion(text2)?.version;
@@ -961,53 +1563,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 = path4.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 = path8.join(input.repoRoot, SKILL_MD_PATH2);
+  await promises.mkdir(path8.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 = path4.join(repoRoot, AGENTS_MD_ARTIFACT_PATH);
+async function readInstalledVersion2(repoRoot) {
+  const filePath = path8.join(repoRoot, SKILL_MD_PATH2);
   const text2 = await readTextOrUndefined2(filePath);
   if (!text2) return void 0;
   return extractMarkdownRegion(text2)?.version;
@@ -1028,16 +1643,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) {
@@ -1051,7 +1656,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) {
@@ -1077,11 +1684,11 @@ var cursorTarget = {
   artifactPaths: [CURSOR_RULE_PATH],
   writerKey: "cursor",
   write: writeCursor,
-  readInstalledVersion: readInstalledVersion2
+  readInstalledVersion: readInstalledVersion3
 };
 async function writeCursor(input) {
-  const filePath = path4.join(input.repoRoot, CURSOR_RULE_PATH);
-  await promises.mkdir(path4.dirname(filePath), { recursive: true });
+  const filePath = path8.join(input.repoRoot, CURSOR_RULE_PATH);
+  await promises.mkdir(path8.dirname(filePath), { recursive: true });
   const existing = await readTextOrUndefined3(filePath);
   const previousVersion = existing ? extractMarkdownRegion(existing)?.version : void 0;
   const body = renderCursorRuleBody({ baseDir: input.citadelBaseDir });
@@ -1099,8 +1706,8 @@ async function writeCursor(input) {
   await promises.writeFile(filePath, next, "utf8");
   return { action, installedVersion: input.skillVersion };
 }
-async function readInstalledVersion2(repoRoot) {
-  const filePath = path4.join(repoRoot, CURSOR_RULE_PATH);
+async function readInstalledVersion3(repoRoot) {
+  const filePath = path8.join(repoRoot, CURSOR_RULE_PATH);
   const text2 = await readTextOrUndefined3(filePath);
   if (!text2) return void 0;
   return extractMarkdownRegion(text2)?.version;
@@ -1113,72 +1720,815 @@ async function readTextOrUndefined3(filePath) {
     throw err;
   }
 }
-function decideAction2(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";
+function decideAction2(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/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 = path8.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 = path8.join(repoRoot, AGENTS_MD_ARTIFACT_PATH);
+  const text2 = await readTextOrUndefined4(filePath);
+  if (!text2) return void 0;
+  return extractMarkdownRegion(text2)?.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",
+  label: "Generic AGENTS.md",
+  artifactPaths: [AGENTS_MD_ARTIFACT_PATH],
+  writerKey: "agents-md",
+  write: writeAgentsMd,
+  readInstalledVersion: readAgentsMdInstalledVersion
+};
+
+// src/core/skill/targets/index.ts
+var REGISTRY2 = [
+  claudeCodeTarget,
+  codexTarget,
+  cursorTarget,
+  genericTarget
+];
+function listSkillTargets() {
+  return REGISTRY2;
+}
+function getTarget(id) {
+  const found = REGISTRY2.find((t) => t.id === id);
+  if (!found) {
+    throw new Error(
+      `Unknown skill target '${id}'. Supported: ${REGISTRY2.map((t) => t.id).join(", ")}`
+    );
+  }
+  return found;
+}
+function dedupeTargets(targets) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const target of targets) {
+    const existing = groups.get(target.writerKey);
+    if (existing) {
+      existing.ids.push(target.id);
+      existing.labels.push(target.label);
+    } else {
+      groups.set(target.writerKey, {
+        writerKey: target.writerKey,
+        primary: target,
+        ids: [target.id],
+        labels: [target.label],
+        artifactPaths: target.artifactPaths
+      });
+    }
+  }
+  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(path8.join(repoRoot, MCP_FILE), launch);
+}
+async function writeJsonMcpFile(filePath, launch) {
+  await promises.mkdir(path8.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(text2) {
+  if (!text2 || text2.trim().length === 0) return {};
+  const parsed = JSON.parse(text2);
+  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 = path8.join(".codex", "config.toml");
+function maesterBlock(repoRoot, launch) {
+  return { command: launch.command, args: [...launch.args], cwd: repoRoot };
+}
+async function writeCodexMcpEntry(repoRoot, options = {}) {
+  const filePath = path8.join(repoRoot, CONFIG_FILE);
+  await promises.mkdir(path8.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 = path8.join(".cursor", "mcp.json");
+async function writeCursorMcpEntry(repoRoot, options = {}) {
+  const launch = options.launch ?? resolveMaesterLaunchCommand();
+  return writeJsonMcpFile(path8.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)
+    };
+  }
+}
+
+// src/cli/commands/connector.ts
+var EXIT_OK = 0;
+var EXIT_FALLBACK_FAILURE = 1;
+var EXIT_INVOCATION_ERROR = 2;
+function registerConnector(program, getContext) {
+  const group2 = program.command("connector").description(
+    "Manage citadel connectors (traveling maesters) and dispatch operations for non-MCP agents."
+  );
+  group2.command("list").description("Print the configured connectors and the tool names the MCP server exposes.").action(async () => {
+    process.exitCode = await runList(getContext());
+  });
+  group2.command("add").description(
+    "Register a new connector with this citadel. Interactive when no flags are passed."
+  ).option("--type <type>", "Connector type identifier (e.g. gitlab-issues).").option("--name <name>", "Unique connector name (kebab-case slug).").option("--env-var <name>", "Environment variable that holds the connector's auth token.").option(
+    "--config <json>",
+    "Per-type config as a JSON string. Required when --type is supplied."
+  ).option(
+    "--description <text>",
+    "Optional short description (prepended to MCP tool descriptions)."
+  ).action(async (options) => {
+    process.exitCode = await runAdd(getContext(), options);
+  });
+  group2.command("remove <name>").description("Remove the named connector from citadel.yaml and refresh per-host MCP entries.").option("--yes", "Skip the confirmation prompt.").action(async (name, options) => {
+    process.exitCode = await runRemove(getContext(), name, options.yes === true);
+  });
+  group2.command("refresh").description(
+    "Re-validate citadel.yaml and refresh per-host MCP registrations. Use this after editing citadel.yaml by hand."
+  ).action(async () => {
+    process.exitCode = await runRefresh(getContext());
+  });
+  group2.command("exec <name> <operation> [args...]").description(
+    "Fallback dispatch for non-MCP agent hosts. Invokes the named operation; prints the JSON envelope on stdout."
+  ).allowUnknownOption(true).action(async (name, operation, args) => {
+    process.exitCode = await runExec(getContext(), name, operation, args);
+  });
+}
+async function runList(ctx) {
+  let connectors;
+  try {
+    connectors = await listConnectorsFromCitadel(ctx.repoRoot.path);
+  } catch (err) {
+    return handleCitadelLoadError(ctx, err);
+  }
+  if (connectors.length === 0) {
+    ctx.prompts.log.info("No connectors configured. Add one with `maester connector add`.");
+    return EXIT_OK;
+  }
+  for (const c of connectors) {
+    const tools = toolNamesFor(c);
+    const lines = [`\u2022 ${c.name} (type: ${c.type})`];
+    for (const t of tools) {
+      lines.push(`    ${t}`);
+    }
+    process.stdout.write(`${lines.join("\n")}
+`);
+  }
+  return EXIT_OK;
+}
+async function runAdd(ctx, options) {
+  const isFlagDriven = Boolean(options.type || options.name);
+  if (isFlagDriven) {
+    return runAddFlagDriven(ctx, options);
+  }
+  return runAddInteractive(ctx);
+}
+async function runAddFlagDriven(ctx, options) {
+  if (!options.type) {
+    ctx.logger.error("--type is required when running connector add non-interactively.");
+    return EXIT_INVOCATION_ERROR;
+  }
+  if (!options.name) {
+    ctx.logger.error("--name is required when running connector add non-interactively.");
+    return EXIT_INVOCATION_ERROR;
+  }
+  if (!SLUG_RE.test(options.name)) {
+    ctx.logger.error(`--name must be kebab-case (matched ${SLUG_RE}).`);
+    return EXIT_INVOCATION_ERROR;
+  }
+  if (!hasConnectorType(options.type)) {
+    const known = listConnectorTypes().map((t) => t.id);
+    ctx.logger.error(
+      `Unknown connector type '${options.type}'.${known.length > 0 ? ` Known types: ${known.join(", ")}` : " No types are registered in this build."}`
+    );
+    return EXIT_INVOCATION_ERROR;
+  }
+  if (options.envVar && !ENV_VAR_RE.test(options.envVar)) {
+    ctx.logger.error("--env-var must be UPPER_SNAKE_CASE (matched ^[A-Z][A-Z0-9_]*$).");
+    return EXIT_INVOCATION_ERROR;
+  }
+  let parsedConfig = {};
+  if (options.config) {
+    try {
+      parsedConfig = JSON.parse(options.config);
+    } catch (err) {
+      ctx.logger.error(
+        `--config must be valid JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return EXIT_INVOCATION_ERROR;
+    }
+  }
+  const connector = {
+    name: options.name,
+    type: options.type,
+    ...options.description ? { description: options.description } : {},
+    ...options.envVar ? { auth: { type: "token", envVar: options.envVar } } : {},
+    config: parsedConfig
+  };
+  return writeAddAndRefresh(ctx, connector);
+}
+async function runAddInteractive(ctx) {
+  const types = listConnectorTypes();
+  if (types.length === 0) {
+    ctx.prompts.log.warning(
+      "No connector types are registered in this build of maester. Cannot add a connector interactively."
+    );
+    return EXIT_INVOCATION_ERROR;
+  }
+  try {
+    const typeId = await ctx.prompts.select({
+      message: "Connector type",
+      options: types.map((t) => ({ value: t.id, label: t.label }))
+    });
+    const name = await ctx.prompts.text({
+      message: "Connector name (unique slug)",
+      validate: (v) => SLUG_RE.test(v) ? void 0 : "Must be a kebab-case slug."
+    });
+    const description = await ctx.prompts.text({
+      message: "Optional description (press enter to skip)",
+      initialValue: ""
+    });
+    const envVar = await ctx.prompts.text({
+      message: "Auth env var name (press enter to skip if no auth required)",
+      initialValue: "",
+      validate: (v) => !v || ENV_VAR_RE.test(v) ? void 0 : "Must be UPPER_SNAKE_CASE."
+    });
+    const configJson = await ctx.prompts.text({
+      message: "Per-type config (JSON)",
+      initialValue: "{}",
+      validate: (v) => {
+        try {
+          JSON.parse(v);
+          return void 0;
+        } catch (e) {
+          return e instanceof Error ? e.message : String(e);
+        }
+      }
+    });
+    const connector = {
+      name,
+      type: typeId,
+      ...description ? { description } : {},
+      ...envVar ? { auth: { type: "token", envVar } } : {},
+      config: JSON.parse(configJson)
+    };
+    return writeAddAndRefresh(ctx, connector);
+  } catch (err) {
+    if (err instanceof PromptCancelledError) {
+      ctx.prompts.outro("Cancelled \u2014 no connector added.");
+      return EXIT_INVOCATION_ERROR;
+    }
+    throw err;
+  }
+}
+async function writeAddAndRefresh(ctx, connector) {
+  try {
+    const result = await addConnectorToCitadel(ctx.repoRoot.path, connector);
+    ctx.prompts.log.success(`Wrote connector '${connector.name}' to ${result.filePath}.`);
+    if (result.config.sources.some((s) => s.name === connector.name)) {
+      ctx.prompts.log.warning(
+        `Connector '${connector.name}' shadows a source with the same name. The two namespaces are separate but reading citadel.yaml may confuse future maintainers.`
+      );
+    }
+    const refreshOutcomes = await refreshMcpRegistrations(ctx.repoRoot.path);
+    reportRefresh(ctx, refreshOutcomes);
+    return EXIT_OK;
+  } catch (err) {
+    return handleCitadelLoadError(ctx, err);
+  }
+}
+async function runRemove(ctx, name, yes) {
+  if (!yes) {
+    try {
+      const confirmed = await ctx.prompts.confirm({
+        message: `Remove connector '${name}' from citadel.yaml?`,
+        initialValue: false
+      });
+      if (!confirmed) {
+        ctx.prompts.outro("Cancelled \u2014 citadel.yaml not modified.");
+        return EXIT_OK;
+      }
+    } catch (err) {
+      if (err instanceof PromptCancelledError) {
+        ctx.prompts.outro("Cancelled.");
+        return EXIT_OK;
+      }
+      throw err;
+    }
+  }
+  try {
+    const result = await removeConnectorFromCitadel(ctx.repoRoot.path, name);
+    ctx.prompts.log.success(`Removed connector '${name}' from ${result.filePath}.`);
+    const refreshOutcomes = await refreshMcpRegistrations(ctx.repoRoot.path);
+    reportRefresh(ctx, refreshOutcomes);
+    return EXIT_OK;
+  } catch (err) {
+    if (err instanceof ConnectorNotFoundError) {
+      ctx.logger.error(err.message);
+      return EXIT_INVOCATION_ERROR;
+    }
+    return handleCitadelLoadError(ctx, err);
+  }
+}
+async function runRefresh(ctx) {
+  let config;
+  try {
+    config = await loadCitadelConfig(ctx.repoRoot.path);
+  } catch (err) {
+    return handleCitadelLoadError(ctx, err);
+  }
+  const count = config.connectors?.length ?? 0;
+  ctx.prompts.log.info(
+    count === 0 ? "citadel.yaml has no connectors. Refreshing per-host MCP entries anyway so the maester server stays registered." : `citadel.yaml lists ${count} connector${count === 1 ? "" : "s"}. Refreshing per-host MCP entries.`
+  );
+  const outcomes = await refreshMcpRegistrations(ctx.repoRoot.path);
+  reportRefresh(ctx, outcomes);
+  return EXIT_OK;
+}
+async function runExec(ctx, name, operation, rawArgs) {
+  let config;
+  try {
+    config = await loadCitadelConfig(ctx.repoRoot.path);
+  } catch (err) {
+    return handleCitadelLoadError(ctx, err);
+  }
+  const connector = (config.connectors ?? []).find((c) => c.name === name);
+  if (!connector) {
+    ctx.logger.error(`No connector named '${name}' is configured in citadel.yaml.`);
+    return EXIT_INVOCATION_ERROR;
+  }
+  let args;
+  try {
+    args = parseExecArgs(rawArgs);
+  } catch (err) {
+    ctx.logger.error(err instanceof Error ? err.message : String(err));
+    return EXIT_INVOCATION_ERROR;
+  }
+  const envelope = await invokeOperation({
+    connector,
+    operationName: operation,
+    args
+  });
+  process.stdout.write(`${JSON.stringify(envelope)}
+`);
+  return envelope.ok ? EXIT_OK : EXIT_FALLBACK_FAILURE;
+}
+function parseExecArgs(raw) {
+  const args = {};
+  let i = 0;
+  while (i < raw.length) {
+    const token = raw[i];
+    if (token === void 0) {
+      i += 1;
+      continue;
+    }
+    if (!token.startsWith("--")) {
+      throw new Error(`Unexpected positional argument '${token}'. Use --key value form.`);
+    }
+    const eqIndex = token.indexOf("=");
+    let key;
+    let value;
+    if (eqIndex >= 0) {
+      key = token.slice(2, eqIndex);
+      value = token.slice(eqIndex + 1);
+      i += 1;
+    } else {
+      key = token.slice(2);
+      const next = raw[i + 1];
+      if (next === void 0 || next.startsWith("--")) {
+        value = true;
+        i += 1;
+      } else {
+        value = next;
+        i += 2;
+      }
+    }
+    const existing = args[key];
+    if (existing === void 0) {
+      args[key] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      args[key] = [existing, value];
+    }
+  }
+  return args;
+}
+function reportRefresh(ctx, outcomes) {
+  if (outcomes.length === 0) {
+    ctx.prompts.log.info(
+      "No MCP-capable Grand Maester targets installed \u2014 skipping MCP config refresh."
+    );
+    return;
+  }
+  for (const o of outcomes) {
+    if (o.action === "failed") {
+      ctx.prompts.log.error(`MCP refresh failed for ${o.host}${o.error ? `: ${o.error}` : ""}`);
+    } else {
+      ctx.prompts.log.success(`MCP entry ${o.action} \u2192 ${o.filePath}`);
+    }
+  }
+  ctx.prompts.log.info(
+    "Restart your agent session to pick up the new tool surface (most host platforms restart MCP servers automatically when their config changes)."
+  );
+}
+function handleCitadelLoadError(ctx, err) {
+  if (err instanceof ConfigError) {
+    ctx.logger.error(err.message);
+    return EXIT_INVOCATION_ERROR;
+  }
+  if (err instanceof MaesterError) {
+    ctx.logger.error(err.message);
+    return EXIT_INVOCATION_ERROR;
+  }
+  throw err;
+}
+function toolNamesFor(connector) {
+  if (!hasConnectorType(connector.type)) {
+    return [`(unregistered type: ${connector.type})`];
+  }
+  const type = listConnectorTypes().find((t) => t.id === connector.type);
+  if (!type) return [];
+  return Object.values(type.operations).map((op) => toolName(connector.name, op.name));
+}
+async function appendMissingGitignoreEntries(repoRoot, entries) {
+  const path9 = resolve(repoRoot, ".gitignore");
+  let existing = "";
+  if (existsSync(path9)) {
+    existing = await readFile(path9, "utf8");
+  }
+  const existingLines = new Set(
+    existing.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0)
+  );
+  const added = [];
+  const alreadyPresent = [];
+  for (const entry of entries) {
+    const normalized = entry.trim();
+    if (normalized.length === 0) continue;
+    if (existingLines.has(normalized)) {
+      alreadyPresent.push(normalized);
+    } else {
+      added.push(normalized);
+      existingLines.add(normalized);
+    }
+  }
+  if (added.length === 0) {
+    return { added, alreadyPresent };
+  }
+  const needsTrailingNewline = existing.length > 0 && !existing.endsWith("\n");
+  const appendBlock = `${needsTrailingNewline ? "\n" : ""}${added.join("\n")}
+`;
+  await writeFile(path9, `${existing}${appendBlock}`, "utf8");
+  return { added, alreadyPresent };
+}
+async function ensureScript(repoRoot, scriptName, command) {
+  const path9 = resolve(repoRoot, "package.json");
+  if (!existsSync(path9)) {
+    return { added: false, reason: "no-package-json" };
+  }
+  const raw = await readFile(path9, "utf8");
+  const trailingNewline = raw.endsWith("\n");
+  const parsed = JSON.parse(raw);
+  const scripts = parsed.scripts ?? {};
+  if (scripts[scriptName] === command) {
+    return { added: false, reason: "already-set" };
+  }
+  if (typeof scripts[scriptName] === "string" && scripts[scriptName] !== command) {
+    return { added: false, reason: "already-set" };
+  }
+  scripts[scriptName] = command;
+  parsed.scripts = scripts;
+  const serialized = JSON.stringify(parsed, null, 2) + (trailingNewline ? "\n" : "");
+  await writeFile(path9, serialized, "utf8");
+  return { added: true, reason: "added" };
+}
+
+// src/core/init/finalize.ts
+async function finalizeCitadel(repoRoot, input) {
+  detectDestinationCollisions(repoRoot, input);
+  const config = {
+    schemaVersion: 1,
+    ...input.baseDir ? { baseDir: input.baseDir } : {},
+    sources: input.sources,
+    ...input.connectors && input.connectors.length > 0 ? { connectors: input.connectors } : {}
+  };
+  const citadelPath = await writeCitadelConfig(repoRoot, config);
+  const gitignore = await appendMissingGitignoreEntries(repoRoot, [`${CACHE_DIR_NAME}/`]);
+  const script = await ensureScript(repoRoot, "maester:sync", "maester sync");
+  return {
+    citadelPath,
+    gitignoreAdded: gitignore.added,
+    packageJsonScript: script.reason
+  };
+}
+function detectDestinationCollisions(repoRoot, input, baseDirArg) {
+  const baseDir = Array.isArray(input) ? baseDirArg : input.baseDir;
+  const entries = Array.isArray(input) ? input : input.sources.map((s) => ({ name: s.name, destination: s.destination }));
+  const byDest = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const dest = entry.destination ? resolve(repoRoot, entry.destination) : defaultDestinationFor(repoRoot, entry.name, baseDir);
+    const prior = byDest.get(dest);
+    if (prior) {
+      throw new Error(
+        `sources '${entry.name}' and '${prior.name}' both resolve to destination '${dest}'. Set a unique destination for one of them.`
+      );
+    }
+    byDest.set(dest, { name: entry.name });
+  }
+}
+
+// src/core/init/validators.ts
+function validateSourceName(value) {
+  if (!value || value.length === 0) return { ok: false, reason: "Name cannot be empty." };
+  if (!SLUG_RE.test(value)) {
+    return {
+      ok: false,
+      reason: "Name must be a kebab-case slug (lowercase letters, digits, and hyphens)."
+    };
+  }
+  return { ok: true };
+}
+function validateGitUrl(value) {
+  if (!value || value.length === 0) return { ok: false, reason: "URL cannot be empty." };
+  if (/\s/.test(value)) return { ok: false, reason: "URL cannot contain whitespace." };
+  if (value.startsWith("https://") || value.startsWith("ssh://") || value.startsWith("file://")) {
+    return { ok: true };
+  }
+  if (/^git@[^\s:]+:\S+$/.test(value)) return { ok: true };
+  return {
+    ok: false,
+    reason: "URL must start with https://, ssh://, file://, or use the git@host:path form."
+  };
+}
+function validateEnvVarName(value) {
+  if (!value || value.length === 0) {
+    return { ok: false, reason: "Environment variable name cannot be empty." };
+  }
+  if (/\s/.test(value)) return { ok: false, reason: "Whitespace is not allowed." };
+  if (!ENV_VAR_RE.test(value)) {
+    return {
+      ok: false,
+      reason: "Environment variable name must be UPPER_SNAKE_CASE (e.g. MAESTER_DOCS_TOKEN)."
+    };
+  }
+  if (value.length >= 32 && !value.includes("_")) {
+    return {
+      ok: true,
+      warning: "That looks unusually long and has no underscores \u2014 make sure you entered the NAME of the env var, not its value."
+    };
+  }
+  return { ok: true };
+}
+function validateDestination(value) {
+  if (!value || value.length === 0) return { ok: true };
+  if (value.startsWith("/"))
+    return { ok: false, reason: "Destination must be repo-relative (no leading '/')." };
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) {
+    return { ok: false, reason: "Destination cannot contain '..' segments." };
+  }
+  return { ok: true };
 }
-
-// src/core/skill/targets/generic.ts
-var genericTarget = {
-  id: "agents-md",
-  label: "Generic AGENTS.md",
-  artifactPaths: [AGENTS_MD_ARTIFACT_PATH],
-  writerKey: "agents-md",
-  write: writeAgentsMd,
-  readInstalledVersion: readAgentsMdInstalledVersion
-};
-
-// src/core/skill/targets/index.ts
-var REGISTRY = [
-  claudeCodeTarget,
-  codexTarget,
-  cursorTarget,
-  genericTarget
-];
-function listSkillTargets() {
-  return REGISTRY;
+function validateBaseDir(value) {
+  if (!value || value.length === 0) return { ok: true };
+  if (value.startsWith("/"))
+    return { ok: false, reason: "Base directory must be repo-relative (no leading '/')." };
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) {
+    return { ok: false, reason: "Base directory cannot contain '..' segments." };
+  }
+  return { ok: true };
 }
-function getTarget(id) {
-  const found = REGISTRY.find((t) => t.id === id);
-  if (!found) {
-    throw new Error(
-      `Unknown skill target '${id}'. Supported: ${REGISTRY.map((t) => t.id).join(", ")}`
-    );
+function validateIncludesEntry(value) {
+  if (!value || value.length === 0) return { ok: false, reason: "Includes entry cannot be empty." };
+  if (/^\s+$/.test(value)) return { ok: false, reason: "Includes entry cannot be whitespace." };
+  if (value.startsWith("/")) {
+    return { ok: false, reason: "Includes entry must be repo-relative (no leading '/')." };
   }
-  return found;
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) {
+    return { ok: false, reason: "Includes entry cannot contain '..' segments." };
+  }
+  return { ok: true };
 }
-function dedupeTargets(targets) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const target of targets) {
-    const existing = groups.get(target.writerKey);
-    if (existing) {
-      existing.ids.push(target.id);
-      existing.labels.push(target.label);
-    } else {
-      groups.set(target.writerKey, {
-        writerKey: target.writerKey,
-        primary: target,
-        ids: [target.id],
-        labels: [target.label],
-        artifactPaths: target.artifactPaths
-      });
-    }
+function validateTag(value) {
+  if (!value || value.length === 0) return { ok: false, reason: "Tag cannot be empty." };
+  if (!SLUG_RE.test(value)) {
+    return { ok: false, reason: "Tag must be a kebab-case slug." };
   }
-  return [...groups.values()];
+  return { ok: true };
 }
 
 // package.json
 var package_default = {
-  version: "0.2.1"};
+  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.");
@@ -1206,12 +2556,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 group2 of installedGroups) {
@@ -1252,7 +2604,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 = [];
@@ -1296,25 +2649,25 @@ async function safeWrite(write6, input) {
 }
 async function findInstalledGroups(repoRoot) {
   const targets = listSkillTargets();
-  const installed = [];
+  const installed2 = [];
   for (const target of targets) {
     const installedVersion = await target.readInstalledVersion(repoRoot);
-    if (installedVersion !== void 0) installed.push(target);
+    if (installedVersion !== void 0) installed2.push(target);
   }
-  return dedupeTargets(installed);
+  return dedupeTargets(installed2);
 }
 function countOutcomes(outcomes) {
-  let installed = 0;
+  let installed2 = 0;
   let upgraded = 0;
   let unchanged = 0;
   let failed = 0;
   for (const o of outcomes) {
-    if (o.action === "installed") installed += 1;
+    if (o.action === "installed") installed2 += 1;
     else if (o.action === "upgraded") upgraded += 1;
     else if (o.action === "unchanged") unchanged += 1;
     else if (o.action === "failed") failed += 1;
   }
-  return { installed, upgraded, unchanged, failed };
+  return { installed: installed2, upgraded, unchanged, failed };
 }
 
 // src/cli/commands/init.ts
@@ -1368,8 +2721,9 @@ async function runInit(ctx) {
       ctx.prompts.outro("Cancelled due to destination collision. Re-run when resolved.");
       return 1;
     }
+    const connectors = await collectConnectors(ctx);
     const confirmWrite = await ctx.prompts.confirm({
-      message: `Write ${sources.length} source(s) to citadel.yaml?`,
+      message: `Write ${sources.length} source(s)${connectors.length > 0 ? ` and ${connectors.length} connector(s)` : ""} to citadel.yaml?`,
       initialValue: true
     });
     if (!confirmWrite) {
@@ -1378,7 +2732,8 @@ async function runInit(ctx) {
     }
     const result = await finalizeCitadel(ctx.repoRoot.path, {
       sources,
-      ...baseDir ? { baseDir } : {}
+      ...baseDir ? { baseDir } : {},
+      ...connectors.length > 0 ? { connectors } : {}
     });
     ctx.prompts.log.success(`Wrote ${result.citadelPath}`);
     if (result.gitignoreAdded.length > 0) {
@@ -1557,9 +2912,9 @@ async function collectIncludes(ctx) {
   });
   const paths = parseIncludesEntries(raw);
   const entries = [];
-  for (const path5 of paths) {
+  for (const path9 of paths) {
     const choice = await ctx.prompts.select({
-      message: `State for '${path5}'?`,
+      message: `State for '${path9}'?`,
       initialValue: "file-header",
       options: [
         { value: "draft", label: "draft", hint: "tag this entry as draft" },
@@ -1571,14 +2926,14 @@ async function collectIncludes(ctx) {
         }
       ]
     });
-    entries.push(buildIncludeEntry(path5, choice));
+    entries.push(buildIncludeEntry(path9, choice));
   }
   return entries;
 }
-function buildIncludeEntry(path5, choice) {
-  if (choice === "file-header") return path5;
+function buildIncludeEntry(path9, choice) {
+  if (choice === "file-header") return path9;
   const state = choice;
-  return { path: path5, state };
+  return { path: path9, state };
 }
 async function collectAuth(ctx) {
   const authType = await ctx.prompts.select({
@@ -1645,13 +3000,137 @@ function parseIncludesEntries(raw) {
 function parseTagsEntries(raw) {
   return raw.split(/[,\s]+/).map((entry) => entry.trim()).filter((entry) => entry.length > 0);
 }
+async function collectConnectors(ctx) {
+  const types = listConnectorTypes();
+  if (types.length === 0) {
+    return [];
+  }
+  ctx.prompts.log.info(
+    `${types.length} connector type(s) available, but interactive registration during init is wired in a follow-on feature. Use \`maester connector add\` after init.`
+  );
+  return [];
+}
+var installed = false;
+function setupStdioForMcp() {
+  if (installed) return;
+  installed = true;
+  const logger = consola;
+  if (typeof logger.setReporters === "function") {
+    logger.setReporters([
+      {
+        log(logObj) {
+          const text2 = formatConsolaLogObj(logObj);
+          process.stderr.write(text2);
+        }
+      }
+    ]);
+  }
+}
+function formatConsolaLogObj(logObj) {
+  const prefix = logObj.type ? `[${logObj.type}] ` : "";
+  const body = (logObj.args ?? []).map((arg) => typeof arg === "string" ? arg : JSON.stringify(arg)).join(" ");
+  return `${prefix}${body}
+`;
+}
+
+// src/core/mcp/server.ts
+var MCP_SERVER_NAME = "maester";
+async function bootMcpServer(repoRoot, serverVersion) {
+  setupStdioForMcp();
+  let citadelConfig;
+  try {
+    citadelConfig = await loadCitadelConfig(repoRoot);
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      return { ok: false, exitCode: 2, message: err.message };
+    }
+    return {
+      ok: false,
+      exitCode: 2,
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+  let tools;
+  try {
+    tools = listConnectorTools(citadelConfig);
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: 2,
+      message: err instanceof Error ? `Failed to build connector tool surface: ${err.message}` : String(err)
+    };
+  }
+  const server = new Server(
+    { name: MCP_SERVER_NAME, version: serverVersion },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const requestedName = request.params.name;
+    const args = request.params.arguments ?? {};
+    const match = findOperationByToolName(citadelConfig, requestedName);
+    let envelope;
+    if (!match) {
+      const failure = {
+        connector: requestedName.split("__")[0] ?? requestedName,
+        operation: requestedName.split("__").slice(1).join("__") || "(unknown)",
+        code: "unknown-operation",
+        message: `No tool named '${requestedName}' is registered. Run \`maester connector list\` to see configured tools.`
+      };
+      envelope = buildFailureEnvelope(failure);
+    } else {
+      envelope = await invokeOperation({
+        connector: match.connector,
+        operationName: match.operationName,
+        args
+      });
+    }
+    const text2 = JSON.stringify(envelope);
+    if (envelope.ok) {
+      return {
+        content: [{ type: "text", text: text2 }]
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: "text", text: text2 }]
+    };
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return { ok: true, toolCount: tools.length, server };
+}
+
+// src/cli/commands/mcp.ts
+function registerMcp(program, getContext) {
+  program.command("mcp").description(
+    "Run the stdio MCP server for this citadel. Intended to be spawned by an agent host (Claude Code, Cursor, Codex CLI) via project-level MCP config."
+  ).action(async () => {
+    process.exitCode = await runMcpCommand(getContext());
+  });
+}
+async function runMcpCommand(ctx) {
+  const result = await bootMcpServer(ctx.repoRoot.path, PACKAGE_VERSION);
+  if (!result.ok) {
+    process.stderr.write(`maester mcp: ${result.message}
+`);
+    return result.exitCode;
+  }
+  return 0;
+}
 
 // src/core/publish/finalize.ts
 async function finalizeMaesterManifest(repoRoot, documents) {
   detectDuplicatePaths(documents);
   const config = { schemaVersion: 1, documents };
-  const path5 = await writeMaesterConfig(repoRoot, config);
-  return { maesterPath: path5, documentCount: documents.length };
+  const path9 = await writeMaesterConfig(repoRoot, config);
+  return { maesterPath: path9, documentCount: documents.length };
 }
 function detectDuplicatePaths(documents) {
   const seen = /* @__PURE__ */ new Map();
@@ -1702,6 +3181,25 @@ function parseTags(value) {
 }
 
 // src/cli/commands/publish.ts
+function buildPublishedDocumentStateField(choice) {
+  if (choice === "file-header") return {};
+  return { state: choice };
+}
+async function askDocumentState(ctx, path9) {
+  return ctx.prompts.select({
+    message: `State for '${path9}'?`,
+    initialValue: "file-header",
+    options: [
+      { value: "draft", label: "draft", hint: "tag this entry as draft" },
+      { value: "canon", label: "canon", hint: "tag this entry as canon" },
+      {
+        value: "file-header",
+        label: "file header",
+        hint: "no rule; defer to inline state in the file"
+      }
+    ]
+  });
+}
 function registerPublish(program, getContext) {
   program.command("publish").description("Configure this repository as a maester (walkthrough).").action(async () => {
     await runPublish(getContext());
@@ -1725,7 +3223,12 @@ async function runPublish(ctx) {
       initialValue: true
     });
     if (useReadme) {
-      documents.push({ path: "README.md", category: "readme" });
+      const stateChoice = await askDocumentState(ctx, "README.md");
+      documents.push({
+        path: "README.md",
+        category: "readme",
+        ...buildPublishedDocumentStateField(stateChoice)
+      });
       ctx.prompts.log.success("Added README.md");
     }
   }
@@ -1772,7 +3275,7 @@ async function runPublish(ctx) {
   return 0;
 }
 async function collectOneDocument(ctx, repoRoot, existing) {
-  const path5 = await ctx.prompts.text({
+  const path9 = await ctx.prompts.text({
     message: "Path or glob (relative to the repo root)",
     placeholder: "docs/runbooks/**/*.md",
     validate: (value) => {
@@ -1785,7 +3288,7 @@ async function collectOneDocument(ctx, repoRoot, existing) {
       return void 0;
     }
   });
-  const trimmed = path5.trim();
+  const trimmed = path9.trim();
   if (isGlobPath(trimmed)) {
     const matches = await globby(trimmed, { cwd: repoRoot, dot: false, gitignore: false });
     ctx.prompts.log.info(`Glob matches ${matches.length} file(s) currently.`);
@@ -1794,6 +3297,7 @@ async function collectOneDocument(ctx, repoRoot, existing) {
       ctx.prompts.log.warning(`'${trimmed}' does not yet exist in this repo. Saving anyway.`);
     }
   }
+  const stateChoice = await askDocumentState(ctx, trimmed);
   const description = await ctx.prompts.text({
     message: "Description (optional)",
     placeholder: ""
@@ -1821,130 +3325,24 @@ async function collectOneDocument(ctx, repoRoot, existing) {
     path: trimmed,
     ...trimmedDesc ? { description: trimmedDesc } : {},
     ...trimmedCat ? { category: trimmedCat } : {},
-    ...tags.length > 0 ? { tags } : {}
+    ...tags.length > 0 ? { tags } : {},
+    ...buildPublishedDocumentStateField(stateChoice)
   };
   return doc;
 }
-function isSafeRepoRelative(value) {
-  if (value.length === 0 || /^\s+$/.test(value)) return false;
-  if (value.startsWith("/")) return false;
-  if (value.split(/[\\/]+/).some((seg) => seg === "..")) return false;
-  return true;
-}
-var PublishedDocumentSchema = z.object({
-  path: z.string().min(1).refine(
-    isSafeRepoRelative,
-    "path must be a repo-relative file or glob; no leading '/' and no '..'"
-  ),
-  description: z.string().min(1).optional(),
-  category: z.string().min(1).regex(SLUG_RE, "category must be a kebab-case slug").optional(),
-  tags: z.array(z.string().min(1).regex(SLUG_RE, "tags must be slugs")).optional(),
-  state: StateSchema.optional()
-}).strict();
-var MaesterConfigSchema = z.object({
-  schemaVersion: z.literal(1),
-  documents: z.array(PublishedDocumentSchema).min(1, "at least one published document must be declared").superRefine((docs, ctx) => {
-    const seen = /* @__PURE__ */ new Map();
-    for (let i = 0; i < docs.length; i++) {
-      const p = docs[i]?.path;
-      if (!p) continue;
-      const prior = seen.get(p);
-      if (prior !== void 0) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `duplicate path '${p}' (also at index ${prior})`,
-          path: [i, "path"]
-        });
-      } else {
-        seen.set(p, i);
-      }
-    }
-  })
-}).strict();
-
-// src/core/config/loader.ts
-async function loadCitadelConfig(repoRoot) {
-  const path5 = citadelConfigPath(repoRoot);
-  if (!existsSync(path5)) {
-    throw new ConfigError(
-      "No citadel.yaml found at the repository root. Run `npx maester init` to create one.",
-      { filePath: path5 }
-    );
-  }
-  const raw = await readFile(path5, "utf8");
-  return parseAndValidate(raw, CitadelConfigSchema, path5);
-}
-function parseAndValidate(raw, schema, filePath) {
-  const data = parseYaml(raw, filePath);
-  return runSchema(data, schema, filePath);
-}
-function parseYaml(raw, filePath) {
-  const doc = parseDocument(raw, { keepSourceTokens: false });
-  const yamlErrors = doc.errors;
-  if (yamlErrors.length > 0) {
-    const first = yamlErrors[0];
-    const pos = positionFromError(first, raw);
-    throw new ConfigError(`YAML parse error: ${first.message}`, {
-      filePath,
-      line: pos.line,
-      column: pos.column,
-      cause: first
-    });
-  }
-  return doc.toJS({ maxAliasCount: -1 });
-}
-function runSchema(data, schema, filePath) {
-  const result = schema.safeParse(data);
-  if (!result.success) {
-    const issue = result.error.issues[0];
-    const where = issue?.path?.length ? ` at \`${issue.path.join(".")}\`` : "";
-    throw new ConfigError(`${filePath}: ${issue?.message ?? "validation failed"}${where}`, {
-      filePath,
-      cause: result.error
-    });
-  }
-  return result.data;
-}
-function positionFromError(err, raw) {
-  const pos = err.pos;
-  if (!pos) return { line: 1, column: 1 };
-  const offset = pos[0];
-  let line = 1;
-  let lastLineStart = 0;
-  for (let i = 0; i < offset && i < raw.length; i++) {
-    if (raw[i] === "\n") {
-      line++;
-      lastLineStart = i + 1;
-    }
-  }
-  return { line, column: offset - lastLineStart + 1 };
-}
-
-// src/core/auth/resolver.ts
-function resolveAuth(auth, env = process.env) {
-  if (!auth || auth.type === "none") return { type: "delegated" };
-  const value = env[auth.envVar];
-  if (value === void 0 || value.length === 0) {
-    throw new AuthError(
-      auth.envVar,
-      `${auth.envVar} is not set. Define it in your shell, .env loader, or CI secret manager before syncing.`
-    );
-  }
-  return { type: "token", value };
-}
 var PROVENANCE_FILENAME = ".maester-source.json";
 async function writeProvenanceMarker(destination, marker) {
-  const path5 = resolve(destination, PROVENANCE_FILENAME);
+  const path9 = resolve(destination, PROVENANCE_FILENAME);
   const body = `${JSON.stringify(marker, null, 2)}
 `;
-  await writeFile(path5, body, "utf8");
-  return path5;
+  await writeFile(path9, body, "utf8");
+  return path9;
 }
 async function readProvenanceMarker(destination) {
-  const path5 = resolve(destination, PROVENANCE_FILENAME);
-  if (!existsSync(path5)) return void 0;
+  const path9 = resolve(destination, PROVENANCE_FILENAME);
+  if (!existsSync(path9)) return void 0;
   try {
-    const text2 = await readFile(path5, "utf8");
+    const text2 = await readFile(path9, "utf8");
     const parsed = JSON.parse(text2);
     if (typeof parsed.sourceName !== "string" || typeof parsed.sourceUrl !== "string" || typeof parsed.commitSha !== "string" || !Array.isArray(parsed.filterSet)) {
       return void 0;
@@ -2199,10 +3597,10 @@ function manifestError(name, reason) {
   );
 }
 async function discoverManifestFromCache(cacheDir) {
-  const path5 = resolve(cacheDir, MAESTER_MANIFEST_FILENAME);
-  if (!existsSync(path5)) return { mode: "no-manifest", reason: "absent" };
+  const path9 = resolve(cacheDir, MAESTER_MANIFEST_FILENAME);
+  if (!existsSync(path9)) return { mode: "no-manifest", reason: "absent" };
   try {
-    const raw = await readFile(path5, "utf8");
+    const raw = await readFile(path9, "utf8");
     const doc = parseDocument(raw);
     if (doc.errors.length > 0) return { mode: "no-manifest", reason: "invalid" };
     const parsed = MaesterConfigSchema.safeParse(doc.toJS({ maxAliasCount: -1 }));
@@ -2490,13 +3888,13 @@ function extractTargetPath(envelope, repoRoot) {
   const raw = input.file_path ?? input.path ?? input.pattern;
   if (typeof raw !== "string" || raw.length === 0) return void 0;
   const cwd = typeof envelope.cwd === "string" ? envelope.cwd : repoRoot;
-  return path4.isAbsolute(raw) ? raw : path4.resolve(cwd, raw);
+  return path8.isAbsolute(raw) ? raw : path8.resolve(cwd, raw);
 }
 function isUnderBaseDir(targetPath, repoRoot, baseDir) {
-  const base = path4.resolve(repoRoot, baseDir);
-  const rel = path4.relative(base, targetPath);
+  const base = path8.resolve(repoRoot, baseDir);
+  const rel = path8.relative(base, targetPath);
   if (rel === "") return true;
-  return !rel.startsWith("..") && !path4.isAbsolute(rel);
+  return !rel.startsWith("..") && !path8.isAbsolute(rel);
 }
 function readTtlSeconds(env) {
   const raw = (env ?? process.env).MAESTER_SKILL_STATUS_TTL;
@@ -2507,7 +3905,7 @@ function readTtlSeconds(env) {
 }
 async function readCache(repoRoot) {
   try {
-    const raw = await promises.readFile(path4.join(repoRoot, CACHE_RELATIVE_PATH), "utf8");
+    const raw = await promises.readFile(path8.join(repoRoot, CACHE_RELATIVE_PATH), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null) return void 0;
     const candidate = parsed;
@@ -2524,8 +3922,8 @@ async function readCache(repoRoot) {
   }
 }
 async function writeCache(repoRoot, verdict) {
-  const finalPath = path4.join(repoRoot, CACHE_RELATIVE_PATH);
-  await promises.mkdir(path4.dirname(finalPath), { recursive: true });
+  const finalPath = path8.join(repoRoot, CACHE_RELATIVE_PATH);
+  await promises.mkdir(path8.dirname(finalPath), { recursive: true });
   const tempPath = `${finalPath}.tmp-${Math.floor(Math.random() * 1e9)}`;
   await promises.writeFile(tempPath, `${JSON.stringify(verdict)}
 `, "utf8");
@@ -2560,7 +3958,7 @@ function buildHookResponse(verdict) {
 }
 
 // src/cli/commands/skill.ts
-var EXIT_OK = 0;
+var EXIT_OK2 = 0;
 var EXIT_OUTDATED_OR_BEHIND = 1;
 var EXIT_FAILED = 2;
 var SUPPORTED_IDS = ["claude-code", "codex", "cursor", "agents-md"];
@@ -2619,7 +4017,7 @@ async function runSkillInstallCommand(ctx, flagTargets, mode) {
     }
     if (targets.length === 0) {
       ctx.logger.warning("No targets selected \u2014 nothing to install.");
-      return EXIT_OK;
+      return EXIT_OK2;
     }
   }
   let result;
@@ -2634,7 +4032,7 @@ async function runSkillInstallCommand(ctx, flagTargets, mode) {
     return EXIT_FAILED;
   }
   renderInstallResult(ctx, result, mode);
-  return result.counts.failed > 0 ? EXIT_FAILED : EXIT_OK;
+  return result.counts.failed > 0 ? EXIT_FAILED : EXIT_OK2;
 }
 async function runSkillUpgradeCommand(ctx, check) {
   const baseDir = await loadBaseDir(ctx);
@@ -2648,7 +4046,7 @@ async function runSkillUpgradeCommand(ctx, check) {
   }
   if (result.outcomes.length === 0) {
     ctx.logger.info("No Grand Maester targets are installed. Run `maester skill install` first.");
-    return check ? EXIT_OK : EXIT_OK;
+    return check ? EXIT_OK2 : EXIT_OK2;
   }
   for (const outcome of result.outcomes) {
     renderInstallOutcome(ctx, outcome);
@@ -2670,7 +4068,7 @@ async function runSkillUpgradeCommand(ctx, check) {
   } else {
     ctx.logger.success(`All ${result.outcomes.length} installed target(s) up to date.`);
   }
-  return EXIT_OK;
+  return EXIT_OK2;
 }
 async function runSkillStatusCommand(ctx) {
   const result = await runSkillStatus(ctx.repoRoot.path);
@@ -2686,13 +4084,13 @@ async function runSkillStatusCommand(ctx) {
   }
   if (result.counts.upToDate + result.counts.outdated === 0) return EXIT_FAILED;
   if (result.counts.outdated > 0) return EXIT_OUTDATED_OR_BEHIND;
-  return EXIT_OK;
+  return EXIT_OK2;
 }
 async function runRuntimePrereadCommand(ctx) {
   const stdin = await readAllStdin();
   const out = await runtimePreread(stdin, { repoRoot: ctx.repoRoot.path });
   if (out.length > 0) process.stdout.write(out);
-  return EXIT_OK;
+  return EXIT_OK2;
 }
 async function runRuntimeStatusSummaryCommand(ctx) {
   const { summary, exitCode } = await runtimeStatusSummary({ repoRoot: ctx.repoRoot.path });
@@ -2737,6 +4135,13 @@ function renderInstallResult(ctx, result, mode) {
   for (const outcome of result.outcomes) {
     renderInstallOutcome(ctx, outcome);
   }
+  for (const reg of result.mcpRegistrations) {
+    if (reg.action === "failed") {
+      ctx.logger.error(`MCP refresh failed for ${reg.host}${reg.error ? `: ${reg.error}` : ""}`);
+    } else if (reg.action !== "skipped") {
+      ctx.logger.success(`MCP entry ${reg.action} \u2192 ${reg.filePath}`);
+    }
+  }
   ctx.logger.blank();
   const action = mode === "add-target" ? "Added" : "Installed";
   const total = result.counts.installed + result.counts.upgraded + result.counts.unchanged;
@@ -2893,7 +4298,7 @@ function redactUrl(value) {
 }
 
 // src/cli/commands/status.ts
-var EXIT_OK2 = 0;
+var EXIT_OK3 = 0;
 var EXIT_BEHIND = 1;
 var EXIT_FAILED2 = 2;
 function registerStatus(program, getContext) {
@@ -2941,7 +4346,7 @@ async function runStatusCommand(ctx, scope, concurrency) {
   }
   if (result.counts.failed > 0) return EXIT_FAILED2;
   if (result.counts.behind > 0) return EXIT_BEHIND;
-  return EXIT_OK2;
+  return EXIT_OK3;
 }
 function buildJsonOutcome(outcome) {
   if (outcome.verdict === "up-to-date") {
@@ -3620,11 +5025,11 @@ function formatStateWarning(warning) {
   return `${warning.file}: inline state '${warning.inline}' overrides rule state '${warning.rule}'`;
 }
 function getRepoRoot(start = process.cwd()) {
-  const path5 = resolve(start);
+  const path9 = resolve(start);
   return {
-    path: path5,
-    hasGit: existsSync(resolve(path5, ".git")),
-    hasPackageJson: existsSync(resolve(path5, "package.json"))
+    path: path9,
+    hasGit: existsSync(resolve(path9, ".git")),
+    hasPackageJson: existsSync(resolve(path9, "package.json"))
   };
 }
 
@@ -3693,7 +5098,7 @@ function maybeRenderHelpVersionBanner(argv) {
   const wantsVersion = tail.includes("--version") || tail.includes("-V");
   if (!wantsHelp && !wantsVersion) return;
   const theming = createTheming();
-  const subtitle = wantsVersion ? "v0.1.0 \xB7 living specs" : "living specs \xB7 v0.1.0";
+  const subtitle = wantsVersion ? "v0.4.0 \xB7 living specs" : "living specs \xB7 v0.4.0";
   const banner = bannerForContext(theming, readColumns(), subtitle);
   if (banner.length > 0) {
     process.stdout.write(`${banner}
@@ -3711,8 +5116,10 @@ function toExitCode(value) {
 }
 function buildProgram() {
   const program = new Command();
-  program.name("maester").description("Aggregate documentation from many sources into one citadel.").version("0.1.0", "-V, --version", "Print the maester version.").option("--verbose", "Show verbose output").option("--quiet", "Suppress all output except errors").option("--json", "Emit machine-readable JSON output (one object per line)").option("--color", "Force colored output (overrides auto-detection)").option("--no-color", "Disable colored output (overrides auto-detection)").option("--theme <theme>", "Theme override: 'dark' or 'light'").option("--no-welcome", "Suppress the first-run welcome banner").enablePositionalOptions(false).allowExcessArguments(false);
+  program.name("maester").description("Aggregate documentation from many sources into one citadel.").version("0.4.0", "-V, --version", "Print the maester version.").option("--verbose", "Show verbose output").option("--quiet", "Suppress all output except errors").option("--json", "Emit machine-readable JSON output (one object per line)").option("--color", "Force colored output (overrides auto-detection)").option("--no-color", "Disable colored output (overrides auto-detection)").option("--theme <theme>", "Theme override: 'dark' or 'light'").option("--no-welcome", "Suppress the first-run welcome banner").enablePositionalOptions(false).allowExcessArguments(false);
+  registerConnector(program, () => buildContext(extractFlags(program.opts())));
   registerInit(program, () => buildContext(extractFlags(program.opts())));
+  registerMcp(program, () => buildContext(extractFlags(program.opts())));
   registerPublish(program, () => buildContext(extractFlags(program.opts())));
   registerSkill(program, () => buildContext(extractFlags(program.opts())));
   registerStatus(program, () => buildContext(extractFlags(program.opts())));
@@ -3747,7 +5154,7 @@ async function runNoArgs(ctx) {
   const roles = detectRoles(ctx.repoRoot.path);
   const showWelcome = !roles.hasCitadel && !roles.hasMaester && !ctx.flags.noWelcome;
   if (showWelcome) {
-    const banner = bannerForContext(ctx.theming, readColumns(), "living specs \xB7 v0.1.0");
+    const banner = bannerForContext(ctx.theming, readColumns(), "living specs \xB7 v0.4.0");
     if (banner.length > 0) {
       process.stdout.write(`${banner}