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.
• tags.json
  • Standardized request tags for queue analysis and admin review.
• queue-workflow.md
  • First-pass automation and review flow.
• editor-capabilities.md
  • Shorthand capability matrix for common request-analysis questions.
• 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. Require the model to use only tags from tags.json.
5. Ask the model to split the submission into atomic requests.
6. Require output that matches request-analysis-schema.json.
7. Validate the JSON before storing anything back into the app.
8. 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.
• Review rationale should be short, structured, and safe to show in admin UI. Do not rely on hidden model chain-of-thought.
• 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.