Add enterprise documentation constructs

.claude/skills/docs-review/SKILL.md

@@ -51,6 +51,7 @@ Perform critical editorial reviews as a tech writer / copyeditor, focusing on cl
 - **Heading count**: 20+ headings signals over-segmentation; consolidate
 - **Information flow**: Conceptual content (trade-offs, when to use) should come before implementation details, not after
 - **Admonition weight**: Tips, notes, and warnings should be supplementary. If an admonition contains primary feature documentation (full YAML examples, the only explanation of a field or concept), it should be promoted to a proper section or its own page. A good test: if this admonition is the only place a feature is documented, it's not a tip - it's a section that needs a heading and ToC visibility.
+- **Enterprise construct usage**: Three constructs exist for enterprise content - check they're used correctly. `:::enterprise` admonitions are for callout blocks (2-4 sentences, max 1-2 per page). `<EnterpriseBadge />` is for inline feature labels next to headings or list items. `className: 'enterprise-only'` in the sidebar is for enterprise-only pages. Flag misuse: enterprise admonitions used for single-feature labels (use `<EnterpriseBadge />` instead), badge used on entire page descriptions (use the admonition instead), or excessive enterprise admonitions on a single page.
 - **Diataxis alignment**: Don't mix tutorials, how-tos, reference, and concepts in one doc without clear separation
 
 ### LLM-Generated Content Patterns

AGENTS.md

@@ -263,7 +263,43 @@ This website is built using Docusaurus, which has some specific requirements and
   - Titles are added using the `title="..."` attribute in the opening code fence.
   - Line highlights are added using comma-separated `{number}` or `{start-end}` ranges in the opening code fence, or `highlight-next-line`, `highlight-start`, and `highlight-end` comments within the code block.
 - Use admonitions for notes, tips, warnings, and other annotations. This provides a consistent look and feel across the site.
-  - Use the `:::type` syntax to define the admonition type: `note`, `tip`, `info`, `warning`, or `danger`. Use square brackets to add a custom title, e.g. `:::info[Title]`. Add empty lines around the start and end directives.
+  - Use the `:::type` syntax to define the admonition type: `note`, `tip`, `info`, `warning`, `danger`, or `enterprise`. Use square brackets to add a custom title, e.g. `:::info[Title]`. Add empty lines around the start and end directives.
+  - The `:::enterprise` admonition is for Stacklok Enterprise content only - see "Enterprise content constructs" below.
 - Place images in `static/img` using WebP, PNG, or SVG format.
 - Use the `ThemedImage` component to provide both light and dark mode screenshots for apps/UIs that support both. Typically used with the `useBaseUrl` hook to construct the image paths. Both require import statements.
 - Use the `Tabs` and `TabItem` components to create tabbed content sections. These are in the global scope and do not require imports.
+- Use the `EnterpriseBadge` component to label individual features or capabilities as enterprise-only. This is in the global scope and does not require imports. See "Enterprise content constructs" below.
+
+### Enterprise content constructs
+
+Three constructs are available for presenting Stacklok Enterprise content inline with OSS documentation. Use the right one for the context:
+
+**`:::enterprise` admonition** - for callout content within OSS pages, typically 2-4 sentences describing an Enterprise capability with a link to the Enterprise landing page. Use when Enterprise adds a meaningful capability to the topic being documented. Don't overuse - one per page is typical, two is the practical maximum.
+
+```mdx
+:::enterprise
+
+Stacklok Enterprise includes turnkey integrations for common identity providers. Instead of manually configuring OIDC, use the built-in Okta or Entra ID integration to map IdP groups directly to ToolHive roles and policy sets.
+
+[Learn more about Stacklok Enterprise](/toolhive/enterprise).
+
+:::
+```
+
+**`<EnterpriseBadge />`** - inline label for tagging individual features, capabilities, or configuration options as enterprise-only. Works next to headings, in lists, or inline with text. Use when a specific feature within a broader page is enterprise-only.
+
+```mdx
+### Session pinning <EnterpriseBadge />
+
+- **Automatic failover** <EnterpriseBadge /> - connections are automatically rerouted when a node becomes unavailable.
+```
+
+**`className: 'enterprise-only'` sidebar badge** - for marking enterprise-only pages in the sidebar navigation. Applied in `sidebars.ts`, not in the page itself. Renders a small "ENT" pill badge with a tooltip on hover.
+
+```ts title="sidebars.ts"
+{
+  type: 'doc',
+  id: 'toolhive/guides-enterprise/config-server',
+  className: 'enterprise-only',
+}
+```

