Fix /kitedit registration error, add snapshot scope, and document kit commands

[Zaldaryon]

Summary

Two related fixes to the kit commands:

1. /kitedit was registered without a base command privilege, so Vintage Story's command API rejected every invocation before Stratum's own handler ever ran. Fixes Fix /kitedit registration error and document kit commands #293.
2. create's snapshot always included worn armor/clothing with no way to opt out. Adds a per-kit /kitedit setscope <name> all|hotbar so an operator can limit create to the hotbar only. Addresses Add /kitedit scope option to exclude worn armor and clothing from create #295.

Also adds a public command reference for /kit and /kitedit, and a console-driven regression probe in scripts/smoke-test.sh.

Part 1 — #293: registration error

Problem

Reported repro:

/kitedit create starter_kit 1

Server response:

Programming error: Incomplete command - no name or required privilege has been set

Baseline reproduction

Confirmed directly against the pre-fix source by piping the reported command (and several others) into a running server's console:

4.9.2026 14:05:46 [Server Notification] Handling Console Command /kitedit list
4.9.2026 14:05:46 [Server Error] Exception: Programming error: Incomplete command - no name or required privilege has been set
4.9.2026 14:05:47 [Server Notification] Handling Console Command /kitedit create starter_kit 1
4.9.2026 14:05:47 [Server Error] Exception: Programming error: Incomplete command - no name or required privilege has been set

Every /kitedit invocation failed the same way, regardless of action or arguments — the command never reached HandleKitEdit at all.

Root cause

Vintage Story's command builder throws "Incomplete command - no name or required privilege has been set" when a registered command has no base privilege set. /kit in the same file ends its registration with .RequiresPrivilege(Privilege.chat); /kitedit did not have that call. Checked every other Stratum command registration in CmdStratumKits.cs, CmdStratumStaffCommands.cs, and CmdStratumRoles.cs: /kitedit was the only one missing it.

Secondary issues found while fixing this:

• The command was registered with two optional word parsers (name, value), so a third word on a one-argument action (e.g. the reported 1 after create starter_kit) was silently accepted and ignored instead of rejected.
• Several usage strings wrote raw <name> inside TextCommandResult.Error(...); the client's chat renderer treats that as an unknown VTML tag and drops it silently, so the usage hint was invisible.

Fix

sources/VintagestoryLib/Vintagestory.Server/CmdStratumKits.cs:

• Add .RequiresPrivilege(Privilege.chat) to the /kitedit registration. This is the actual fix. The real, configurable gate (Commands.KitEdit / stratum.kitedit, enforced in CheckAccess) is unchanged.
• Add CheckActionArgs/ActionShape, a per-action argument-count table with a usage line, so an action rejects too few or too many arguments with a clear message instead of silently ignoring extras.
• Add UnknownAction, listing valid actions.
• Escape </> as </> in every usage string so it renders in chat.
• Improve both commands' .WithDescription and add .WithAdditionalInformation (shown by /help kit / /help kitedit) with real usage text.

Regression proof

scripts/smoke-test.sh now pipes 8 console commands into the running server after it reaches RunGame and asserts each was dispatched and produced the expected message — including the literal reported command. A console caller always passes Stratum's own access check and has no player entity, so this exercises registration, parsing, and argument handling end to end without a game client.

After the fix:

4.9.2026 14:09:57 [Server Notification] Handling Console Command /kitedit list
4.9.2026 14:09:57 [Server Notification] No kits exist yet. Create one with /kitedit create <name>.
4.9.2026 14:09:58 [Server Notification] Handling Console Command /kitedit create starter_kit 1
4.9.2026 14:09:58 [Server Notification] /kitedit create takes 1 argument. Usage: /kitedit create <name>
4.9.2026 14:09:59 [Server Notification] Handling Console Command /kitedit create starter_kit
4.9.2026 14:09:59 [Server Notification] Only a connected player can snapshot a kit from their own inventory.
4.9.2026 14:10:00 [Server Notification] Handling Console Command /kitedit preview starter_kit
4.9.2026 14:10:00 [Server Notification] No kit named 'starter_kit'.
4.9.2026 14:10:01 [Server Notification] Handling Console Command /kitedit rename starter_kit
4.9.2026 14:10:01 [Server Notification] Usage: /kitedit rename <name> <newName>
4.9.2026 14:10:02 [Server Notification] Handling Console Command /kitedit list extra
4.9.2026 14:10:02 [Server Notification] /kitedit list takes no arguments. Usage: /kitedit list
4.9.2026 14:10:03 [Server Notification] Handling Console Command /kitedit create starter_kit 1 2
4.9.2026 14:10:03 [Server Notification] Command /kitedit, too many arguments
4.9.2026 14:10:04 [Server Notification] Handling Console Command /kit
4.9.2026 14:10:04 [Server Notification] Only a connected player can use /kit.

PASS: server reached RunGame, no fatal errors, 8 console command(s) verified. (last phase: WorldReady)

Also fixed en route: smoke-test.sh launched the server with cwd=repo root. Mono.Cecil's default assembly resolver searches the process's current directory when resolving mod references; from repo root it failed to resolve VintagestoryAPI, which silently dropped every mod (including the base game content mod) and made the server crash before RunGame on every run, independent of this fix. Now launches from the server's own directory.

Manual verification (done)

