docs: rewrite bnstoolkit handoff for feature-complete state

The original handoff doc described an empty M0 scaffold with placeholder
screens to "discuss tomorrow". 0.3.1 actually ships the full UI plus
villager trade rebalance, so the doc now is a testing guide for the
working features rather than a discussion-points list.

Includes the architecture diagram for how Java + KubeJS interact, the
key bindings table, a step-by-step testing path, and a known-gaps list
for future iteration.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/bnstoolkit-discussion-points-2026-06-07.md

@@ -1,143 +1,114 @@
-# bnstoolkit M0 — discussion points for testing session
+# bnstoolkit feature-complete — testing notes for 2026-06-07 evening
 
-> Built 2026-06-07 (early hours UTC). Shipped via pack v0.34.0.
+> Shipped: pack v0.35.0 / bnstoolkit 0.3.1.
 > Repo: http://10.16.5.102:3000/minecraft/bnstoolkit
-> Jar: `bnstoolkit-0.1.0.jar` (15.6 KB)
+> Server status: ✅ live + verified at 02:41 UTC.
 
-## What this is
+## What's in the build
 
-The skeleton of the custom companion mod. It loads cleanly on the client
+### 5 screens (FTB Library widgets — matches FTB Quests look)
-and the dedicated server, registers nothing visible yet, and exposes the
-package layout we'll fill in over M1–M4. The point of this milestone is:
 
-1. Tooling proven end-to-end (Java 21, ModDevGradle, NeoForge 21.1.228, jar in pack)
+All opened via key bindings. Rebindable in vanilla controls menu under
-2. Mod-id, package, and resource paths locked so future commits only ADD code
+"Brass and Sigil" category.
-3. One C2S/S2C packet pair wired to prove the network plumbing
-4. Placeholder screens in place so wiring keybinds to real UI is M1's first task
 
-## Open decisions — please walk through these tomorrow
+| Key | Screen | What it does |
-
-Each is marked with `TODO(matt …)` in the source.
-
-### 1. Key bindings (BnsKeyBindings.java)
-
-Defaults I picked, all unbinding is in the vanilla controls menu:
-
-| Binding | Key | Opens |
 |---|---|---|
-| Tier ladder | T | `TierUpgradeScreen` |
+| **K** | Civic Tier ladder | 13 rows, current tier highlighted. Right pane shows next tier's cost + perks + Upgrade button. Disabled if you can't afford it or are at Sovereign. |
-| Bounty board | B | `BountyBoardScreen` |
+| **J** | Bounty Board | Today's 5-bounty pool + any active set. Detail pane: target, count, reward, progress. Accept / Cancel / Turn In buttons by state. |
-| Plot map | P | `PlotPurchaseScreen` |
+| **N** | Plot Office | Plot list with ownership state-coding (yours / taken / free). Detail pane: size, chunks, price. Buy / Release buttons. |
+| **H** | Bazaar shop | 9-cell sell item grid. Click an item, see DR-aware effective price for current tier. Sell 1 / 16 / 64 quick buttons. |
+| **M** | Quest Log | At-a-glance status: tier + balance + active bounties (with progress bars) + owned plots. |
 
-**Question**: any conflicts with mods you already use? `T` is vanilla's
+### HUD overlay
-chat-open IIRC — I should probably move it. Pick a free combo when you
-playtest, I'll bump the defaults.
 
-### 2. Screen open triggers — keybind only, or block + keybind?
+Top-left of the screen, always visible: `<tier-colour><tier-name>` on
+one line, `<balance> spurs` on the second. Refreshes 1Hz from server
+push — picks up coin pickups immediately, no inventory polling.
 
-Each major screen has two viable open paths:
+Auto-hides when F1 is pressed or chat is open (standard NeoForge HUD
+layer behavior).
 
-- **Keybind** (already drafted): bnstoolkit binds T/B/P
+### Villager trade rebalance
-- **In-world block**: e.g. a "Bounty Board" block placed at the spawn
-  guild building. Right-click opens the screen. More immersive, ties the
-  feature to a physical location.
 
