world-building-framework 0.2.0 → 0.2.2

package/dist/core/query/dates.d.ts

@@ -2,54 +2,18 @@ import { z } from "zod";
 export declare const dateBoundSchema: z.ZodObject<{
     year: z.ZodNumber;
     day: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    year: number;
-    day?: number | undefined;
-}, {
-    year: number;
-    day?: number | undefined;
-}>;
+}, z.core.$strip>;
 export type DateBound = z.infer<typeof dateBoundSchema>;
 export declare const dateRangeQuerySchema: z.ZodObject<{
     from: z.ZodOptional<z.ZodObject<{
         year: z.ZodNumber;
         day: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day?: number | undefined;
-    }, {
-        year: number;
-        day?: number | undefined;
-    }>>;
+    }, z.core.$strip>>;
     to: z.ZodOptional<z.ZodObject<{
         year: z.ZodNumber;
         day: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day?: number | undefined;
-    }, {
-        year: number;
-        day?: number | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    from?: {
-        year: number;
-        day?: number | undefined;
-    } | undefined;
-    to?: {
-        year: number;
-        day?: number | undefined;
-    } | undefined;
-}, {
-    from?: {
-        year: number;
-        day?: number | undefined;
-    } | undefined;
-    to?: {
-        year: number;
-        day?: number | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type DateRangeQuery = z.infer<typeof dateRangeQuerySchema>;
 /** An in-world date, as stored in an event's `date` field. */
 export interface DateTuple {

package/dist/core/query/types.d.ts

@@ -6,70 +6,16 @@ import { z } from "zod";
  * its `buildVariants` entries against — one definition, no separate DSL to parse.
  */
 export declare const buildVariantQuerySchema: z.ZodObject<{
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     dateRange: z.ZodOptional<z.ZodObject<{
         from: z.ZodOptional<z.ZodObject<{
             year: z.ZodNumber;
             day: z.ZodOptional<z.ZodNumber>;
-        }, "strip", z.ZodTypeAny, {
-            year: number;
-            day?: number | undefined;
-        }, {
-            year: number;
-            day?: number | undefined;
-        }>>;
+        }, z.core.$strip>>;
         to: z.ZodOptional<z.ZodObject<{
             year: z.ZodNumber;
             day: z.ZodOptional<z.ZodNumber>;
-        }, "strip", z.ZodTypeAny, {
-            year: number;
-            day?: number | undefined;
-        }, {
-            year: number;
-            day?: number | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        from?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-        to?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-    }, {
-        from?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-        to?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    tags?: string[] | undefined;
-    dateRange?: {
-        from?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-        to?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-    } | undefined;
-}, {
-    tags?: string[] | undefined;
-    dateRange?: {
-        from?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-        to?: {
-            year: number;
-            day?: number | undefined;
-        } | undefined;
-    } | undefined;
-}>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type BuildVariantQuery = z.infer<typeof buildVariantQuerySchema>;

package/dist/core/schema/describe.d.ts

@@ -1,8 +1,34 @@
+/** Example `wbf create` inputs, one per kind. A test validates them, so they can't drift from the schema either. */
+export declare const SCHEMA_EXAMPLES: {
+    entity: {
+        frontmatter: {
+            type: string;
+            entityType: string;
+            title: string;
+            tags: string[];
+            home: string;
+        };
+        body: string;
+    };
+    event: {
+        frontmatter: {
+            type: string;
+            title: string;
+            date: {
+                year: number;
+                day: number;
+            };
+            after: string[];
+            entities: string[];
+        };
+        body: string;
+    };
+};
 /**
- * Prints the live, current schema: field names come straight from the zod
- * schemas in fields.ts, so this can't structurally drift from what
+ * Prints the live, current schema: field names and value shapes come straight
+ * from the zod schemas in fields.ts, so this can't structurally drift from what
  * validateFrontmatter actually enforces. This is what the CLI's `schema`
- * command exposes so Claude always sees the real, current rules — see
+ * command exposes so an agent always sees the real, current rules — see
  * claude-dev/PROJECT_STRUCTURE.md.
  */
 export declare function describeSchema(entityTypeVocabulary?: string[]): string;

package/dist/core/schema/describe.js

@@ -1,45 +1,92 @@
-import { commonFieldsSchema, entityFrontmatterSchema, eventFrontmatterSchema } from "./fields.js";
+import { z } from "zod";
+import { commonFieldsSchema, entityFrontmatterSchema, eventFrontmatterSchema, wikilinkSchema, } from "./fields.js";
 const FIELD_MEANINGS = {
-    type: 'Top-level kind: "entity" or "event".',
-    title: "Human-readable display name (required — filenames are UUIDs, this is the real name).",
+    type: "Top-level kind.",
+    title: "Human-readable display name (filenames are UUIDs, this is the real name).",
     tags: "Project-defined tags used for build-time filtering.",
     aliases: "Alternate names/spellings, for search recall and Obsidian autocomplete only — not used for link resolution.",
     entityType: "Category (e.g. character, location). Lint-checked against this vault's declared vocabulary, if any.",
     supersedes: "Marks this file as a new version of an existing entity — points at the file it replaces.",
     causedBy: "The event responsible for this version existing. Required alongside supersedes, and vice versa.",
     after: "Causal predecessor event(s) — the required ordering/branching backbone.",
-    date: "Optional in-world date anchor: { year, day }.",
+    date: "In-world date anchor. Give both year and day.",
     entities: "The entities this event is tied to.",
 };
-function shapeKeys(schema) {
-    return Object.keys(schema.shape);
+/** Example `wbf create` inputs, one per kind. A test validates them, so they can't drift from the schema either. */
+export const SCHEMA_EXAMPLES = {
+    entity: {
+        frontmatter: {
+            type: "entity",
+            entityType: "character",
+            title: "Alea Marrow",
+            tags: ["player"],
+            home: "[[66a7bd3f-a744-4565-acbe-006957625792|Port Kavas]]",
+        },
+        body: "Captain of the *Gull*.",
+    },
+    event: {
+        frontmatter: {
+            type: "event",
+            title: "The Great Storm",
+            date: { year: 150, day: 200 },
+            after: ["[[bb1ddebd-3a7c-4b6c-847a-b4de59a71e66|Alea takes command of the Gull]]"],
+            entities: ["[[adfdd8db-0bf1-4053-928f-52709232859f|Alea Marrow]]"],
+        },
+        body: "A three-day storm floods the lower docks.",
+    },
+};
+/** A schema's value shape in words, read from the zod schema itself. */
+function describeShape(schema) {
+    if (schema === wikilinkSchema)
+        return "link";
+    if (schema instanceof z.ZodOptional)
+        return describeShape(schema.unwrap());
+    if (schema instanceof z.ZodLiteral)
+        return schema.values.size === 1 ? JSON.stringify([...schema.values][0]) : "literal";
+    if (schema instanceof z.ZodString)
+        return "string";
+    if (schema instanceof z.ZodNumber)
+        return schema.isInt ? "integer" : "number";
+    if (schema instanceof z.ZodArray)
+        return `list of ${describeShape(schema.element)}s`;
+    if (schema instanceof z.ZodObject) {
+        const keys = Object.entries(schema.shape).map(([key, value]) => `${key}${value instanceof z.ZodOptional ? "?" : ""}: ${describeShape(value)}`);
+        return `{ ${keys.join(", ")} }`;
+    }
+    return "value";
 }
-function describeFields(names) {
-    return names.map((name) => `  - ${name}: ${FIELD_MEANINGS[name] ?? "(see SCHEMA.md)"}`);
+function describeFields(shape, names) {
+    return names.map((name) => {
+        const schema = shape[name];
+        const required = schema instanceof z.ZodOptional ? "optional" : "required";
+        return `  - ${name} (${describeShape(schema)}, ${required}): ${FIELD_MEANINGS[name] ?? "(see SCHEMA.md)"}`;
+    });
 }
 /**
- * Prints the live, current schema: field names come straight from the zod
- * schemas in fields.ts, so this can't structurally drift from what
+ * Prints the live, current schema: field names and value shapes come straight
+ * from the zod schemas in fields.ts, so this can't structurally drift from what
  * validateFrontmatter actually enforces. This is what the CLI's `schema`
- * command exposes so Claude always sees the real, current rules — see
+ * command exposes so an agent always sees the real, current rules — see
  * claude-dev/PROJECT_STRUCTURE.md.
  */
 export function describeSchema(entityTypeVocabulary) {
-    const commonKeys = shapeKeys(commonFieldsSchema);
+    const commonKeys = Object.keys(commonFieldsSchema.shape);
     const excluded = new Set([...commonKeys, "type"]);
-    const entityKeys = shapeKeys(entityFrontmatterSchema).filter((key) => !excluded.has(key));
-    const eventKeys = shapeKeys(eventFrontmatterSchema).filter((key) => !excluded.has(key));
+    const entityKeys = Object.keys(entityFrontmatterSchema.shape).filter((key) => !excluded.has(key));
+    const eventKeys = Object.keys(eventFrontmatterSchema.shape).filter((key) => !excluded.has(key));
     const lines = [
         "Common fields (every file):",
-        ...describeFields(["type", ...commonKeys]),
+        `  - type ("entity" or "event", required): ${FIELD_MEANINGS.type}`,
+        ...describeFields(commonFieldsSchema.shape, commonKeys),
         "",
         "Entity-only fields:",
-        ...describeFields(entityKeys),
+        ...describeFields(entityFrontmatterSchema.shape, entityKeys),
         "",
         "Event-only fields:",
-        ...describeFields(eventKeys),
+        ...describeFields(eventFrontmatterSchema.shape, eventKeys),
         "",
-        'Any other frontmatter field whose value is a wikilink ("[[uuid|Display Name]]") is automatically a relation.',
+        'A link is a string "[[uuid|Display Name]]". A list field takes a list even for one link: after: ["[[uuid|Name]]"].',
+        "Any other frontmatter field whose value is a link is automatically a relation.",
     ];
     if (entityTypeVocabulary && entityTypeVocabulary.length > 0) {
         lines.push("", `This vault's declared entityType vocabulary: ${entityTypeVocabulary.join(", ")}`);
@@ -47,5 +94,6 @@ export function describeSchema(entityTypeVocabulary) {
     else {
         lines.push("", "This vault has not declared an entityType vocabulary — any entityType value is accepted.");
     }
+    lines.push("", "Example input for `wbf create` (replace the UUIDs with real ids, e.g. from `wbf search`):", `  entity: ${JSON.stringify(SCHEMA_EXAMPLES.entity)}`, `  event:  ${JSON.stringify(SCHEMA_EXAMPLES.event)}`);
     return lines.join("\n");
 }

package/dist/core/schema/fields.d.ts

@@ -1,249 +1,57 @@
 import { z } from "zod";
 /** Any field whose value looks like this is auto-detected as a graph edge (SCHEMA.md rule 2) — no fixed vocabulary of relation-field names. */
-export declare const wikilinkSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const wikilinkSchema: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
 export declare const inWorldDateSchema: z.ZodObject<{
     year: z.ZodNumber;
     day: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    year: number;
-    day: number;
-}, {
-    year: number;
-    day: number;
-}>;
+}, z.core.$strip>;
 /** Fields every knowledge file carries (SCHEMA.md "Common frontmatter"). */
 export declare const commonFieldsSchema: z.ZodObject<{
     title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    title: string;
-    tags?: string[] | undefined;
-    aliases?: string[] | undefined;
-}, {
-    title: string;
-    tags?: string[] | undefined;
-    aliases?: string[] | undefined;
-}>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export declare const entityFrontmatterSchema: z.ZodObject<{
     title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     type: z.ZodLiteral<"entity">;
     entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"entity">;
-    entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"entity">;
-    entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, z.ZodTypeAny, "passthrough">>;
+    supersedes: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    causedBy: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+}, z.core.$loose>;
 export declare const eventFrontmatterSchema: z.ZodObject<{
     title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    date: z.ZodOptional<z.ZodObject<{
-        year: z.ZodNumber;
-        day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    date: z.ZodOptional<z.ZodObject<{
-        year: z.ZodNumber;
-        day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    date: z.ZodOptional<z.ZodObject<{
-        year: z.ZodNumber;
-        day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, z.ZodTypeAny, "passthrough">>;
-export declare const knowledgeFileFrontmatterSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"entity">;
-    entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"entity">;
-    entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"entity">;
-    entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    date: z.ZodOptional<z.ZodObject<{
-        year: z.ZodNumber;
-        day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    date: z.ZodOptional<z.ZodObject<{
-        year: z.ZodNumber;
-        day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-    date: z.ZodOptional<z.ZodObject<{
-        year: z.ZodNumber;
-        day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, z.ZodTypeAny, "passthrough">>]>, z.objectOutputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
-    type: z.ZodLiteral<"entity">;
-    entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, z.ZodTypeAny, "passthrough"> | z.objectOutputType<{
-    title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    after: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
     date: z.ZodOptional<z.ZodObject<{
         year: z.ZodNumber;
         day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    }, z.core.$strip>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+}, z.core.$loose>;
+export declare const knowledgeFileFrontmatterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     type: z.ZodLiteral<"entity">;
     entityType: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, z.ZodTypeAny, "passthrough"> | z.objectInputType<{
+    supersedes: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    causedBy: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+}, z.core.$loose>, z.ZodObject<{
     title: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-} & {
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     type: z.ZodLiteral<"event">;
-    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    after: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
     date: z.ZodOptional<z.ZodObject<{
         year: z.ZodNumber;
         day: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        year: number;
-        day: number;
-    }, {
-        year: number;
-        day: number;
-    }>>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
-}, z.ZodTypeAny, "passthrough">>;
+    }, z.core.$strip>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+}, z.core.$loose>], "type">;
 export type EntityFrontmatter = z.infer<typeof entityFrontmatterSchema>;
 export type EventFrontmatter = z.infer<typeof eventFrontmatterSchema>;
 export type KnowledgeFileFrontmatter = z.infer<typeof knowledgeFileFrontmatterSchema>;

package/dist/core/schema/fields.js

@@ -21,7 +21,7 @@ export const entityFrontmatterSchema = commonFieldsSchema
     supersedes: wikilinkSchema.optional(),
     causedBy: wikilinkSchema.optional(),
 })
-    .passthrough();
+    .loose();
 export const eventFrontmatterSchema = commonFieldsSchema
     .extend({
     type: z.literal("event"),
@@ -29,13 +29,13 @@ export const eventFrontmatterSchema = commonFieldsSchema
     date: inWorldDateSchema.optional(),
     entities: z.array(wikilinkSchema).optional(),
 })
-    .passthrough();
+    .loose();
 export const knowledgeFileFrontmatterSchema = z
     .discriminatedUnion("type", [entityFrontmatterSchema, eventFrontmatterSchema])
     .superRefine((data, ctx) => {
     if (data.type === "entity" && Boolean(data.supersedes) !== Boolean(data.causedBy)) {
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: "custom",
             message: '"supersedes" and "causedBy" must both be present, or both absent',
             path: ["causedBy"],
         });

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;