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.mdnew file mode 100644index 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.yamlnew file mode 100644index 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: truediff --git a/.skills/discourse-admin-ui/references/content-patterns.md b/.skills/discourse-admin-ui/references/content-patterns.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.