From 043364e43ef8e87a79929c99f438fe2bba2fcd78 Mon Sep 17 00:00:00 2001
From: Gabe Kangas <gabek@real-ity.com>
Date: Sat, 1 Aug 2026 12:44:28 -0700
Subject: [PATCH 1/2] feat: key manifest pages and tabs

---
 docs/PLUGIN_AUTHOR_GUIDE.md                   | 40 ++++++++--------
 docs/WIRE_PROTOCOL.md                         | 46 +++++++++++++------
 examples/js/README.md                         |  2 +-
 .../js/action-buttons/plugin.manifest.json    |  7 ++-
 examples/js/admin-demo/plugin.manifest.json   | 12 ++---
 examples/js/file-manager/plugin.manifest.json |  7 ++-
 examples/js/manual-video-settings/README.md   |  2 +-
 .../plugin.manifest.json                      |  7 ++-
 examples/js/page-content-demo/INSTRUCTIONS.md |  6 +--
 examples/js/page-content-demo/README.md       |  6 +--
 .../js/page-content-demo/plugin.manifest.json |  9 ++--
 examples/js/rules-tab/plugin.manifest.json    | 16 +++----
 examples/js/tabs-demo/INSTRUCTIONS.md         | 12 ++---
 examples/js/tabs-demo/README.md               | 10 ++--
 examples/js/tabs-demo/plugin.manifest.json    | 10 ++--
 examples/js/theme-hub/plugin.manifest.json    |  7 ++-
 examples/python/README.md                     |  2 +-
 .../action-buttons/plugin.manifest.json       |  7 ++-
 .../python/admin-demo/plugin.manifest.json    | 12 ++---
 .../python/file-manager/plugin.manifest.json  |  7 ++-
 .../python/manual-video-settings/README.md    |  2 +-
 .../plugin.manifest.json                      |  7 ++-
 .../python/page-content-demo/INSTRUCTIONS.md  |  6 +--
 examples/python/page-content-demo/README.md   |  6 +--
 .../page-content-demo/plugin.manifest.json    |  9 ++--
 examples/python/tabs-demo/INSTRUCTIONS.md     | 12 ++---
 examples/python/tabs-demo/README.md           | 10 ++--
 .../python/tabs-demo/plugin.manifest.json     | 10 ++--
 .../python/theme-hub/plugin.manifest.json     |  7 ++-
 rules-tab/plugin.manifest.json                | 16 +++----
 .../skills/create-owncast-plugin-js/SKILL.md  |  3 +-
 .../skills/create-owncast-plugin-py/SKILL.md  |  3 +-
 32 files changed, 159 insertions(+), 159 deletions(-)

diff --git a/docs/PLUGIN_AUTHOR_GUIDE.md b/docs/PLUGIN_AUTHOR_GUIDE.md
index a29166f..5e08f14 100644
--- a/docs/PLUGIN_AUTHOR_GUIDE.md
+++ b/docs/PLUGIN_AUTHOR_GUIDE.md
@@ -654,7 +654,7 @@ Sends are fire-and-forget: the call returns immediately and never blocks, even i
 Notes:
 
 - Up to 64 simultaneous connections per plugin. Over that the endpoint returns 503. `EventSource` reconnects automatically.
-- If the channel matches one of your `admin.pages[]` globs it's auth-gated like any admin route, handy for an admin-only stats stream.
+- If the channel matches one of your `admin.pages` path globs, it is auth-gated like any admin route. This is useful for an admin-only stats stream.
 - The endpoint is host-owned and reserved: your `onHttpRequest` never sees `/_sse/...` requests, and you can't serve your own route there.
 
 ### Knowing who is connected
@@ -738,32 +738,33 @@ Prefer it over building a bespoke settings page and KV plumbing.
 
 ## Admin pages
 
-Plugins can register pages that appear in the Owncast admin UI for configuration. Declare them in the manifest:
+Plugins can register pages that appear in the Owncast admin UI for configuration. Each `pages` object key is a plugin-relative path glob:
 
 ```json
 {
   "permissions": ["http.serve"],
   "admin": {
-    "pages": [
-      { "title": "Settings", "path": "/admin", "icon": "gear" },
-      { "title": "Settings", "path": "/admin/*" }
-    ]
+    "pages": {
+      "/admin": { "title": "Settings", "icon": "gear" },
+      "/admin/*": { "title": "Settings" }
+    }
   }
 }
 ```
 
-- `path` is a glob (e.g. `"/admin"`, `"/admin/*"`). Requests under `/plugins/<your-slug>/<path>` that match any declared glob are **auth-gated by the host**, unauthenticated requests get `401` before your plugin code ever runs.
+- Each key is a path glob such as `"/admin"` or `"/admin/*"`. Requests under `/plugins/<your-slug>/<path>` that match any declared glob are **auth-gated by the host**. Unauthenticated requests get `401` before your plugin code runs.
 - Owncast's admin renders each declared page as a tab inside `/admin/plugins/configure?id=<your-slug>`, embedded as an iframe pointed at `/plugins/<your-slug>/<path>`. Each plugin gets its own bookmarkable URL plus a sidebar entry under **Plugins** in the admin nav.
 - Both static assets and dynamic endpoints under matched paths are auth-gated. You don't have to check `req.authenticated` yourself.
