From 71ae91960f10d048fa3276f59b509ae366cddf55 Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Sun, 16 Aug 2026 13:04:14 +0800
Subject: [PATCH] docs: mark stale bgm engine/loader docs as in progress

Call out that the tabletop and engine package split is not yet landed, add a status note to tabletop.md, and drop the retired WIP banner in bgm-loader.md.
---
 docs/bgm/engine.md        | 15 +++++++++------
 docs/bgm/tabletop.md      |  9 +++++++--
 docs/status/bgm-loader.md |  8 ++++----
 3 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/docs/bgm/engine.md b/docs/bgm/engine.md
index ff5c024..0453df8 100644
--- a/docs/bgm/engine.md
+++ b/docs/bgm/engine.md
@@ -19,12 +19,15 @@ is node-testable in isolation (mirroring `@tts/extract`'s isomorphic, zero-dep
 style). It defines the contract — `Message`, the handler registry, `Trigger`,
 `Orchestrator`, and `RunContext`.
 
-[`@tts/tabletop`](./tabletop.md) is one consumer of that contract: it
-registers the built-in commands (`move`, `focus`, `caption`, `enableSurface`,
-...) that mutate the tabletop store and drive the render layer. The engine
-never imports tabletop; tabletop depends on the engine for the message types
-and the handler registry. A headless sim or bot harness can consume the engine
-without the render layer.
+[`@tts/tabletop`](./tabletop.md) is the intended consumer of that contract:
+it will register the built-in commands (`move`, `focus`, `caption`,
+`enableSurface`, ...) that mutate the tabletop store and drive the render layer.
+The engine never imports tabletop, and tabletop is expected to depend on the
+engine for the message types and the handler registry. **This wiring is designed
+but not yet landed** — today `@tts/tabletop` has no dependency on the engine;
+it ships its state store and render layer standalone (see
+[`../status/bgm-tabletop.md`](../status/bgm-tabletop.md)). A headless sim or bot
+harness can consume the engine without the render layer.
 
 ## 1. messages
 
diff --git a/docs/bgm/tabletop.md b/docs/bgm/tabletop.md
index dfff70d..26befce 100644
--- a/docs/bgm/tabletop.md
+++ b/docs/bgm/tabletop.md
@@ -1,10 +1,15 @@
 # bgm-tabletop
 
-a r3f based interactive component library to work with [bgm](./format.md) board games. will be used somewhere in the `web` app's bgm inspector routes.
+> **Status:** Implemented (items 1–8 of the plan). A few features below are
+> designed but not yet wired (commands, HUD rendering); see §5 and
+> [`../status/bgm-tabletop.md`](../status/bgm-tabletop.md).
+
+An r3f-based interactive component library for working with [bgm](./format.md)
+board games. It is used in the `web` app's bgm inspector routes.
 
 ## 1. stack
 
-`react` - react, react router, tailwindv4
+`react` - react, react router, tailwind v4
 `r3f` - r3f, drei, postprocessing
 `zustand` - for state management
 
diff --git a/docs/status/bgm-loader.md b/docs/status/bgm-loader.md
index 82a53df..8adc67d 100644
--- a/docs/status/bgm-loader.md
+++ b/docs/status/bgm-loader.md
@@ -1,7 +1,7 @@
 # bgm Loader — Status
 
-> WIP. What's built, what works, what's missing, and the known issues.
-> Spec: [`../bgm/format.md`](../bgm/format.md).
+> Status: current. What's built, what works, what's missing, and the known
+> issues. Spec: [`../bgm/format.md`](../bgm/format.md).
 
 ## What's built
 
@@ -20,9 +20,9 @@
 
 Deps: `marked`, `typed-csv`, `yaml`, `smol-toml`, `picomatch`, `zod`, `vite`, `@types/picomatch`.
 
-### `games/harbor/harbor.md` — example game (new)
+### Example game: harbor (fixture)
 
-Exercises the format end-to-end: package decl, two `file=parts/tokens.yaml` blocks, a table surface with `mount`/`children` and `candidates: $variants` against a virtual csv block, a child player surface, and a setup declaring its enabled `surfaces`. Same content duplicated as the vitest fixture under `packages/bgm/src/__fixtures__/harbor/`.
+Exercises the format end-to-end: package decl, two `file=parts/tokens.yaml` blocks, a table surface with `mount`/`children` and `candidates: $variants` against a virtual csv block, a child player surface, and a setup declaring its enabled `surfaces`. Lives as the vitest fixture under `packages/bgm/src/__fixtures__/harbor/` (and a copy under `packages/tabletop/src/__fixtures__/vite-build/games/harbor/`).
 
 ### `games/poker/poker.md` — example game (new)