@myna-sh/cli 0.12.1 → 0.13.0

package/dist/main.js

@@ -431,6 +431,45 @@ var ManagementClient = class {
   mutate(method, path, body, query) {
     return this.http.request(method, path, { body, query, idempotencyKey: this.idem() });
   }
+  /**
+   * Escape hatch: call any management endpoint, wrapped or not.
+   *
+   * The typed methods above cover the API, but never all of it at once — a
+   * route ships before its wrapper, or a caller needs a header the wrapper does
+   * not take. Without a documented way around the client, that caller hand-rolls
+   * `fetch` and loses everything this class provides: credential handling,
+   * retry policy, and RFC 9457 errors thrown as `MynaApiError` rather than left
+   * as an opaque body to parse. The escape hatch keeps all of it.
+   *
+   * `path` is version-relative (`/projects/x`), and a leading `/v1` is accepted
+   * and stripped — this is the one method whose paths are written by hand, and
+   * every example a caller copies from the docs carries the prefix.
+   *
+   * Unlike the typed mutations, no idempotency key is generated: sending one
+   * makes a request retry-eligible, and only the caller knows whether replaying
+   * this particular one is safe. Pass `idempotencyKey` to opt in.
+   *
+   * Returns the response envelope untouched — `{ data, pagination }` and all —
+   * because an escape hatch that reshapes the response is not one.
+   */
+  async raw(method, path, options = {}) {
+    const relative = path.startsWith("/v1/") ? path.slice(3) : path.startsWith("/") ? path : `/${path}`;
+    const response = await this.http.requestRaw(method, relative, options);
+    const headers = {};
+    response.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    if (response.status === 204 || response.status === 304) {
+      return { status: response.status, headers, body: void 0 };
+    }
+    const text = await response.text();
+    if (!text) return { status: response.status, headers, body: void 0 };
+    try {
+      return { status: response.status, headers, body: JSON.parse(text) };
+    } catch {
+      return { status: response.status, headers, body: text };
+    }
+  }
   // --- Organizations --------------------------------------------------------
   organizations = {
     list: (signal) => this.get("/organizations", void 0, signal),
@@ -971,6 +1010,24 @@ function readCredentialFile() {
     return {};
   }
 }
+function mcpConfigFile() {
+  return process.env.MYNA_MCP_CONFIG ?? join(configDir(), "mcp.json");
+}
+function readMcpConfig() {
+  try {
+    return JSON.parse(readFileSync(mcpConfigFile(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeMcpConfig(patch) {
+  const next = { ...readMcpConfig(), ...patch };
+  const file = mcpConfigFile();
+  ensureDir(dirname(file));
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  chmodSync(file, 384);
+  return next;
+}
 function resolveContext(flags) {
   const link = findLinkedProject();
   const user = readUserConfig();
@@ -3027,6 +3084,8 @@ var ID_PREFIXES = {
   mcpAuthorizationCode: "mac",
   mcpToken: "mtk",
   deviceAuthorization: "dev",
+  webauthnCredential: "pky",
+  webauthnChallenge: "wac",
   githubInstallation: "ghi",
   projectRepository: "prp"
 };
@@ -4064,9 +4123,671 @@ function registerBilling(program) {
   );
 }
 
+// src/commands/api.ts
+import { readFileSync as readFileSync6 } from "fs";
+var METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+var SAFE = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+function parseTarget(args) {
+  const [first, second] = args;
+  if (!first) throw new UsageError("Provide a path, e.g. `myna api /projects`.");
+  const asMethod = first.toUpperCase();
+  if (METHODS.has(asMethod)) {
+    if (!second) throw new UsageError(`Provide a path after ${asMethod}, e.g. \`myna api ${asMethod} /projects\`.`);
+    return { method: asMethod, path: second };
+  }
+  if (second) {
+    throw new UsageError(
+      `Unknown method "${first}". Expected one of ${[...METHODS].join(", ")}, or a single path argument.`
+    );
+  }
+  return { method: "GET", path: first };
+}
+function parseBody(input) {
+  if (input === void 0) return void 0;
+  const raw = input.startsWith("@") ? readFileSync6(input.slice(1), "utf8") : input;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new UsageError(`Invalid JSON for --data: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function parseHeaders(values) {
+  const headers = {};
+  for (const value of values ?? []) {
+    const colon = value.indexOf(":");
+    if (colon === -1) throw new UsageError(`Invalid --header "${value}". Expected name:value.`);
+    headers[value.slice(0, colon).trim().toLowerCase()] = value.slice(colon + 1).trim();
+  }
+  return headers;
+}
+function registerApi(program) {
+  program.command("api").description("Call a management API endpoint directly, using the resolved credential").argument("<method-or-path>", "HTTP method, or the path when the method is GET").argument("[path]", "request path, e.g. /projects/my-site/entries?collection=posts").option("--data <json>", "request body as inline JSON or @file").option("--header <name:value>", "extra request header (repeatable)", (value, previous = []) => [...previous, value], []).option(
+    "--idempotency-key <key>",
+    "send Idempotency-Key, which also makes the request eligible for automatic retry"
+  ).option("--include", "also report the response status and headers on stderr").action(
+    handle(async (ctx, args, opts) => {
+      const { method, path } = parseTarget(args);
+      const body = parseBody(opts.data);
+      if (body !== void 0 && SAFE.has(method)) {
+        throw new UsageError(`--data cannot be sent with ${method}.`);
+      }
+      const response = await ctx.management().raw(method, path, {
+        headers: parseHeaders(opts.header),
+        ...body !== void 0 ? { body } : {},
+        ...opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}
+      });
+      if (opts.include) {
+        diag(`${response.status}`);
+        for (const [name, value] of Object.entries(response.headers)) diag(`${name}: ${value}`);
+        diag("");
+      }
+      emit(response.body ?? { status: response.status }, () => {
+        process.stdout.write(
+          (response.body === void 0 ? `${response.status} (no content)` : JSON.stringify(response.body, null, 2)) + "\n"
+        );
+      });
+    })
+  );
+}
+
+// src/agent-clients.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname3, join as join9 } from "path";
+var AGENT_CLIENTS = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    dialect: "standard",
+    projectPath: ".mcp.json",
+    userPath: ".claude.json",
+    marker: ".claude"
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    dialect: "standard",
+    projectPath: ".cursor/mcp.json",
+    userPath: ".cursor/mcp.json",
+    marker: ".cursor"
+  },
+  {
+    id: "vscode",
+    label: "VS Code",
+    dialect: "vscode",
+    projectPath: ".vscode/mcp.json",
+    marker: ".vscode"
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    dialect: "standard",
+    userPath: ".codeium/windsurf/mcp_config.json",
+    marker: ".codeium"
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    dialect: "toml",
+    userPath: ".codex/config.toml",
+    marker: ".codex",
+    note: "Codex configuration is TOML; the CLI prints the block to paste rather than editing it."
+  }
+];
+function findClient(id) {
+  const client = AGENT_CLIENTS.find((c) => c.id === id);
+  if (!client) {
+    throw new UsageError(
+      `Unknown client "${id}". Known clients: ${AGENT_CLIENTS.map((c) => c.id).join(", ")}.`
+    );
+  }
+  return client;
+}
+function isDetected(client) {
+  return existsSync7(join9(homedir2(), client.marker));
+}
+function scopesFor(client) {
+  const scopes = [];
+  if (client.projectPath) scopes.push("project");
+  if (client.userPath) scopes.push("user");
+  return scopes;
+}
+function configPath(client, scope, projectRoot) {
+  if (scope === "project") {
+    if (!client.projectPath) {
+      throw new UsageError(
+        `${client.label} has no project-scoped configuration file. Use --scope user.`
+      );
+    }
+    return join9(projectRoot, client.projectPath);
+  }
+  if (!client.userPath) {
+    throw new UsageError(
+      `${client.label} has no user-scoped configuration file. Use --scope project.`
+    );
+  }
+  return join9(homedir2(), client.userPath);
+}
+function serverEntry(client, spec) {
+  if (spec.transport === "http") {
+    return { type: "http", url: spec.url };
+  }
+  const stdio = {
+    command: "npx",
+    args: ["-y", "@myna-sh/mcp"]
+  };
+  if (client.dialect === "vscode") stdio.type = "stdio";
+  if (Object.keys(spec.env).length > 0) stdio.env = spec.env;
+  return stdio;
+}
+function tomlBlock(name, spec) {
+  const lines = [`[mcp_servers.${name}]`];
+  if (spec.transport === "http") {
+    lines.push(`url = ${JSON.stringify(spec.url)}`);
+  } else {
+    lines.push(`command = "npx"`, `args = ["-y", "@myna-sh/mcp"]`);
+    for (const [key, value] of Object.entries(spec.env)) {
+      lines.push(`env.${key} = ${JSON.stringify(value)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function serversKey(client) {
+  return client.dialect === "vscode" ? "servers" : "mcpServers";
+}
+function readDocument(path) {
+  if (!existsSync7(path)) return {};
+  const raw = readFileSync7(path, "utf8");
+  if (raw.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("expected a JSON object");
+    }
+    return parsed;
+  } catch (error) {
+    throw new CliError(
+      `${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}). Fix or move it; refusing to overwrite a file that may hold configuration.`
+    );
+  }
+}
+function existingEntry(client, path, name) {
+  const servers = readDocument(path)[serversKey(client)];
+  if (typeof servers !== "object" || servers === null) return void 0;
+  const entry = servers[name];
+  return typeof entry === "object" && entry !== null ? entry : void 0;
+}
+function writeEntry(client, path, name, entry) {
+  const doc = readDocument(path);
+  const key = serversKey(client);
+  const servers = typeof doc[key] === "object" && doc[key] !== null ? doc[key] : {};
+  servers[name] = entry;
+  doc[key] = servers;
+  mkdirSync4(dirname3(path), { recursive: true });
+  writeFileSync5(path, JSON.stringify(doc, null, 2) + "\n");
+}
+function removeEntry(client, path, name) {
+  if (!existsSync7(path)) return false;
+  const doc = readDocument(path);
+  const key = serversKey(client);
+  const servers = doc[key];
+  if (typeof servers !== "object" || servers === null) return false;
+  const map = servers;
+  if (!(name in map)) return false;
+  delete map[name];
+  writeFileSync5(path, JSON.stringify(doc, null, 2) + "\n");
+  return true;
+}
+
+// src/commands/mcp.ts
+var HOSTED_PATH = "/mcp";
+function resolveTransport(value) {
+  if (value === void 0) return "stdio";
+  if (value === "stdio" || value === "http") return value;
+  throw new UsageError(`--transport must be "stdio" or "http" (got "${String(value)}").`);
+}
+function resolveScope(client, requested) {
+  const supported = scopesFor(client);
+  if (requested === void 0) return supported[0];
+  if (requested !== "project" && requested !== "user") {
+    throw new UsageError(`--scope must be "project" or "user" (got "${String(requested)}").`);
+  }
+  if (!supported.includes(requested)) {
+    throw new UsageError(
+      `${client.label} has no ${requested}-scoped configuration file. Supported: ${supported.join(", ")}.`
+    );
+  }
+  return requested;
+}
+function resolveClients(names) {
+  if (names.length > 0) return names.map(findClient);
+  const detected = AGENT_CLIENTS.filter(isDetected);
+  if (detected.length === 0) {
+    throw new CliError(
+      `No MCP client detected. Name one explicitly: ${AGENT_CLIENTS.map((c) => c.id).join(", ")}.`
+    );
+  }
+  return detected;
+}
+function buildSpec(ctx, transport) {
+  const env = {};
+  if (ctx.apiUrl !== DEFAULT_API_URL2) env.MYNA_API_URL = ctx.apiUrl;
+  if (ctx.organization) env.MYNA_ORGANIZATION = ctx.organization;
+  if (ctx.project) env.MYNA_PROJECT = ctx.project;
+  return { transport, url: `${ctx.apiUrl}${HOSTED_PATH}`, env };
+}
+function registerMcp(program) {
+  const mcp = program.command("mcp").description("Connect coding agents to Myna's MCP server");
+  mcp.command("install").description("Write Myna's MCP server into the configuration of one or more coding agents").argument("[clients...]", "client ids (default: every client detected on this machine)").option("--transport <mode>", "stdio (local server, default) or http (hosted server over OAuth)").option("--scope <scope>", "project or user (default: the most specific the client supports)").option("--name <name>", "server name in the client's configuration", "myna").option("--key <token>", "credential to store for the local server (default: the resolved credential)").option("--no-credential", "do not write ~/.config/myna/mcp.json").option("--dir <dir>", "project root for project-scoped files (default: the linked project or cwd)").option("--print", "show what would be written, and write nothing").option("--force", "replace an existing server entry of the same name").action(
+    handle(async (ctx, args, opts) => {
+      const transport = resolveTransport(opts.transport);
+      const name = opts.name;
+      const root = opts.dir ?? ctx.linkedRoot ?? process.cwd();
+      const clients = resolveClients(args[0] ?? []);
+      const spec = buildSpec(ctx, transport);
+      const dryRun = Boolean(opts.print);
+      const token = transport === "stdio" ? opts.key ?? ctx.token : void 0;
+      if (transport === "stdio" && !token) {
+        throw new CliError(
+          "No credential to give the local MCP server. Run `myna login`, pass --key, or use --transport http."
+        );
+      }
+      const results = [];
+      for (const client of clients) {
+        if (client.dialect === "toml") {
+          results.push({ client: client.id, scope: null, path: client.userPath ?? "", action: "printed", reason: client.note });
+          continue;
+        }
+        const scope = resolveScope(client, opts.scope);
+        const path = configPath(client, scope, root);
+        const entry = serverEntry(client, spec);
+        if (!opts.force && existingEntry(client, path, name)) {
+          results.push({
+            client: client.id,
+            scope,
+            path,
+            action: "skipped",
+            reason: `"${name}" is already configured; pass --force to replace it.`
+          });
+          continue;
+        }
+        if (!dryRun) writeEntry(client, path, name, entry);
+        results.push({ client: client.id, scope, path, action: dryRun ? "printed" : "written" });
+      }
+      let credentialPath;
+      if (token && opts.credential !== false && !dryRun) {
+        const patch = { token };
+        if (ctx.apiUrl !== DEFAULT_API_URL2) patch.apiUrl = ctx.apiUrl;
+        writeMcpConfig(patch);
+        credentialPath = mcpConfigFile();
+      }
+      emit({ transport, name, results, credentialPath: credentialPath ?? null }, () => {
+        for (const r of results) {
+          const where = r.scope ? ` (${r.scope})` : "";
+          process.stdout.write(`${r.action === "written" ? "\u2713" : r.action === "skipped" ? "\u2013" : "\xB7"} ${r.client}${where}: ${r.path}
+`);
+          if (r.reason) process.stdout.write(`    ${r.reason}
+`);
+        }
+        for (const client of clients.filter((c) => c.dialect === "toml")) {
+          process.stdout.write(`
+Add to ~/${client.userPath}:
+
+${tomlBlock(name, spec)}
+`);
+        }
+        if (credentialPath) diag(`
+Credential written to ${credentialPath} (0600).`);
+        if (transport === "stdio" && token && !token.startsWith("myna_sk_")) {
+          diag(
+            "\nThis is your personal credential, so the agent inherits everything you can do.\nPrefer a scoped key: myna keys create --scopes content:read,content:write,assets:read,assets:write,preview:write,schema:read"
+          );
+        }
+        if (dryRun) {
+          diag("\nNothing written (--print).");
+        } else if (results.some((r) => r.action === "written")) {
+          diag("\nRestart the client to pick up the new server.");
+        }
+      });
+    })
+  );
+  mcp.command("list").description("Show known MCP clients, whether they are installed here, and whether Myna is configured").option("--name <name>", "server name to look for", "myna").option("--dir <dir>", "project root for project-scoped files (default: the linked project or cwd)").action(
+    handle(async (ctx, _args, opts) => {
+      const name = opts.name;
+      const root = opts.dir ?? ctx.linkedRoot ?? process.cwd();
+      const rows = AGENT_CLIENTS.map((client) => {
+        const scopes = scopesFor(client);
+        const configured = client.dialect === "toml" ? null : scopes.filter((scope) => existingEntry(client, configPath(client, scope, root), name) !== void 0);
+        return {
+          id: client.id,
+          label: client.label,
+          detected: isDetected(client),
+          scopes,
+          configured
+        };
+      });
+      emit(
+        rows,
+        () => table(rows, [
+          { header: "CLIENT", value: (r) => r.id },
+          { header: "DETECTED", value: (r) => r.detected ? "yes" : "" },
+          { header: "SCOPES", value: (r) => r.scopes.join(", ") },
+          {
+            header: "MYNA",
+            value: (r) => r.configured === null ? "(manual)" : r.configured.length > 0 ? r.configured.join(", ") : ""
+          }
+        ])
+      );
+    })
+  );
+  mcp.command("uninstall").description("Remove Myna's MCP server entry from one or more coding agents").argument("[clients...]", "client ids (default: every client detected on this machine)").option("--scope <scope>", "project or user (default: every scope the client supports)").option("--name <name>", "server name in the client's configuration", "myna").option("--dir <dir>", "project root for project-scoped files (default: the linked project or cwd)").action(
+    handle(async (ctx, args, opts) => {
+      const name = opts.name;
+      const root = opts.dir ?? ctx.linkedRoot ?? process.cwd();
+      const clients = resolveClients(args[0] ?? []);
+      const removed = [];
+      for (const client of clients) {
+        if (client.dialect === "toml") continue;
+        const scopes = opts.scope ? [resolveScope(client, opts.scope)] : scopesFor(client);
+        for (const scope of scopes) {
+          const path = configPath(client, scope, root);
+          if (removeEntry(client, path, name)) removed.push({ client: client.id, scope, path });
+        }
+      }
+      emit({ name, removed }, () => {
+        if (removed.length === 0) {
+          diag(`No "${name}" server entry found.`);
+          return;
+        }
+        for (const r of removed) process.stdout.write(`\u2713 ${r.client} (${r.scope}): ${r.path}
+`);
+        diag(`
+The credential in ${mcpConfigFile()} was left in place. Remove it by hand if nothing else uses it.`);
+      });
+    })
+  );
+}
+
+// src/commands/skills.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join10 } from "path";
+
+// src/skills/index.ts
+function skill(name, description, lines) {
+  return {
+    name,
+    description,
+    // The description is quoted: these sentences contain colons, and a plain
+    // YAML scalar containing ": " is a mapping, not a string. An unquoted one
+    // makes the whole frontmatter block fail to parse.
+    body: ["---", `name: ${name}`, `description: ${JSON.stringify(description)}`, "---", "", ...lines, ""].join("\n")
+  };
+}
+var CHANGE_SETS = skill(
+  "myna-change-sets",
+  "How to write content in Myna: every write is a draft on a change set, validated and previewed before a human publishes it. Use when creating, updating, or deleting entries or assets in Myna.",
+  [
+    "# Writing content in Myna",
+    "",
+    "Myna has one product invariant, and it governs everything below:",
+    "",
+    "> Writes create reviewable drafts on a change set. They never publish implicitly.",
+    "> Validation and preview precede a separately authorized, atomic publish.",
+    "",
+    "There is no way to write directly to published content, and you should not look",
+    "for one. A tool that appears to offer it is staging a draft.",
+    "",
+    "## The workflow",
+    "",
+    "1. **Create a change set.** It is the unit of work \u2014 one coherent edit, however",
+    "   many entries it touches. Give it a title a reviewer can act on.",
+    "2. **Stage the writes.** Create, update, or delete entries and assets against",
+    "   that change set. Each one becomes a draft item on it.",
+    "3. **Validate the whole set.** Not each entry \u2014 the set. Cross-entry problems",
+    "   (a broken reference, a required translation missing) only appear here.",
+    "4. **Create one preview.** One URL covers the entire change set. Creating a",
+    "   preview per entry is a misuse of the API and floods the project's tokens.",
+    "5. **Stop.** Report the change set id and the preview URL, and let a human",
+    "   review it \u2014 unless publishing was explicitly requested *and* your credential",
+    "   holds `content:publish`.",
+    "",
+    "```bash",
+    "myna changes create --set title='Autumn refresh'",
+    "myna entries update posts/welcome --change-set chs_... --set title='New title'",
+    "myna changes validate chs_...",
+    "myna preview create chs_...",
+    "```",
+    "",
+    "The MCP equivalents are `myna_create_change_set`, `myna_update_entry`,",
+    "`myna_validate_change_set`, and `myna_create_preview`.",
+    "",
+    "## Read the collection before you write to it",
+    "",
+    "Collections carry `guidance`: the house style anyone writing into them is",
+    "expected to follow, plus `policy` rules that will fail validation if broken",
+    "(length budgets, required fields, allowed values). Fetch the schema first \u2014",
+    "`myna_get_collection_schema`, or `myna schema get <collection>` \u2014 and follow it.",
+    "A title that busts a length budget fails at validation, not at publish, so",
+    "there is no reason to discover it late.",
+    "",
+    "## Concurrency",
+    "",
+    "- Pass `expectedRevisionId` when updating an entry you have read. Without it,",
+    "  two writers silently overwrite each other; with it, the loser gets a clear",
+    "  conflict.",
+    "- An entry may be staged on several open change sets at once. Yours builds on",
+    "  your change set's own base, not on anyone else's draft.",
+    "- If publish reports `STALE_REVISION`, the entry moved underneath you. Run a",
+    "  rebase (`myna changes rebase`, `myna_rebase_change_set`) \u2014 it performs the",
+    "  three-way merge and re-opens review, because the merged result is not what",
+    "  the reviewer approved. Never work around it by re-staging over the top.",
+    "",
+    "## Deleting",
+    "",
+    "Deletes are staged like any other write, and they need explicit confirmation:",
+    "`--confirm-delete` on the CLI, `confirm: true` on the MCP tool. An unconfirmed",
+    "destructive call is refused, not queued.",
+    "",
+    "## What to report back",
+    "",
+    "The change set id, what it contains, the validation result, and the preview",
+    'URL. Not "published" \u2014 you did not publish.'
+  ]
+);
+var SCHEMA = skill(
+  "myna-schema",
+  "How Myna collection schemas work: code-defined, immutably versioned, deployed with a reviewed diff. Use when adding or changing a collection, field, or generated content types.",
+  [
+    "# Schemas in Myna",
+    "",
+    "Schemas are code. They live in the project's schema directory (`myna/` by",
+    "default), are written with the DSL from `@myna-sh/sdk/schema`, and are deployed",
+    "by pushing a diff \u2014 never edited through a UI, and never edited in the database.",
+    "Every deployed version is immutable; a change creates a new version.",
+    "",
+    "## Changing a schema",
+    "",
+    "```bash",
+    "myna schema diff          # what would change, and how dangerous it is",
+    "myna schema push          # deploy it",
+    "myna types generate       # regenerate the typed client surface",
+    "```",
+    "",
+    "`schema diff` classifies the change. An **additive** diff is safe. A diff that",
+    "removes a field, narrows a type, or changes a key is **destructive** and",
+    "`push` refuses it without `--allow-destructive`. That flag is a statement that",
+    "the data loss is intended \u2014 check what is stored in the affected fields first.",
+    "",
+    "## Drift goes both ways",
+    "",
+    "`myna schema drift` compares the repository against what is deployed. When they",
+    "disagree, decide which one is right before acting:",
+    "",
+    "- the repository is right \u2192 `myna schema push`",
+    "- the deployed schema is right \u2192 `myna schema pull --open-pr`, which brings it",
+    "  back as a reviewable pull request rather than a silent local edit",
+    "",
+    "## Generated types",
+    "",
+    '`myna types generate` writes a file carrying a "do not edit by hand" header.',
+    "Believe the header. Codegen is deterministic, so any hand edit is reverted by",
+    "the next run and `myna doctor` reports the file as stale in the meantime.",
+    "",
+    "## Guidance and policy belong in the schema",
+    "",
+    "If a collection has a rule \u2014 a title budget, a required summary, an allowed set",
+    "of values \u2014 express it as schema `policy` so validation enforces it for every",
+    "writer, human or agent. Do not enforce it in a build script: a build-time gate",
+    "fails after the content is already staged, and only for the one pipeline that",
+    "runs it. A rule that cannot be expressed as policy is a gap in Myna worth",
+    "reporting, not a script worth writing."
+  ]
+);
+var PUBLISHING = skill(
+  "myna-publishing",
+  "How publishing, releases, and reverts work in Myna, and when an agent may publish. Use before publishing a change set, reverting a release, or reading content as of a past release.",
+  [
+    "# Publishing, releases, and reverts",
+    "",
+    "Publishing is a separate, explicitly authorized action. It is atomic over the",
+    "whole change set, and it assigns the set a sequential release number \u2014 that",
+    "number is what makes it a release.",
+    "",
+    "## Before you publish",
+    "",
+    "Do not publish unless **both** are true:",
+    "",
+    '1. The user asked for it, in this task, in so many words. "Update the pricing',
+    '   page" is not a request to publish it.',
+    "2. Your credential holds `content:publish`. Many agent keys deliberately do not,",
+    "   and that is the design working, not an obstacle to route around.",
+    "",
+    "Publishing needs explicit confirmation \u2014 `--confirm-publish` on the CLI,",
+    "`confirm: true` on `myna_publish_change_set` \u2014 and it can still be refused by",
+    "the project's gates:",
+    "",
+    "- a number of required approvals",
+    "- the built-in check suite passing",
+    "- any check the project declared `required`, reported by an outside system",
+    "",
+    "A refused publish is information. Report which gate is unmet; do not try to",
+    "disable the gate.",
+    "",
+    "## Reverting",
+    "",
+    "A revert does not undo anything directly. It generates a **new open change set**",
+    "staging the inverse of every item in the release, which then goes through",
+    "validation, review, and the same publish gates as any other change. It needs",
+    "only `content:write`, because it publishes nothing.",
+    "",
+    "```bash",
+    "myna releases list",
+    "myna releases revert <release>   # creates a change set; review it, then publish",
+    "```",
+    "",
+    "## Reading a past release",
+    "",
+    "The public content API takes `?at=<release>`, which serves a collection exactly",
+    "as that release served it \u2014 including the slug each entry carried at the time.",
+    "Two properties matter when reasoning about it:",
+    "",
+    "- Visibility is read live, never at the pin. Pinning reproduces content, not",
+    "  access decisions: a collection made private since is private now.",
+    "- `?at=` and `?preview=` are mutually exclusive. One reads what shipped, the",
+    "  other what has not. Asking for both is an error rather than a guess.",
+    "",
+    "A site that pins its content sets the release in `myna.lock`, and publishing",
+    "opens a pull request moving that pin. Nothing deploys behind the repository's",
+    "back."
+  ]
+);
+var SKILLS = [CHANGE_SETS, SCHEMA, PUBLISHING];
+
+// src/commands/skills.ts
+function destinations(scope, root, extra) {
+  const home = homedir3();
+  if (scope === "project") {
+    return [
+      { id: "project", dir: join10(root, ".claude", "skills") },
+      ...extra.map((dir, i) => ({ id: `target-${i + 1}`, dir }))
+    ];
+  }
+  return [
+    // The convention Claude Code, Codex, and others now read from.
+    { id: "agents", dir: join10(home, ".agents", "skills") },
+    { id: "claude", dir: join10(home, ".claude", "skills"), requiresExisting: join10(home, ".claude") },
+    ...extra.map((dir, i) => ({ id: `target-${i + 1}`, dir }))
+  ];
+}
+function registerSkills(program) {
+  const skills = program.command("skills").description("Install Myna's agent skills for coding agents");
+  skills.command("install").description("Write Myna's agent skills into the skill directories on this machine").option("--scope <scope>", "user (default) or project", "user").option("--target <dir>", "additional skill directory to write to (repeatable)", (value, previous = []) => [...previous, value], []).option("--dir <dir>", "project root for --scope project (default: the linked project or cwd)").option("--print", "show what would be written, and write nothing").option("--force", "overwrite skill files that have been edited").action(
+    handle(async (ctx, _args, opts) => {
+      const scope = opts.scope;
+      if (scope !== "user" && scope !== "project") {
+        throw new UsageError(`--scope must be "user" or "project" (got "${scope}").`);
+      }
+      const root = opts.dir ?? ctx.linkedRoot ?? process.cwd();
+      const dryRun = Boolean(opts.print);
+      const targets = destinations(scope, root, opts.target ?? []).filter(
+        (d) => !d.requiresExisting || existsSync8(d.requiresExisting)
+      );
+      const results = [];
+      for (const target of targets) {
+        for (const skill2 of SKILLS) {
+          const path = join10(target.dir, skill2.name, "SKILL.md");
+          const current = existsSync8(path) ? readFileSync8(path, "utf8") : void 0;
+          if (current === skill2.body) {
+            results.push({ skill: skill2.name, path, action: "unchanged" });
+            continue;
+          }
+          if (current !== void 0 && !opts.force) {
+            results.push({ skill: skill2.name, path, action: "skipped" });
+            continue;
+          }
+          if (!dryRun) {
+            mkdirSync5(join10(target.dir, skill2.name), { recursive: true });
+            writeFileSync6(path, skill2.body);
+          }
+          results.push({ skill: skill2.name, path, action: "written" });
+        }
+      }
+      const written = results.filter((r) => r.action === "written").length;
+      const skipped = results.filter((r) => r.action === "skipped").length;
+      emit({ scope, written, skipped, results }, () => {
+        if (targets.length === 0) {
+          diag("No skill directory to write to.");
+          return;
+        }
+        for (const r of results) {
+          const icon = r.action === "written" ? "\u2713" : r.action === "unchanged" ? "=" : "\u2013";
+          process.stdout.write(`${icon} ${r.path}
+`);
+        }
+        if (skipped > 0) diag(`
+${skipped} file(s) differ from the bundled version and were left alone. Pass --force to update them.`);
+        diag(dryRun ? "\nNothing written (--print)." : `
+${written} skill file(s) written.`);
+      });
+    })
+  );
+  skills.command("list").description("List the agent skills bundled with this CLI").action(
+    handle(async () => {
+      emit(
+        SKILLS.map((s) => ({ name: s.name, description: s.description })),
+        () => table(SKILLS, [
+          { header: "SKILL", value: (s) => s.name },
+          { header: "DESCRIPTION", value: (s) => s.description.split(". ")[0] + "." }
+        ])
+      );
+    })
+  );
+}
+
 // src/commands/doctor.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync9, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join11 } from "path";
 
 // src/registry.ts
 var NPM_REGISTRY = "https://registry.npmjs.org";
@@ -4105,7 +4826,7 @@ function installCommand(manager, version) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.12.1" : "0.0.0-dev";
+var VERSION = true ? "0.13.0" : "0.0.0-dev";
 var IS_RELEASE_BUILD = true;
 
 // src/commands/doctor.ts
@@ -4279,7 +5000,7 @@ async function checkOrigin(ctx, origin) {
 }
 async function checkSchema(ctx, schemaDir) {
   const dir = schemaDirFor(ctx.linkedRoot, schemaDir);
-  if (!existsSync7(dir)) {
+  if (!existsSync9(dir)) {
     return check("schema.drift", "Local schema", "skip", `No schema directory at ${dir}.`);
   }
   if (!ctx.project) {
@@ -4329,7 +5050,7 @@ function findGeneratedTypes(root, depth = 4) {
   const dirs = [];
   for (const entry of entries) {
     if (SCAN_IGNORE.has(entry) || entry.startsWith(".")) continue;
-    const full = join9(root, entry);
+    const full = join11(root, entry);
     let stats;
     try {
       stats = statSync2(full);
@@ -4342,7 +5063,7 @@ function findGeneratedTypes(root, depth = 4) {
     }
     if (!/\.(ts|d\.ts)$/.test(entry)) continue;
     try {
-      if (looksGenerated(readFileSync6(full, "utf8"))) return full;
+      if (looksGenerated(readFileSync9(full, "utf8"))) return full;
     } catch {
     }
   }
@@ -4359,16 +5080,16 @@ async function checkTypes(ctx, explicit, schemaDir) {
   if (!file) {
     return check("types.freshness", "Generated types", "skip", "No generated types file found.");
   }
-  if (!existsSync7(file)) {
+  if (!existsSync9(file)) {
     return check("types.freshness", "Generated types", "fail", `${file} does not exist.`);
   }
   const dir = schemaDirFor(ctx.linkedRoot, schemaDir);
-  if (!existsSync7(dir)) {
+  if (!existsSync9(dir)) {
     return check("types.freshness", "Generated types", "skip", `Found ${file} but no schema directory to compare against.`);
   }
   try {
     const expected = generateTypesModule(await loadLocalSchemas(dir));
-    return readFileSync6(file, "utf8") === expected ? check("types.freshness", "Generated types", "pass", `${file} matches the local schema.`) : check(
+    return readFileSync9(file, "utf8") === expected ? check("types.freshness", "Generated types", "pass", `${file} matches the local schema.`) : check(
       "types.freshness",
       "Generated types",
       "warn",
@@ -4484,7 +5205,7 @@ function registerUpdate(program) {
 
 // src/commands/sync.ts
 import { readdir as readdir2, stat as stat2 } from "fs/promises";
-import { join as join10 } from "path";
+import { join as join12 } from "path";
 async function isDirectory(path) {
   const info = await stat2(path).catch(() => void 0);
   return Boolean(info?.isDirectory());
@@ -4499,7 +5220,7 @@ async function planDirectories(dir, collection) {
   const plan = [];
   for (const name of children.sort()) {
     if (name.startsWith(".")) continue;
-    const full = join10(dir, name);
+    const full = join12(dir, name);
     if (await isDirectory(full)) plan.push({ collection: name, path: full });
   }
   if (plan.length === 0) {
@@ -4673,6 +5394,9 @@ function buildProgram() {
   registerPull(program);
   registerPreviews(program);
   registerAssets(program);
+  registerMcp(program);
+  registerSkills(program);
+  registerApi(program);
   registerAdmin(program);
   return program;
 }