# 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:

```bash
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:

```powershell
$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:

```powershell
$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.