world-building-framework 0.2.0 → 0.2.1

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

@@ -4,13 +4,7 @@ import { type ValidationIssue } from "../../core/schema/index.js";
 export declare const fileInputSchema: z.ZodObject<{
     frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     body: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    frontmatter: Record<string, unknown>;
-    body: string;
-}, {
-    frontmatter: Record<string, unknown>;
-    body?: string | undefined;
-}>;
+}, z.core.$strip>;
 export interface CreateOutcome {
     written: boolean;
     id?: string;

package/dist/cli/commands/publish.js

@@ -49,7 +49,7 @@ export async function runPublish(vaultOption, options) {
     await setQuartzPageTitle(quartzDir, title);
     for (const name of variantNames) {
         const query = getBuildVariant(config, name);
-        const pages = buildDerivedTree(files, query);
+        const pages = buildDerivedTree(files, query, { title });
         await syncDerivedTreeToQuartz(path.join(quartzDir, "content"), pages);
         if (options.baseUrl) {
             await setQuartzBaseUrl(quartzDir, `${normalizeBaseUrl(options.baseUrl)}/${name}`);

package/dist/cli/commands/render.js

@@ -11,7 +11,7 @@ export async function runRender(vaultOption, options) {
     const config = await loadWorldConfig(vaultDir);
     const query = getBuildVariant(config, options.variant);
     const files = await readVault(vaultDir);
-    const pages = buildDerivedTree(files, query);
+    const pages = buildDerivedTree(files, query, { title: worldTitle(config) });
     // Before syncing: a fresh clone must not land on top of a content folder we just wrote.
     if (options.build)
         await ensureQuartz(quartzDir);

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

@@ -3,226 +3,26 @@ import { z } from "zod";
  * A vault's own project-specific setup parameters (PROJECT_CONFIG.md).
  * `title`, `entityTypes` and `buildVariants` are the fields with a decided consumer
  * so far — tag vocabulary itself (as opposed to where it's used, buildVariants)
- * and relation-field naming are still open, so this stays passthrough rather
+ * and relation-field naming are still open, so this stays loose (unknown keys kept) rather
  * than locking in a shape for those prematurely.
  */
 export declare const worldConfigSchema: z.ZodObject<{
-    /** The world's name, shown as the published site's title (every variant and the landing page). */
     title: z.ZodOptional<z.ZodString>;
-    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** Named filter queries (render-pipeline's BuildVariantQuery) — PROJECT_CONFIG.md #3. */
+    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     buildVariants: z.ZodOptional<z.ZodRecord<z.ZodString, 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;
-    }>>>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    /** The world's name, shown as the published site's title (every variant and the landing page). */
-    title: z.ZodOptional<z.ZodString>;
-    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** Named filter queries (render-pipeline's BuildVariantQuery) — PROJECT_CONFIG.md #3. */
-    buildVariants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        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;
-            }>>;
-            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.ZodTypeAny, "passthrough">, z.objectInputType<{
-    /** The world's name, shown as the published site's title (every variant and the landing page). */
-    title: z.ZodOptional<z.ZodString>;
-    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** Named filter queries (render-pipeline's BuildVariantQuery) — PROJECT_CONFIG.md #3. */
-    buildVariants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        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;
-            }>>;
-            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.ZodTypeAny, "passthrough">>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$loose>;
 export type WorldConfig = z.infer<typeof worldConfigSchema>;
 export declare const DEFAULT_WORLD_TITLE = "World Wiki";
 /** The world's display title, falling back to a neutral default (never Quartz's own "Quartz 5"). */

package/dist/core/config/schema.js

@@ -4,7 +4,7 @@ import { buildVariantQuerySchema } from "../query/index.js";
  * A vault's own project-specific setup parameters (PROJECT_CONFIG.md).
  * `title`, `entityTypes` and `buildVariants` are the fields with a decided consumer
  * so far — tag vocabulary itself (as opposed to where it's used, buildVariants)
- * and relation-field naming are still open, so this stays passthrough rather
+ * and relation-field naming are still open, so this stays loose (unknown keys kept) rather
  * than locking in a shape for those prematurely.
  */
 export const worldConfigSchema = z
@@ -15,7 +15,7 @@ export const worldConfigSchema = z
     /** Named filter queries (render-pipeline's BuildVariantQuery) — PROJECT_CONFIG.md #3. */
     buildVariants: z.record(z.string(), buildVariantQuerySchema).optional(),
 })
-    .passthrough();
+    .loose();
 export const DEFAULT_WORLD_TITLE = "World Wiki";
 /** The world's display title, falling back to a neutral default (never Quartz's own "Quartz 5"). */
 export function worldTitle(config) {

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/render-pipeline/build.d.ts

@@ -4,6 +4,9 @@ import type { BuildVariantQuery, RenderedPage } from "./types.js";
  * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
  * by the build variant's query, merges each included entity's version history
  * into one page, and rewrites every link to a slug (or strips it if the target
- * isn't included).
+ * isn't included). Adds a start page listing everything included, titled
+ * `options.title` (the world's title).
  */
-export declare function buildDerivedTree(files: VaultFile[], query: BuildVariantQuery): RenderedPage[];
+export declare function buildDerivedTree(files: VaultFile[], query: BuildVariantQuery, options?: {
+    title?: string;
+}): RenderedPage[];

package/dist/render-pipeline/build.js

@@ -1,9 +1,10 @@
-import { buildGraph } from "../core/graph/index.js";
+import { buildGraph, topologicalOrder } from "../core/graph/index.js";
 import { filterEvents, filterEntityAnchors } from "./filter.js";
 import { mergeEntityBody } from "./merge.js";
 import { assignSlugs } from "./slugs.js";
 import { rewriteLinks, rewriteFrontmatterLinks } from "./rewrite.js";
 import { renameQuartzReservedFields } from "./quartz-compat.js";
+import { buildStartPage, START_PAGE_SLUG } from "./start-page.js";
 function titleOf(file) {
     return typeof file.frontmatter.title === "string" ? file.frontmatter.title : file.id;
 }
@@ -11,20 +12,22 @@ function titleOf(file) {
  * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
  * by the build variant's query, merges each included entity's version history
  * into one page, and rewrites every link to a slug (or strips it if the target
- * isn't included).
+ * isn't included). Adds a start page listing everything included, titled
+ * `options.title` (the world's title).
  */
-export function buildDerivedTree(files, query) {
+export function buildDerivedTree(files, query, options = {}) {
     const graph = buildGraph(files);
     const includedEventIds = filterEvents(graph, files, query);
     const includedAnchorIds = filterEntityAnchors(graph, files, query);
     // Sorted for a deterministic slug assignment, independent of vault read order.
     const includedIds = [...includedEventIds, ...includedAnchorIds].sort();
     const titles = new Map(includedIds.map((id) => [id, titleOf(graph.nodes.get(id))]));
-    const slugsById = assignSlugs(titles);
-    const pages = [];
-    for (const id of includedEventIds) {
+    const slugsById = assignSlugs(titles, [START_PAGE_SLUG]);
+    const eventPages = [];
+    const entityPages = [];
+    for (const id of topologicalOrder(graph).filter((eventId) => includedEventIds.has(eventId))) {
         const file = graph.nodes.get(id);
-        pages.push({
+        eventPages.push({
             id,
             slug: slugsById.get(id),
             frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(file.frontmatter, slugsById)),
@@ -34,12 +37,13 @@ export function buildDerivedTree(files, query) {
     for (const anchorId of includedAnchorIds) {
         const anchor = graph.nodes.get(anchorId);
         const mergedBody = mergeEntityBody(graph, anchorId, includedEventIds);
-        pages.push({
+        entityPages.push({
             id: anchorId,
             slug: slugsById.get(anchorId),
             frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(anchor.frontmatter, slugsById)),
             body: rewriteLinks(mergedBody, slugsById),
         });
     }
-    return pages;
+    const startPage = buildStartPage(options.title ?? "World Wiki", entityPages, eventPages);
+    return [...eventPages, ...entityPages, startPage];
 }

package/dist/render-pipeline/index.d.ts

@@ -5,6 +5,7 @@ export * from "./merge.js";
 export * from "./slugs.js";
 export * from "./rewrite.js";
 export * from "./quartz-compat.js";
+export * from "./start-page.js";
 export * from "./build.js";
 export * from "./write.js";
 export * from "./sync.js";

package/dist/render-pipeline/index.js

@@ -5,6 +5,7 @@ export * from "./merge.js";
 export * from "./slugs.js";
 export * from "./rewrite.js";
 export * from "./quartz-compat.js";
+export * from "./start-page.js";
 export * from "./build.js";
 export * from "./write.js";
 export * from "./sync.js";

package/dist/render-pipeline/slugs.d.ts

@@ -2,6 +2,7 @@
  * Assigns a unique, readable slug per id — vault files are UUID-named (SCHEMA.md),
  * meaningless as a published URL; this is what Stage 1 uses instead for the
  * derived tree. Iterates `titles` in whatever order the caller provides, so pass
- * ids in a deterministic order for reproducible builds.
+ * ids in a deterministic order for reproducible builds. No page gets a slug
+ * in `reserved` (e.g. the start page's "index").
  */
-export declare function assignSlugs(titles: Map<string, string>): Map<string, string>;
+export declare function assignSlugs(titles: Map<string, string>, reserved?: string[]): Map<string, string>;

package/dist/render-pipeline/slugs.js

@@ -10,10 +10,11 @@ function slugify(title) {
  * Assigns a unique, readable slug per id — vault files are UUID-named (SCHEMA.md),
  * meaningless as a published URL; this is what Stage 1 uses instead for the
  * derived tree. Iterates `titles` in whatever order the caller provides, so pass
- * ids in a deterministic order for reproducible builds.
+ * ids in a deterministic order for reproducible builds. No page gets a slug
+ * in `reserved` (e.g. the start page's "index").
  */
-export function assignSlugs(titles) {
-    const used = new Set();
+export function assignSlugs(titles, reserved = []) {
+    const used = new Set(reserved);
     const slugs = new Map();
     for (const [id, title] of titles) {
         const base = slugify(title);

package/dist/render-pipeline/start-page.d.ts

@@ -0,0 +1,9 @@
+import type { RenderedPage } from "./types.js";
+/** Quartz builds a site's root page from `content/index.md`; without it, the wiki's own address is a 404. */
+export declare const START_PAGE_SLUG = "index";
+/**
+ * The wiki's start page: every included entity, grouped by entityType and sorted
+ * by title, then every included event in causal order. `events` must already be
+ * in that order; only pages of this build go in, so nothing filtered out shows up.
+ */
+export declare function buildStartPage(title: string, entities: RenderedPage[], events: RenderedPage[]): RenderedPage;

package/dist/render-pipeline/start-page.js

@@ -0,0 +1,44 @@
+/** Quartz builds a site's root page from `content/index.md`; without it, the wiki's own address is a 404. */
+export const START_PAGE_SLUG = "index";
+function titleOf(page) {
+    return typeof page.frontmatter.title === "string" ? page.frontmatter.title : page.slug;
+}
+function linkTo(page) {
+    return `[[${page.slug}|${titleOf(page)}]]`;
+}
+function describeDate(page) {
+    const date = page.frontmatter.worldDate;
+    if (typeof date?.year !== "number")
+        return "";
+    return typeof date.day === "number" ? ` (year ${date.year}, day ${date.day})` : ` (year ${date.year})`;
+}
+function heading(entityType) {
+    return entityType.charAt(0).toUpperCase() + entityType.slice(1);
+}
+/**
+ * The wiki's start page: every included entity, grouped by entityType and sorted
+ * by title, then every included event in causal order. `events` must already be
+ * in that order; only pages of this build go in, so nothing filtered out shows up.
+ */
+export function buildStartPage(title, entities, events) {
+    const groups = new Map();
+    for (const page of entities) {
+        const entityType = typeof page.frontmatter.entityType === "string" ? page.frontmatter.entityType : "";
+        groups.set(entityType, [...(groups.get(entityType) ?? []), page]);
+    }
+    // Typed groups alphabetically, untyped entities last.
+    const groupKeys = [...groups.keys()].sort((a, b) => (a === "" ? 1 : b === "" ? -1 : a.localeCompare(b)));
+    const sections = groupKeys.map((key) => {
+        const pages = groups.get(key).sort((a, b) => titleOf(a).localeCompare(titleOf(b)));
+        return `## ${key === "" ? "Other" : heading(key)}\n\n${pages.map((page) => `- ${linkTo(page)}`).join("\n")}`;
+    });
+    if (events.length > 0) {
+        sections.push(`## Events\n\n${events.map((page) => `- ${linkTo(page)}${describeDate(page)}`).join("\n")}`);
+    }
+    return {
+        id: START_PAGE_SLUG,
+        slug: START_PAGE_SLUG,
+        frontmatter: { title },
+        body: sections.length > 0 ? `${sections.join("\n\n")}\n` : "Nothing here yet.\n",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "world-building-framework",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Build, search and publish fictional worlds from a vault of Markdown files: the wbf CLI and its core engine.",
   "license": "UNLICENSED",
   "type": "module",
@@ -36,7 +36,7 @@
     "commander": "^15.0.0",
     "gray-matter": "^4.0.3",
     "uuid": "^14.0.2",
-    "zod": "^3.23.8"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",