docs/theme-preview.mdx

@@ -174,6 +174,48 @@ This is getting silly
 
 :::::
 
+## Enterprise constructs
+
+Components for presenting Stacklok Enterprise content inline with OSS docs.
+
+### Enterprise admonition
+
+Custom `:::enterprise` admonition for callout content within OSS pages. Uses the
+Stacklok symbol as the icon and a teal color palette distinct from the other
+admonition types. Supports custom titles via `:::enterprise[My title]`.
+
+:::enterprise
+
+Stacklok Enterprise includes turnkey integrations for common identity providers.
+Instead of manually configuring OIDC, use the built-in Okta or Entra ID
+integration to map IdP groups directly to ToolHive roles and policy sets.
+
+[Learn more about Stacklok Enterprise](/toolhive/enterprise).
+
+:::
+
+### Enterprise badge
+
+Inline `<EnterpriseBadge />` component for labeling individual features or
+capabilities within a page. Works next to headings, in lists, or inline with
+text.
+
+#### Session pinning <EnterpriseBadge />
+
+Sessions can be pinned to a specific node for the duration of a connection.
+
+- **Automatic failover** <EnterpriseBadge /> - connections are automatically
+  rerouted when a node becomes unavailable.
+- **Manual failover** - connections can be manually rerouted by an
+  administrator.
+
+### Sidebar badge
+
+Enterprise-only pages can be marked with an `ENT` badge in the sidebar by adding
+`className: 'enterprise-only'` to the sidebar item in `sidebars.ts`. The badge
+includes a tooltip on hover. See "Stacklok Enterprise" in the sidebar for an
+example.
+
 ## Tables
 
 A standard Markdown table:

docusaurus.config.ts

@@ -171,6 +171,10 @@ const config: Config = {
           // Populate lastUpdatedAt metadata for JSON-LD structured data.
           // The rendered timestamp is hidden via CSS (.theme-last-updated).
           showLastUpdateTime: true,
+          admonitions: {
+            keywords: ['enterprise'],
+            extendDefaults: true,
+          },
         },
         blog: {
           blogTitle: 'ToolHive Updates and Announcements',

eslint.config.mjs

@@ -45,6 +45,7 @@ export default [
         Tabs: 'readonly',
         TabItem: 'readonly',
         MCPMetadata: 'readonly',
+        EnterpriseBadge: 'readonly',
       },
     },
   },

src/components/EnterpriseBadge/index.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import styles from './styles.module.css';
+
+export default function EnterpriseBadge(): React.ReactNode {
+  return (
+    <span className={styles.badge} title='Stacklok Enterprise feature'>
+      Enterprise
+    </span>
+  );
+}

src/components/EnterpriseBadge/styles.module.css

@@ -0,0 +1,20 @@
+.badge {
+  display: inline-flex;
+  align-items: center;
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  line-height: 1;
+  padding: 0.2em 0.6em;
+  border: 1.5px solid #2a9d8f;
+  border-radius: 6px;
+  color: #1a5c54;
+  vertical-align: middle;
+  margin-left: 0.4em;
+  white-space: nowrap;
+}
+
+:global([data-theme='dark']) .badge {
+  color: #c8ece7;
+  border-color: #2a9d8f;
+}

src/css/custom.css