-- The host auto-injects an admin-themed stylesheet (`/styles/admin/plugin-iframe.css`) into HTML responses on admin paths so plain `<input>`/`<button>` controls match Owncast's look without you needing to ship CSS. Plugins that prefer their own styling can layer on top.
+- The host auto-injects an admin-themed stylesheet (`/styles/admin/plugin-iframe.css`) into HTML responses on admin paths so plain `<input>` and `<button>` controls match Owncast's look without you needing to ship CSS. Plugins that prefer their own styling can layer on top.
 - The iframe is sandboxed but permits what an admin page normally needs: your scripts, form submits, same-origin `fetch` to your own endpoints, popups, **file downloads** (a blob/data-URL `<a download>` clicked from script), and **`confirm()`/`alert()`/`prompt()`** dialogs. If a browser feature seems silently blocked, suspect the iframe sandbox first.
+- JSON object order is not significant. Owncast displays pages in lexicographic path order.
 
 Author flow:
 
-1. Put admin HTML/CSS/JS in `public/admin/index.html` (and friends)
-2. Expose admin APIs via `onHttpRequest` at `/admin/api/...`
-3. Declare both globs (or just `"/admin/*"`) in `manifest.admin.pages[].path`
-4. Visit `/admin/plugins/configure?id=<your-slug>` in the admin UI (or `/plugins/<your-slug>/admin/` directly). Owncast uses your existing admin login to gate the page. No extra prompt.
+1. Put admin HTML, CSS, and JavaScript in `public/admin/index.html` and related files.
+2. Expose admin APIs via `onHttpRequest` at `/admin/api/...`.
+3. Declare both path keys, or just `"/admin/*"`, in `manifest.admin.pages`.
+4. Visit `/admin/plugins/configure?id=<your-slug>` in the admin UI or `/plugins/<your-slug>/admin/` directly. Owncast uses your existing admin login to gate the page. No extra prompt.
 
 ## Viewer authentication gates
 
@@ -999,21 +1000,22 @@ The admin's extra page content goes through the markdown processor, but plugin H
 
 ## Viewer-page tabs
 
-Plugins can add tabs to the viewer page's tab row (alongside the built-in **About** and **Followers** tabs) with `manifest.tabs[]`. Each entry requires a `title` and a `slug`, and `content` is optional:
+Plugins can add tabs to the viewer page's tab row alongside the built-in **About** and **Followers** tabs with `manifest.tabs`. Each object key is the tab slug. Every value requires a `title`, and `content` is optional:
 
 ```json
 {
   "permissions": ["ui.modify"],
-  "tabs": [
-    { "title": "Music",       "slug": "music",       "content": "music.html" },
-    { "title": "Stream Info", "slug": "stream-info" }
-  ]
+  "tabs": {
+    "music": { "title": "Music", "content": "music.html" },
+    "stream-info": { "title": "Stream Info" }
+  }
 }
 ```
 
-- `slug`: required. Stable identifier, unique within the plugin's tabs. Passed to `onTabContent` so the handler knows which tab to render. Lowercase letters, digits, hyphens.
-- `title`: required. The label shown on the tab. Keep it short (~16 characters max for mobile).
+- Each key is the tab's required stable slug. It must be unique within the plugin and use lowercase letters, digits, and hyphens. Owncast passes it to `onTabContent` so the handler knows which tab to render.
+- `title`: required. The label shown on the tab. Keep it short, around 16 characters maximum for mobile.
 - `content`: optional. Relative path to a static HTML file in `assets/`. When omitted, the host calls `onTabContent`.
+- JSON object order is not significant. Owncast displays tabs in lexicographic slug order.
 
 **Static** (`content` present): the host reads the file from `assets/` and inlines it as the tab body. Path rules match `extraPageContent.content`.
 
diff --git a/docs/WIRE_PROTOCOL.md b/docs/WIRE_PROTOCOL.md
index fe28e8c..e128ec1 100644
--- a/docs/WIRE_PROTOCOL.md
+++ b/docs/WIRE_PROTOCOL.md
@@ -269,7 +269,7 @@ the gate re-validate a session on each `/` page load and return
 ### `ui.modify`
 
 - Not a custom host function. Gates UI surfaces that place plugin-contributed elements inside Owncast's own chrome.
