world-building-framework 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2026 Marius Faust. All rights reserved.
+
+This software and its source code are proprietary. No license is granted to
+use, copy, modify, merge, publish, distribute, sublicense, or sell any part of
+it, in source or compiled form, without the prior written permission of the
+copyright holder.
+
+Being able to view this repository or download this software does not grant
+any such permission.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# World Building Framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build a fictional world as a folder of Markdown files, and publish it as a wiki on GitHub Pages: one site per audience, such as a player wiki and a GM wiki. You write with any AI agent, through Obsidian, or by hand. The `wbf` command checks every change, so links stay valid and history is kept.
+
+## Start a world
+
+You need [Node.js 22](https://nodejs.org/) or newer and git.
+
+```
+mkdir my-world
+cd my-world
+git init
+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` never overwrites a file you already have. It creates:
+- `package.json`, with the framework version pinned
+- `world.config.json`
+- `.gitignore`
+- `AGENTS.md`
+- a GitHub Pages workflow
+- Obsidian settings that hide tooling folders
+
+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>/`.
+
+## Writing your world
+
+**With an AI agent:** ask it to add or change things ("add a character called Alea, a ship's captain in Port Kavas"). It uses the `wbf` command through the installed skill or `AGENTS.md`.
+
+**From the command line,** inside your world folder:
+
+| Command | What it does |
+|---|---|
+| `npx wbf schema` | Shows which fields files can have |
+| `npx wbf search <terms>` | Keyword search, returns each file's UUID |
+| `npx wbf create` | Creates a file from JSON on stdin; checks it first |
+| `npx wbf update --id <uuid>` | Replaces a file's content, for corrections |
+| `npx wbf validate` | Checks the whole world |
+| `npx wbf render --variant wiki --build` | Builds one wiki locally |
+| `npx wbf publish --output site` | Builds every wiki, as the workflow does |
+| `npx wbf --help` | Every command and option |
+
+Run `npx wbf` only inside a world folder. Elsewhere it would fetch an unrelated npm package that happens to be called `wbf`.
+
+**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.
+
+## 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.
+- **Two kinds of file:** `type: entity` (characters, places, factions, …) and `type: event` (things that happen).
+- **Links** look like `[[<uuid>|Display Name]]`. Any frontmatter field holding one is a relation, whatever you call it.
+- **Events are ordered by `after`**, a link to the event(s) they follow. A `date: {year, day}` is optional.
+- **Changes over time** become new files: a new version of an entity points at the old one with `supersedes`, and at the event that changed it with `causedBy`. The wiki shows the whole history on one page.
+
+## world.config.json
+
+```json
+{
+  "title": "The Kavas Chronicles",
+  "entityTypes": ["character", "location", "faction"],
+  "buildVariants": {
+    "player-wiki": { "tags": ["player"], "dateRange": { "to": { "year": 150 } } },
+    "gm-wiki": {}
+  }
+}
+```
+
+- **`title`:** shown on every wiki page and the landing page.
+- **`entityTypes`:** the allowed `entityType` values. Leave it out to allow any.
+- **`buildVariants`:** one wiki per entry, published at `/<name>/`. `init` starts you with one unfiltered `wiki`.
+  - `tags`: a file must carry all of them to be included.
+  - `dateRange`: limits events by in-world date. An undated event is placed by its `after` links and only included if it surely falls inside the range.
+  - `{}` includes everything.
+
+**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.
+
+## Preview locally
+
+```
+npx wbf render --variant wiki --build
+cd .wbf/quartz
+node ./quartz/bootstrap-cli.mjs build --serve
+```
+
+The first build downloads Quartz, the site generator, into `.wbf/quartz/`.
+
+## Updating the framework
+
+```
+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.
+
+## License
+
+Proprietary, all rights reserved. See [LICENSE](LICENSE). No use, copying or distribution without written permission.

package/dist/cli/check.d.ts

@@ -0,0 +1,13 @@
+import { type ValidateOptions, type ValidationIssue } from "../core/schema/index.js";
+import { type LintContext } from "../core/lint/index.js";
+/**
+ * Every check a file gets before it's written, or when validated: schema
+ * validation plus lint against the whole vault (`context`, from
+ * createLintContext). Shared by create, update and validate so they can
+ * never disagree. Pass `id` for a file that already exists in the vault.
+ */
+export declare function checkFile(file: {
+    id?: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}, options: ValidateOptions, context: LintContext): ValidationIssue[];

package/dist/cli/check.js

@@ -0,0 +1,11 @@
+import { validateFrontmatter } from "../core/schema/index.js";
+import { lintFile } from "../core/lint/index.js";
+/**
+ * Every check a file gets before it's written, or when validated: schema
+ * validation plus lint against the whole vault (`context`, from
+ * createLintContext). Shared by create, update and validate so they can
+ * never disagree. Pass `id` for a file that already exists in the vault.
+ */
+export function checkFile(file, options, context) {
+    return [...validateFrontmatter(file.frontmatter, options).issues, ...lintFile(file, context)];
+}

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

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { type ValidationIssue } from "../../core/schema/index.js";
+/** {"frontmatter": {...}, "body": "..."} — the input shape for both create and update. */
+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;
+}>;
+export interface CreateOutcome {
+    written: boolean;
+    id?: string;
+    path?: string;
+    /** Errors (when not written) and warnings (which never block the write). */
+    issues?: ValidationIssue[];
+}
+/**
+ * Lints the candidate against the whole vault before writing, same as `validate` —
+ * so a dangling link blocks the write here too instead of silently becoming plain
+ * text in the rendered wiki. Lint warnings are returned but don't block.
+ */
+export declare function runCreate(vaultOption: string | undefined, rawInput: unknown): Promise<CreateOutcome>;