Ran a real Stratum server locally, connected with the stock client using the maintainer's normal account, and exercised the full command surface by hand: /kitedit create, preview, additem, removeitem, /kit, /kit <name>, and /help kitedit. Create, preview, item add/remove, redeem, and the give-back all worked end to end with a real inventory.

This manual pass is what surfaced the #295 follow-up below: the maintainer noticed create picked up worn armor/clothing along with the hotbar contents. That is correct per the original #210/#269 design (StratumKitGiver's own comments confirm armor placement was always intentional), just not something an operator could opt out of before this PR.

Part 2 — #295: snapshot scope

Problem

create always walks hotbar + character inventory together, so worn armor/clothing is captured with no way to opt out. Confirmed by manual testing above.

Fix

sources/VintagestoryLib/Vintagestory.Server/CmdStratumKits.cs, StratumKitStore.cs:

• StratumKitDefinition.Scope ("all" default, or "hotbar").
• /kitedit setscope <name> all|hotbar, added to the action table and argument validation the same way every other action is.
• SnapshotInventory takes the kit's scope: all walks hotbar + character (current behavior, unchanged), hotbar walks only the hotbar (offhand included, since it's the same inventory).
• create reads existing?.Scope ?? "all" so a brand-new kit keeps today's default and a re-create respects whatever setscope set.
• preview shows the current scope.

Scope is a kit property applied on the next create, not retroactive to an already-stored item list — same model as setrole/setcooldown/the on/off flags.

Regression proof

A console caller has no player entity, so this path cannot be exercised by the public smoke test (which is console-driven). Instead, added Create_scope_all_includes_worn_armor_hotbar_excludes_it to the private Atlas regression suite (research/atlas-tests/stratum-pr-validation/KitScenarios.cs, not part of this public repo): a real test player is given a hotbar item and has armor equipped into a real character inventory slot, then:

• /kitedit create with default scope all → resulting kit's items include both the hotbar item and the armor.
• /kitedit setscope <name> hotbar → Find(...).Scope == "hotbar".
• /kitedit create again → resulting kit's items include the hotbar item, not the armor.
• /kitedit preview output contains "hotbar".
• /kitedit setscope <name> everything (invalid value) → rejected with the usage line.

Passed!  - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: 575 ms

Ran the full KitScenarios class alongside it: 4 passed (including this new one), 1 pre-existing failure (Respawn_gives_assigned_kits_skips_unassigned_and_marks_one_per_life) — a real-time polling scenario on a code path this PR does not touch (OnPlayerRespawn / GiveAssignedRespawnKits), timing out at 600 ticks in this sandboxed environment. Not a regression from either change here.

Documentation

docs/commands/kits.md: full reference for /kit and /kitedit, including setscope, the scope's effect on create, and a symbol-to-behavior sync table so a future implementation change is easy to spot as needing a doc update.

Gates run

• dotnet build VintageStory.slnx -c Release -p:EmbedPatchedFiles=true — 0 errors, 0 new warnings on touched files.
• bash scripts/smoke-test.sh — PASS (log above), covers Fix /kitedit registration error and document kit commands #293.
• Atlas KitScenarios (private suite) — covers Add /kitedit scope option to exclude worn armor and clothing from create #295's scope behavior against a real player/inventory.
• Manual verification with a real connected client — done (see Part 1).
• git diff --check clean.

Limitations

• scripts/smoke-test.ps1 was not extended with the console command probe and not re-verified on Windows; it now has a note pointing to the bash probe. The coverage for Fix /kitedit registration error and document kit commands #293 is bash-only for now.
• Noticed independently, not fixed here: smoke-test.ps1 prefers VintagestoryServer.exe over StratumServer.exe, the opposite of smoke-test.sh's (correct) preference — likely boot-tests unpatched vanilla on Windows. Worth its own issue.
• Noticed independently, not fixed here: the same raw-angle-bracket usage-string defect this PR fixes in CmdStratumKits.cs also exists in CmdStratumStaffCommands.cs and CmdStratumRoles.cs. Left out to keep this PR scoped.
• Also noticed: dotnet build VintageStory.slnx -p:EmbedPatchedFiles=true needs to be run twice, and StratumServer needs to actually be launched once, for its embedded/overlaid VintagestoryLib.dll to pick up a same-session code change. Not fixed here (build/overlay pipeline issue, outside this file's scope) but worth knowing when verifying any patch through StratumServer locally.
• setscope does not retroactively filter an existing kit's stored items; documented, not a bug.

Risk

Low. sources/-only changes, no vanilla patch touched. .RequiresPrivilege(Privilege.chat) is the loosest possible base gate and matches every sibling command; no player loses access they had. The new scope defaults to all, so no existing kit's behavior changes unless an operator explicitly opts it into hotbar.

Type

• Bug fix
• New feature
• Docs or build

Checklist

• scripts/extract-patches.sh ran clean (unrelated pre-existing working-tree drift in this environment was discarded before committing; only the intended files are in this diff).
• dotnet build VintageStory.slnx -c Release is green.
• Every vanilla edit has a // Stratum marker. (N/A — no vanilla file touched; CmdStratumKits.cs/StratumKitStore.cs are Stratum-only under sources/.)
• No vanilla source committed.
• Tested on a real server start, not just compilation.

Related issues

Fixes #293
Fixes #295

Related: #210 (original feature request), #269 (original implementation).