[pull] master from mattermost:master

.github/workflows/docs-cd.yml

@@ -27,6 +27,7 @@ jobs:
       - name: cd/checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
+          submodules: true
           persist-credentials: false
 
       - name: cd/setup-node

.github/workflows/docs-ci.yaml

@@ -25,6 +25,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
+          submodules: true
           persist-credentials: false
 
       - name: Set up Node

.gitignore

@@ -193,6 +193,12 @@ docs/pdf/build/
 docs/pdf/node_modules/
 docs/site/openapi/
 
+# Agents docs, staged from the mattermost-plugin-agents submodule at build
+# time by docs/site/scripts/stage-agents-docs.mjs (see docs/vendor/) — never
+# tracked as source, regenerated on every prestart/prebuild.
+docs/main/agents/docs/
+docs/site/static/images/agents/
+
 # OpenAPI make build artifacts
 api/v4/html/static/mattermost-openapi-v4.yaml
 api/v4/html/index.html

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "docs/vendor/mattermost-plugin-agents"]
+	path = docs/vendor/mattermost-plugin-agents
+	url = https://github.com/mattermost/mattermost-plugin-agents.git
+	branch = master

docs/main/administration-guide/configure/agents-admin-guide.mdx

@@ -1,9 +1,11 @@
 ---
 title: "Mattermost Agents Admin Guide"
 ---
+import AgentsAdminGuideBody from '../../agents/docs/_admin_guide_partial.mdx';
+
 <PlanAvailability slug="all-commercial" />
 
-{/* TODO: include /agents/docs/admin_guide.md could not be resolved */}
+<AgentsAdminGuideBody />
 
 ## Additional configuration guides
 

docs/main/administration-guide/upgrade/important-upgrade-notes.mdx

@@ -466,7 +466,7 @@ DROP INDEX CONCURRENTLY IF EXISTS idx_propertyfields_protected;</code></pre></td
 <td>The <code>role_updated</code> WebSocket events are scoped to the affected team/channel instead of broadcasting globally, improving performance and reducing unnecessary network traffic. No manual action is required from administrators as the migration runs automatically during the upgrade. No downtime is expected, and no special planning is needed for the upgrade as the migration can run during normal operations. All installations are affected by this change, but the impact is minimal since the <code>roles</code> table is small with well under 10k rows even on large installations. The upgrade includes automatic database migrations to add a <code>schemeid</code> column to the <code>roles</code> table for efficient role-scheme lookups. The migrations use PostgreSQL's non-blocking techniques: first adding the column with a brief ACCESS EXCLUSIVE lock (catalog-only operation), then backfilling existing data with a ROW EXCLUSIVE lock, and finally creating an index concurrently with a SHARE UPDATE EXCLUSIVE lock that doesn't block other operations. The <code>roles</code> table size is bounded and unaffected by posts, reactions, or other high-volume data. The migrations are fully backwards-compatible.</td>
 </tr>
 <tr>