-Both can coexist easily — they're not exclusive. I'd default to "both for
+Every emerald cost or result in vanilla + modded villager trades is
-TierUpgrade + Plots, keybind-only for QuestLog, block-only for ShopBrowser
+now Numismatics:
-and BountyBoard". But that's a 30-second call you make tomorrow.
+- 1..7 emeralds → spurs
+- 8..63 → bevels (1 bevel = 8 spurs)
+- 64+ → cogs (1 cog = 64 spurs)
 
-### 3. FTB Library UI swap timing
+Works automatically on:
+- All 14 vanilla villager professions
+- Wandering trader (generic + rare)
+- Any modded villager professions (we wrap the event's list, no enum
+  of professions needed)
 
-Right now the placeholder screens extend vanilla `Screen`. The
+This was the "blocked on API" item. Built it into bnstoolkit instead
-architecture doc commits to `dev.ftb.mods.ftblibrary.ui.BaseScreen` for
+of pulling a third-party mod, because the cleanest Modrinth option
-visual consistency with FTB Quests / Chunks. The swap is one line per
+needed NeoForge 21.1.230+ and we're on 228.
-screen — happens in M1 alongside the first real screen layout.
 
-Reason it's deferred: the FTB maven coords need to be wired into
+## Testing path
-`build.gradle`, and I don't want to pin the wrong artifact name. Will
-verify against the pack's installed FTB Library version (2101.1.31) before
-the M1 build.
-
-### 4. HUD overlay layout
-
-The architecture doc shows a small panel "tier-icon | tier-name | spurs"
-at top-left. Drop me a sketch when you have time and I'll lay it out for
-M4. Current placeholder draws nothing — won't appear in game at all yet.
-
-### 5. Network smoke-test packet
-
-`RequestTierStatePacket` / `TierStateUpdatePacket` are the only wire
-pair I shipped. They prove the codec + handler pattern. M1 fills in the
-server-side handler that reads `player.persistentData.bnsTier` (the
-KubeJS-owned NBT) and replies. **No client code yet sends the request** —
-the round trip is dormant in M0.
-
-### 6. Mod settings screen
-
-Not addressed. Will be a small screen in M4 with toggles for the HUD,
-keybind reminders, and (eventually) a colour-blind mode for tier ranks.
-Low priority unless you've got a specific UX concern.
-
----
-
-## Files added/changed (PR for v0.34.0)
 
 ```
-pack/overrides/mods/bnstoolkit-0.1.0.jar           NEW (15.6 KB)
+/bns me                            # confirm Peasant tier 1
-pack/pack.lock.json                                version 0.33.0 -> 0.34.0
+/give @s numismatics:spur 500      # give spurs for upgrades
-docs/bnstoolkit-discussion-points-2026-06-07.md    NEW (this file)
+K                                  # open tier ladder
+# click Upgrade — should pay 200 and bump you to Farmer
+
+/bns admin tier set <you> 5        # jump to Knight for plot testing
+K                                  # confirm new tier visible
+H                                  # open bazaar
+# click diamond, click Sell 1 (you'll need a diamond in inventory)
+J                                  # open bounty board, accept one
+# kill the target mobs — progress shows in chat AND the screen
+# turn in via the J screen
+N                                  # open plot office, buy p001
+M                                  # quest log shows everything
+
+# Test villager trades:
+/summon villager ~ ~ ~
+# Right-click the villager once it picks a profession (place a workstation)
+# Trades should show spurs/bevels/cogs instead of emeralds
 ```
 
-The bnstoolkit source itself lives at `http://10.16.5.102:3000/minecraft/bnstoolkit`
+## Architecture
-— one initial commit on `main` with the full M0 scaffold. Build:
 
 ```
-cd /home/matt/dev/bnstoolkit
+KubeJS server_scripts/economy/    ← single source of truth for state + logic
-./gradlew build
+                ↑
+                │ (chat commands via server.getCommands)
+                │
+ServerEconomyBridge.java          ← reads NBT, sums Numismatics coins,
+                                    routes write verbs through /bns
+                ↑↓
+       4 snapshot + 2 command packets
+                ↑↓
+ClientBnsState.java               ← single static state holder
+                ↑
+        Screens read this each frame
 ```
 