package/dist/cli/commands/create.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { createVaultFile, readVault } from "../../core/vault/index.js";
+import { hasErrors } from "../../core/schema/index.js";
+import { loadWorldConfig, validateOptionsFromConfig } from "../../core/config/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+import { createLintContext } from "../../core/lint/index.js";
+import { checkFile } from "../check.js";
+/** {"frontmatter": {...}, "body": "..."} — the input shape for both create and update. */
+export const fileInputSchema = z.object({
+    frontmatter: z.record(z.string(), z.unknown()),
+    body: z.string().default(""),
+});
+/**
+ * Lints the candidate against the whole vault before writing, same as `validate` —
+ * so a dangling link blocks the write here too instead of silently becoming plain
+ * text in the rendered wiki. Lint warnings are returned but don't block.
+ */
+export async function runCreate(vaultOption, rawInput) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const input = fileInputSchema.parse(rawInput);
+    const config = await loadWorldConfig(vaultDir);
+    const options = validateOptionsFromConfig(config);
+    const files = await readVault(vaultDir);
+    const issues = checkFile(input, options, createLintContext(files));
+    if (hasErrors(issues)) {
+        return { written: false, issues };
+    }
+    const result = await createVaultFile(vaultDir, input.frontmatter, input.body, options);
+    if (!result.written) {
+        return { written: false, issues: result.issues };
+    }
+    return issues.length > 0
+        ? { written: true, id: result.id, path: result.path, issues }
+        : { written: true, id: result.id, path: result.path };
+}

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

@@ -0,0 +1,26 @@
+export interface InitOptions {
+    /** Folder to set up; defaults to the current folder. */
+    dir?: string;
+    /** The world's display title; defaults to one derived from the folder name. */
+    title?: string;
+    /** Agents to install skills for (see AGENT_SKILL_DIRS). */
+    agents?: string[];
+    /** Branch the publish workflow runs on; defaults to the git repo's current branch, else "main". */
+    branch?: string;
+}
+export interface InitOutcome {
+    dir: string;
+    created: string[];
+    /** Existing files init added to (package.json dependency, .gitignore entries). */
+    updated: string[];
+    /** Existing files init left alone. Managed ones among them aren't kept current by `refresh`. */
+    skipped: string[];
+    nextSteps: string[];
+}
+/**
+ * Sets a folder up as a world repo (claude-dev/DISTRIBUTION_PLAN.md, component 4).
+ * Never overwrites an existing file: it only adds the framework dependency to an
+ * existing package.json and missing lines to an existing .gitignore, and reports
+ * everything it left alone.
+ */
+export declare function runInit(options?: InitOptions): Promise<InitOutcome>;

package/dist/cli/commands/init.js

