world-building-framework 0.2.1 → 0.2.2

package/README.md

@@ -6,6 +6,10 @@ Build a fictional world as a folder of Markdown files, and publish it as a wiki
 
 You need [Node.js 22](https://nodejs.org/) or newer and git.
 
+**With an AI agent:** in an empty folder, ask it: "Set up a world here with the npm package world-building-framework." It follows the steps in the next section and installs the skills it needs itself.
+
+**By hand:**
+
 ```
 mkdir my-world
 cd my-world
@@ -14,7 +18,7 @@ npx world-building-framework init --agent claude
 npm install
 ```
 
-`init` sets the folder up as a world. `--agent claude` also installs skills for Claude Code. Leave it out if you use another agent; the generated `AGENTS.md` works with any agent.
+`init` sets the folder up as a world. `--agent claude` also installs skills for Claude Code; for another agent, use `--skills-dir <folder>` with the folder that agent reads project skills from. Leave both out if you don't want skills; the generated `AGENTS.md` works with any agent.
 
 `init` never overwrites a file you already have. It creates:
 - `package.json`, with the framework version pinned
@@ -28,7 +32,21 @@ Then put it on GitHub:
 
 1. Create a GitHub repo, commit everything (including `package-lock.json` and `.wbf/managed.json`), and push.
 2. In the repo on GitHub: **Settings → Pages → Source: GitHub Actions**. On a free account, Pages needs the repo to be public.
-3. Every push to your default branch now publishes the wiki to `https://<you>.github.io/<repo>/wiki/`, with a landing page at `https://<you>.github.io/<repo>/`.
+3. Every push to your default branch now publishes the wiki to `https://<you>.github.io/<repo>/wiki/`, with a landing page at `https://<you>.github.io/<repo>/`. To publish without a push, run it by hand: **Actions → Publish wiki → Run workflow**.
+
+You don't enter the URL anywhere; the workflow asks GitHub for it. For a custom domain, set it under **Settings → Pages → Custom domain**; the next run picks it up.
+
+## For AI agents: setting up a world
+
+If a user asks you to set up a world with this package:
+
+1. In the folder they chose (run `git init` first if it isn't a git repo), run `npx world-building-framework init`, adding the option for **your own** skills:
+   - Claude Code: `--agent claude`
+   - any other agent that reads Agent Skills (`SKILL.md`): `--skills-dir <your project skills folder>`, relative to the repo. Only use a folder you know your agent reads; if you don't know one, leave the option out.
+   - Add `--title "<the world's name>"` if the user named it.
+2. Run `npm install`.
+3. Read the generated `AGENTS.md` and, if installed, the `world-vault` skill, then follow them for all further work.
+4. Tell the user the remaining steps from "Then put it on GitHub" above.
 
 ## Writing your world
 
@@ -49,8 +67,31 @@ Then put it on GitHub:
 
 Run `npx wbf` only inside a world folder. Elsewhere it would fetch an unrelated npm package that happens to be called `wbf`.
 
+**With an AI agent that has no terminal (MCP):** see [Agents without a terminal](#agents-without-a-terminal-mcp) below.
+
 **In Obsidian:** open the world folder as a vault to browse and read. Create and change files through `wbf`, so they get valid UUID names and checked links.
 
+## Agents without a terminal (MCP)
+
+Some AI apps can't run commands, but can use tools from an MCP server. `wbf mcp` offers the same functions as the commands above as tools: `schema`, `search`, `read`, `validate`, `create`, `update` and `list_variants`. The app starts the server itself; you only add it to the app's MCP settings once. You need [Node.js 22](https://nodejs.org/) or newer installed.
+
+For Claude Desktop, open **Settings → Developer → Edit Config** and add:
+
+```json
+{
+  "mcpServers": {
+    "my-world": {
+      "command": "npx",
+      "args": ["-y", "world-building-framework@0.2.2", "mcp", "--vault", "C:\\Users\\you\\worlds\\my-world"]
+    }
+  }
+}
+```
+
+- Use the **absolute path** to your world folder, and the framework version from your world's `package.json`, so the app checks files with the same rules as your published wiki. If they differ, the `schema` tool says so.
+- Restart the app afterwards. Other apps use the same `command` and `args`; see their docs for where they go.
+- Setting a world up (`init`, `npm install`) and publishing (commit and push) still happen outside the app, as described above.
+
 ## How a world is organized
 
 - **Files are named by UUID,** e.g. `7c1e9b2a-….md`. The readable name is the `title` field, so two characters can share a name.
@@ -81,6 +122,8 @@ Run `npx wbf` only inside a world folder. Elsewhere it would fetch an unrelated
 
 **Every wiki is public.** Anyone who knows or guesses a variant's address can open it. Variants decide what each wiki contains; they don't lock anything.
 
+**Variants filter whole files.** A file that's included is shown in full, body text and all. Put a secret in its own file with narrower tags rather than in the text of a file everyone sees. A link to a file a wiki leaves out turns into plain text, so its title still shows there.
+
 ## Preview locally
 
 ```
@@ -98,7 +141,7 @@ npm install world-building-framework@latest
 npx wbf refresh
 ```
 
-`refresh` updates the files `init` generated (the workflow, `AGENTS.md`, skills) to the new version. It leaves any file you've edited alone and lists it. `npx wbf init --agent <name>` adds skills for another agent later.
+`refresh` updates the files `init` generated (the workflow, `AGENTS.md`, skills) to the new version. It leaves any file you've edited alone and lists it. `npx wbf init --agent <name>` or `--skills-dir <folder>` adds skills for another agent later; `refresh` keeps those current too.
 
 ## License
 

package/dist/cli/commands/init.d.ts

@@ -5,6 +5,8 @@ export interface InitOptions {
     title?: string;
     /** Agents to install skills for (see AGENT_SKILL_DIRS). */
     agents?: string[];
+    /** Repo-relative folders to install skills into directly, for agents without a shortcut. */
+    skillsDirs?: string[];
     /** Branch the publish workflow runs on; defaults to the git repo's current branch, else "main". */
     branch?: string;
 }

package/dist/cli/commands/init.js

@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { WORLD_CONFIG_FILENAME } from "../../core/config/index.js";
-import { AGENT_SKILL_DIRS, contentHash, readFrameworkVersion, readManifest, renderManagedFiles, writeManifest, writeRepoFile, PACKAGE_ROOT, } from "../managed-files.js";
+import { AGENT_SKILL_DIRS, contentHash, normalizeSkillsDir, readFrameworkVersion, readManifest, renderManagedFiles, writeManifest, writeRepoFile, PACKAGE_ROOT, } from "../managed-files.js";
 const PACKAGE_NAME = "world-building-framework";
 function titleFromFolder(dir) {
     const words = path.basename(path.resolve(dir)).split(/[-_\s]+/).filter(Boolean);
@@ -29,9 +29,11 @@ export async function runInit(options = {}) {
     const agents = [...new Set(options.agents ?? [])];
     for (const agent of agents) {
         if (!AGENT_SKILL_DIRS[agent]) {
-            throw new Error(`Unknown agent "${agent}". Supported: ${Object.keys(AGENT_SKILL_DIRS).join(", ")}`);
+            throw new Error(`Unknown agent "${agent}". Supported: ${Object.keys(AGENT_SKILL_DIRS).join(", ")}. ` +
+                "For another agent, give its project skills folder instead: --skills-dir <folder>");
         }
     }
+    const skillsDirs = [...new Set((options.skillsDirs ?? []).map(normalizeSkillsDir))];
     const version = await readFrameworkVersion();
     const outcome = { dir, created: [], updated: [], skipped: [], nextSteps: [] };
     const exists = (rel) => existsSync(path.join(dir, rel));
@@ -94,6 +96,7 @@ export async function runInit(options = {}) {
     const settings = {
         branch: options.branch ?? previous?.branch ?? detectBranch(dir),
         agents: [...new Set([...(previous?.agents ?? []), ...agents])],
+        skillsDirs: [...new Set([...(previous?.skillsDirs ?? []), ...skillsDirs])],
     };
     const manifest = { frameworkVersion: version, ...settings, files: { ...(previous?.files ?? {}) } };
     for (const [rel, content] of await renderManagedFiles(version, settings)) {
@@ -112,8 +115,9 @@ export async function runInit(options = {}) {
         "Commit everything, including package-lock.json and .wbf/managed.json.",
         "On GitHub: Settings → Pages → Source: GitHub Actions. Then push to publish.",
     ];
-    if (agents.length === 0) {
-        outcome.nextSteps.push(`Optional: install skills for your AI agent with npx wbf init --agent <${Object.keys(AGENT_SKILL_DIRS).join("|")}>.`);
+    if (settings.agents.length === 0 && settings.skillsDirs.length === 0) {
+        outcome.nextSteps.push(`Optional: install skills for your AI agent with npx wbf init --agent <${Object.keys(AGENT_SKILL_DIRS).join("|")}>, ` +
+            "or for any other agent with npx wbf init --skills-dir <its project skills folder>.");
     }
     return outcome;
 }

package/dist/cli/commands/refresh.js

@@ -25,7 +25,11 @@ export async function runRefresh(options = {}) {
         kept: [],
         retired: [],
     };
-    const rendered = await renderManagedFiles(toVersion, { branch: manifest.branch, agents: manifest.agents });
+    const rendered = await renderManagedFiles(toVersion, {
+        branch: manifest.branch,
+        agents: manifest.agents,
+        skillsDirs: manifest.skillsDirs,
+    });
     const files = {};
     for (const [rel, content] of rendered) {
         const newHash = contentHash(content);

package/dist/cli/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { Command } from "commander";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "../mcp/server.js";
 import { runSchema } from "./commands/schema.js";
 import { runInit } from "./commands/init.js";
 import { runRefresh } from "./commands/refresh.js";
@@ -35,9 +37,16 @@ program
     .option("--dir <path>", "folder to set up (default: current folder)")
     .option("--title <title>", "the world's display title (default: derived from the folder name)")
     .option("--agent <name>", "install skills for this AI agent; repeat for several", (value, previous) => [...previous, value], [])
+    .option("--skills-dir <folder>", "install skills into this repo-relative folder, for an agent --agent doesn't know; repeat for several", (value, previous) => [...previous, value], [])
     .option("--branch <name>", "branch the publish workflow runs on (default: the repo's current branch, else main)")
     .action(handle(async (opts) => {
-    const outcome = await runInit({ dir: opts.dir, title: opts.title, agents: opts.agent, branch: opts.branch });
+    const outcome = await runInit({
+        dir: opts.dir,
+        title: opts.title,
+        agents: opts.agent,
+        skillsDirs: opts.skillsDir,
+        branch: opts.branch,
+    });
     console.log(JSON.stringify(outcome, null, 2));
 }));
 program
@@ -154,4 +163,12 @@ program
     });
     console.log(JSON.stringify(outcome, null, 2));
 }));
+program
+    .command("mcp")
+    .description("Run an MCP server over stdio, offering the vault commands as tools to agents without a terminal. Started by the agent's host, not by hand")
+    .option("-v, --vault <path>", "world folder (default: WBF_VAULT_DIR, else the current folder)")
+    .action(handle(async (opts) => {
+    // stdout carries the protocol from here on; nothing else may write to it.
+    await createMcpServer({ vault: opts.vault, version }).connect(new StdioServerTransport());
+}));
 await program.parseAsync(process.argv);

package/dist/cli/managed-files.d.ts

@@ -10,7 +10,17 @@ export declare const AGENT_SKILL_DIRS: Record<string, string>;
 export interface ManagedSettings {
     branch: string;
     agents: string[];
+    /** Skill folders given directly (`--skills-dir`), for agents without a shortcut in AGENT_SKILL_DIRS. Missing in manifests from 0.2.1 and older. */
+    skillsDirs?: string[];
 }
+/**
+ * Checks a `--skills-dir` value and returns it repo-relative with forward
+ * slashes, e.g. ".agent\skills\" -> ".agent/skills". It must stay inside the
+ * repo: no absolute path, no "..".
+ */
+export declare function normalizeSkillsDir(dir: string): string;
+/** Every folder skills get copied into: the agents' known folders plus any given directly, without duplicates. */
+export declare function skillTargets(settings: ManagedSettings): string[];
 /** The record of generated files, kept in the world repo (committed) at MANIFEST_PATH. */
 export interface Manifest extends ManagedSettings {
     frameworkVersion: string;
@@ -27,7 +37,7 @@ export declare function readFrameworkVersion(): Promise<string>;
 /**
  * The files wbf owns in a world repo, rendered for this framework version:
  * the publish workflow, AGENTS.md, and the package's skills copied into each
- * chosen agent's skill folder. Keyed by repo-relative path.
+ * skill folder (see skillTargets). Keyed by repo-relative path.
  */
 export declare function renderManagedFiles(version: string, settings: ManagedSettings): Promise<Map<string, string>>;
 export declare function readManifest(rootDir: string): Promise<Manifest | undefined>;

package/dist/cli/managed-files.js

@@ -13,6 +13,31 @@ export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.
 export const AGENT_SKILL_DIRS = {
     claude: ".claude/skills",
 };
+/**
+ * Checks a `--skills-dir` value and returns it repo-relative with forward
+ * slashes, e.g. ".agent\skills\" -> ".agent/skills". It must stay inside the
+ * repo: no absolute path, no "..".
+ */
+export function normalizeSkillsDir(dir) {
+    if (path.isAbsolute(dir) || /^[a-zA-Z]:/.test(dir)) {
+        throw new Error(`Skills folder "${dir}" must be relative to the world repo, e.g. .agent/skills`);
+    }
+    const parts = dir.split(/[\\/]+/).filter((part) => part !== "" && part !== ".");
+    if (parts.length === 0 || parts.includes("..")) {
+        throw new Error(`Skills folder "${dir}" must be a folder inside the world repo, e.g. .agent/skills`);
+    }
+    return parts.join("/");
+}
+/** Every folder skills get copied into: the agents' known folders plus any given directly, without duplicates. */
+export function skillTargets(settings) {
+    const targets = settings.agents.map((agent) => {
+        const target = AGENT_SKILL_DIRS[agent];
+        if (!target)
+            throw new Error(`Unknown agent "${agent}". Supported: ${Object.keys(AGENT_SKILL_DIRS).join(", ")}`);
+        return target;
+    });
+    return [...new Set([...targets, ...(settings.skillsDirs ?? [])])];
+}
 export const MANIFEST_PATH = ".wbf/managed.json";
 /**
  * Content hash, ignoring line endings: git may check a file out with CRLF on
@@ -44,7 +69,7 @@ async function listFiles(dir, prefix = "") {
 /**
  * The files wbf owns in a world repo, rendered for this framework version:
  * the publish workflow, AGENTS.md, and the package's skills copied into each
- * chosen agent's skill folder. Keyed by repo-relative path.
+ * skill folder (see skillTargets). Keyed by repo-relative path.
  */
 export async function renderManagedFiles(version, settings) {
     const files = new Map();
@@ -52,10 +77,7 @@ export async function renderManagedFiles(version, settings) {
     files.set("AGENTS.md", await template("AGENTS.md", version, settings.branch));
     const skillsDir = path.join(PACKAGE_ROOT, "skills");
     const skillFiles = await listFiles(skillsDir);
-    for (const agent of settings.agents) {
-        const target = AGENT_SKILL_DIRS[agent];
-        if (!target)
-            throw new Error(`Unknown agent "${agent}". Supported: ${Object.keys(AGENT_SKILL_DIRS).join(", ")}`);
+    for (const target of skillTargets(settings)) {
         for (const rel of skillFiles) {
             files.set(`${target}/${rel}`, await readFile(path.join(skillsDir, rel), "utf8"));
         }

package/dist/cli/vault-path.d.ts

@@ -3,5 +3,5 @@
  * that are useful without a vault (e.g. `schema`).
  */
 export declare function findVaultDir(cliOption: string | undefined): string | undefined;
-/** Resolves which vault to operate on: explicit flag, then WBF_VAULT_DIR, then the current folder if it has a world.config.json, then a single directory under ./vaults/. */
+/** Resolves which vault to operate on: explicit flag, then WBF_VAULT_DIR, then the current folder if it has a world.config.json. */
 export declare function resolveVaultDir(cliOption: string | undefined): string;

package/dist/cli/vault-path.js

@@ -1,24 +1,6 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { WORLD_CONFIG_FILENAME } from "../core/config/index.js";
-function findSingleVaultUnderVaultsDir() {
-    const vaultsRoot = path.join(process.cwd(), "vaults");
-    let entries;
-    try {
-        entries = readdirSync(vaultsRoot).filter((name) => {
-            try {
-                return statSync(path.join(vaultsRoot, name)).isDirectory();
-            }
-            catch {
-                return false;
-            }
-        });
-    }
-    catch {
-        return undefined;
-    }
-    return entries.length === 1 ? path.join(vaultsRoot, entries[0]) : undefined;
-}
 /** The current folder, if it's a vault — i.e. it has a world.config.json (the vault repo is the project, see claude-dev/DISTRIBUTION_PLAN.md). */
 function currentFolderIfVault() {
     const cwd = process.cwd();
@@ -29,16 +11,14 @@ function currentFolderIfVault() {
  * that are useful without a vault (e.g. `schema`).
  */
 export function findVaultDir(cliOption) {
-    // The ./vaults/ fallback is the old fork-the-framework layout, kept until the
-    // world-repo layout fully replaces it.
-    return cliOption ?? process.env.WBF_VAULT_DIR ?? currentFolderIfVault() ?? findSingleVaultUnderVaultsDir();
+    return cliOption ?? process.env.WBF_VAULT_DIR ?? currentFolderIfVault();
 }
-/** Resolves which vault to operate on: explicit flag, then WBF_VAULT_DIR, then the current folder if it has a world.config.json, then a single directory under ./vaults/. */
+/** Resolves which vault to operate on: explicit flag, then WBF_VAULT_DIR, then the current folder if it has a world.config.json. */
 export function resolveVaultDir(cliOption) {
     const vaultDir = findVaultDir(cliOption);
     if (!vaultDir) {
-        throw new Error("No vault specified — run this inside a vault (a folder with world.config.json), pass --vault <path>, " +
-            "set WBF_VAULT_DIR, or have exactly one directory under ./vaults/.");
+        throw new Error("No vault specified — run this inside a world (a folder with world.config.json; `wbf init` creates one), " +
+            "pass --vault <path>, or set WBF_VAULT_DIR.");
     }
     return vaultDir;
 }

package/dist/core/vault/read.js

@@ -42,8 +42,12 @@ export async function findVaultFilePath(vaultDir, id) {
 }
 /** Reads and parses one vault file by id. Never validates — see write.ts. */
 export async function readVaultFile(vaultDir, id) {
-    const raw = await readFile(path.join(vaultDir, `${id}.md`), "utf8");
-    return parseVaultFile(id, raw);
+    // Looked up among the vault's UUID-named files, never joined into a path: an
+    // id like "../notes" must not reach a file outside the vault.
+    const filePath = await findVaultFilePath(vaultDir, id);
+    if (!filePath)
+        throw new Error(`No file with id "${id}" in this vault.`);
+    return parseVaultFile(id, await readFile(filePath, "utf8"));
 }
 /**
  * Reads every vault file: UUID-named `.md` files anywhere under vaultDir.

package/dist/mcp/server.d.ts

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * What every agent connecting to the server is told up front: the
+ * world-vault skill's rules (skills/world-vault/SKILL.md), in terms of this
+ * server's tools instead of CLI commands.
+ */
+export declare const MCP_INSTRUCTIONS = "This server reads and writes a world built with the World Building Framework: a vault of entity and event files, named by UUID. Use only these tools to read or change it; they validate everything before it's written.\n\n1. Call `schema` before writing anything. It lists every field, its shape, and an example input.\n2. Call `search` before creating something, to avoid duplicates and to get the UUIDs you link with.\n3. Links are always \"[[<uuid>|<current title>]]\", in frontmatter and in body text. Never a bare [[Name]].\n4. Before `create` or `update`, show the user the frontmatter and body you're about to write, and wait for their go-ahead.\n5. `update` is for corrections only (a typo, a wrong tag, a missing link). Call `read` first and send the file's complete new content: any field you leave out is removed. Changing a title rewrites links showing the old title in other files.\n6. A change in the story is never an update. Create a new entity file with `supersedes` (a link to the entity's latest version) and `causedBy` (a link to the event that caused the change). Other files keep linking to the entity's first file.\n7. Each published wiki (see `list_variants`) includes or leaves out whole files by their tags, and shows an included file in full. Keep secrets in their own files with narrower tags, never in the text of a file a wider audience sees.\n\nErrors in a result block a write; warnings don't, but mention them to the user.";
+export interface McpServerOptions {
+    /** World folder; else WBF_VAULT_DIR, else the server's working folder if it has a world.config.json. */
+    vault?: string;
+    /** This framework's version, reported to clients. */
+    version: string;
+}
+/**
+ * The `wbf mcp` server (claude-dev/DISTRIBUTION_PLAN.md, component 6): the
+ * CLI's vault commands as MCP tools, for agents without a terminal. Each tool
+ * calls the same function as its CLI command; only `read` is extra, since an
+ * agent without a shell can't open a file to prepare an `update`.
+ */
+export declare function createMcpServer(options: McpServerOptions): McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,140 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readVaultFile } from "../core/vault/index.js";
+import { runSchema } from "../cli/commands/schema.js";
+import { runSearch } from "../cli/commands/search.js";
+import { runValidate } from "../cli/commands/validate.js";
+import { runCreate } from "../cli/commands/create.js";
+import { runUpdate } from "../cli/commands/update.js";
+import { loadWorldConfig } from "../core/config/index.js";
+import { findVaultDir, resolveVaultDir } from "../cli/vault-path.js";
+/**
+ * What every agent connecting to the server is told up front: the
+ * world-vault skill's rules (skills/world-vault/SKILL.md), in terms of this
+ * server's tools instead of CLI commands.
+ */
+export const MCP_INSTRUCTIONS = `This server reads and writes a world built with the World Building Framework: a vault of entity and event files, named by UUID. Use only these tools to read or change it; they validate everything before it's written.
+
+1. Call \`schema\` before writing anything. It lists every field, its shape, and an example input.
+2. Call \`search\` before creating something, to avoid duplicates and to get the UUIDs you link with.
+3. Links are always "[[<uuid>|<current title>]]", in frontmatter and in body text. Never a bare [[Name]].
+4. Before \`create\` or \`update\`, show the user the frontmatter and body you're about to write, and wait for their go-ahead.
+5. \`update\` is for corrections only (a typo, a wrong tag, a missing link). Call \`read\` first and send the file's complete new content: any field you leave out is removed. Changing a title rewrites links showing the old title in other files.
+6. A change in the story is never an update. Create a new entity file with \`supersedes\` (a link to the entity's latest version) and \`causedBy\` (a link to the event that caused the change). Other files keep linking to the entity's first file.
+7. Each published wiki (see \`list_variants\`) includes or leaves out whole files by their tags, and shows an included file in full. Keep secrets in their own files with narrower tags, never in the text of a file a wider audience sees.
+
+Errors in a result block a write; warnings don't, but mention them to the user.`;
+function toolResult({ result, failed }) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], ...(failed ? { isError: true } : {}) };
+}
+/** Runs a tool body, turning a thrown error into an error result the agent can read, like the CLI's `{"error": ...}`. */
+async function run(body) {
+    try {
+        return toolResult(await body());
+    }
+    catch (err) {
+        return toolResult({ result: { error: err.message }, failed: true });
+    }
+}
+/** A note when the world pins a different framework version than the one running this server, else undefined. */
+async function versionMismatch(vaultDir, running) {
+    if (!vaultDir)
+        return undefined;
+    try {
+        const pkg = JSON.parse(await readFile(path.join(vaultDir, "package.json"), "utf8"));
+        const pinned = pkg.dependencies?.["world-building-framework"];
+        if (!pinned || pinned === running)
+            return undefined;
+        return `This server runs world-building-framework ${running}, but the world pins ${pinned}. The published wiki is built with ${pinned}, so validation can differ slightly. Update the world (npm install world-building-framework@${running}, then wbf refresh), or start the server at the pinned version.`;
+    }
+    catch {
+        return undefined;
+    }
+}
+const fileInput = {
+    frontmatter: z.record(z.string(), z.unknown()).describe("The file's frontmatter fields. See the schema tool."),
+    body: z.string().optional().describe("Markdown body text. Links inside it use the same [[<uuid>|Title]] form."),
+};
+/**
+ * The `wbf mcp` server (claude-dev/DISTRIBUTION_PLAN.md, component 6): the
+ * CLI's vault commands as MCP tools, for agents without a terminal. Each tool
+ * calls the same function as its CLI command; only `read` is extra, since an
+ * agent without a shell can't open a file to prepare an `update`.
+ */
+export function createMcpServer(options) {
+    const server = new McpServer({ name: "world-building-framework", version: options.version }, { instructions: MCP_INSTRUCTIONS });
+    const vault = options.vault;
+    const readOnly = { readOnlyHint: true, openWorldHint: false };
+    server.registerTool("schema", {
+        title: "Show the file schema",
+        description: "Every frontmatter field with its shape and whether it's required, this world's entityType list, and example inputs for create. Call it before writing anything.",
+        annotations: readOnly,
+    }, () => run(async () => {
+        const text = await runSchema(vault);
+        const note = await versionMismatch(findVaultDir(vault), options.version);
+        return { result: note ? `${text}\n\nNote: ${note}` : text };
+    }));
+    server.registerTool("search", {
+        title: "Search the world",
+        description: "Keyword search over titles, aliases and text. Each result has the file's id (the UUID you link with), title and score, and for entities entityType and tags.",
+        inputSchema: {
+            query: z.string().min(1).describe("Search terms"),
+            tags: z.array(z.string()).optional().describe("Only files carrying all of these tags"),
+            limit: z.number().int().positive().optional().describe("Maximum number of results"),
+        },
+        annotations: readOnly,
+    }, ({ query, tags, limit }) => run(async () => ({ result: await runSearch(vault, query, { tags, limit }) })));
+    server.registerTool("read", {
+        title: "Read a file",
+        description: "One file's id, frontmatter and body. Call it before update, which needs the file's complete new content.",
+        inputSchema: { id: z.string().describe("The file's UUID") },
+        annotations: readOnly,
+    }, ({ id }) => run(async () => {
+        const file = await readVaultFile(resolveVaultDir(vault), id);
+        return { result: { id: file.id, frontmatter: file.frontmatter, body: file.body } };
+    }));
+    server.registerTool("validate", {
+        title: "Validate",
+        description: "Checks without writing anything. With frontmatter (and body): a candidate file, exactly as create would check it. With id: one existing file. With neither: the whole world.",
+        inputSchema: {
+            id: z.string().optional().describe("Check one existing file"),
+            frontmatter: fileInput.frontmatter.optional(),
+            body: fileInput.body,
+        },
+        annotations: readOnly,
+    }, ({ id, frontmatter, body }) => run(async () => {
+        const candidate = frontmatter ? { frontmatter, body } : undefined;
+        const outcome = await runValidate(vault, { id: candidate ? undefined : id, candidate });
+        const valid = Array.isArray(outcome) ? outcome.every((o) => o.valid) : outcome.valid;
+        return { result: outcome, failed: !valid };
+    }));
+    server.registerTool("create", {
+        title: "Create a file",
+        description: "Creates a new entity or event file under a new UUID, after the same checks as validate; on any error nothing is written. Returns the new id. Show the user the content and get their go-ahead first.",
+        inputSchema: fileInput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, ({ frontmatter, body }) => run(async () => {
+        const outcome = await runCreate(vault, { frontmatter, body });
+        return { result: outcome, failed: !outcome.written };
+    }));
+    server.registerTool("update", {
+        title: "Correct a file",
+        description: "Replaces an existing file's whole content, for corrections only; a change in the story is a new version (create with supersedes and causedBy). Call read first and send the complete content: fields you leave out are removed. type can't change. A changed title is also rewritten in other files' links. Show the user the change and get their go-ahead first.",
+        inputSchema: { id: z.string().describe("The file's UUID"), ...fileInput },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, ({ id, frontmatter, body }) => run(async () => {
+        const outcome = await runUpdate(vault, id, { frontmatter, body });
+        return { result: outcome, failed: !outcome.written };
+    }));
+    server.registerTool("list_variants", {
+        title: "List the wikis",
+        description: "The build variants in world.config.json, by name: one published wiki each, e.g. a player wiki and a GM wiki. A file is in a wiki if it carries all of the variant's tags (and, for events, its date is inside the dateRange); {} includes everything. Use it to see which audiences a file's tags reach.",
+        annotations: readOnly,
+    }, () => run(async () => {
+        const config = await loadWorldConfig(resolveVaultDir(vault));
+        return { result: config.buildVariants ?? {} };
+    }));
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "world-building-framework",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Build, search and publish fictional worlds from a vault of Markdown files: the wbf CLI and its core engine.",
   "license": "UNLICENSED",
   "type": "module",
@@ -32,6 +32,7 @@
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "better-sqlite3": "^13.0.3",
     "commander": "^15.0.0",
     "gray-matter": "^4.0.3",

package/skills/world-vault/SKILL.md

@@ -98,3 +98,11 @@ When an event changes something about an entity (it looks different, its status
 Both fields are required together. The vault keeps every version, and the published wiki shows the whole history. Never overwrite an entity file's body to reflect an in-world change; that erases history the vault is designed to keep.
 
 Other files always link to an entity's **original, first-ever** file (its anchor), never to a later version. If you're not sure which id is the anchor, follow the file's `supersedes` chain back. Or reuse whatever id you already have for that entity: that's always the anchor once created.
+
+## 9. Secrets: each wiki shows whole files
+
+A world can publish several wikis (build variants in `world.config.json`, e.g. a player wiki and a GM wiki). They filter by **file**, using its `tags` and, for events, its date. Everything inside a file that's included is shown, body text and all.
+
+- Before writing, check which wikis the file will appear in: compare its `tags` with each variant's `tags` in `world.config.json`.
+- Keep anything meant for fewer readers (a GM secret, a later plot twist) out of files the wider audience sees. Put it in its own file with narrower tags, and link to it from there.
+- A link to a file a wiki leaves out turns into plain text, so its title still shows. Give secret files titles that don't give the secret away.

package/templates/AGENTS.md

@@ -6,6 +6,14 @@ This repo is a world built with the World Building Framework (version __WBF_VERS
 - Run `npx wbf schema` before writing anything, `npx wbf search <terms>` before creating something, and `npx wbf --help` for every command.
 - Never hand-write or hand-edit a vault `.md` file. Only `wbf create` and `wbf update` validate content, and only `create` generates the required UUID filename.
 - Show the user what you're about to write, and wait for their go-ahead, before `create` or `update`.
-- If skills were installed for your agent (`npx wbf init --agent <name>`), the `world-vault` skill has the full workflow.
+
+## Skills
+
+The `world-vault` skill (open Agent Skills format, `SKILL.md`) has the full workflow. If your project skills folder doesn't have it yet, install it for yourself, then tell the user to commit the new files:
+
+- Claude Code: `npx wbf init --agent claude`
+- Any other agent that reads `SKILL.md` skills: `npx wbf init --skills-dir <your project skills folder>`, relative to this repo. Only use a folder you know your agent reads.
+
+`init` only adds what's missing here and never overwrites a file.
 
 Generated by `wbf init`. `npx wbf refresh` keeps it current while it's unedited.