Run request analysis on demand on the VPS

docs/kb/README.md

@@ -0,0 +1,107 @@
+# 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.