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

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