inistate-core 0.1.0

package/data/inistate-schema.json

@@ -0,0 +1,1197 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "INISTATE — Initial State Module Schema",
+  "description": "Subset of the FACTS schema for defining module structure without listings. All identifiers use display names — internal IDs, GUIDs, and numeric enums are resolved automatically by the MCP layer.",
+  "version": "1.0.0",
+
+  "definitions": {
+    "FieldType": {
+      "type": "string",
+      "description": "Human-readable field type. The MCP layer maps these to/from internal numeric enums automatically.",
+      "enum": [
+        "Text", "YesNo", "Integer", "Number", "Currency",
+        "Date", "DateTime", "DateRange",
+        "Selection", "Tag",
+        "User", "Users", "Module", "Modules",
+        "Image", "Images", "File", "Files",
+        "Table",
+        "MultiText",
+        "Email", "Phone", "Link", "Signature", "Formula"
+      ]
+    },
+
+    "FieldDefinition": {
+      "type": "object",
+      "description": "A module field as seen through the MCP abstraction.",
+      "required": ["name", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable opaque identifier. Absent on create, present on read/update. Enables renaming — the MCP layer matches by id when present, falling back to name for new fields."
+        },
+        "name": {
+          "type": "string",
+          "description": "Display name. Used as the key in all MCP input/output payloads (e.g. 'Leave Type', not 'xKfLmNpQ')."
+        },
+        "type": { "$ref": "#/definitions/FieldType" },
+        "options": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Available option names for Selection/Tag fields. Each option may optionally start with an emoji prefix (e.g. '🏖️ Annual Leave', '🏥 Sick Leave', '💰 Cash'). Shorthand: Selection(Option1/Option2/Option3)."
+        },
+        "fields": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/SubFieldDefinition" },
+          "description": "Sub-field definitions for Table type. Each sub-field defines a column in the table."
+        },
+        "ai_hint": {
+          "type": "string",
+          "description": "Natural-language guidance for AI agents on how to interpret or populate this field."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "SubFieldDefinition": {
+      "type": "object",
+      "description": "Sub-field (column) within a Table field.",
+      "required": ["name", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable opaque identifier. Absent on create, present on read/update."
+        },
+        "name": { "type": "string", "description": "Display name of the sub-field." },
+        "type": { "$ref": "#/definitions/FieldType" },
+        "options": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Options for Selection/Tag sub-fields. Each option may optionally start with an emoji prefix (e.g. '🏖️ Annual Leave')."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "StateDefinition": {
+      "type": "object",
+      "description": "A workflow state. MCP resolves names to internal GUIDs automatically.",
+      "required": ["name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable opaque identifier. Absent on create, present on read/update. Enables renaming states without breaking flows."
+        },
+        "name": {
+          "type": "string",
+          "description": "State display name (e.g. 'Approved', not a GUID)."
+        },
+        "color": {
+          "type": "string",
+          "description": "Hex color code for the state badge (white text on colored background). Choose based on attention level and sentiment: #5A6070 (grey) = not started/idle, #2968A8 (blue) = waiting for action, #2A7B50 (green) = active work in progress, #A07828 (amber) = at risk/deadline approaching, #C0392B (red) = urgent/SLA breached, #6B4D91 (purple) = externally blocked, #1E6B45 (dark green) = terminal success, #8B2D2D (dark red) = terminal failure/rejected. Rules: terminal success states must use #1E6B45, terminal failure/rejection/cancellation must use #8B2D2D, only use #2A7B50 for states where work is actively being executed, use #2968A8 for approved/completed states still awaiting next action."
+        },
+        "initial": {
+          "type": "boolean",
+          "description": "When true, new entries default to this state. Only one state should be initial.",
+          "default": false
+        },
+        "ai_hint": {
+          "type": "string",
+          "description": "Guidance for AI agents on when an entry should be in this state."
+        },
+        "ai_instruction": {
+          "type": "string",
+          "description": "Instruction for AI agents to execute when an entry reaches this state. Describes what the AI should do automatically (e.g. 'Notify the approver via email', 'Generate a summary report', 'Check inventory levels and flag if below threshold'). Unlike ai_hint (which describes the state), ai_instruction prescribes an action."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "ActivityDefinition": {
+      "type": "object",
+      "description": "A custom activity (e.g. Approve, Reject). Standard activities (create, edit, delete, etc.) are implicit.",
+      "required": ["name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable opaque identifier. Absent on create, present on read/update. Enables renaming activities without breaking flows."
+        },
+        "name": {
+          "type": "string",
+          "description": "Activity display name. MCP resolves to internal activity ID."
+        },
+        "fields": {
+          "type": "array",
+          "description": "Fields included in this activity's form. Each item is either a field name string (shorthand) or an ActivityFieldRef object with constraints.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "Field display name (shorthand — defaults to required=false, readOnly=false)."
+              },
+              { "$ref": "#/definitions/ActivityFieldRef" }
+            ]
+          }
+        },
+        "ai_hint": {
+          "type": "string",
+          "description": "Guidance for AI agents on when/how to perform this activity."
+        },
+        "ai_instruction": {
+          "type": "string",
+          "description": "Instruction for AI agents to execute when this activity is performed (e.g. 'Validate all required documents are attached before approving', 'Send notification to the finance team'). Unlike ai_hint (which guides when/how to trigger the activity), ai_instruction prescribes what to do when executing it."
+        },
+        "actor": {
+          "type": "string",
+          "enum": ["human", "ai", "hybrid"],
+          "description": "Who is expected to perform this activity. 'human' = only a person can execute it, 'ai' = an AI agent performs it autonomously, 'hybrid' = either a person or AI agent may perform it. Defaults to 'human' when omitted."
+        },
+        "confidence_threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Minimum AI confidence required for this activity to proceed with a state transition. If ai_confidence < confidence_threshold, the state change is suppressed and the entry is flagged for human intervention. Omit or set to 0 to disable the gate."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "ActivityFieldRef": {
+      "type": "object",
+      "description": "A field reference within an activity form, with per-field constraints.",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Field display name. References FieldDefinition.name."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "When true, this field must be filled to submit the activity.",
+          "default": false
+        },
+        "readOnly": {
+          "type": "boolean",
+          "description": "When true, the field is visible but not editable in this activity.",
+          "default": false
+        },
+        "options": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Subset of allowed options for Selection/Tag fields in this activity. Options may include emoji prefixes. Omit to allow all options."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "FlowDefinition": {
+      "type": "object",
+      "description": "A state transition rule. All references use display names — MCP resolves to internal IDs.",
+      "required": ["from", "to", "activity"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Source state name (matches StateDefinition.name). Empty string = any state."
+        },
+        "to": {
+          "type": "string",
+          "description": "Target state name (matches StateDefinition.name)."
+        },
+        "activity": {
+          "type": "string",
+          "description": "Activity name that triggers this transition (matches ActivityDefinition.name)."
+        },
+        "ai_hint": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "ModuleSchema": {
+      "type": "object",
+      "description": "INISTATE module definition — used for both input (create/update) and output (GET/POST/PUT responses). The configure endpoints accept and return this same shape. On output, 'id' is added and all elements include stable IDs for round-tripping. A module can be either a workflow module (with states, activities, and flows) or a record list module (master data, lookup tables, registries) that simply stores entries without any workflow. Record list modules omit states, activities, and flows entirely.",
+      "required": ["name"],
+      "properties": {
+        "id": {
+          "type": "integer",
+          "description": "Module ID. Present on responses, absent on create input. Required for update operations to identify which module to update."
+        },
+        "name": {
+          "type": "string",
+          "description": "Module name. On create, this is the new module's name. On update, this can rename the module."
+        },
+        "icon": {
+          "type": "string",
+          "description": "Emoji identifier for the module."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable module description for discovery."
+        },
+        "information": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/FieldDefinition" },
+          "description": "Field definitions. Order determines default display order."
+        },
+        "states": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/StateDefinition" },
+          "description": "Workflow states. First state with initial=true (or first state if none specified) is the default. Omit for record list modules that do not need workflow."
+        },
+        "activities": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ActivityDefinition" },
+          "description": "Custom activities (e.g. Approve, Reject). Standard activities (create, edit, delete, view, assign, comment, etc.) are always available. Omit for record list modules that only need standard activities."
+        },
+        "flows": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/FlowDefinition" },
+          "description": "State transition rules linking activities to state changes. Omit for record list modules with no workflow."
+        }
+      },
+      "_note": "Responses may include additional properties (updatedDate, version, summary, changes) beyond these base fields."
+    },
+
+    "FileUploadResult": {
+      "type": "object",
+      "description": "Response from uploading a file via MCP.",
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Relative file path in /s/{shortId}/{fileName} format. Same key as FileFieldValue.path. To download, prepend /api/mcp/download/{moduleName}."
+        },
+        "filename": { "type": "string", "description": "Sanitized filename." },
+        "mimeType": { "type": "string", "description": "MIME type of the uploaded file." },
+        "size": { "type": "integer", "description": "File size in bytes." }
+      }
+    },
+
+    "PresignedUploadResult": {
+      "type": "object",
+      "description": "Response from requesting a presigned upload URL.",
+      "properties": {
+        "uploadUrl": { "type": "string", "description": "Presigned S3 PUT URL. Upload the file with HTTP PUT to this URL. Content-Type MUST match contentType exactly or S3 returns 403." },
+        "s3Key": { "type": "string", "description": "Internal S3 object key. Pass this to confirm_upload after uploading." },
+        "path": { "type": "string", "description": "Relative file path in /s/{shortId}/{fileName} format. Use this as the File/Image field value in submit_activity (same key as FileFieldValue.path)." },
+        "filename": { "type": "string", "description": "Sanitized filename." },
+        "contentType": { "type": "string", "description": "MIME type — use this exact value as the Content-Type header in the PUT request." },
+        "expiresIn": { "type": "integer", "description": "Seconds until the presigned URL expires (3600 = 1 hour)." }
+      }
+    },
+
+    "FileFieldValue": {
+      "type": "object",
+      "description": "Value shape for File/Image fields as stored and returned by MCP.",
+      "properties": {
+        "name": { "type": "string", "description": "Original filename (e.g. 'report.pdf')." },
+        "path": { "type": "string", "description": "Relative download path in /s/{shortId}/{fileName} format. To download, prepend /api/mcp/download/{moduleName}." }
+      }
+    },
+
+    "FileFieldInput": {
+      "type": "object",
+      "description": "Input shape for File/Image fields when submitting an activity. Provide a path from request_upload_url()+confirm_upload() (default) or an external URL. upload_file() is a fallback only.",
+      "required": ["name", "path"],
+      "properties": {
+        "name": { "type": "string", "description": "Filename (e.g. 'report.pdf'). Required." },
+        "path": { "type": "string", "description": "Either a path from request_upload_url()+confirm_upload() / upload_file() (fallback) (e.g. '/s/xK8m/report.pdf') or an external URL (e.g. 'https://example.com/report.pdf')." },
+        "type": { "type": "string", "description": "MIME type (optional, e.g. 'application/pdf')." }
+      },
+      "_notes": [
+        "For File/Image (single): value is one FileFieldInput object",
+        "For Files/Images (multiple): value is an array of FileFieldInput objects"
+      ]
+    },
+
+    "ModuleFieldValue": {
+      "type": "object",
+      "description": "Value shape for Module (singular) fields. Round-trippable: output and input use the same shape.",
+      "properties": {
+        "value": { "type": "string", "description": "Display value of the referenced entry." },
+        "id": { "oneOf": [{ "type": "integer" }, { "type": "string" }], "description": "Entry ID of the referenced entry." }
+      },
+      "_notes": [
+        "Module (singular): value is one ModuleFieldValue object",
+        "Modules (plural): value is an array of ModuleFieldValue objects"
+      ]
+    },
+
+    "UserFieldValue": {
+      "type": "object",
+      "description": "Value shape for User (singular) fields. Round-trippable: output and input use the same shape.",
+      "properties": {
+        "value": { "type": "string", "description": "Display name of the user." },
+        "id": { "oneOf": [{ "type": "integer" }, { "type": "string" }], "description": "Entry ID of the user entry." },
+        "username": { "type": "string", "description": "Username of the user." }
+      },
+      "_notes": [
+        "User (singular): value is one UserFieldValue object",
+        "Users (plural): value is an array of UserFieldValue objects"
+      ]
+    },
+
+    "EntryData": {
+      "type": "object",
+      "description": "Entry field values as returned by MCP. Keys are field display names, values are typed according to FieldType. For File/Image fields, values are FileFieldValue objects ({ name, path }). For Module fields, values are ModuleFieldValue objects ({ value, id }). For User fields, values are UserFieldValue objects ({ value, id, username }). Plural variants (Files/Images/Modules/Users) use arrays of these objects.",
+      "additionalProperties": true
+    },
+
+    "Entry": {
+      "type": "object",
+      "description": "A single module entry as seen through MCP. All field values use display names as keys.",
+      "properties": {
+        "module": { "type": "string", "description": "Module name." },
+        "entryId": {
+          "oneOf": [{ "type": "integer" }, { "type": "string" }],
+          "description": "Unique entry identifier."
+        },
+        "documentId": {
+          "type": "string",
+          "description": "Auto-generated document ID (e.g. LV-2026-0001)."
+        },
+        "state": {
+          "type": "string",
+          "description": "Current state display name."
+        },
+        "date": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "Entry date (business date, distinct from audit timestamps)."
+        },
+        "data": {
+          "$ref": "#/definitions/EntryData",
+          "description": "Field values keyed by display name."
+        },
+        "createdBy": { "type": "string" },
+        "createdDate": { "type": "string", "format": "date-time" },
+        "updatedBy": { "type": "string" },
+        "updatedDate": { "type": "string", "format": "date-time" },
+        "assignees": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Assigned usernames."
+        },
+        "due": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "Due date, if assigned."
+        },
+        "availableActivities": {
+          "$ref": "#/definitions/AvailableActivities",
+          "description": "Activities available on this entry based on current state and user authorization."
+        }
+      }
+    },
+
+    "EntryList": {
+      "type": "object",
+      "description": "Paginated list of entries.",
+      "properties": {
+        "moduleId": { "type": "string" },
+        "page": { "type": "integer" },
+        "pageSize": { "type": "integer" },
+        "totalItems": { "type": "integer" },
+        "list": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/Entry" }
+        }
+      }
+    },
+
+    "ActivityForm": {
+      "type": "object",
+      "description": "Form definition returned when preparing to perform an activity.",
+      "properties": {
+        "module": { "type": "string" },
+        "activity": { "type": "string" },
+        "entryId": {
+          "oneOf": [{ "type": "integer" }, { "type": "string" }, { "type": "null" }],
+          "description": "Entry ID when editing an existing entry. Null for create."
+        },
+        "documentId": { "type": ["string", "null"], "description": "Document ID of the entry, if applicable." },
+        "form": {
+          "type": "array",
+          "description": "Form fields. Each item is an object keyed by field display name, containing field definition properties.",
+          "items": {
+            "type": "object",
+            "description": "Single field: { \"Field Name\": { type, required?, readOnly?, options?, module?, fields? } }",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "type": { "$ref": "#/definitions/FieldType" },
+                "required": { "type": "boolean" },
+                "readOnly": { "type": "boolean" },
+                "options": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Available options for Selection/Tag fields. Options may include emoji prefixes (e.g. '🏖️ Annual Leave')."
+                },
+                "module": {
+                  "type": "string",
+                  "description": "Referenced module name for Module/User field types."
+                },
+                "fields": {
+                  "type": "array",
+                  "description": "Sub-fields for Table/List types. Same keyed-by-name structure.",
+                  "items": { "type": "object", "additionalProperties": true }
+                }
+              }
+            }
+          },
+          "_example": [
+            { "Leave Type": { "type": "Selection", "required": true, "options": ["🏖️ Annual Leave", "🏥 Sick Leave", "📋 Unpaid Leave"] } },
+            { "Start Date": { "type": "Date", "required": true } },
+            { "Reason": { "type": "MultiText" } },
+            { "Approver": { "type": "Text" } }
+          ]
+        },
+        "defaults": {
+          "$ref": "#/definitions/EntryData",
+          "description": "Current/default values for pre-populating the form, keyed by display name."
+        },
+        "states": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Available target states for this activity."
+        },
+        "confidence_threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "The activity's confidence threshold for AI-driven state transitions. Present only when the activity has a threshold configured (> 0). AI agents should compare their confidence against this value before submitting."
+        },
+        "availableActivities": {
+          "$ref": "#/definitions/AvailableActivities",
+          "description": "Activities available on the entry in its current state."
+        }
+      }
+    },
+
+    "ActivitySubmission": {
+      "type": "object",
+      "description": "Payload for performing an activity on an entry. All keys use display names.",
+      "required": ["module"],
+      "properties": {
+        "module": { "type": "string", "description": "Module name." },
+        "activity": {
+          "type": "string",
+          "default": "create",
+          "description": "Activity name: create, edit, delete, or any custom activity name."
+        },
+        "entryId": {
+          "oneOf": [{ "type": "integer" }, { "type": "string" }],
+          "description": "Required for edit/delete/custom activities. Omit for create."
+        },
+        "entryIds": {
+          "type": "array",
+          "items": { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
+          "description": "Multiple entry IDs for bulk operations."
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Field values keyed by display name. For File/Image fields, use FileFieldInput objects ({ name, path }). For Module fields, use ModuleFieldValue objects ({ value, id }). For User fields, use UserFieldValue objects ({ value, id, username }). Plural variants (Files/Images/Modules/Users) use arrays of these objects."
+        },
+        "state": {
+          "type": "string",
+          "description": "Target state name (resolved to internal ID automatically)."
+        },
+        "comment": { "type": "string" },
+        "assignees": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Usernames to assign."
+        },
+        "due": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Due date for assignment."
+        },
+        "ai": {
+          "type": "object",
+          "description": "AI agent traceability context. Include when the submission is made by an AI agent.",
+          "properties": {
+            "reasoning": {
+              "type": "string",
+              "description": "Natural language explanation of the AI's decision."
+            },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "type": { "type": "string", "description": "Source type (e.g. 'field', 'document', 'policy')." },
+                  "reference": { "type": "string", "description": "Identifier or location of the source." },
+                  "excerpt": { "type": "string", "description": "Relevant excerpt from the source." }
+                }
+              },
+              "description": "What data the AI used and from where."
+            },
+            "model": {
+              "type": "string",
+              "description": "Which model made this decision (e.g. claude-sonnet-4-20250514)."
+            },
+            "model_version": {
+              "type": "string",
+              "description": "Model version / checkpoint for reproducibility."
+            },
+            "prompt_hash": {
+              "type": "string",
+              "description": "Hash of the system prompt used, for version tracking."
+            },
+            "confidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Confidence score (0–1). If below the activity's confidence_threshold, the state transition is suppressed and the entry is flagged for human intervention."
+            }
+          }
+        }
+      }
+    },
+
+    "AvailableActivities": {
+      "type": "object",
+      "description": "Activities the current user can perform on the entry, based on authorization and current state.",
+      "properties": {
+        "standard": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Standard activities available (e.g. create, edit, delete, changeState, duplicate, comment, manage)."
+        },
+        "custom": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Custom activities available based on current state and flows."
+        },
+        "stateFlow": {
+          "type": "object",
+          "description": "Current state and possible transitions. Present only when the module has states.",
+          "properties": {
+            "currentState": { "type": "string", "description": "Current state name of the entry." },
+            "transitions": {
+              "type": "object",
+              "description": "Per-activity target state names. Keys are activity names, values are arrays of possible target state names.",
+              "additionalProperties": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+
+    "ActivityResult": {
+      "type": "object",
+      "description": "Response after performing an activity.",
+      "properties": {
+        "module": { "type": "string" },
+        "activity": { "type": "string" },
+        "entryId": { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
+        "documentId": { "type": "string" },
+        "state": { "type": ["string", "null"] },
+        "message": { "type": ["string", "null"] },
+        "flagged": {
+          "type": "boolean",
+          "description": "True when AI confidence was below the activity's confidence_threshold. State transition was suppressed and the entry is flagged for human intervention (collaboration flags: WithIntention + LastIntention, history type: intention). Only present when true."
+        },
+        "ai_instruction": {
+          "type": "string",
+          "description": "Instruction for AI agents to execute, from the new state's ai_instruction field. Only present when the activity caused a state change and the target state has an ai_instruction defined."
+        },
+        "availableActivities": {
+          "$ref": "#/definitions/AvailableActivities",
+          "description": "Activities available on the entry after this activity was performed."
+        }
+      }
+    },
+
+    "HistoryEvent": {
+      "type": "object",
+      "description": "A single audit trail event.",
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["create", "edit", "activity", "changeStatus", "delete", "duplicate", "assign", "import", "intention", "comment", "clone", "manage"],
+          "description": "Event type."
+        },
+        "by": { "type": "string", "description": "Username who performed the action." },
+        "on": { "type": "string", "format": "date-time" },
+        "activity": { "type": ["string", "null"], "description": "Custom activity name, if applicable." },
+        "state": { "type": ["string", "null"], "description": "Resulting state name." },
+        "comment": { "type": ["string", "null"] },
+        "changes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "field": { "type": "string", "description": "Field display name." },
+              "from": {},
+              "to": {}
+            }
+          }
+        },
+        "replies": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "by": { "type": "string" },
+              "on": { "type": "string", "format": "date-time" },
+              "comment": { "type": "string" }
+            }
+          }
+        },
+        "ai": {
+          "type": "object",
+          "description": "AI agent traceability context captured at submission time. Present only on events submitted by an AI agent.",
+          "properties": {
+            "reasoning": { "type": "string", "description": "Natural language explanation of the AI's decision." },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "type": { "type": "string" },
+                  "reference": { "type": "string" },
+                  "excerpt": { "type": "string" }
+                }
+              }
+            },
+            "model": { "type": "string" },
+            "model_version": { "type": "string" },
+            "prompt_hash": { "type": "string" },
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+          }
+        }
+      }
+    },
+
+    "EntryHistory": {
+      "type": "object",
+      "description": "Paginated audit trail for an entry.",
+      "properties": {
+        "moduleId": { "type": "string" },
+        "entryId": { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
+        "histories": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/HistoryEvent" }
+        },
+        "hasMore": { "type": "boolean" },
+        "page": { "type": "integer" }
+      }
+    },
+
+    "FilterOperators": {
+      "type": "object",
+      "description": "Available filter operators for list_entries. Keys are field display names. Simple value = equality match.",
+      "properties": {
+        "_string": {
+          "type": "object",
+          "description": "String field operators",
+          "properties": {
+            "contains": { "type": "string" },
+            "startsWith": { "type": "string" },
+            "endsWith": { "type": "string" },
+            "is": { "type": "string" },
+            "not": { "type": "string" },
+            "excludes": { "type": "string" }
+          }
+        },
+        "_numeric": {
+          "type": "object",
+          "description": "Numeric/currency field operators",
+          "properties": {
+            "min": { "type": "number" },
+            "max": { "type": "number" },
+            "above": { "type": "number" },
+            "below": { "type": "number" },
+            "between": {
+              "type": "object",
+              "properties": {
+                "min": { "type": "number" },
+                "max": { "type": "number" }
+              }
+            }
+          }
+        },
+        "_date": {
+          "type": "object",
+          "description": "Date/DateTime field operators",
+          "properties": {
+            "after": { "type": "string", "format": "date" },
+            "before": { "type": "string", "format": "date" }
+          }
+        },
+        "_existence": {
+          "type": "object",
+          "description": "Presence/absence operators (any field type)",
+          "properties": {
+            "empty": { "type": "boolean" },
+            "exists": { "type": "boolean" }
+          }
+        },
+        "_boolean": {
+          "type": "object",
+          "description": "YesNo field operators",
+          "properties": {
+            "yes": { "type": "boolean" },
+            "no": { "type": "boolean" }
+          }
+        }
+      }
+    },
+
+    "ErrorResponse": {
+      "type": "object",
+      "description": "Standard error shape returned by all MCP endpoints.",
+      "properties": {
+        "error": { "type": "string", "description": "Short error code." },
+        "message": { "type": "string", "description": "Human-readable description." },
+        "details": {
+          "type": "array",
+          "description": "Validation details (422 only).",
+          "items": {
+            "type": "object",
+            "properties": {
+              "field": { "type": "string" },
+              "message": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  },
+
+  "operations": {
+    "_description": "INISTATE operations map to MCP endpoints. Each operation uses display names exclusively — the MCP layer handles all internal ID resolution.",
+
+    "list_workspaces": {
+      "description": "List workspaces the current user can access. Call this first when no workspace is set — the chosen workspace ID must be passed on subsequent calls via the wsid header or the workspaceId tool parameter, otherwise every downstream call scopes to the wrong tenant.",
+      "parameters": {
+        "search": { "type": "string", "description": "Optional case-insensitive name filter. Use when the user names a workspace and you need to resolve it to an ID." }
+      },
+      "returns": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "integer" },
+            "name": { "type": "string" }
+          }
+        }
+      },
+      "_maps_to": "GET /api/mcp/workspace"
+    },
+
+    "get_workspace": {
+      "description": "Get workspace details including its modules, states, and company info.",
+      "parameters": {
+        "id": { "type": "string", "description": "Workspace ID." }
+      },
+      "returns": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "name": { "type": "string" },
+          "company": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "logo": { "type": "string" },
+              "phone": { "type": "string" }
+            }
+          },
+          "modules": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "integer" },
+                "emoji": { "type": "string" },
+                "name": { "type": "string" },
+                "states": { "type": "array" }
+              }
+            }
+          },
+          "states": { "type": "array" },
+          "country": { "type": "string" }
+        }
+      },
+      "_maps_to": "GET /api/mcp/workspace/{id}"
+    },
+
+    "discover_modules": {
+      "description": "List every module in the active workspace. Use this first to discover what's available before calling get_module, list_entries, or submit_activity — the user may refer to modules informally ('leave requests', 'the PO module') and you need the exact module name. Returns lightweight entries with name and emoji only; call get_module for fields, states, and activities.",
+      "returns": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "emoji": { "type": "string" }
+          }
+        }
+      },
+      "_maps_to": "GET /api/mcp/"
+    },
+
+    "get_module": {
+      "description": "Get a module's schema: fields, states, and (with tier=extended) activities and flows. Field, state, and activity names returned here are the keys to pass into get_form, list_entries, and submit_activity — use display names, never internal IDs. Use tier=basic by default to minimize context; request tier=extended only when you need activity forms or state-transition flows.",
+      "parameters": {
+        "module": { "type": "string", "description": "Module name from discover_modules. Case-sensitive, may contain spaces (e.g. 'Leave Requests')." },
+        "tier": {
+          "type": "string",
+          "enum": ["basic", "extended"],
+          "default": "basic",
+          "description": "basic = fields + states only (smaller response, enough for reading/listing entries). extended = adds activities and flows (needed before submit_activity on a module you haven't seen before)."
+        }
+      },
+      "returns": { "$ref": "#/definitions/ModuleSchema" },
+      "_maps_to": "GET /api/mcp/{moduleName}",
+      "_notes": [
+        "Record list modules (master data, lookup tables) have no states/activities/flows — an empty states array in the response means you use standard create/edit/delete only",
+        "Field order in the response is the display order — preserve it when rendering forms to the user"
+      ]
+    },
+
+    "list_entries": {
+      "description": "Query entries in a module with filters, pagination, and sorting. Filter keys are field display names (from get_module); simple values match exactly, object values use operators. Always prefer specific filters over fetching everything — responses >100KB are auto-truncated to 20 items with _truncated=true. Each entry in the response includes availableActivities, so you can chain directly into submit_activity without an extra get_form call.",
+      "parameters": {
+        "module": { "type": "string", "description": "Module name from discover_modules." },
+        "filters": {
+          "type": "object",
+          "description": "Field display names as keys. Simple value = equality ({'Priority': 'High'}). Object value = operator — text: {contains,startsWith,endsWith,excludes,is,not}; number: {min,max,above,below,between}; date: {after,before,upcoming,past,within}; boolean: true/false; user: {is,isMe,not,includes}; module: by referenced entry ID. Combine multiple keys for AND; use {or: [...]} for OR.",
+          "additionalProperties": true
+        },
+        "state": { "type": "string", "description": "Filter by state display name (e.g. 'Pending Approval'). MCP resolves to internal state ID." },
+        "search": { "type": "string", "description": "Free-text search against document ID and indexed text fields." },
+        "sortBy": { "type": "string", "description": "Field display name to sort by. Defaults to createdDate descending." },
+        "sortDirection": { "type": "string", "enum": ["asc", "desc"] },
+        "currentPage": { "type": "integer", "description": "0-based page index." },
+        "pageSize": { "type": "integer", "description": "Items per page. Default 50, max 500. Use small pages (20–50) when summarizing for the user; larger pages only when exporting or aggregating." }
+      },
+      "returns": { "$ref": "#/definitions/EntryList" },
+      "_maps_to": "POST /api/mcp/list",
+      "_notes": [
+        "Use 'me'/'myself'/'currentUser' as filter values for User fields to match the calling user without knowing their ID",
+        "Response includes totalItems and hasMore; paginate when hasMore=true rather than raising pageSize past 500",
+        "For Module reference fields, filter by the referenced entry's ID, not its display name"
+      ]
+    },
+
+    "get_entry": {
+      "description": "Read a single entry's field values, current state, and availableActivities. Use the response's availableActivities.standard and .custom directly when deciding the next submit_activity call — do not hard-code activity names, because what's allowed depends on current state, user permissions, and workflow rules.",
+      "parameters": {
+        "module": { "type": "string", "description": "Module name from discover_modules." },
+        "entryId": { "oneOf": [{ "type": "integer" }, { "type": "string" }], "description": "Entry ID (numeric) or documentId (string like 'LR-2026-0042'). Both are accepted." }
+      },
+      "returns": { "$ref": "#/definitions/Entry" },
+      "_maps_to": "POST /api/mcp/entry",
+      "_notes": [
+        "Field values use display names as keys (e.g. 'Leave Type', not an internal ID)",
+        "File/Image fields return FileFieldValue objects; Module fields return ModuleFieldValue ({value,id}); User fields return UserFieldValue ({value,id,username}) — these shapes are round-trippable: pass the same objects back to submit_activity.input"
+      ]
+    },
+
+    "get_form": {
+      "description": "Get the form definition for an activity: required fields, types, options, per-field readOnly/required constraints, the activity's confidence_threshold, and (for edit) current field values as defaults. REQUIRED STEP before submit_activity — skipping it leads to 422 validation failures that are entirely avoidable. Pass entryId for edit/custom activities so defaults are populated from the current entry state.",
+      "parameters": {
+        "module": { "type": "string", "description": "Module name from discover_modules." },
+        "activity": { "type": "string", "default": "create", "description": "Activity name. Standard: create, edit, delete, changeStatus, comment, duplicate, manage. Custom: any activity defined in the module (from get_module tier=extended)." },
+        "entryId": { "description": "Required for edit and custom activities that operate on an existing entry. Omit for create." }
+      },
+      "returns": { "$ref": "#/definitions/ActivityForm" },
+      "_maps_to": "POST /api/mcp/form"
+    },
+
+    "submit_activity": {
+      "description": "Perform an activity on an entry: create (no entryId), edit, delete, changeStatus, comment, duplicate, manage, or any custom activity from the module. ALWAYS call get_form first — it returns the required fields, valid options, per-field constraints, and the activity's confidence_threshold. Submitting without get_form risks 422 validation errors and unknown field rejections. For bulk operations, pass entryIds instead of entryId.",
+      "parameters": { "$ref": "#/definitions/ActivitySubmission" },
+      "returns": { "$ref": "#/definitions/ActivityResult" },
+      "_maps_to": "POST /api/mcp/activity",
+      "_notes": [
+        "Input shapes by field type — File/Image: { name, path } where path is from confirm_upload (default via request_upload_url+confirm_upload) or upload_file (fallback only) or an external URL. Files/Images: array of those. Module: { value, id } (id is the referenced entry ID). User: { value, id, username }. Modules/Users: arrays. Table: array of row objects keyed by sub-field display name. Other types: plain values matching FieldType.",
+        "Always include the `ai` object (reasoning, sources, model, confidence) when an AI agent is the actor — it's the audit trail the user relies on to trust automated actions",
+        "Confidence gate: if ai.confidence < the activity's confidence_threshold (from get_form), the state transition is SUPPRESSED and the response returns flagged: true. The entry is saved but stays in the original state and is flagged for human review. Do NOT retry automatically — surface the situation to the user",
+        "The response includes availableActivities — use it to decide the next legal action on the entry without another round-trip to get_entry",
+        "For Selection/Tag fields, pass option names exactly as returned by get_form.options (case-sensitive, including any emoji prefix)",
+        "State names are resolved automatically from the `state` parameter — pass the display name (e.g. 'Approved'), never an internal GUID"
+      ]
+    },
+
+    "get_history": {
+      "description": "Get the chronological audit trail for an entry: create/edit/delete events, state transitions, comments, assignments, and AI audit records (reasoning, sources, model, confidence) when an `ai` object was submitted. Use this to explain how an entry reached its current state, answer 'who did what and when' questions, or surface why a transition was flagged.",
+      "parameters": {
+        "module": { "type": "string", "description": "Module name from discover_modules." },
+        "entryId": { "oneOf": [{ "type": "integer" }, { "type": "string" }], "description": "Entry ID or documentId." },
+        "page": { "type": "integer", "default": 0, "description": "0-based page index. 50 events per page." }
+      },
+      "returns": { "$ref": "#/definitions/EntryHistory" },
+      "_maps_to": "POST /api/mcp/history",
+      "_notes": [
+        "History entries with type='intention' indicate a confidence-gated action — the AI tried to perform an activity but ai.confidence was below confidence_threshold, so the state transition was suppressed and the entry was flagged for human review",
+        "Field-level changes are in the 'changes' object (before/after values) on edit events — use to answer 'what changed between X and Y'",
+        "AI audit context (ai.reasoning, ai.sources, ai.confidence) is preserved verbatim from what was submitted — useful for post-hoc review of automated decisions"
+      ]
+    },
+
+    "upload_file": {
+      "description": "FALLBACK ONLY — do NOT use this by default. Always use request_upload_url + confirm_upload first; call this tool only after the presigned flow has actually failed. Uploads a file to S3 via multipart/form-data. Returns a /s/ path usable as a File/Image field value in submit_activity.",
+      "parameters": {
+        "required": ["module", "file"],
+        "module": { "type": "string", "description": "Module name. Required — scopes the file to the module's storage folder." },
+        "file": { "type": "string", "format": "binary", "description": "The file to upload. Must be sent as multipart/form-data." }
+      },
+      "returns": { "$ref": "#/definitions/FileUploadResult" },
+      "_maps_to": "POST /api/mcp/upload",
+      "_notes": [
+        "Fallback path — only use after request_upload_url + confirm_upload has failed",
+        "Request must be multipart/form-data — no other content types are supported",
+        "Required 'module' form field scopes the file to the module's S3 folder",
+        "Maximum file size: 50MB",
+        "Blocked extensions: .exe, .bat, .cmd, .dll, .msi, and other executable types",
+        "Filenames are sanitized (path traversal characters stripped)"
+      ]
+    },
+
+    "request_upload_url": {
+      "description": "DEFAULT upload path — ALWAYS use this for every file upload (any size, up to 500 MB). Only fall back to upload_file if this flow actually fails. Returns an uploadUrl for the client to PUT the file directly to S3, plus a path to use in File/Image fields. After uploading, call confirm_upload to finalize.",
+      "parameters": {
+        "required": ["module", "fileName", "fileSize"],
+        "module": { "type": "string", "description": "Module name. Required — scopes the file to the module's storage folder." },
+        "fileName": { "type": "string", "description": "Original filename including extension." },
+        "contentType": { "type": "string", "description": "MIME type of the file. Defaults to application/octet-stream." },
+        "fileSize": { "type": "integer", "description": "File size in bytes. Must be > 0 and ≤ 500 MB.", "minimum": 1, "maximum": 524288000 }
+      },
+      "returns": { "$ref": "#/definitions/PresignedUploadResult" },
+      "_maps_to": "POST /api/mcp/request-upload-url",
+      "_notes": [
+        "Default for every file upload regardless of size — always attempt this flow first; only fall back to upload_file if this actually fails",
+        "IMPORTANT: The PUT request Content-Type header MUST exactly match the contentType from this response. S3 presigned URLs sign headers — a mismatch causes 403 SignatureDoesNotMatch with no useful error message",
+        "The uploadUrl expires in 1 hour (expiresIn seconds). If the PUT fails with 403 after expiry, call request_upload_url again — presigned URLs cannot be renewed",
+        "Maximum file size: 500 MB",
+        "Blocked extensions: .exe, .bat, .cmd, .dll, .msi, and other executable types",
+        "Filenames are sanitized (path traversal characters stripped)",
+        "After the PUT upload completes, call confirm_upload with the s3Key from this response",
+        "Server should have an S3 lifecycle policy to expire unconfirmed uploads (e.g. 24h) — if a client crashes between PUT and confirm_upload, the S3 object is orphaned",
+        "Worked example: 1. request_upload_url({ module, fileName, fileSize, contentType }) → { uploadUrl, s3Key, path, filename }  2. PUT uploadUrl with body=<bytes>, headers Content-Type=<contentType>  3. confirm_upload({ s3Key }) → { path, filename, mimeType, size }  4. submit_activity({ input: { \"Attachment\": { name: filename, path } } })"
+      ]
+    },
+
+    "confirm_upload": {
+      "description": "Confirm that a presigned upload completed. Verifies the file exists in S3, reads its metadata, and tracks workspace storage. Only s3Key is required — filename, size, and content type are resolved from S3.",
+      "parameters": {
+        "required": ["s3Key"],
+        "s3Key": { "type": "string", "description": "The s3Key returned from request_upload_url." }
+      },
+      "returns": { "$ref": "#/definitions/FileUploadResult" },
+      "_maps_to": "POST /api/mcp/confirm-upload",
+      "_notes": [
+        "Must be called after the file has been uploaded to the presigned URL",
+        "Returns 400 if the file is not found in S3 — ensure the PUT upload completed before calling",
+        "If the presigned URL expired (403 from S3), call request_upload_url again before retrying",
+        "Response format matches upload_file — path can be used identically in File/Image fields"
+      ]
+    },
+
+    "download_file": {
+      "description": "Download a file by module name. AI agents construct the download URL by prepending /api/mcp/download/{moduleName} to a /s/{shortId}/{fileName} path.",
+      "parameters": {
+        "moduleName": { "type": "string", "description": "Module name (resolved to vectorId internally)." },
+        "guid": { "type": "string", "description": "Short ID from the file URL." },
+        "fileName": { "type": "string", "description": "Original filename." }
+      },
+      "returns": { "type": "string", "description": "Redirects to a pre-signed S3 URL (1hr TTL) or streams the file directly for Office applications." },
+      "_maps_to": "GET /api/mcp/download/{moduleName}/s/{guid}/{fileName}",
+      "_notes": [
+        "Returns 404 with MCP error format if file not found in S3",
+        "Office user-agents receive direct stream; all others get a 302 redirect to a pre-signed URL"
+      ]
+    },
+
+    "get_module_schema": {
+      "description": "Get an existing module definition as a ModuleSchema with stable IDs. The output is round-trippable — modify and send back via update_module.",
+      "parameters": {
+        "module": { "type": "string", "description": "Module name or numeric ID." }
+      },
+      "returns": { "$ref": "#/definitions/ModuleSchema" },
+      "_maps_to": "GET /api/configure/{moduleName}"
+    },
+
+    "create_module": {
+      "description": "Create a new module from a ModuleSchema definition. Returns the created module as a ModuleSchema with generated IDs.",
+      "parameters": { "$ref": "#/definitions/ModuleSchema" },
+      "returns": {
+        "allOf": [
+          { "$ref": "#/definitions/ModuleSchema" },
+          {
+            "type": "object",
+            "properties": {
+              "updatedDate": { "type": "string", "format": "date-time" },
+              "version": { "type": "string" },
+              "summary": {
+                "type": "object",
+                "description": "Summary of what was created.",
+                "properties": {
+                  "fields": { "type": "integer" },
+                  "states": { "type": "array", "items": { "type": "string" } },
+                  "activities": { "type": "array", "items": { "type": "string" } },
+                  "flows": { "type": "integer" }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "_maps_to": "POST /api/configure"
+    },
+
+    "update_module": {
+      "description": "Update an existing module. Send a ModuleSchema with id. Returns the full updated ModuleSchema.",
+      "parameters": { "$ref": "#/definitions/ModuleSchema" },
+      "returns": {
+        "allOf": [
+          { "$ref": "#/definitions/ModuleSchema" },
+          {
+            "type": "object",
+            "properties": {
+              "updatedDate": { "type": "string", "format": "date-time" },
+              "version": { "type": "string" },
+              "changes": {
+                "type": "object",
+                "description": "What the update changed.",
+                "properties": {
+                  "renamed": { "type": "array", "items": { "type": "object" } },
+                  "added": { "type": "array", "items": { "type": "object" } },
+                  "updated": { "type": "array", "items": { "type": "string" } }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "_maps_to": "PUT /api/configure"
+    }
+  },
+
+  "workflow_guide": {
+    "_description": "Recommended sequence for AI agents interacting through INISTATE.",
+    "steps": [
+      "1. list_workspaces(?search=) → find accessible workspaces (id and name)",
+      "2. get_workspace(id) → get workspace details with modules and states",
+      "3. discover_modules() → find available module names",
+      "4. get_module(module, tier='basic') → understand fields and states",
+      "5. get_module(module, tier='extended') → understand activities (only when needed)",
+      "6. get_form(module, activity) → get required fields, types, options, defaults, and confidence_threshold before submitting",
+      "7. request_upload_url(module, fileName, fileSize, contentType) → PUT bytes to uploadUrl → confirm_upload(s3Key) → returns /s/ path. ALWAYS use this flow for File/Image fields. Only fall back to upload_file(module, file) if this flow fails.",
+      "8. submit_activity(module, activity, input) → create/edit/delete/custom operations. Use /s/ paths from confirm_upload (or upload_file fallback) for File/Image fields.",
+      "9. list_entries(module, filters) → query and browse entries",
+      "10. get_entry(module, entryId) → read a specific entry",
+      "11. get_history(module, entryId) → audit trail and comments",
+      "12. download_file(moduleName, guid, fileName) → download a file. Construct URL: /api/mcp/download/{moduleName}/s/{guid}/{fileName} from any /s/{guid}/{fileName} value",
+      "--- Module Configuration (via /api/configure/ endpoints, uses INISTATE ModuleSchema format) ---",
+      "13. get_module_schema(moduleName) → GET /api/configure/{moduleName} — get the module's current definition as ModuleSchema with stable IDs. Round-trippable: modify and send back via update_module.",
+      "14. create_module(ModuleSchema) → POST /api/configure — create a new module using the ModuleSchema definition from this schema",
+      "15. update_module(ModuleSchema) → PUT /api/configure — update an existing module. Use get_module_schema() first, modify, then send back."
+    ],
+    "key_rules": [
+      "All input/output keys use field DISPLAY NAMES, never internal IDs",
+      "State references use state NAMES, never GUIDs",
+      "Activity references use activity NAMES, resolved to IDs internally",
+      "Always call get_form() before submit_activity() to discover required fields and valid options",
+      "Use tier='basic' by default; only request 'extended' when activity details are needed",
+      "Not all modules have workflows — record list modules (master data, lookup tables) have no states, activities, or flows. Use standard create/edit/delete activities directly.",
+      "File/Image fields use object values, not plain strings. Retrieval returns { name, path }. Submission accepts { name, path } where path is from request_upload_url()+confirm_upload() (always the default flow; fall back to upload_file() only if it fails) or an external URL. Files/Images (plural) use arrays of these objects. To download, prepend /api/mcp/download/{moduleName} to any /s/ path.",
+      "Module/User fields use object values. Retrieval returns { value, id } for Module and { value, id, username } for User. Submission accepts the same shape — the MCP layer decomposes these into internal storage format. Modules/Users (plural) use arrays of these objects."
+    ],
+    "module_types": {
+      "_description": "Modules fall into two categories based on their purpose.",
+      "workflow_module": {
+        "description": "Modules with states, custom activities, and flows that define a process lifecycle (e.g. Leave Request, Purchase Order, Support Ticket). Entries move through states via activities and transition rules.",
+        "has_states": true,
+        "has_activities": true,
+        "has_flows": true
+      },
+      "record_list_module": {
+        "description": "Modules used purely to maintain a list of entries — master data, lookup tables, registries, catalogs (e.g. Employee Directory, Department List, Product Catalog, Holiday Calendar). No workflow, no state transitions, no custom activities. Entries are managed with standard create/edit/delete operations only.",
+        "has_states": false,
+        "has_activities": false,
+        "has_flows": false,
+        "examples": [
+          "Employee Directory — master list of employees and their details",
+          "Department List — organizational departments for reference",
+          "Product Catalog — items available for selection in other modules",
+          "Holiday Calendar — list of holiday dates used by leave/attendance modules",
+          "Cost Centers — finance lookup table referenced by expense and budget modules"
+        ]
+      }
+    },
+
+    "confidence_gate": {
+      "_description": "When an AI agent submits an activity with ai.confidence below the activity's confidence_threshold:",
+      "behavior": [
+        "State transition is suppressed — the entry stays in its current state",
+        "The history event is recorded with type 'intention' instead of the normal activity type",
+        "The entry's collaboration flags are set to WithIntention + LastIntention",
+        "The response includes flagged: true so the AI agent knows the action requires human review",
+        "Entries flagged for intervention can be filtered using the collaboration filter: 'intention' or 'lastIntention'",
+        "get_form() returns confidence_threshold when configured, so agents can check the threshold before submitting"
+      ]
+    },
+    "ai_audit_trail": {
+      "_description": "AI agent traceability in history events:",
+      "behavior": [
+        "Every history event submitted by an AI agent includes the full 'ai' object (reasoning, sources, model, model_version, prompt_hash, confidence)",
+        "get_history() returns the ai context on each event, enabling full chain-of-reasoning reconstruction",
+        "The ai object is only present on events that were submitted with AI context — human actions have no ai field"
+      ]
+    },
+    "state_color_system": {
+      "_description": "Color assignment rules for states based on attention level and sentiment. Use hex codes.",
+      "palette": {
+        "#5A6070": "Grey — not started, idle, queued, no action expected",
+        "#2968A8": "Blue — waiting for an actor to take next action, no urgency",
+        "#2A7B50": "Green — work is actively being executed by an actor right now",
+        "#A07828": "Amber — deadline approaching, condition flagged, action needed soon",
+        "#C0392B": "Red — SLA breached, escalation required, process stuck",
+        "#6B4D91": "Purple — blocked by external dependency outside this workflow",
+        "#1E6B45": "Dark green — terminal success (approved, completed, closed)",
+        "#8B2D2D": "Dark red — terminal failure (rejected, cancelled, failed)"
+      },
+      "_note": "All colors are designed for white text on colored background (WCAG AA 4.5:1+ contrast).",
+      "decision_order": [
+        "1. Terminal success → #1E6B45",
+        "2. Terminal failure/rejection/cancellation → #8B2D2D",
+        "3. Active work being executed → #2A7B50",
+        "4. SLA breached or escalation required → #C0392B",
+        "5. Deadline approaching or flagged → #A07828",
+        "6. Blocked by external dependency → #6B4D91",
+        "7. Waiting for next action, no urgency → #2968A8",
+        "8. Not started, queued, idle → #5A6070"
+      ],
+      "rules": [
+        "Never use #2A7B50 (green) for states where no actor is actively working — use #2968A8 (blue) for approved/completed states awaiting next action",
+        "Terminal states must always be #1E6B45 or #8B2D2D — never grey, blue, or green",
+        "Never use #C0392B (red) unless a real SLA breach or escalation condition exists",
+        "Only one state in a linear workflow should typically be green — the active work state",
+        "When unsure, default to #2968A8 (blue) — it is the safest general-purpose color",
+        "In parallel/branching workflows, multiple states may use #2A7B50 (green) if each represents genuinely concurrent active work by different actors"
+      ],
+      "default_when_unsure": "#2968A8",
+      "strict_palette": "Only use the 8 hex codes listed in the palette. Never generate custom hex values.",
+      "keyword_hints": {
+        "_description": "When a state name contains these keywords, use the mapped color. Always check terminal rules first — a state named 'Completed' is terminal success even if it contains 'complete' from the green list.",
+        "#5A6070": ["draft", "new", "open", "backlog", "queued", "not started", "inactive", "parked", "unassigned"],
+        "#2968A8": ["pending", "submitted", "awaiting", "assigned", "ready", "scheduled", "planned", "under review", "to do"],
+        "#2A7B50": ["in progress", "processing", "working", "executing", "building", "running", "reviewing", "implementing", "testing"],
+        "#A07828": ["due soon", "at risk", "warning", "expiring", "needs attention", "follow up", "reminder"],
+        "#C0392B": ["overdue", "escalated", "breached", "stuck", "critical", "urgent", "sla"],
+        "#6B4D91": ["blocked", "waiting on", "on hold", "external", "vendor", "third party", "dependency"],
+        "#1E6B45": ["approved", "completed", "done", "resolved", "closed", "delivered", "passed", "accepted", "verified", "fulfilled", "signed off"],
+        "#8B2D2D": ["rejected", "cancelled", "failed", "denied", "expired", "voided", "abandoned", "withdrawn", "terminated", "declined"]
+      }
+    }
+  }
+}