@@ -0,0 +1,119 @@
+import { spawnSync } from "node:child_process";
+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";
+const PACKAGE_NAME = "world-building-framework";
+function titleFromFolder(dir) {
+    const words = path.basename(path.resolve(dir)).split(/[-_\s]+/).filter(Boolean);
+    return words.map((word) => word[0].toUpperCase() + word.slice(1)).join(" ") || "My World";
+}
+function detectBranch(dir) {
+    const result = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: dir, encoding: "utf8" });
+    const branch = result.status === 0 ? result.stdout.trim() : "";
+    return branch && branch !== "HEAD" ? branch : "main";
+}
+function packageNameFromFolder(dir) {
+    const name = path.basename(path.resolve(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return name || "my-world";
+}
+/**
+ * Sets a folder up as a world repo (claude-dev/DISTRIBUTION_PLAN.md, component 4).
+ * Never overwrites an existing file: it only adds the framework dependency to an
+ * existing package.json and missing lines to an existing .gitignore, and reports
+ * everything it left alone.
+ */
+export async function runInit(options = {}) {
+    const dir = path.resolve(options.dir ?? process.cwd());
+    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(", ")}`);
+        }
+    }
+    const version = await readFrameworkVersion();
+    const outcome = { dir, created: [], updated: [], skipped: [], nextSteps: [] };
+    const exists = (rel) => existsSync(path.join(dir, rel));
+    // package.json: create, or add the framework dependency to an existing one.
+    if (!exists("package.json")) {
+        const pkg = { name: packageNameFromFolder(dir), private: true, dependencies: { [PACKAGE_NAME]: version } };
+        await writeRepoFile(dir, "package.json", JSON.stringify(pkg, null, 2) + "\n");
+        outcome.created.push("package.json");
+    }
+    else {
+        const pkg = JSON.parse(await readFile(path.join(dir, "package.json"), "utf8"));
+        const deps = (pkg.dependencies ?? {});
+        if (deps[PACKAGE_NAME]) {
+            outcome.skipped.push("package.json");
+        }
+        else {
+            pkg.dependencies = { ...deps, [PACKAGE_NAME]: version };
+            await writeFile(path.join(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n", "utf8");
+            outcome.updated.push("package.json");
+        }
+    }
+    // world.config.json: one unfiltered variant, so a first publish shows everything; edit it to add filtered ones.
+    if (!exists(WORLD_CONFIG_FILENAME)) {
+        const config = { title: options.title ?? titleFromFolder(dir), entityTypes: [], buildVariants: { wiki: {} } };
+        await writeRepoFile(dir, WORLD_CONFIG_FILENAME, JSON.stringify(config, null, 2) + "\n");
+        outcome.created.push(WORLD_CONFIG_FILENAME);
+    }
+    else {
+        outcome.skipped.push(WORLD_CONFIG_FILENAME);
+    }
+    // .gitignore: create, or append the lines it's missing.
+    const ignoreTemplate = await readFile(path.join(PACKAGE_ROOT, "templates", "gitignore"), "utf8");
+    if (!exists(".gitignore")) {
+        await writeRepoFile(dir, ".gitignore", ignoreTemplate);
+        outcome.created.push(".gitignore");
+    }
+    else {
+        const current = await readFile(path.join(dir, ".gitignore"), "utf8");
+        const present = new Set(current.split(/\r?\n/).map((line) => line.trim()));
+        const missing = ignoreTemplate.split(/\r?\n/).filter((line) => line && !line.startsWith("#") && !present.has(line));
+        if (missing.length > 0) {
+            const separator = current.endsWith("\n") || current === "" ? "" : "\n";
+            await writeFile(path.join(dir, ".gitignore"), current + separator + missing.join("\n") + "\n", "utf8");
+            outcome.updated.push(".gitignore");
+        }
+        else {
+            outcome.skipped.push(".gitignore");
+        }
+    }
+    // Obsidian: hide tooling folders, so it doesn't list package READMEs.
+    if (!exists(".obsidian/app.json")) {
+        await writeRepoFile(dir, ".obsidian/app.json", JSON.stringify({ userIgnoreFilters: ["node_modules/", ".wbf/"] }, null, 2) + "\n");
+        outcome.created.push(".obsidian/app.json");
+    }
+    else {
+        outcome.skipped.push(".obsidian/app.json");
+    }
+    // Managed files (workflow, AGENTS.md, skills): written only where nothing exists yet, and recorded so `refresh` can update them.
+    const previous = await readManifest(dir);
+    const settings = {
+        branch: options.branch ?? previous?.branch ?? detectBranch(dir),
+        agents: [...new Set([...(previous?.agents ?? []), ...agents])],
+    };
+    const manifest = { frameworkVersion: version, ...settings, files: { ...(previous?.files ?? {}) } };
+    for (const [rel, content] of await renderManagedFiles(version, settings)) {
+        if (exists(rel)) {
+            if (!manifest.files[rel])
+                outcome.skipped.push(rel);
+            continue;
+        }
+        await writeRepoFile(dir, rel, content);
+        manifest.files[rel] = contentHash(content);
+        outcome.created.push(rel);
+    }
+    await writeManifest(dir, manifest);
+    outcome.nextSteps = [
+        "npm install",
+        "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("|")}>.`);
+    }
+    return outcome;
+}

