world-building-framework 0.0.0-stage → 0.2.0

package/skills/world-vault/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: world-vault
+description: Search, create, correct, and validate entity/event files in a World Building Framework world via the `wbf` CLI. Use whenever the user wants to look up, add, or change world-building content (characters, locations, events, factions, ...) in this repo.
+---
+
+# World Vault authoring
+
+This repo is a world built with the World Building Framework. Its content is a vault of entity/event Markdown files, named by UUID, next to a `world.config.json`. You read and write it through the `wbf` command-line tool, which prints JSON.
+
+**Never hand-write or hand-edit a vault file.** Only `wbf create` and `wbf update` validate content before it touches disk, and only `create` generates the required UUID filename.
+
+Run every command from the repo root as `npx wbf <command>`. That runs the framework version installed in this repo. If it reports "No vault specified", you're not in the folder that holds `world.config.json`: change into it, or pass `--vault <path>`.
+
+Commands that take JSON input read it from stdin, or from a file with `--input <file>`. Use a file when piping is awkward in your shell.
+
+## 1. Check the current schema before writing anything
+
+```
+npx wbf schema
+```
+
+This prints the framework's fixed fields, plus this world's own `entityType` list from `world.config.json`, if it declares one. Run it whenever you're unsure which fields are valid, especially before creating an entity with an `entityType` you haven't seen used here yet.
+
+## 2. Search before creating
+
+Search for what already exists before adding anything. That avoids duplicating an entity, and gives you the UUIDs you need to link to things:
+
+```
+npx wbf search <query terms...>
+```
+
+Each result has an `id` (the UUID you link with), `title` and `score`, and for entities `entityType` and `tags`. Add `--tags a,b` to require specific tags, and `--limit N` to cap the results.
+
+## 3. Writing links
+
+Every relation, in frontmatter or in body text, uses this link form: the target's UUID before the pipe, and its current title after it.
+
+```
+[[3af2c9d1-8b4e-4c6a-91f0-2d5e7a9b1c33|Port Kavas]]
+```
+
+Get the UUID from a search result's `id`, or from the `id` a `create` call just returned. Never write a bare `[[Display Name]]`. The vault only resolves links by UUID.
+
+## 4. Propose before writing
+
+No tool here enforces an approval step, so that's your job. Before calling `create` or `update`, show the user the frontmatter and body you're about to write, and wait for their go-ahead, the way you'd show a diff before editing code.
+
+## 5. Validate before (or instead of) creating
+
+To check a candidate without writing it:
+
+```
+echo '{"frontmatter": {"type": "entity", "title": "Alea Vantorr", "entityType": "character"}}' | npx wbf validate --input -
+```
+
+Each issue has a `severity`:
+- Fix every `"error"` (schema problems, dangling links, wrong link targets) before calling `create`.
+- A `"warning"` (e.g. an event with no `entities` yet) doesn't block anything. Mention it to the user, but it's fine to proceed.
+
+`create` runs these same checks, so `valid: true` here means `create` will succeed.
+
+## 6. Creating a file
+
+```
+echo '{"frontmatter": {...}, "body": "..."}' | npx wbf create
+```
+
+- **Required fields:** `type` and `title`. Everything else depends on whether it's an entity or an event; see `npx wbf schema`.
+- **On success** it prints `{"written": true, "id": "...", "path": "..."}`, plus an `issues` list if there were warnings. Tell the user the new `id`, since anything that links to this file needs that UUID.
+- **If any link points at an id that doesn't exist**, nothing is written, and the error is reported instead.
+
+## 7. Correcting an existing file
+
+For a **correction** (a typo, a wrong tag, a missing link, badly written text), replace the file in place:
+
+```
+echo '{"frontmatter": {...}, "body": "..."}' | npx wbf update --id <uuid>
+```
+
+- **Send the complete content.** The input is the file's whole new content, not just the changed fields. Read the current file (`<uuid>.md`) first, change what needs changing, and send all of it. Any field you leave out is removed.
+- **Same checks as `create`**, and `type` can't change.
+- **Show the user what you're changing** before calling it, as with `create`.
+
+Changing a `title` also changes **other files**:
+- Every link elsewhere written as `[[<uuid>|<old title>]]` is rewritten to show the new title.
+- Links with different display text, like `[[<uuid>|the old harbour]]`, are left alone.
+- When proposing a rename, tell the user other files will be updated too. Search the vault for `[[<uuid>|<old title>]]` to say which ones.
+- The result lists them under `relinked`. Any file under `relinkFailed` is already invalid on its own and kept the old name; report it to the user.
+
+`update` is only for things that were wrong. If something changed **in the story**, use section 8 instead.
+
+## 8. Recording a change to an existing entity: never edit it in place
+
+When an event changes something about an entity (it looks different, its status changed, and so on), that's **not** an edit to the existing file. Create a **new** entity file with these two fields:
+- `supersedes`: a link to the entity's current file. That's its **latest** version, not the anchor, unless the anchor is the only version so far. A "Fork in the version chain" warning almost always means you pointed at an older version. Tell the user and fix it with `update`, unless they deliberately want a story branch.
+- `causedBy`: a link to the event that caused the change.
+
+Both fields are required together. The vault keeps every version, and the published wiki shows the whole history. Never overwrite an entity file's body to reflect an in-world change; that erases history the vault is designed to keep.
+
+Other files always link to an entity's **original, first-ever** file (its anchor), never to a later version. If you're not sure which id is the anchor, follow the file's `supersedes` chain back. Or reuse whatever id you already have for that entity: that's always the anchor once created.

package/templates/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent instructions
+
+This repo is a world built with the World Building Framework (version __WBF_VERSION__). Its content is a vault of UUID-named Markdown files next to `world.config.json`.
+
+- Read and write the vault only through the `wbf` command-line tool: run `npx wbf <command>` from this folder. It prints JSON.
+- Run `npx wbf schema` before writing anything, `npx wbf search <terms>` before creating something, and `npx wbf --help` for every command.
+- Never hand-write or hand-edit a vault `.md` file. Only `wbf create` and `wbf update` validate content, and only `create` generates the required UUID filename.
+- Show the user what you're about to write, and wait for their go-ahead, before `create` or `update`.
+- If skills were installed for your agent (`npx wbf init --agent <name>`), the `world-vault` skill has the full workflow.
+
+Generated by `wbf init`. `npx wbf refresh` keeps it current while it's unedited.

package/templates/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+# Quartz's working copy, fetched by wbf on demand
+.wbf/quartz/
+# Local publish output
+site/

package/templates/publish.yml

@@ -0,0 +1,54 @@
+# Generated by world-building-framework __WBF_VERSION__ (`wbf init`).
+# `npx wbf refresh` updates this file to the installed framework version, but
+# only while you haven't edited it. Once you change it, it's yours to maintain.
+name: Publish wiki
+
+on:
+  push:
+    branches: [__BRANCH__]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install the framework (version pinned in package.json)
+        run: npm ci
+
+      # Runs before publish so its base_url output (the Pages site's real
+      # address) can be handed to Quartz.
+      - uses: actions/configure-pages@v5
+        id: pages
+
+      - name: Publish every build variant
+        run: npx wbf publish --output ./site --base-url "${{ steps.pages.outputs.base_url }}"
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment