{
       "$schema": "http://json-schema.org/draft-07/schema#",
       "$id": "https://clearhead.dev/schemas/v0.7.0/charter_metadata.schema.json",
       "title": "Charter Metadata",
       "description": "Per-charter sidecar for machine-oriented metadata that does not belong in human-readable .actions or .ics files. Keyed by domain concept (charter, actions, notes, plans) with entries keyed by identifier.",
       "type": "object",
       "properties": {
              "charter": {
                     "type": "object",
                     "description": "Metadata about the charter itself",
                     "properties": {
                            "id": {
                                   "type": "string",
                                   "format": "uuid",
                                   "description": "The charter's identity, recorded so the sidecar re-joins its charter by id rather than by file path (move-safe, and works for a charter with no actions). A reference: the charter's own declaration (frontmatter `id`, or the file itself for an action-only charter) is authoritative and doctor verifies agreement."
                            },
                            "created": {
                                   "type": "string",
                                   "description": "ISO 8601 creation timestamp"
                            }
                     },
                     "additionalProperties": true
              },
              "actions": {
                     "type": "object",
                     "description": "Metadata keyed by action identifier",
                     "additionalProperties": {
                            "type": "object",
                            "description": "Metadata for a single planned action",
                            "properties": {
                                   "created": {
                                          "type": "string",
                                          "description": "ISO 8601 creation timestamp"
                                   },
                                   "plan": {
                                          "type": "object",
                                          "description": "Durable semantic link from this Action to the iCalendar Plan it realizes.",
                                          "properties": {
                                                 "uid": {
                                                        "type": "string",
                                                        "description": "Interoperable iCalendar UID of the Plan component. ClearHead-authored one-off Plans normally use the Action UUID; calendar-authored Plans may use arbitrary text."
                                                 },
                                                 "occurrence_key": {
                                                        "type": "string",
                                                        "description": "Canonical recurrence slot key when this Action realizes one occurrence of a recurring Plan; omitted for one-off Plans."
                                                 }
                                          },
                                          "required": ["uid"],
                                          "additionalProperties": false
                                   },
                                   "occurrence": {
                                          "type": "object",
                                          "description": "Durable native occurrence lineage for live and archived Actions; independent of the machine-local projection store. Archive snapshots preserve history through Habit edits and deletion.",
                                          "properties": {
                                                 "habit_id": {
                                                        "type": "string",
                                                        "format": "uuid",
                                                        "description": "Native UUID from the Habit line, never derived from transport UID"
                                                 },
                                                 "plan_uid": {
                                                        "type": "string",
                                                        "description": "Transport VEVENT UID at crystallization time, not native identity"
                                                 },
                                                 "occurrence_key": {
                                                        "type": "string",
                                                        "description": "Canonical recurrence slot key (RECURRENCE-ID/EXDATE key) realized by this occurrence"
                                                 },
                                                 "plan_title": {
                                                        "type": "string",
                                                        "description": "Human title of the recurring Plan at crystallization time"
                                                 },
                                                 "scheduled_at": {
                                                        "type": "string",
                                                        "description": "Scheduled timestamp on the archived occurrence root"
                                                 },
                                                 "rrule": {
                                                        "type": "string",
                                                        "description": "RRULE text from the native Habit at crystallization time"
                                                 },
                                                 "template": {
                                                        "type": "string",
                                                        "description": "Template name attached to the recurring Plan at crystallization time"
                                                 }
                                          },
                                          "required": ["habit_id", "occurrence_key", "plan_title"],
                                          "additionalProperties": true
                                   }
                            },
                            "additionalProperties": true
                     }
              },
              "notes": {
                     "type": "object",
                     "description": "Append-only notes keyed by the UUID of any entity (charter, action, Habit) whose line or document this charter holds. Oldest first. Tools only append; readers accept hand edits.",
                     "additionalProperties": {
                            "type": "array",
                            "items": {
                                   "type": "object",
                                   "properties": {
                                          "at": {"type": "string", "format": "date-time", "description": "ISO 8601 date-time with UTC offset: the instant the note was written"},
                                          "by": {"type": "string", "description": "Writer: human:<name> or agent:<role>"},
                                          "text": {"type": "string"}
                                   },
                                   "required": ["at", "text"],
                                   "additionalProperties": true
                            }
                     }
              },
              "habits": {
                     "type": "object",
                     "description": "Durable calendar-only facts keyed by native Habit UUID. Preserve RFC properties and parameters losslessly; never use transport UID as the key.",
                     "additionalProperties": {
                            "type": "object",
                            "properties": {
                                   "uid": {"type": "string"},
                                   "rdate": {"type": "array", "items": {"type": "string"}},
                                   "exdate": {"type": "array", "items": {"type": "string"}},
                                   "frame": {"type": "string", "description": "DATE, floating, UTC, or IANA TZID"},
                                   "pending_overrides": {"type": "object", "description": "Lossless ICS overrides keyed by canonical original slot", "additionalProperties": {"type": "string"}}
                            },
                            "additionalProperties": true
                     }
              },
              "plans": {
                     "type": "object",
                     "description": "Metadata keyed by plan identifier",
                     "additionalProperties": {
                            "type": "object",
                            "description": "Metadata for a single plan",
                            "additionalProperties": true
                     }
              }
       },
       "additionalProperties": true
}