package/dist/cli/commands/list-variants.d.ts

@@ -0,0 +1 @@
+export declare function runListVariants(vaultOption: string | undefined): Promise<string[]>;

package/dist/cli/commands/list-variants.js

@@ -0,0 +1,7 @@
+import { loadWorldConfig, listBuildVariants } from "../../core/config/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+export async function runListVariants(vaultOption) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const config = await loadWorldConfig(vaultDir);
+    return listBuildVariants(config);
+}

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

@@ -0,0 +1,24 @@
+export interface PublishOptions {
+    quartzDir?: string;
+    outputDir: string;
+    /** The combined site's public URL (e.g. https://user.github.io/repo). Each variant is built with `<baseUrl>/<variant>`. Omit to leave Quartz's configured baseUrl untouched. */
+    baseUrl?: string;
+}
+export interface PublishedVariant {
+    name: string;
+    pagesWritten: number;
+    outputDir: string;
+}
+export interface PublishOutcome {
+    variants: PublishedVariant[];
+    landingPage: string;
+}
+export declare function generateLandingPageHtml(variantNames: string[], title: string): string;
+/**
+ * Builds every declared build variant (subpath topology: each gets its own
+ * subfolder of one combined output tree) plus a landing page linking to them.
+ * Refuses to publish a vault with zero declared variants rather than falling
+ * back to an unfiltered build — that must always be a deliberate choice
+ * (REQUIREMENTS.md), never an implicit default.
+ */
+export declare function runPublish(vaultOption: string | undefined, options: PublishOptions): Promise<PublishOutcome>;

package/dist/cli/commands/publish.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { readVault } from "../../core/vault/index.js";
+import { loadWorldConfig, listBuildVariants, getBuildVariant, worldTitle } from "../../core/config/index.js";
+import { buildDerivedTree, syncDerivedTreeToQuartz } from "../../render-pipeline/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+import { resolveQuartzDir, runQuartzBuild, setQuartzBaseUrl, setQuartzPageTitle, normalizeBaseUrl, } from "../quartz-runner.js";
+import { ensureQuartz } from "../quartz-setup.js";
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function generateLandingPageHtml(variantNames, title) {
+    const items = variantNames
+        .map((name) => `    <li><a href="./${escapeHtml(name)}/">${escapeHtml(name)}</a></li>`)
+        .join("\n");
+    return `<!doctype html>
+<html>
+<head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head>
+<body>
+<h1>${escapeHtml(title)}</h1>
+<ul>
+${items}
+</ul>
+</body>
+</html>
+`;
+}
+/**
+ * Builds every declared build variant (subpath topology: each gets its own
+ * subfolder of one combined output tree) plus a landing page linking to them.
+ * Refuses to publish a vault with zero declared variants rather than falling
+ * back to an unfiltered build — that must always be a deliberate choice
+ * (REQUIREMENTS.md), never an implicit default.
+ */
+export async function runPublish(vaultOption, options) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const quartzDir = resolveQuartzDir(options.quartzDir);
+    const outputRoot = path.resolve(process.cwd(), options.outputDir);
+    const config = await loadWorldConfig(vaultDir);
+    const variantNames = listBuildVariants(config);
+    if (variantNames.length === 0) {
+        throw new Error("This vault has no declared build variants (world.config.json's buildVariants) — nothing to publish. " +
+            "An unfiltered build must be deliberately configured as its own named variant, never an implicit default.");
+    }
+    await ensureQuartz(quartzDir);
+    const files = await readVault(vaultDir);
+    const variants = [];
+    const title = worldTitle(config);
+    await setQuartzPageTitle(quartzDir, title);
+    for (const name of variantNames) {
+        const query = getBuildVariant(config, name);
+        const pages = buildDerivedTree(files, query);
+        await syncDerivedTreeToQuartz(path.join(quartzDir, "content"), pages);
+        if (options.baseUrl) {
+            await setQuartzBaseUrl(quartzDir, `${normalizeBaseUrl(options.baseUrl)}/${name}`);
+        }
+        const variantOutputDir = path.join(outputRoot, name);
+        await runQuartzBuild(quartzDir, variantOutputDir);
+        // GitHub Pages only reads CNAME (custom-domain config) at the actual site
+        // root, never in a subfolder — verified hands-on that Quartz writes one into
+        // every variant's own output regardless, carrying whatever placeholder
+        // baseUrl the local Quartz setup happens to have. Harmless as dead weight,
+        // but wrong/confusing content, so don't ship it per-variant.
+        await rm(path.join(variantOutputDir, "CNAME"), { force: true });
+        variants.push({ name, pagesWritten: pages.length, outputDir: variantOutputDir });
+    }
+    await mkdir(outputRoot, { recursive: true });
+    const landingPage = path.join(outputRoot, "index.html");
+    await writeFile(landingPage, generateLandingPageHtml(variantNames, title), "utf8");
+    return { variants, landingPage };
+}

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

