Worldshaper/docs/kb

Worldshaper KB Scaffold

This folder is the first pass of an internal knowledge base for Worldshaper.

It is meant to support three jobs:

1. Human onboarding.
2. Faster request triage.
3. Grounded local-LLM analysis for the Requests queue.

The goal is to give request-processing tools stable system summaries instead of asking a model to infer editor behavior from raw user text alone.

Layout

• systems.json
  • Machine-readable system index.
• request-analysis-schema.json
  • JSON schema for structured request parsing output.
• queue-workflow.md
  • First-pass automation and review flow.
• systems/*.md
  • Human-readable system notes, organized by editor subsystem.

Current System Coverage

The scaffold currently covers:

• Launcher home and tabbed board
• Requests intake and request state handling
• Studio bootstrap and world loading
• Chunk storage and neighborhood streaming
• Layers and tile editing
• Graphics Painter
• Rendering and viewport behavior
• World Overview
• Persistence and save pipeline
• Floating windows and popout shell
• Content catalog and record APIs

How To Use This For Request Analysis

Suggested queue flow:

1. Pull a raw request submission from the launcher request store.
2. Retrieve likely systems from systems.json using tags, aliases, and file names.
3. Provide the matching systems/*.md files to the local model as context.
4. Ask the model to split the submission into atomic requests.
5. Require output that matches request-analysis-schema.json.
6. Validate the JSON before storing anything back into the app.
7. Auto-promote only high-confidence items. Keep low-confidence items in review.

Recommended Next Additions

• Add concrete file-level notes for major controllers as they evolve.
• Add a small extractor script that refreshes endpoint lists from server.js.
• Add examples of well-tagged historical requests for few-shot prompting.
• Add confidence thresholds and retry rules for malformed model output.

Current Automation Entry Point

Use the queue worker with:

npm run analyze:requests

The worker expects:

• the Worldshaper API server to be running
• a model endpoint and API key
• KB files from this folder

DeepSeek Setup

The worker now supports DeepSeek directly.

Recommended environment:

$env:DEEPSEEK_API_KEY="your-key-here"

Defaults when DEEPSEEK_API_KEY is present:

• provider: deepseek
• base URL: https://api.deepseek.com
• model: deepseek-v4-flash
• JSON mode: enabled
• thinking: disabled

You can override the model if you want:

$env:REQUEST_ANALYZER_MODEL="deepseek-v4-pro"

Suggested Review Rules

• If the model produces multiple atomic requests from one submission, keep the original submission id on every derived item.
• If a request touches multiple systems, prefer one primary category and many tags.
• If the request is really a bug report, preserve the problem statement and write the implementation note as a likely fix path, not a promise.
• If the model cannot confidently map a request, store it as needs_review instead of forcing a category.

Notes

• This scaffold is grounded to the repo layout on 2026-06-26.
• It is intentionally incomplete. Treat it as a maintained map, not generated truth.