Move command metadata authority to server

client/public/version.js

@@ -1,5 +1,5 @@
 // Maintainer-controlled web client version.
 // Format: YYYY.MM.DD Rn (example: 2026.02.20 R2)
-window.CHGRID_WEB_VERSION = "2026.03.08 R335";
+window.CHGRID_WEB_VERSION = "2026.03.08 R336";
 // Optional display timezone for timestamps. Falls back to America/Detroit if unset/invalid.
 window.CHGRID_TIME_ZONE = "America/Detroit";

client/src/items/itemRegistry.ts

@@ -17,6 +17,22 @@ export type ItemPropertyMetadata = {
 };
 
 type UiDefinitionsPayload = {
+  commandMetadata?: {
+    mainModeActions?: Array<{
+      id: string;
+      label?: string;
+      tooltip?: string;
+    }>;
+  };
+  itemManagement?: {
+    actions?: Array<{
+      id: string;
+      label?: string;
+      tooltip?: string;
+      anyPermission?: string;
+      ownPermission?: string;
+    }>;
+  };
   itemTypeOrder?: ItemType[];
   itemTypes?: Array<{
     type: ItemType;
@@ -28,6 +44,17 @@ type UiDefinitionsPayload = {
     globalProperties?: Record<string, unknown>;
   }>;
 };
+
+type ServerCommandMetadata = {
+  label?: string;
+  tooltip?: string;
+};
+
+type ItemManagementActionMetadata = ServerCommandMetadata & {
+  anyPermission?: string;
+  ownPermission?: string;
+};
+
 let itemTypeSequence: ItemType[] = [];
 let itemTypeLabels: Partial<Record<ItemType, string>> = {};
 let itemTypeTooltips: Partial<Record<ItemType, string>> = {};
@@ -36,6 +63,8 @@ let itemTypeCapabilities: Partial<Record<ItemType, string[]>> = {};
 let itemTypeGlobalProperties: Partial<Record<ItemType, Record<string, string | number | boolean>>> = {};
 let itemTypePropertyMetadata: Partial<Record<ItemType, Record<string, ItemPropertyMetadata>>> = {};
 let propertyLabelByKey: Record<string, string> = {};
+let mainModeCommandMetadataById: Record<string, ServerCommandMetadata> = {};
+let itemManagementActionMetadataById: Record<string, ItemManagementActionMetadata> = {};
 
 export let EDITABLE_ITEM_PROPERTY_KEYS = new Set<string>(
   Object.values(itemTypeEditableProperties).flatMap((keys) => keys ?? []),
@@ -150,6 +179,16 @@ export function getItemTypeCapabilities(itemType: ItemType): string[] {
   return [...(itemTypeCapabilities[itemType] ?? [])];
 }
 
+/** Returns server-authored metadata for one server-backed main-mode command id. */
+export function getServerMainModeCommandMetadata(commandId: string): ServerCommandMetadata | undefined {
+  return mainModeCommandMetadataById[commandId];
+}
+
+/** Returns server-authored metadata for one item-management action id. */
+export function getItemManagementActionMetadata(actionId: string): ItemManagementActionMetadata | undefined {
+  return itemManagementActionMetadataById[actionId];
+}
+
 /** Returns human-facing label for a property key. */
 export function itemPropertyLabel(key: string): string {
   const metadataLabel = propertyLabelByKey[key];
@@ -237,6 +276,8 @@ export function applyServerItemUiDefinitions(uiDefinitions: UiDefinitionsPayload
     itemTypeGlobalProperties = {};
     itemTypePropertyMetadata = {};
     propertyLabelByKey = {};
+    mainModeCommandMetadataById = {};
+    itemManagementActionMetadataById = {};
     rebuildEditablePropertyKeySet();
     return false;
   }
@@ -253,6 +294,8 @@ export function applyServerItemUiDefinitions(uiDefinitions: UiDefinitionsPayload
   const nextGlobals: Partial<Record<ItemType, Record<string, string | number | boolean>>> = {};
   const nextPropertyMetadata: Partial<Record<ItemType, Record<string, ItemPropertyMetadata>>> = {};
   const nextPropertyLabels: Record<string, string> = {};
+  const nextMainModeCommandMetadata: Record<string, ServerCommandMetadata> = {};
+  const nextItemManagementActionMetadata: Record<string, ItemManagementActionMetadata> = {};
 
   for (const definition of uiDefinitions.itemTypes) {
     if (!definition || typeof definition.type !== 'string') continue;
@@ -295,6 +338,28 @@ export function applyServerItemUiDefinitions(uiDefinitions: UiDefinitionsPayload
     discoveredOrder.push(definition.type as ItemType);
   }
 
+  for (const action of uiDefinitions.commandMetadata?.mainModeActions ?? []) {
+    const id = String(action?.id ?? '').trim();
+    if (!id) continue;
+    nextMainModeCommandMetadata[id] = {
+      label: typeof action?.label === 'string' && action.label.trim().length > 0 ? action.label.trim() : undefined,
+      tooltip: typeof action?.tooltip === 'string' && action.tooltip.trim().length > 0 ? action.tooltip.trim() : undefined,
+    };
+  }
+
+  for (const action of uiDefinitions.itemManagement?.actions ?? []) {
+    const id = String(action?.id ?? '').trim();
+    if (!id) continue;
+    nextItemManagementActionMetadata[id] = {
+      label: typeof action?.label === 'string' && action.label.trim().length > 0 ? action.label.trim() : undefined,
+      tooltip: typeof action?.tooltip === 'string' && action.tooltip.trim().length > 0 ? action.tooltip.trim() : undefined,
+      anyPermission:
+        typeof action?.anyPermission === 'string' && action.anyPermission.trim().length > 0 ? action.anyPermission.trim() : undefined,
+      ownPermission:
+        typeof action?.ownPermission === 'string' && action.ownPermission.trim().length > 0 ? action.ownPermission.trim() : undefined,
+    };
+  }
+
   itemTypeLabels = nextLabels;
   itemTypeTooltips = nextTooltips;
   itemTypeEditableProperties = nextEditable;
@@ -302,6 +367,8 @@ export function applyServerItemUiDefinitions(uiDefinitions: UiDefinitionsPayload
   itemTypeGlobalProperties = nextGlobals;
   itemTypePropertyMetadata = nextPropertyMetadata;
   propertyLabelByKey = nextPropertyLabels;
+  mainModeCommandMetadataById = nextMainModeCommandMetadata;
+  itemManagementActionMetadataById = nextItemManagementActionMetadata;
   itemTypeSequence = explicitOrder ?? discoveredOrder;
   rebuildEditablePropertyKeySet();
   return itemTypeSequence.length > 0;

client/src/main.ts

@@ -47,6 +47,8 @@ import {
 } from './state/gameState';
 import {
   applyServerItemUiDefinitions,
+  getItemManagementActionMetadata,
+  getServerMainModeCommandMetadata,
   getItemTypeGlobalProperties,
   getItemTypeSequence,
   getEditableItemPropertyKeys,
@@ -192,6 +194,7 @@ type AuthPolicy = {
 type AdminMenuAction = {
   id: string;
   label: string;
+  tooltip?: string;
 };
 
 type AdminRoleSummary = {
@@ -220,6 +223,7 @@ type ItemManagementAction = 'delete' | 'transfer';
 type ItemManagementOption = {
   action: ItemManagementAction;
   label: string;
+  tooltip?: string;
 };
 
 type ItemManagementConfirmContext = {
@@ -650,11 +654,12 @@ function applyAuthPermissions(role: string | null | undefined, permissions: stri
 }
 
 /** Applies server-authored admin menu actions for current session. */
-function applyServerAdminMenuActions(actions: Array<{ id: string; label: string }> | null | undefined): void {
+function applyServerAdminMenuActions(actions: Array<{ id: string; label: string; tooltip?: string }> | null | undefined): void {
   serverAdminMenuActions = (actions || [])
     .map((entry) => ({
       id: String(entry.id || '').trim(),
       label: String(entry.label || '').trim(),
+      tooltip: typeof entry.tooltip === 'string' && entry.tooltip.trim().length > 0 ? entry.tooltip.trim() : undefined,
     }))
     .filter((entry) => entry.id.length > 0 && entry.label.length > 0);
 }
@@ -1064,24 +1069,36 @@ function beginItemSelection(
 
 /** Returns whether the local user can delete the provided item. */
 function canManageDeleteItem(item: WorldItem): boolean {
-  if (hasPermission('item.delete.any')) return true;
+  const metadata = getItemManagementActionMetadata('delete');
-  return hasPermission('item.delete.own') && authUserId.length > 0 && item.createdBy === authUserId;
+  if (metadata?.anyPermission && hasPermission(metadata.anyPermission)) return true;
+  return Boolean(metadata?.ownPermission) && hasPermission(metadata.ownPermission) && authUserId.length > 0 && item.createdBy === authUserId;
 }
 
 /** Returns whether the local user can transfer the provided item. */
 function canManageTransferItem(item: WorldItem): boolean {
-  if (hasPermission('item.transfer.any')) return true;
+  const metadata = getItemManagementActionMetadata('transfer');
-  return hasPermission('item.transfer.own') && authUserId.length > 0 && item.createdBy === authUserId;
+  if (metadata?.anyPermission && hasPermission(metadata.anyPermission)) return true;
+  return Boolean(metadata?.ownPermission) && hasPermission(metadata.ownPermission) && authUserId.length > 0 && item.createdBy === authUserId;
 }
 
 /** Builds available item-management actions for one selected item. */
 function itemManagementOptionsFor(item: WorldItem): ItemManagementOption[] {
   const options: ItemManagementOption[] = [];
+  const transferMetadata = getItemManagementActionMetadata('transfer');
   if (canManageTransferItem(item) && (state.player.id !== null || state.peers.size > 0)) {
-    options.push({ action: 'transfer', label: 'Transfer item' });
+    options.push({
+      action: 'transfer',
+      label: transferMetadata?.label ?? 'Transfer item',
+      tooltip: transferMetadata?.tooltip,
+    });
   }
+  const deleteMetadata = getItemManagementActionMetadata('delete');
   if (canManageDeleteItem(item)) {
-    options.push({ action: 'delete', label: 'Delete item' });
+    options.push({
+      action: 'delete',
+      label: deleteMetadata?.label ?? 'Delete item',
+      tooltip: deleteMetadata?.tooltip,
+    });
   }
   return options;
 }
@@ -2570,6 +2587,8 @@ function getAvailableCommandPaletteEntriesForMode(mode: GameMode): Array<Command
     });
     return descriptors.map((descriptor) => ({
       ...descriptor,
+      label: getServerMainModeCommandMetadata(descriptor.id)?.label ?? descriptor.label,
+      tooltip: getServerMainModeCommandMetadata(descriptor.id)?.tooltip ?? descriptor.tooltip,
       run: mainModeCommandHandlers[descriptor.id],
     }));
   }
@@ -3054,6 +3073,11 @@ function handleItemManageOptionsModeInput(code: string, key: string): void {
     audio.sfxUiBlip();
     return;
   }
+  if (code === 'Space') {
+    updateStatus(itemManagementOptions[itemManagementOptionIndex]?.tooltip ?? 'No tooltip available.');
+    audio.sfxUiBlip();
+    return;
+  }
   if (control.type === 'select') {
     const option = itemManagementOptions[itemManagementOptionIndex];
     if (option.action === 'delete') {
@@ -3176,6 +3200,11 @@ function handleAdminMenuModeInput(code: string, key: string): void {
     audio.sfxUiBlip();
     return;
   }
+  if (code === 'Space') {
+    updateStatus(adminMenuActions[adminMenuIndex]?.tooltip ?? 'No tooltip available.');
+    audio.sfxUiBlip();
+    return;
+  }
   if (control.type === 'select') {
     const selected = adminMenuActions[adminMenuIndex];
     if (!selected) return;

client/src/network/protocol.ts

@@ -1,5 +1,11 @@
 import { z } from 'zod';
 
+const actionMetadataSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  tooltip: z.string().optional(),
+});
+
 export const itemSchema = z.object({
   id: z.string(),
   type: z.string().min(1),
@@ -59,7 +65,7 @@ export const welcomeMessageSchema = z.object({
       username: z.string().nullable().optional(),
       role: z.string().nullable().optional(),
       permissions: z.array(z.string()).optional(),
-      adminMenuActions: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
+      adminMenuActions: z.array(actionMetadataSchema).optional(),
       policy: z
         .object({
           usernameMinLength: z.number().int().positive(),
@@ -105,7 +111,22 @@ export const welcomeMessageSchema = z.object({
       ),
       adminMenu: z
         .object({
-          actions: z.array(z.object({ id: z.string(), label: z.string() })),
+          actions: z.array(actionMetadataSchema),
+        })
+        .optional(),
+      commandMetadata: z
+        .object({
+          mainModeActions: z.array(actionMetadataSchema).optional(),
+        })
+        .optional(),
+      itemManagement: z
+        .object({
+          actions: z.array(
+            actionMetadataSchema.extend({
+              anyPermission: z.string().optional(),
+              ownPermission: z.string().optional(),
+            }),
+          ),
         })
         .optional(),
     })
@@ -133,7 +154,7 @@ export const authResultSchema = z.object({
   username: z.string().optional(),
   role: z.string().optional(),
   permissions: z.array(z.string()).optional(),
-  adminMenuActions: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
+  adminMenuActions: z.array(actionMetadataSchema).optional(),
   nickname: z.string().optional(),
   authPolicy: z
     .object({
@@ -289,7 +310,7 @@ export const authPermissionsSchema = z.object({
   type: z.literal('auth_permissions'),
   role: z.string(),
   permissions: z.array(z.string()),
-  adminMenuActions: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
+  adminMenuActions: z.array(actionMetadataSchema).optional(),
 });
 
 const adminRoleSummarySchema = z.object({

docs/controls.md

@@ -33,6 +33,7 @@ This document is the authoritative keymap for the client.
 - `Shift+O`: Inspect all item properties
 - `D`: Pick up/drop item
 - `Z`: Item management menu (delete/transfer when permitted)
+- `Space` in item management menu: Read tooltip/help for the selected action
 - `Enter`: Use item
 - `Shift+Enter`: Secondary item action
 
@@ -104,6 +105,7 @@ Applies to effect select, user/item list modes, item selection, item property li
 ## Admin Modes
 
 - `Shift+Z`: Open admin menu
+- `Space` on admin root actions: Read tooltip/help for the selected action
 - Admin menu options are permission-gated and include:
   - role management
   - change user role

docs/protocol-notes.md

@@ -111,7 +111,9 @@ This is a behavior guide for packet semantics beyond raw schemas.
   - `itemTypes[].editableProperties`: editable property keys by item type
   - `itemTypes[].propertyMetadata`: property-level metadata (`valueType`, optional `label`, optional `range`, optional `tooltip`, optional `maxLength`, optional `options`, optional `visibleWhen`)
   - `itemTypes[].globalProperties`: non-editable global values (`useSound`, `emitSound`, `useCooldownMs`, `emitRange`, `directional`, `emitSoundSpeed`, `emitSoundTempo`, `emitInitialDelay`, `emitLoopDelay`)
-  - `adminMenu.actions`: server-authored admin root menu labels/ordering for the authenticated user.
+  - `commandMetadata.mainModeActions`: server-authored labels/tooltips for server-backed main-mode commands used by the client command palette
+  - `itemManagement.actions`: server-authored labels/tooltips and permission-key metadata for item-management actions (`transfer`, `delete`)
+  - `adminMenu.actions`: server-authored admin root menu labels/tooltips/ordering for the authenticated user
 - Client item UI requires this metadata from the server; there is no fallback item definition map.
 - Client property help/type rendering is metadata-driven; it does not infer fallback types/tooltips from hardcoded key heuristics.
 - `visibleWhen` supports equality checks and string negation via `!` prefix (example: `{"mediaEffect": "!off"}`).

docs/runtime-flow.md

@@ -20,7 +20,7 @@
   - uses `welcome.player` as authoritative starting position (restored from server-side account state when available)
    - records `welcome.serverInfo` (`instanceId`, `version`) for restart detection
    - if `welcome.serverInfo.version` differs from running client version, auto-reloads the page
-   - applies `welcome.uiDefinitions` for item menus/properties/options and admin menu labels/order
+   - applies `welcome.uiDefinitions` for item menus/properties/options, server-backed command metadata, item-management metadata, and admin menu labels/order
    - sends initial `update_position` echo from server-assigned starting tile
    - sends initial `update_nickname`
    - creates peer runtimes for known users

server/app/server.py

@@ -134,11 +134,42 @@ AUTH_SESSION_COOKIE_CLIENT_HEADER = "X-Chgrid-Auth-Client"
 AUTH_LOGIN_FAILURE_MESSAGE = "We couldn't log you in. Check your details and try again."
 AUTH_RESUME_FAILURE_MESSAGE = "We couldn't restore your session. Please log in again."
 ADMIN_MENU_ACTION_DEFINITIONS: tuple[dict[str, str], ...] = (
-    {"id": "manage_roles", "label": "Role management", "permission": "role.manage"},
+    {"id": "manage_roles", "label": "Role management", "tooltip": "Manage roles and their permission sets.", "permission": "role.manage"},
-    {"id": "change_user_role", "label": "Change user role", "permission": "user.change_role"},
+    {"id": "change_user_role", "label": "Change user role", "tooltip": "Change a user's assigned role.", "permission": "user.change_role"},
-    {"id": "ban_user", "label": "Ban user", "permission": "user.ban_unban"},
+    {"id": "ban_user", "label": "Ban user", "tooltip": "Disable a user account.", "permission": "user.ban_unban"},
-    {"id": "unban_user", "label": "Unban user", "permission": "user.ban_unban"},
+    {"id": "unban_user", "label": "Unban user", "tooltip": "Re-enable a disabled user account.", "permission": "user.ban_unban"},
-    {"id": "delete_account", "label": "Delete account", "permission": "account.delete.any"},
+    {"id": "delete_account", "label": "Delete account", "tooltip": "Delete a user account permanently.", "permission": "account.delete.any"},
+)
+
+ITEM_MANAGEMENT_ACTION_DEFINITIONS: tuple[dict[str, str], ...] = (
+    {
+        "id": "transfer",
+        "label": "Transfer item",
+        "tooltip": "Transfer this item to another user.",
+        "anyPermission": "item.transfer.any",
+        "ownPermission": "item.transfer.own",
+    },
+    {
+        "id": "delete",
+        "label": "Delete item",
+        "tooltip": "Delete this item from the world.",
+        "anyPermission": "item.delete.any",
+        "ownPermission": "item.delete.own",
+    },
+)
+
+MAIN_MODE_SERVER_COMMAND_DEFINITIONS: tuple[dict[str, str], ...] = (
+    {"id": "addItem", "label": "Add item", "tooltip": "Open the add-item menu."},
+    {"id": "useItem", "label": "Use item", "tooltip": "Use the carried item or a usable item on your current square."},
+    {
+        "id": "secondaryUseItem",
+        "label": "Secondary item action",
+        "tooltip": "Run the secondary action for the carried item or a usable item on your current square.",
+    },
+    {"id": "pickupDropItem", "label": "Pick up or drop item", "tooltip": "Pick up an item or drop your carried item."},
+    {"id": "openItemManagement", "label": "Item management", "tooltip": "Open item management actions for items on your square."},
+    {"id": "editItem", "label": "Edit item properties", "tooltip": "Edit the carried item or an item on your current square."},
+    {"id": "inspectItem", "label": "Inspect item properties", "tooltip": "Inspect all properties for the carried item or an item on your current square."},
 )
 
 
@@ -347,7 +378,7 @@ class SignalingServer:
             return []
         client_permissions = client.permissions or set()
         return [
-            {"id": action["id"], "label": action["label"]}
+            {"id": action["id"], "label": action["label"], "tooltip": action["tooltip"]}
             for action in ADMIN_MENU_ACTION_DEFINITIONS
             if action["permission"] in client_permissions
         ]
@@ -1695,6 +1726,8 @@ class SignalingServer:
         return {
             "itemTypeOrder": list(ITEM_TYPE_SEQUENCE),
             "itemTypes": item_types,
+            "commandMetadata": {"mainModeActions": list(MAIN_MODE_SERVER_COMMAND_DEFINITIONS)},
+            "itemManagement": {"actions": list(ITEM_MANAGEMENT_ACTION_DEFINITIONS)},
             "adminMenu": {"actions": self._build_admin_menu_actions_for_client(client)},
         }