@@ -0,0 +1,29 @@
+export interface RefreshOptions {
+    /** World repo root; defaults to the current folder. */
+    dir?: string;
+    /** Also overwrite files that were edited, deleted, or never generated by wbf. */
+    force?: boolean;
+}
+export interface KeptFile {
+    path: string;
+    reason: "edited" | "deleted" | "not-managed";
+}
+export interface RefreshOutcome {
+    fromVersion: string;
+    toVersion: string;
+    created: string[];
+    updated: string[];
+    unchanged: string[];
+    /** Left alone so nothing of yours is lost; `--force` overwrites them. */
+    kept: KeptFile[];
+    /** Recorded before, but no longer generated by this framework version. The file itself stays. */
+    retired: string[];
+}
+/**
+ * Brings the files wbf generated (publish workflow, AGENTS.md, agent skills)
+ * up to the installed framework version (claude-dev/DISTRIBUTION_PLAN.md,
+ * component 4). A file is only overwritten while its content still matches the
+ * hash recorded when wbf last wrote it — so anything you edited, deleted, or
+ * wrote yourself is kept and reported instead.
+ */
+export declare function runRefresh(options?: RefreshOptions): Promise<RefreshOutcome>;

package/dist/cli/commands/refresh.js

@@ -0,0 +1,70 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { MANIFEST_PATH, contentHash, readFrameworkVersion, readManifest, renderManagedFiles, writeManifest, writeRepoFile, } from "../managed-files.js";
+/**
+ * Brings the files wbf generated (publish workflow, AGENTS.md, agent skills)
+ * up to the installed framework version (claude-dev/DISTRIBUTION_PLAN.md,
+ * component 4). A file is only overwritten while its content still matches the
+ * hash recorded when wbf last wrote it — so anything you edited, deleted, or
+ * wrote yourself is kept and reported instead.
+ */
+export async function runRefresh(options = {}) {
+    const dir = path.resolve(options.dir ?? process.cwd());
+    const manifest = await readManifest(dir);
+    if (!manifest) {
+        throw new Error(`No ${MANIFEST_PATH} in ${dir} — run wbf init here first.`);
+    }
+    const toVersion = await readFrameworkVersion();
+    const outcome = {
+        fromVersion: manifest.frameworkVersion,
+        toVersion,
+        created: [],
+        updated: [],
+        unchanged: [],
+        kept: [],
+        retired: [],
+    };
+    const rendered = await renderManagedFiles(toVersion, { branch: manifest.branch, agents: manifest.agents });
+    const files = {};
+    for (const [rel, content] of rendered) {
+        const newHash = contentHash(content);
+        const recorded = manifest.files[rel];
+        const target = path.join(dir, ...rel.split("/"));
+        if (!existsSync(target)) {
+            if (recorded && !options.force) {
+                outcome.kept.push({ path: rel, reason: "deleted" });
+                files[rel] = recorded;
+                continue;
+            }
+            await writeRepoFile(dir, rel, content);
+            files[rel] = newHash;
+            outcome.created.push(rel);
+            continue;
+        }
+        const currentHash = contentHash(await readFile(target, "utf8"));
+        if (!recorded && !options.force) {
+            outcome.kept.push({ path: rel, reason: "not-managed" });
+            continue;
+        }
+        if (recorded && currentHash !== recorded && !options.force) {
+            outcome.kept.push({ path: rel, reason: "edited" });
+            files[rel] = recorded;
+            continue;
+        }
+        if (currentHash === newHash) {
+            files[rel] = newHash;
+            outcome.unchanged.push(rel);
+            continue;
+        }
+        await writeRepoFile(dir, rel, content);
+        files[rel] = newHash;
+        outcome.updated.push(rel);
+    }
+    for (const rel of Object.keys(manifest.files)) {
+        if (!rendered.has(rel))
+            outcome.retired.push(rel);
+    }
+    await writeManifest(dir, { ...manifest, frameworkVersion: toVersion, files });
+    return outcome;
+}

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

