fix(docs): Restore Conditions system enhancements after rebase

- Add conditions.cue definition file
- Enhanced conditions metadata field documentation
- Add Contest Parameters to System Parameters list
- Support both Markdown and HTML content types with charset
- Update validation process to clarify upward traversal
- Add schema-level vs validation-level requirement distinction

Author: nathanbogale

docs/src/architecture/08_concepts/signed_doc/metadata.md

@@ -442,7 +442,10 @@ The `conditions` metadata field serves two distinct purposes depending on the do
    * References all condition documents that the user has accepted
    * Must include ALL conditions required by the parameter hierarchy (Brand → Campaign → Category → Contest)
    * The act of listing these references and signing the document serves as the user's digital signature and acceptance
-   * The field is optional when no conditions are required by the parameter hierarchy, but required when conditions are specified
+   * **Schema-level**: The field is marked as optional in the schema, allowing documents to be created without it
+   * **Validation-level**: During validation, this field becomes required when the parameter hierarchy specifies conditions.
+     If conditions are required by any level in the parameter hierarchy, the field must be present and must exactly
+     match all required conditions. If no conditions are specified in the parameter hierarchy, the field may be omitted
 
 #### `conditions` Validation
 
@@ -456,17 +459,30 @@ The `conditions` metadata field serves two distinct purposes depending on the do
 
 **For User-Submitted Documents:**
 