@@ -382,6 +382,71 @@ details summary:hover {
   --ifm-alert-foreground-color: var(--stacklok-green-light);
 }
 
+/* Enterprise admonitions - teal */
+.alert--enterprise {
+  --ifm-alert-background-color: #d5f0ec;
+  --ifm-alert-border-color: #1a8a7d;
+  --ifm-alert-foreground-color: #0f4f48;
+}
+
+[data-theme='dark'] .alert--enterprise {
+  --ifm-alert-background-color: #1a3330;
+  --ifm-alert-border-color: #2a9d8f;
+  --ifm-alert-foreground-color: #c8ece7;
+}
+
+/* Sidebar badge for enterprise-only pages */
+.enterprise-only > .menu__link {
+  position: relative;
+}
+
+.enterprise-only > .menu__link::after {
+  content: 'ENT';
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.55rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+  line-height: 1;
+  padding: 0.15em 0.4em;
+  margin-left: 0.75em;
+  border: 1.5px solid #2a9d8f;
+  border-radius: 999px;
+  color: #1a5c54;
+  flex-shrink: 0;
+}
+
+.enterprise-only > .menu__link:hover::before,
+.enterprise-only > .menu__link:focus-visible::before {
+  content: 'Stacklok Enterprise feature';
+  position: absolute;
+  left: 50%;
+  bottom: calc(100% + 6px);
+  transform: translateX(-50%);
+  padding: 0.3em 0.6em;
+  font-size: 0.7rem;
+  font-weight: 500;
+  line-height: 1.3;
+  white-space: nowrap;
+  color: #fff;
+  background: #1a5c54;
+  border-radius: 4px;
+  pointer-events: none;
+  z-index: 10;
+}
+
+[data-theme='dark'] .enterprise-only > .menu__link::after {
+  color: #c8ece7;
+  border-color: #2a9d8f;
+}
+
+[data-theme='dark'] .enterprise-only > .menu__link:hover::before,
+[data-theme='dark'] .enterprise-only > .menu__link:focus-visible::before {
+  background: #1a5c54;
+  color: #c8ece7;
+}
+
 /* Screenshot styling with subtle border */
 .screenshot {
   border: 1px solid var(--ifm-table-border-color);

src/theme/Admonition/Types.tsx

@@ -0,0 +1,46 @@
+import React, { type ReactNode } from 'react';
+import DefaultAdmonitionTypes from '@theme-original/Admonition/Types';
+import AdmonitionLayout from '@theme/Admonition/Layout';
+
+const StacklokIcon = () => (
+  <svg
+    width='20'
+    height='18'
+    viewBox='0 0 147 129'
+    fill='none'
+    xmlns='http://www.w3.org/2000/svg'
+    aria-hidden='true'
+  >
+    <path
+      fillRule='evenodd'
+      clipRule='evenodd'
+      d='M73.4721 0C73.5628 2.93136e-06 73.653 0.00281392 73.7426 0.00878906C75.0869 0.0983668 76.3072 0.851495 76.9868 2.02832L146.402 122.257C146.444 122.331 146.483 122.406 146.521 122.481C146.527 122.493 146.532 122.505 146.538 122.517C146.544 122.529 146.551 122.542 146.557 122.555C146.564 122.569 146.571 122.584 146.578 122.599C146.612 122.674 146.644 122.749 146.673 122.825C146.677 122.834 146.68 122.843 146.683 122.853C146.728 122.972 146.768 123.093 146.801 123.215C146.806 123.233 146.811 123.251 146.816 123.27C146.842 123.369 146.863 123.469 146.881 123.569C146.883 123.579 146.885 123.589 146.886 123.599C146.894 123.644 146.901 123.69 146.908 123.735C146.91 123.749 146.911 123.763 146.913 123.776C146.918 123.823 146.924 123.869 146.928 123.916C146.929 123.928 146.929 123.939 146.93 123.951C146.941 124.082 146.946 124.213 146.944 124.344C146.944 124.36 146.943 124.377 146.943 124.394C146.94 124.483 146.936 124.573 146.927 124.662C146.926 124.678 146.923 124.695 146.921 124.711C146.902 124.89 146.872 125.067 146.83 125.242C146.823 125.269 146.817 125.296 146.81 125.322C146.788 125.404 146.764 125.486 146.737 125.566C146.732 125.582 146.727 125.598 146.721 125.613C146.717 125.625 146.713 125.637 146.708 125.648C146.682 125.722 146.655 125.796 146.624 125.868C146.616 125.889 146.605 125.908 146.596 125.929C146.595 125.931 146.594 125.934 146.593 125.937C146.59 125.945 146.586 125.953 146.582 125.961C146.555 126.023 146.525 126.083 146.494 126.144C146.487 126.155 146.482 126.168 146.476 126.18C146.464 126.202 146.452 126.224 146.44 126.246C146.428 126.268 146.415 126.29 146.402 126.312C146.387 126.338 146.373 126.363 146.358 126.388C146.349 126.402 146.34 126.417 146.331 126.432C146.325 126.441 146.319 126.45 146.313 126.459C146.093 126.806 145.819 127.123 145.492 127.396C145.481 127.406 145.47 127.415 145.458 127.424C145.411 127.463 145.362 127.501 145.312 127.538C145.288 127.556 145.265 127.574 145.241 127.591C145.233 127.597 145.224 127.603 145.216 127.608L145.213 127.611C145.203 127.618 145.192 127.624 145.182 127.631C145.142 127.658 145.102 127.685 145.061 127.711C145.052 127.717 145.043 127.723 145.034 127.729C144.942 127.786 144.848 127.839 144.752 127.889C144.732 127.899 144.713 127.91 144.693 127.92C144.687 127.923 144.682 127.924 144.676 127.927C144.673 127.928 144.671 127.93 144.668 127.932C144.651 127.94 144.633 127.949 144.615 127.957C144.453 128.033 144.288 128.098 144.121 128.151C144.115 128.153 144.11 128.155 144.105 128.156C143.913 128.217 143.718 128.262 143.522 128.293C143.515 128.294 143.508 128.295 143.5 128.296C143.448 128.304 143.395 128.311 143.342 128.317C143.328 128.319 143.314 128.321 143.3 128.322C143.269 128.325 143.238 128.328 143.207 128.33C143.202 128.33 143.197 128.331 143.192 128.331C143.127 128.336 143.062 128.339 142.997 128.341C142.983 128.341 142.97 128.342 142.957 128.342C142.936 128.342 142.915 128.343 142.894 128.343C142.885 128.343 142.876 128.343 142.867 128.343C142.795 128.342 142.724 128.339 142.653 128.335C142.641 128.334 142.629 128.334 142.618 128.333C142.594 128.331 142.571 128.33 142.547 128.328C142.467 128.321 142.388 128.312 142.308 128.301C142.303 128.3 142.298 128.3 142.292 128.299C142.289 128.298 142.285 128.298 142.282 128.298C142.265 128.295 142.249 128.292 142.233 128.289C142.145 128.275 142.058 128.257 141.971 128.237C141.965 128.236 141.958 128.235 141.952 128.233C141.938 128.23 141.924 128.226 141.91 128.223C141.815 128.199 141.721 128.173 141.627 128.143C141.541 128.114 141.455 128.082 141.371 128.048C141.361 128.044 141.351 128.041 141.341 128.037L141.31 128.024C141.297 128.019 141.285 128.014 141.272 128.009L73.8533 100.211C73.6092 100.11 73.3351 100.11 73.0909 100.211L5.66061 128.014L5.65865 128.015L5.65377 128.017L5.60397 128.037C5.6006 128.038 5.5966 128.039 5.59322 128.04C5.50318 128.077 5.41265 128.112 5.32076 128.142C5.22609 128.173 5.13013 128.199 5.03365 128.223C5.01924 128.226 5.00513 128.231 4.99069 128.234C4.98491 128.236 4.97888 128.236 4.97311 128.237C4.89317 128.256 4.81274 128.272 4.7319 128.285C4.70775 128.289 4.6838 128.294 4.65963 128.298L4.65377 128.299C4.64407 128.3 4.63418 128.3 4.62447 128.302C4.54884 128.312 4.47307 128.322 4.39694 128.328C4.37739 128.33 4.35789 128.332 4.33834 128.333C4.31558 128.335 4.29276 128.335 4.26998 128.336C4.20623 128.339 4.14248 128.342 4.07858 128.343C4.06881 128.343 4.05905 128.343 4.04928 128.343C4.02877 128.343 4.00827 128.342 3.98776 128.342C3.97473 128.342 3.96172 128.341 3.94869 128.341C3.88323 128.339 3.81782 128.336 3.7524 128.331C3.7472 128.331 3.74198 128.33 3.73678 128.33C3.70617 128.328 3.67556 128.325 3.64498 128.322C3.62899 128.321 3.6131 128.318 3.59713 128.316C3.54497 128.31 3.49288 128.304 3.44088 128.296C3.43601 128.295 3.4311 128.295 3.42623 128.294C3.38154 128.287 3.33697 128.279 3.29244 128.271C3.2846 128.269 3.27684 128.267 3.26901 128.266C3.1724 128.247 3.07644 128.224 2.98092 128.197C2.966 128.193 2.95088 128.19 2.936 128.186C2.90979 128.178 2.88397 128.169 2.85787 128.161C2.84321 128.157 2.82854 128.152 2.81393 128.147C2.7538 128.128 2.6937 128.108 2.63424 128.086C2.62478 128.082 2.61535 128.079 2.60592 128.075C2.58466 128.067 2.56361 128.058 2.54244 128.05C2.53717 128.048 2.53208 128.045 2.52682 128.043C2.49224 128.029 2.45756 128.015 2.4233 128C2.40399 127.991 2.3849 127.982 2.36569 127.974C2.33329 127.959 2.30108 127.943 2.26901 127.928C2.26064 127.924 2.25195 127.92 2.24362 127.916C2.23308 127.911 2.22287 127.905 2.21237 127.899C2.10962 127.847 2.00853 127.79 1.90963 127.729C1.90083 127.723 1.89204 127.717 1.88326 127.712C1.71747 127.607 1.55713 127.489 1.40475 127.357C1.38082 127.337 1.35778 127.315 1.33444 127.294C1.29208 127.256 1.25085 127.217 1.21041 127.177C1.09977 127.068 0.99578 126.955 0.899865 126.836C0.878841 126.81 0.858659 126.783 0.838342 126.757C0.821064 126.734 0.803343 126.712 0.786584 126.689C0.774812 126.673 0.763922 126.657 0.752404 126.641C0.692665 126.557 0.636251 126.471 0.583459 126.384C0.571772 126.364 0.560627 126.345 0.549279 126.325C0.531753 126.295 0.514227 126.265 0.497521 126.234C0.487599 126.216 0.477859 126.198 0.468225 126.18C0.461972 126.168 0.456775 126.155 0.450646 126.144C0.421581 126.087 0.392983 126.03 0.366662 125.973C0.360128 125.958 0.353494 125.944 0.347131 125.93C0.308793 125.843 0.273781 125.755 0.241662 125.666C0.23159 125.638 0.221816 125.61 0.212365 125.582C0.183705 125.497 0.157189 125.411 0.13424 125.324C0.12809 125.301 0.123373 125.277 0.117639 125.254C0.0737987 125.075 0.04228 124.894 0.0229121 124.711C0.0211957 124.695 0.0185719 124.678 0.0170527 124.662C0.00870127 124.573 0.00386734 124.483 0.00142769 124.394C0.000959042 124.376 0.000691781 124.358 0.000451126 124.341C-0.00133802 124.215 0.00211938 124.088 0.0121699 123.962C0.0134684 123.946 0.0145801 123.929 0.0160761 123.913C0.0205894 123.864 0.0263452 123.815 0.0326777 123.766C0.0337674 123.757 0.0344641 123.749 0.0356074 123.74C0.0484609 123.645 0.0647103 123.55 0.0844355 123.456C0.0908408 123.425 0.0978114 123.395 0.104943 123.364C0.11179 123.335 0.118906 123.306 0.126428 123.276C0.131712 123.256 0.137412 123.235 0.143029 123.215C0.176423 123.093 0.215895 122.972 0.261193 122.853C0.264654 122.843 0.268405 122.834 0.271935 122.825C0.277581 122.811 0.282712 122.796 0.288537 122.781L0.304162 122.742C0.330496 122.678 0.358339 122.615 0.388146 122.552C0.392004 122.544 0.395949 122.535 0.399865 122.527C0.443862 122.436 0.492018 122.346 0.54342 122.257L69.9585 2.02832L70.101 1.79883C70.8038 0.749524 71.9571 0.0867155 73.2182 0.0078125C73.3024 0.00254865 73.3871 7.78799e-06 73.4721 0ZM34.8266 105.087C33.9179 105.807 34.757 107.238 35.8287 106.796L71.9253 91.9131C72.9159 91.5047 74.0284 91.5047 75.019 91.9131L111.115 106.795C112.186 107.237 113.026 105.806 112.117 105.087L74.0931 74.9655C73.7293 74.6773 73.215 74.6773 72.8512 74.9655L34.8266 105.087ZM38.8716 89.0045C38.099 89.9276 39.3158 91.1775 40.2594 90.4301L70.9526 66.1172C72.4287 64.9479 74.5155 64.9481 75.9917 66.1172L106.685 90.4308C107.628 91.1782 108.845 89.9283 108.073 89.0051L74.239 48.5737C73.8393 48.096 73.1049 48.096 72.7052 48.5737L38.8716 89.0045ZM36.7057 75.8545C36.0944 76.9133 37.5539 77.9339 38.3386 76.9963L70.3608 38.7314L70.5092 38.5625C71.274 37.7451 72.3461 37.2774 73.4721 37.2773C74.6734 37.2774 75.8135 37.8102 76.5844 38.7314L108.605 76.9962C109.39 77.9338 110.849 76.9133 110.238 75.8545L74.3382 13.6738C73.9533 13.0072 72.991 13.0072 72.6061 13.6738L36.7057 75.8545Z'
+      fill='currentColor'
+    />
+  </svg>
+);
+
+interface EnterpriseAdmonitionProps {
+  children: ReactNode;
+  title?: string;
+  className?: string;
+}
+
+function EnterpriseAdmonition(props: EnterpriseAdmonitionProps): ReactNode {
+  return (
+    <AdmonitionLayout
+      icon={<StacklokIcon />}
+      title={props.title ?? 'Stacklok Enterprise'}
+      className={`alert alert--enterprise ${props.className ?? ''}`}
+    >
+      {props.children}
+    </AdmonitionLayout>
+  );
+}
+
+const AdmonitionTypes = {
+  ...DefaultAdmonitionTypes,
+  enterprise: EnterpriseAdmonition,
+};
+
+export default AdmonitionTypes;

src/theme/MDXComponents.tsx

@@ -10,6 +10,7 @@ import MDXComponents from '@theme-original/MDXComponents';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import MCPMetadata from '@site/src/components/MCPMetadata';
+import EnterpriseBadge from '@site/src/components/EnterpriseBadge';
 
 export default {
   // Reusing the default mapping
@@ -18,4 +19,5 @@ export default {
   Tabs,
   TabItem,
   MCPMetadata,
+  EnterpriseBadge,
 };