@@ -0,0 +1,14 @@
+export interface RenderOptions {
+    variant: string;
+    quartzDir?: string;
+    /** Absolute or cwd-relative; resolved against process.cwd() before being passed to Quartz's -o flag. */
+    outputDir?: string;
+    build?: boolean;
+}
+export interface RenderOutcome {
+    variant: string;
+    pagesWritten: number;
+    quartzContentDir: string;
+    built: boolean;
+}
+export declare function runRender(vaultOption: string | undefined, options: RenderOptions): Promise<RenderOutcome>;

package/dist/cli/commands/render.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+import { readVault } from "../../core/vault/index.js";
+import { loadWorldConfig, getBuildVariant, worldTitle } from "../../core/config/index.js";
+import { buildDerivedTree, syncDerivedTreeToQuartz } from "../../render-pipeline/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+import { resolveQuartzDir, runQuartzBuild, setQuartzPageTitle } from "../quartz-runner.js";
+import { ensureQuartz } from "../quartz-setup.js";
+export async function runRender(vaultOption, options) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const quartzDir = resolveQuartzDir(options.quartzDir);
+    const config = await loadWorldConfig(vaultDir);
+    const query = getBuildVariant(config, options.variant);
+    const files = await readVault(vaultDir);
+    const pages = buildDerivedTree(files, query);
+    // Before syncing: a fresh clone must not land on top of a content folder we just wrote.
+    if (options.build)
+        await ensureQuartz(quartzDir);
+    const quartzContentDir = path.join(quartzDir, "content");
+    await syncDerivedTreeToQuartz(quartzContentDir, pages);
+    if (options.build) {
+        // Same title as publish, so a local preview looks like the real site.
+        await setQuartzPageTitle(quartzDir, worldTitle(config));
+        const outputDir = options.outputDir ? path.resolve(process.cwd(), options.outputDir) : undefined;
+        await runQuartzBuild(quartzDir, outputDir);
+    }
+    return { variant: options.variant, pagesWritten: pages.length, quartzContentDir, built: Boolean(options.build) };
+}

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

@@ -0,0 +1,2 @@
+/** Vault is optional here — the framework-fixed schema is useful even with no vault selected. */
+export declare function runSchema(vaultOption: string | undefined): Promise<string>;

package/dist/cli/commands/schema.js

@@ -0,0 +1,9 @@
+import { describeSchema } from "../../core/schema/index.js";
+import { loadWorldConfig } from "../../core/config/index.js";
+import { findVaultDir } from "../vault-path.js";
+/** Vault is optional here — the framework-fixed schema is useful even with no vault selected. */
+export async function runSchema(vaultOption) {
+    const vaultDir = findVaultDir(vaultOption);
+    const config = vaultDir ? await loadWorldConfig(vaultDir) : {};
+    return describeSchema(config.entityTypes);
+}

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

@@ -0,0 +1,9 @@
+import { type SearchOptions } from "../../core/search/index.js";
+export interface SearchResultSummary {
+    id: string;
+    score: number;
+    title?: string;
+    entityType?: string;
+    tags?: string[];
+}
+export declare function runSearch(vaultOption: string | undefined, query: string, options: SearchOptions): Promise<SearchResultSummary[]>;

package/dist/cli/commands/search.js

@@ -0,0 +1,20 @@
+import { readVault } from "../../core/vault/index.js";
+import { buildSearchIndex, closeSearchIndex, search } from "../../core/search/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+export async function runSearch(vaultOption, query, options) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const files = await readVault(vaultDir);
+    const index = buildSearchIndex(files);
+    try {
+        return search(index, query, options).map((result) => ({
+            id: result.id,
+            score: result.score,
+            title: typeof result.file.frontmatter.title === "string" ? result.file.frontmatter.title : undefined,
+            entityType: typeof result.file.frontmatter.entityType === "string" ? result.file.frontmatter.entityType : undefined,
+            tags: Array.isArray(result.file.frontmatter.tags) ? result.file.frontmatter.tags : undefined,
+        }));
+    }
+    finally {
+        closeSearchIndex(index);
+    }
+}