add mention of conda-store default mapping

Author: viniciusdc

docs/docs/how-tos/fine-grained-permissions.mdx

@@ -340,6 +340,32 @@ role-mappings](https://conda.store/conda-store/explanations/conda-store-concepts
 
 </div>
 
+:::note Conda-Store defaults and Nebari’s internal group handling
+Nebari grants some Conda-Store permissions **automatically**, regardless of how your
+Keycloak groups are configured. The authentication class applies these defaults at
+login so users can work even if the Keycloak groups don’t define any `conda_store_*`
+client roles.
+
+**What Nebari applies by default**
+- **Personal namespace** → always **admin**
+  `"{username}/*" → {"admin"}` (cannot be downgraded by scopes).
+- **Deployment default namespace** → **viewer**
+  `"{default_namespace}/*" → {"viewer"}`.
+- **Nebari default groups** (`analyst`, `developer`, `admin`) → **[handled internally](https://github.com/nebari-dev/nebari/blob/main/src/_nebari/stages/kubernetes_services/template/modules/kubernetes/services/conda-store/config/conda_store_config.py#L105)**
+  If a user is in one of these groups, Nebari binds a **same-named namespace** to the
+  user with that group’s effective Conda-Store role (e.g., group `analyst` ⇒ `analyst/*`),
+  **even when the Keycloak group itself has no client roles**.
+- **SuperAdmin** (`conda_store_superadmin`) → full wildcard
+  `"*/*" → {"admin"}` (includes delete & service-token privileges).
+
+**How it reconciles with Keycloak scopes**
+- On each login, Nebari **removes non-default bindings** and re-applies permissions from
+  Keycloak role **scopes** (e.g., `admin!namespace=analyst`).
+- If multiple grants target the same namespace, the **highest** permission wins.
+- Order of precedence (highest → lowest): **SuperAdmin** → **explicit scopes** → **internal defaults**.
+- Changes take effect after the user signs in again.
+:::
+
 ### Creating a Role
 
 In the following example, we create a new role for the `JupyterHub` client granting the

docs/src/theme/TOCItems/Tree.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import type { Props } from '@theme/TOCItems/Tree';
+
+function TOCItemTree({
+  toc,
+  className,
+  linkClassName,
+  isChild,
+}: Props): JSX.Element | null {
+  if (!toc.length) {
+    return null;
+  }
+
+  return (
+    <ul className={isChild ? undefined : className}>
+      {toc.map((heading) => {
+        // Parse the heading ID to check if it has "provider::actualId"
+        let providerQuery = null;
+        let actualId = heading.id;
+
+        if (heading.id.includes('::')) {
+          const [provider, ...rest] = heading.id.split('::');
+          providerQuery = provider;
+          actualId = rest.join('::'); // In case there's more than one '::', join back the rest.
+        }
+
+        // If a provider is found, build the URL with the query param
+        const linkHref = providerQuery
+          ? `?provider=${providerQuery}#${heading.id}`
+          : `#${heading.id}`;
+
+        return (
+          <li key={heading.id}>
+            <Link
+              to={linkHref}
+              className={linkClassName ?? undefined}
+              // Developer provided the HTML, so assume it's safe.
+              dangerouslySetInnerHTML={{ __html: heading.value }}
+            />
+            <TOCItemTree
+              isChild
+              toc={heading.children}
+              className={className}
+              linkClassName={linkClassName}
+            />
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+export default React.memo(TOCItemTree);

docs/src/theme/TOCItems/index.tsx

@@ -0,0 +1,54 @@
+import React, {useMemo} from 'react';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import {
+  useTOCHighlight,
+  useFilteredAndTreeifiedTOC,
+  type TOCHighlightConfig,
+} from '@docusaurus/theme-common/internal';
+import TOCItemTree from '@theme/TOCItems/Tree';
+import type {Props} from '@theme/TOCItems';
+
+export default function TOCItems({
+  toc,
+  className = 'table-of-contents table-of-contents__left-border',
+  linkClassName = 'table-of-contents__link',
+  linkActiveClassName = undefined,
+  minHeadingLevel: minHeadingLevelOption,
+  maxHeadingLevel: maxHeadingLevelOption,
+  ...props
+}: Props): JSX.Element | null {
+  const themeConfig = useThemeConfig();
+
+  const minHeadingLevel =
+    minHeadingLevelOption ?? themeConfig.tableOfContents.minHeadingLevel;
+  const maxHeadingLevel =
+    maxHeadingLevelOption ?? themeConfig.tableOfContents.maxHeadingLevel;
+
+  const tocTree = useFilteredAndTreeifiedTOC({
+    toc,
+    minHeadingLevel,
+    maxHeadingLevel,
+  });
+
+  const tocHighlightConfig: TOCHighlightConfig | undefined = useMemo(() => {
+    if (linkClassName && linkActiveClassName) {
+      return {
+        linkClassName,
+        linkActiveClassName,
+        minHeadingLevel,
+        maxHeadingLevel,
+      };
+    }
+    return undefined;
+  }, [linkClassName, linkActiveClassName, minHeadingLevel, maxHeadingLevel]);
+  useTOCHighlight(tocHighlightConfig);
+
+  return (
+    <TOCItemTree
+      toc={tocTree}
+      className={className}
+      linkClassName={linkClassName}
+      {...props}
+    />
+  );
+}