chore: Upgrade Docusaurus from 3.6.3 to 3.9.2

website/blog/2025-12-31-ask-ai-search.mdx

@@ -0,0 +1,57 @@
+---
+slug: ask-ai-search
+title: "Introducing Ask AI: Conversational Search for Atmos Documentation"
+authors:
+  - osterman
+tags:
+  - feature
+  - documentation
+---
+
+We're excited to announce **Ask AI**, an AI-powered conversational search feature now available on [atmos.tools](https://atmos.tools). Instead of just searching for keywords, you can now ask natural language questions about Atmos and get intelligent, contextual answers drawn directly from the documentation.
+
+<!-- truncate -->
+
+## What is Ask AI?
+
+Ask AI is powered by [Algolia DocSearch v4](https://docsearch.algolia.com/docs/v4/askai/) and brings conversational AI directly into the documentation search experience. When you open the search dialog (press `/` or `Cmd+K`), you can seamlessly switch between traditional keyword search and a chat-style assistant that understands your questions.
+
+**Key features:**
+
+- **Natural language queries** - Ask questions like "How do I configure AWS SSO authentication?" or "What's the difference between stacks and components?"
+- **Contextual answers** - Responses are generated from the actual documentation content, not generic AI knowledge
+- **Source citations** - Every answer includes links to the specific documentation pages it drew from
+- **Seamless experience** - Switch between keyword search and AI assistant without leaving the search dialog
+
+## How It Works
+
+Ask AI uses Algolia's integration with large language models (LLMs) to understand your questions and find relevant information from the indexed documentation. The assistant is specifically trained on Atmos documentation, so it understands:
+
+- Atmos CLI commands and their flags
+- Stack configuration patterns and YAML syntax
+- Authentication providers and identity management
+- Workflows, custom commands, and extensibility patterns
+- Design patterns and best practices
+
+## Try It Now
+
+Visit [atmos.tools](https://atmos.tools) and press `/` or `Cmd+K` to open the search dialog. Try asking questions like:
+
+- "How do I set up AWS SSO with Atmos?"
+- "What is the difference between imports and inheritance?"
+- "How do I create a custom workflow?"
+- "What YAML functions are available?"
+
+The AI assistant will provide detailed answers with direct links to the relevant documentation pages.
+
+## Technical Details
+
+This feature is enabled by upgrading to Docusaurus 3.9.2 and DocSearch v4, which adds native support for Algolia's Ask AI feature. The assistant is configured with an understanding of Atmos as a DevOps and cloud automation tool, ensuring responses are relevant and technically accurate.
+
+## Get Involved
+
+Have feedback on Ask AI? We'd love to hear how it's helping you navigate the documentation:
+
+- [Open an issue](https://github.com/cloudposse/atmos/issues) for bugs or feature requests
+- [Join our Slack](https://slack.cloudposse.com/) to discuss with the community
+- [Star the repo](https://github.com/cloudposse/atmos) if you find Atmos helpful

website/docusaurus.config.js

@@ -492,7 +492,15 @@ const config = {
                 appId: process.env.ALGOLIA_APP_ID || '32YOERUX83',
                 apiKey: process.env.ALGOLIA_SEARCH_API_KEY || '557985309adf0e4df9dcf3cb29c61928', // this is SEARCH ONLY API key and is not sensitive information
                 indexName: process.env.ALGOLIA_INDEX_NAME || 'atmos.tools',
-                contextualSearch: false
+                contextualSearch: false,
+                // DocSearch v4 Ask AI integration
+                // https://docsearch.algolia.com/docs/v4/askai/
+                askAi: {
+                    assistantId: process.env.ALGOLIA_ASKAI_ASSISTANT_ID || 'xzgtsIXZSf7V',
+                    appId: process.env.ALGOLIA_APP_ID || '32YOERUX83',
+                    apiKey: process.env.ALGOLIA_SEARCH_API_KEY || '557985309adf0e4df9dcf3cb29c61928',
+                    indexName: process.env.ALGOLIA_INDEX_NAME || 'atmos.tools',
+                }
             },
             zoom: {
                 selector: '.markdown :not(em) > img',

website/package.json

@@ -17,13 +17,14 @@
     "build:site": "npm run build"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.6.3",
-    "@docusaurus/plugin-client-redirects": "^3.6.3",
-    "@docusaurus/plugin-content-blog": "^3.6.3",
-    "@docusaurus/plugin-google-tag-manager": "^3.6.3",
-    "@docusaurus/preset-classic": "^3.6.3",
-    "@docusaurus/theme-common": "^3.6.3",
-    "@docusaurus/theme-mermaid": "^3.6.3",
+    "@docsearch/react": "^4.2.0",
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/plugin-client-redirects": "^3.9.2",
+    "@docusaurus/plugin-content-blog": "^3.9.2",
+    "@docusaurus/plugin-google-tag-manager": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
+    "@docusaurus/theme-common": "^3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
     "@excalidraw/excalidraw": "^0.17.6",
     "@fortawesome/fontawesome-svg-core": "^6.7.2",
     "@fortawesome/free-brands-svg-icons": "^6.7.2",
@@ -58,7 +59,7 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.6.3",
+    "@docusaurus/module-type-aliases": "^3.9.2",
     "prettier": "^3.4.2"
   },
   "browserslist": {