-- Required when the manifest declares `actions[]`, `styles[]`, `scripts[]`, `extraPageContent`, or `tabs[]`, and required at runtime by `owncast_add_actions` / `owncast_clear_actions`. Manifests that declare any of those fields without `ui.modify` are rejected at load. Runtime calls return a permission error.
+- Required when the manifest declares `actions[]`, `styles[]`, `scripts[]`, `extraPageContent`, or `tabs`, and required at runtime by `owncast_add_actions` / `owncast_clear_actions`. Manifests that declare any of those fields without `ui.modify` are rejected at load. Runtime calls return a permission error.
 - `owncast_add_actions(jsonPtr: PTR): u64`, append one or more `ActionButton` entries on top of `manifest.actions`. Argument is a JSON array. The host validates each entry with the same rules as the manifest (title required, exactly one of `url` / `html`, relative URLs and icons auto-prefixed to the plugin's namespace, cross-plugin paths rejected) and persists the merged set to the plugin's config. Returns the host call envelope (success indicator + optional error string).
 - `owncast_clear_actions(jsonPtr: PTR): u64`, drop every runtime addition. `manifest.actions` are untouched. Argument is an empty JSON object (`"{}"`) for API symmetry. Returns the host call envelope.
 
@@ -317,7 +317,7 @@ The plugin process is **not** involved in serving the connection, no wasm call i
 Host behavior:
 
 - Requires the `http.sse` permission, 404 otherwise.
-- A channel that matches a `manifest.admin.pages[]` glob is auth-gated like any other admin path (401 if not authenticated).
+- A channel that matches a `manifest.admin.pages` path glob is auth-gated like any other admin path (401 if not authenticated).
 - Connections are capped per-plugin (default 64). Over the cap returns 503.
 - Idle streams get a `: keep-alive` comment line every 15s so proxies don't drop them.
 - Delivery is best-effort: each client has a small send buffer, and frames are dropped for a client that can't keep up rather than blocking the publishing plugin.
@@ -356,9 +356,23 @@ Runtime additions go through `owncast_add_actions` / `owncast_clear_actions` (se
 
 The host exposes the merged list as `GET /api/plugins/actions` (public). The Owncast server is responsible for folding that into its existing `/api/externalactions` response.
 
-### `manifest.admin.pages[]`
+### `manifest.admin.pages`
 
-Glob-matched routes inside `/plugins/<name>/...` that the host auth-gates before reaching the plugin's `on_http_request`. See `manifest.go:AdminPage`.
+An object of plugin-relative path glob keys to admin-page definitions. The host auth-gates matching routes inside `/plugins/<name>/...` before they reach the plugin's `on_http_request`.
+
+```json
+{
+  "/admin": {
+    "title": "Settings",
+    "icon": "gear"
+  },
+  "/admin/*": {
+    "title": "Settings"
+  }
+}
+```
+
+Each key must start with `/`. Each value requires a non-empty `title` and may include `icon`. The host processes pages in lexicographic path order because JSON object order is not significant.
 
 ### `manifest.network.allowedHosts[]`
 
@@ -411,31 +425,35 @@ Validation:
 
 Each contribution is wrapped with an `<!-- plugin: <slug> — <file> -->\n` comment for in-page attribution. The admin's content goes through the markdown processor before plugin HTML is prepended. Plugin HTML is left raw so tags and attributes pass through as written.
 
-### `manifest.tabs[]`
+### `manifest.tabs`
 
-An array of viewer-page tabs the plugin contributes alongside the built-in tabs (Followers, About).
+An object of tab slug keys to viewer-page tab definitions. The tabs appear alongside the built-in tabs (Followers, About).
 
 ```json
 {
-  "title": "string (required, tab label)",
-  "slug": "string (required, stable identifier, passed to on_tab_content)",
-  "content": "string (optional, relative path to assets/<file>.html)"
+  "music": {
+    "title": "Music",
+    "content": "music.html"
+  },
+  "stream-info": {
+    "title": "Stream Info"
+  }
 }
 ```
 
 Validation:
 
 - `ui.modify` permission required.
-- `http.serve` is **not** required: each tab's HTML is inlined into the response, not served at a URL.
-- `title` must be non-empty. Unique within the plugin's tabs.
-- `slug` must be a valid slug. Unique within the plugin's tabs. Passed to `on_tab_content` so the plugin knows which tab to render.
-- When `content` is present, the same path rules as `manifest.extraPageContent.content` apply (must end in `.html`).
+- `http.serve` is **not** required. Each tab's HTML is inlined into the response, not served at a URL.
+- Each key must be a valid slug and is passed to `on_tab_content`.
+- `title` must be non-empty and unique within the plugin's tabs.
+- When `content` is present, the same path rules as `manifest.extraPageContent.content` apply. It must end in `.html`.
 
 **Static** (`content` present): the host reads the file from `assets/` and inlines its bytes.
 
 **Dynamic** (`content` absent): the host calls `on_tab_content` with `{ slug, user? }` and inlines the returned HTML string.
 
-The host emits the tab list on `GET /api/config` under `pluginTabs[]` as `[{slug, title, html}]` entries. The viewer page maps each entry to a tab whose body renders the inlined HTML. `slug` doubles as the React key so a tab only unmounts when the source plugin is disabled/removed.
+JSON object order is not significant. The host emits tabs in lexicographic slug order on `GET /api/config` under `pluginTabs[]` as `[{slug, title, html}]` entries. The viewer page maps each entry to a tab whose body renders the inlined HTML. The emitted `slug` is `<plugin-slug>/<tab-slug>` and doubles as the React key.
 
 ## Payload types
 
diff --git a/examples/js/README.md b/examples/js/README.md
index 5a5585b..07a033a 100644
--- a/examples/js/README.md
+++ b/examples/js/README.md
@@ -32,7 +32,7 @@ One self-contained npm project per directory. Each has its own `README.md` with
 | [page-content-demo](./page-content-demo/)         | `manifest.extraPageContent`, HTML prepended to the viewer's extra-content block.                        |
 | [theme-hub](./theme-hub/)                         | Dynamic `onPageStyles` + `onPageScripts`: an admin-selectable theme catalog applied to the whole viewer UI via `customStyles`. |
 | [viewer-gate](./viewer-gate/)                     | `manifest.styles` + `manifest.scripts` together: a confirmation modal on page load.                     |
-| [tabs-demo](./tabs-demo/)                         | `manifest.tabs[]`, two tabs added to the viewer page's tab row alongside Followers and About.           |
+| [tabs-demo](./tabs-demo/)                         | `manifest.tabs`, two tabs added to the viewer page's tab row alongside Followers and About.             |
 
 ## Building and testing
 
diff --git a/examples/js/action-buttons/plugin.manifest.json b/examples/js/action-buttons/plugin.manifest.json
index 5b773cd..07eb685 100644
--- a/examples/js/action-buttons/plugin.manifest.json
+++ b/examples/js/action-buttons/plugin.manifest.json
@@ -11,13 +11,12 @@
     "storage.kv"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Button labels",
-        "path": "/admin",
         "icon": "gear"
       }
-    ]
+    }
   },
   "actions": [
     {
diff --git a/examples/js/admin-demo/plugin.manifest.json b/examples/js/admin-demo/plugin.manifest.json
index 1e806ed..395d58e 100644
--- a/examples/js/admin-demo/plugin.manifest.json
+++ b/examples/js/admin-demo/plugin.manifest.json
@@ -10,16 +10,14 @@
     "storage.kv"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Example Page 1",
-        "path": "/admin",
         "icon": "gear"
       },
-      {
-        "title": "Example Page 2",
-        "path": "/admin/anotherpage.html"
+      "/admin/anotherpage.html": {
+        "title": "Example Page 2"
       }
-    ]
+    }
   }
 }