-<td>v11.7 includes Agents plugin v2. Please see <a href="https://github.com/mattermost/mattermost-plugin-agents/blob/master/docs/upgrading_to_2.0.md">this guide</a> on how to upgrade the Mattermost Agents plugin from a v1.x release to v2.0.0. It covers the supported version path, the migrations that run automatically on first start of v2.0.0, the breaking changes and default-behavior flips that admins should know about before the upgrade window, and the verification steps to confirm the upgrade succeeded.</td>
+<td>v11.7 includes Agents plugin v2. Please see <a href="/agents/docs/upgrading_to_2.0">this guide</a> on how to upgrade the Mattermost Agents plugin from a v1.x release to v2.0.0. It covers the supported version path, the migrations that run automatically on first start of v2.0.0, the breaking changes and default-behavior flips that admins should know about before the upgrade window, and the verification steps to confirm the upgrade succeeded.</td>
 </tr>
 <tr>
 <td><p>v11.7.6 migration removes orphaned rows from the <code>threadmemberships</code> table — specifically, rows where the associated user is no longer a member of the channel that the thread belongs to. The cleanup is performed via a filtered <code>DELETE</code> using a three-way join across <code>threadmemberships</code>, <code>threads</code>, and <code>channelmembers</code>. No schema objects (tables, columns, or indexes) are added or removed; only data rows are affected. Note for large instances: this migration issues a single unbatched delete that scans the entirety of <code>threadmemberships</code> with a join against <code>threads</code> and <code>channelmembers</code>. On databases with tens of millions of rows or significant historical channel-membership churn, this query may run for an extended period, block autovacuum on <code>threadmemberships</code>, increase WAL pressure, and contribute to replication lag. Administrators of large deployments should test execution time on a representative dataset before upgrading and consider scheduling the upgrade during a low-traffic window. The down migration contains no rollback SQL because the deleted rows cannot be recovered; this migration is irreversible. The migrations are fully backwards-compatible and no database downtime is expected for this upgrade. The SQL queries included are:</p><pre><code>-- Drop ThreadMembership rows whose user is no longer a member of the thread's channel.

docs/main/end-user-guide/agents.mdx

@@ -1,9 +1,11 @@
 ---
 title: "AI Agents"
 ---
+import AgentsUserGuideBody from '../agents/docs/_user_guide_partial.mdx';
+
 <PlanAvailability slug="all-commercial" />
 
-{/* TODO: include /agents/docs/user_guide.md could not be resolved */}
+<AgentsUserGuideBody />
 
 <Note>
 

docs/main/product-overview/mattermost-v11-changelog.mdx

