kit.json

Every key of a Site Kit's kit.json (id, version, permissions, anchors, settings, palette, sidebar, theme), and the group's site, with what each does.

kit.json sits at the top of the kit's folder. Switchboard checks it each time you save: a problem names the file and key ("kit.json: anchors.prHeader.selectors must have at least one selector") and the kit keeps running its last good version. Keys it doesn't know are kept.

key
`id`	Required. `kit.` and a name, such as `kit.github-plus`. It stays the same in every version; a kit imported with an id you already have is an update.
`version`	Required. Semantic: `1.2.0`. Raise it when you share a change.
`name`	Shown when it differs from the group's name.
`permissions`	What the kit may read. See below.
`anchors`	Named places in the page. See below.
`settings`	Options the person can change. See below.
`palette`	`{ "hotkey": "⌥⌘K" }`. The key that opens the kit's command palette in the page.
`sidebar`	`{ "title": "PR notes" }`. Having this key gives the kit a sidebar; the title is its heading.
`theme`	`"site"` (default): follow the site's look. `"switchboard"`: the fixed house look, for a kit that is its own tool and not part of the site.

The group's site #

Which pages the kit runs on is not in kit.json but in the group (group.json), under site:

{ "site": { "match": ["github.com/*"], "browser": "any", "exclude": ["gist.github.com/*"] } }

match and exclude are address patterns; one with no :// means any scheme. browser is safari, chrome or any. A macro in the group that has a browser trigger with no address of its own takes match.

permissions #

"permissions": { "mainWorld": true, "responses": ["/graphql", "/*/pull/*/checks*"] }

mainWorld: run the kit's JavaScript in the page's own world instead of the isolated one. Needed to read the site's responses. Default false. Chrome also needs Allow User Scripts.
responses: the address paths kit.onResponse and the A kit reads the site's data trigger may read. :name matches one segment, * anything. Anything not listed is refused. When a kit is shared, these are shown in words before it is installed.

anchors #

"anchors": {
  "prHeader": {
    "selectors": [".gh-header-actions", "role=toolbar[name=\"Pull request\"]"],
    "routes": ["/:owner/:repo/pull/:id"],
    "required": true,
    "text": "the row of buttons at the top right of a pull request"
  }
}

selectors: at least one, tried in order. The first is the best; the rest are fallbacks. Besides CSS, a selector can be text=Files changed, role=button[name="Merge"] or contain >>> to cross into a shadow root.
routes: the route patterns the anchor is used on. The health check reports per route.
required: if it misses on its route, the kit is marked unhealthy (a warning badge, a row in Activity). An optional anchor is only listed.
text: a sentence about what the element is. Repair with AI reads it to find the element again.

ctx.anchor(name) returns the element for the first selector that matches, and reports hit, fallback or miss.

settings #

"settings": {
  "compact": { "type": "bool", "default": false, "label": "Compact diff", "help": "Tighter lines in Files changed." },
  "editor":  { "type": "choice", "default": "vscode", "label": "Editor", "choices": ["vscode", "cursor"] }
}

type is bool, text, number, choice (with choices) or color. label is required, help is the small line under it. The form is drawn from this in the Kit tab and behind the ⚙ in the kit's sidebar. The person's values are kept apart from the kit, so updating the kit keeps them. Read them with ctx.settings.name, kit.settings.get("name") or {{ kit.setting.name }} in a macro.

Files #

Beside kit.json: features/*.js, lib/*.js, styles/*.css, html/*.html and snapshots/*.html. Site Kits says what each is for. Switchboard never deletes a file in the folder that it doesn't know about.