Skip to content

A platform for community discussion. Free, open, simple.

DEV: Add a Discourse admin UI skill (#41040)

Martin Brennan4d7893aa2bb8
diff --git a/.skills/discourse-admin-ui/SKILL.md b/.skills/discourse-admin-ui/SKILL.md
new file mode 100644
index 00000000000..865cb0f0c11
--- /dev/null
+++ b/.skills/discourse-admin-ui/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: discourse-admin-ui
+description: Use when creating, modifying, or reviewing Discourse admin interfaces in core or plugins. Covers admin sidebar navigation, config pages, route/templates, DPageHeader breadcrumbs/tabs/actions, DPageSubheader, AdminConfigAreaCard, help insets, d-table responsive tables, empty states, third-level new/edit routes, filtered site setting pages, plugin admin UIs, translations, accessibility, and current in-repo examples.
+---
+
+# Discourse Admin UI
+
+Use this skill before building or reviewing any Discourse admin UI. It distills the Meta guide
+[Creating consistent admin interfaces](https://meta.discourse.org/t/creating-consistent-admin-interfaces/326780?tl=en)
+and points to current code examples so agents do not need to rediscover the conventions.
+
+## Workflow
+
+1. Classify the admin surface before editing:
+ - Core config page or general admin route: read [references/page-shell.md](references/page-shell.md).
+ - Cards, forms, help content, tables, empty lists, or third-level new/edit pages: read [references/content-patterns.md](references/content-patterns.md).
+ - A page that mainly exposes site settings by `area` or `category`: read [references/filtered-settings-pages.md](references/filtered-settings-pages.md).
+ - Plugin admin UI under `/admin/plugins/:plugin`: read [references/plugin-admin-interfaces.md](references/plugin-admin-interfaces.md).
+2. Inspect nearby examples in the same admin section or plugin before designing new structure. Prefer an existing route/component split over inventing a parallel pattern.
+3. Keep admin copy translatable and sentence-cased. Config page title and description keys normally live under `admin.config.page_name.title` and `admin.config.page_name.header_description`.
+4. Use standard UI primitives:
+ - `DPageHeader` for the page shell, breadcrumbs, top actions, and tabs.
+ - `DPageSubheader` for section-level headings and section actions.
+ - `AdminConfigAreaCard` for grouped configuration content.
+ - FormKit for forms.
+ - `d-table` classes for responsive tables.
+ - `AdminConfigAreaEmptyList` for createable empty lists.
+5. For templates or styles, also follow `.skills/discourse-writing-html-css`. For QUnit tests, use `.skills/discourse-writing-js-tests`.
+6. Verify route reloads work for nested/new/edit admin routes, especially plugin routes and third-level pages.
+7. Always run `bin/lint --fix` on changed files.
+
+## Quick Decisions
+
+- Adding a sidebar-visible admin config page? Add the route, template, translations, and an `ADMIN_NAV_MAP` entry with `name`, `route`, `label`, `description`, and `icon`.
+- Adding a settings-only config page? Use `AdminConfigWithSettingsRoute`, `AdminAreaSettingsBaseController`, and `AdminAreaSettings`.
+- Adding a related list of records? Use a standalone index table plus separate `new` and `edit` routes rather than inline row forms.
+- Adding a plugin configuration UI? Use `add_admin_route(..., use_new_show_route: true)`, plugin routes under `admin.adminPlugins.show`, and `api.addAdminPluginConfigurationNav`.
+- Adding page actions? Put primary/secondary actions in `DPageHeader` or `DPageSubheader` yielded actions; use specific labels such as "Add webhook", not generic labels such as "Add".
+
+## Local Anchors
+
+- Core admin nav map: `frontend/discourse/app/lib/sidebar/admin-nav-map.js`
+- Core admin route map: `frontend/discourse/admin/routes/admin-route-map.js`
+- Page header component: `frontend/discourse/app/ui-kit/d-page-header.gjs`
+- Page subheader component: `frontend/discourse/app/ui-kit/d-page-subheader.gjs`
+- Filtered settings example: `frontend/discourse/admin/templates/admin-config/localization/settings.gjs`
+- Header with tabs/actions example: `frontend/discourse/admin/templates/admin/backups.gjs`
+- Custom config page example: `frontend/discourse/admin/templates/admin-config/about.gjs`
+- Table and empty list example: `frontend/discourse/admin/templates/admin-permalinks/index.gjs`
+- Plugin nav example: `plugins/discourse-ai/assets/javascripts/discourse/initializers/admin-plugin-configuration-nav.js`
+- Plugin route map example: `plugins/discourse-ai/assets/javascripts/discourse/admin-discourse-ai-plugin-route-map.js`
diff --git a/.skills/discourse-admin-ui/agents/openai.yaml b/.skills/discourse-admin-ui/agents/openai.yaml
new file mode 100644
index 00000000000..9866ea632df
--- /dev/null
+++ b/.skills/discourse-admin-ui/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: "Discourse Admin UI"
+ short_description: "Build consistent Discourse admin screens"
+ default_prompt: "Use $discourse-admin-ui to build a consistent Discourse admin interface."
+
+policy:
+ allow_implicit_invocation: true
diff --git a/.skills/discourse-admin-ui/references/content-patterns.md b/.skills/discourse-admin-ui/references/content-patterns.md
new file mode 100644
index 00000000000..b66488e98aa
--- /dev/null
+++ b/.skills/discourse-admin-ui/references/content-patterns.md
@@ -0,0 +1,162 @@
+# Content Patterns
+
+Use this reference for admin page body layout, cards, forms, subheaders, help insets, tables, empty states, and third-level routes.
+
+## Body layout
+
+Wrap page content in the established admin page area class:
+
+```gjs
+<div class="admin-config-page__main-area">
+ ...
+</div>
+```
+
+When a page has primary content plus contextual help, use a two-column layout where the primary content takes about two-thirds and the help/reference area takes about one-third. On small screens the columns should stack. If there is no secondary content, keep the main content width consistent with comparable pages instead of expanding into a bespoke full-width layout.
+
+Prefer existing admin classes and nearby page structure before creating new layout CSS.
+
+## DPageSubheader
+
+Use `DPageSubheader` from `discourse/ui-kit/d-page-subheader` to introduce a section below the main page header, especially when the section has a description or action buttons.
+
+Use `h2`-level subheaders through the component, and keep action labels specific. Primary actions use the yielded primary button; secondary actions use default buttons and usually appear only when a primary action exists.
+
+Example to inspect: `plugins/discourse-data-explorer/admin/assets/javascripts/admin/templates/admin-plugins/show/explorer/index.gjs`.
+
+```gjs
+<DPageSubheader
+ @titleLabel={{i18n "admin.example.records.title"}}
+ @descriptionLabel={{i18n "admin.example.records.description"}}
+>
+ <:actions as |actions|>
+ <actions.Primary
+ @route="admin.example.records.new"
+ @label="admin.example.records.add"
+ />
+ </:actions>
+</DPageSubheader>
+```
+
+## Config area cards
+
+Use `AdminConfigAreaCard` from `discourse/admin/components/admin-config-area-card` for grouped settings, setup steps, and form sections. Cards should group related work, put the most important content first, and usually have one primary next action.
+
+Card headings should be sentence-cased. Use `@heading` for I18n keys or `@translatedHeading` when the caller already has translated text.
+
+```gjs
+<AdminConfigAreaCard
+ @heading="admin.config_areas.example.general_settings"
+ class="admin-example__general-settings"
+>
+ <ExampleSettingsForm @model={{@model}} />
+</AdminConfigAreaCard>
+```
+
+Current examples:
+
+- `frontend/discourse/admin/templates/admin-embedding/index.gjs`
+- `plugins/discourse-ai/admin/assets/javascripts/discourse/templates/admin-plugins/show/discourse-ai-features/edit.gjs`
+
+## Forms
+
+Use FormKit for new admin forms. Do not build ad hoc form controls when FormKit components cover the interaction. Keep client validation paired with server-side validation; do not rely only on browser or JS validation.
+
+Reference: `docs/developer-guides/docs/03-code-internals/21-form-kit.md` and `frontend/discourse/app/form-kit`.
+
+New/edit forms usually belong on third-level routes rather than inline inside a table row. This makes the form linkable, reloadable, and easier to test.
+
+## Help insets
+
+Use help/reference content for contextual docs, caveats, or links that help admins complete the task. Keep it in the secondary column and sentence-case headings. Include an icon in the heading when the surrounding pattern does so.
+
+Do not turn help content into marketing copy. It should answer what the admin needs to know at this point in the workflow.
+
+## Tables
+
+Use tables for growing sets of structured records where each row has the same attributes and admins need to scan, edit, enable/disable, or delete entries.
+
+Structural classes:
+
+- `<table class="d-table">`
+- `<thead class="d-table__header">`
+- `<tbody class="d-table__body">`
+- `<tr class="d-table__row">`
+- Overview cell: `d-table__cell --overview`
+- Detail cell: `d-table__cell --detail`
+- Controls cell: `d-table__cell --controls`
+- Action wrapper: `d-table__cell-actions`
+
+Overview cells should carry the row identity. When rows have a show/edit page, wrap the main name/description in a `LinkTo` with `d-table__overview-link`, and mark the primary name with `d-table__overview-name`.
+
+Every non-overview cell needs a mobile label matching its header:
+
+```gjs
+<td class="d-table__cell --detail">
+ <div class="d-table__mobile-label">
+ {{i18n "admin.example.status"}}
+ </div>
+ {{record.status}}
+</td>
+```
+
+For row actions:
+
+- Put actions in the far-right controls cell.
+- If there is one primary action, make it a text button such as Edit.
+- If there are multiple secondary/destructive actions, group them in `DMenu` with `DDropdownMenu`.
+- Confirm destructive actions before executing them.
+- Apply `btn-small` to row action buttons unless the local pattern says otherwise.
+- Use `DToggleSwitch` for enable/disable toggles.
+
+Current examples:
+
+- Core table and empty list: `frontend/discourse/admin/templates/admin-permalinks/index.gjs`
+- Plugin table: `plugins/discourse-data-explorer/admin/assets/javascripts/admin/templates/admin-plugins/show/explorer/index.gjs`
+- Toggle rows: `plugins/discourse-calendar/assets/javascripts/discourse/components/admin-holidays-list-item.gjs`
+
+## Empty lists
+
+When an empty list can be resolved by creating a record, use `AdminConfigAreaEmptyList` with a clear CTA label and route/action.
+
+```gjs
+<AdminConfigAreaEmptyList
+ @emptyLabel="admin.example.no_records"
+ @ctaLabel="admin.example.add_record"
+ @ctaRoute="admin.example.records.new"
+/>
+```
+
+Do not show an empty-list CTA for filtered search results. In that case show a no-results message and a way to clear/reset filters.
+
+## Third-level new/edit routes
+
+Use standalone routes for forms or detailed record editing:
+
+- New: `<resource>/new`
+- Edit: `<resource>/:id/edit`
+
+These routes must reload directly from the browser; add matching backend routes when required. Avoid inline forms inside index tables unless the existing page already depends on that pattern.
+
+Third-level new/edit pages should:
+
+- Omit the normal page header, breadcrumbs, and subheader.
+- Show a `BackButton` at the top.
+- Wrap form content in `AdminConfigAreaCard`.
+- Use card headings for form subsections.
+
+```gjs
+<BackButton
+ @route="adminConfig.flags"
+ @label="admin.config_areas.flags.back"
+/>
+
+<AdminConfigAreaCard @heading="admin.config_areas.flags.form.title">
+ <AdminFlagsForm @model={{@model}} />
+</AdminConfigAreaCard>
+```
+
+Current examples:
+
+- Thin route template: `frontend/discourse/admin/templates/admin-config/flags/new.gjs`
+- Plugin edit card: `plugins/discourse-ai/admin/assets/javascripts/discourse/templates/admin-plugins/show/discourse-ai-features/edit.gjs`
diff --git a/.skills/discourse-admin-ui/references/filtered-settings-pages.md b/.skills/discourse-admin-ui/references/filtered-settings-pages.md
new file mode 100644
index 00000000000..697edb8c288
--- /dev/null
+++ b/.skills/discourse-admin-ui/references/filtered-settings-pages.md
@@ -0,0 +1,109 @@
+# Filtered Settings Pages
+
+Use this reference when adding an admin config page that mainly displays a curated list of site settings by `area` or `category`.
+
+## When to use
+
+Use a filtered settings page when the admin task is best represented as related site settings and does not yet need a specialized custom workflow. If the page needs custom records, complex validation, setup steps, or rich help content, build a custom config page using the patterns in [content-patterns.md](content-patterns.md).
+
+## Site setting grouping
+
+Settings can be displayed by:
+
+- `area`: preferred when settings from multiple categories belong to a user-facing admin task.
+- `category`: useful when the page maps to a top-level site settings category.
+
+Add the matching `settings_area` or `settings_category` to the page's `ADMIN_NAV_MAP` entry.
+
+## Files to add
+
+For a route like `/admin/config/localization`, inspect the current implementation:
+
+- Route: `frontend/discourse/admin/routes/admin-config/localization.js`
+- Settings controller: `frontend/discourse/admin/controllers/admin-config/localization/settings.js`
+- Template: `frontend/discourse/admin/templates/admin-config/localization/settings.gjs`
+- Nav entry: `frontend/discourse/app/lib/sidebar/admin-nav-map.js`
+
+## Route map
+
+Add the route under `adminConfig` in `frontend/discourse/admin/routes/admin-route-map.js`. Settings pages usually make the `settings` child route the index path:
+
+```js
+this.route("example", { path: "/example" }, function () {
+ this.route("settings", { path: "/" });
+});
+```
+
+Use hyphenated URL slugs. Route names stay camelCase where Ember expects that.
+
+## Route class
+
+The page route should extend `AdminConfigWithSettingsRoute` and provide a title token:
+
+```js
+import { i18n } from "discourse-i18n";
+import AdminConfigWithSettingsRoute from "../admin-config-with-settings-route";
+
+export default class AdminConfigExampleRoute extends AdminConfigWithSettingsRoute {
+ titleToken() {
+ return i18n("admin.config.example.title");
+ }
+}
+```
+
+## Settings controller
+
+The settings child controller should extend `AdminAreaSettingsBaseController` so search and filtering work consistently:
+
+```js
+import AdminAreaSettingsBaseController from "discourse/admin/controllers/admin-area-settings-base";
+
+export default class AdminConfigExampleSettingsController extends AdminAreaSettingsBaseController {}
+```
+
+## Template
+
+Use `DPageHeader` and `AdminAreaSettings`. Hide internal breadcrumbs inside `AdminAreaSettings` because the page header owns breadcrumbs.
+
+```gjs
+import AdminAreaSettings from "discourse/admin/components/admin-area-settings";
+import DBreadcrumbsItem from "discourse/ui-kit/d-breadcrumbs-item";
+import DPageHeader from "discourse/ui-kit/d-page-header";
+import { i18n } from "discourse-i18n";
+
+export default <template>
+ <DPageHeader
+ @hideTabs={{true}}
+ @titleLabel={{i18n "admin.config.example.title"}}
+ @descriptionLabel={{i18n "admin.config.example.header_description"}}
+ >
+ <:breadcrumbs>
+ <DBreadcrumbsItem @path="/admin" @label={{i18n "admin_title"}} />
+ <DBreadcrumbsItem
+ @path="/admin/config/example"
+ @label={{i18n "admin.config.example.title"}}
+ />
+ </:breadcrumbs>
+ </DPageHeader>
+
+ <div class="admin-config-page__main-area">
+ <AdminAreaSettings
+ @showBreadcrumb={{false}}
+ @area="example"
+ @path="/admin/config/example"
+ @filter={{@controller.filter}}
+ @adminSettingsFilterChangedCallback={{@controller.adminSettingsFilterChangedCallback}}
+ />
+ </div>
+</template>
+```
+
+Use `@categories={{...}}` instead of `@area` only when category filtering is the intended behavior.
+
+## Checklist
+
+- Add title, header description, and optional keywords translations.
+- Add `ADMIN_NAV_MAP` entry with `settings_area` or `settings_category`.
+- Add route, controller, template, and route map entry.
+- Confirm `/admin/config/example` reloads directly.
+- Run `bin/lint --fix` on changed files.
diff --git a/.skills/discourse-admin-ui/references/page-shell.md b/.skills/discourse-admin-ui/references/page-shell.md
new file mode 100644
index 00000000000..a4ead0a36f8
--- /dev/null
+++ b/.skills/discourse-admin-ui/references/page-shell.md
@@ -0,0 +1,153 @@
+# Page Shell, Navigation, and Routes
+
+Use this reference when adding or changing a core admin page, page header, breadcrumbs, tabs, or sidebar entry.
+
+## Admin page shape
+
+Most admin config pages sit in this hierarchy:
+
+```text
+Admin interface
+Config page in sidebar
+Optional third-level tabs
+New/edit/show routes for records
+```
+
+Every sidebar-visible config page needs a stable navigation entry, browser title, page title, and page description. This supports consistency now and admin search/navigation enhancements later.
+
+## Sidebar entries
+
+Add config pages to `ADMIN_NAV_MAP` in `frontend/discourse/app/lib/sidebar/admin-nav-map.js`.
+
+Required or expected keys:
+
+- `name`: unique `snake_case` identifier.
+- `route`: Ember route name. Prefer this over `href`.
+- `label`: I18n key, usually `admin.config.page_name.title`.
+- `description`: I18n key, usually `admin.config.page_name.header_description`.
+- `icon`: FontAwesome icon name used in the sidebar.
+
+Use optional keys when relevant:
+
+- `routeModels`: route params in route order.
+- `moderator`: `true` if moderators can access the page.
+- `keywords`: I18n key containing `|`-separated search synonyms.
+- `links`: third-level child routes for admin search; these are not sidebar rows.
+- `settings_area` or `settings_category`: for pages backed by filtered site settings.
+- `multi_tabbed`: `true` when a page has settings plus other tabs.
+
+Example to inspect: `frontend/discourse/app/lib/sidebar/admin-nav-map.js`, especially `admin_localization`, `admin_login`, and `admin_permalinks`.
+
+## Translations
+
+Core config page title and description keys should be shaped like this:
+
+```yaml
+en:
+ js:
+ admin:
+ config:
+ page_name:
+ title: "Page title"
+ header_description: "What admins can manage here."
+ keywords: "optional|search|terms"
+```
+
+Keep UI text sentence-cased unless the string is a table header or a proper name. Do not split translated sentences around links or interpolated values; use placeholders.
+
+## DPageHeader
+
+Use `DPageHeader` from `discourse/ui-kit/d-page-header` for the top of admin pages.
+
+Include:
+
+- `@titleLabel`: translated page title.
+- `@descriptionLabel`: translated page description.
+- `@learnMoreUrl`: optional docs URL.
+- `@hideTabs={{true}}`: when the page has no third-level tabs.
+- `:breadcrumbs`: one `DBreadcrumbsItem` for `/admin`, plus the current page and any parent context.
+- `:actions`: page-level actions. Use yielded `actions.Primary`, `actions.Default`, `actions.Danger`, or `actions.Wrapped`.
+- `:tabs`: third-level `DNavItem` entries.
+
+The component automatically hides itself on admin `new` and `edit` route segments. Override with `@shouldDisplay` only when the route intentionally needs a header.
+
+Current examples:
+
+- Simple page header: `frontend/discourse/admin/templates/admin-config/about.gjs`
+- Header around filtered settings: `frontend/discourse/admin/templates/admin-config/localization/settings.gjs`
+- Header with actions and tabs: `frontend/discourse/admin/templates/admin/backups.gjs`
+- Plugin wrapper header: `frontend/discourse/admin/components/admin-plugin-config-page.gjs`
+
+Minimal shape:
+
+```gjs
+import DBreadcrumbsItem from "discourse/ui-kit/d-breadcrumbs-item";
+import DPageHeader from "discourse/ui-kit/d-page-header";
+import { i18n } from "discourse-i18n";
+
+export default <template>
+ <DPageHeader
+ @titleLabel={{i18n "admin.config.example.title"}}
+ @descriptionLabel={{i18n "admin.config.example.header_description"}}
+ @hideTabs={{true}}
+ >
+ <:breadcrumbs>
+ <DBreadcrumbsItem @path="/admin" @label={{i18n "admin_title"}} />
+ <DBreadcrumbsItem
+ @path="/admin/config/example"
+ @label={{i18n "admin.config.example.title"}}
+ />
+ </:breadcrumbs>
+ </DPageHeader>
+
+ <div class="admin-config-page__main-area">
+ {{outlet}}
+ </div>
+</template>
+```
+
+## Tabs
+
+Use tabs only for related views inside the same admin context. Do not use them as primary admin navigation; the sidebar owns that.
+
+Tabs are rendered in the `DPageHeader` `:tabs` block with `DNavItem` from `discourse/ui-kit/d-nav-item`.
+
+```gjs
+<:tabs>
+ <DNavItem
+ @route="admin.example.settings"
+ @label="settings"
+ class="admin-example-tabs__settings"
+ />
+ <DNavItem
+ @route="admin.example.records"
+ @label="admin.example.records"
+ class="admin-example-tabs__records"
+ />
+</:tabs>
+```
+
+If plugins should extend the tab list, include the established `PluginOutlet` for that area rather than hardcoding plugin links.
+
+## Browser titles
+
+Admin routes should extend Discourse route classes and implement `titleToken()` when they own a browser title:
+
+```js
+import { i18n } from "discourse-i18n";
+import DiscourseRoute from "discourse/routes/discourse";
+
+export default class AdminExampleRoute extends DiscourseRoute {
+ titleToken() {
+ return i18n("admin.config.example.title");
+ }
+}
+```
+
+For filtered settings pages, use the specialized route class described in [filtered-settings-pages.md](filtered-settings-pages.md).
+
+## Breadcrumbs
+
+Breadcrumbs appear above the page header content on normal admin pages. Use a `/admin` crumb first, then page hierarchy crumbs, and mark the current page by using the current path and title. Do not add the normal header/breadcrumb area to third-level new/edit pages; use a back link there instead.
+
+The implementation is via `DBreadcrumbsItem` yielded into the `DPageHeader`; `DPageHeader` provides the container.
diff --git a/.skills/discourse-admin-ui/references/plugin-admin-interfaces.md b/.skills/discourse-admin-ui/references/plugin-admin-interfaces.md
new file mode 100644
index 00000000000..810c6727037
--- /dev/null
+++ b/.skills/discourse-admin-ui/references/plugin-admin-interfaces.md
@@ -0,0 +1,159 @@
+# Plugin Admin Interfaces
+
+Use this reference when creating or reviewing a custom plugin admin UI under `/admin/plugins/:plugin`.
+
+## When to build one
+
+Build a plugin admin UI when a plugin needs more than a generated settings list: record management, setup workflows, reports, nested pages, custom tables, or multiple related configuration views. If the plugin only exposes site settings, rely on the generated settings page.
+
+Core examples to inspect:
+
+- Discourse AI: `plugins/discourse-ai`
+- Data Explorer: `plugins/discourse-data-explorer`
+- Chat Integration: `plugins/discourse-chat-integration`
+- Gamification: `plugins/discourse-gamification`
+
+## Server-side registration
+
+Use `add_admin_route` in `plugin.rb` and pass `use_new_show_route: true` so the plugin uses the modern plugin show page:
+
+```ruby
+add_admin_route("plugin_example.title", "plugin-example", { use_new_show_route: true })
+```
+
+Some plugins pass the options hash as the third argument; others use keyword style. Follow nearby style.
+
+Examples:
+
+- `plugins/discourse-ai/plugin.rb`
+- `plugins/discourse-data-explorer/plugin.rb`
+- `plugins/discourse-chat-integration/plugin.rb`
+
+## Route map
+
+Plugin admin routes should attach to `admin.adminPlugins.show` with `path: "/plugins"`.
+
+Create a route map such as `assets/javascripts/discourse/admin-plugin-example-plugin-route-map.js`:
+
+```js
+export default {
+ resource: "admin.adminPlugins.show",
+ path: "/plugins",
+
+ map() {
+ this.route("plugin-example-items", { path: "items" }, function () {
+ this.route("new");
+ this.route("edit", { path: "/:id/edit" });
+ });
+ },
+};
+```
+
+Current examples:
+
+- `plugins/discourse-ai/assets/javascripts/discourse/admin-discourse-ai-plugin-route-map.js`
+- `plugins/discourse-data-explorer/assets/javascripts/discourse/explorer-route-map.js`
+- `plugins/discourse-chat-integration/assets/javascripts/discourse/admin-chat-integration-plugin-route-map.js`
+
+## File locations
+
+Modern plugin admin route JS files live under:
+
+```text
+admin/assets/javascripts/discourse/routes/admin-plugins/show/
+```
+
+Templates live under:
+
+```text
+admin/assets/javascripts/discourse/templates/admin-plugins/show/
+```
+
+Simple routes usually have one template like:
+
+```text
+admin/assets/javascripts/discourse/templates/admin-plugins/show/plugin-example-items.gjs
+```
+
+Nested routes use the normal Ember structure with `index.gjs`, `new.gjs`, `edit.gjs`, or route-specific names under the route folder.
+
+## Plugin navigation
+
+Register plugin configuration navigation from an initializer, and only run it for admins:
+
+```js
+import { withPluginApi } from "discourse/lib/plugin-api";
+
+const PLUGIN_ID = "plugin-example";
+
+export default {
+ name: "plugin-example-admin-plugin-configuration-nav",
+
+ initialize(container) {
+ const currentUser = container.lookup("service:current-user");
+ if (!currentUser?.admin) {
+ return;
+ }
+
+ withPluginApi((api) => {
+ api.addAdminPluginConfigurationNav(PLUGIN_ID, [
+ {
+ label: "plugin_example.items.short_title",
+ route: "adminPlugins.show.plugin-example-items",
+ description: "plugin_example.items.description",
+ },
+ ]);
+ });
+ },
+};
+```
+
+The plugin's generated settings link is added automatically. Do not duplicate it in `addAdminPluginConfigurationNav`.
+
+Top tabs are preferred for plugin navigation. Avoid introducing an inner sidebar for new plugin UIs.
+
+Example: `plugins/discourse-ai/assets/javascripts/discourse/initializers/admin-plugin-configuration-nav.js`.
+
+## Page structure
+
+The plugin show wrapper renders the main `DPageHeader`; plugin index routes should normally render `DPageSubheader` to describe the selected tab and provide tab-local actions.
+
+Use the same content primitives as core admin pages:
+
+- `AdminConfigAreaCard` for grouped forms and setup areas.
+- `AdminConfigAreaEmptyList` for empty createable lists.
+- `d-table` classes for growing record lists.
+- Third-level `new` and `edit` routes for forms.
+- `BackButton` on new/edit pages instead of the full header.
+
+Examples:
+
+- Plugin subheader and table: `plugins/discourse-data-explorer/admin/assets/javascripts/admin/templates/admin-plugins/show/explorer/index.gjs`
+- Plugin nested detail page: `plugins/discourse-chat-integration/admin/assets/javascripts/discourse/templates/admin-plugins/show/discourse-chat-integration-providers/show.gjs`
+- Plugin edit card: `plugins/discourse-ai/admin/assets/javascripts/discourse/templates/admin-plugins/show/discourse-ai-features/edit.gjs`
+
+## Header actions outlet
+
+If a plugin needs actions in the main plugin page header rather than inside a tab/subsection, render a component into the `admin-plugin-config-page-actions` outlet from the same initializer that registers plugin navigation.
+
+```js
+api.renderInOutlet(
+ "admin-plugin-config-page-actions",
+ PluginExampleAdminActions
+);
+```
+
+The outlet receives the plugin model and `DPageHeader` action components through `outletArgs`; use those instead of hand-rolling header buttons.
+
+Implementation anchor: `frontend/discourse/admin/components/admin-plugin-config-page.gjs`.
+
+## Checklist
+
+- Register the plugin admin route with `use_new_show_route: true`.
+- Add a plugin route map under `admin.adminPlugins.show`.
+- Add route JS and templates under `admin/assets/javascripts/discourse/...`.
+- Register top-tab navigation with `api.addAdminPluginConfigurationNav` in an admin-only initializer.
+- Use `DPageSubheader` inside plugin index routes.
+- Use cards, tables, empty states, FormKit, and third-level routes consistently with core admin pages.
+- Confirm direct reload works for every plugin route, including `new` and `edit`.
+- Run `bin/lint --fix` on changed files.