@@ -437,7 +437,7 @@ See [this blog post](https://mattermost.com/blog/mattermost-v11-8-0-is-now-avail
 
 **Breaking Changes**
  - FIPS builds require a minimum of 14 characters for passwords, atmos/camo proxy configuration, and shared channel secrets. Shorter passwords for existing users will no longer be valid and require a password reset. Non-FIPS builds are unaffected.
- - v11.7 includes Agents plugin v2. Please see [this guide](https://github.com/mattermost/mattermost-plugin-agents/blob/master/docs/upgrading_to_2.0.md) on how to upgrade the Mattermost Agents plugin from a v1.x release to v2.0.0. It covers the supported version path, the migrations that run automatically on first start of v2.0.0, the breaking changes and default-behavior flips that admins should know about before the upgrade window, and the verification steps to confirm the upgrade succeeded.
+ - v11.7 includes Agents plugin v2. Please see [this guide](/agents/docs/upgrading_to_2.0) on how to upgrade the Mattermost Agents plugin from a v1.x release to v2.0.0. It covers the supported version path, the migrations that run automatically on first start of v2.0.0, the breaking changes and default-behavior flips that admins should know about before the upgrade window, and the verification steps to confirm the upgrade succeeded.
 
 </Important>
 

docs/site/README.md

@@ -83,6 +83,38 @@ leaving it at the root.
 existing one (Integrations Guide is the simplest example), then wire it
 into `main()` alongside the existing `dir === '...'` checks.
 
+**Nesting a doc from one section under a page in another section:** most
+group `items` are plain basenames relative to that section's own
+directory, but `buildAdminConfigureItem` also accepts `{doc: '<full id>'}`
+for cross-directory references (their label is read directly from the
+target file's frontmatter via `docLabelById`, since it won't be in that
+section's `leafLabels` map). This is how `ADMIN_CONFIGURE_GROUPS.agents`
+nests the vendored Agents plugin pages (`main/agents/docs/`, staged by
+`stage-agents-docs.mjs` — not one of the `TOP_LEVEL` sections, so it has
+no top-level nav entry of its own) under
+`administration-guide/configure/agents-admin-guide`. The same page is
+also nested for End User Guide's `end-user-guide/agents` doc, but since
+that section has no manual grouping override at all, it uses the smaller
+standalone `promoteDocToCategory` helper instead of a full `*_GROUPS`
+override — copy that pattern for other one-off single-doc nestings rather
+than building a whole grouping override for a section that's otherwise
+fine auto-generated.
+
+**Inlining another doc's content onto a page** (rather than just linking
+or nesting it): Docusaurus's built-in [Markdown
+partials](https://docusaurus.io/docs/next/create-doc#markdown-partials)
+feature — any `.md`/`.mdx` file with a leading underscore in its name is
+excluded from the docs plugin's routing/sidebars and can be `import`ed
+into another MDX file and rendered as `<Component />`. `stage-agents-docs.mjs`
+uses this to reproduce Sphinx's `.. include:: /agents/docs/admin_guide.md`
+behavior: it stages `admin_guide.md`/`user_guide.md` as normal (but
+`unlisted: true`) docs for direct-link parity, *and* as
+`_admin_guide_partial.mdx`/`_user_guide_partial.mdx` partials that
+`administration-guide/configure/agents-admin-guide.mdx` and
+`end-user-guide/agents.mdx` import and render inline — so those two pages
+show the full vendored guide content directly, with zero extra clicks,
+instead of just linking out to a separate page.
+
 The API reference section (`docs/api/reference/`, also gitignored) has the
 same requirement: `docusaurus-plugin-openapi-docs` needs `docusaurus
 gen-api-docs mattermost` run before it has any pages to render. `prestart`

docs/site/package.json

@@ -6,12 +6,13 @@
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
     "build": "docusaurus build",
+    "stage:agents-docs": "node scripts/stage-agents-docs.mjs",
     "build:sidebars": "node scripts/gen-documentation-sidebar.mjs && node scripts/gen-developer-sidebar.mjs",
     "build:openapi:spec": "node scripts/build-openapi.mjs",
     "build:openapi:docs": "docusaurus gen-api-docs mattermost",
     "build:openapi": "npm run build:openapi:spec && npm run build:openapi:docs",
-    "prestart": "npm run build:sidebars && ( [ -f openapi/mattermost-openapi-v4.yaml ] || npm run build:openapi:spec ) && npm run build:openapi:docs",
-    "prebuild": "npm run build:sidebars && npm run build:openapi",
+    "prestart": "npm run stage:agents-docs && npm run build:sidebars && ( [ -f openapi/mattermost-openapi-v4.yaml ] || npm run build:openapi:spec ) && npm run build:openapi:docs",
+    "prebuild": "npm run stage:agents-docs && npm run build:sidebars && npm run build:openapi",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",

docs/site/scripts/gen-documentation-sidebar.mjs

@@ -56,7 +56,6 @@ const TOP_LEVEL = [
   {dir: 'end-user-guide',       label: 'End User Guide'},
   {dir: 'integrations-guide',   label: 'Integrations Guide'},
   {dir: 'get-help',             label: 'Get Help'},
-  {dir: 'agents',               label: 'Agents'},
 ];
 
 // ---------------------------------------------------------------------------
@@ -380,6 +379,23 @@ const ADMIN_CONFIGURE_GROUPS = {
       'optimize-your-workspace',
     ],
   },
+  // Nests the Agents plugin's own provider/setup pages (vendored from the
+  // mattermost-plugin-agents submodule, staged by stage-agents-docs.mjs
+  // into main/agents/docs/) under the admin guide landing page, instead of
+  // a standalone top-level "Agents" section — mirrors Sphinx, which hides
+  // these behind a small toctree on administration-guide/configure/
+  // agents-admin-guide.rst rather than giving Agents its own nav entry.
+  // Items use the {doc: '<full id>'} form since they live outside
+  // administration-guide/configure/.
+  agents: {
+    label: 'AI Agents Configuration',
+    landing: 'agents-admin-guide',
+    items: [
+      {doc: 'agents/docs/providers'},
+      {doc: 'agents/docs/aws_bedrock_setup'},
+      {doc: 'agents/docs/sovereign_ai'},
+    ],
+  },
 };
 
 // Top-level Configure order. Strings are doc basenames relative to