diff --git a/examples/js/file-manager/plugin.manifest.json b/examples/js/file-manager/plugin.manifest.json
index ae256e8..a452e04 100644
--- a/examples/js/file-manager/plugin.manifest.json
+++ b/examples/js/file-manager/plugin.manifest.json
@@ -10,12 +10,11 @@
     "storage.fs"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Files",
-        "path": "/admin",
         "icon": "folder"
       }
-    ]
+    }
   }
 }
diff --git a/examples/js/manual-video-settings/README.md b/examples/js/manual-video-settings/README.md
index 98970f4..9f65a8e 100644
--- a/examples/js/manual-video-settings/README.md
+++ b/examples/js/manual-video-settings/README.md
@@ -7,7 +7,7 @@ Admin-only form at `/plugins/manual-video-settings/admin/` for hand-editing the
 ```json
 {
   "permissions": ["http.serve", "videoconfig.read", "videoconfig.write"],
-  "admin": { "pages": [{ "title": "Manual Video Settings", "path": "/admin" }] }
+  "admin": { "pages": { "/admin": { "title": "Manual Video Settings" } } }
 }
 ```
 
diff --git a/examples/js/manual-video-settings/plugin.manifest.json b/examples/js/manual-video-settings/plugin.manifest.json
index 6a6d1b1..541ab8b 100644
--- a/examples/js/manual-video-settings/plugin.manifest.json
+++ b/examples/js/manual-video-settings/plugin.manifest.json
@@ -11,12 +11,11 @@
     "videoconfig.write"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Manual Video Settings",
-        "path": "/admin",
         "icon": "gear"
       }
-    ]
+    }
   }
 }
diff --git a/examples/js/page-content-demo/INSTRUCTIONS.md b/examples/js/page-content-demo/INSTRUCTIONS.md
index fe4203b..c0fcb15 100644
--- a/examples/js/page-content-demo/INSTRUCTIONS.md
+++ b/examples/js/page-content-demo/INSTRUCTIONS.md
@@ -16,9 +16,9 @@ The manifest declares the two slots without `content` paths, which tells the hos
 {
   "permissions": ["ui.modify", "server.read"],
   "extraPageContent": { "slug": "banner" },
-  "tabs": [
-    { "title": "Stream Info", "slug": "stream-info" }
-  ]
+  "tabs": {
+    "stream-info": { "title": "Stream Info" }
+  }
 }
 ```
 
diff --git a/examples/js/page-content-demo/README.md b/examples/js/page-content-demo/README.md
index bf8941b..5e4973d 100644
--- a/examples/js/page-content-demo/README.md
+++ b/examples/js/page-content-demo/README.md
@@ -6,9 +6,9 @@ Demonstrates dynamic `extraPageContent` and viewer tabs using `onPageContent` an
 {
   "permissions": ["ui.modify", "server.read"],
   "extraPageContent": { "slug": "banner" },
-  "tabs": [
-    { "title": "Stream Info", "slug": "stream-info" }
-  ]
+  "tabs": {
+    "stream-info": { "title": "Stream Info" }
+  }
 }
 ```
 
diff --git a/examples/js/page-content-demo/plugin.manifest.json b/examples/js/page-content-demo/plugin.manifest.json
index 8305db1..ac79242 100644
--- a/examples/js/page-content-demo/plugin.manifest.json
+++ b/examples/js/page-content-demo/plugin.manifest.json
@@ -12,10 +12,9 @@
   "extraPageContent": {
     "slug": "banner"
   },
-  "tabs": [
-    {
-      "title": "Stream Info",
-      "slug": "stream-info"
+  "tabs": {
+    "stream-info": {
+      "title": "Stream Info"
     }
-  ]
+  }
 }
diff --git a/examples/js/rules-tab/plugin.manifest.json b/examples/js/rules-tab/plugin.manifest.json
index fc1ae7e..8f11e6c 100644
--- a/examples/js/rules-tab/plugin.manifest.json
+++ b/examples/js/rules-tab/plugin.manifest.json
@@ -11,19 +11,17 @@
     "storage.kv",
     "chat.send"
   ],
