{
  "$comment": "Zenith Launcher — machine-readable reference. Every menu, control, default and gate, structured for assistants and tooling. Human manual: /user-guide/ · plain text: /user-guide/zenith-manual.md",
  "app": {
    "name": "Zenith Launcher",
    "package": "com.zenith.launcher",
    "build": "b0.8",
    "minAndroid": "8.0 (SDK 26)",
    "developer": "Black Syntax",
    "publisher": "Friend Castle",
    "contact": "zenith@blacksyntax.com",
    "site": "https://zenith.blacksyntax.com/",
    "defaultOrientation": "portrait",
    "monetisation": "free, with a one-time Zenith Gold unlock"
  },
  "coreGesture": {
    "summary": "Press and hold on empty sky; a ring of app-stars blooms under the finger. Slide onto a star and lift to open it. Lift on empty sky to dissolve everything.",
    "steps": [
      "hold empty sky (default 220 ms)",
      "ring blooms centred on the finger",
      "slide onto a star (label appears, haptic tick)",
      "lift to launch — or slide to empty sky and lift to cancel"
    ],
    "folderDescent": "Rest on a folder star for the bloom delay (default 330 ms); its ring blooms and the previous ring vanishes, leaving a chevron marker at the point your line came from. Trace back into that marker to fold the ring shut.",
    "states": [
      "idle",
      "pending",
      "flick",
      "active",
      "all_apps",
      "comet"
    ]
  },
  "timings": [
    {
      "id": "holdDelayMs",
      "label": "hold delay / ring opens after",
      "default": 220,
      "unit": "ms",
      "range": [
        120,
        450
      ],
      "rangeAccessibility": [
        120,
        600
      ],
      "where": "settings › rings & effects · settings › accessibility › extended"
    },
    {
      "id": "delayFolderBloom",
      "label": "folder ring blooms after",
      "default": 330,
      "unit": "ms",
      "range": [
        150,
        1200
      ],
      "where": "settings › accessibility › extended"
    },
    {
      "id": "delayDoubleTap",
      "label": "double-tap window",
      "default": 340,
      "unit": "ms",
      "range": [
        200,
        700
      ],
      "where": "settings › accessibility › extended"
    },
    {
      "id": "a11yDwellMs",
      "label": "dwell to select",
      "default": 900,
      "unit": "ms",
      "range": [
        400,
        2500
      ],
      "where": "settings › accessibility › motor"
    },
    {
      "id": "ritualStep",
      "label": "ritual step spacing",
      "default": 650,
      "unit": "ms",
      "fixed": true
    },
    {
      "id": "breathe",
      "label": "breathe pause before opening",
      "default": 2600,
      "unit": "ms",
      "fixed": true
    },
    {
      "id": "veilRest",
      "label": "veil rest-to-unseal",
      "default": 4000,
      "unit": "ms",
      "fixed": true
    },
    {
      "id": "cometLife",
      "label": "comet flight",
      "default": "11000–17500",
      "unit": "ms",
      "fixed": true
    },
    {
      "id": "flickWindow",
      "label": "flick must complete within",
      "default": 330,
      "unit": "ms",
      "fixed": true
    }
  ],
  "hitZones": [
    {
      "id": "corner",
      "size": "52 × 52 dp",
      "note": "each of four corners; a hold here runs the corner action instead of opening a ring"
    },
    {
      "id": "edgeBand",
      "size": "18 dp",
      "note": "the strip along each edge between the corners"
    },
    {
      "id": "edgeIndexDrag",
      "size": "26 dp from the right edge, drag inward 36 dp",
      "note": "only when 'drag in from the right edge' is on"
    },
    {
      "id": "starHit",
      "size": "1.4 × star radius, multiplied by a11yHitboxScale (1.0–2.5×)"
    },
    {
      "id": "cometHead",
      "size": "34 dp",
      "note": "hold within this of a comet's head to catch it"
    },
    {
      "id": "flickMinDistance",
      "size": "55 dp"
    },
    {
      "id": "talismanMinLength",
      "size": "90 dp of stroke travel"
    },
    {
      "id": "circleMinLength",
      "size": "140 dp of stroke travel, bounding box > 50 dp each way"
    }
  ],
  "dock": {
    "description": "Four buttons up the left edge, 60 dp in from the left, visible only while a ring is open. ✛ is always shown; ◈ ✎ − appear once a star has been touched.",
    "toggle": "settings › rings & effects › show dock buttons",
    "buttons": [
      {
        "glyph": "✛",
        "name": "add",
        "heightAboveBottomDp": 246,
        "radiusDp": 28,
        "actsOn": "the star under the finger, else the open ring",
        "onRelease": "opens the add sheet",
        "onSecondFingerTap": "starts live placement — the held thumb positions the new star"
      },
      {
        "glyph": "◈",
        "name": "icon",
        "heightAboveBottomDp": 182,
        "radiusDp": 24,
        "actsOn": "the last star touched",
        "onRelease": "opens the icon picker",
        "onSecondFingerTap": "same, ends the gesture"
      },
      {
        "glyph": "✎",
        "name": "edit",
        "heightAboveBottomDp": 118,
        "radiusDp": 24,
        "actsOn": "the last star touched",
        "onRelease": "opens the star editor",
        "onSecondFingerTap": "same, ends the gesture"
      },
      {
        "glyph": "−",
        "name": "remove",
        "heightAboveBottomDp": 54,
        "radiusDp": 24,
        "actsOn": "the last star touched",
        "onRelease": "removes it",
        "onSecondFingerTap": "removes it and keeps the ring open"
      }
    ]
  },
  "nodeTypes": [
    {
      "id": "APP",
      "drawnAs": "the app's icon in a disc",
      "onRelease": "launches the app"
    },
    {
      "id": "FOLDER",
      "drawnAs": "a tiny orbit — centre point with three circling moons",
      "onRelease": "nothing (dwell to descend); a ritual folder launches everything inside"
    },
    {
      "id": "SHORTCUT",
      "drawnAs": "the shortcut's icon",
      "onRelease": "runs the app shortcut",
      "requires": "Zenith must be the default launcher"
    },
    {
      "id": "WIDGET",
      "drawnAs": "a small square outline with a dot",
      "onRelease": "opens the widget as a floating window"
    }
  ],
  "nodeFlags": [
    {
      "id": "hybrid",
      "meaning": "any non-folder star that also has children; wears a faint band. Dwell blooms its ring, release launches it."
    },
    {
      "id": "ritual",
      "meaning": "a folder flagged in the ✎ editor; releasing on it activates everything inside, in order, 650 ms apart. Wears a double band."
    },
    {
      "id": "breathe",
      "meaning": "a 2.6 s pause with a pulsing circle before the app opens; tap during it to stay."
    }
  ],
  "geometry": {
    "angle": "degrees, 0° straight up, increasing clockwise (as shown in placement and spoken by TalkBack)",
    "orbit": {
      "unit": "multiplier of the base ring radius",
      "min": 0.4,
      "max": 6,
      "snapStep": 0.25,
      "siblingMagnet": "an existing sibling orbit wins only when genuinely nearer than the closest quarter step"
    },
    "baseRadiusDp": {
      "default": 150,
      "range": [
        80,
        280
      ]
    },
    "starRadiusDp": {
      "default": 26,
      "range": [
        18,
        36
      ]
    }
  },
  "actions": [
    {
      "id": "NONE",
      "label": "—",
      "does": "nothing; a hold here opens a ring instead"
    },
    {
      "id": "SETTINGS",
      "label": "settings",
      "does": "opens Zenith settings"
    },
    {
      "id": "DEEP_SKY",
      "label": "deep sky",
      "does": "opens the searchable all-apps list"
    },
    {
      "id": "INDEX",
      "label": "star index",
      "does": "opens the all-apps semicircle"
    },
    {
      "id": "SHADE",
      "label": "shade",
      "does": "pulls down the notification shade",
      "requires": "zenith actions (statusbar fallback on some builds)"
    },
    {
      "id": "QUICK_SETTINGS",
      "label": "quick tiles",
      "does": "opens quick settings",
      "requires": "zenith actions"
    },
    {
      "id": "LOCK",
      "label": "lock",
      "does": "locks the screen",
      "requires": "zenith actions · Android 9+"
    },
    {
      "id": "RECENTS",
      "label": "recents",
      "does": "opens the recent-apps switcher",
      "requires": "zenith actions"
    },
    {
      "id": "SCREENSHOT",
      "label": "screenshot",
      "does": "takes a screenshot",
      "requires": "zenith actions · Android 9+"
    },
    {
      "id": "POWER",
      "label": "power menu",
      "does": "opens the power dialogue",
      "requires": "zenith actions"
    },
    {
      "id": "BACK",
      "label": "back",
      "does": "system back",
      "requires": "zenith actions"
    },
    {
      "id": "HOME",
      "label": "home",
      "does": "system home",
      "requires": "zenith actions"
    },
    {
      "id": "VEIL",
      "label": "seal the sky",
      "does": "draws the Sky Veil immediately"
    },
    {
      "id": "APP",
      "label": "app or shortcut",
      "does": "opens any app or app-shortcut bound to this position"
    }
  ],
  "gesturePositions": [
    {
      "slot": "cornerBL",
      "label": "↙ bottom-left corner",
      "fires": "hold in the 52 dp corner",
      "default": "SETTINGS"
    },
    {
      "slot": "cornerBR",
      "label": "↘ bottom-right corner",
      "fires": "hold in the 52 dp corner",
      "default": "DEEP_SKY"
    },
    {
      "slot": "cornerTL",
      "label": "↖ top-left corner",
      "fires": "hold in the 52 dp corner",
      "default": "SHADE"
    },
    {
      "slot": "cornerTR",
      "label": "↗ top-right corner",
      "fires": "hold in the 52 dp corner",
      "default": "LOCK"
    },
    {
      "slot": "edgeL",
      "label": "← left edge",
      "fires": "hold on the 18 dp band",
      "default": "NONE"
    },
    {
      "slot": "edgeR",
      "label": "→ right edge",
      "fires": "hold on the 18 dp band",
      "default": "NONE"
    },
    {
      "slot": "edgeT",
      "label": "↑ top edge",
      "fires": "hold on the 18 dp band",
      "default": "NONE"
    },
    {
      "slot": "edgeB",
      "label": "↓ bottom edge",
      "fires": "hold on the 18 dp band",
      "default": "NONE"
    },
    {
      "slot": "flickUp",
      "label": "↑ flick up",
      "fires": "quick swipe ≥55 dp within 330 ms",
      "default": "DEEP_SKY"
    },
    {
      "slot": "flickDown",
      "label": "↓ flick down",
      "fires": "quick swipe ≥55 dp within 330 ms",
      "default": "SHADE"
    },
    {
      "slot": "flickLeft",
      "label": "← flick left",
      "fires": "quick swipe",
      "default": "NONE",
      "caveat": "Android's back gesture wins on gesture-nav devices"
    },
    {
      "slot": "flickRight",
      "label": "→ flick right",
      "fires": "quick swipe",
      "default": "NONE",
      "caveat": "Android's back gesture wins on gesture-nav devices"
    },
    {
      "slot": "doubleTap",
      "label": "◎◎ double-tap on the sky",
      "fires": "two taps within the double-tap window, <48 dp apart",
      "default": "LOCK"
    }
  ],
  "menus": {
    "settingsMain": {
      "openBy": [
        "tap the ⚙︎ in the lower-left corner",
        "hold the lower-left corner",
        "Deep Sky › ✦ zenith settings"
      ],
      "items": [
        "✦ ICON MODE / ☰ LIST MODE switch",
        "skies (create · rename · delete · switch)",
        "the twelve pages",
        "· close ·"
      ],
      "backBehaviour": "back walks up one level; it only leaves settings from the main page"
    },
    "settingsPages": [
      {
        "title": "talismans",
        "hint": "inscribe · playback · priority order"
      },
      {
        "title": "system",
        "hint": "default launcher · status bar · zenith actions"
      },
      {
        "title": "gestures",
        "hint": "corners · edges · flicks · double-tap"
      },
      {
        "title": "regions & star index",
        "hint": "layout editor · all-apps triggers"
      },
      {
        "title": "background & light",
        "hint": "colors · wallpaper · icon set"
      },
      {
        "title": "rings & effects",
        "hint": "sizes · labels · sparks · trails"
      },
      {
        "title": "the sky's voice",
        "hint": "astral tones · ambient drone · scale"
      },
      {
        "title": "accessibility",
        "hint": "dwell · latched · magnify · spoken · haptics"
      },
      {
        "title": "sky overlays",
        "hint": "clock · date · weather · position"
      },
      {
        "title": "star chart",
        "hint": "backup · hidden apps · reset"
      },
      {
        "title": "privacy & permissions",
        "hint": "no spyware · what each permission does"
      },
      {
        "title": "about",
        "hint": "black syntax · friend castle · version"
      }
    ],
    "addSheet": {
      "openBy": "slide onto ✛ during a hold (or second-finger tap it)",
      "tabs": [
        {
          "name": "Apps",
          "lists": "every installed personal-profile app, searchable",
          "tapDoes": "places it as a star"
        },
        {
          "name": "Folder",
          "lists": "a name field",
          "tapDoes": "create ✦ makes an empty folder star"
        },
        {
          "name": "Widgets",
          "lists": "installed widget providers, alphabetical",
          "tapDoes": "binds, configures and places the widget"
        },
        {
          "name": "Shortcuts",
          "lists": "apps, then the shortcuts each publishes",
          "tapDoes": "places the shortcut",
          "requires": "Zenith must be the default launcher"
        },
        {
          "name": "Direct",
          "lists": "everything other apps pinned into Zenith, newest first",
          "tapDoes": "places it; 'forget' drops it from the list only"
        },
        {
          "name": "Edit",
          "lists": "this ring's stars",
          "tapDoes": "colour dot cycles colour · name renames · ◎ re-place · ✕ remove"
        }
      ]
    },
    "starEditor": {
      "openBy": "touch a star during a hold, then slide onto ✎",
      "controls": [
        {
          "name": "name",
          "type": "text",
          "appliesTo": "all"
        },
        {
          "name": "light color",
          "type": "swatches from the theme palette",
          "appliesTo": "all"
        },
        {
          "name": "show label",
          "type": "switch",
          "appliesTo": "all"
        },
        {
          "name": "show app icon",
          "type": "switch",
          "appliesTo": "app · shortcut"
        },
        {
          "name": "breathe before opening",
          "type": "switch",
          "appliesTo": "app · shortcut"
        },
        {
          "name": "ritual",
          "type": "switch",
          "appliesTo": "folder"
        },
        {
          "name": "haptic signature",
          "type": "8-slot timeline, each slot still · small · big",
          "appliesTo": "all",
          "extras": [
            "▶ feel",
            "clear",
            "preset → (pulse · triple tick · swell · double knock)"
          ]
        },
        {
          "name": "uninstall app from device…",
          "type": "link",
          "appliesTo": "app"
        },
        {
          "name": "◎ re-place",
          "type": "button",
          "appliesTo": "all"
        },
        {
          "name": "− remove",
          "type": "button",
          "appliesTo": "all"
        },
        {
          "name": "done ✦",
          "type": "button",
          "appliesTo": "all"
        }
      ]
    },
    "iconPicker": {
      "openBy": "touch a star during a hold, then slide onto ◈ (or Deep Sky › long-press an app › ◈ set icon)",
      "sections": [
        "zenith set (8 bundled glyphs: star · moon · sun · comet · orbit · spark · eye · rune)",
        "installed icon packs — tap the name for the pack's own match",
        "browse all → the pack's full library in its own categories",
        "choose image… (gold) with a pinch-and-drag round crop",
        "reset icon"
      ],
      "precedence": [
        "1 · this star's custom icon",
        "2 · this app's chosen icon (set from Deep Sky)",
        "3 · the default icon pack",
        "4 · the app's own icon"
      ]
    },
    "deepSky": {
      "openBy": [
        "hold the lower-right corner (default)",
        "flick up (default)",
        "any position assigned to deep sky"
      ],
      "layout": "list first, search box at the bottom so the keyboard never appears unasked",
      "alwaysPresent": "✦ zenith settings as the first row — the guaranteed way back into settings",
      "longPressMenu": [
        "open",
        "view app info",
        "◈ set icon",
        "inscribe talisman for this",
        "hide from deep sky",
        "uninstall…"
      ],
      "workProfile": "work apps are listed and launchable, marked '· work'; they cannot be placed on rings"
    },
    "starIndex": {
      "openBy": [
        "draw a quick circle (on by default)",
        "any position assigned to star index",
        "drag in from the right edge (off by default)",
        "a dedicated region (none by default)"
      ],
      "layout": "a semicircle anchored to the right edge at the height the gesture started; 3–8 letter groups on the inner arc, apps in outer arcs (up to 9, then 12, then the rest)",
      "use": "slide to a group, slide outward to an app, lift to launch"
    },
    "cometMenu": {
      "openBy": "hold on a drifting comet's head",
      "items": [
        "open",
        "dismiss",
        "snooze 30 min"
      ],
      "cancel": "lift off the menu — the comet resumes its flight"
    }
  },
  "settings": {
    "system": [
      {
        "id": "defaultLauncher",
        "label": "set zenith as default launcher →",
        "type": "action"
      },
      {
        "id": "hideStatusBar",
        "label": "hide status bar",
        "type": "switch",
        "default": false
      },
      {
        "id": "showSettingsStar",
        "label": "show ⚙︎ settings corner",
        "type": "switch",
        "default": true
      },
      {
        "id": "orientation",
        "label": "orientation",
        "type": "choice",
        "options": [
          "portrait",
          "landscape",
          "rotate"
        ],
        "default": "portrait"
      },
      {
        "id": "zenithActions",
        "label": "enable zenith actions →",
        "type": "action",
        "note": "accessibility service powering lock, shade, recents, quick tiles, screenshot, power, back, home"
      },
      {
        "id": "isPro",
        "label": "zenith gold",
        "type": "switch",
        "default": false,
        "note": "demo switch in b0.8; Play Billing at v1.0"
      },
      {
        "id": "tutorial",
        "label": "first-time hints",
        "type": "switch",
        "default": true
      },
      {
        "id": "resetHints",
        "label": "reset hints",
        "type": "action"
      },
      {
        "id": "replayWelcome",
        "label": "replay welcome →",
        "type": "action"
      },
      {
        "id": "veilOnWake",
        "label": "veil when the screen sleeps",
        "type": "switch",
        "default": false
      },
      {
        "id": "veilTalismanId",
        "label": "unseal sigil",
        "type": "choice",
        "default": "any talisman"
      },
      {
        "id": "cometsEnabled",
        "label": "notifications drift by as comets",
        "type": "switch",
        "default": true,
        "requires": "notification access"
      }
    ],
    "backgroundAndLight": [
      {
        "id": "theme",
        "label": "theme",
        "type": "choice",
        "default": "clean",
        "options": [
          "clean",
          "mono",
          "pastel",
          "rainbow (gold)",
          "daytime (gold)",
          "mono inverted (gold)",
          "iridescent (gold)",
          "neon (gold)"
        ]
      },
      {
        "id": "bgColor",
        "label": "background",
        "type": "colour",
        "default": "#000000"
      },
      {
        "id": "bgMySky",
        "label": "my sky — the real stars above you",
        "type": "switch",
        "default": false,
        "gold": true
      },
      {
        "id": "bgImageUri",
        "label": "choose image",
        "type": "action",
        "default": null
      },
      {
        "id": "bgDim",
        "label": "image dimming",
        "type": "slider",
        "default": 0.35,
        "range": [
          0,
          0.9
        ]
      },
      {
        "id": "iconPack",
        "label": "icon set",
        "type": "choice",
        "default": "system icons",
        "note": "applying any installed pack is free"
      },
      {
        "id": "starStyle",
        "label": "star style",
        "type": "choice",
        "default": "app icons",
        "options": [
          "app icons",
          "monochrome",
          "text only",
          "inverted mono"
        ]
      },
      {
        "id": "usageLight",
        "label": "usage as light",
        "type": "switch",
        "default": false,
        "note": "often-launched stars glow up to ~30% brighter"
      },
      {
        "id": "accent",
        "label": "accent",
        "type": "colour",
        "default": "#E8E8E6",
        "affects": "rings · labels · clock · trails"
      },
      {
        "id": "talismanColor",
        "label": "talisman ink",
        "type": "colour",
        "default": "#F6E7B9"
      },
      {
        "id": "castGlowColor",
        "label": "cast glow",
        "type": "colour",
        "default": "#F6E7B9"
      }
    ],
    "ringsAndEffects": [
      {
        "id": "ringRadiusDp",
        "label": "orbit radius",
        "type": "slider",
        "default": 150,
        "range": [
          80,
          280
        ],
        "unit": "dp"
      },
      {
        "id": "nodeRadiusDp",
        "label": "star size",
        "type": "slider",
        "default": 26,
        "range": [
          18,
          36
        ],
        "unit": "dp"
      },
      {
        "id": "holdDelayMs",
        "label": "hold delay",
        "type": "slider",
        "default": 220,
        "range": [
          120,
          450
        ],
        "unit": "ms"
      },
      {
        "id": "labels",
        "label": "labels",
        "type": "choice",
        "default": "on hover",
        "options": [
          "off",
          "on hover",
          "always"
        ]
      },
      {
        "id": "haptics",
        "label": "haptic feedback",
        "type": "switch",
        "default": true
      },
      {
        "id": "sparks",
        "label": "birth sparks",
        "type": "switch",
        "default": true,
        "overriddenBy": "reduce motion"
      },
      {
        "id": "sparkIntensity",
        "label": "spark intensity",
        "type": "choice",
        "default": "gentle",
        "options": [
          "twinkle",
          "gentle",
          "lively",
          "🎆 sparkler (gold)"
        ]
      },
      {
        "id": "trails",
        "label": "light trails & comet",
        "type": "switch",
        "default": true,
        "overriddenBy": "reduce motion"
      },
      {
        "id": "trailSustainMs",
        "label": "trail sustain",
        "type": "slider",
        "default": 450,
        "range": [
          0,
          3000
        ],
        "unit": "ms",
        "note": "0 = twinkle only · 3000 = permanent until release"
      },
      {
        "id": "strokeWidthDp",
        "label": "trail thickness",
        "type": "slider",
        "default": 4,
        "range": [
          2,
          10
        ],
        "unit": "dp"
      },
      {
        "id": "strokeGlow",
        "label": "trail glow",
        "type": "slider",
        "default": 10,
        "range": [
          0,
          25
        ],
        "overriddenBy": "remove glows"
      },
      {
        "id": "starLineDp",
        "label": "line thickness",
        "type": "slider",
        "default": 1.8,
        "range": [
          0.5,
          5
        ],
        "unit": "dp"
      },
      {
        "id": "starGlow",
        "label": "star & orbit glow",
        "type": "slider",
        "default": 10,
        "range": [
          0,
          25
        ],
        "overriddenBy": "remove glows"
      },
      {
        "id": "twinkleAmount",
        "label": "✨ twinkle",
        "type": "slider",
        "default": 0,
        "range": [
          0,
          100
        ],
        "gold": true
      },
      {
        "id": "showPlus",
        "label": "show dock buttons (✛ ◈ ✎ −)",
        "type": "switch",
        "default": true
      },
      {
        "id": "showCornerHint",
        "label": "show corner & edge hints",
        "type": "switch",
        "default": true
      }
    ],
    "regionsAndStarIndex": [
      {
        "id": "regionCount",
        "label": "region layout editor",
        "type": "editor",
        "default": 1,
        "range": [
          1,
          9
        ],
        "freeMax": 2
      },
      {
        "id": "showRegionHints",
        "label": "show region borders while holding",
        "type": "switch",
        "default": true
      },
      {
        "id": "circleIndex",
        "label": "draw a quick circle to open",
        "type": "switch",
        "default": true
      },
      {
        "id": "edgeIndex",
        "label": "drag in from the right edge",
        "type": "switch",
        "default": false
      },
      {
        "id": "indexRegion",
        "label": "open from a region",
        "type": "choice",
        "default": "—"
      }
    ],
    "skyOverlays": [
      {
        "id": "overlayPos",
        "label": "position on screen",
        "type": "3×3 grid",
        "default": "top centre"
      },
      {
        "id": "showClock",
        "label": "clock",
        "type": "switch",
        "default": true,
        "tapOpens": "alarms"
      },
      {
        "id": "use24h",
        "label": "24-hour time",
        "type": "switch",
        "default": false
      },
      {
        "id": "showDate",
        "label": "date",
        "type": "switch",
        "default": true,
        "tapOpens": "calendar"
      },
      {
        "id": "showBattery",
        "label": "battery",
        "type": "switch",
        "default": false,
        "tapOpens": "battery usage"
      },
      {
        "id": "showNextEvent",
        "label": "next calendar event",
        "type": "switch",
        "default": false,
        "requires": "READ_CALENDAR"
      },
      {
        "id": "showWeather",
        "label": "weather",
        "type": "switch",
        "default": false,
        "requires": "ACCESS_COARSE_LOCATION",
        "tapDoes": "refresh; auto-refreshes every 30 min"
      },
      {
        "id": "weatherCelsius",
        "label": "celsius",
        "type": "switch",
        "default": true
      }
    ],
    "sound": [
      {
        "id": "soundEnabled",
        "label": "✧ sound",
        "type": "switch",
        "default": false,
        "gold": true
      },
      {
        "id": "soundVolume",
        "label": "volume",
        "type": "slider",
        "default": 50,
        "range": [
          0,
          100
        ]
      },
      {
        "id": "soundStars",
        "label": "stars",
        "type": "switch",
        "default": true
      },
      {
        "id": "soundRings",
        "label": "rings",
        "type": "switch",
        "default": true
      },
      {
        "id": "soundLaunch",
        "label": "opening",
        "type": "switch",
        "default": true
      },
      {
        "id": "soundCast",
        "label": "talismans & comets",
        "type": "switch",
        "default": true
      },
      {
        "id": "soundAmbient",
        "label": "ambient drone",
        "type": "switch",
        "default": false
      },
      {
        "id": "soundScale",
        "label": "tuning",
        "type": "choice",
        "default": "open",
        "options": [
          "open (major pentatonic)",
          "deep (minor pentatonic)",
          "floating (lydian)"
        ]
      }
    ],
    "accessibility": [
      {
        "id": "a11yDwellSelect",
        "label": "dwell to select",
        "type": "switch",
        "default": false
      },
      {
        "id": "a11yDwellMs",
        "label": "dwell time",
        "type": "slider",
        "default": 900,
        "range": [
          400,
          2500
        ],
        "unit": "ms"
      },
      {
        "id": "a11yBackButton",
        "label": "latched buttons — tap ‹ back and ◉ activate",
        "type": "switch",
        "default": false
      },
      {
        "id": "a11yHitboxScale",
        "label": "touch target size",
        "type": "slider",
        "default": 1,
        "range": [
          1,
          2.5
        ],
        "unit": "×"
      },
      {
        "id": "a11yMagnifier",
        "label": "magnifier",
        "type": "switch",
        "default": false
      },
      {
        "id": "a11ySpokenLabels",
        "label": "spoken labels",
        "type": "switch",
        "default": false
      },
      {
        "id": "a11yHighContrast",
        "label": "high contrast",
        "type": "switch",
        "default": false,
        "overrides": "accent colour"
      },
      {
        "id": "a11yLabelScale",
        "label": "star label text size",
        "type": "slider",
        "default": 100,
        "range": [
          70,
          250
        ],
        "unit": "%"
      },
      {
        "id": "a11yClockScale",
        "label": "clock & overlay text size",
        "type": "slider",
        "default": 100,
        "range": [
          60,
          200
        ],
        "unit": "%"
      },
      {
        "id": "a11yRemoveGlows",
        "label": "remove glows",
        "type": "switch",
        "default": false,
        "overrides": "trail glow · star & orbit glow"
      },
      {
        "id": "a11yReduceMotion",
        "label": "reduce motion",
        "type": "switch",
        "default": false,
        "overrides": "birth sparks · light trails"
      }
    ],
    "starChart": [
      {
        "id": "export",
        "label": "export ✦",
        "type": "action",
        "note": "writes zenith-star-chart.json wherever you choose"
      },
      {
        "id": "import",
        "label": "import…",
        "type": "action"
      },
      {
        "id": "hiddenPkgs",
        "label": "hidden from deep sky",
        "type": "list",
        "note": "each row has an unhide button; the section only shows when something is hidden"
      },
      {
        "id": "resetTree",
        "label": "erase all rings…",
        "type": "action",
        "note": "two-tap confirmation; empties every region in the current sky"
      }
    ]
  },
  "regions": {
    "description": "The screen can be split into up to 9 areas, each remembering its own root ring. Where the hold starts decides which constellation appears.",
    "grids": {
      "1": "1 × 1",
      "2": "1 col × 2 rows",
      "3": "1 × 3",
      "4": "2 × 2",
      "5": "2 cols × 3 rows (last two cells merge)",
      "6": "2 × 3",
      "7": "2 cols × 4 rows (last two cells merge)",
      "8": "2 × 4",
      "9": "3 × 3"
    },
    "numbering": "left to right, then top to bottom, starting at 1",
    "editor": "settings › regions & star index › ✦ edit region layout — a count slider plus full-length draggable dividers; each line stops 8% short of its neighbour",
    "freeMax": 2
  },
  "skies": {
    "description": "A sky is a complete separate setup. Switch from the top of the settings main page.",
    "freeMax": 1,
    "perSky": [
      "the constellation tree",
      "icon/list mode",
      "region count and dividers",
      "index region",
      "background colour, image, dimming, my sky",
      "theme and accent",
      "ring radius and star size",
      "labels, sparks, trails, glow, twinkle",
      "overlay contents and position",
      "talisman ink and cast glow",
      "star style, usage-as-light, battery, next event"
    ],
    "shared": [
      "corner, edge, flick and double-tap actions",
      "apps bound to gesture positions",
      "hold delay and accessibility timings",
      "haptics",
      "hidden apps",
      "default icon pack",
      "status bar, orientation",
      "sound",
      "all accessibility options",
      "the talismans themselves",
      "comets, the veil, onboarding and hints"
    ]
  },
  "talismans": {
    "inscribe": [
      "settings › talismans › ✎ inscribe new talisman",
      "draw the shape once",
      "draw it again (the first shows faintly as a guide)",
      "name it and bind it: apps · actions · rings"
    ],
    "cast": "draw the shape fast on empty sky, before the hold delay elapses; the trail turns talisman-ink while fast enough",
    "matchThreshold": 0.8,
    "veilThreshold": 0.78,
    "rotationTolerance": "roughly ±28°",
    "priority": "list order — the higher talisman wins ties; only a clearly better score takes a cast from a higher-priority glyph",
    "targets": [
      "an app",
      "an app shortcut",
      "any built-in action",
      "any ring in the sky, including one placed nowhere (casting opens it in place, driven by taps)"
    ],
    "menu": [
      "▶ playback",
      "⋮ re-inscribe",
      "⋮ move up (higher priority)",
      "⋮ move down",
      "⋮ delete"
    ],
    "freeMax": 3
  },
  "comets": {
    "requires": "notification access for the 'Zenith comets' service",
    "toggle": "settings › system › notifications drift by as comets",
    "catch": "hold on the comet's head (within 34 dp); after the hold delay the flight freezes and a menu opens beside it",
    "menu": [
      "open",
      "dismiss",
      "snooze 30 min"
    ],
    "cancel": "lift off the menu; the comet resumes exactly where it paused",
    "skipped": [
      "ongoing notifications",
      "Zenith's own",
      "notifications with neither title nor text"
    ],
    "privacy": "titles are drawn on screen and forgotten — never stored, never transmitted"
  },
  "veil": {
    "what": "a curtain over the launcher, not device security — keep the system lock",
    "enable": "settings › system › veil when the screen sleeps",
    "sealNow": "assign the 'seal the sky' action to any gesture position",
    "unseal": [
      {
        "method": "draw the unseal sigil",
        "available": "only if at least one talisman is inscribed",
        "threshold": 0.78
      },
      {
        "method": "rest one still finger for 4 seconds",
        "available": "always — the guaranteed way in",
        "feedback": "a ring fills around the finger; it opens the instant it completes"
      }
    ],
    "refusal": "a refused sigil always says 'the sky does not know that sign', even with hints off",
    "shows": "the clock, a hint line, and (with my sky on) the real night sky",
    "back": "the back gesture cannot lift the veil"
  },
  "gold": {
    "name": "Zenith Gold",
    "price": "4.99",
    "currency": "USD",
    "billing": "one-time purchase, not a subscription",
    "model": "every feature is usable for free; gold caps quantity and depth rather than walling features away",
    "free": [
      "the full gesture launcher",
      "deep sky",
      "star index",
      "widgets",
      "shortcuts",
      "direct",
      "star-chart backups and sharing",
      "comets",
      "every accessibility feature",
      "icon packs including Zenith's own",
      "themes clean · mono · pastel",
      "spark tiers twinkle · gentle · lively",
      "2 regions",
      "3 talismans",
      "1 sky"
    ],
    "gold": [
      "unlimited regions, talismans and skies",
      "every theme (rainbow · daytime · mono inverted · iridescent · neon)",
      "my sky",
      "your own cropped images as star icons",
      "twinkle",
      "the sparkler spark tier",
      "the sky's voice (sound)"
    ],
    "purchase": "a single $4.99 payment unlocks it permanently; b0.8 ships a free demo switch in settings › system, replaced by Play Billing at v1.0"
  },
  "permissions": [
    {
      "id": "ACCESS_COARSE_LOCATION",
      "usedFor": "weather and placing the real night sky",
      "data": "rounded to ~1 km before use; never stored; sent only to Open-Meteo",
      "optional": true
    },
    {
      "id": "notification access",
      "usedFor": "comets",
      "data": "titles drawn on screen and forgotten; never stored, never transmitted",
      "optional": true
    },
    {
      "id": "accessibility (Zenith actions)",
      "usedFor": "lock, shade, recents, quick tiles, screenshot, power, back, home, and screen-reader/haptic navigation",
      "data": "reads nothing from the screen; only performs assigned actions",
      "optional": true
    },
    {
      "id": "READ_CALENDAR",
      "usedFor": "the next-event overlay",
      "data": "read and shown on-device, never sent",
      "optional": true
    },
    {
      "id": "VIBRATE",
      "usedFor": "haptic feedback",
      "optional": true
    },
    {
      "id": "INTERNET",
      "usedFor": "the single weather request",
      "data": "no request is ever made unless weather or my sky is on",
      "optional": true
    }
  ],
  "backup": {
    "file": "zenith-star-chart.json",
    "travels": [
      "every region's constellation tree",
      "all settings",
      "talismans with their shapes",
      "custom star icons, embedded and rebuilt on the new device"
    ],
    "doesNotTravel": [
      "widgets (Android widget IDs are device-local — the star imports but must be re-bound)",
      "the wallpaper image (content URIs do not survive a device change)",
      "the Gold entitlement"
    ],
    "note": "written only when you export it, to a place you choose; never uploaded"
  },
  "troubleshooting": [
    {
      "symptom": "nothing happens when I hold the screen",
      "causes": [
        "holding inside a corner (52 dp) or edge band (18 dp)",
        "the finger is moving, making it a flick or talisman",
        "a long hold delay",
        "that region is set to open the Star Index"
      ]
    },
    {
      "symptom": "the ring opens but is empty",
      "fix": "that region has no stars yet — slide to ✛ and add one; remember each region keeps its own ring"
    },
    {
      "symptom": "folders open while I browse",
      "fix": "keep moving; folders open on a dwell. Raise 'folder ring blooms after' in accessibility › extended"
    },
    {
      "symptom": "I can't get back to the previous ring",
      "fix": "trace into the chevron at the previous ring's centre; or lift on empty sky and start again"
    },
    {
      "symptom": "I hid the gear and can't find settings",
      "fix": "hold the lower-left corner; or open Deep Sky and tap '✦ zenith settings', always the first row"
    },
    {
      "symptom": "app shortcuts don't work",
      "fix": "set Zenith as the default launcher — Android only gives shortcuts to the active home app"
    },
    {
      "symptom": "lock / shade / recents / screenshot do nothing",
      "fix": "enable Zenith actions in settings › system; lock and screenshot also need Android 9+"
    },
    {
      "symptom": "no comets appear",
      "fix": "grant notification access; only new, non-ongoing notifications become comets"
    },
    {
      "symptom": "my talisman won't cast",
      "fix": "draw faster and bigger; check the master switch; a lookalike higher in the list may be winning"
    },
    {
      "symptom": "I'm locked behind the veil",
      "fix": "press one finger and hold perfectly still for four seconds"
    },
    {
      "symptom": "a star is off the screen edge",
      "fix": "open ✛ › Edit, find the star and use ◎ re-place"
    },
    {
      "symptom": "an icon didn't change",
      "fix": "a higher precedence layer is winning; reset the star's own icon to let the layer below show"
    },
    {
      "symptom": "widget says 'widget unavailable'",
      "fix": "its binding is gone — remove the star and add the widget again"
    },
    {
      "symptom": "left/right flicks never fire",
      "fix": "Android's back gesture owns the edges; use a corner, an up/down flick, or the drawn circle"
    }
  ]
}