-## What you'll see in-game when you log in
+Source of truth stays in KubeJS. Java is just the UI layer and a thin
+write-path proxy. If you want to rebalance prices or add bounties, you
+do it in KubeJS — Java auto-reflects.
 
-**Nothing yet.** That's the point of M0 — it loads cleanly with zero
+## Known gaps for future iteration
-visible surface. Verification path:
 
-1. Server log: grep for `[bnstoolkit] mod entry constructed` and
+| Gap | Where to fix |
-   `common setup complete (M0 scaffold — no surface yet)`
+|---|---|
-2. Client log on connect: `registered 3 key bindings under key.category.bnstoolkit`
+| No client toast notifications — feedback comes via KubeJS chat messages | Add a dist-isolated `ClientToastDispatcher` class (0.4.0) |
-3. Controls menu → "Brass and Sigil" category → 3 unbound-looking lines
+| Bazaar grid doesn't tooltip the per-unit price | One `addMouseOverText` per `ItemCell` |
-   (Open Tier Ladder, Open Bounty Board, Open Plot Map) on T/B/P
+| Plot office doesn't show a minimap | Render bluemap PNG snippet as background or use FTB Chunks' map widget |
+| Quest log doesn't show FTB Quests progression | Hook into FTB Quests' API once first chapter ships |
+| Numismatics coins as bunch — no fractional change | Bazaar pays in highest denom that fits; player converts at the Bank |
+| Wanderer rare-trade rebalance is greedy (every rare item costs are converted) | Profession-aware exclusion list if anything weird sneaks through |
 
-If you bind one of those keys and press it in-game, **nothing happens**.
+## File map
-That's correct — the handlers are M1 work.
 
-## Milestones — concrete next deliverables
+| File | Purpose |
+|---|---|
+| `pack/overrides/mods/bnstoolkit-0.3.1.jar` | The mod itself (95 KB) |
+| `pack/overrides/kubejs/server_scripts/economy/*.js` | State + business logic (unchanged from v0.33.0) |
+| `pack/overrides/world/serverconfig/ftbranks/ranks.snbt` | 13-tier rank config (unchanged) |
+| `docs/bnstoolkit-architecture.md` | Original architecture spec |
 
-| Milestone | Scope | Estimated work |
+Source repo: http://10.16.5.102:3000/minecraft/bnstoolkit (main = 14dc69f at time of pack ship).
-|---|---|---|
-| M1 | TierUpgradeScreen + KubeJS bridge (tier/balance) + FTB Library swap | 1 evening |
-| M2 | QuestLogScreen + ShopBrowserScreen | 1 evening |
-| M3 | BountyBoardScreen + PlotPurchaseScreen | 1 evening |
-| M4 | SpurHud, mod settings screen, polish | 1 evening |
-
-Each milestone ends with a deployable jar + a screen you can poke in
-game. None of them require server downtime — drop the new jar in
-`pack/overrides/mods/`, the wrapper sync handles the rest.
-
-## Quick recovery
-
-If the mod misbehaves and bricks the world:
-
-```
-# 1. Stop the server
-sudo systemctl stop brass-sigil-server.service
-
-# 2. Pull the jar out of the live mods dir
-sudo rm /srv/fast/brass-sigil-server/server/mods/bnstoolkit-0.1.0.jar
-
-# 3. Restart
-sudo systemctl start brass-sigil-server.service
-```
-
-That leaves `pack/overrides/mods/bnstoolkit-0.1.0.jar` in the pack repo
-so the next sync would put it back — to fully revert, also `git revert`
-the v0.34.0 commit on the pack.

pack/pack.lock.json

@@ -1,13 +1,13 @@
 {
   "$schema": "Brass-and-Sigil pack.lock.json - generated, do not edit by hand unless you know what you are doing",
   "name": "Brass and Sigil",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "minecraft": "1.21.1",
   "loader": {
     "type": "neoforge",
     "version": "21.1.228"
   },
-  "lockedAt": "2026-06-07T00:18:08Z",
+  "lockedAt": "2026-06-07T02:33:07Z",
   "mods": [
     {
       "source": "modrinth",