{
  "$id": "https://glimmervoid.dev/schema/pack.v1.json",
  "title": "Glimmervoid pack",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
      "description": "Unique among installed packs; a second pack with the same name is refused. Theme and panel ids are scoped to it, so they never clash with another pack"
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Your release number, shown to the operator beside the pack; raise it with each change. Approval follows the files, not this number: any changed file asks again"
    },
    "description": {
      "type": "string",
      "maxLength": 500
    },
    "preview": {
      "description": "An image of what the pack adds, shown on its card in the Packs tab before it is approved. Glimmervoid releases after 0.58.4 read it; older ones refuse a manifest that sets it",
      "type": "string",
      "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))[A-Za-z0-9._/-]{1,200}$"
    },
    "requires": {
      "default": {
        "env": [],
        "programs": []
      },
      "type": "object",
      "properties": {
        "env": {
          "default": [],
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
          }
        },
        "programs": {
          "default": [],
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]*$"
          }
        }
      },
      "additionalProperties": false
    },
    "prFlows": {
      "description": "PR flows this pack adds; one invalid entry skips the whole section",
      "type": "object",
      "properties": {
        "repos": {
          "description": "The default owner/name repositories, matched case-insensitively, for every prAction, source and rule of this pack that lists no repos of its own; an entry's own repos narrow this default to the repositories both list; every repository when absent",
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
          }
        },
        "prActions": {
          "default": [],
          "description": "Buttons on a pull request; the command prints {\"outcome\":\"done|started|refused|failed\",\"message\":\"...\"}, and one that prints started reports later with glimmervoid pr-action report",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
                "description": "Unique within its list; inside a pack it is shown as <pack>/<id>"
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 24,
                "description": "The name shown to the operator; rules never match on it"
              },
              "command": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "The program and its arguments, run without a shell from the Glimmervoid home folder; an argument may hold {prUrl}, {repo}, {number}, {head}, {headRef}, {baseRef}, and in a pack also {packDir}, the pack's folder. Its environment has GLIMMERVOID_PR_URL, GLIMMERVOID_PR_REPO, GLIMMERVOID_PR_NUMBER and GLIMMERVOID_PR_HEAD, GLIMMERVOID_PR_HEAD_REF, GLIMMERVOID_PR_BASE_REF and the pull request as GLIMMERVOID_PR_JSON. Exit 0 means done and any other exit failed, unless stdout prints the action outcome JSON (glimmervoid packs guide --schema pr-flows)"
              },
              "timeoutSeconds": {
                "default": 120,
                "description": "Seconds before the command is stopped",
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 3600
              },
              "repos": {
                "description": "The owner/name repositories this applies to; every repository when absent",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
                }
              }
            },
            "required": [
              "id",
              "label",
              "command"
            ],
            "additionalProperties": false
          }
        },
        "sources": {
          "default": [],
          "description": "Commands run on each pull request that print {\"findings\":[{\"path\",\"lineStart\",\"lineEnd\",\"priority\",\"body\",\"url\"}],\"status\":[{\"label\",\"state\"}]}, at most 200 findings and 4 status lines",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
                "description": "Unique within its list; inside a pack it is shown as <pack>/<id>"
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 24,
                "description": "The name shown to the operator; rules never match on it"
              },
              "command": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "The program and its arguments, run without a shell from the Glimmervoid home folder; an argument may hold {prUrl}, {repo}, {number}, {head}, and in a pack also {packDir}, the pack's folder. Its environment has GLIMMERVOID_PR_URL, GLIMMERVOID_PR_REPO, GLIMMERVOID_PR_NUMBER and GLIMMERVOID_PR_HEAD. It must print the source output JSON (glimmervoid packs guide --schema pr-flows) on stdout; anything else shows as an error on the pull request"
              },
              "timeoutSeconds": {
                "default": 120,
                "description": "Seconds before the command is stopped",
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 3600
              },
              "repos": {
                "description": "The owner/name repositories this applies to; every repository when absent",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
                }
              }
            },
            "required": [
              "id",
              "label",
              "command"
            ],
            "additionalProperties": false
          }
        },
        "actions": {
          "default": [],
          "description": "Commands rules run on one review item with run:<id>; they print {\"outcome\":\"done|started|refused|failed\",\"message\":\"...\"} and are limited to repositories only through the rules that name them",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
                "description": "Unique within its list; inside a pack it is shown as <pack>/<id>"
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 24,
                "description": "The name shown to the operator; rules never match on it"
              },
              "command": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "The program and its arguments, run without a shell from the Glimmervoid home folder; an argument may hold {prUrl}, {repo}, {number}, {head}, {itemPath}, {itemLine}, and in a pack also {packDir}, the pack's folder. Its environment has GLIMMERVOID_PR_URL, GLIMMERVOID_PR_REPO, GLIMMERVOID_PR_NUMBER and GLIMMERVOID_PR_HEAD, and the review item as GLIMMERVOID_ITEM_JSON. Exit 0 means done and any other exit failed, unless stdout prints the action outcome JSON (glimmervoid packs guide --schema pr-flows)"
              },
              "timeoutSeconds": {
                "default": 120,
                "description": "Seconds before the command is stopped",
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 3600
              }
            },
            "required": [
              "id",
              "label",
              "command"
            ],
            "additionalProperties": false
          }
        },
        "rules": {
          "default": [],
          "description": "Run after your own config.json rules; the first rule that matches an item decides it",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80,
                "pattern": "\\S"
              },
              "sources": {
                "description": "The bare ids of this pack's sources the rule acts on. An item merged from several sources matches only when every one of them is listed here or under authors; any source when both are absent",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                }
              },
              "authors": {
                "description": "The GitHub logins of review comment authors this rule acts on, compared case-insensitively. An item merged from several sources matches only when every one of them is listed here or under authors; any source when both are absent",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "priority": {
                "description": "The finding priorities this rule acts on; any priority when absent",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "blocker",
                    "high",
                    "medium",
                    "low",
                    "unknown"
                  ]
                }
              },
              "paths": {
                "description": "Repository paths; an entry ending in / matches every path under it, any other matches that exact path",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "text": {
                "description": "Text the finding must contain, compared case-insensitively",
                "type": "string",
                "minLength": 1
              },
              "scope": {
                "default": "mine",
                "description": "Rules act only on your own pull requests today, so mine and both act there and team never acts yet",
                "type": "string",
                "enum": [
                  "mine",
                  "team",
                  "both"
                ]
              },
              "repos": {
                "description": "The owner/name repositories this applies to; every repository when absent",
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
                }
              },
              "action": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "ask",
                      "fix-local",
                      "dismiss"
                    ]
                  },
                  {
                    "type": "string",
                    "pattern": "^run:[a-z0-9][a-z0-9-]{0,63}$"
                  }
                ],
                "description": "ask waits for you, fix-local hands the item to a local session, dismiss replies with reason and resolves it, run:<id> runs that action; run:<id> names an action of this pack by its bare id"
              },
              "reason": {
                "description": "The reply posted when the rule dismisses an item",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "name",
              "action"
            ],
            "additionalProperties": false,
            "if": {
              "properties": {
                "action": {
                  "const": "dismiss"
                }
              },
              "required": [
                "action"
              ]
            },
            "then": {
              "required": [
                "reason"
              ]
            }
          }
        }
      },
      "additionalProperties": false
    },
    "ui": {
      "type": "object",
      "properties": {
        "themes": {
          "default": [],
          "maxItems": 8,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40,
                "description": "The name shown in the Theme picker"
              },
              "mode": {
                "type": "string",
                "enum": [
                  "dark",
                  "light"
                ],
                "description": "Whether the theme is dark or light, which picks the terminal palette its ANSI colors are tuned for"
              },
              "accentAnsiSlot": {
                "type": "string",
                "enum": [
                  "blue",
                  "magenta",
                  "none"
                ],
                "description": "The terminal ANSI color the accent replaces, with a lighter mix of it as that color's bright variant; none leaves terminal colors alone"
              },
              "chrome": {
                "type": "object",
                "properties": {
                  "bg": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Page background"
                  },
                  "bg-card": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Cards, panes and the terminal background"
                  },
                  "bg-header": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Headers and toolbars"
                  },
                  "bg-surface": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Raised controls: chips, inputs, menus and hover fills"
                  },
                  "border": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Default borders"
                  },
                  "border-dim": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Faint dividers inside a card or list"
                  },
                  "border-hover": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Borders of a hovered or focused control"
                  },
                  "text": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Body text"
                  },
                  "text-dim": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Secondary text such as hints and empty states"
                  },
                  "text-head": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Headings and emphasized text"
                  },
                  "text-muted": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Labels and metadata, between text and text-dim"
                  },
                  "accent": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Links, focus rings, selection and primary actions"
                  },
                  "accent-dim": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "A quieter accent for selected borders"
                  }
                },
                "required": [
                  "bg",
                  "bg-card",
                  "bg-header",
                  "bg-surface",
                  "border",
                  "border-dim",
                  "border-hover",
                  "text",
                  "text-dim",
                  "text-head",
                  "text-muted",
                  "accent",
                  "accent-dim"
                ],
                "additionalProperties": false,
                "description": "Dashboard colors; each key becomes the CSS custom property --<key>"
              },
              "states": {
                "type": "object",
                "properties": {
                  "running": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "waiting": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "failed": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "monitoring": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "done": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "initializing": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "idle": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "starting": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  },
                  "complete": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  }
                },
                "required": [
                  "running",
                  "waiting",
                  "failed",
                  "monitoring",
                  "done",
                  "initializing",
                  "idle",
                  "starting",
                  "complete"
                ],
                "additionalProperties": false,
                "description": "One color per session state, shown as --state-<state> on cards, dots and badges"
              },
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
              }
            },
            "required": [
              "label",
              "mode",
              "accentAnsiSlot",
              "chrome",
              "states",
              "id"
            ],
            "additionalProperties": false
          }
        },
        "panels": {
          "default": [],
          "maxItems": 8,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 24
              },
              "entry": {
                "type": "string",
                "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))[A-Za-z0-9._/-]{1,200}$",
                "description": "The HTML page the panel opens, relative to the pack folder"
              },
              "icon": {
                "type": "string",
                "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))[A-Za-z0-9._/-]{1,200}$"
              },
              "reads": {
                "default": [],
                "description": "The bridge topics this panel may receive; the operator sees them before approving, and a subscribe for any other topic is ignored",
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "sessions",
                    "focus",
                    "theme",
                    "usage",
                    "attention",
                    "reviews",
                    "providers"
                  ]
                }
              },
              "acts": {
                "default": [],
                "description": "What this panel may do as the operator, without asking again: reviews lets it post, discard or requeue team reviews and resolve their threads, open an agent session on a pull request, merge your pull requests, turn merge when ready on or off, turn keep mergeable on or off, dismiss review items, hand them to a session or run their actions, reopen handled review items, save rules to your config, approve PR flow commands, run PR actions; sessions lets it start an agent session with any prompt in any project, and type text into any live session on this machine, using the pack sessions settings; the operator sees it before approving",
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "reviews",
                    "sessions"
                  ]
                }
              }
            },
            "required": [
              "id",
              "label",
              "entry"
            ],
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "launchers": {
      "description": "Buttons in the Add session picker, each starting a session with its own prompt",
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
          },
          "label": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_\\-. ()]{1,24}$",
            "description": "The button text, also the name of the session it starts"
          },
          "project": {
            "type": "string",
            "maxLength": 4096,
            "pattern": "^(?:[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+|\\/.+|[A-Za-z]:[\\\\/].*)$",
            "description": "owner/name: the first configured project whose origin is that GitHub repository; or an absolute path of a folder on this machine. A launcher whose project matches nothing shows disabled"
          },
          "agent": {
            "type": "string",
            "enum": [
              "claude-code",
              "codex",
              "kimi",
              "opencode",
              "pi",
              "antigravity"
            ],
            "description": "The agent the session runs"
          },
          "model": {
            "description": "The model passed to the agent, as its own --model flag takes it; absent uses the agent default",
            "type": "string",
            "maxLength": 200,
            "pattern": "^[A-Za-z0-9._:/[\\]-]+$"
          },
          "effort": {
            "description": "The reasoning effort passed to the agent, such as low, medium or high; absent uses the agent default",
            "type": "string",
            "maxLength": 40,
            "pattern": "^[A-Za-z0-9._:/[\\]-]+$"
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000,
            "pattern": "^[\\P{C}\\n\\t]*$",
            "description": "The first prompt the session gets"
          },
          "schedule": {
            "description": "A cron pattern of five fields in the operator timezone; the launcher also starts its session on this schedule, skipping a run while its last scheduled session is still live, and catching up runs missed while Glimmervoid was down only with catchUp",
            "type": "string",
            "maxLength": 100
          },
          "catchUp": {
            "description": "With a schedule, start one run at once when a scheduled run fell while Glimmervoid was down or the host slept; off skips missed runs",
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "label",
          "project",
          "agent",
          "prompt"
        ],
        "additionalProperties": false
      }
    },
    "sessions": {
      "description": "Permission settings for every session this pack starts",
      "type": "object",
      "properties": {
        "dangerouslySkipPermissions": {
          "default": false,
          "description": "Sessions this pack starts skip the agent's permission prompts; the operator sees it before approving",
          "type": "boolean"
        },
        "saneYolo": {
          "description": "With dangerouslySkipPermissions, also catch risky commands with Sane YOLO; absent follows the operator's default",
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "status": {
      "description": "Status pages its panels read through the providers topic",
      "type": "object",
      "properties": {
        "urls": {
          "maxItems": 8,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri"
          },
          "description": "Statuspage summary URLs, such as https://www.githubstatus.com/api/v2/summary.json; the providers topic carries their open incidents"
        }
      },
      "required": [
        "urls"
      ],
      "additionalProperties": false
    },
    "agent": {
      "description": "Context and skills every session's agent gets once the operator approves the pack",
      "type": "object",
      "properties": {
        "context": {
          "description": "A file in the pack that every session's first prompt names, so the agent reads it when the task touches what it covers; the operator reads it word for word before approving",
          "type": "string",
          "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))[A-Za-z0-9._/-]{1,200}$"
        },
        "skills": {
          "default": [],
          "description": "Skill folders in the pack, each holding a SKILL.md; every session gets them, as /<pack>:<folder name> on Claude Code and <pack>-<folder name> on Codex and Kimi Code",
          "maxItems": 32,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))[A-Za-z0-9._/-]{1,200}$"
          }
        }
      },
      "additionalProperties": false
    },
    "mcp": {
      "description": "MCP servers every session gets once the pack is approved. Glimmervoid releases after 0.62.8 read it; older ones refuse a manifest that sets it",
      "type": "object",
      "properties": {
        "servers": {
          "minItems": 1,
          "maxItems": 8,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$",
                "not": {
                  "const": "glimmervoid"
                },
                "description": "The name every agent lists the server under; a server the operator registered under the same name gives way to this one in glimmervoid sessions"
              },
              "url": {
                "type": "string",
                "format": "uri",
                "pattern": "^(https://|http://(127\\.0\\.0\\.1|localhost|\\[::1\\])([:/?#]|$))[^$]*$",
                "description": "The streamable HTTP MCP endpoint; with no secret the agent signs in through its own MCP OAuth login"
              },
              "secret": {
                "description": "A bearer token sent to this server: glimmervoid reads the name from the vault at session start once the operator allows it for the project, and passes it by environment variable, never argv; while it is denied or cannot be read, a Gemini CLI or Kimi Code session fails its sign-in and any other session leaves the server out",
                "type": "string",
                "pattern": "^[A-Z_][A-Z0-9_]{0,127}$"
              }
            },
            "required": [
              "name",
              "url"
            ],
            "additionalProperties": false
          },
          "description": "MCP servers every locally launched glimmervoid session gets once the operator approves the pack"
        }
      },
      "required": [
        "servers"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "name",
    "version"
  ],
  "additionalProperties": false
}