-  "tabs": [
-    {
-      "title": "Rules",
-      "slug": "rules"
+  "tabs": {
+    "rules": {
+      "title": "Rules"
     }
-  ],
+  },
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin/*": {
         "title": "Rules",
-        "path": "/admin/*",
         "icon": "book"
       }
-    ]
+    }
   }
 }
diff --git a/examples/js/tabs-demo/INSTRUCTIONS.md b/examples/js/tabs-demo/INSTRUCTIONS.md
index 9777342..0997b42 100644
--- a/examples/js/tabs-demo/INSTRUCTIONS.md
+++ b/examples/js/tabs-demo/INSTRUCTIONS.md
@@ -13,19 +13,19 @@ The tab content is plain HTML the plugin ships, so editing `assets/music.html` o
 
 ## How it works
 
-The manifest declares two tabs. Each has a `slug` (the stable identifier Owncast uses internally and passes to handlers), a `title` (the tab label), and a `content` path pointing at a static HTML file:
+The manifest declares two tabs. Each object key is the stable slug Owncast uses internally and passes to handlers. Each value contains a `title` and a `content` path pointing at a static HTML file:
 
 ```json
 {
   "permissions": ["ui.modify"],
-  "tabs": [
-    { "title": "Music",    "slug": "music",    "content": "music.html" },
-    { "title": "Schedule", "slug": "schedule", "content": "schedule.html" }
-  ]
+  "tabs": {
+    "music": { "title": "Music", "content": "music.html" },
+    "schedule": { "title": "Schedule", "content": "schedule.html" }
+  }
 }
 ```
 
-The host reads each file at `/api/config` time, inlines the bytes into a `pluginTabs[]` array on the response, and the viewer page maps each entry to a tab next to the built-ins. Tab keys are derived from the tab `slug` so a tab only unmounts when the plugin is disabled or removed.
+The host reads each file at `/api/config` time, inlines the bytes into a `pluginTabs[]` array on the response, and maps each entry to a tab next to the built-ins. The emitted tab key combines the plugin slug and manifest object key, so a tab only unmounts when the plugin is disabled or removed.
 
 ## Permissions
 
diff --git a/examples/js/tabs-demo/README.md b/examples/js/tabs-demo/README.md
index d76f0d7..a909f96 100644
--- a/examples/js/tabs-demo/README.md
+++ b/examples/js/tabs-demo/README.md
@@ -5,14 +5,14 @@ Example plugin for `manifest.tabs`: contributes two static viewer-page tabs (Mus
 ```json
 {
   "permissions": ["ui.modify"],
-  "tabs": [
-    { "title": "Music",    "slug": "music",    "content": "music.html" },
-    { "title": "Schedule", "slug": "schedule", "content": "schedule.html" }
-  ]
+  "tabs": {
+    "music": { "title": "Music", "content": "music.html" },
+    "schedule": { "title": "Schedule", "content": "schedule.html" }
+  }
 }
 ```
 
-Each tab has a `slug` (stable identifier), a `title` (tab label), and a `content` path pointing at a static HTML file in `assets/`. When `content` is present the host reads the file and inlines it directly, and no plugin code runs. When `content` is omitted the host calls `onTabContent({ slug, user? })` so the plugin can render dynamic content per viewer.
+Each tab's object key is its stable slug. The value contains the tab label in `title` and an optional `content` path pointing at a static HTML file in `assets/`. When `content` is present the host reads the file and inlines it directly, and no plugin code runs. When `content` is omitted the host calls `onTabContent({ slug, user? })` so the plugin can render dynamic content per viewer.
 
 Requires `ui.modify` (the plugin paints inside Owncast's chrome). `http.serve` is not required: each tab's HTML is read from `assets/` and inlined into the tab body on `/api/config`, not served at a URL.
 
diff --git a/examples/js/tabs-demo/plugin.manifest.json b/examples/js/tabs-demo/plugin.manifest.json
index 9da164f..52e75d4 100644
--- a/examples/js/tabs-demo/plugin.manifest.json
+++ b/examples/js/tabs-demo/plugin.manifest.json
@@ -8,16 +8,14 @@
   "permissions": [
     "ui.modify"
   ],
-  "tabs": [
-    {
+  "tabs": {
+    "music": {
       "title": "Music",
-      "slug": "music",
       "content": "music.html"
     },
-    {
+    "schedule": {
       "title": "Schedule",
-      "slug": "schedule",
       "content": "schedule.html"
     }
-  ]
+  }
 }
diff --git a/examples/js/theme-hub/plugin.manifest.json b/examples/js/theme-hub/plugin.manifest.json
index 9c33e8f..df23e06 100644
--- a/examples/js/theme-hub/plugin.manifest.json
+++ b/examples/js/theme-hub/plugin.manifest.json
@@ -11,12 +11,11 @@
     "storage.kv"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Themes",
-        "path": "/admin",
         "icon": "gear"
       }
-    ]
+    }
   }
 }
diff --git a/examples/python/README.md b/examples/python/README.md
index f33c382..77b6f3f 100644
--- a/examples/python/README.md
+++ b/examples/python/README.md
@@ -32,7 +32,7 @@ One self-contained plugin per directory, authored in Python and compiled to wasm
 | [page-content-demo](./page-content-demo/)         | `manifest.extraPageContent` + tabs rendered server-side from Mustache templates.                        |
 | [theme-hub](./theme-hub/)                         | Dynamic `@plugin.on_page_styles` + `@plugin.on_page_scripts`: an admin-selectable theme catalog applied to the whole viewer UI via `customStyles`. |
 | [viewer-gate](./viewer-gate/)                     | `manifest.styles` + `manifest.scripts` together: a confirmation modal on page load.                     |
-| [tabs-demo](./tabs-demo/)                         | `manifest.tabs[]`, two tabs added to the viewer page's tab row alongside Followers and About.           |
+| [tabs-demo](./tabs-demo/)                         | `manifest.tabs`, two tabs added to the viewer page's tab row alongside Followers and About.             |
 | [timer-bot](./timer-bot/)                         | `owncast.timer` (set_timeout/set_interval/clear) and the once-a-second `on_tick` event.                 |
 | [whoami](./whoami/)                               | Reads the logged-in chat user the host passes to a plugin HTTP handler as `req.user`.                   |
 
diff --git a/examples/python/action-buttons/plugin.manifest.json b/examples/python/action-buttons/plugin.manifest.json
index f8fa578..9238a43 100644
--- a/examples/python/action-buttons/plugin.manifest.json
+++ b/examples/python/action-buttons/plugin.manifest.json
@@ -11,13 +11,12 @@
     "storage.kv"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Button labels",
-        "path": "/admin",
         "icon": "gear"
       }
-    ]
+    }
   },
   "actions": [
     {
diff --git a/examples/python/admin-demo/plugin.manifest.json b/examples/python/admin-demo/plugin.manifest.json
index b7e8822..747574a 100644
--- a/examples/python/admin-demo/plugin.manifest.json
+++ b/examples/python/admin-demo/plugin.manifest.json
@@ -10,16 +10,14 @@
     "storage.kv"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Example Page 1",
-        "path": "/admin",
         "icon": "gear"
       },
-      {
-        "title": "Example Page 2",
-        "path": "/admin/anotherpage.html"
+      "/admin/anotherpage.html": {
+        "title": "Example Page 2"
       }
-    ]
+    }
   }
 }
diff --git a/examples/python/file-manager/plugin.manifest.json b/examples/python/file-manager/plugin.manifest.json
index 50b39e1..41d4193 100644
--- a/examples/python/file-manager/plugin.manifest.json
+++ b/examples/python/file-manager/plugin.manifest.json
@@ -10,12 +10,11 @@
     "storage.fs"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Files",
-        "path": "/admin",
         "icon": "folder"
       }
-    ]
+    }
   }
 }
diff --git a/examples/python/manual-video-settings/README.md b/examples/python/manual-video-settings/README.md
index c18d0b0..11c345d 100644
--- a/examples/python/manual-video-settings/README.md
+++ b/examples/python/manual-video-settings/README.md
@@ -7,7 +7,7 @@ Admin-only form at `/plugins/manual-video-settings/admin/` for hand-editing the
 ```json
 {
   "permissions": ["http.serve", "videoconfig.read", "videoconfig.write"],
-  "admin": { "pages": [{ "title": "Manual Video Settings", "path": "/admin" }] }
+  "admin": { "pages": { "/admin": { "title": "Manual Video Settings" } } }
 }
 ```
 
diff --git a/examples/python/manual-video-settings/plugin.manifest.json b/examples/python/manual-video-settings/plugin.manifest.json
index 20a9032..12576ea 100644
--- a/examples/python/manual-video-settings/plugin.manifest.json
+++ b/examples/python/manual-video-settings/plugin.manifest.json
@@ -11,12 +11,11 @@
     "videoconfig.write"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Manual Video Settings",
-        "path": "/admin",
         "icon": "gear"
       }
-    ]
+    }
   }
 }
diff --git a/examples/python/page-content-demo/INSTRUCTIONS.md b/examples/python/page-content-demo/INSTRUCTIONS.md
index fe4203b..c0fcb15 100644
--- a/examples/python/page-content-demo/INSTRUCTIONS.md
+++ b/examples/python/page-content-demo/INSTRUCTIONS.md
@@ -16,9 +16,9 @@ The manifest declares the two slots without `content` paths, which tells the hos
 {
   "permissions": ["ui.modify", "server.read"],
   "extraPageContent": { "slug": "banner" },
-  "tabs": [
-    { "title": "Stream Info", "slug": "stream-info" }
-  ]
+  "tabs": {
+    "stream-info": { "title": "Stream Info" }
+  }
 }
 ```
 
diff --git a/examples/python/page-content-demo/README.md b/examples/python/page-content-demo/README.md
index 10330bf..738f90b 100644
--- a/examples/python/page-content-demo/README.md
+++ b/examples/python/page-content-demo/README.md
@@ -6,9 +6,9 @@ Demonstrates dynamic `extraPageContent` and viewer tabs using `on_page_content`
 {
   "permissions": ["ui.modify", "server.read"],
   "extraPageContent": { "slug": "banner" },
-  "tabs": [
-    { "title": "Stream Info", "slug": "stream-info" }
-  ]
+  "tabs": {
+    "stream-info": { "title": "Stream Info" }
+  }
 }
 ```
 
diff --git a/examples/python/page-content-demo/plugin.manifest.json b/examples/python/page-content-demo/plugin.manifest.json
index f65f087..c9c1563 100644
--- a/examples/python/page-content-demo/plugin.manifest.json
+++ b/examples/python/page-content-demo/plugin.manifest.json
@@ -12,10 +12,9 @@
   "extraPageContent": {
     "slug": "banner"
   },
-  "tabs": [
-    {
-      "title": "Stream Info",
-      "slug": "stream-info"
+  "tabs": {
+    "stream-info": {
+      "title": "Stream Info"
     }
-  ]
+  }
 }
diff --git a/examples/python/tabs-demo/INSTRUCTIONS.md b/examples/python/tabs-demo/INSTRUCTIONS.md
index 9777342..0997b42 100644
--- a/examples/python/tabs-demo/INSTRUCTIONS.md
+++ b/examples/python/tabs-demo/INSTRUCTIONS.md
@@ -13,19 +13,19 @@ The tab content is plain HTML the plugin ships, so editing `assets/music.html` o
 
 ## How it works
 
-The manifest declares two tabs. Each has a `slug` (the stable identifier Owncast uses internally and passes to handlers), a `title` (the tab label), and a `content` path pointing at a static HTML file:
+The manifest declares two tabs. Each object key is the stable slug Owncast uses internally and passes to handlers. Each value contains a `title` and a `content` path pointing at a static HTML file:
 
 ```json
 {
   "permissions": ["ui.modify"],
-  "tabs": [
-    { "title": "Music",    "slug": "music",    "content": "music.html" },
-    { "title": "Schedule", "slug": "schedule", "content": "schedule.html" }
-  ]
+  "tabs": {
+    "music": { "title": "Music", "content": "music.html" },
+    "schedule": { "title": "Schedule", "content": "schedule.html" }
+  }
 }
 ```
 
-The host reads each file at `/api/config` time, inlines the bytes into a `pluginTabs[]` array on the response, and the viewer page maps each entry to a tab next to the built-ins. Tab keys are derived from the tab `slug` so a tab only unmounts when the plugin is disabled or removed.
+The host reads each file at `/api/config` time, inlines the bytes into a `pluginTabs[]` array on the response, and maps each entry to a tab next to the built-ins. The emitted tab key combines the plugin slug and manifest object key, so a tab only unmounts when the plugin is disabled or removed.
 
 ## Permissions
 
diff --git a/examples/python/tabs-demo/README.md b/examples/python/tabs-demo/README.md
index d0cd3c8..b85145a 100644
--- a/examples/python/tabs-demo/README.md
+++ b/examples/python/tabs-demo/README.md
@@ -5,14 +5,14 @@ Example plugin for `manifest.tabs`: contributes two static viewer-page tabs (Mus
 ```json
 {
   "permissions": ["ui.modify"],
-  "tabs": [
-    { "title": "Music",    "slug": "music",    "content": "music.html" },
-    { "title": "Schedule", "slug": "schedule", "content": "schedule.html" }
-  ]
+  "tabs": {
+    "music": { "title": "Music", "content": "music.html" },
+    "schedule": { "title": "Schedule", "content": "schedule.html" }
+  }
 }
 ```
 
-Each tab has a `slug` (stable identifier), a `title` (tab label), and a `content` path pointing at a static HTML file in `assets/`. When `content` is present the host reads the file and inlines it directly, and no plugin code runs. When `content` is omitted the host calls `on_tab_content({ slug, user? })` so the plugin can render dynamic content per viewer.
+Each tab's object key is its stable slug. The value contains the tab label in `title` and an optional `content` path pointing at a static HTML file in `assets/`. When `content` is present the host reads the file and inlines it directly, and no plugin code runs. When `content` is omitted the host calls `on_tab_content({ slug, user? })` so the plugin can render dynamic content per viewer.
 
 Requires `ui.modify` (the plugin paints inside Owncast's chrome). `http.serve` is not required: each tab's HTML is read from `assets/` and inlined into the tab body on `/api/config`, not served at a URL.
 
diff --git a/examples/python/tabs-demo/plugin.manifest.json b/examples/python/tabs-demo/plugin.manifest.json
index e8a55cc..9213f3e 100644
--- a/examples/python/tabs-demo/plugin.manifest.json
+++ b/examples/python/tabs-demo/plugin.manifest.json
@@ -8,16 +8,14 @@
   "permissions": [
     "ui.modify"
   ],
-  "tabs": [
-    {
+  "tabs": {
+    "music": {
       "title": "Music",
-      "slug": "music",
       "content": "music.html"
     },
-    {
+    "schedule": {
       "title": "Schedule",
-      "slug": "schedule",
       "content": "schedule.html"
     }
-  ]
+  }
 }
diff --git a/examples/python/theme-hub/plugin.manifest.json b/examples/python/theme-hub/plugin.manifest.json
index 07f6129..80835bb 100644
--- a/examples/python/theme-hub/plugin.manifest.json
+++ b/examples/python/theme-hub/plugin.manifest.json
@@ -11,12 +11,11 @@
     "storage.kv"
   ],
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin": {
         "title": "Themes",
-        "path": "/admin",
         "icon": "gear"
       }
-    ]
+    }
   }
 }
diff --git a/rules-tab/plugin.manifest.json b/rules-tab/plugin.manifest.json
index fc1ae7e..8f11e6c 100644
--- a/rules-tab/plugin.manifest.json
+++ b/rules-tab/plugin.manifest.json
@@ -11,19 +11,17 @@
     "storage.kv",
     "chat.send"
   ],
-  "tabs": [
-    {
-      "title": "Rules",
-      "slug": "rules"
+  "tabs": {
+    "rules": {
+      "title": "Rules"
     }
-  ],
+  },
   "admin": {
-    "pages": [
-      {
+    "pages": {
+      "/admin/*": {
         "title": "Rules",
-        "path": "/admin/*",
         "icon": "book"
       }
-    ]
+    }
   }
 }
diff --git a/sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md b/sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md
index 717ea1c..06be124 100644
--- a/sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md
+++ b/sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md
@@ -288,7 +288,8 @@ Important shape/behavior notes:
 - `permissions`: see the Capability map. Declare exactly what you use.
 - `config`: optional admin-configurable settings: `{ "key": { "type": "string|number|boolean", "default": ..., "description": "..." } }`, read via `owncast.config.get`.
 - UI fields (`actions`, `styles`, `scripts`, `extraPageContent`, `tabs`) all require `ui.modify`.
-- `admin.pages`: `[{ "title", "path": "/admin/*" }]`, and the host auth-gates matching paths.
+- `tabs`: `{ "tab-slug": { "title": "Tab label", "content": "optional.html" } }`.
+- `admin.pages`: `{ "/admin/*": { "title": "Settings" } }`. The host auth-gates matching path keys.
 - **`network.fetch` also requires `network` block:** `"network": { "allowedHosts": ["api.example.com", "*.weather.com"] }`. The bare wildcard `"*"` is allowed but must be written explicitly. The host rejects the load if `network.fetch` is granted without `allowedHosts`.
 
 ## Project layout
diff --git a/sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md b/sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md
index e97f49c..844eebf 100644
--- a/sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md
+++ b/sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md
@@ -294,7 +294,8 @@ Important shape/behavior notes:
 - `permissions`: see the Capability map. Declare exactly what you use.
 - `config`: optional admin-configurable settings: `{ "key": { "type": "string|number|boolean", "default": ..., "description": "..." } }`, read via `owncast.config.get`.
 - UI fields (`actions`, `styles`, `scripts`, `extraPageContent`, `tabs`) all require `ui.modify`.
-- `admin.pages`: `[{ "title", "path": "/admin/*" }]`, and the host auth-gates matching paths.
+- `tabs`: `{ "tab-slug": { "title": "Tab label", "content": "optional.html" } }`.
+- `admin.pages`: `{ "/admin/*": { "title": "Settings" } }`. The host auth-gates matching path keys.
 - **`network.fetch` also requires `network` block:** `"network": { "allowedHosts": ["api.example.com", "*.weather.com"] }`. The bare wildcard `"*"` is allowed but must be written explicitly. The host rejects the load if `network.fetch` is granted without `allowedHosts`.
 
 ## Project layout

From c76ce6adf40e704585e3f367ceb7363a17cefc8e Mon Sep 17 00:00:00 2001
From: Gabe Kangas <gabek@real-ity.com>
Date: Sat, 1 Aug 2026 20:20:10 -0700
Subject: [PATCH 2/2] ci: test paired Owncast branches

---
 .github/workflows/examples-js.yml     | 11 ++++++++---
 .github/workflows/examples-python.yml | 11 ++++++++---
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/examples-js.yml b/.github/workflows/examples-js.yml
index 70bb9bc..9327bbf 100644
--- a/.github/workflows/examples-js.yml
+++ b/.github/workflows/examples-js.yml
@@ -56,14 +56,19 @@ jobs:
 
       # Build owncast-plugin-test/serve from source and drop them into the
       # shared cache, replacing the released binaries postinstall fetched, so
-      # examples run against the current runtime. The runtime lives in owncast
-      # (services/plugins); GOPRIVATE + @develop matches release.yml.
+      # examples run against the current runtime. A matching branch in the
+      # Owncast repository takes precedence over develop for cross-repo stacks.
       - name: Build host binaries from source
         working-directory: host-runtime
         env:
           GOPRIVATE: github.com/owncast/owncast
         run: |
-          go get github.com/owncast/owncast@develop
+          owncast_ref=develop
+          if [[ -n "${GITHUB_HEAD_REF:-}" ]] && git ls-remote --exit-code --heads https://github.com/owncast/owncast.git "refs/heads/${GITHUB_HEAD_REF}" >/dev/null; then
+            owncast_ref="${GITHUB_HEAD_REF}"
+          fi
+          echo "Building against owncast@${owncast_ref}"
+          go get "github.com/owncast/owncast@${owncast_ref}"
           go build -o ../sdks/js/bin/.cache/owncast-plugin-test ./cmd/owncast-plugin-test
           go build -o ../sdks/js/bin/.cache/owncast-plugin-serve ./cmd/owncast-plugin-serve
 
diff --git a/.github/workflows/examples-python.yml b/.github/workflows/examples-python.yml
index 9e2fda1..d7128dc 100644
--- a/.github/workflows/examples-python.yml
+++ b/.github/workflows/examples-python.yml
@@ -39,14 +39,19 @@ jobs:
           go-version-file: host-runtime/go.mod
           cache-dependency-path: host-runtime/go.sum
 
-      # Build owncast-plugin-test/serve from the current owncast runtime
-      # (services/plugins). GOPRIVATE + @develop matches release.yml.
+      # Build owncast-plugin-test/serve from the current owncast runtime.
+      # A matching Owncast branch takes precedence over develop for stacked PRs.
       - name: Build host binaries from source
         working-directory: host-runtime
         env:
           GOPRIVATE: github.com/owncast/owncast
         run: |
-          go get github.com/owncast/owncast@develop
+          owncast_ref=develop
+          if [[ -n "${GITHUB_HEAD_REF:-}" ]] && git ls-remote --exit-code --heads https://github.com/owncast/owncast.git "refs/heads/${GITHUB_HEAD_REF}" >/dev/null; then
+            owncast_ref="${GITHUB_HEAD_REF}"
+          fi
+          echo "Building against owncast@${owncast_ref}"
+          go get "github.com/owncast/owncast@${owncast_ref}"
           mkdir -p "$GITHUB_WORKSPACE/pytoolchain/bin" "$GITHUB_WORKSPACE/pytoolchain/share"
           go build -o "$GITHUB_WORKSPACE/pytoolchain/bin/owncast-plugin-test" ./cmd/owncast-plugin-test
           go build -o "$GITHUB_WORKSPACE/pytoolchain/bin/owncast-plugin-serve" ./cmd/owncast-plugin-serve