+**Important**: While the `conditions` field is optional at the schema level, validation enforces conditional requirements
+based on the parameter hierarchy. This validation occurs at runtime, not during schema validation.
+
 The validation process for user-submitted documents involves transitive collection of required conditions:
 
 1. Extract the [`parameters`](metadata.md#parameters) reference from the user document
-2. Follow the parameter chain: Contest → Category → Campaign → Brand
-3. Collect all `conditions` arrays from each parameter level in the hierarchy
+2. Starting from the referenced parameters document, follow the parent chain upward to Brand:
+   * If the document references **Contest Parameters**, follow: Contest → (its parent: Brand/Campaign/Category) → Campaign (if parent was Category) → Brand
+   * If the document references **Category Parameters**, follow: Category → Campaign → Brand
+   * If the document references **Campaign Parameters**, follow: Campaign → Brand
+   * If the document references **Brand Parameters**, only Brand is included
+3. Collect all `conditions` arrays from each parameter level encountered in the upward chain
 4. Union all condition references (removing duplicates based on document ID and
    version)
 5. Sort the unified list according to [CBOR Deterministic Encoding][CBOR-LFD-ENCODING]
 6. Compare the user document's `conditions` array with this unified, sorted list
 7. Validation succeeds only if they match exactly
 
+**Important**: The chain traversal always moves UPWARD from the document's referenced parameters document to Brand. Contest Parameters are only included if the document directly references them. The chain order depends on where the document is anchored in the hierarchy.
+
+**If the unified list is non-empty** (conditions are required by the parameter hierarchy), the `conditions` field
+becomes required and must be present in the user document. **If the unified list is empty** (no conditions are
+required), the `conditions` field may be omitted.
+
 **Validation Rules:**
 
 * The user document's `conditions` array must exactly match the union of all required conditions from the parameter hierarchy
@@ -500,13 +516,14 @@ The document will be rejected if:
 
 A user submitting a Proposal to a Category must accept:
 
-* All conditions from the Contest Parameters (if any)
 * All conditions from the Category Parameters (if any)
 * All conditions from the Campaign Parameters (if any)
 * All conditions from the Brand Parameters (if any)
 
 The Proposal's `conditions` array must contain the union of all these conditions, sorted and deduplicated.
 
+Note: Contest Parameters are below Category in the hierarchy, so they do not apply to documents at the Category level. If a Proposal is submitted to a Contest, then Contest Parameters would be included in the chain (Contest → Category → Campaign → Brand).
+
 In the event there are **MULTIPLE** [`conditions`](metadata.md#conditions) listed, they **MUST** be sorted.
 
 Sorting for each element of [`conditions`](metadata.md#conditions) follows the same sort order as specified for Map Keys,

specs/definitions/signed_doc_types/types.cue

@@ -30,6 +30,7 @@ allDocTypes: {
 	"Contest Delegation":                "764f17fb-cc50-4979-b14a-b213dbac5994"
 	"Contest Ballot":                    "de1284b8-8533-4f7a-81cc-ff4bde5ef8d0"
 	"Contest Ballot Checkpoint":         "58608925-bda3-47df-b39a-ae0d0a1dd6ed"
+	"Conditions":                         "b664afc2-6472-4028-b90f-875bf6eefab8"
 	//"Rep Profile Moderation Action":    "0e20010b-eeaf-4938-a7ee-ceb3df9e8af6" // speculative
 	//"Rep Nomination Moderation Action": "d27ecb44-bd4d-42bb-9273-5e5433cdfdb6" // speculative
 }

specs/definitions/signed_docs/docs/conditions.cue

@@ -0,0 +1,140 @@
+package signed_docs
+
+import (
+	"github.com/input-output-hk/catalyst-libs/specs/signed_doc_types"
+)
+
+// Conditions Document Definition
+
+docs: #DocumentDefinitions & {
+	Conditions: {
+		description: """
+			Conditions documents define terms and conditions that users must accept
+			before submitting documents to the system.
+			
+			Supports multiple condition types (TOU, license agreements, operational
+			guidelines, regional restrictions).
+			
+			The payload of a Conditions document contains the text of the terms and
+			conditions, typically in Markdown or HTML format.
+			This allows for rich formatting while maintaining human readability.
+			
+			Conditions documents are versioned and can be revoked, enabling
+			administrators to update terms over time while maintaining an auditable
+			history of what terms were in effect at any given time.
+			"""
+
+		validation: """
+			The Conditions document *MUST* be a valid signed document according to
+			the Signed Document Standard.
+			
+			When a Conditions document is referenced in a parameter document's
+			`conditions` metadata field, the referenced document *MUST* exist and be
+			of type "Conditions".
+			
+			When a Conditions document is referenced in a user-submitted document's
+			`conditions` metadata field, the referenced document *MUST* exist, be of
+			type "Conditions", and not be revoked.
+			"""
+
+		business_logic: {
+			front_end: """
+				Front-end applications should:
+				
+				* Display Conditions documents to users when they are required to
+				  accept them
+				* Store user acceptance locally to minimize friction (users only need
+				  to explicitly accept conditions the first time they encounter them)
+				* Gray out submission buttons until all required conditions have been
+				  accepted
+				* Display a disclosure on submission listing all accepted conditions
+				  under which the document is being submitted
+				* Provide clear error messages if required conditions are missing or
+				  invalid
+				"""
+
+			back_end: """
+				Back-end validation must:
+				
+				* Verify that all Conditions documents referenced in user-submitted
+				  documents exist and are valid
+				* Collect all required conditions from the parameter hierarchy
+				  (Brand → Campaign → Category → Contest)
+				* Ensure user-submitted documents include exactly the union of all
+				  required conditions from their parameter hierarchy
+				* Reject documents that reference revoked Conditions documents
+				* Reject documents that are missing required conditions or include
+				  conditions not in the parameter hierarchy
+				
+				The decentralized system (Hermes) will also reject documents without
+				the required conditions, ensuring validation occurs at multiple layers.
+				"""
+		}
+
+		headers: "content type": value: [
+			"text/markdown; charset=utf-8",
+			"text/html; charset=utf-8",
+		]
+
+		headers: "content-encoding": value: ["br"]
+
+		metadata: {
+			ref: {
+				required: "optional"
+				type:     signed_doc_types.allDocNames
+			}
+
+			revocations: required: "optional"
+		}
+
+		payload: description: """
+			The Conditions document payload contains the text of the terms and
+			conditions.
+			
+			The payload *MUST* be valid according to the content type specified in
+			the COSE header:
+			
+			* If `content-type` is `text/markdown; charset=utf-8`, the payload must be
+			  valid Markdown
+			* If `content-type` is `text/html; charset=utf-8`, the payload must be
+			  valid HTML5
+			
+			The payload is compressed using Brotli compression (`br` encoding) as
+			specified in the `content-encoding` header.
+			
+			The payload content should be human-readable and clearly state:
+			* The purpose of the conditions
+			* What users are agreeing to
+			* Any obligations or restrictions
+			* Effective dates or version information
+			* Contact information for questions
+			"""
+
+		signers: {
+			roles: admin: [
+				"Brand Admin",
+				"Campaign Admin",
+				"Category Admin",
+				"Contest Admin",
+			]
+
+			update: type: "author"
+		}
+
+		authors: {
+			"Nathan Bogale":  "[email protected]"
+			"Steven Johnson": "[email protected]"
+		}
+
+		versions: [
+			{
+				version:  "0.01"
+				modified: "2025-01-XX"
+				changes: """
+					* First Published Version (DRAFT)
+					"""
+			},
+		]
+	}
+}
+

specs/definitions/signed_docs/docs/generic_parameters.cue

@@ -47,6 +47,8 @@ _parameters_payload_description: """
 		revocations: required: "optional"
 
 		parameters: required: _ | *"yes"
+
+		conditions: required: "optional"
 	}
 
 	headers: "content type": value: "application/json"

specs/definitions/signed_docs/metadata.cue

@@ -87,6 +87,7 @@ _metadataNames: [
 	"collaborators",
 	"revocations",
 	"parameters",
+	"conditions",
 	"chain",
 ]
 
@@ -275,6 +276,71 @@ _allMetadataNames: or([
 			"""
 	}
 
+	conditions: {
+		format: "Document Reference"
+		description: """
+			An array of references to Conditions documents that define terms and conditions.
+
+			The `conditions` metadata field serves two distinct purposes depending on the document type:
+
+			1. **On Parameter Documents** (Brand Parameters, Campaign Parameters, Category Parameters, Contest Parameters):
+			   * Lists the required condition documents for that level of the system hierarchy
+			   * Specifies which terms users must accept when submitting documents at this level
+			   * The field is optional - if not present, no conditions are required at that level
+
+			2. **On User-Submitted Documents** (Proposals, Proposal Comments, etc.):
+			   * References all condition documents that the user has accepted
+			   * Must include ALL conditions required by the parameter hierarchy (Brand → Campaign → Category → Contest)
+			   * The act of listing these references and signing the document serves as the user's digital signature and acceptance
+			   * The field is optional when no conditions are required by the parameter hierarchy, but required when conditions are specified
+			"""
+		validation: """
+			**For Parameter Documents:**
+
+			* The `conditions` field is optional
+			* If present, must be an array of valid Conditions document references
+			* All referenced documents must exist and be of type "Conditions"
+			* The array must be sorted according to CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering)
+			* All array elements must be unique
+
+			**For User-Submitted Documents:**
+
+			The validation process for user-submitted documents involves transitive collection of required conditions:
+
+			1. Extract the `parameters` reference from the user document
+			2. Starting from the referenced parameters document, follow the parent chain upward to Brand:
+			   * If the document references Contest Parameters, follow: Contest → (its parent: Brand/Campaign/Category) → Campaign (if parent was Category) → Brand
+			   * If the document references Category Parameters, follow: Category → Campaign → Brand
+			   * If the document references Campaign Parameters, follow: Campaign → Brand
+			   * If the document references Brand Parameters, only Brand is included
+			3. Collect all `conditions` arrays from each parameter level encountered in the upward chain
+			4. Union all condition references (removing duplicates based on document ID and version)
+			5. Sort the unified list according to CBOR Deterministic Encoding
+			6. Compare the user document's `conditions` array with this unified, sorted list
+			7. Validation succeeds only if they match exactly
+
+			Important: The chain traversal always moves UPWARD from the document's referenced parameters document to Brand. Contest Parameters are only included if the document directly references them. The chain order depends on where the document is anchored in the hierarchy.
+
+			**Validation Rules:**
+
+			* The user document's `conditions` array must exactly match the union of all required conditions from the parameter hierarchy
+			* All referenced Conditions documents must exist and be valid
+			* All referenced Conditions documents must not be revoked
+			* The array must be sorted (CBOR deterministic encoding order)
+			* All array elements must be unique
+
+			**Validation Failures:**
+
+			The document will be rejected if:
+			* Missing required conditions (conditions specified in parameter hierarchy but not in user document)
+			* Includes extra conditions (conditions in user document not in parameter hierarchy)
+			* Array is not sorted correctly
+			* Any referenced condition document doesn't exist or is invalid
+			* Any referenced condition document is revoked
+			* Array contains duplicate references
+			"""
+	}
+
 }
 
 // Note: we make all normally excluded fields optional at the global level, because they are globally optional
@@ -288,6 +354,12 @@ metadata: headers: {
 	reply: type:             signed_doc_types.commentDocNamesList
 	section: required:       "optional"
 	collaborators: required: "optional"
+	conditions: {
+		required: "optional"
+		format:   "Document Reference"
+		type:     ["Conditions"]
+		multiple: true
+	}
 }
 
 // Preferred display order