@@ -389,7 +405,7 @@ const ADMIN_CONFIGURE_GROUPS = {
 const ADMIN_CONFIGURE_ORDER = [
   {group: 'settingsReference'},
   {group: 'search'},
-  'agents-admin-guide',
+  {group: 'agents'},
   {group: 'calls'},
   {group: 'storage'},
   {group: 'email'},
@@ -903,11 +919,28 @@ function buildDeploymentSidebar(autoCat) {
 // Administration Guide — builder (regroups the "Configure" sub-category).
 // ---------------------------------------------------------------------------
 
+// Resolves the label for a fully-qualified doc id (one that lives outside
+// the section currently being built, e.g. an Agents doc nested under
+// Administration Guide → Configure) by reading its own frontmatter
+// directly, since it won't be present in that section's `leafLabels` map.
+function docLabelById(id) {
+  for (const ext of ['.mdx', '.md']) {
+    const abs = join(SRC, `${id}${ext}`);
+    if (existsSync(abs)) {
+      return readFm(abs, 'sidebar_label') || readFm(abs, 'title') || humanize(id.split('/').pop());
+    }
+  }
+  throw new Error(`doc id not found on disk: ${id}`);
+}
+
 function buildAdminConfigureItem(spec, leafLabels) {
   if (typeof spec === 'string') {
     const id = `administration-guide/configure/${spec}`;
     return {type: 'doc', id, label: leafLabels[id] || humanize(spec)};
   }
+  if (spec.doc) {
+    return {type: 'doc', id: spec.doc, label: docLabelById(spec.doc)};
+  }
   const g = ADMIN_CONFIGURE_GROUPS[spec.group];
   if (!g) throw new Error(`unknown admin configure group: ${spec.group}`);
   const items = g.items.map((it) => buildAdminConfigureItem(it, leafLabels));
@@ -1092,6 +1125,46 @@ function buildIntegrationsSidebar(autoCat) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// End User Guide — nests the Agents plugin's usage-tips page under the
+// existing "AI Agents" doc, the same way Configure nests Agents' admin-side
+// pages (see ADMIN_CONFIGURE_GROUPS.agents above). End User Guide is
+// otherwise fully filesystem-driven, so this is a narrow, targeted
+// promotion rather than a full manual-grouping override.
+// ---------------------------------------------------------------------------
+
+// Finds the {type: 'doc', id: docId} leaf anywhere in `items` and replaces
+// it in place with a category that links to that same doc and nests
+// `children` (each a fully-qualified doc id) underneath it. Returns true if
+// the promotion was applied, so callers can warn when it wasn't.
+function promoteDocToCategory(items, docId, children) {
+  for (let i = 0; i < items.length; i++) {
+    const it = items[i];
+    if (it.type === 'doc' && it.id === docId) {
+      items[i] = {
+        type: 'category',
+        label: it.label,
+        collapsed: true,
+        link: {type: 'doc', id: docId},
+        items: children.map((childId) => ({type: 'doc', id: childId, label: docLabelById(childId)})),
+      };
+      return true;
+    }
+    if (it.type === 'category' && it.items && promoteDocToCategory(it.items, docId, children)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function buildEndUserGuideSidebar(autoCat) {
+  const promoted = promoteDocToCategory(autoCat.items, 'end-user-guide/agents', ['agents/docs/usage_tips']);
+  if (!promoted) {
+    console.warn('[sidebar] WARN: End User Guide "agents" doc not found — Agents usage-tips nesting was not applied.');
+  }
+  return autoCat;
+}
+
 // ---------------------------------------------------------------------------
 // Entry point.
 // ---------------------------------------------------------------------------
@@ -1115,6 +1188,8 @@ function main() {
       cat = buildAdminGuideSidebar(cat);
     } else if (dir === 'integrations-guide') {
       cat = buildIntegrationsSidebar(cat);
+    } else if (dir === 'end-user-guide') {
+      cat = buildEndUserGuideSidebar(cat);
     }
     sidebar.push(cat);
   }