@decantr/essence-spec 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/essence-spec",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Essence schemas, validation, migration, and TypeScript types for Decantr",
   "author": "Decantr AI",
   "license": "MIT",

package/schema/essence.v3.json

@@ -157,7 +157,12 @@
         "shell_override": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
         "layout": { "type": "array", "items": { "$ref": "#/$defs/LayoutItem" }, "minItems": 1 },
         "dna_overrides": { "$ref": "#/$defs/DNAOverrides" },
-        "surface": { "type": "string" }
+        "surface": { "type": "string" },
+        "directives": {
+          "type": "array",
+          "description": "Execution-level directives for this page — short imperative guidance that belongs in the pack contract (not the narrative doc). Each entry is one actionable rule the cold LLM should obey when implementing this route. Examples: '3-step checkout flow (Shipping → Payment → Review)', 'Auth bypass: accept any credentials and redirect to /shop', 'Skeleton placeholders render with d-annotation[data-loading]'.",
+          "items": { "type": "string", "minLength": 1 }
+        }
       }
     },
     "BlueprintSection": {
@@ -171,7 +176,46 @@
         "features": { "type": "array", "items": { "type": "string" } },
         "description": { "type": "string", "minLength": 1 },
         "pages": { "type": "array", "items": { "$ref": "#/$defs/BlueprintPage" }, "minItems": 1 },
-        "dna_overrides": { "$ref": "#/$defs/DNAOverrides" }
+        "dna_overrides": { "$ref": "#/$defs/DNAOverrides" },
+        "navigation_items": {
+          "type": "array",
+          "description": "Items to render in the shell's primary navigation for this section. Provides the contract so LLMs don't have to improvise sidebar/top-nav lists.",
+          "items": { "$ref": "#/$defs/SectionNavigationItem" }
+        },
+        "directives": {
+          "type": "array",
+          "description": "Execution-level directives for this section — short imperative rules the cold LLM should obey when implementing any page in this section. Belongs in the pack contract (not the narrative doc). Examples: 'Header is 52px, use d-interactive[data-size=sm] for all action buttons', 'Dev mode: localStorage flag `decantr_authenticated` gates protected routes', 'Hotkey chords bind keyboard only — never render them as visible nav labels'.",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "SectionNavigationItem": {
+      "type": "object",
+      "required": ["label", "route"],
+      "additionalProperties": false,
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "route": { "type": "string", "minLength": 1, "description": "Route path (e.g., '/agents')." },
+        "icon": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Icon identifier. Typically a Lucide icon name in kebab-case."
+        },
+        "hotkey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Keyboard shortcut used to invoke this item (matches a hotkey key string)."
+        },
+        "active_match": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Regex or path prefix the shell uses to decide if this item is 'active' for the current route. Defaults to exact match of `route`."
+        },
+        "badge": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional short badge label (e.g., 'beta', '3') rendered on the item."
+        }
       }
     },
     "RouteEntry": {
@@ -265,7 +309,13 @@
       "additionalProperties": false,
       "properties": {
         "hotkeys": { "type": "array", "items": { "$ref": "#/$defs/NavigationHotkey" } },
-        "command_palette": { "type": "boolean" }
+        "command_palette": {
+          "oneOf": [
+            { "type": "boolean" },
+            { "$ref": "#/$defs/CommandPaletteContract" }
+          ]
+        },
+        "hotkey_semantics": { "$ref": "#/$defs/HotkeySemantics" }
       }
     },
     "NavigationHotkey": {
@@ -276,7 +326,75 @@
         "key": { "type": "string", "minLength": 1 },
         "label": { "type": "string", "minLength": 1 },
         "route": { "type": "string", "minLength": 1 },
-        "action": { "type": "string", "minLength": 1 }
+        "action": { "type": "string", "minLength": 1 },
+        "semantics": { "$ref": "#/$defs/HotkeySemantics" }
+      }
+    },
+    "CommandPaletteContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Structured contract for the command palette. When present, LLMs should match exactly instead of improvising trigger/styling.",
+      "properties": {
+        "trigger": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Keyboard shortcut that opens the palette. Platform-neutral form (e.g., 'Cmd+K' implies Cmd on Mac and Ctrl elsewhere)."
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Placeholder text shown in the palette's search input."
+        },
+        "width": {
+          "type": "string",
+          "description": "Preferred width (CSS length, e.g., '640px' or '40rem')."
+        },
+        "styling": {
+          "type": "string",
+          "enum": ["modal", "sheet", "inline", "fullscreen"],
+          "description": "Visual presentation mode. 'modal' = centered dialog, 'sheet' = slide-over, 'inline' = inline dropdown, 'fullscreen' = full-viewport (typical mobile default)."
+        },
+        "commands": {
+          "type": "array",
+          "description": "Command vocabulary. If omitted, LLMs may seed a minimal default from declared routes.",
+          "items": {
+            "type": "object",
+            "required": ["id", "label"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "label": { "type": "string", "minLength": 1 },
+              "section": { "type": "string", "minLength": 1 },
+              "hotkey": { "type": "string", "minLength": 1 },
+              "action": { "type": "string", "minLength": 1 },
+              "route": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "HotkeySemantics": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Behavioral directives for hotkey handlers. Declared once globally in NavigationHints.hotkey_semantics OR per-hotkey on NavigationHotkey.semantics (per-key wins).",
+      "properties": {
+        "chord_window_ms": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 5000,
+          "description": "For chord hotkeys (e.g., 'g a'), the max ms between keystrokes before the chord resets. Typical value: 900."
+        },
+        "input_guard": {
+          "type": "boolean",
+          "description": "If true (default): hotkeys do NOT fire while focus is inside an editable element (input, textarea, contenteditable). Avoids keyboard-conflict with user typing."
+        },
+        "modifier_suppression": {
+          "type": "boolean",
+          "description": "If true (default): hotkeys do NOT fire when a modifier (Meta/Ctrl/Alt) is held unless the hotkey itself declares the modifier in its key string."
+        },
+        "match_case": {
+          "type": "boolean",
+          "description": "If true: hotkey key matching is case-sensitive (distinguishes 'g' from 'G'). Default: false — uppercase letter implies Shift modifier."
+        }
       }
     },
     "Impression": {