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.
• terminology.json
  • Canonical editor terminology and user-language aliases.
• modules.json
  • Machine-readable index of granular KB slices for targeted retrieval.
• 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.
• modules/*.md
  • Smaller topical docs that can be mixed into model context without sending the whole KB.

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
• Routing terminology and modular retrieval slices

How To Use This For Request Analysis

Suggested queue flow:

1. Pull a raw request submission from the launcher request store.
2. Run a routing pass using systems.json, modules.json, and terminology.json.
3. Retrieve only the most relevant systems/*.md and modules/*.md files.
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

• Keep expanding modules until every major tool and runtime handoff has at least one focused doc.
• 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.