diff --git a/docs/_layouts/latest-release-feature.html b/docs/_layouts/latest-release-feature.html
index 38a7b88a..c089af3e 100644
--- a/docs/_layouts/latest-release-feature.html
+++ b/docs/_layouts/latest-release-feature.html
@@ -96,5 +96,5 @@ <h5 class="modal-title mb-1" id="latestFeatureImageModalLabel">Latest Feature Pr
 </article>
 
 {% if feature_meta.images and feature_meta.images.size > 0 %}
-<script src="{{ '/assets/js/latest-release.js' | relative_url }}"></script>
+<script src="{{ '/assets/js/latest-release.js' | relative_url }}?v={{ site.time | date: '%s' }}"></script>
 {% endif %}
diff --git a/docs/_layouts/showcase-page.html b/docs/_layouts/showcase-page.html
new file mode 100644
index 00000000..f96eb4ae
--- /dev/null
+++ b/docs/_layouts/showcase-page.html
@@ -0,0 +1,122 @@
+---
+layout: default
+---
+
+{% assign accent = page.accent | default: 'blue' %}
+
+<article class="page-content latest-release-page docs-showcase-page latest-release-accent--{{ accent }}">
+  <section class="latest-release-hero">
+    <div class="latest-release-hero-copy">
+      {% if page.breadcrumb and page.breadcrumb.url and page.breadcrumb.label %}
+        <div class="latest-release-breadcrumb">
+          <a href="{{ page.breadcrumb.url | relative_url }}"><i class="bi bi-arrow-left"></i> {{ page.breadcrumb.label }}</a>
+        </div>
+      {% endif %}
+
+      {% if page.eyebrow or page.hero_version %}
+        <div class="latest-release-pill-row">
+          {% if page.eyebrow %}
+            <span class="latest-release-pill">{{ page.eyebrow }}</span>
+          {% endif %}
+          {% if page.hero_version %}
+            <span class="latest-release-subtle">{{ page.hero_version }}</span>
+          {% endif %}
+        </div>
+      {% endif %}
+
+      <h1 class="latest-release-hero-title">{{ page.title }}</h1>
+
+      {% if page.description %}
+        <p class="latest-release-hero-description">{{ page.description }}</p>
+      {% endif %}
+
+      {% if page.hero_pills %}
+        <div class="latest-release-pill-row">
+          {% for pill in page.hero_pills %}
+            <span class="latest-release-pill">{{ pill }}</span>
+          {% endfor %}
+        </div>
+      {% endif %}
+
+      {% if page.hero_links %}
+        <div class="latest-release-hero-actions">
+          {% for link in page.hero_links %}
+            {% assign button_class = 'btn-outline-secondary' %}
+            {% if link.style == 'primary' %}
+              {% assign button_class = 'btn-primary' %}
+            {% elsif link.style == 'secondary' %}
+              {% assign button_class = 'btn-secondary' %}
+            {% endif %}
+            <a href="{{ link.url | relative_url }}" class="btn {{ button_class }} btn-sm">{{ link.label }}</a>
+          {% endfor %}
+        </div>
+      {% endif %}
+    </div>
+
+    <div class="latest-release-hero-art" aria-hidden="true">
+      {% if page.hero_icons and page.hero_icons.size > 1 %}
+        <div class="latest-release-hero-stack">
+          {% for icon in page.hero_icons limit: 3 %}
+            <span><i class="bi {{ icon }}"></i></span>
+          {% endfor %}
+        </div>
+      {% else %}
+        {% assign hero_icon = page.hero_icon %}
+        {% if hero_icon == nil and page.hero_icons and page.hero_icons.size > 0 %}
+          {% assign hero_icon = page.hero_icons[0] %}
+        {% endif %}
+        <div class="latest-release-icon-orb">
+          <i class="bi {{ hero_icon | default: 'bi-stars' }}"></i>
+        </div>
+      {% endif %}
+    </div>
+  </section>
+
+  <div class="latest-release-feature-content">
+    <div class="latest-release-rich-content">
+      {{ content }}
+    </div>
+
+    {% if page.show_nav and page.nav_links %}
+      <nav class="page-navigation mt-5">
+        <div class="row">
+          {% if page.nav_links.prev %}
+            <div class="col-md-6">
+              <a href="{{ page.nav_links.prev.url | relative_url }}" class="btn btn-outline-primary">
+                <i class="bi bi-arrow-left me-2"></i>{{ page.nav_links.prev.title }}
+              </a>
+            </div>
+          {% endif %}
+          {% if page.nav_links.next %}
+            <div class="col-md-6 text-end">
+              <a href="{{ page.nav_links.next.url | relative_url }}" class="btn btn-outline-primary">
+                {{ page.nav_links.next.title }}<i class="bi bi-arrow-right ms-2"></i>
+              </a>
+            </div>
+          {% endif %}
+        </div>
+      </nav>
+    {% endif %}
+  </div>
+
+  <div class="modal fade latest-feature-image-modal" id="latestFeatureImageModal" tabindex="-1" aria-labelledby="latestFeatureImageModalLabel" aria-hidden="true">
+    <div class="modal-dialog modal-dialog-centered modal-xl">
+      <div class="modal-content">
+        <div class="modal-header">
+          <div>
+            <h5 class="modal-title mb-1" id="latestFeatureImageModalLabel">Image Preview</h5>
+            <small class="latest-feature-image-modal-caption" id="latestFeatureImageModalCaption">Click outside the popup to close it.</small>
+          </div>
+          <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+        </div>
+        <div class="modal-body pt-2">
+          <div class="latest-feature-image-frame">
+            <img id="latestFeatureImageModalImage" src="" alt="Image preview" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</article>
+
+<script src="{{ '/assets/js/latest-release.js' | relative_url }}?v={{ site.time | date: '%s' }}"></script>
\ No newline at end of file
diff --git a/docs/about.md b/docs/about.md
index 8b4e0b28..d432ece8 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -1,18 +1,97 @@
 ---
-layout: page
-title: About
+layout: showcase-page
+title: "About Simple Chat"
 permalink: /about/
+menubar: docs_menu
+accent: teal
+eyebrow: "Platform Overview"
+description: "Simple Chat combines Azure-hosted chat, grounded retrieval, workspace management, and optional agent orchestration into one application surface."
+hero_icons:
+  - bi-chat-square-text
+  - bi-database
+  - bi-diagram-3
+hero_pills:
+  - Azure-native by design
+  - Workspace-first document grounding
+  - Optional agents and automation
+hero_links:
+  - label: Start with setup
+    url: /setup_instructions/
+    style: primary
+  - label: Explore features
+    url: /features/
+    style: secondary
 ---
 
-This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/)
+Simple Chat is an enterprise-ready Flask application for teams that want conversational AI grounded in their own data, with admin controls that stay practical instead of sprawling.
 
-You can find the source code for Minima at GitHub:
-[jekyll][jekyll-organization] /
-[minima](https://github.com/jekyll/minima)
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-chat-square-text"></i></div>
+		<h2>Grounded Chat</h2>
+		<p>Users can chat directly with models or switch into retrieval-backed conversations that cite files from personal, group, or public workspaces.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-folder2-open"></i></div>
+		<h2>Document Workflows</h2>
+		<p>Uploads are processed through document extraction, chunking, embeddings, and search so teams can move from raw files to usable retrieval quickly.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-sliders"></i></div>
+		<h2>Admin Control Surface</h2>
+		<p>Admins configure branding, models, workspaces, search, safety, logging, and scale features from one settings experience.</p>
+	</article>
+</section>
 
-You can find the source code for Jekyll at GitHub:
-[jekyll][jekyll-organization] /
-[jekyll](https://github.com/jekyll/jekyll)
+<div class="latest-release-note-panel">
+	<h2>What the docs are optimized for</h2>
+	<p>The documentation is organized to help with three common paths: deploy the platform, configure the services behind it, and teach end users how to get value from workspaces, search, and agents.</p>
+</div>
 
+## Follow the right path
 
-[jekyll-organization]: https://github.com/jekyll
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-rocket-takeoff"></i></div>
+		<h2>Deploy</h2>
+		<p>Use the guided deployment path if you want the fastest route into a working environment.</p>
+		<p><a href="{{ '/setup_instructions/' | relative_url }}">Open Getting Started</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-grid-1x2"></i></div>
+		<h2>Understand capabilities</h2>
+		<p>Review how chat, workspaces, safety, citations, multimedia, and agents fit together before expanding the deployment.</p>
+		<p><a href="{{ '/features/' | relative_url }}">Browse the feature map</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-gear"></i></div>
+		<h2>Operate and tune</h2>
+		<p>Use the admin, workflow, scaling, and troubleshooting guides when the platform moves from proof of concept into production support.</p>
+		<p><a href="{{ '/application_scaling/' | relative_url }}">Review scaling guidance</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-mortarboard"></i></div>
+		<h2>Teach the team</h2>
+		<p>The tutorial track is written for people who need to go from first login to useful document-grounded chat without reading every reference page first.</p>
+		<p><a href="{{ '/tutorials/' | relative_url }}">Open tutorials</a></p>
+	</article>
+</section>
+
+## Built as an open repo
+
+The project lives in the open and includes application code, deployment assets, functional tests, UI tests, and deep change documentation under the docs tree.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-github"></i></div>
+		<h2>Source and contribution flow</h2>
+		<p>Contributors can inspect the application, deployment scripts, docs site, and supporting tools in one repository.</p>
+		<p><a href="{{ '/contributing/' | relative_url }}">Read contribution guidance</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-journal-text"></i></div>
+		<h2>Release-by-release traceability</h2>
+		<p>Feature explanations, fixes, and release notes are captured inside the docs site so changes remain searchable after deployment work is done.</p>
+		<p><a href="{{ '/explanation/release_notes/' | relative_url }}">Review release notes</a></p>
+	</article>
+</section>
diff --git a/docs/admin_configuration.md b/docs/admin_configuration.md
index 40a56572..e584a581 100644
--- a/docs/admin_configuration.md
+++ b/docs/admin_configuration.md
@@ -1,10 +1,59 @@
-# Simple Chat - Admin Configuration
-
-[Return to Main](../README.md)
-
-Once the application is running and you log in as a user assigned the Admin role, you can access the **Admin Settings** page. This UI provides a centralized location to configure most application features and service connections.
-
-![alt text](./images/admin_settings_page.png)
+---
+layout: showcase-page
+title: Admin Configuration
+permalink: /admin_configuration/
+menubar: docs_menu
+accent: violet
+eyebrow: Central Control Surface
+description: Admin Settings turns a raw deployment into an operating environment by centralizing branding, model routing, workspace policy, safety controls, scale features, and logging.
+hero_icons:
+  - bi-gear
+  - bi-sliders2-vertical
+  - bi-shield-check
+hero_pills:
+  - Guided setup walkthrough included
+  - Model and workspace configuration in one UI
+  - Logging, safety, and scale controls available
+hero_links:
+  - label: Getting started guide
+    url: /setup_instructions/
+    style: primary
+  - label: Manual setup reference
+    url: /setup_instructions_manual/
+    style: secondary
+---
+
+Once the application is running and you sign in with the Admin role, the Admin Settings page becomes the main place to configure the product without editing environment variables directly.
+
+<section class="latest-release-card-grid">
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-brush"></i></div>
+    <h2>General</h2>
+    <p>Brand the app, tune appearance, manage landing-page content, and control global behavior such as file limits and system prompts.</p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-cpu"></i></div>
+    <h2>Models and retrieval</h2>
+    <p>Configure GPT, embeddings, image generation, Azure AI Search, Document Intelligence, and enhanced citations from the same settings surface.</p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-people"></i></div>
+    <h2>Workspaces and agents</h2>
+    <p>Enable personal, group, and public workspaces, define classification behavior, and manage agent and action capabilities.</p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-speedometer"></i></div>
+    <h2>Safety, scale, and logging</h2>
+    <p>Turn on Content Safety, Redis, Front Door, Application Insights logging, and other controls that matter once the deployment grows up.</p>
+  </article>
+</section>
+
+<div class="latest-release-note-panel">
+  <h2>Best starting point</h2>
+  <p>The Setup Walkthrough is the fastest way to move a fresh environment from partially configured to usable. It guides admins through the critical dependencies in the right order and skips steps that do not apply.</p>
+</div>
+
+![Admin Settings page](./images/admin_settings_page.png)
 
 ## Setup Walkthrough
 
diff --git a/docs/application_scaling.md b/docs/application_scaling.md
index 956b5d60..ad21e207 100644
--- a/docs/application_scaling.md
+++ b/docs/application_scaling.md
@@ -1,98 +1,109 @@
-# Simple Chat - Application Scaling
-
-- [Azure App Service](#azure-app-service)
-- [Azure Cosmos DB](#azure-cosmos-db)
-- [Azure AI Search](#azure-ai-search)
-- [Azure AI Cognitive Services](#azure-ai--cognitive-services-openai-document-intelligence-etc)
-- [Return to Main](../README.md)
-
-**General Scaling Principle:** Monitor key performance metrics (CPU/memory utilization, request latency, queue lengths, RU consumption, query latency, rate limit responses) for all services using **Azure Monitor** and **Application Insights**. Use these metrics to make informed decisions about when and how to scale each component.
-
-As user load, data volume, or feature usage increases, you will need to scale the underlying Azure resources to maintain performance and availability. Here’s a breakdown of scaling strategies for the key components:
+---
+layout: showcase-page
+title: "Application Scaling"
+permalink: /application_scaling/
+menubar: docs_menu
+accent: cyan
+eyebrow: "Operate With Headroom"
+description: "Scale Simple Chat by measuring pressure in the web tier, the data plane, the retrieval plane, and the AI services that sit behind them."
+hero_icons:
+  - bi-graph-up-arrow
+  - bi-arrows-expand
+  - bi-speedometer2
+hero_pills:
+  - Monitor first
+  - Scale the bottleneck you can prove
+  - Keep sessions and retrieval consistent
+hero_links:
+  - label: Review setup guidance
+    url: /setup_instructions/
+    style: primary
+  - label: Manual setup details
+    url: /setup_instructions_manual/
+    style: secondary
+---
+
+As load grows, Simple Chat usually hits one of four pressure points first: the App Service web tier, Cosmos DB throughput, Azure AI Search capacity, or rate limits on AI services. Treat each one independently so you do not pay to over-scale the wrong component.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-window-stack"></i></div>
+        <h2>App Service</h2>
+        <p>Scale up when single requests need more memory or CPU. Scale out when concurrent users, long chats, and upload traffic rise.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-database"></i></div>
+        <h2>Cosmos DB</h2>
+        <p>Watch RU consumption and move to container-level autoscale for the busiest containers so chat and document traffic do not fight each other.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-search"></i></div>
+        <h2>Azure AI Search</h2>
+        <p>Replicas lift query throughput, partitions lift storage and indexing throughput, and higher tiers raise the service ceiling when S1 runs out.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-cpu"></i></div>
+        <h2>AI Services</h2>
+        <p>OpenAI, Document Intelligence, Speech, Content Safety, and Video Indexer are usually quota-driven. Route them through APIM if you need retries, load balancing, or consistent policy enforcement.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>General scaling principle</h2>
+    <p>Use Azure Monitor and Application Insights to decide when to scale. Track CPU and memory, request latency, queue depth, RU consumption, search query latency, and rate-limit responses before changing service sizes.</p>
+</div>
 
 ## Azure App Service
 
-> <a href="#simple-chat---application-scaling" style="text-decoration: none;">Return to top</a>
-
-The App Service hosts the Python backend application.
+The App Service hosts the Python backend and is the first place to look when the UI feels slow or request concurrency rises.
 
-*   **Vertical Scaling (Scale Up):**
-    *   **What:** Increasing the resources (CPU, RAM, Storage) allocated to each instance running your application.
-    *   **How:** Change the App Service Plan pricing tier (e.g., move from P0v3 to P1v3, P2v3, etc.).
-    *   **When:** Useful if individual requests are resource-intensive or if a single instance needs more power to handle its share of the load.
-    *   **Simple Chat Support:** **Supported.** The application benefits directly from more powerful instances.
-
-*   **Horizontal Scaling (Scale Out):**
-    *   **What:** Increasing the number of instances running your application. Traffic is load-balanced across these instances.
-    *   **How:** Adjust the "Instance count" slider in the App Service Plan's "Scale out (App Service plan)" settings, or configure Autoscale rules based on metrics (CPU percentage, memory usage, request queue length).
-    *   **When:** Essential for handling higher numbers of concurrent users and improving availability.
-    *   **Simple Chat Support:** **Fully Supported.**
-        *   With the integration of **Azure Cache for Redis** as a distributed session backend, Simple Chat now supports true horizontal scaling. User sessions are no longer tied to a single app instance, allowing seamless load balancing and high availability across multiple instances.
-        *   **Best Practice:** Enable Redis Cache and configure the application to use it for session storage before scaling out. This ensures consistent user experience and prevents authentication issues.
-        *   **Reference:** See [Setup Instructions](#setup-instructions) for details on deploying and configuring Azure Cache for Redis.
+- Scale up by moving the App Service Plan to a larger SKU when individual requests are memory-heavy or CPU-heavy.
+- Scale out by increasing instance count or using autoscale when you need more concurrent request capacity.
+- Enable Redis-backed session storage before serious horizontal scaling so user sessions are not pinned to a single instance.
+- Treat Redis as a prerequisite for clean high-availability behavior, not as an afterthought.
 
 ## Azure Cosmos DB
 
-> <a href="#simple-chat---application-scaling" style="text-decoration: none;">Return to top</a>
-
-Cosmos DB stores metadata, conversations, settings, etc. Scaling focuses on Request Units per second (RU/s) and global distribution.
+Cosmos DB stores settings, conversation history, document metadata, and related operational records. The core scaling lever is RU/s.
 
-*   **Throughput Scaling (RU/s):**
-    *   **Autoscale:** The recommended approach. You set a *maximum* RU/s value, and Cosmos DB automatically scales the provisioned throughput between 10% and 100% of that maximum based on real-time usage. This helps manage costs while ensuring performance.
-    *   **Database vs. Container Throughput:** You can set Autoscale throughput at the database level (shared by all containers) or, preferably, at the **individual container level**.
-    *   **Recommendations:**
-        *   Set **Max throughput** at the database level initially (e.g., 1000 RU/s) during setup.
-        *   **Configure Container-Level Autoscale (Post-Setup):** For optimal performance, set maximum Autoscale RU/s per container. Recommended starting points for key containers:
-            *   `messages`: **4000 RU/s** (scales 400-4000 RU/s)
-            *   `documents`: **4000 RU/s** (scales 400-4000 RU/s)
-            *   `group_documents`: **4000 RU/s** (scales 400-4000 RU/s)
-            *   Other containers (`settings`, `feedback`, `archived_conversations`, etc.): Start lower (e.g., **1000 RU/s** max, scaling 100-1000 RU/s) and monitor.
-        *   **Monitor:** Continuously monitor RU consumption (using Azure Monitor Metrics) for each container and adjust the maximum Autoscale values as needed to avoid throttling (HTTP 429 errors) while optimizing cost.
+- Prefer autoscale so throughput can move between 10% and 100% of the configured maximum.
+- Start with database-level throughput during setup, then move critical containers to container-level autoscale once real usage patterns are visible.
+- Good starting points for heavier containers are `messages`, `documents`, and `group_documents` at 4000 RU/s max.
+- Lower-volume containers such as `settings`, `feedback`, and `archived_conversations` can usually begin around 1000 RU/s max.
+- Watch for HTTP 429 responses and sustained RU saturation before increasing limits.
 
-    ![Scale - Cosmos DB Container Throughput Settings](./images/scale-cosmos.png)
+![Scale - Cosmos DB Container Throughput Settings](./images/scale-cosmos.png)
 
-*   **Global Distribution:**
-    *   **What:** Replicate your Cosmos DB data across multiple Azure regions.
-    *   **Why:** Reduces read/write latency for users in different geographic locations and provides higher availability via regional failover.
-    *   **How:** Configure replication in the Azure Cosmos DB portal ("Replicate data globally"). The application *should* automatically connect to the nearest available region, but thorough testing in a multi-region setup is advised. Consider the implications for data consistency levels based on your application's requirements.
+If users are distributed across regions, consider global replication as a latency and availability tool. Multi-region deployment improves failover posture, but it also requires testing around consistency and application behavior.
 
 ## Azure AI Search
 
-> <a href="#simple-chat---application-scaling" style="text-decoration: none;">Return to top</a>
+Azure AI Search usually becomes the next limiter once retrieval traffic and indexed data volume climb.
+
+- Increase replicas to improve query throughput and basic high availability.
+- Increase partitions to support larger indexes and faster indexing throughput.
+- Plan partition count before the index becomes large because major partition changes often imply re-indexing.
+- Move from S1 to S2, S3, or higher tiers when storage, replica, partition, or feature limits become the real constraint.
+
+For production, monitor query latency and indexing backlog rather than scaling on intuition.
 
-Azure AI Search scaling involves adjusting replicas, partitions, and the service tier.
+## Azure AI and Cognitive Services
 
-*   **Replicas (Horizontal Query Scaling):**
-    *   **What:** Copies of your index that handle query requests in parallel.
-    *   **Why:** Increase query throughput (Queries Per Second - QPS) and improve high availability (queries can be served even if one replica is down).
-    *   **How:** Increase the "Replica count" on the AI Search service's "Scale" blade in the Azure portal. Start with 1 for Dev/Test, consider 2-3 for basic HA in production, and increase based on monitored query latency and QPS under load.
+Azure OpenAI, Document Intelligence, Content Safety, Speech, and Video Indexer are API-driven services with quota and rate-limit ceilings.
 
-*   **Partitions (Data & Indexing Scaling):**
-    *   **What:** Shards that store distinct portions of your index. More partitions distribute the index storage and allow for faster parallel indexing.
-    *   **Why:** Increase the total amount of data the index can hold and potentially speed up document ingestion/indexing.
-    *   **How:** Increase the "Partition count" on the "Scale" blade. **Important:** You generally need to decide on the partition count based on anticipated data volume *before* significant data is indexed, as changing partitions often requires re-indexing. The S1 tier supports up to 12 partitions.
+- Monitor tokens-per-minute, requests-per-minute, transactions-per-second, and backend throttling responses.
+- Request quota increases when the service is healthy but the regional quota is the limiter.
+- Use Azure API Management when you need retry policy, request shaping, throttling, or distribution across multiple backends.
 
-*   **Service Tier (Vertical Scaling):**
-    *   **What:** Changing the overall service tier (e.g., Basic, S1, S2, S3, L1, L2).
-    *   **Why:** Higher tiers offer increased limits on storage per partition, total storage, maximum replicas/partitions, Semantic Ranker usage, and other features.
-    *   **How:** Select a different pricing tier on the "Scale" blade. The recommended starting point is S1. Scale up to S2/S3/L-tiers if you hit the fundamental limits of S1 or require features only available in higher tiers.
+### APIM as the scaling control plane
 
-## Azure AI / Cognitive Services (OpenAI, Document Intelligence, etc.)
+APIM is the recommended pattern when Simple Chat needs a stable gateway in front of AI services.
 
-> <a href="#simple-chat---application-scaling" style="text-decoration: none;">Return to top</a>
+- It can spread traffic across multiple Azure OpenAI deployments or regions.
+- It can rate-limit callers before they hit backend service quotas.
+- It can retry transient failures such as HTTP 429 responses.
+- It gives operations teams one place to apply auth, policy, and logging rules.
 
-Services like Azure OpenAI, Document Intelligence, Content Safety, Speech Service, and Video Indexer are typically consumed via API calls and often have rate limits (e.g., Tokens Per Minute/Requests Per Minute for OpenAI, Transactions Per Second for others).
+Simple Chat already supports APIM-backed configuration for GPT, embeddings, image generation, Content Safety, Document Intelligence, and Azure AI Search through Admin Settings.
 
-*   **Rate Limits & Quotas:** Be aware of the default limits for your service tiers and regions. Monitor usage and request quota increases via Azure support if necessary.
-*   **Azure API Management (APIM) - Recommended Pattern:**
-    *   **What:** An Azure service that acts as a gateway or facade for your backend APIs, including Azure AI services.
-    *   **Why for Scaling:**
-        *   **Load Balancing:** Distribute requests across multiple Azure OpenAI deployments (e.g., different instances, regions, or even different models if abstracted).
-        *   **Throttling/Rate Limiting:** Implement custom rate limits in APIM *before* hitting the backend service limits.
-        *   **Retry Policies:** Configure automatic retries for transient errors (like HTTP 429 Too Many Requests).
-        *   **Centralized Management:** Provides a single point for security, monitoring, and policy enforcement.
-    *   **How:**
-        1.  Deploy an Azure API Management instance.
-        2.  Configure APIM to route requests to your specific Azure AI service endpoints. Implement policies for load balancing, retries, rate limiting, etc.
-        3.  **Reference:** For detailed patterns, especially for Azure OpenAI, refer to the guidance and examples provided in the **[AzureOpenAI-with-APIM GitHub repository](https://github.com/microsoft/AzureOpenAI-with-APIM)**. This repository demonstrates robust methods for load balancing and scaling Azure OpenAI consumption.
-        4.  **Simple Chat Integration:** Configure the **Admin Settings** within Simple Chat to point to your **APIM Gateway URL** and use your **APIM Subscription Key** for authentication, instead of directly using the backend service endpoint and key. The UI supports APIM configuration for Azure OpenAI (GPT, Embeddings, Image Gen), Content Safety, Document Intelligence, and AI Search.
+For a strong Azure OpenAI pattern, review the [AzureOpenAI-with-APIM repository](https://github.com/microsoft/AzureOpenAI-with-APIM).
diff --git a/docs/application_workflows.md b/docs/application_workflows.md
index 4b11f2ad..3d5fec20 100644
--- a/docs/application_workflows.md
+++ b/docs/application_workflows.md
@@ -1,57 +1,82 @@
-# Simple Chat - Application workflows
-
-- [Content Safety](#content-safety---workflow)
-- [Add your data (RAG Ingestion)](#add-your-data-rag-ingestion)
-
-- [Return to Main](../README.md)
-
-## Content Safety - Workflow
-
-![Workflow - Content Safety](./images/workflow-content_safety.png) 
-
-1.  **User Sends Message**: A user types a message in the chat interface.
-2.  **Content Safety Interrogation (If Enabled)**:
-    *   Before the message reaches *any* backend service (AI model, Search, Image Gen, etc.), it is sent to the configured **Azure AI Content Safety** endpoint.
-    *   Content Safety analyzes the text for harmful content based on configured categories (Hate, Sexual, Violence, Self-Harm) and severity thresholds.
-    *   Custom blocklists can also be applied.
-3.  **Decision Point**:
-    *   **If Safe**: The message proceeds to the intended service (e.g., RAG, Direct Model Interaction, Image Generation).
-    *   **If Unsafe**: The message is blocked. The user receives a generic notification (or configured message). Details of the violation may be logged (if configured) and potentially viewable by users with the `SafetyAdmin` role.
-4.  **Service Interaction (If Safe)**:
-    *   **RAG / AI Search**: The query is used to search Azure AI Search indexes (personal/group).
-    *   **Direct Model Interaction**: The message is sent directly to the Azure OpenAI GPT model.
-    *   **Image Generation**: The prompt is sent to the Azure OpenAI DALL-E model (if enabled).
-    *   *Note:* Responses from these services are typically *not* sent back through Content Safety by default in this flow, though Azure OpenAI itself has built-in content filtering.
-
-## Add your data (RAG Ingestion)
-
-This workflow describes how documents uploaded via "Your Workspace" or "Group Workspaces" are processed for Retrieval-Augmented Generation.
-
-![Add your data - Workflow](./images/workflow-add_your_data.png) 
-
-1.  **User Uploads File(s)**:
-    *   User selects one or more supported files via the application UI (e.g., PDF, DOCX, TXT, MP4, MP3).
-    *   Files are sent to the backend application running on Azure App Service.
-2.  **Initial Processing & Text Extraction**:
-    *   The backend determines the file type.
-    *   The file is sent to the appropriate service for text extraction:
-        *   **Azure AI Document Intelligence**: For PDFs, Office Docs, Images (OCR). Extracts text, layout, tables.
-        *   **Azure Video Indexer**: For videos. Extracts audio transcript and frame OCR text (if enabled).
-        *   **Azure Speech Service**: For audio files. Extracts audio transcript (if enabled).
-        *   **Internal Parsers**: For plain text, HTML, Markdown, JSON, CSV.
-3.  **Content Chunking**:
-    *   The extracted text content is divided into smaller, manageable chunks based on file type and content structure.
-    *   Chunking strategies vary (see [Advanced Chunking Logic](#advanced-chunking-logic) under Latest Features) but aim for semantic coherence and appropriate size (~400-1200 words, depending on type), often with overlap between chunks to preserve context. Timestamps or page numbers are included where applicable.
-4.  **Vectorization (Embedding)**:
-    *   Each text chunk is sent to the configured **Embedding Model** endpoint in **Azure OpenAI**.
-    *   The model generates a high-dimensional **vector embedding** (a numerical representation) for the semantic content of the chunk.
-    *   This process repeats for all chunks from the uploaded file(s).
-5.  **Storage in Azure AI Search and Cosmos DB**:
-    *   For each chunk, the following are stored in the appropriate **Azure AI Search Index** (`simplechat-user-index` or `simplechat-group-index`):
-        *   Chunk content (text).
-        *   Vector embedding.
-        *   Metadata: Parent document ID, user/group ID, filename, chunk sequence number, page number (if applicable), timestamp (if applicable), classification tags (if applicable), extracted keywords/summary (if applicable).
-    *   Metadata about the **parent document** (e.g., original filename, total chunks, upload date, user ID, group ID, document version, classification, processing status) is stored in **Azure Cosmos DB**.
-    *   Cosmos DB maintains the relationship between the parent document record and its constituent chunks stored in Azure AI Search.
-6.  **Ready for Retrieval**:
-    *   Once indexed, the document content is available for hybrid search (vector + keyword) when users toggle "Search Your Data" or perform targeted searches within workspaces.
+---
+layout: showcase-page
+title: "Application Workflows"
+permalink: /application_workflows/
+menubar: docs_menu
+accent: violet
+eyebrow: "How Requests Move"
+description: "Two workflows explain most of the system behavior: how user prompts are screened, and how uploaded files become searchable context for grounded chat."
+hero_icons:
+  - bi-shield-check
+  - bi-arrow-repeat
+  - bi-diagram-2
+hero_pills:
+  - Prompt safety gate
+  - RAG ingestion pipeline
+  - Search-ready document processing
+hero_links:
+  - label: Review features
+    url: /features/
+    style: primary
+  - label: Open troubleshooting
+    url: /troubleshooting/
+    style: secondary
+---
+These flows are the fastest way to understand where Simple Chat applies safety checks, where Azure services participate, and where document-grounded answers actually come from.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-image">
+            <img src="{{ '/images/workflow-content_safety.png' | relative_url }}" alt="Workflow diagram for content safety screening before model execution">
+        </div>
+        <h2>Content Safety</h2>
+        <p>User prompts can be screened before the system touches retrieval, direct model calls, or image generation. Unsafe prompts are blocked before they propagate.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-image">
+            <img src="{{ '/images/workflow-add_your_data.png' | relative_url }}" alt="Workflow diagram for document ingestion into retrieval indices">
+        </div>
+        <h2>Add Your Data</h2>
+        <p>Uploads are extracted, chunked, embedded, and indexed so chat can retrieve the right fragments later with citations and metadata.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>Why these two flows matter</h2>
+    <p>The first flow protects the front door. The second flow determines whether retrieval answers are useful, traceable, and fast. Most production issues map back to one of these two paths.</p>
+</div>
+
+## Content Safety Workflow
+
+![Workflow - Content Safety](./images/workflow-content_safety.png)
+
+1. A user sends a message from the chat interface.
+2. If Content Safety is enabled, the message is evaluated before it reaches the target backend service.
+3. Azure AI Content Safety evaluates configured categories such as hate, sexual content, violence, and self-harm, and can also apply custom blocklists.
+4. If the message passes, the system routes it to the intended destination.
+5. If the message fails, the request is blocked and the user receives a generic notification. Details can be logged for administrators when that feature is enabled.
+
+When a prompt is considered safe, it can continue into one of several paths:
+
+- Retrieval-backed chat that queries Azure AI Search.
+- Direct GPT interaction against Azure OpenAI.
+- Image generation against a configured DALL-E deployment.
+
+The default flow protects the inbound user message. Downstream services may still apply their own filtering behavior after that point.
+
+## Add Your Data Workflow
+
+This workflow covers what happens when users upload content into personal or group workspaces for Retrieval-Augmented Generation.
+
+![Add your data - Workflow](./images/workflow-add_your_data.png)
+
+1. Users upload one or more supported files through the application UI.
+2. The backend determines file type and chooses the correct extraction path.
+3. Text is extracted through Azure AI Document Intelligence, Azure Video Indexer, Azure Speech Service, or internal parsers depending on the content type.
+4. Extracted content is chunked into retrieval-friendly segments while preserving structural context such as pages, timestamps, tables, or sequence.
+5. Each chunk is embedded through the configured Azure OpenAI embedding model.
+6. The chunk text, embedding vector, and retrieval metadata are written to Azure AI Search.
+7. Parent document records and processing metadata are written to Cosmos DB so the system can relate the original file to its indexed chunks.
+8. Once indexing completes, the document becomes available to hybrid retrieval in chat and workspace search.
+
+Typical chunk metadata includes document identity, filename, workspace scope, sequence numbers, page references, timestamps, and optional classification or extraction metadata.
diff --git a/docs/assets/js/latest-release.js b/docs/assets/js/latest-release.js
index 7923c4f2..b39604e5 100644
--- a/docs/assets/js/latest-release.js
+++ b/docs/assets/js/latest-release.js
@@ -14,7 +14,9 @@ function setupLatestFeatureImageModal() {
     const imageModal = bootstrap.Modal.getOrCreateInstance(modalElement);
 
     imageTriggers.forEach((trigger) => {
-        trigger.addEventListener('click', () => {
+        trigger.addEventListener('click', (event) => {
+            event.preventDefault();
+
             const imageSrc = trigger.dataset.latestFeatureImageSrc;
             const imageTitle = trigger.dataset.latestFeatureImageTitle || 'Latest Feature Preview';
             const imageCaption = trigger.dataset.latestFeatureImageCaption || 'Click outside the popup to close it.';
diff --git a/docs/demos.md b/docs/demos.md
index a5f72d50..bdc819ac 100644
--- a/docs/demos.md
+++ b/docs/demos.md
@@ -1,11 +1,47 @@
-# Simple Chat - Solution Demonstrations
+---
+layout: showcase-page
+title: "Solution Demonstrations"
+permalink: /demos/
+menubar: docs_menu
+accent: orange
+eyebrow: "See The Product Move"
+description: "These short demos show the two motions that matter most for first-time teams: getting content in, then using that content in grounded conversations."
+hero_icons:
+  - bi-play-circle
+  - bi-file-earmark-arrow-up
+  - bi-chat-left-text
+hero_pills:
+  - Upload and inspect
+  - Classify and search
+  - Observe the user flow quickly
+hero_links:
+  - label: Open Getting Started
+    url: /setup_instructions/
+    style: primary
+  - label: Review workflows
+    url: /application_workflows/
+    style: secondary
+---
+These demos are useful when you need a quick visual of the product before walking through setup or user training.
 
-- [Upload document and review metadata](#upload-document-and-review-metadata)
-- [Classify documetn and chat with content](#classify-document-and-chat-with-content)
-- [Return to Main](../README.md)
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-image">
+			<img src="{{ '/images/UploadDocumentDemo.gif' | relative_url }}" alt="Animated demo showing document upload and metadata review in Simple Chat">
+		</div>
+		<h2>Upload document and review metadata</h2>
+		<p>This flow shows how a document enters the system, how users confirm the upload worked, and where metadata becomes visible during processing.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-image">
+			<img src="{{ '/images/ChatwithSearchingYourDocsDemo.gif' | relative_url }}" alt="Animated demo showing document classification and grounded chat in Simple Chat">
+		</div>
+		<h2>Classify a document and chat with the content</h2>
+		<p>This flow shows how classification helps organize content and how retrieval-backed chat turns uploaded files into cited answers.</p>
+	</article>
+</section>
 
-## Upload document and review metadata
-![Upload Document Demo](./images/UploadDocumentDemo.gif)
-
-## Classify document and chat with content
-![Chat with Searching your Documents Demo](./images/ChatwithSearchingYourDocsDemo.gif)
\ No newline at end of file
+<div class="latest-release-note-panel">
+	<h2>Where to go next</h2>
+	<p>If these flows match what your team needs, move into the getting started guide for deployment and then into the tutorials for end-user onboarding.</p>
+</div>
\ No newline at end of file
diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
index f319d9a6..d8ea15fa 100644
--- a/docs/explanation/architecture.md
+++ b/docs/explanation/architecture.md
@@ -1,11 +1,48 @@
-# explanation/architecture.md
 ---
-layout: libdoc/page
-title: Architecture
+layout: showcase-page
+title: "Architecture"
+permalink: /explanation/architecture/
+menubar: docs_menu
+accent: slate
+eyebrow: "Explanation"
+description: "Understand the major platform layers in Simple Chat and how data, AI services, identity, and operations interact."
+hero_icons: ["bi-diagram-3", "bi-hdd-network", "bi-cpu"]
+hero_pills: ["Application, data, and AI layers", "Security and scale concerns", "Azure-native service composition"]
+hero_links: [{ label: "Explanation index", url: "/explanation/", style: "primary" }, { label: "Design principles", url: "/explanation/design_principles/", style: "secondary" }]
 order: 110
 category: Explanation
 ---
 
+Architecture matters here because Simple Chat is not just a chat frontend. It is a coordinated application layer over identity, search, storage, retrieval, and optional AI services.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-window-stack"></i></div>
+        <h2>Application tier</h2>
+        <p>Azure App Service hosts the Flask application, owns the request flow, and orchestrates conversations, uploads, configuration, and service integration.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-database"></i></div>
+        <h2>Data plane</h2>
+        <p>Cosmos DB stores application metadata and history while Azure AI Search stores the retrieval layer that grounded chat depends on.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-stars"></i></div>
+        <h2>AI services</h2>
+        <p>Azure OpenAI, Document Intelligence, Speech, Video Indexer, and Content Safety can be combined based on which feature packs the deployment enables.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-shield-check"></i></div>
+        <h2>Security and operations</h2>
+        <p>Identity, private networking, monitoring, autoscale, and role separation are first-order parts of the design rather than optional polish.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>How to read this page</h2>
+    <p>Start with the high-level diagram, then move into the component and data-flow sections. That order mirrors how most production questions appear: first where a responsibility lives, then how requests and documents move across the system.</p>
+</div>
+
 
 This document explains the overall architecture, design principles, and key concepts behind Simple Chat. Understanding these foundations will help you make informed decisions about deployment, configuration, and usage.
 
diff --git a/docs/explanation/design_principles.md b/docs/explanation/design_principles.md
index c04f6d8d..3ee5e5dc 100644
--- a/docs/explanation/design_principles.md
+++ b/docs/explanation/design_principles.md
@@ -1,11 +1,48 @@
-# explanation/design_principles.md
 ---
-layout: libdoc/page
-title: Design Principles
+layout: showcase-page
+title: "Design Principles"
+permalink: /explanation/design_principles/
+menubar: docs_menu
+accent: teal
+eyebrow: "Explanation"
+description: "These principles explain the recurring design choices in Simple Chat across security, extensibility, operability, and user experience."
+hero_icons: ["bi-compass", "bi-shield-lock", "bi-people"]
+hero_pills: ["Security by default", "Enterprise-ready design", "Configuration over reinvention"]
+hero_links: [{ label: "Explanation index", url: "/explanation/", style: "primary" }, { label: "Architecture", url: "/explanation/architecture/", style: "secondary" }]
 order: 120
 category: Explanation
 ---
 
+These principles are the shortest explanation for why the product sometimes feels opinionated. They describe what the repo optimizes for when flexibility and operational safety pull in different directions.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-shield-lock"></i></div>
+		<h2>Security first</h2>
+		<p>Identity, least privilege, private connectivity, and managed identities are built into the architecture instead of layered on later.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-person-check"></i></div>
+		<h2>User-centered execution</h2>
+		<p>The platform tries to keep high-value paths understandable for end users and manageable for administrators at the same time.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-building-check"></i></div>
+		<h2>Enterprise readiness</h2>
+		<p>Scalability, auditability, compliance, and integration boundaries are treated as core product concerns rather than future hardening tasks.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-sliders"></i></div>
+		<h2>Configuration over code edits</h2>
+		<p>Many capabilities are designed to be enabled, disabled, or tuned through admin settings so rollout changes do not require constant redeployment.</p>
+	</article>
+</section>
+
+<div class="latest-release-note-panel">
+	<h2>Why this page helps</h2>
+	<p>When two implementation options both look reasonable, these principles are the tie-breakers. They also explain why many docs pages emphasize identity, service dependencies, and rollout order as much as feature behavior.</p>
+</div>
+
 
 Simple Chat is built on a set of core design principles that guide architectural decisions, feature development, and operational practices. Understanding these principles helps explain why certain choices were made and how to extend the system effectively.
 
diff --git a/docs/explanation/feature_guidance.md b/docs/explanation/feature_guidance.md
index 9060e0dd..381365c2 100644
--- a/docs/explanation/feature_guidance.md
+++ b/docs/explanation/feature_guidance.md
@@ -1,7 +1,70 @@
-# explanation/feature_guidance.md
 ---
-layout: libdoc/page
-title: Feature Guidance
+layout: showcase-page
+title: "Feature Guidance"
+permalink: /explanation/feature_guidance/
+menubar: docs_menu
+accent: orange
+eyebrow: "Explanation"
+description: "Use this page to decide which Simple Chat capabilities belong in a first rollout, which ones depend on more Azure services, and which ones should wait until the platform is stable."
+hero_icons: ["bi-grid-1x2", "bi-signpost-split", "bi-stars"]
+hero_pills: ["Foundational features first", "Dependency-aware rollout", "Optional packs after the core loop works"]
+hero_links: [{ label: "Features overview", url: "/features/", style: "primary" }, { label: "Admin configuration", url: "/admin_configuration/", style: "secondary" }]
 order: 130
 category: Explanation
 ---
+
+Feature rollout goes better when capabilities are grouped by operational risk instead of novelty. The right question is usually not “Can we turn this on?” but “What extra service, process, or support burden does this add?”
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-chat-dots"></i></div>
+		<h2>Start with the core loop</h2>
+		<p>Get sign-in, model routing, workspace access, document upload, embeddings, AI Search, and grounded chat working before you widen the feature surface.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-shield-check"></i></div>
+		<h2>Layer governance deliberately</h2>
+		<p>Content Safety, feedback review, archiving, API documentation controls, and role-scoped admin features are valuable, but they also create operational review work.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-camera-video"></i></div>
+		<h2>Treat media as an expansion pack</h2>
+		<p>Audio, video, speech, enhanced citations, and metadata extraction increase capability and complexity at the same time because they pull in extra Azure services and processing paths.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-robot"></i></div>
+		<h2>Add agents after the platform is predictable</h2>
+		<p>Agents, actions, and external system integrations work best once the base chat and workspace behavior is stable, observable, and well understood.</p>
+	</article>
+</section>
+
+<div class="latest-release-note-panel">
+	<h2>A good rollout sequence reduces support load</h2>
+	<p>If users can already sign in, upload content, search it, and get grounded answers, later feature additions feel like improvements. If the core loop is unstable, every optional feature makes triage harder.</p>
+</div>
+
+## Rollout groups
+
+| Feature group | Enable early? | Typical dependencies | Why it belongs there |
+| :--- | :--- | :--- | :--- |
+| Authentication, chat, base model routing | Yes | Entra ID, Azure OpenAI | Users need a stable starting point before anything else matters. |
+| Workspaces, ingestion, embeddings, AI Search | Yes | Azure AI Search, embeddings, Document Intelligence | This is the foundation of grounded chat and document-backed workflows. |
+| Classification, metadata, enhanced citations | Usually after core search works | Storage, admin process decisions, optional GPT extraction | Useful, but easier to operationalize after the retrieval path is already trusted. |
+| Content Safety, feedback, archiving | Based on governance needs | Content Safety, Cosmos containers, reviewer roles | These features change process and oversight, not just UI behavior. |
+| Audio, video, speech, image generation | Later | Speech, Video Indexer, DALL-E, storage | Strong value, but each one adds cost, service dependencies, and user-experience edge cases. |
+| Agents, OpenAPI actions, SQL workflows | Later | Agent enablement, actions, external systems, model discipline | Best added once prompt boundaries, workspace scope, and admin ownership are clear. |
+
+## Questions to ask before enabling a feature
+
+1. Which Azure service or quota does this add?
+2. Which admin setting or role boundary controls it?
+3. What new failure mode does it introduce?
+4. Who owns support when the feature misbehaves?
+5. Does the feature help the core user workflow or distract from it?
+
+## Practical guidance
+
+- Prefer a smaller, reliable feature set for the first production rollout.
+- Turn on media and agent capabilities only after you have baseline monitoring and support habits in place.
+- Use the admin reference to map each feature toggle back to its service dependency before enabling it.
+- Revisit the rollout after users have proven which workflows matter enough to justify extra complexity.
diff --git a/docs/explanation/features/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md b/docs/explanation/features/v0.241.006/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md
similarity index 100%
rename from docs/explanation/features/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md
rename to docs/explanation/features/v0.241.006/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md
diff --git a/docs/explanation/fixes/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md b/docs/explanation/fixes/v0.241.006/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md
similarity index 100%
rename from docs/explanation/fixes/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md
rename to docs/explanation/fixes/v0.241.006/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md
diff --git a/docs/explanation/fixes/MEDIA_ENHANCED_CITATION_BADGE_FIX.md b/docs/explanation/fixes/v0.241.006/MEDIA_ENHANCED_CITATION_BADGE_FIX.md
similarity index 100%
rename from docs/explanation/fixes/MEDIA_ENHANCED_CITATION_BADGE_FIX.md
rename to docs/explanation/fixes/v0.241.006/MEDIA_ENHANCED_CITATION_BADGE_FIX.md
diff --git a/docs/explanation/fixes/v0.241.008/SPEECH_RESOURCE_ID_BUILDER_FIX.md b/docs/explanation/fixes/v0.241.006/SPEECH_RESOURCE_ID_BUILDER_FIX.md
similarity index 100%
rename from docs/explanation/fixes/v0.241.008/SPEECH_RESOURCE_ID_BUILDER_FIX.md
rename to docs/explanation/fixes/v0.241.006/SPEECH_RESOURCE_ID_BUILDER_FIX.md
diff --git a/docs/explanation/fixes/v0.241.007/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md b/docs/explanation/fixes/v0.241.006/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md
similarity index 100%
rename from docs/explanation/fixes/v0.241.007/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md
rename to docs/explanation/fixes/v0.241.006/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md
diff --git a/docs/explanation/fixes/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md b/docs/explanation/fixes/v0.241.006/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md
similarity index 100%
rename from docs/explanation/fixes/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md
rename to docs/explanation/fixes/v0.241.006/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md
diff --git a/docs/explanation/fixes/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md b/docs/explanation/fixes/v0.241.006/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md
similarity index 100%
rename from docs/explanation/fixes/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md
rename to docs/explanation/fixes/v0.241.006/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
index 8930a58c..abb87ef6 100644
--- a/docs/explanation/index.md
+++ b/docs/explanation/index.md
@@ -1,13 +1,63 @@
-Welcome to the **Explanation** section. Here you'll find understanding-oriented discussions of key topics and concepts behind Simple Chat.
-
-- [Architecture](/explanation/architecture/)
-- [Design Principles](/explanation/design_principles/)
-- [Feature Guidance](/explanation/feature_guidance/)
-- [Running Simple Chat Locally](/explanation/running_simplechat_locally/)
-- [Running Simple Chat in Azure Production](/explanation/running_simplechat_azure_production/)
-- **Scenarios:**
-  - [Agent Examples](/explanation/scenarios/agents/)
-  - [Workspace Examples](/explanation/scenarios/workspaces/)
-- **Version History:**
-  - [Features by Version](/explanation/features/)
-  - [Fixes by Version](/explanation/fixes/)
\ No newline at end of file
+---
+layout: showcase-page
+title: "Explanation"
+permalink: /explanation/
+menubar: docs_menu
+accent: violet
+eyebrow: "Understand The Platform"
+description: "Use the explanation section when you want the reasoning behind the product: architecture, operating principles, rollout guidance, and runtime patterns."
+hero_icons: ["bi-diagram-3", "bi-lightbulb", "bi-journal-richtext"]
+hero_pills: ["Architecture and principles", "Feature rollout guidance", "Local and production runtime patterns"]
+hero_links: [{ label: "Architecture", url: "/explanation/architecture/", style: "primary" }, { label: "Feature guidance", url: "/explanation/feature_guidance/", style: "secondary" }]
+---
+
+This section is for decisions, not just steps. Use it when you need to understand why Simple Chat is put together the way it is and how that affects deployment, operations, and feature rollout.
+
+<section class="latest-release-card-grid">
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+    <h2>Architecture</h2>
+    <p>Understand how App Service, Azure OpenAI, AI Search, Cosmos DB, Storage, and optional services combine into one application surface.</p>
+    <p><a href="{{ '/explanation/architecture/' | relative_url }}">Open architecture</a></p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-compass"></i></div>
+    <h2>Design Principles</h2>
+    <p>See the operating philosophy behind the product, including security, enterprise readiness, modularity, observability, and user-centered design.</p>
+    <p><a href="{{ '/explanation/design_principles/' | relative_url }}">Open design principles</a></p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-grid-1x2"></i></div>
+    <h2>Feature Guidance</h2>
+    <p>Use the feature guidance page to decide which capabilities belong in a first rollout and which ones should be layered in after the platform stabilizes.</p>
+    <p><a href="{{ '/explanation/feature_guidance/' | relative_url }}">Open feature guidance</a></p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-play-circle"></i></div>
+    <h2>Runtime Patterns</h2>
+    <p>Compare the recommended local developer loop with the Azure production runtime model so startup decisions stay consistent with the deployment model.</p>
+    <p><a href="{{ '/explanation/running_simplechat_locally/' | relative_url }}">Local runtime</a> · <a href="{{ '/explanation/running_simplechat_azure_production/' | relative_url }}">Azure production</a></p>
+  </article>
+</section>
+
+<div class="latest-release-note-panel">
+  <h2>Use these pages differently from how-to guides</h2>
+  <p>How-to guides are task-oriented. The explanation section is where you go when you want to understand the tradeoffs behind deployment models, feature boundaries, or operational choices before you commit to one path.</p>
+</div>
+
+## Continue into deeper references
+
+<section class="latest-release-card-grid">
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-collection"></i></div>
+    <h2>Scenarios</h2>
+    <p>Example workspace and agent scenarios show how the product can be applied in concrete business contexts.</p>
+    <p><a href="{{ '/explanation/scenarios/agents/' | relative_url }}">Agent examples</a> · <a href="{{ '/explanation/scenarios/workspaces/' | relative_url }}">Workspace examples</a></p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-clock-history"></i></div>
+    <h2>Version history</h2>
+    <p>Track long-lived feature and fix documentation by version when you need historical context for rollout planning or regression analysis.</p>
+    <p><a href="{{ '/explanation/features/' | relative_url }}">Features by version</a> · <a href="{{ '/explanation/fixes/' | relative_url }}">Fixes by version</a></p>
+  </article>
+</section>
\ No newline at end of file
diff --git a/docs/explanation/running_simplechat_azure_production.md b/docs/explanation/running_simplechat_azure_production.md
index b3042591..73e32316 100644
--- a/docs/explanation/running_simplechat_azure_production.md
+++ b/docs/explanation/running_simplechat_azure_production.md
@@ -1,14 +1,51 @@
-# explanation/running_simplechat_azure_production.md
 ---
-layout: libdoc/page
-title: Running Simple Chat in Azure Production
+layout: showcase-page
+title: "Running Simple Chat in Azure Production"
+permalink: /explanation/running_simplechat_azure_production/
+menubar: docs_menu
+accent: emerald
+eyebrow: "Explanation"
+description: "Use the deployment model first, then choose the right Azure production startup pattern for web workers and scheduler work."
+hero_icons: ["bi-cloud-check", "bi-box-seam", "bi-gear-wide-connected"]
+hero_pills: ["Container App Service by default", "Native Python is a separate path", "Separate scheduler work when scaling"]
+hero_links: [{ label: "Deployment reference", url: "/reference/deploy/", style: "primary" }, { label: "Running locally", url: "/explanation/running_simplechat_locally/", style: "secondary" }]
 order: 150
 category: Explanation
 ---
 
+Production startup guidance only makes sense after you identify the deployment model. In this repo, most Azure deployment paths are container-based, and that changes the startup-command conversation immediately.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+		<h2>Repo deployers are container-first</h2>
+		<p>AZD, Bicep, Terraform, and Azure CLI paths all assume the container image is what App Service runs in production.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-play-circle"></i></div>
+		<h2>Container entrypoint already starts Gunicorn</h2>
+		<p>For the supported container paths, App Service does not need a second native Python startup command layered on top.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-filetype-py"></i></div>
+		<h2>Native Python is intentional, not default</h2>
+		<p>If you choose a native Python App Service deployment, you need to manage startup behavior explicitly and treat it as a different operating model.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-arrow-repeat"></i></div>
+		<h2>Scheduler work deserves its own plan</h2>
+		<p>Once you scale workers or instances, background task isolation becomes part of production correctness, not a tuning detail.</p>
+	</article>
+</section>
+
+<div class="latest-release-note-panel">
+	<h2>The key split</h2>
+	<p>If the site runs the repo container image, let the image entrypoint launch Gunicorn. If the site runs native Python directly, set the startup command yourself. Most confusion in Azure production comes from mixing those two models.</p>
+</div>
+
 This guide explains the supported production startup patterns for Simple Chat in Azure.
 
-Current documentation version: 0.241.002
+Current documentation version: 0.241.009
 
 ## Default Azure Production Model in This Repo
 
diff --git a/docs/explanation/running_simplechat_locally.md b/docs/explanation/running_simplechat_locally.md
index cc0d2537..b1d70f58 100644
--- a/docs/explanation/running_simplechat_locally.md
+++ b/docs/explanation/running_simplechat_locally.md
@@ -1,14 +1,51 @@
-# explanation/running_simplechat_locally.md
 ---
-layout: libdoc/page
-title: Running Simple Chat Locally
+layout: showcase-page
+title: "Running Simple Chat Locally"
+permalink: /explanation/running_simplechat_locally/
+menubar: docs_menu
+accent: blue
+eyebrow: "Explanation"
+description: "Use the repo-local Python 3.12 environment and the Flask debug loop for everyday development, then move to Linux-compatible runtimes only when Gunicorn validation matters."
+hero_icons: ["bi-laptop", "bi-terminal", "bi-code-square"]
+hero_pills: ["Python 3.12 local venv", "Flask debug loop first", "Gunicorn validation only when needed"]
+hero_links: [{ label: "Explanation index", url: "/explanation/", style: "primary" }, { label: "Azure production runtime", url: "/explanation/running_simplechat_azure_production/", style: "secondary" }]
 order: 140
 category: Explanation
 ---
 
+Local development is intentionally simpler than Azure production. The goal is fast editing and debugging, not pretending every laptop is a production host.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-box"></i></div>
+		<h2>Use a repo-local virtual environment</h2>
+		<p>Create a Python 3.12 `.venv` in the repo and point VS Code at it before you install dependencies or run the app.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-bug"></i></div>
+		<h2>Prefer `python app.py` for normal work</h2>
+		<p>The Flask debug loop is the default developer path because it keeps iteration fast and avoids unnecessary production-runtime complexity.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-windows"></i></div>
+		<h2>Windows is supported for development</h2>
+		<p>On Windows, keep using the local Python flow for day-to-day work and move to Docker or WSL2 only when Linux-specific runtime behavior needs testing.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-diagram-2"></i></div>
+		<h2>Test Gunicorn separately</h2>
+		<p>Use a Linux-compatible environment when you specifically need worker, thread, timeout, or streaming behavior that mirrors production more closely.</p>
+	</article>
+</section>
+
+<div class="latest-release-note-panel">
+	<h2>Do not overfit local startup to production</h2>
+	<p>The repo deliberately separates the everyday developer loop from the production hosting model. That keeps local work straightforward and makes production-specific validation more explicit.</p>
+</div>
+
 This guide explains the recommended local developer workflow for Simple Chat.
 
-Current documentation version: 0.241.002
+Current documentation version: 0.241.009
 
 ## VS Code Python 3.12 Setup
 
diff --git a/docs/external_apps_overview.md b/docs/external_apps_overview.md
index 01d7908a..19c784d3 100644
--- a/docs/external_apps_overview.md
+++ b/docs/external_apps_overview.md
@@ -1,17 +1,46 @@
-# Simple Chat - External Applications Overview
-
-[Return to Main](../README.md)
-
-The following applications while not directly associated with the Simple Chat solution, are made to assist users in the usage of the system.
-
-## Bulk Uploader Utility
-
-Tool used to assist users with the bulk loading of documents into a group for use within Simple Chat application.
-
-[Link to Bulk Uploader Utility](../application//external_apps/bulkloader/ReadMe.md)
-
-## Database Seeder Utility
-
-The DatabaseSeeder application is a utility designed to automate the process of initializing or updating administrative settings in the CosmosDB database used by the SimpleChat platform. By using this tool, you can reliably seed or overwrite configuration data, ensuring that your environment matches the desired settings for your version of SimpleChat.
-
-[Link to Database Seeder Utility documentation](../application/external_apps/databaseseeder/ReadMe.md)
+---
+layout: showcase-page
+title: "External Applications Overview"
+permalink: /external_apps_overview/
+menubar: docs_menu
+accent: emerald
+eyebrow: "Supporting Utilities"
+description: "Simple Chat ships with helper applications for teams that need to load content in bulk or seed administrative configuration outside the main UI."
+hero_icons:
+  - bi-box-arrow-up-right
+  - bi-upload
+  - bi-database-gear
+hero_pills:
+  - Bulk content onboarding
+  - Configuration seeding
+  - Useful for environment setup and migration
+hero_links:
+  - label: Manual setup guide
+    url: /setup_instructions_manual/
+    style: primary
+  - label: Admin configuration
+    url: /admin_configuration/
+    style: secondary
+---
+
+These utilities sit beside the main application. They are intended for administrators and support teams that need faster environment preparation or large-scale document loading.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-upload"></i></div>
+		<h2>Bulk Uploader Utility</h2>
+		<p>Use the bulk uploader when you need to load a larger document set into a group workspace without relying on repeated manual uploads through the web UI.</p>
+		<p><a href="{{ site.github.repository_url }}/tree/main/application/external_apps/bulkloader">Open bulk uploader source</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-database-gear"></i></div>
+		<h2>Database Seeder Utility</h2>
+		<p>Use the database seeder to initialize or overwrite admin settings in Cosmos DB so an environment starts from a known configuration state.</p>
+		<p><a href="{{ site.github.repository_url }}/tree/main/application/external_apps/databaseseeder">Open database seeder source</a></p>
+	</article>
+</section>
+
+<div class="latest-release-note-panel">
+	<h2>When these tools are the right choice</h2>
+	<p>Use them when the UI is not the fastest path: for migration work, large initial content loads, repeatable environment setup, or admin configuration seeding across multiple environments.</p>
+</div>
diff --git a/docs/faqs.md b/docs/faqs.md
index 3d5907c8..15c10739 100644
--- a/docs/faqs.md
+++ b/docs/faqs.md
@@ -1,60 +1,309 @@
-# Simple Chat - FAQ's
+---
+layout: showcase-page
+title: "FAQ"
+description: "Answers to the questions that come up most often when teams deploy, secure, and operate Simple Chat in Azure environments."
+section: "Support"
+accent: slate
+eyebrow: "Troubleshooting"
+hero_icons:
+  - bi-question-circle
+  - bi-shield-lock
+  - bi-search
+hero_pills:
+  - Networking and firewall issues
+  - Identity and model setup
+  - Upload and retrieval troubleshooting
+hero_links:
+  - label: "Getting Started"
+    url: /setup_instructions/
+    style: primary
+  - label: "Review features"
+    url: /features/
+    style: outline
+---
 
-[Return to Main](../README.md)
+Use this page as the fast triage layer: it focuses on the recurring questions that show up after a team has already deployed or started hardening the environment.
 
-## Q: We've put Simple Chat behind a firewall (like Azure Firewall or a WAF), and some features (like search, document upload, or admin settings updates) don't work. What's wrong?
+<section class="latest-release-section">
+   <div class="latest-release-section-header">
+      <div>
+         <div class="latest-release-section-kicker">Quick jump</div>
+         <h2>Start with the category that matches the failure mode</h2>
+         <p>Each card jumps to the section where the most likely causes and checks are grouped together.</p>
+      </div>
+      <span class="latest-release-section-badge">Top issues</span>
+   </div>
 
-   - **A:** The application consists of a frontend (served to the browser) and a backend API running on the App Service. The frontend makes JavaScript calls to this backend API (e.g., /api/conversation, /api/documents, /api/config). Firewalls or Web Application Firewalls (WAFs) might block these API requests if not configured correctly.
+   <div class="latest-release-card-grid">
+      <article class="latest-release-card latest-release-accent--orange">
+         <div class="latest-release-card-shell">
+            <div class="latest-release-card-top">
+               <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-shield-lock"></i></span>
+               <span class="latest-release-card-badge">Network</span>
+            </div>
+            <h3 class="latest-release-card-title"><a href="#networking-and-firewalls">Firewall and private endpoint issues</a></h3>
+            <p class="latest-release-card-summary">Start here when uploads, search, or admin actions break only after the app is placed behind a firewall, WAF, or private network boundary.</p>
+         </div>
+      </article>
 
-     - **Solution**: Review your firewall/WAF rules. Ensure that HTTP GET, POST, PUT, PATCH, DELETE requests from user browsers to your App Service URL (e.g., https://<your-app-service-name>.azurewebsites.net/api/*) are allowed. Refer to the OpenAPI specification provided in the repository (artifacts/open_api/openapi.yaml) for a detailed list of API endpoints used by the application. You may need to create specific rules to allow traffic to these paths. 
+      <article class="latest-release-card latest-release-accent--blue">
+         <div class="latest-release-card-shell">
+            <div class="latest-release-card-top">
+               <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-person-lock"></i></span>
+               <span class="latest-release-card-badge">Identity</span>
+            </div>
+            <h3 class="latest-release-card-title"><a href="#authentication-and-access">Authentication and access</a></h3>
+            <p class="latest-release-card-summary">Use this section when users cannot sign in, role assignments do not behave as expected, or model enumeration fails because of tenant boundaries.</p>
+         </div>
+      </article>
 
-     ```
-     📁 SimpleChat
-          └── 📁 artifacts
-              └── 📁 open_api
-                  ├── openapi.yaml
-     ```
+      <article class="latest-release-card latest-release-accent--emerald">
+         <div class="latest-release-card-shell">
+            <div class="latest-release-card-top">
+               <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-cloud-upload"></i></span>
+               <span class="latest-release-card-badge">Ingestion</span>
+            </div>
+            <h3 class="latest-release-card-title"><a href="#uploads-and-search">Uploads and retrieval</a></h3>
+            <p class="latest-release-card-summary">Use this path when files fail during processing, indexes stay empty, or grounded answers are missing expected source material.</p>
+         </div>
+      </article>
 
-## Q: Users are getting authentication errors or cannot log in.
+      <article class="latest-release-card latest-release-accent--slate">
+         <div class="latest-release-card-shell">
+            <div class="latest-release-card-top">
+               <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-sliders2"></i></span>
+               <span class="latest-release-card-badge">Configuration</span>
+            </div>
+            <h3 class="latest-release-card-title"><a href="#model-configuration">Model and endpoint configuration</a></h3>
+            <p class="latest-release-card-summary">Use this section when GPT, embeddings, DALL-E, or APIM-mode settings are the part of the system that is behaving unexpectedly.</p>
+         </div>
+      </article>
+   </div>
+</section>
 
-   - **A:** Check the following:
-     - **App Registration**: Is the Redirect URI (.../.auth/login/aad/callback) correctly configured in the Azure AD App Registration?
-     - **App Service Authentication**: Is Authentication turned on in the App Service, linked to the correct App Registration, and set to "Require authentication"? Is the Issuer URL correct?
-     - **Enterprise Application**: Are users or groups correctly assigned to the application in **Enterprise Applications > Users and groups**? If "User assignment required" is enabled on the Enterprise App, only assigned users/groups can log in.
-     - **API Permissions**: Have the required Microsoft Graph permissions (`User.Read`, `openid`, `profile`, etc., and potentially `People.Read.All` for groups) been added *and* granted admin consent in the App Registration?
-     - **Tenant ID/Client ID**: Are the `TENANT_ID` and `CLIENT_ID` values in the App Service Application Settings correct?
+<div id="networking-and-firewalls"></div>
 
-## Q: File uploads are failing.
+<section class="latest-release-section">
+   <div class="latest-release-section-header">
+      <div>
+         <div class="latest-release-section-kicker">Network</div>
+         <h2>Firewall and private endpoint questions</h2>
+         <p>These issues usually surface after the app is moved behind network controls that only allow a subset of browser or outbound service traffic.</p>
+      </div>
+      <span class="latest-release-section-badge">Connectivity</span>
+   </div>
 
-   - **A:** Possible causes:
-     - **Permissions**: Does the App Service have permissions to write to Azure AI Search (if indexing), Document Intelligence (for processing), Speech/Video Indexer (if applicable), and Azure Storage (if using Enhanced Citations)? Check IAM roles, especially if using Managed Identity. If using keys, ensure they are correct in Admin Settings/App Settings.
-     - **Service Issues**: Check the status of dependent Azure services (Document Intelligence, AI Search, OpenAI Embeddings).
-     - **App Service Logs**: Enable and check Application Insights and App Service Logs (Diagnose and solve problems -> Application Logs) for specific error messages from the backend.
-     - **File Processing Logs**: Enable verbose File Processing Logs in Admin Settings > Other for detailed ingestion pipeline steps.
+   <details class="latest-release-archive-panel" open>
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q1</span>
+            <strong>We put Simple Chat behind a firewall or WAF and uploads, search, or admin updates stopped working.</strong>
+            <small>The browser still needs to reach the backend API routes that power the app.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">API traffic</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--orange">
+            <h3>What to verify</h3>
+            <ul>
+               <li>Simple Chat serves a frontend in the browser and a backend API from the app service, so blocking `/api/*` traffic breaks core features even when the page shell still loads.</li>
+               <li>Allow browser-originated `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` calls to your app service API routes.</li>
+               <li>Use the repository OpenAPI specification under `artifacts/open_api/openapi.yaml` to understand which endpoints the frontend depends on.</li>
+            </ul>
+         </div>
+      </div>
+   </details>
 
-## Q: Document search (RAG) isn't returning expected results or any results.
+   <details class="latest-release-archive-panel">
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q2</span>
+            <strong>Can I use Azure OpenAI and related services through private endpoints?</strong>
+            <small>Yes, but the app service must be able to resolve and reach those private addresses.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">Private networking</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--slate">
+            <h3>What to verify</h3>
+            <ul>
+               <li>Integrate the app service with a VNet that can reach the private endpoints for Azure OpenAI, AI Search, Cosmos DB, Storage, and any other required service.</li>
+               <li>Make sure private DNS zones or custom DNS resolve those endpoints to the expected private IP addresses.</li>
+               <li>Validate outbound connectivity from the app service, not just from an admin workstation.</li>
+            </ul>
+         </div>
+      </div>
+   </details>
+</section>
 
-   - **A:** Possible causes:
-     - **Indexing Status**: Check if the documents were successfully uploaded and processed. Look at the document status in "Your Workspace" or "Group Workspaces". Check File Processing Logs if enabled.
-     - **Azure AI Search**: Go to the Azure AI Search resource in the portal. Check the simplechat-user-index or simplechat-group-index. Do they contain documents? Are the document counts increasing after uploads? Use the Search explorer tool in the portal to test queries directly against the index.
-     - **Embedding Model**: Is the Embedding model configured correctly in Admin Settings and reachable? Errors during embedding will prevent indexing.
-     - **Search Query**: The quality of the search query matters. Ensure the "Search Documents" toggle is enabled in the chat UI. Try rephrasing your question.
+<div id="authentication-and-access"></div>
 
-## Q: How do I update the AI models (GPT, Embedding, DALL-E) used by the application?
+<section class="latest-release-section">
+   <div class="latest-release-section-header">
+      <div>
+         <div class="latest-release-section-kicker">Identity</div>
+         <h2>Authentication and access questions</h2>
+         <p>When sign-in or model management fails, start by confirming the identity plane before you assume the app itself is broken.</p>
+      </div>
+      <span class="latest-release-section-badge">Entra ID</span>
+   </div>
 
-   - **A:** Go to **Admin Settings**. Navigate to the relevant section (**GPT**, **Embeddings**, **Image Generation**). Use the interface to fetch available deployments from your configured Azure OpenAI endpoint(s) and select the desired deployment name(s). Save the settings. You don't need to redeploy the application code to change models if the endpoint remains the same.
+   <details class="latest-release-archive-panel">
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q3</span>
+            <strong>Users are getting authentication errors or cannot log in.</strong>
+            <small>Most login failures come from app registration or assignment drift.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">Access checks</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--blue">
+            <h3>What to verify</h3>
+            <ul>
+               <li>The redirect URI for `/.auth/login/aad/callback` is configured correctly in the Entra app registration.</li>
+               <li>App Service Authentication is enabled, points at the correct app registration, and is set to require authentication.</li>
+               <li>Users or groups are assigned to the enterprise application when assignment is required.</li>
+               <li>Microsoft Graph permissions such as `User.Read`, `openid`, and `profile` are configured and have admin consent.</li>
+               <li>`TENANT_ID` and `CLIENT_ID` values in the app settings match the intended tenant and application.</li>
+            </ul>
+         </div>
+      </div>
+   </details>
 
-## Q: Can I use Azure OpenAI endpoints secured with Private Endpoints?
+   <details class="latest-release-archive-panel">
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q4</span>
+            <strong>Fetch Models fails when the authentication app registration is in a different tenant than Azure OpenAI.</strong>
+            <small>The data plane can still work even when cross-tenant management-plane model listing is blocked.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">Cross-tenant</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--orange">
+            <h3>Workaround</h3>
+            <ol>
+               <li>In Admin Settings under GPT, enable <strong>Use APIM instead of direct to Azure OpenAI endpoint</strong>.</li>
+               <li>Enter the Azure OpenAI endpoint URL, API version, and deployment name in the APIM fields instead of a true APIM proxy.</li>
+               <li>Save the settings and fetch models again.</li>
+            </ol>
+            <p class="mb-0">That route shifts model listing into the APIM-mode flow and avoids the cross-tenant management-plane enumeration failure.</p>
+         </div>
+         <img src="{{ '/images/cross_tenant-model_support.png' | relative_url }}" alt="Cross-tenant model support guidance screenshot." />
+      </div>
+   </details>
+</section>
 
-   - **A:** Yes, but it requires network integration. The App Service must be integrated with a Virtual Network (VNet) that has connectivity to the private endpoints of your Azure services (OpenAI, Search, Cosmos DB, etc.). This typically involves using App Service VNet Integration and configuring Private DNS Zones or custom DNS. Ensure the App Service's outbound traffic can resolve and reach the private endpoint IPs.
+<div id="uploads-and-search"></div>
 
-## Q: “Fetch Models” fails if my authentication app registration is in a different Azure AD tenant than my Azure OpenAI resource. What’s happening and how can I work around it?
+<section class="latest-release-section">
+   <div class="latest-release-section-header">
+      <div>
+         <div class="latest-release-section-kicker">Ingestion and retrieval</div>
+         <h2>Upload and search questions</h2>
+         <p>These problems usually come from permission gaps, failed indexing, or missing model configuration for embeddings and extraction.</p>
+      </div>
+      <span class="latest-release-section-badge">Grounding</span>
+   </div>
 
-   - **A:** Because your app registration (the “management-plane” identity) lives in Tenant B but your Azure OpenAI resource is in Tenant A, cross-tenant listing of deployed models is blocked by default. Data-plane calls (completions via managed identity) still work, but management-plane operations (model enumeration) will return a 403.
-   - **Workaround:**
-     1. In **Admin Settings → GPT**, enable **Use APIM instead of direct to Azure OpenAI endpoint**.
-     2. In the APIM fields, enter your **Azure OpenAI endpoint** URL, API version, and deployment name (instead of an actual APIM proxy).
-     3. Save and re-fetch models.
-         This causes the app to call the AOAI endpoint through the APIM-mode flow, bypassing the cross-tenant management-plane check and allowing model listing to succeed.
+   <details class="latest-release-archive-panel">
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q5</span>
+            <strong>File uploads are failing.</strong>
+            <small>Start by checking the dependent services the pipeline writes to during ingestion.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">Uploads</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--emerald">
+            <h3>What to verify</h3>
+            <ul>
+               <li>The app service has permission to reach AI Search, Document Intelligence, Storage, Speech, Video Indexer, and any other enabled service in the upload path.</li>
+               <li>Managed identity role assignments or configured keys are valid and match the services you enabled.</li>
+               <li>Application Insights and App Service logs show whether the failure happens during extraction, embedding, indexing, or storage.</li>
+               <li>File Processing Logs in Admin Settings can expose the exact stage that failed.</li>
+            </ul>
+         </div>
+      </div>
+   </details>
 
-   ![Cross-tenant Model Support](./images/cross_tenant-model_support.png)
+   <details class="latest-release-archive-panel">
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q6</span>
+            <strong>RAG is not returning expected results or any results.</strong>
+            <small>When search quality drops, verify indexing and embeddings before tuning prompts.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">Search</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--teal">
+            <h3>What to verify</h3>
+            <ul>
+               <li>Uploaded documents finished processing successfully in the workspace UI.</li>
+               <li>The relevant Azure AI Search index contains the documents you expect and its count increases after uploads.</li>
+               <li>The embedding deployment is configured correctly and reachable from the application.</li>
+               <li>The Search Documents toggle is enabled in the chat UI and the user question is phrased in a way that maps to indexed content.</li>
+            </ul>
+         </div>
+      </div>
+   </details>
+</section>
+
+<div id="model-configuration"></div>
+
+<section class="latest-release-section">
+   <div class="latest-release-section-header">
+      <div>
+         <div class="latest-release-section-kicker">Configuration</div>
+         <h2>Model management questions</h2>
+         <p>These checks matter when the application loads but the configured AI capabilities do not behave the way you expect.</p>
+      </div>
+      <span class="latest-release-section-badge">Admin settings</span>
+   </div>
+
+   <details class="latest-release-archive-panel">
+      <summary>
+         <span class="latest-release-archive-summary-copy">
+            <span class="latest-release-section-kicker">Q7</span>
+            <strong>How do I update the GPT, embedding, or DALL-E models used by the application?</strong>
+            <small>Model selection is handled through admin configuration rather than code deployment.</small>
+         </span>
+         <span class="latest-release-archive-toggle">
+            <span class="latest-release-archive-version">Model updates</span>
+            <span class="latest-release-archive-toggle-text">Open answer</span>
+         </span>
+      </summary>
+      <div class="latest-release-archive-body">
+         <div class="latest-release-note-panel latest-release-accent--slate">
+            <h3>What to do</h3>
+            <ul>
+               <li>Open <strong>Admin Settings</strong>.</li>
+               <li>Go to the GPT, Embeddings, or Image Generation section that matches the model you want to change.</li>
+               <li>Fetch the available deployments from the configured Azure OpenAI endpoint and select the desired deployment name.</li>
+               <li>Save the settings. A code redeploy is not required when the endpoint stays the same.</li>
+            </ul>
+         </div>
+      </div>
+   </details>
+</section>
diff --git a/docs/features.md b/docs/features.md
index 21dba4d4..4297f39d 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -1,210 +1,299 @@
 ---
-layout: page
+layout: showcase-page
 title: "Features"
-description: "Comprehensive overview of Simple Chat's features and capabilities"
+description: "A structured view of the Simple Chat experience, from core workspace flows to optional feature packs and the Azure services behind them."
 section: "Overview"
+accent: orange
+eyebrow: "Capability Map"
+hero_icons:
+  - bi-stars
+  - bi-grid-3x3-gap
+  - bi-shield-check
+hero_pills:
+  - Core workspace experience
+  - Optional admin-enabled packs
+  - Azure-native services
+hero_links:
+  - label: "See latest release highlights"
+    url: /latest-release/
+    style: primary
+  - label: "Review admin configuration"
+    url: /admin_configuration/
+    style: outline
 ---
 
-# Simple Chat - Features
-
-- [Features](#features)
-- [Architecture Diagram](#architecture-diagram)
-- [Optional Features](#optional-features)
-  - [Redis Cache](#redis-cache-azure-cache-for-redis)
-  - [Content Safety](#content-safety)
-  - [Your Workspaces](#your-workspaces)
-  - [My Groups](#my-groups-includes-group-workspaces)
-  - [User Feedback](#user-feedback)
-  - [Conversation Archiving](#conversation-archiving)
-  - [Video Extraction](#video-extraction-video-indexer)
-  - [Audio Extraction](#audio-extraction-speech-service)
-  - [Document Classification](#document-classification)
-  - [Enhanced Citation](#enhanced-citation-storage-account)
-  - [Metadata Extraction](#metadata-extraction)
-  - [File Processing Logs](#file-processing-logs)
-- [Return to Main](../README.md)
-
-## Features
-
--   **Chat with AI**: Interact with an AI model based on Azure OpenAI’s GPT models.
--   **RAG with Hybrid Search**: Upload documents and perform hybrid searches (vector + keyword), retrieving relevant information from your files to augment AI responses.
--   **Document Management**: Upload, store, and manage multiple versions of documents—personal ("Your Workspace") or group-level ("Group Workspaces").
--   **Group Management**: Create and join groups to share access to group-specific documents, enabling collaboration with Role-Based Access Control (RBAC).
--   **Ephemeral (Single-Convo) Documents**: Upload temporary documents available only during the current chat session, without persistent storage in Azure AI Search.
--   **Conversation Archiving (Optional)**: Retain copies of user conversations—even after deletion from the UI—in a dedicated Cosmos DB container for audit, compliance, or legal requirements.
--   **Content Safety (Optional)**: Integrate Azure AI Content Safety to review every user message *before* it reaches AI models, search indexes, or image generation services. Enforce custom filters and compliance policies, with an optional `SafetyAdmin` role for viewing violations.
--   **Feedback System (Optional)**: Allow users to rate AI responses (thumbs up/down) and provide contextual comments on negative feedback. Includes user and admin dashboards, governed by an optional `FeedbackAdmin` role.
--   **Image Generation (Optional)**: Enable on-demand image creation using Azure OpenAI's DALL-E models, controlled via Admin Settings.
--   **Video Extraction (Optional)**: Utilize Azure Video Indexer to transcribe speech and perform Optical Character Recognition (OCR) on video frames. Segments are timestamp-chunked for precise retrieval and enhanced citations linking back to the video timecode.
--   **Audio Extraction (Optional)**: Leverage Azure Speech Service to transcribe audio files into timestamped text chunks, making audio content searchable and enabling enhanced citations linked to audio timecodes.
--   **Document Classification (Optional)**: Admins define custom classification types and associated colors. Users tag uploaded documents with these labels, which flow through to AI conversations, providing lineage and insight into data sensitivity or type.
--   **Enhanced Citation (Optional)**: Store processed, chunked files in Azure Storage (organized into user- and document-scoped folders). Display interactive citations in the UI—showing page numbers or timestamps—that link directly to the source document preview.
--   **Metadata Extraction (Optional)**: Apply an AI model (configurable GPT model via Admin Settings) to automatically generate keywords, two-sentence summaries, and infer author/date for uploaded documents. Allows manual override for richer search context.
--   **File Processing Logs (Optional)**: Enable verbose logging for all ingestion pipelines (workspaces and ephemeral chat uploads) to aid in debugging, monitoring, and auditing file processing steps.
--   **Redis Cache (Optional)**: Integrate Azure Cache for Redis to provide a distributed, high-performance session store. This enables true horizontal scaling and high availability by decoupling user sessions from individual app instances.
--   **Authentication & RBAC**: Secure access via Azure Active Directory (Entra ID) using MSAL. Supports Managed Identities for Azure service authentication, group-based controls, and custom application roles (`Admin`, `User`, `CreateGroup`, `SafetyAdmin`, `FeedbackAdmin`).
--   **Backend Services**:
-    -   **Azure Cosmos DB**: Stores conversations, document metadata, user/group information, settings, and optionally archived chats and feedback.
-    -   **Azure AI Search**: Powers efficient hybrid search and retrieval over personal and group documents.
-    -   **Azure AI Document Intelligence**: Extracts text, layout, and structured data from PDFs, Office files, images, and more during ingestion.
-    -   **Azure Cache for Redis**: (Optional) Provides a distributed cache for session data, enabling seamless scaling and improved reliability.
-
--   **Supported File Types**:
-    -   Text: `txt`, `md`, `html`, `json`
-    *   Documents: `pdf`, `docx`, `pptx`, `xlsx`, `xlsm`, `xls`, `csv`
-    *   Images: `jpg`, `jpeg`, `png`, `bmp`, `tiff`, `tif`, `heif` (processed via Document Intelligence OCR)
-    *   Video: `mp4`, `mov`, `avi`, `wmv`, `mkv`, `webm` (requires Video Indexer)
-    *   Audio: `mp3`, `wav`, `ogg`, `aac`, `flac`, `m4a` (requires Speech Service)
-
-## Architecture Diagram
-
-> <a href="#simple-chat---features" style="text-decoration: none;">Return to top</a>
-
-![Architecture](./images/architecture.png)
-
-## Optional Features
-
-> <a href="#simple-chat---features" style="text-decoration: none;">Return to top</a>
-
-### **Redis Cache (Azure Cache for Redis)**
-
-Enabling Redis Cache provides a distributed, high-performance session store for the application. This is essential for supporting horizontal scaling (scale out) and high availability in enterprise deployments. By storing user session data in Redis, all app instances can access and update sessions consistently, eliminating issues with session stickiness and enabling seamless load balancing.
-
--   **Enables true horizontal scaling** by decoupling user sessions from individual app instances.
--   **Improves reliability and availability** by providing a central, resilient cache for session data.
--   **Reduces login issues** (such as infinite login loops) when running multiple app instances behind a load balancer.
--   **Supports high concurrency** and fast session access, critical for large user bases.
--   **Configurable authentication**: Supports Access Keys or Entra ID (Managed Identity) for secure access.
-
-> **When to enable:** Enable Redis Cache if you plan to scale out the application to multiple App Service instances, require high availability, or want to future-proof your deployment for enterprise workloads.
-
-### **Content Safety**
-
-Ensures governance and security by reviewing all user messages before they interact with any service, including AI models, document search, web search, and image generation. This feature allows organizations to enforce custom filters and compliance policies, mitigating risks associated with harmful content or policy violations while maintaining a safe and controlled user experience.
-
--   **Prevents inappropriate content** from being processed, generated, or retrieved.
--   **Aids compliance** with organizational policies, industry regulations, and responsible AI principles.
--   **Enhances security** by filtering potentially malicious or sensitive queries before they interact with external systems or internal data.
--   **Optional RBAC** (`SafetyAdmin` App Role) restricts access to the Safety Violation Admin View, allowing designated personnel to review flagged content.
-
-| ![Content Safety - Settings](./images/content_safety-settings.png) | ![Content Safety - In Action](./images/content_safety-in_action.png) | ![Content Safety - Cosmos Container](./images/content_safety-cosmos_container.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| ![Content Safety - Management](./images/content_safety-management.png) | ![Content Safety - Taking Action](./images/content_safety-taking_action.png) | ![Content Safety - User View](./images/content_safety-user_view.png) |
-
-### **Your Workspaces**
-
-**Your Workspace** enhances individual productivity by allowing users to upload, manage, and utilize their personal documents as context for Azure OpenAI. It centralizes important files and prompts, eliminating repetitive uploads and copy-pasting. When enabled, the AI can reference these documents, leading to more relevant, personalized, and contextually accurate responses for tasks like summarizing reports, drafting emails, or brainstorming.
-
--   **Centralized hub** for personal documents and frequently used prompts, making them easily accessible.
--   **Improved AI context** by enabling Azure OpenAI to "see" user-specific documents, resulting in tailored and accurate responses.
--   **Time-saving** by storing crucial information once for repeated use across multiple chat sessions.
-
-| ![Admin Settings - Enable Workspace](./images/admin_settings-enable_workspace.png) | ![Workspace - Document List](./images/workspace-doc_list.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| ![Workspace - Prompt list](./images/workspace-prompt_list.png) | ![Workspace - Edit Prompt](./images/workspace-prompt_edit.png) |
-
-### **My Groups (includes Group Workspaces)**
-
-Facilitates teamwork by enabling users to create or join groups where documents and prompts can be shared securely. This creates a shared knowledge base, ensuring team members are aligned and can leverage the same information for AI-driven tasks. It reduces redundant explanations and email chains, allowing teams to collaborate efficiently and obtain consistent, AI-generated insights based on collective resources.
-
--   **Shared knowledge base** ensures team alignment with up-to-date, common resources.
--   **Streamlined collaboration** on documents and prompts, reducing repetitive tasks and communication overhead.
--   **Consistent AI responses** across the team by referencing identical data and prompt sets, minimizing misinformation.
--   **Optional RBAC** (`CreateGroup` App Role) can be enforced to control which users have permission to create new groups.
-
-| ![Admin Settings - Enable Groups](./images/admin_settings-enable_groups.png) | ![App Registration - App Role - Create Group](./images/app_reg-app_role-create_group.png) | ![Enterprise App - Add user to Create Group role](./images/enterprise_app-add_user_to_role.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| ![My Groups - Group list](./images/my_groups-group_list.png) | ![My Groups - Find group - Request to join](./images/my_groups-find_group-request_to_join.png) | ![Manage Group - Group details as owner](./images/manage_group-group_details_as_owner.png) |
-| ![Manage Group - Add member](./images/manage_group-add_member.png) | ![Manage Group - Assign member role](./images/manage_group-update_member_role.png) | ![Group Workspace - Document list](./images/group_workspace-doc_list.png) |
-
-### **User Feedback**
-
-Provides a mechanism for end-users to offer direct feedback on the quality and relevance of AI-generated responses. This feedback loop is crucial for monitoring model performance, identifying areas for improvement, and understanding user satisfaction.
-
--   **Simple rating system** (Thumbs up/down) for quick assessment of AI replies.
--   **Contextual comments** prompted upon a thumbs-down selection, allowing users to specify issues.
--   **User dashboard** for individuals to review their submitted feedback history.
--   **Admin dashboard** for aggregating, reviewing, and acting upon feedback. Access is controlled by **Optional RBAC** (`FeedbackAdmin` App Role).
-
-| ![Admin Settings - Enable User Feedback](./images/admin_settings-enable_user_feedback.png) | ![Chat - Negative Feedback](./images/chat-feedback-negative.png) | ![Feedback Review - List all](./images/feedback_review-list_all.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| ![Feedback Review - Feedback review workflow](./images/feedback_review-workflow.png) | ![My feedback - List all](./images/my_feedback-list_all.png) | ![My feedback - View specific](./images/my_feedback-view_specific.png) |
-
-### **Conversation Archiving**
-
-Addresses compliance and record-keeping needs by automatically retaining a copy of all user conversations in a separate Cosmos DB container, even if users delete them from their chat history interface.
-
--   **Dedicated archive container** in Cosmos DB ensures separation from live conversation data.
--   **Post-deletion retention** guarantees that chats removed from the user history remain available for audit or legal discovery.
--   **Supports policy compliance** for regulatory, legal, or internal organizational record-keeping requirements.
-
-| ![Admin Settings - Enable Conversation Archiving](./images/admin_settings-enable_conversation_archiving.png) | ![Chat - Delete conversation](./images/chat-delete_conversation.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| ![Cosmos container - View archived conversation](./images/cosmos_container-view_archived_conversation.png) | ![Cosmos container - View archived messages](./images/cosmos_container-view_archived_messages.png) |
-
-### **Video Extraction (Video Indexer)**
-
-Unlocks the value within video files by using Azure Video Indexer to transcribe spoken words and extract text visible on screen (OCR). This makes video content searchable and citable within the chat application.
-
--   **Comprehensive text extraction** from both audio tracks (transcription) and visual elements (OCR).
--   **Timestamp-based chunking** segments the extracted text, tagging each chunk with its start time in the video for precise retrieval.
--   **Enhanced citations** in chat responses link directly to the specific time point in the video source.
--   **Integrates seamlessly** with the application's document storage, search, and citation workflow.
-
-| ![Admin settings - Enable Video file support](./images/admin_settings-enable_video_file_support.png) | ![Workspace - Upload and process video file](./images/workflow-upload_video_file.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-
-### **Audio Extraction (Speech Service)**
-
-Leverages Azure Speech Service to automatically transcribe audio files, converting spoken content into searchable and citable text.
-
--   **Accurate transcription** of various uploaded audio formats.
--   **Timestamped text chunks** enable precise linking of citations back to the specific moment in the audio file.
--   **Enhanced citation support** allows users to click a citation and potentially jump to (or reference) the relevant audio timestamp.
-
-| ![Admin settings - Enable audio file support](./images/admin_settings-enable_audio_file_support.png) | ![Workspace - Upload and process audio file](./images/workflow-upload_process_audio_file.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-
-### **Document Classification**
-
-Allows organizations to categorize documents based on sensitivity, type, or other criteria defined by administrators. These classifications persist throughout the application, providing context and aiding governance.
-
--   **Admin-defined classification types** with customizable labels and visual color-coding.
--   **User-assigned labels** applied during the document upload process.
--   **Classification propagation** ensures that tags associated with referenced documents appear in the chat context, indicating the nature of the source data.
--   **Improved insights** into how different types of documents are being used and referenced in AI interactions.
-
-| ![Admin settings - Enable and configure Document classification](./images/admin_settings-enable_and_configure_doc_classification.png) | ![Workspace - View and update classification](./images/workflow-view_and_update_classification.png) | ![Chat - Classification propagation](./images/chat-classification_propagation.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-
-### **Enhanced Citation (Storage Account)**
-
-Provides a richer citation experience by storing processed document chunks in Azure Storage and enabling interactive citations that link directly to the source content (e.g., specific page or timestamp).
-
--   **Structured Azure Storage**: Organizes processed files into user-specific and document-specific folders.
--   **Metadata linkage**: Connects files in Azure Storage with their corresponding document records in Cosmos DB.
--   **Rich UI citations**: Displays page numbers (for documents) or timestamps (for video/audio) alongside document previews within the chat interface.
--   **Direct navigation**: Allows users to click citations to view the original content source, improving transparency and trust.
-
-### **Metadata Extraction**
-
-Uses AI (a configurable GPT model) to automatically enrich uploaded documents with relevant metadata, improving search relevance and providing better context for AI responses.
-
--   **Configurable AI model**: Administrators select the GPT model used for extraction via Admin Settings.
--   **Automated generation**: Extracts keywords, creates concise two-sentence summaries, and infers potential author and creation dates.
--   **Improved searchability**: Generated metadata enhances the information available to Azure AI Search, leading to more relevant results.
--   **Manual override**: Users can manually edit or provide their own metadata if the AI-generated content needs correction or refinement.
-
-| ![Admin settings - Enable Enhanced citations](./images/admin_settings-enable_enhanced_citations.png) | ![Workspace - Enhanced citation tag](./images/workspace-enhanced_citation_tag.png) | ![Storage account - View documents for citation retrieval](./images/storage_account-view_doc_for_citation_retrieval.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-
-### **File Processing Logs**
-
-Enables detailed logging for the entire file ingestion and processing pipeline, assisting administrators and developers in troubleshooting issues, monitoring performance, and auditing activity.
-
--   **Granular logging**: Captures step-by-step details of document ingestion, chunking, embedding, and indexing processes.
--   **Error diagnostics**: Helps pinpoint failures or bottlenecks in the ingestion or AI-driven extraction steps.
--   **Admin control**: Verbosity can be toggled on or off via Admin Settings, allowing control over logging volume.
-
-| ![Admin settings - Enable File processing logs](./images/admin_settings-enable_file_processing_logs.png) | ![Cosmos container - View specific document's file processing logs](./images/cosmos_container-view_specific_doc_file_processing_logs.png) |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
+Simple Chat starts with a grounded chat experience, then expands through optional modules for governance, media processing, feedback loops, advanced citations, and operational scale.
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Core experience</div>
+      <h2>What ships with the day-one product surface</h2>
+      <p>These are the capabilities most teams use immediately after deployment.</p>
+    </div>
+    <span class="latest-release-section-badge">Always relevant</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-chat-dots"></i></span>
+          <span class="latest-release-card-badge">Conversation</span>
+        </div>
+        <h3 class="latest-release-card-title">Chat with AI</h3>
+        <p class="latest-release-card-summary">Interact with Azure OpenAI deployments through a workspace-aware chat surface built for grounded answers, prompt reuse, and iterative conversations.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--teal">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-search"></i></span>
+          <span class="latest-release-card-badge">Retrieval</span>
+        </div>
+        <h3 class="latest-release-card-title">RAG with hybrid search</h3>
+        <p class="latest-release-card-summary">Combine vector and keyword retrieval over uploaded files so chat responses can pull directly from the indexed document set.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-folder2-open"></i></span>
+          <span class="latest-release-card-badge">Workspaces</span>
+        </div>
+        <h3 class="latest-release-card-title">Personal and group document management</h3>
+        <p class="latest-release-card-summary">Upload, version, organize, and reuse files in personal workspaces or share them through group workspaces with role-aware access control.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-clock-history"></i></span>
+          <span class="latest-release-card-badge">Session scope</span>
+        </div>
+        <h3 class="latest-release-card-title">Ephemeral chat uploads</h3>
+        <p class="latest-release-card-summary">Attach single-conversation documents when you need temporary grounding without committing those files to persistent search indexes.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-person-lock"></i></span>
+          <span class="latest-release-card-badge">Access</span>
+        </div>
+        <h3 class="latest-release-card-title">Authentication and RBAC</h3>
+        <p class="latest-release-card-summary">Secure the app with Entra ID, managed identities, and app roles such as Admin, User, CreateGroup, SafetyAdmin, and FeedbackAdmin.</p>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Optional capability packs</div>
+      <h2>Modules you can enable as the rollout matures</h2>
+      <p>These features are designed to layer onto the base experience through admin settings and supporting Azure services.</p>
+    </div>
+    <span class="latest-release-section-badge">Admin controlled</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--rose">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-shield-check"></i></span>
+          <span class="latest-release-card-badge">Governance</span>
+        </div>
+        <h3 class="latest-release-card-title">Content safety and policy controls</h3>
+        <p class="latest-release-card-summary">Review user prompts before they reach AI models, search, or image generation and give designated reviewers a place to inspect flagged activity.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-images"></i></span>
+          <span class="latest-release-card-badge">Generation</span>
+        </div>
+        <h3 class="latest-release-card-title">Image generation and live web results</h3>
+        <p class="latest-release-card-summary">Add DALL-E powered image creation and Bing-powered web search when your users need current results or generated visuals inside the same app.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--teal">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-camera-video"></i></span>
+          <span class="latest-release-card-badge">Media</span>
+        </div>
+        <h3 class="latest-release-card-title">Video and audio extraction</h3>
+        <p class="latest-release-card-summary">Transcribe media, capture timestamps, and turn recordings into searchable assets with citations that can point back to the right moment.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-tags"></i></span>
+          <span class="latest-release-card-badge">Document context</span>
+        </div>
+        <h3 class="latest-release-card-title">Classification, metadata, and enhanced citations</h3>
+        <p class="latest-release-card-summary">Add labels, AI-generated summaries, author/date inference, and source-linked previews so users can understand where an answer came from.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-hand-thumbs-up"></i></span>
+          <span class="latest-release-card-badge">Feedback + retention</span>
+        </div>
+        <h3 class="latest-release-card-title">User feedback and conversation archiving</h3>
+        <p class="latest-release-card-summary">Collect structured sentiment on responses and, when needed, retain conversations in a dedicated archive for audit and compliance workflows.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-hdd-network"></i></span>
+          <span class="latest-release-card-badge">Scale + extensibility</span>
+        </div>
+        <h3 class="latest-release-card-title">Redis cache, SQL agents, and processing logs</h3>
+        <p class="latest-release-card-summary">Scale session handling, inspect ingestion activity, and connect agent workflows to SQL data sources through configurable plugins.</p>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Platform services</div>
+      <h2>Azure building blocks behind the product</h2>
+      <p>Simple Chat is opinionated about which Azure services handle which part of the workload.</p>
+    </div>
+    <span class="latest-release-section-badge">Service map</span>
+  </div>
+
+  <div class="latest-release-note-panel latest-release-accent--orange">
+    <h3>Primary service roles</h3>
+    <ul>
+      <li><strong>Azure Cosmos DB</strong> stores conversations, metadata, settings, user and group records, and optional archive or feedback data.</li>
+      <li><strong>Azure AI Search</strong> powers hybrid retrieval across indexed personal and group content.</li>
+      <li><strong>Azure AI Document Intelligence</strong> extracts text and layout from uploaded files during ingestion.</li>
+      <li><strong>Azure OpenAI</strong> handles chat completions, embeddings, optional image generation, and AI-driven metadata extraction.</li>
+      <li><strong>Azure Storage</strong> supports enhanced citation content and related document assets.</li>
+      <li><strong>Azure Cache for Redis</strong> is optional and becomes important when you need horizontal scale with shared sessions.</li>
+    </ul>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Supported inputs</div>
+      <h2>File types the platform is built to understand</h2>
+      <p>Exact behavior depends on which optional extraction features you enable, but these are the main content categories the app is designed around.</p>
+    </div>
+    <span class="latest-release-section-badge">Coverage</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-filetype-txt"></i></span>
+          <span class="latest-release-card-badge">Text</span>
+        </div>
+        <h3 class="latest-release-card-title">Structured and plain text</h3>
+        <p class="latest-release-card-summary">`txt`, `md`, `html`, `json`, `xml`, `yaml`, `yml`, and `log` files fit the basic ingestion pipeline well.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-file-earmark-richtext"></i></span>
+          <span class="latest-release-card-badge">Documents</span>
+        </div>
+        <h3 class="latest-release-card-title">Office and tabular documents</h3>
+        <p class="latest-release-card-summary">`pdf`, `doc`, `docm`, `docx`, `pptx`, `xlsx`, `xlsm`, `xls`, and `csv` cover the common enterprise file set.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-image"></i></span>
+          <span class="latest-release-card-badge">Images</span>
+        </div>
+        <h3 class="latest-release-card-title">Image ingestion with OCR support</h3>
+        <p class="latest-release-card-summary">`jpg`, `jpeg`, `png`, `bmp`, `tiff`, `tif`, and `heif` can be processed through document analysis and OCR-aware workflows.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--teal">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-film"></i></span>
+          <span class="latest-release-card-badge">Media</span>
+        </div>
+        <h3 class="latest-release-card-title">Audio and video formats</h3>
+        <p class="latest-release-card-summary">`mp4`, `mov`, `avi`, `wmv`, `mkv`, `webm`, `mp3`, `wav`, `ogg`, `aac`, `flac`, and `m4a` become searchable when the related media services are enabled.</p>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Visual reference</div>
+      <h2>Architecture and admin surface</h2>
+      <p>The deployment architecture and admin settings page are usually the fastest way to explain how the feature set is organized.</p>
+    </div>
+    <span class="latest-release-section-badge">Screens</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <button
+          type="button"
+          class="latest-release-card-image latest-release-thumbnail-trigger"
+          data-latest-feature-image-src="{{ '/images/architecture.png' | relative_url }}"
+          data-latest-feature-image-title="Architecture overview"
+          data-latest-feature-image-caption="Architecture diagram showing how App Service, Azure OpenAI, AI Search, Cosmos DB, and storage fit together."
+          aria-label="Open architecture overview image"
+        >
+          <img src="{{ '/images/architecture.png' | relative_url }}" alt="Architecture diagram for Simple Chat on Azure." />
+        </button>
+        <h3 class="latest-release-card-title">Architecture overview</h3>
+        <p class="latest-release-card-summary">Use this diagram when you need to explain how App Service, Azure OpenAI, AI Search, Cosmos DB, and storage fit together.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <button
+          type="button"
+          class="latest-release-card-image latest-release-thumbnail-trigger"
+          data-latest-feature-image-src="{{ '/images/admin_settings_page.png' | relative_url }}"
+          data-latest-feature-image-title="Admin configuration surface"
+          data-latest-feature-image-caption="Admin Settings page showing the central control surface for branding, models, workspaces, and optional feature packs."
+          aria-label="Open admin configuration surface image"
+        >
+          <img src="{{ '/images/admin_settings_page.png' | relative_url }}" alt="Admin settings page for Simple Chat." />
+        </button>
+        <h3 class="latest-release-card-title">Admin configuration surface</h3>
+        <p class="latest-release-card-summary">Most optional features are exposed through the admin settings experience, which keeps rollout decisions in one operational surface.</p>
+      </div>
+    </article>
+  </div>
+</section>
diff --git a/docs/how-to/add_documents.md b/docs/how-to/add_documents.md
index e69de29b..66cc618b 100644
--- a/docs/how-to/add_documents.md
+++ b/docs/how-to/add_documents.md
@@ -0,0 +1,83 @@
+---
+layout: showcase-page
+title: "Add Documents"
+permalink: /how-to/add_documents/
+menubar: docs_menu
+accent: blue
+eyebrow: "How-To Guide"
+description: "Use this guide when you need a practical, repeatable workflow for adding files to personal, group, or public workspaces and making them searchable."
+hero_icons:
+  - bi-file-earmark-arrow-up
+  - bi-folder2-open
+  - bi-search
+hero_pills:
+  - Personal, group, and public scopes
+  - Searchable after processing completes
+  - Classification and citations supported
+hero_links:
+  - label: "Document tutorial"
+    url: /tutorials/uploading_documents/
+    style: primary
+  - label: "Admin overview"
+    url: /admin_configuration/
+    style: secondary
+---
+
+Treat uploads as an ingestion workflow, not just a file transfer. The target workspace, enabled services, and metadata choices determine whether the file becomes grounded chat context, searchable workspace content, or an item waiting on a missing dependency.
+
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-folder2-open"></i></div>
+				<h2>Choose the right workspace</h2>
+				<p>Upload into the personal, group, or public scope that matches who should discover and cite the file later.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-file-earmark-check"></i></div>
+				<h2>Prepare a clean source file</h2>
+				<p>Clear filenames, readable text, and well-structured documents make extraction, chunking, and retrieval more reliable.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-hourglass-split"></i></div>
+				<h2>Wait for processing to finish</h2>
+				<p>Uploads are only useful for grounding after extraction, indexing, and metadata processing complete successfully.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+				<h2>Verify searchability</h2>
+				<p>Test retrieval from the workspace UI or chat flow so you know the document is ready before relying on it in user workflows.</p>
+		</article>
+</section>
+
+<div class="latest-release-note-panel">
+		<h2>Uploads depend on the search and extraction stack</h2>
+		<p>If workspace grounding is enabled, document ingestion usually depends on embeddings, Azure AI Search, and Document Intelligence being configured correctly. Optional features like enhanced citations, speech, or video support add more dependencies on top of that core path.</p>
+</div>
+
+## Recommended upload flow
+
+1. Pick the destination workspace based on who should be able to discover the file.
+2. Confirm the file type is supported and the document is readable enough for extraction.
+3. Upload the file and watch for processing completion in the workspace experience.
+4. Add or verify metadata such as classification, title, or extraction results when your environment uses them.
+5. Run a search or grounded chat prompt to confirm the document is discoverable.
+
+## Metadata choices that improve retrieval
+
+- Use descriptive filenames so citations are meaningful.
+- Apply document classification when the workspace relies on category-based filtering.
+- Review extracted fields if the environment surfaces metadata extraction results.
+- Keep duplicates and outdated copies under control so retrieval does not split relevance across nearly identical files.
+
+## When a file uploads but does not show up in chat
+
+- Verify the workspace type you uploaded to matches the scope you are searching.
+- Confirm the document finished processing rather than remaining in an in-progress or failed state.
+- Check that embeddings, Azure AI Search, and Document Intelligence are configured if the environment uses grounded retrieval.
+- Review the admin settings for file-type restrictions, classification requirements, or disabled workspace features.
+
+## Related guides
+
+- [Uploading and Managing Documents](../tutorials/uploading_documents.md)
+- [Document Classification Tutorial](../tutorials/classifying_documents.md)
+- [Application Workflows](../application_workflows.md)
+- [Troubleshooting](../troubleshooting/troubleshooting.md)
diff --git a/docs/how-to/agents/ServiceNow/SERVICENOW_ASSET_MANAGEMENT_SETUP.md b/docs/how-to/agents/ServiceNow/SERVICENOW_ASSET_MANAGEMENT_SETUP.md
index e99f67f7..713f3837 100644
--- a/docs/how-to/agents/ServiceNow/SERVICENOW_ASSET_MANAGEMENT_SETUP.md
+++ b/docs/how-to/agents/ServiceNow/SERVICENOW_ASSET_MANAGEMENT_SETUP.md
@@ -1,6 +1,45 @@
-# ServiceNow Asset Management Agent Setup Guide
+---
+layout: showcase-page
+title: "ServiceNow Asset Management Setup"
+permalink: /how-to/agents/ServiceNow/servicenow_asset_management_setup/
+menubar: docs_menu
+accent: orange
+eyebrow: "How-To Guide"
+description: "Set up a ServiceNow asset-management agent with separate actions for querying, creating, updating, and deleting records in the `alm_asset` table."
+hero_icons: ["bi-pc-display-horizontal", "bi-database-gear", "bi-arrow-repeat"]
+hero_pills: ["Four-action asset workflow", "Direct `alm_asset` table operations", "Query-first pattern for update and delete"]
+hero_links: [{ label: "ServiceNow guides", url: "/how-to/agents/ServiceNow/", style: "primary" }, { label: "OAuth setup", url: "/how-to/agents/ServiceNow/servicenow_oauth_setup/", style: "secondary" }]
+---
 
-This guide walks through setting up a complete ServiceNow Asset Management agent with separate actions for querying, creating, updating, and deleting assets.
+This guide is for teams that want a dedicated asset-management agent instead of overloading a general ServiceNow support agent. It keeps query, create, update, and delete actions separate so each operation is easier to govern and debug.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-list-check"></i></div>
+      <h2>Four actions, one agent</h2>
+      <p>Query, create, update, and delete are modeled as separate actions so permissions, behavior, and troubleshooting stay explicit.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-hdd-stack"></i></div>
+      <h2>Direct asset record scope</h2>
+      <p>This setup works directly against the `alm_asset` table for actual hardware asset records rather than request or stockroom workflows.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-key"></i></div>
+      <h2>Shared authentication</h2>
+      <p>All four actions use the same ServiceNow integration user and bearer token, which simplifies action setup while keeping the service account dedicated.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-exclamation-triangle"></i></div>
+      <h2>Query before mutating</h2>
+      <p>Updates and deletes should always resolve the `sys_id` first, then perform the mutation. That two-call pattern is the safety boundary for this setup.</p>
+   </article>
+</section>
+
+<div class="latest-release-note-panel">
+   <h2>Use this when assets are the real business object</h2>
+   <p>If your workflow is about formal requests, transfers, or stock operations, build separate actions for those tables instead. This guide is intentionally narrower and better for that reason.</p>
+</div>
 
 ## Overview
 
diff --git a/docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md b/docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md
index 91764088..a4376a66 100644
--- a/docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md
+++ b/docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md
@@ -1,7 +1,48 @@
-# ServiceNow Integration Guide
+---
+layout: showcase-page
+title: "ServiceNow Integration"
+permalink: /how-to/agents/ServiceNow/servicenow_integration/
+menubar: docs_menu
+accent: blue
+eyebrow: "How-To Guide"
+description: "Configure the standard single-agent ServiceNow integration for incident management and read-only knowledge-base search in Simple Chat."
+hero_icons: ["bi-life-preserver", "bi-plug", "bi-search"]
+hero_pills: ["Single-agent support pattern", "Incident management + KB search", "Global or group-scoped rollout"]
+hero_links: [{ label: "ServiceNow guides", url: "/how-to/agents/ServiceNow/", style: "primary" }, { label: "OAuth setup", url: "/how-to/agents/ServiceNow/servicenow_oauth_setup/", style: "secondary" }]
+---
+
+This is the default ServiceNow pattern for most teams. It gives you one support-focused agent backed by modular OpenAPI actions so users can manage incidents and search KB content without splitting responsibilities across multiple agents.
+
+<section class="latest-release-card-grid">
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-person-workspace"></i></div>
+    <h2>One agent for standard support work</h2>
+    <p>Keep the operating model simple when the main need is incident CRUD plus read-only knowledge search.</p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-braces"></i></div>
+    <h2>Two OpenAPI actions</h2>
+    <p>Incident management and KB search stay as separate actions even though one agent uses both, which keeps the API surfaces clearer.</p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-shield-check"></i></div>
+    <h2>Scope by governance needs</h2>
+    <p>Global, group, and personal scope are all possible, but most enterprise setups should choose scope based on who is allowed to operate against ServiceNow.</p>
+  </article>
+  <article class="latest-release-card">
+    <div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+    <h2>Test the flow end to end</h2>
+    <p>Validation is not just API access. You should confirm incident queries, creates, updates, and KB search all work with the agent behavior you expect.</p>
+  </article>
+</section>
+
+<div class="latest-release-note-panel">
+  <h2>Start here unless permissions force you elsewhere</h2>
+  <p>If one support-facing agent is enough, use this guide. Move to the OAuth guide for production authentication, or the two-agent guide only when KB publishing and support operations need separate permissions and tokens.</p>
+</div>
 
 **Version:** 0.237.005  
-**Implemented in version:**0.237.005
+**Implemented in version:** 0.237.005
 
 ## Overview
 
diff --git a/docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md b/docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md
index 923788b8..e19e3a0e 100644
--- a/docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md
+++ b/docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md
@@ -1,4 +1,45 @@
-# ServiceNow OAuth 2.0 Setup for Simple Chat
+---
+layout: showcase-page
+title: "ServiceNow OAuth 2.0 Setup"
+permalink: /how-to/agents/ServiceNow/servicenow_oauth_setup/
+menubar: docs_menu
+accent: violet
+eyebrow: "How-To Guide"
+description: "Configure OAuth 2.0 bearer-token authentication for ServiceNow actions in Simple Chat using ServiceNow's current inbound integration flow."
+hero_icons: ["bi-key", "bi-shield-lock", "bi-arrow-repeat"]
+hero_pills: ["Bearer token auth", "Integration user + OAuth app credentials", "Production-oriented alternative to Basic Auth"]
+hero_links: [{ label: "ServiceNow integration", url: "/how-to/agents/ServiceNow/servicenow_integration/", style: "primary" }, { label: "Two-agent setup", url: "/how-to/agents/ServiceNow/two_agent_setup/", style: "secondary" }]
+---
+
+This guide matters when Basic Auth is not acceptable and you want a cleaner production authentication story for ServiceNow actions. The important idea is that OAuth setup here still depends on a dedicated ServiceNow user because the token executes with that user's permissions.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-person-badge"></i></div>
+      <h2>Create a dedicated integration user</h2>
+      <p>The OAuth token should represent a service identity with only the roles required for the ServiceNow operations you plan to expose.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-app-indicator"></i></div>
+      <h2>Create the OAuth application</h2>
+      <p>ServiceNow's inbound integration flow generates the client ID and client secret you need before Simple Chat can request bearer tokens.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-box-arrow-in-down"></i></div>
+      <h2>Obtain and store the token</h2>
+      <p>Use cURL, PowerShell, or Python to request the access token, then store it securely and plan for refresh before expiry becomes an outage.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-plug"></i></div>
+      <h2>Wire it into the action</h2>
+      <p>Once the token exists, the Simple Chat action configuration becomes straightforward: the bearer token is what the OpenAPI action sends on each request.</p>
+   </article>
+</section>
+
+<div class="latest-release-note-panel">
+   <h2>Both credential sets matter</h2>
+   <p>The token request needs the OAuth app credentials and the ServiceNow integration-user credentials. That is the easiest place to get confused, so keep those identities clearly separated as you configure the flow.</p>
+</div>
 
 **Version:** 0.237.005  
 **Implemented in version:** 0.237.005
diff --git a/docs/how-to/agents/ServiceNow/TWO_AGENT_SETUP.md b/docs/how-to/agents/ServiceNow/TWO_AGENT_SETUP.md
index 96ce09e3..ece56e4d 100644
--- a/docs/how-to/agents/ServiceNow/TWO_AGENT_SETUP.md
+++ b/docs/how-to/agents/ServiceNow/TWO_AGENT_SETUP.md
@@ -1,4 +1,45 @@
-# ServiceNow Two-Agent Setup Guide (Advanced KB Management)
+---
+layout: showcase-page
+title: "ServiceNow Two-Agent Setup"
+permalink: /how-to/agents/ServiceNow/two_agent_setup/
+menubar: docs_menu
+accent: teal
+eyebrow: "How-To Guide"
+description: "Use a split-agent ServiceNow design when incident handling and knowledge-base management need different roles, users, and approval boundaries."
+hero_icons: ["bi-people", "bi-journal-richtext", "bi-shield-lock"]
+hero_pills: ["Separate support and KB permissions", "Distinct integration users and tokens", "Approval-aware KB management"]
+hero_links: [{ label: "ServiceNow guides", url: "/how-to/agents/ServiceNow/", style: "primary" }, { label: "OAuth setup", url: "/how-to/agents/ServiceNow/servicenow_oauth_setup/", style: "secondary" }]
+---
+
+Use this pattern only when separation really helps. The value is not having more agents. The value is keeping support operations and KB publishing under different permission boundaries so governance and audit trails stay cleaner.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-life-preserver"></i></div>
+      <h2>Support agent stays narrow</h2>
+      <p>The first agent handles incidents and read-only KB search so day-to-day support work stays fast and low risk.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-journal-plus"></i></div>
+      <h2>KB manager agent owns publishing</h2>
+      <p>The second agent handles KB creation and publication workflows, which is where broader permissions and approval logic usually belong.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-key"></i></div>
+      <h2>Separate users and tokens</h2>
+      <p>Each agent gets its own ServiceNow integration user and bearer token so audit trails and least-privilege boundaries stay explicit.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-diagram-2"></i></div>
+      <h2>Workflow rules still apply</h2>
+      <p>If your ServiceNow KB approval flow requires portal interaction, the agent design must acknowledge that instead of pretending the API can bypass it.</p>
+   </article>
+</section>
+
+<div class="latest-release-note-panel">
+   <h2>Only choose this if one agent is not enough</h2>
+   <p>If the standard single-agent integration covers your needs, it is the better default. The split-agent design exists for governance, approval, and permission-boundary reasons, not because two agents are inherently better.</p>
+</div>
 
 **Version:** 0.237.005 
 **Implemented in version:** 0.237.005
diff --git a/docs/how-to/agents/ServiceNow/index.md b/docs/how-to/agents/ServiceNow/index.md
new file mode 100644
index 00000000..cc85c676
--- /dev/null
+++ b/docs/how-to/agents/ServiceNow/index.md
@@ -0,0 +1,61 @@
+---
+layout: showcase-page
+title: "ServiceNow Agent Guides"
+permalink: /how-to/agents/ServiceNow/
+menubar: docs_menu
+accent: slate
+eyebrow: "How-To Guide"
+description: "Use these guides to connect Simple Chat agents and actions to ServiceNow for incident handling, knowledge workflows, OAuth authentication, and asset management."
+hero_icons: ["bi-plug", "bi-life-preserver", "bi-database-gear"]
+hero_pills: ["Incident and KB integrations", "OAuth 2.0 authentication", "Single-agent and multi-agent patterns"]
+hero_links: [{ label: "Create agents", url: "/how-to/create_agents/", style: "primary" }, { label: "How-to index", url: "/how-to/", style: "secondary" }]
+---
+
+These guides are best read as a family. Start with the single-agent integration if you want the fastest path, move into OAuth when you need production authentication, then use the advanced guides only when your permissions or workflows demand more separation.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-life-preserver"></i></div>
+        <h2>Single-agent ServiceNow integration</h2>
+        <p>Use the standard support-agent guide for incident management and read-only KB search through one agent and two actions.</p>
+        <p><a href="{{ '/how-to/agents/ServiceNow/servicenow_integration/' | relative_url }}">Open integration guide</a></p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-key"></i></div>
+        <h2>OAuth 2.0 setup</h2>
+        <p>Use the OAuth guide when you need bearer-token authentication instead of Basic Auth for ServiceNow actions in production-style environments.</p>
+        <p><a href="{{ '/how-to/agents/ServiceNow/servicenow_oauth_setup/' | relative_url }}">Open OAuth guide</a></p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-people"></i></div>
+        <h2>Two-agent KB management</h2>
+        <p>Use the advanced split-agent design when incident handling and KB publishing need separate roles, tokens, and approval boundaries.</p>
+        <p><a href="{{ '/how-to/agents/ServiceNow/two_agent_setup/' | relative_url }}">Open two-agent guide</a></p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-pc-display-horizontal"></i></div>
+        <h2>Asset management agent</h2>
+        <p>Use the asset-management guide when you want a dedicated agent with separate query, create, update, and delete actions over the `alm_asset` table.</p>
+        <p><a href="{{ '/how-to/agents/ServiceNow/servicenow_asset_management_setup/' | relative_url }}">Open asset guide</a></p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>Pick the narrowest integration that fits</h2>
+    <p>Most teams should start with the single-agent support pattern. Add OAuth when security posture requires it, add the two-agent KB model when permissions diverge, and add asset management only when hardware lifecycle workflows belong inside the agent surface.</p>
+</div>
+
+## Shared supporting assets
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-filetype-yaml"></i></div>
+        <h2>OpenAPI specs</h2>
+        <p>The ServiceNow folder includes incident, knowledge-base, and asset-management specs for the actions described in these guides.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-journal-text"></i></div>
+        <h2>Agent instructions</h2>
+        <p>Instruction files for the support, KB management, and asset-management agents live beside the specs so action and prompt behavior stay aligned.</p>
+    </article>
+</section>
\ No newline at end of file
diff --git a/docs/how-to/azure_speech_managed_identity_manul_setup.md b/docs/how-to/azure_speech_managed_identity_manul_setup.md
index f991e02a..25044e16 100644
--- a/docs/how-to/azure_speech_managed_identity_manul_setup.md
+++ b/docs/how-to/azure_speech_managed_identity_manul_setup.md
@@ -1,8 +1,59 @@
-# Azure Speech Service with Managed Identity Manual Setup
+---
+layout: showcase-page
+title: "Azure Speech Managed Identity Setup"
+permalink: /how-to/azure_speech_managed_identity_manul_setup/
+menubar: docs_menu
+accent: blue
+eyebrow: "How-To Guide"
+description: "Configure Azure Speech for managed identity correctly by using the resource-specific endpoint, the right RBAC roles, and the matching Admin Settings fields."
+hero_icons:
+  - bi-mic
+  - bi-person-badge
+  - bi-globe2
+hero_pills:
+  - Custom subdomain required
+  - Regional endpoint fails with MI
+  - Speech User role first
+hero_links:
+  - label: "Managed identity guide"
+    url: /how-to/use_managed_identity/
+    style: primary
+  - label: "Admin configuration"
+    url: /reference/admin_configuration/
+    style: secondary
+---
 
-## Overview
+Speech is the place where managed identity setup becomes very specific. The most important rule is simple: the regional endpoint that works with keys is not enough for managed identity. You need the resource-specific custom-subdomain endpoint so Azure can evaluate RBAC against the correct Speech resource.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-globe2"></i></div>
+        <h2>Use the resource-specific endpoint</h2>
+        <p>Managed identity needs the custom-subdomain Speech endpoint, not the shared regional gateway endpoint used by key-based authentication.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-shield-check"></i></div>
+        <h2>Grant RBAC on the Speech resource</h2>
+        <p>Start with <code>Cognitive Services Speech User</code> and add <code>Cognitive Services Speech Contributor</code> only if the specific transcription flow still needs it.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-sliders"></i></div>
+        <h2>Fill the matching admin fields</h2>
+        <p>Endpoint, region, locale, authentication type, and resource ID all need to align with the Speech resource you are actually authorizing.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+        <h2>Test with a real audio workflow</h2>
+        <p>Validate with upload, transcription, and optional text-to-speech scenarios rather than stopping at a configuration save.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>The endpoint format is the root-cause difference</h2>
+    <p>With key authentication, the regional endpoint can infer the target resource from the key. With managed identity, Azure needs the hostname itself to identify the specific Speech resource so it can evaluate RBAC. That is why the custom subdomain is mandatory here.</p>
+</div>
 
-This guide explains the critical difference between key-based and managed identity authentication when configuring Azure Speech Service, and the required steps to enable managed identity properly. In Simple Chat, the same Speech configuration is shared across audio uploads, speech-to-text chat input, and text-to-speech voice responses.
+## Authentication Methods: Regional vs. Resource-Specific Endpoints
 
 ## Authentication Methods: Regional vs. Resource-Specific Endpoints
 
diff --git a/docs/how-to/create_agents.md b/docs/how-to/create_agents.md
index e69de29b..37a2c9ea 100644
--- a/docs/how-to/create_agents.md
+++ b/docs/how-to/create_agents.md
@@ -0,0 +1,89 @@
+---
+layout: showcase-page
+title: "Create Agents"
+permalink: /how-to/create_agents/
+menubar: docs_menu
+accent: teal
+eyebrow: "How-To Guide"
+description: "Use this guide when you want a repeatable process for creating focused agents, attaching the right actions, and validating their behavior before wider rollout."
+hero_icons:
+  - bi-robot
+  - bi-tools
+  - bi-clipboard-check
+hero_pills:
+  - Global, group, and personal scope
+  - Focused instructions over generic prompts
+  - Validate before publishing
+hero_links:
+  - label: "First agent tutorial"
+    url: /tutorials/first_agent/
+    style: primary
+  - label: "Admin configuration"
+    url: /admin_configuration/
+    style: secondary
+---
+
+Create agents around a specific job to be done, not around a vague persona. The most reliable agents in Simple Chat have narrow instructions, deliberate tool access, and a test set that proves they behave the way you expect.
+
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-bullseye"></i></div>
+				<h2>Start with one use case</h2>
+				<p>Define the exact task, audience, and boundary for the agent before you write instructions or connect tools.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-signpost-split"></i></div>
+				<h2>Choose the right scope</h2>
+				<p>Pick global, group, or personal scope based on who should use the agent and where its actions or documents live.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-plug"></i></div>
+				<h2>Attach only the tools it needs</h2>
+				<p>Actions and plugins should widen capability intentionally, not create a grab bag of tools the agent will misuse.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-clipboard-check"></i></div>
+				<h2>Validate with real prompts</h2>
+				<p>Test against typical, edge-case, and failure-mode prompts before making the agent widely available.</p>
+		</article>
+</section>
+
+<div class="latest-release-note-panel">
+		<h2>Agents depend on admin enablement and workspace context</h2>
+		<p>Semantic Kernel agents, actions, and workspace-scoped agent surfaces have to be enabled first. If the right scope or action type is disabled in Admin Settings, the agent design work will never show up where users need it.</p>
+</div>
+
+## Minimum viable agent setup
+
+1. Write a single-sentence mission for the agent.
+2. Decide whether the agent should be global, group-scoped, or personal.
+3. Add instructions that define what the agent should do, what it should avoid, and when it should ask for clarification.
+4. Attach only the actions, knowledge sources, or workspace access needed for that mission.
+5. Test the agent with representative prompts before broader rollout.
+
+## Scope decisions
+
+- Use **global agents** when the same capability should be shared across the whole deployment.
+- Use **group agents** when the behavior, documents, or actions are tied to one team or workspace.
+- Use **personal agents** when users need private experimentation or individualized tool combinations.
+
+## Prompt and tool design rules
+
+- Prefer specific instructions over aspirational descriptions.
+- Tell the agent what evidence or citations it should rely on when grounded answers matter.
+- Avoid attaching write-capable actions unless the workflow truly needs them.
+- Give the agent permission to decline when the request falls outside its domain.
+
+## Validation checklist
+
+- Test a prompt the agent should answer well.
+- Test a prompt it should refuse or redirect.
+- Test a prompt that exercises each attached action.
+- Review whether the agent cites the correct workspace content or asks for missing context when needed.
+
+## Related guides
+
+- [Create Your First Agent](../tutorials/first_agent.md)
+- [Admin Configuration Reference](../reference/admin_configuration.md)
+- [API Reference](../reference/api_reference.md)
+- [ServiceNow Agent Examples](./agents/ServiceNow/)
diff --git a/docs/how-to/docker_customization.md b/docs/how-to/docker_customization.md
index 736abd5e..18f641c6 100644
--- a/docs/how-to/docker_customization.md
+++ b/docs/how-to/docker_customization.md
@@ -1,6 +1,57 @@
-# Docker Customization
-
-Updated in version: 0.240.006
+---
+layout: showcase-page
+title: "Docker Customization"
+permalink: /how-to/docker_customization/
+menubar: docs_menu
+accent: slate
+eyebrow: "How-To Guide"
+description: "Customize the container image when you need private trust anchors, enterprise TLS compatibility, or pip configuration changes during Docker build."
+hero_icons:
+  - bi-box-seam
+  - bi-shield-lock
+  - bi-tools
+hero_pills:
+  - Container builds only
+  - Private CA support
+  - pip configuration override
+hero_links:
+  - label: "AZD deployment"
+    url: /reference/deploy/azd-cli_deploy/
+    style: primary
+  - label: "Special setup scenarios"
+    url: /setup_instructions_special/
+    style: secondary
+---
+
+Use Docker customization when the default container image is correct for the application but not quite correct for the network or package-install environment you need to run inside.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-shield-lock"></i></div>
+        <h2>Private certificate authorities</h2>
+        <p>Add internal root or intermediate certificates when outbound HTTPS calls rely on enterprise PKI or TLS interception infrastructure.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+        <h2>Rebuild the image</h2>
+        <p>Changes in the customization folders only take effect after the Simple Chat container image is rebuilt and redeployed.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-download"></i></div>
+        <h2>Customize pip behavior</h2>
+        <p>Use the repo-level pip configuration when package installation needs custom indexes, mirrors, or enterprise network settings during build.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+        <h2>Validate from the container</h2>
+        <p>Confirm the trust bundle and network behavior from inside the running container instead of assuming the image build succeeded.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>This guide applies to container-based deployments</h2>
+    <p>The certificate and pip-customization steps here affect images built from the repo Dockerfile. Native Python App Service deployments need different host- or app-level configuration for certificate trust and package resolution.</p>
+</div>
 
 ## Custom Certificate Authorities
 
diff --git a/docs/how-to/enterprise_networking.md b/docs/how-to/enterprise_networking.md
index d4469cc7..72e8c52e 100644
--- a/docs/how-to/enterprise_networking.md
+++ b/docs/how-to/enterprise_networking.md
@@ -1,6 +1,45 @@
-# How to Configure Enterprise Networking
-
-This guide walks you through setting up Simple Chat with enterprise-grade network security using Azure Private Endpoints, Virtual Networks, and Private DNS. This configuration ensures all traffic stays on the Microsoft backbone and never traverses the public internet.
+---
+layout: showcase-page
+title: "Enterprise Networking"
+permalink: /how-to/enterprise_networking/
+menubar: docs_menu
+accent: teal
+eyebrow: "How-To Guide"
+description: "Use private endpoints, VNets, and private DNS to move Simple Chat into an enterprise network boundary without losing deployment or service connectivity."
+hero_icons: ["bi-diagram-3", "bi-shield-lock", "bi-hdd-network"]
+hero_pills: ["Private endpoints across services", "DNS and route-all matter", "Deployment runner connectivity first"]
+hero_links: [{ label: "Special setup scenarios", url: "/setup_instructions_special/", style: "primary" }, { label: "Managed identity guide", url: "/how-to/use_managed_identity/", style: "secondary" }]
+---
+
+Enterprise networking changes the deployment story as much as the runtime story. The main job is to keep the deployment runner, App Service, and Azure dependencies all able to reach one another while you progressively close off public access.
+
+<section class="latest-release-card-grid">
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-map"></i></div>
+            <h2>Plan the VNet shape first</h2>
+            <p>Subnet design, delegation, and IP planning should be settled before you start placing private endpoints or integrating App Service.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-hdd-network"></i></div>
+            <h2>Private-endpoint every dependency</h2>
+            <p>Cosmos DB, Azure OpenAI, Search, Storage, and other services need a consistent private-connectivity plan rather than one-off exceptions.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-diagram-2"></i></div>
+            <h2>DNS and route-all are part of the feature</h2>
+            <p>Private DNS zones and VNet routing are what make private endpoints usable from the app, not optional polish you add later.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-door-closed"></i></div>
+            <h2>Disable public access last</h2>
+            <p>Only shut off public paths after validating name resolution, App Service connectivity, and deployment-runner reachability.</p>
+      </article>
+</section>
+
+<div class="latest-release-note-panel">
+      <h2>Start with the deployment runner question</h2>
+      <p>Before you touch private endpoints, decide whether the machine running the deployment can already resolve and reach the private network path. That answer determines whether you leave <code>allowedIpAddresses</code> blank or temporarily allow a public egress IP during rollout.</p>
+</div>
 
 ## Overview
 
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
new file mode 100644
index 00000000..52ff1dea
--- /dev/null
+++ b/docs/how-to/index.md
@@ -0,0 +1,40 @@
+---
+layout: showcase-page
+title: "How-To Guides"
+permalink: /how-to/
+menubar: docs_menu
+accent: teal
+eyebrow: "Task-Oriented Guidance"
+description: "Use the how-to section for practical workflows after the platform is already understood: uploads, agents, identity, scaling, upgrades, networking, and external integrations."
+hero_icons: ["bi-tools", "bi-signpost-split", "bi-check2-square"]
+hero_pills: ["Repeatable operator tasks", "Platform and integration workflows", "Shorter than full reference pages"]
+hero_links: [{ label: "Tutorials", url: "/tutorials/", style: "primary" }, { label: "Reference section", url: "/reference/", style: "secondary" }]
+---
+
+How-to guides assume you already know what area of the product you are working in. They focus on practical execution: the steps, dependencies, and validation checks needed to complete a specific task.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-file-earmark-arrow-up"></i></div>
+        <h2>Content and agents</h2>
+        <p>Add documents, create agents, and use the ServiceNow agent guides when your work is centered on user workflows and external system actions.</p>
+        <p><a href="{{ '/how-to/add_documents/' | relative_url }}">Add documents</a> · <a href="{{ '/how-to/create_agents/' | relative_url }}">Create agents</a> · <a href="{{ '/how-to/agents/ServiceNow/' | relative_url }}">ServiceNow guides</a></p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-person-badge"></i></div>
+        <h2>Identity and security</h2>
+        <p>Use the managed identity and Azure Speech guides when you want to replace stored secrets or handle service-specific authentication correctly.</p>
+        <p><a href="{{ '/how-to/use_managed_identity/' | relative_url }}">Managed identity</a> · <a href="{{ '/how-to/azure_speech_managed_identity_manul_setup/' | relative_url }}">Azure Speech setup</a></p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+        <h2>Deployment operations</h2>
+        <p>Use these guides for enterprise networking, scaling, upgrades, and Docker customization once the deployment starts moving toward production operations.</p>
+        <p><a href="{{ '/how-to/enterprise_networking/' | relative_url }}">Enterprise networking</a> · <a href="{{ '/how-to/scaling_on_azure/' | relative_url }}">Scaling</a> · <a href="{{ '/how-to/upgrade_paths/' | relative_url }}">Upgrade paths</a></p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>Choose the shortest path that solves the task</h2>
+    <p>If you need conceptual background, switch to the explanation pages. If you need exact settings or route details, switch to the reference pages. Stay in the how-to section when the task itself is already clear and you want the execution sequence.</p>
+</div>
\ No newline at end of file
diff --git a/docs/how-to/scaling_on_azure.md b/docs/how-to/scaling_on_azure.md
index e24912ea..c57ab73f 100644
--- a/docs/how-to/scaling_on_azure.md
+++ b/docs/how-to/scaling_on_azure.md
@@ -1,6 +1,45 @@
-# How to Scale Simple Chat on Azure
-
-When your Simple Chat deployment grows in users, data, or usage, you'll need to scale the underlying Azure resources. This guide provides specific steps for scaling each component to maintain performance and availability.
+---
+layout: showcase-page
+title: "Scale Simple Chat on Azure"
+permalink: /how-to/scaling_on_azure/
+menubar: docs_menu
+accent: orange
+eyebrow: "How-To Guide"
+description: "Use this guide when a working deployment needs more throughput, higher availability, or cleaner scaling rules across App Service, Cosmos DB, Search, and AI services."
+hero_icons: ["bi-graph-up-arrow", "bi-server", "bi-speedometer2"]
+hero_pills: ["App Service and data scale", "Search and AI throughput", "Monitor before you overprovision"]
+hero_links: [{ label: "Scaling overview", url: "/application_scaling/", style: "primary" }, { label: "Admin overview", url: "/admin_configuration/", style: "secondary" }]
+---
+
+Scaling Simple Chat is about coordinating several Azure services, not just adding more web instances. Use this guide when you already have a functioning deployment and need to expand capacity without breaking session behavior, retrieval performance, or downstream service quotas.
+
+<section class="latest-release-card-grid">
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-server"></i></div>
+            <h2>Scale App Service deliberately</h2>
+            <p>Vertical and horizontal scaling solve different problems, and scale-out requires session strategy to be correct before you add instances.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-database"></i></div>
+            <h2>Track Cosmos RU pressure</h2>
+            <p>Most data-tier trouble shows up as throttling, query latency, or hot containers before it shows up as a full outage.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-search"></i></div>
+            <h2>Protect retrieval quality</h2>
+            <p>Search replicas, partitions, and index performance all influence how grounded chat behaves at higher load.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-cpu"></i></div>
+            <h2>Mind downstream AI quotas</h2>
+            <p>Azure OpenAI and other AI services have their own TPM, RPM, and service limits, so app scaling alone does not solve throughput bottlenecks.</p>
+      </article>
+</section>
+
+<div class="latest-release-note-panel">
+      <h2>Redis comes before App Service scale-out</h2>
+      <p>If you plan to run more than one web instance, configure shared session storage first. Without it, scale-out can create authentication and session consistency problems that look like random app instability.</p>
+</div>
 
 ## When to Scale
 
diff --git a/docs/how-to/upgrade_paths.md b/docs/how-to/upgrade_paths.md
index 9e22ac61..f1f4ad62 100644
--- a/docs/how-to/upgrade_paths.md
+++ b/docs/how-to/upgrade_paths.md
@@ -1,6 +1,57 @@
-# Upgrade Paths
-
-Use this guide when you already have SimpleChat deployed and want to update the application without rediscovering the initial deployment steps.
+---
+layout: showcase-page
+title: "Upgrade Paths"
+permalink: /how-to/upgrade_paths/
+menubar: docs_menu
+accent: emerald
+eyebrow: "How-To Guide"
+description: "Choose the right upgrade method based on whether your deployment is native Python App Service or one of the repo's container-based deployment paths."
+hero_icons:
+  - bi-arrow-repeat
+  - bi-box-seam
+  - bi-cloud-arrow-up
+hero_pills:
+  - Deployment model first
+  - Container and native paths differ
+  - Validate before closing the release
+hero_links:
+  - label: "Deployment reference"
+    url: /reference/deploy/
+    style: primary
+  - label: "Manual deployment notes"
+    url: /reference/deploy/manual_deploy/
+    style: secondary
+---
+
+The first upgrade decision is not which command to run. It is whether your existing site is running as native Python App Service or as one of the repo's container-based deployment models. That single distinction drives startup handling, rollout mechanics, and rollback choices.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-filetype-py"></i></div>
+        <h2>Native Python upgrades</h2>
+        <p>Use VS Code deploy, ZIP deploy, or deployment slots when the app code is deployed directly to App Service instead of through a container image.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+        <h2>Container upgrades</h2>
+        <p>Use <code>azd deploy</code> for routine code updates when infrastructure is unchanged and reserve <code>azd up</code> for combined app-plus-infrastructure releases.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-tag"></i></div>
+        <h2>Image-only rollouts</h2>
+        <p>Teams already managing App Service against ACR can use image-tag promotion or restart-based rollout strategies without reprovisioning infrastructure.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+        <h2>Validation is part of the upgrade</h2>
+        <p>Checking startup behavior, dependency installation, and app health after release is not optional. It is part of the upgrade path itself.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>Figure out the runtime model before you change anything</h2>
+    <p>If you skip the deployment-model check, you can apply the wrong startup-command guidance, wrong release command, or wrong rollback assumption. That is the most common way an upgrade guide becomes misleading.</p>
+</div>
 
 ## Choose the Right Upgrade Path
 
diff --git a/docs/how-to/use_managed_identity.md b/docs/how-to/use_managed_identity.md
index 3e728d8f..9f1cf5c5 100644
--- a/docs/how-to/use_managed_identity.md
+++ b/docs/how-to/use_managed_identity.md
@@ -1,6 +1,45 @@
-# How to Use Managed Identity
-
-This guide shows you how to configure Simple Chat to use Azure Managed Identity instead of API keys for secure authentication to Azure services. Using Managed Identity eliminates the need to store secrets in your application configuration.
+---
+layout: showcase-page
+title: "Use Managed Identity"
+permalink: /how-to/use_managed_identity/
+menubar: docs_menu
+accent: teal
+eyebrow: "How-To Guide"
+description: "Use Azure Managed Identity to move Simple Chat away from stored API keys and toward resource-to-resource authentication with RBAC."
+hero_icons: ["bi-shield-lock", "bi-key", "bi-person-badge"]
+hero_pills: ["RBAC over stored secrets", "Service-by-service role assignment", "Validate then remove keys"]
+hero_links: [{ label: "Admin configuration", url: "/reference/admin_configuration/", style: "primary" }, { label: "Speech MI manual setup", url: "/how-to/azure_speech_managed_identity_manul_setup/", style: "secondary" }]
+---
+
+Managed identity works best when you treat it as an incremental migration. Enable the identity, assign the right RBAC roles, switch each service configuration over deliberately, and only then remove the old keys.
+
+<section class="latest-release-card-grid">
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-person-badge"></i></div>
+            <h2>Enable the App Service identity</h2>
+            <p>Everything starts with turning on system-assigned or user-assigned managed identity and confirming the principal exists before you assign roles.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-shield-check"></i></div>
+            <h2>Grant RBAC per service</h2>
+            <p>Azure OpenAI, Search, Cosmos DB, Storage, Speech, and other services each need the correct role assignment at the right scope.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-sliders"></i></div>
+            <h2>Switch the app configuration</h2>
+            <p>Use Admin Settings or application settings to move each dependency from keys or connection strings to managed-identity authentication.</p>
+      </article>
+      <article class="latest-release-card">
+            <div class="latest-release-card-icon"><i class="bi bi-trash3"></i></div>
+            <h2>Remove secrets last</h2>
+            <p>Do not delete old credentials until you have validated the new path with connection tests and real workflows.</p>
+      </article>
+</section>
+
+<div class="latest-release-note-panel">
+      <h2>Not every service behaves the same way</h2>
+      <p>Most services can move cleanly to managed identity, but Cosmos DB and Speech usually deserve extra attention because RBAC scope and endpoint details matter more there than they do with simpler key-based setups.</p>
+</div>
 
 ## What is Managed Identity?
 
diff --git a/docs/index.md b/docs/index.md
index 8cea0212..5994021d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,66 +1,176 @@
 ---
-layout: page
+layout: showcase-page
 title: "Simple Chat Documentation"
-description: "Welcome to the official documentation for Simple Chat - a comprehensive platform for AI-powered conversations and document intelligence."
+description: "Azure-native documentation for deploying, operating, and extending Simple Chat with the same polished visual language as the latest-release experience."
+section: "Overview"
+accent: blue
+eyebrow: "Docs Overview"
+hero_icons:
+  - bi-house-fill
+  - bi-stars
+  - bi-rocket-takeoff
+hero_pills:
+  - Azure OpenAI
+  - Retrieval-Augmented Generation
+  - Enterprise controls
+hero_links:
+  - label: "Start with deployment"
+    url: /setup_instructions/
+    style: primary
+  - label: "Explore features"
+    url: /features/
+    style: outline
 ---
 
-The **Simple Chat Application** is a comprehensive, web-based platform designed to facilitate secure and context-aware interactions with generative AI models, specifically leveraging **Azure OpenAI**. Its central feature is **Retrieval-Augmented Generation (RAG)**, which significantly enhances AI interactions by allowing users to ground conversations in their own data. Users can upload personal ("Your Workspace") or shared group ("Group Workspaces") documents, which are processed using **Azure AI Document Intelligence**, chunked intelligently based on content type, vectorized via **Azure OpenAI Embeddings**, and indexed into **Azure AI Search** for efficient hybrid retrieval (semantic + keyword).
-
-Built with modularity in mind, the application offers a suite of powerful **optional features** that can be enabled via administrative settings. These include integrating **Azure AI Content Safety** for governance, providing **Image Generation** capabilities (DALL-E), processing **Video** (via Azure Video Indexer) and **Audio** (via Azure Speech Service) files for RAG, implementing **Document Classification** schemes, collecting **User Feedback**, enabling **Conversation Archiving** for compliance, extracting **AI-driven Metadata**, and offering **Enhanced Citations** linked directly to source documents stored in Azure Storage.
-
-The application utilizes **Azure Cosmos DB** for storing conversations, metadata, and settings, and is secured using **Azure Active Directory (Entra ID)** for authentication and fine-grained Role-Based Access Control (RBAC) via App Roles. Designed for enterprise use, it runs reliably on **Azure App Service** and supports deployment in both **Azure Commercial** and **Azure Government** cloud environments, offering a versatile tool for knowledge discovery, content generation, and collaborative AI-powered tasks within a secure, customizable, and Azure-native framework.
-
-## Contributing
-
-If you want to contribute code, documentation, or fixes to Simple Chat, see the [Contributing guide](./contributing.md) for the fork workflow, target branch guidance, pull request expectations, and local development references.
-
-## Features
-
-- **Chat with AI**: Interact with an AI model based on Azure OpenAI’s GPT and Thinking models.
-
-- **RAG with Hybrid Search**: Upload documents and perform hybrid searches (vector + keyword), retrieving relevant information from your files to augment AI responses.
-
-- **Document Management**: Upload, store, and manage multiple versions of documents—personal ("Your Workspace") or group-level ("Group Workspaces").
-
-- **Group Management**: Create and join groups to share access to group-specific documents, enabling collaboration with Role-Based Access Control (RBAC).
-
-- **Ephemeral (Single-Convo) Documents**: Upload temporary documents available only during the current chat session, without persistent storage in Azure AI Search.
-
-- **Conversation Archiving (Optional)**: Retain copies of user conversations—even after deletion from the UI—in a dedicated Cosmos DB container for audit, compliance, or legal requirements.
-
-- **Content Safety (Optional)**: Integrate Azure AI Content Safety to review every user message *before* it reaches AI models, search indexes, or image generation services. Enforce custom filters and compliance policies, with an optional `SafetyAdmin` role for viewing violations.
-
-- **Feedback System (Optional)**: Allow users to rate AI responses (thumbs up/down) and provide contextual comments on negative feedback. Includes user and admin dashboards, governed by an optional `FeedbackAdmin` role.
-
-- **Bing Web Search (Optional)**: Augment AI responses with live Bing search results, providing up-to-date information. Configurable via Admin Settings.
-
-- **Image Generation (Optional)**: Enable on-demand image creation using Azure OpenAI's DALL-E models, controlled via Admin Settings.
-
-- **Video Extraction (Optional)**: Utilize Azure Video Indexer to transcribe speech and perform Optical Character Recognition (OCR) on video frames. Segments are timestamp-chunked for precise retrieval and enhanced citations linking back to the video timecode.
-
-- **Audio Extraction (Optional)**: Leverage Azure Speech Service to transcribe audio files into timestamped text chunks, making audio content searchable and enabling enhanced citations linked to audio timecodes.
-
-- **Document Classification (Optional)**: Admins define custom classification types and associated colors. Users tag uploaded documents with these labels, which flow through to AI conversations, providing lineage and insight into data sensitivity or type.
-
-- **Enhanced Citation (Optional)**: Store processed, chunked files in Azure Storage (organized into user- and document-scoped folders). Display interactive citations in the UI—showing page numbers or timestamps—that link directly to the source document preview.
-
-- **Metadata Extraction (Optional)**: Apply an AI model (configurable GPT model via Admin Settings) to automatically generate keywords, two-sentence summaries, and infer author/date for uploaded documents. Allows manual override for richer search context.
-
-- **File Processing Logs (Optional)**: Enable verbose logging for all ingestion pipelines (workspaces and ephemeral chat uploads) to aid in debugging, monitoring, and auditing file processing steps.
-
-- **Redis Cache (Optional)**: Integrate Azure Cache for Redis to provide a distributed, high-performance session store. This enables true horizontal scaling and high availability by decoupling user sessions from individual app instances.
-
-- **Authentication & RBAC**: Secure access via Azure Active Directory (Entra ID) using MSAL. Supports Managed Identities for Azure service authentication, group-based controls, and custom application roles (`Admin`, `User`, `CreateGroup`, `SafetyAdmin`, `FeedbackAdmin`).
-
-- **Supported File Types**:
-
-  -   Text: `txt`, `md`, `html`, `json`
-
-  *   Documents: `pdf`, `docx`, `pptx`, `xlsx`, `xlsm`, `xls`, `csv`
-  *   Images: `jpg`, `jpeg`, `png`, `bmp`, `tiff`, `tif`, `heif`
-  *   Video: `mp4`, `mov`, `avi`, `wmv`, `mkv`, `webm`
-  *   Audio: `mp3`, `wav`, `ogg`, `aac`, `flac`, `m4a`
-
-## Architecture-diagram
-
-![Architecture](./images/architecture.png)
+Simple Chat gives teams an Azure-native way to deploy, ground, govern, and extend AI experiences without stitching together a separate chat app, search layer, and admin plane.
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Start here</div>
+      <h2>Four pages that cover the full path</h2>
+      <p>Use these entry points when you want to get from deployment decisions to daily usage without hunting through the entire docs tree.</p>
+    </div>
+    <span class="latest-release-section-badge">Core docs</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-rocket-takeoff"></i></span>
+          <span class="latest-release-card-badge">Deployment</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/setup_instructions/' | relative_url }}">Getting Started</a></h3>
+        <p class="latest-release-card-summary">Pick the right deployment path, line up prerequisites, and follow the repo's recommended order of operations.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/setup_instructions/' | relative_url }}">Open guide</a>
+        </div>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-grid-3x3-gap"></i></span>
+          <span class="latest-release-card-badge">Capabilities</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/features/' | relative_url }}">Features</a></h3>
+        <p class="latest-release-card-summary">See the core workspace experience, optional feature packs, platform services, and supported file types in one place.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/features/' | relative_url }}">Browse features</a>
+        </div>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-question-circle"></i></span>
+          <span class="latest-release-card-badge">Troubleshooting</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/faqs/' | relative_url }}">FAQ</a></h3>
+        <p class="latest-release-card-summary">Jump straight to the issues teams hit most often around networking, auth, uploads, search, and model configuration.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/faqs/' | relative_url }}">Read answers</a>
+        </div>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--teal">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-stars"></i></span>
+          <span class="latest-release-card-badge">Current release</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/latest-release/' | relative_url }}">Latest Release Highlights</a></h3>
+        <p class="latest-release-card-summary">Review the newest user-facing work with curated summaries, screenshots, and links into the deeper feature documentation.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/latest-release/' | relative_url }}">See highlights</a>
+        </div>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Why teams use it</div>
+      <h2>One application, multiple working modes</h2>
+      <p>Simple Chat is opinionated about the hard parts: identity, grounding, document processing, and admin controls are already wired together.</p>
+    </div>
+    <span class="latest-release-section-badge">Azure-native</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-chat-dots"></i></span>
+          <span class="latest-release-card-badge">Chat + grounding</span>
+        </div>
+        <h3 class="latest-release-card-title">Context-aware AI conversations</h3>
+        <p class="latest-release-card-summary">Use Azure OpenAI with hybrid retrieval over personal, group, and public workspace content so responses stay tied to your own data.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-folder2-open"></i></span>
+          <span class="latest-release-card-badge">Documents</span>
+        </div>
+        <h3 class="latest-release-card-title">Document pipelines that stay searchable</h3>
+        <p class="latest-release-card-summary">Ingest PDFs, Office files, images, audio, and video through Azure AI services, then retrieve them with citations and optional metadata enrichment.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-shield-check"></i></span>
+          <span class="latest-release-card-badge">Governance</span>
+        </div>
+        <h3 class="latest-release-card-title">Controls for enterprise rollouts</h3>
+        <p class="latest-release-card-summary">Layer on Entra ID roles, content safety, feedback review, conversation archiving, and operational logging without rebuilding the app.</p>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Architecture</div>
+      <h2>What sits behind the experience</h2>
+      <p>The platform runs on Azure App Service and composes search, storage, document processing, and conversation state into a single application surface.</p>
+    </div>
+    <span class="latest-release-section-badge">Reference view</span>
+  </div>
+
+  <div class="latest-release-note-panel latest-release-accent--slate">
+    <h3>Platform at a glance</h3>
+    <p>Core application state lives in Azure Cosmos DB, document retrieval runs through Azure AI Search, ingestion is handled by Azure AI Document Intelligence and related media services, and authentication uses Entra ID. That combination makes it practical to run Simple Chat as a governed internal tool instead of a demo-only sample.</p>
+  </div>
+
+  <div class="mt-3">
+    <img src="{{ '/images/architecture.png' | relative_url }}" alt="Architecture diagram showing Simple Chat running on Azure App Service with Azure OpenAI, AI Search, Cosmos DB, and storage services." />
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Contribute</div>
+      <h2>Working in the repo</h2>
+      <p>The docs, app, and deployers are all maintained together, so the contributor guide is the fastest way to align with the expected workflow.</p>
+    </div>
+    <span class="latest-release-section-badge">Collaboration</span>
+  </div>
+
+  <div class="latest-release-note-panel latest-release-accent--teal">
+    <h3>Want to make changes?</h3>
+    <p>Use the <a href="{{ '/contributing/' | relative_url }}">Contributing guide</a> for the fork-based workflow, target branch expectations, and local development references before you start editing code or docs.</p>
+  </div>
+</section>
diff --git a/docs/reference/admin_configuration.md b/docs/reference/admin_configuration.md
index 0a622b6a..dab4c3ae 100644
--- a/docs/reference/admin_configuration.md
+++ b/docs/reference/admin_configuration.md
@@ -1,6 +1,45 @@
-# Admin Configuration Reference
-
-This reference provides complete details about all administrative configuration options available in Simple Chat. The Admin Settings page provides a centralized location to configure application features and service connections.
+---
+layout: showcase-page
+title: "Admin Configuration Reference"
+permalink: /reference/admin_configuration/
+menubar: docs_menu
+accent: teal
+eyebrow: "Reference"
+description: "Use this operator guide to map each Admin Settings section to the Azure services, workspace policies, and runtime behaviors it controls."
+hero_icons: ["bi-sliders", "bi-shield-check", "bi-diagram-3"]
+hero_pills: ["Dependency-aware settings", "Workspace and safety controls", "Agents, actions, and citations"]
+hero_links: [{ label: "Admin overview", url: "/admin_configuration/", style: "primary" }, { label: "Managed identity setup", url: "/how-to/use_managed_identity/", style: "secondary" }]
+---
+
+This page is the detailed companion to the main admin guide. Use it when you need to understand what a setting actually governs, which Azure dependency it relies on, and what downstream behavior changes when you turn it on.
+
+<section class="latest-release-card-grid">
+        <article class="latest-release-card">
+                <div class="latest-release-card-icon"><i class="bi bi-palette"></i></div>
+                <h2>Branding and model routing</h2>
+                <p>Start here when you are setting the application title, logo, GPT routing, embeddings, and optional image generation behavior.</p>
+        </article>
+        <article class="latest-release-card">
+                <div class="latest-release-card-icon"><i class="bi bi-folder2-open"></i></div>
+                <h2>Workspaces and ingestion</h2>
+                <p>These sections control personal, group, and public workspace availability, multimedia processing, metadata extraction, and classification behavior.</p>
+        </article>
+        <article class="latest-release-card">
+                <div class="latest-release-card-icon"><i class="bi bi-journal-richtext"></i></div>
+                <h2>Citations and retrieval</h2>
+                <p>Search, extraction, enhanced citations, and storage-backed preview features all sit behind separate settings with their own service requirements.</p>
+        </article>
+        <article class="latest-release-card">
+                <div class="latest-release-card-icon"><i class="bi bi-robot"></i></div>
+                <h2>Safety and automation</h2>
+                <p>Content safety, feedback, archiving, agents, and custom action integrations should be enabled deliberately because they affect governance as much as user experience.</p>
+        </article>
+</section>
+
+<div class="latest-release-note-panel">
+        <h2>Read the settings in dependency order</h2>
+        <p>Start with identity, branding, and model connectivity. Then enable workspaces, search, and extraction. After that, layer on citations, safety, and agents. That order mirrors how the application actually lights up features and makes troubleshooting much easier when a dependency is missing.</p>
+</div>
 
 ## Accessing Admin Settings
 
diff --git a/docs/reference/api_reference.md b/docs/reference/api_reference.md
index e69de29b..19a52b80 100644
--- a/docs/reference/api_reference.md
+++ b/docs/reference/api_reference.md
@@ -0,0 +1,79 @@
+---
+layout: showcase-page
+title: "API Reference"
+permalink: /reference/api_reference/
+menubar: docs_menu
+accent: slate
+eyebrow: "Reference"
+description: "Use the live Swagger endpoints and repository OpenAPI artifacts to inspect Simple Chat APIs, integration helpers, and route coverage."
+hero_icons:
+  - bi-braces
+  - bi-filetype-json
+  - bi-diagram-2
+hero_pills:
+  - Authenticated live docs
+  - JSON and YAML output
+  - Route and cache inspection
+hero_links:
+  - label: "Admin settings reference"
+    url: /reference/admin_configuration/
+    style: primary
+  - label: "Feature reference"
+    url: /reference/features/
+    style: secondary
+---
+
+Use this page when you need to answer a concrete API question: what route exists, which auth model it uses, whether a deployed environment is exposing docs, or which OpenAPI helper endpoints support custom action setup.
+
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-window"></i></div>
+				<h2>Interactive docs</h2>
+				<p>Open <code>/swagger</code> in a signed-in environment when you want the interactive route browser backed by the running app.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-filetype-json"></i></div>
+				<h2>Machine-readable specs</h2>
+				<p>Download <code>/swagger.json</code> or <code>/swagger.yaml</code> when you need tooling input, contract review, or export-friendly route metadata.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-list-task"></i></div>
+				<h2>Route inventory</h2>
+				<p>Use <code>/api/swagger/routes</code> and <code>/api/swagger/cache</code> to inspect route coverage, cache state, and documentation internals.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-plug"></i></div>
+				<h2>OpenAPI helpers</h2>
+				<p>The <code>/api/openapi/*</code> endpoints support OpenAPI upload, validation, and auth-scheme analysis for custom action configuration.</p>
+		</article>
+</section>
+
+<div class="latest-release-note-panel">
+		<h2>Pick the right source of truth</h2>
+		<p>Use the live Swagger endpoints when you need the currently deployed route set, auth requirements, or generated schemas. Use the repository artifact at <code>artifacts/open_api/openapi.yaml</code> when you are reviewing frontend dependencies or discussing API shape in a pull request without relying on a running environment.</p>
+</div>
+
+## Documentation endpoints
+
+| Endpoint | Use it for | Notes |
+| :--- | :--- | :--- |
+| <code>/swagger</code> | Interactive documentation UI | Requires authentication and depends on API documentation being enabled in Admin Settings. |
+| <code>/swagger.json</code> | JSON OpenAPI output | Cached and rate limited. Good for tooling and diffing. |
+| <code>/swagger.yaml</code> | YAML OpenAPI output | Same data as JSON, but easier to read or export into YAML-based workflows. |
+| <code>/api/swagger/routes</code> | Route documentation status | Useful when you want to confirm which endpoints are documented. |
+| <code>/api/swagger/cache</code> | Cache statistics and management | Supports inspection and cache clearing workflows. |
+
+## OpenAPI action helper endpoints
+
+Use these when configuring custom OpenAPI-backed actions:
+
+- <code>/api/openapi/upload</code> validates an uploaded OpenAPI file and returns extracted spec metadata.
+- <code>/api/openapi/list-uploaded</code> lists previously stored validated specs when available.
+- <code>/api/openapi/analyze-auth</code> inspects the uploaded spec and suggests authentication handling.
+
+## Recommended working pattern
+
+1. Enable API documentation in Admin Settings if the environment hides Swagger routes by default.
+2. Sign in and confirm the live docs at <code>/swagger</code> match the running environment.
+3. Download <code>/swagger.json</code> or <code>/swagger.yaml</code> when you need contract-oriented tooling.
+4. Use <code>artifacts/open_api/openapi.yaml</code> when you want a repo-side artifact for code review or frontend analysis.
diff --git a/docs/reference/deploy/azd-cli_deploy.md b/docs/reference/deploy/azd-cli_deploy.md
index 5445f946..b6021a4a 100644
--- a/docs/reference/deploy/azd-cli_deploy.md
+++ b/docs/reference/deploy/azd-cli_deploy.md
@@ -1,13 +1,65 @@
 ---
-layout: page
+layout: showcase-page
 title: "Azure Developer CLI Deployment"
-description: "Deploy Simple Chat with azd up"
-section: "Reference"
+permalink: /reference/deploy/azd-cli_deploy/
+menubar: docs_menu
+accent: emerald
+eyebrow: "Deployment Reference"
+description: "Deploy Simple Chat with Azure Developer CLI when you want the repo's most current, end-to-end supported rollout path."
+hero_icons:
+  - bi-rocket-takeoff
+  - bi-cloud-arrow-up
+  - bi-box-seam
+hero_pills:
+  - Recommended deployment path
+  - Provision and deploy together
+  - Container-based runtime
+hero_links:
+  - label: "Getting Started"
+    url: /setup_instructions/
+    style: primary
+  - label: "Upgrade paths"
+    url: /how-to/upgrade_paths/
+    style: secondary
+nav_links:
+  prev:
+    title: "Deployment Reference"
+    url: /reference/deploy/
+  next:
+    title: "Azure CLI with PowerShell"
+    url: /reference/deploy/azurecli_powershell_deploy/
+show_nav: true
 ---
 
-# Azure Developer CLI Deployment
-
-Azure Developer CLI (azd) provides the fastest and most automated way to deploy Simple Chat. This method handles resource provisioning, configuration, and application deployment with minimal manual steps.
+Azure Developer CLI handles the cleanest end-to-end deployment flow in this repo. Use it when you want infrastructure provisioning, environment configuration, and application deployment to stay in one documented path.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+        <h2>Provision infrastructure</h2>
+        <p>AZD drives the Bicep templates for the required Azure resources instead of making you stitch together the provisioning steps manually.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-sliders2"></i></div>
+        <h2>Capture environment choices</h2>
+        <p>Subscription, region, environment naming, and optional environment settings all stay tied to the AZD environment instead of scattered across ad hoc scripts.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+        <h2>Deploy the app</h2>
+        <p>The current path is container-based App Service, so the image runtime and startup behavior are handled by the deployment model rather than a native Python startup command.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-graph-up-arrow"></i></div>
+        <h2>Inspect and iterate</h2>
+        <p>Use AZD commands for logs, monitoring, environment inspection, and upgrade decisions without switching to a separate deployment toolset midstream.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>Startup command rule for this path</h2>
+    <p>The repo's AZD workflow deploys a container-based App Service. Do not add a native Python App Service startup command unless you intentionally move away from the container runtime later.</p>
+</div>
 
 ## Overview
 
diff --git a/docs/reference/deploy/azurecli_powershell_deploy.md b/docs/reference/deploy/azurecli_powershell_deploy.md
index 921083d4..f479c484 100644
--- a/docs/reference/deploy/azurecli_powershell_deploy.md
+++ b/docs/reference/deploy/azurecli_powershell_deploy.md
@@ -1,34 +1,78 @@
 ---
-layout: page
+layout: showcase-page
 title: "Azure CLI with PowerShell Deployment"
-description: "Use the script-driven Azure CLI + PowerShell deployer"
-section: "Reference"
+permalink: /reference/deploy/azurecli_powershell_deploy/
+menubar: docs_menu
+accent: blue
+eyebrow: "Deployment Reference"
+description: "Use the script-driven Azure CLI and PowerShell deployer when you want more sequencing control than the default AZD flow."
+hero_icons:
+  - bi-terminal
+  - bi-cloud-check
+  - bi-arrow-repeat
+hero_pills:
+  - Script-driven rollout
+  - Container App Service model
+  - Direct sequencing control
+hero_links:
+  - label: "Deployment reference"
+    url: /reference/deploy/
+    style: primary
+  - label: "Upgrade paths"
+    url: /how-to/upgrade_paths/
+    style: secondary
+nav_links:
+  prev:
+    title: "Azure Developer CLI"
+    url: /reference/deploy/azd-cli_deploy/
+  next:
+    title: "Bicep Deployment"
+    url: /reference/deploy/bicep_deploy/
+show_nav: true
 ---
 
-# Azure CLI with PowerShell Deployment
+This deployer keeps you in the repo's container-based deployment model while giving you more direct script control over sequencing, retries, and environment-specific adjustments.
 
-This deployer provisions Simple Chat with Azure CLI and PowerShell orchestration.
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-terminal"></i></div>
+				<h2>Script-first operations</h2>
+				<p>Use this when you want the deployment flow to live in PowerShell instead of AZD orchestration commands.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-list-check"></i></div>
+				<h2>Explicit sequencing</h2>
+				<p>The script-driven model makes it easier to reason about recovery steps and operational checkpoints in environments that prefer scripted control.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+				<h2>Same runtime model</h2>
+				<p>This path still deploys the containerized App Service runtime, so Gunicorn startup stays with the container entrypoint.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-tools"></i></div>
+				<h2>Key scripts</h2>
+				<p>The main flow lives in <code>deployers/azurecli/deploy-simplechat.ps1</code>, with destroy/reset support in the paired cleanup script.</p>
+		</article>
+</section>
 
-Use it when you want a script-driven deployment flow without `azd`, or when you want more direct control over sequencing and recovery steps than the default `azd` workflow provides.
+<div class="latest-release-note-panel">
+		<h2>Keep the runtime rule consistent</h2>
+		<p>This deployer targets container-based Azure App Service. Do not add the native Python startup command for this path unless you intentionally change deployment models.</p>
+</div>
 
-## When to Choose This Path
+## When to choose this path
 
 - You want a script-driven deployment flow without `azd`
 - You want more direct control over sequencing and recovery steps
 - You still want the repo's container-based App Service deployment model
 
-## Runtime Model
-
-- This deployer creates a container-based Azure App Service deployment.
-- Gunicorn is started by the container entrypoint in `application/single_app/Dockerfile`.
-- Do not add a native Python App Service startup command for this path.
-
-## Main Files
+## Main files
 
 - `deployers/azurecli/deploy-simplechat.ps1`
 - `deployers/azurecli/destroy-simplechat.ps1`
 
-## Quick Start
+## Quick start
 
 1. Review the variables near the top of `deploy-simplechat.ps1`.
 2. Sign in to the target Azure cloud and subscription.
diff --git a/docs/reference/deploy/bicep_deploy.md b/docs/reference/deploy/bicep_deploy.md
index d292cd3d..dd7ea60a 100644
--- a/docs/reference/deploy/bicep_deploy.md
+++ b/docs/reference/deploy/bicep_deploy.md
@@ -1,34 +1,78 @@
 ---
-layout: page
+layout: showcase-page
 title: "Bicep Deployment"
-description: "How the repo's Bicep templates fit into the supported deployment paths"
-section: "Reference"
+permalink: /reference/deploy/bicep_deploy/
+menubar: docs_menu
+accent: orange
+eyebrow: "Deployment Reference"
+description: "Use this page when you need to inspect or modify the Bicep templates that sit underneath the repo's primary deployment workflow."
+hero_icons:
+  - bi-diagram-3
+  - bi-braces-asterisk
+  - bi-cloud-check
+hero_pills:
+  - Repo IaC layer
+  - Best used with AZD orchestration
+  - Container runtime underneath
+hero_links:
+  - label: "AZD deployment"
+    url: /reference/deploy/azd-cli_deploy/
+    style: primary
+  - label: "Enterprise networking"
+    url: /how-to/enterprise_networking/
+    style: secondary
+nav_links:
+  prev:
+    title: "Azure CLI with PowerShell"
+    url: /reference/deploy/azurecli_powershell_deploy/
+  next:
+    title: "Terraform Deployment"
+    url: /reference/deploy/terraform_deploy/
+show_nav: true
 ---
 
-# Bicep Deployment
+The Bicep templates are the infrastructure backbone behind the repo's recommended deployment flow. Most teams should still apply them through AZD, but this page is where you orient yourself when you need to inspect or customize the infrastructure directly.
 
-The repo's Bicep templates are the infrastructure foundation behind the primary `azd up` deployment flow.
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-boxes"></i></div>
+				<h2>Understand the IaC baseline</h2>
+				<p>Use this path when you need to know what the repo is actually provisioning rather than treating AZD as a black box.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-wrench-adjustable"></i></div>
+				<h2>Customize safely</h2>
+				<p>Review or modify the files in <code>deployers/bicep/</code> when your organization needs network, SKU, or resource-layout changes.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-search"></i></div>
+				<h2>Preview before applying</h2>
+				<p>Keep <code>azd provision --preview</code> in the flow so you can inspect infrastructure impact before applying it to a shared environment.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+				<h2>Remember the runtime model</h2>
+				<p>The supported Bicep path still lands on container-based App Service, so startup behavior follows the container entrypoint rather than native Python app settings.</p>
+		</article>
+</section>
 
-For most teams, the best-supported Bicep experience is to use the [Azure Developer CLI deployment guide](./azd-cli_deploy.md) and let `azd` orchestrate packaging, provisioning, and deployment.
+<div class="latest-release-note-panel">
+		<h2>Use Bicep as the infrastructure layer, not a separate platform story</h2>
+		<p>In this repo, Bicep is best understood as the IaC layer beneath AZD rather than a competing deployment experience. Start from the AZD guide unless your goal is specifically to inspect or change the infrastructure modules themselves.</p>
+</div>
 
-## When to Choose This Path
+## When to choose this path
 
 - You want to inspect or customize the Bicep templates in `deployers/bicep/`
 - You want to understand the infrastructure used by the `azd` deployment flow
 - You are troubleshooting infrastructure behavior or preparing Bicep module changes
 
-## Recommended Workflow
+## Recommended workflow
 
 1. Start with the [Azure Developer CLI deployment guide](./azd-cli_deploy.md).
 2. Review or modify the Bicep files under `deployers/bicep/`.
 3. Use `azd provision --preview` or `azd up` to apply those changes through the supported workflow.
 
-## Runtime Model
-
-- The repo's Bicep-based deployment path is container-based Azure App Service.
-- Gunicorn is started by the container entrypoint in `application/single_app/Dockerfile`.
-- Do not add a native Python App Service startup command unless you intentionally switch away from containers.
-
 ## References
 
 - [Setup Instructions](../../setup_instructions.md)
diff --git a/docs/reference/deploy/index.md b/docs/reference/deploy/index.md
index 80ef7fd4..fd6b18cf 100644
--- a/docs/reference/deploy/index.md
+++ b/docs/reference/deploy/index.md
@@ -1,15 +1,63 @@
 ---
-layout: page
+layout: showcase-page
 title: "Deployment Reference"
-description: "Choose the right Simple Chat deployment path"
-section: "Reference"
+permalink: /reference/deploy/
+menubar: docs_menu
+accent: emerald
+eyebrow: "Reference"
+description: "Choose the right Simple Chat deployment path and understand when each deployment model is the right operational fit."
+hero_icons:
+  - bi-rocket-takeoff
+  - bi-cloud-arrow-up
+  - bi-diagram-3
+hero_pills:
+  - AZD first
+  - Container deployers by default
+  - Native Python notes included
+hero_links:
+  - label: "Getting Started"
+    url: /setup_instructions/
+    style: primary
+  - label: "Upgrade paths"
+    url: /how-to/upgrade_paths/
+    style: secondary
 ---
 
-# Deployment Reference
+This section is the deployment decision map. Use it after you already understand the basics and need the path-specific guidance for the rollout model your team actually uses.
 
-Simple Chat supports multiple deployment paths. If you want the best-supported path with the most current repo guidance, start with **Azure Developer CLI** and run `azd up`.
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-rocket-takeoff"></i></div>
+				<h2>Azure Developer CLI</h2>
+				<p>The most current and best-supported path. Use it when you want provisioning, configuration, and deployment handled in one repo-aligned workflow.</p>
+				<p><a href="{{ '/reference/deploy/azd-cli_deploy/' | relative_url }}">Open AZD reference</a></p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-terminal"></i></div>
+				<h2>Azure CLI with PowerShell</h2>
+				<p>Use this when you want a script-driven deployment flow with more control over sequencing and recovery than the default AZD experience.</p>
+				<p><a href="{{ '/reference/deploy/azurecli_powershell_deploy/' | relative_url }}">Open script-driven path</a></p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+				<h2>Bicep and Terraform</h2>
+				<p>Use these when infrastructure-as-code ownership is the main concern and your team needs more direct control over templates or state.</p>
+				<p><a href="{{ '/reference/deploy/bicep_deploy/' | relative_url }}">Inspect IaC paths</a></p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+				<h2>Manual native Python notes</h2>
+				<p>Use the manual notes only when you are intentionally operating a native Python App Service deployment rather than the repo's container deployers.</p>
+				<p><a href="{{ '/reference/deploy/manual_deploy/' | relative_url }}">Read native Python notes</a></p>
+		</article>
+</section>
 
-## Recommended Order
+<div class="latest-release-note-panel">
+		<h2>Pick the runtime model first</h2>
+		<p>The most important split is not AZD versus Terraform. It is container-based App Service versus native Python App Service. The repo's main deployment paths are container-based, and that changes startup-command handling, upgrade flow, and rollback expectations.</p>
+</div>
+
+## Recommended order
 
 1. [Azure Developer CLI (`azd up`)](./azd-cli_deploy.md)
 2. [Azure CLI with PowerShell](./azurecli_powershell_deploy.md)
@@ -17,7 +65,7 @@ Simple Chat supports multiple deployment paths. If you want the best-supported p
 4. [Terraform](./terraform_deploy.md)
 5. [Manual deployment notes](./manual_deploy.md)
 
-## Related Guides
+## Related guides
 
 - [Setup Instructions](../../setup_instructions.md)
 - [Upgrade Paths](../../how-to/upgrade_paths.md)
diff --git a/docs/reference/deploy/manual_deploy.md b/docs/reference/deploy/manual_deploy.md
index 1a0e9937..c8285c77 100644
--- a/docs/reference/deploy/manual_deploy.md
+++ b/docs/reference/deploy/manual_deploy.md
@@ -1,15 +1,62 @@
 ---
-layout: page
+layout: showcase-page
 title: "Manual Deployment Notes"
-description: "Use the native Python Azure App Service deployment path when container deployers are not the right fit"
-section: "Reference"
+permalink: /reference/deploy/manual_deploy/
+menubar: docs_menu
+accent: orange
+eyebrow: "Deployment Reference"
+description: "Use these notes when you are intentionally running Simple Chat as a native Python Azure App Service deployment instead of the repo's container deployers."
+hero_icons:
+  - bi-box-arrow-up-right
+  - bi-file-earmark-zip
+  - bi-gear
+hero_pills:
+  - Native Python only
+  - Explicit startup command required
+  - Upgrade validation matters
+hero_links:
+  - label: "Upgrade paths"
+    url: /how-to/upgrade_paths/
+    style: primary
+  - label: "Deployment reference"
+    url: /reference/deploy/
+    style: secondary
+nav_links:
+  prev:
+    title: "Terraform Deployment"
+    url: /reference/deploy/terraform_deploy/
+show_nav: true
 ---
 
-# Manual Deployment Notes
-
-Use this path when deploying SimpleChat to **native Python Azure App Service** instead of the repo's container-based deployers.
-
-For the combined native-vs-container decision guide, see [../../how-to/upgrade_paths.md](../../how-to/upgrade_paths.md).
+Use this path only when native Python App Service is an intentional operating choice. It is not the default runtime model for the repo, so the main thing to get right is the distinction between native Python startup behavior and the container-based deployers used elsewhere.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-signpost-split"></i></div>
+        <h2>Confirm the deployment model</h2>
+        <p>Before touching the app, verify that you are actually running a native Python App Service deployment and not one of the repo's container paths.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-play-circle"></i></div>
+        <h2>Set the startup command</h2>
+        <p>Native Python deployments require an explicit Gunicorn startup command. Leaving it blank is a common way to turn a routine upgrade into downtime.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-cloud-upload"></i></div>
+        <h2>Pick an upgrade method</h2>
+        <p>Use VS Code deploy, ZIP deploy, or deployment slots based on how much repeatability and rollback capability you need.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+        <h2>Validate after release</h2>
+        <p>Confirm the app starts, dependencies install correctly, and the site is healthy before closing the change.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>This page exists because native Python and container deployments behave differently</h2>
+    <p>Container-based App Service deployments in this repo do not need the native Python startup command because the image entrypoint already launches Gunicorn. Native Python App Service does need it, and that difference drives the whole deployment checklist here.</p>
+</div>
 
 ## Native Python App Service Startup Command
 
@@ -29,12 +76,12 @@ python -m gunicorn -c gunicorn.conf.py app:app
 
 Use this checklist when updating an existing native Python App Service deployment.
 
-1. Confirm the deployment model is **native Python App Service**, not container-based App Service.
+1. Confirm the deployment model is **native Python Azure App Service**, not container-based App Service.
 2. Confirm the `application/single_app` folder is the deployment unit and the Startup command is present and correct.
 3. Choose an upgrade method:
-    - **VS Code deployment** when you want the simplest manual update path.
-    - **Azure CLI ZIP deploy** when you want a repeatable package-and-deploy path.
-    - **Deployment slots** when you want validation and rollback for production.
+   - **VS Code deployment** when you want the simplest manual update path.
+   - **Azure CLI ZIP deploy** when you want a repeatable package-and-deploy path.
+   - **Deployment slots** when you want validation and rollback for production.
 4. If you use ZIP deploy, confirm `SCM_DO_BUILD_DURING_DEPLOYMENT=true` so App Service installs dependencies from `requirements.txt`.
 5. Validate the site after deployment.
 
@@ -58,7 +105,7 @@ az webapp deploy \
 
 This is an upgrade method, not only an initial deployment method.
 
-## Important Distinction
+## Important distinction
 
 - Native Python App Service needs the Startup command above.
 - The repo-provided `azd`, Bicep, Terraform, and Azure CLI deployers do not need this because they deploy a container image whose entrypoint already launches Gunicorn.
diff --git a/docs/reference/deploy/terraform_deploy.md b/docs/reference/deploy/terraform_deploy.md
index 5dcb6d78..026bc305 100644
--- a/docs/reference/deploy/terraform_deploy.md
+++ b/docs/reference/deploy/terraform_deploy.md
@@ -1,35 +1,83 @@
 ---
-layout: page
+layout: showcase-page
 title: "Terraform Deployment"
-description: "Use the Terraform deployer for state-managed infrastructure"
-section: "Reference"
+permalink: /reference/deploy/terraform_deploy/
+menubar: docs_menu
+accent: slate
+eyebrow: "Deployment Reference"
+description: "Use the Terraform deployer when your environment standardizes on Terraform state and you want to keep Simple Chat in the repo's container-based runtime model."
+hero_icons:
+  - bi-boxes
+  - bi-box-seam
+  - bi-tag
+hero_pills:
+  - Terraform-managed infrastructure
+  - Container image first
+  - Native Python only if you switch models
+hero_links:
+  - label: "Deployment reference"
+    url: /reference/deploy/
+    style: primary
+  - label: "Upgrade paths"
+    url: /how-to/upgrade_paths/
+    style: secondary
+nav_links:
+  prev:
+    title: "Bicep Deployment"
+    url: /reference/deploy/bicep_deploy/
+  next:
+    title: "Manual Deployment Notes"
+    url: /reference/deploy/manual_deploy/
+show_nav: true
 ---
 
-# Terraform Deployment
+Use Terraform when state-managed infrastructure is already your team standard and you are comfortable separating image publication from infrastructure application.
 
-Use this path when Terraform is the standard infrastructure workflow in your environment and you want the repo's container-based App Service deployment model.
+<section class="latest-release-card-grid">
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-diagram-2"></i></div>
+				<h2>State-managed infra</h2>
+				<p>Choose this path when Terraform workflows, reviews, and state handling are already part of how your platform team works.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-box-seam"></i></div>
+				<h2>Container runtime by default</h2>
+				<p>The current deployer targets a container-based Azure Linux Web App, so the application runtime still follows the Docker image entrypoint.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-tag"></i></div>
+				<h2>Publish the image first</h2>
+				<p>Terraform does not build the application image for you. Publish to ACR first, then point the deployment at the tag you intend to run.</p>
+		</article>
+		<article class="latest-release-card">
+				<div class="latest-release-card-icon"><i class="bi bi-arrow-left-right"></i></div>
+				<h2>Know when the rule changes</h2>
+				<p>If you ever move Terraform away from containers and into native Python App Service, the startup-command rules change with it.</p>
+		</article>
+</section>
 
-## When to Choose This Path
+<div class="latest-release-note-panel">
+		<h2>Terraform is not the image build step</h2>
+		<p>The most common mistake with this path is assuming Terraform also handles the application image lifecycle. It does not. Treat image publication and infrastructure application as two separate steps in the release flow.</p>
+</div>
+
+## When to choose this path
 
 - Your team standardizes on Terraform state and workflows
 - You want Terraform-managed infrastructure rather than `azd` orchestration
 - You are comfortable publishing the application image before applying infrastructure
 
-## Runtime Model
+## Runtime model
 
 The current Terraform deployer in this repo provisions a **container-based Azure Linux Web App**.
 
-## Current Behavior
+## Current behavior
 
 - Terraform sets the App Service to run the published container image.
 - Gunicorn startup is already handled by the container entrypoint in `application/single_app/Dockerfile`.
 - You do **not** need to configure App Service Stack Settings Startup command for the current Terraform deployment.
 
-## Important Note
-
-Terraform does not build the application image for you. Publish the image to Azure Container Registry first, then point Terraform at the image tag you want App Service to run.
-
-## If You Switch Terraform to Native Python Later
+## If you switch Terraform to native Python later
 
 If you change the Terraform deployment model away from containers and into native Python App Service, deploy the `application/single_app` folder and use this Startup command:
 
diff --git a/docs/reference/features.md b/docs/reference/features.md
index e69de29b..e94a406a 100644
--- a/docs/reference/features.md
+++ b/docs/reference/features.md
@@ -0,0 +1,93 @@
+---
+layout: showcase-page
+title: "Features Reference"
+permalink: /reference/features/
+menubar: docs_menu
+accent: blue
+eyebrow: "Reference"
+description: "Use this page as an operator-focused map of Simple Chat capabilities, service dependencies, and the docs that go deeper on each area."
+hero_icons:
+  - bi-grid-1x2
+  - bi-chat-square-text
+  - bi-gear
+hero_pills:
+  - Chat and retrieval
+  - Workspaces and processing
+  - Safety and automation
+hero_links:
+  - label: "Feature overview"
+    url: /features/
+    style: primary
+  - label: "Application workflows"
+    url: /application_workflows/
+    style: secondary
+---
+
+The main features page is the broad product tour. This reference page is the faster operator map for people who need to connect a capability to the Azure services, admin settings, and user workflows behind it.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-chat-square-text"></i></div>
+		<h2>Conversation surface</h2>
+		<p>Core chat includes model selection, grounded responses, citations, exports, history, and optional multimedia or image-generation extensions.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-folder2-open"></i></div>
+		<h2>Workspace ingestion</h2>
+		<p>Personal, group, and public workspaces add uploads, extraction, chunking, indexing, metadata, and optional classification across shared document sets.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-shield-check"></i></div>
+		<h2>Governance and safety</h2>
+		<p>Admins can control content safety, archiving, feedback, access roles, API documentation visibility, and advanced feature exposure from one settings surface.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-robot"></i></div>
+		<h2>Agents and integrations</h2>
+		<p>Optional Semantic Kernel agents, actions, OpenAPI plugins, SQL workflows, and external application helpers let teams move beyond plain chat into automation.</p>
+	</article>
+</section>
+
+<div class="latest-release-note-panel">
+	<h2>Use the narrative page and the reference page differently</h2>
+	<p>Start with <a href="{{ '/features/' | relative_url }}">Features</a> when you want the user-facing tour. Switch to this page when you are mapping a requirement to configuration, dependencies, or adjacent docs.</p>
+</div>
+
+## Feature map by operating area
+
+| Area | What it covers | Common dependencies |
+| :--- | :--- | :--- |
+| Chat and model routing | Conversations, grounded answers, citations, export, streaming, optional image generation | Azure OpenAI, optional Content Safety |
+| Workspaces and documents | Uploads, extraction, embeddings, search, classification, multimedia processing | Azure AI Search, embeddings, Document Intelligence, optional Speech and Video Indexer |
+| Citations and previews | Standard citations, enhanced previews, storage-backed source rendering | Azure Storage for enhanced citations |
+| Governance and operations | RBAC, logging, feedback, archiving, API docs visibility, scaling controls | Admin Settings, App Service, Application Insights |
+| Agents and actions | Semantic Kernel agents, OpenAPI actions, SQL integrations, workspace-scoped automation | Agent/action enablement, plugin configuration, model endpoints |
+
+## Where to go deeper
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-sliders"></i></div>
+		<h2>Admin settings</h2>
+		<p>Use the admin reference when you need to turn a capability on and verify which toggles or service tests control it.</p>
+		<p><a href="{{ '/reference/admin_configuration/' | relative_url }}">Open admin reference</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+		<h2>Workflows</h2>
+		<p>Use the workflow guide when you want to understand how uploads, safety review, and retrieval-backed chat behave behind the UI.</p>
+		<p><a href="{{ '/application_workflows/' | relative_url }}">Review workflows</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-stars"></i></div>
+		<h2>Latest release changes</h2>
+		<p>Use the latest-release section when you need the most recent UI and capability changes rather than the long-lived platform map.</p>
+		<p><a href="{{ '/latest-release/' | relative_url }}">Browse latest release</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-mortarboard"></i></div>
+		<h2>Tutorials and how-to guides</h2>
+		<p>Use tutorials for onboarding and the how-to guides for repeatable operational workflows once the platform is already running.</p>
+		<p><a href="{{ '/tutorials/' | relative_url }}">Open tutorials</a></p>
+	</article>
+</section>
diff --git a/docs/setup_instructions.md b/docs/setup_instructions.md
index 3d463665..397390a4 100644
--- a/docs/setup_instructions.md
+++ b/docs/setup_instructions.md
@@ -1,87 +1,251 @@
 ---
-layout: page
-title: "Setup Instructions"
-description: "Complete guide to deploying and configuring Simple Chat"
+layout: showcase-page
+title: "Getting Started"
+description: "Choose the right deployment path, line up the prerequisites, and follow the repo's recommended rollout order for Simple Chat."
 section: "Tutorials"
+accent: emerald
+eyebrow: "Deployment Guide"
+hero_icons:
+  - bi-rocket-takeoff
+  - bi-cloud-arrow-up
+  - bi-sliders2
+hero_pills:
+  - "Recommended path: azd up"
+  - Container-first deployers
+  - Native Python fallback available
+hero_links:
+  - label: "Open AZD deployment guide"
+    url: /reference/deploy/azd-cli_deploy/
+    style: primary
+  - label: "Review upgrade paths"
+    url: /how-to/upgrade_paths/
+    style: outline
 nav_links:
   next:
     title: "Manual Setup"
     url: /setup_instructions_manual/
 ---
 
-# Simple Chat - Setup Instructions
-
-## Summary
-
-Simple Chat supports several deployment paths, but they are not equal in automation, coverage, or current repo support.
-
-If you want the best-supported path with the most up-to-date guidance, start with **Azure Developer CLI** and run `azd up`. That workflow uses the repo's Bicep templates under the hood and is the primary deployment path reflected across the current README and deployment docs.
-
-Recommended order:
-- [Azure Developer CLI (`azd up`)](#azure-developer-cli-azd-up)
-- [Azure CLI with PowerShell](#azure-cli-with-powershell)
-- [Bicep](#bicep)
-- [Terraform](#terraform)
-- [Manual Deployment](#manual-deployment)
-- [Upgrade Existing Deployments](#upgrade-existing-deployments)
-- [Special Deployment Scenarios](#special-deployment-scenarios)
-
-Why multiple deployment technologies?
-We want teams to be able to adopt Simple Chat using the deployment tooling that best fits their environment, while still making the most-supported default path clear.
-
-## Azure Developer CLI (`azd up`)
-
-This is the primary recommended deployment path.
-
-Use it when you want the most automation, the most repo-level guidance, and the fewest manual decisions. `azd up` packages, provisions, and deploys Simple Chat through one workflow, and it uses the repo's Bicep templates behind the scenes.
-
-[Azure Developer CLI deployment guide](./reference/deploy/azd-cli_deploy.md)
-
-## Azure CLI with PowerShell
-
-Use this path when you want a script-driven deployment flow without `azd`.
-
-Azure CLI performs the Azure resource work, while PowerShell handles orchestration, sequencing, and recovery-oriented scripting. This is the next-best fit when you want more direct control than the `azd` workflow provides.
-
-[Azure CLI with PowerShell deployment guide](./reference/deploy/azurecli_powershell_deploy.md)
-
-## Bicep
-
-Bicep is the infrastructure layer behind the primary `azd` deployment flow.
-
-Use this path when you want to inspect or customize the Bicep modules directly. For most deployments, start with **Azure Developer CLI** instead of treating Bicep as a separate first-choice workflow.
-
-[Bicep deployment guide](./reference/deploy/bicep_deploy.md)
-
-## Terraform
-
-Use Terraform when it is the standard infrastructure workflow in your environment.
-
-This path manages a container-based Azure App Service deployment, but it expects your application image to be published before you apply the infrastructure changes.
-
-[Terraform deployment guide](./reference/deploy/terraform_deploy.md)
-
-## Manual Deployment
-
-This is the step-by-step process required to deploy the infrastructure and configurations needed to run Simple Chat without the repo's container-based deployers.
-
-This path is useful for native Python App Service scenarios and for understanding the lower-level configuration details, but it is not the preferred starting point when one of the automated deployment paths fits your environment.
-
-[Link to manual deployment steps](./setup_instructions_manual.md)
-
-## Upgrade Existing Deployments
-
-If you already have Simple Chat deployed and only need to update the application, use the dedicated upgrade guide instead of rerunning the full setup flow.
-
-[Link to upgrade paths](./how-to/upgrade_paths.md)
-
-## Special Deployment Scenarios
-
-The sections below cover scenarios that sit alongside the main deployment paths rather than replacing them.
-
-This includes topics such as:
-- Azure Commercial vs Azure Government deployments
-- Managed Identity configurations
-- Enterprise Networking Requirements
-
-[Link to special deployment configurations](./setup_instructions_special.md)
\ No newline at end of file
+If you want the most current, least ambiguous deployment path, start with Azure Developer CLI and run `azd up`. The rest of the deployment options exist to match different operating models, not because they are all equally preferred.
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Choose your path</div>
+      <h2>Deployment options in recommended order</h2>
+      <p>All of these paths are supported, but they differ in how much automation, flexibility, and operational context they give you.</p>
+    </div>
+    <span class="latest-release-section-badge">Most used first</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-rocket-takeoff"></i></span>
+          <span class="latest-release-card-badge">Recommended</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/reference/deploy/azd-cli_deploy/' | relative_url }}">Azure Developer CLI</a></h3>
+        <p class="latest-release-card-summary">Use this when you want the smoothest repo-supported experience. It provisions infrastructure, packages the app, and deploys it through the same workflow.</p>
+        <div class="latest-release-card-why">
+          <div class="latest-release-card-why-label">Why it matters</div>
+          <p class="mb-0">This is the path reflected across the main README and the current deployment documentation.</p>
+        </div>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/reference/deploy/azd-cli_deploy/' | relative_url }}">Read AZD guide</a>
+        </div>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-terminal"></i></span>
+          <span class="latest-release-card-badge">Scripted</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/reference/deploy/azurecli_powershell_deploy/' | relative_url }}">Azure CLI with PowerShell</a></h3>
+        <p class="latest-release-card-summary">Use this when you want more direct control over sequencing, recovery steps, and script-driven operations without moving to a fully manual deployment.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/reference/deploy/azurecli_powershell_deploy/' | relative_url }}">Read Azure CLI guide</a>
+        </div>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-diagram-3"></i></span>
+          <span class="latest-release-card-badge">IaC</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/reference/deploy/bicep_deploy/' | relative_url }}">Bicep</a></h3>
+        <p class="latest-release-card-summary">Use Bicep when you want to inspect or customize the infrastructure modules directly. It is the same IaC layer that the AZD path builds on.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/reference/deploy/bicep_deploy/' | relative_url }}">Inspect Bicep flow</a>
+        </div>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-box-seam"></i></span>
+          <span class="latest-release-card-badge">Alternative</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/reference/deploy/terraform_deploy/' | relative_url }}">Terraform</a></h3>
+        <p class="latest-release-card-summary">Use Terraform when it is already the standard in your environment and you are comfortable handling image publishing as part of the rollout.</p>
+        <div class="latest-release-card-actions">
+          <a class="btn btn-primary btn-sm" href="{{ '/reference/deploy/terraform_deploy/' | relative_url }}">Review Terraform guide</a>
+        </div>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Recommended flow</div>
+      <h2>What a clean first deployment looks like</h2>
+      <p>These four steps keep you aligned with the repo's expectations and reduce the chance of backtracking later.</p>
+    </div>
+    <span class="latest-release-section-badge">Step by step</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--emerald">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-1-circle"></i></span>
+          <span class="latest-release-card-badge">Step 1</span>
+        </div>
+        <h3 class="latest-release-card-title">Prepare access</h3>
+        <p class="latest-release-card-summary">Confirm Azure subscription permissions, app registration creation rights, and access to container build resources before you begin.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-2-circle"></i></span>
+          <span class="latest-release-card-badge">Step 2</span>
+        </div>
+        <h3 class="latest-release-card-title">Choose the deployer</h3>
+        <p class="latest-release-card-summary">Default to AZD unless your environment already depends on a different provisioning workflow or you need native Python deployment details.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-3-circle"></i></span>
+          <span class="latest-release-card-badge">Step 3</span>
+        </div>
+        <h3 class="latest-release-card-title">Deploy infrastructure and app</h3>
+        <p class="latest-release-card-summary">Run the chosen workflow end to end so the app service, identity, storage, search, and runtime expectations stay in sync.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-4-circle"></i></span>
+          <span class="latest-release-card-badge">Step 4</span>
+        </div>
+        <h3 class="latest-release-card-title">Plan the upgrade path</h3>
+        <p class="latest-release-card-summary">Once the first environment is live, switch to the dedicated upgrade guidance for updates instead of replaying the initial setup flow.</p>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Prerequisites</div>
+      <h2>What to line up before you run anything</h2>
+      <p>Most failed first deployments come from missing access, not from the deployer itself.</p>
+    </div>
+    <span class="latest-release-section-badge">Read once</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--teal">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-person-check"></i></span>
+          <span class="latest-release-card-badge">Access</span>
+        </div>
+        <h3 class="latest-release-card-title">Azure and identity permissions</h3>
+        <p class="latest-release-card-summary">You need subscription-level deployment rights plus the ability to create or coordinate an Entra application registration for the app.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-tools"></i></span>
+          <span class="latest-release-card-badge">Tooling</span>
+        </div>
+        <h3 class="latest-release-card-title">Install the local toolchain</h3>
+        <p class="latest-release-card-summary">At minimum, line up Azure CLI, Azure Developer CLI, PowerShell 7, and Visual Studio Code before starting the primary flow.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-building-gear"></i></span>
+          <span class="latest-release-card-badge">Platform model</span>
+        </div>
+        <h3 class="latest-release-card-title">Know whether you need exceptions</h3>
+        <p class="latest-release-card-summary">If you need sovereign cloud support, private networking, managed identity-specific configuration, or native Python hosting, review the related docs before deploying.</p>
+      </div>
+    </article>
+  </div>
+</section>
+
+<section class="latest-release-section">
+  <div class="latest-release-section-header">
+    <div>
+      <div class="latest-release-section-kicker">Next steps</div>
+      <h2>Use the follow-on guides when the default path is not enough</h2>
+      <p>These documents sit alongside the main setup flow instead of replacing it.</p>
+    </div>
+    <span class="latest-release-section-badge">Related guides</span>
+  </div>
+
+  <div class="latest-release-card-grid">
+    <article class="latest-release-card latest-release-accent--blue">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-wrench-adjustable-circle"></i></span>
+          <span class="latest-release-card-badge">Detailed setup</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/setup_instructions_manual/' | relative_url }}">Manual deployment</a></h3>
+        <p class="latest-release-card-summary">Use this for native Python App Service deployments or when you need the lower-level configuration path spelled out.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--orange">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-signpost-split"></i></span>
+          <span class="latest-release-card-badge">Scenarios</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/setup_instructions_special/' | relative_url }}">Special deployment scenarios</a></h3>
+        <p class="latest-release-card-summary">Review guidance for Azure Government, managed identities, enterprise networking, and other non-default rollout patterns.</p>
+      </div>
+    </article>
+
+    <article class="latest-release-card latest-release-accent--slate">
+      <div class="latest-release-card-shell">
+        <div class="latest-release-card-top">
+          <span class="latest-release-card-icon" aria-hidden="true"><i class="bi bi-arrow-repeat"></i></span>
+          <span class="latest-release-card-badge">Operations</span>
+        </div>
+        <h3 class="latest-release-card-title"><a href="{{ '/how-to/upgrade_paths/' | relative_url }}">Upgrade existing deployments</a></h3>
+        <p class="latest-release-card-summary">Once you are live, use the upgrade guide to decide between code-only, image-only, and infrastructure-aware updates.</p>
+      </div>
+    </article>
+  </div>
+</section>
\ No newline at end of file
diff --git a/docs/setup_instructions_manual.md b/docs/setup_instructions_manual.md
index 5bd0cd98..91d566a0 100644
--- a/docs/setup_instructions_manual.md
+++ b/docs/setup_instructions_manual.md
@@ -1,25 +1,64 @@
-# Simple Chat - Manual Setup Instructions
-
-- [Provision Azure Resources](#provision-azure-resources)
-- [Application-Specific Configuration Steps](#application-specific-configuration-steps)
-  - [Setting Up Authentication (Azure AD / Entra ID)](#setting-up-authentication-azure-ad--entra-id)
-  - [Grant App Registration Access to Azure OpenAI (for Model Fetching)](#grant-app-registration-access-to-azure-openai-for-model-fetching)
-  - [Clone the Repository](#clone-the-repository)
-  - [Configure Environment Variables (`.env` File)](#configure-environment-variables-env-file)
-  - [Alternate Method: Update App Settings via JSON (Advanced)](#alternate-method-update-app-settings-via-json-advanced)
-  - [Initializing Indexes in Azure AI Search](#initializing-indexes-in-azure-ai-search)
-- [Installing and Deploying the Application Code](#installing-and-deploying-the-application-code)
-  - [Deploying via VS Code (Recommended for Simplicity)](#deploying-via-vs-code-recommended-for-simplicity)
-  - [Deploying via Azure CLI (Zip Deploy)](#deploying-via-azure-cli-zip-deploy)
-- [Running the Application](#running-the-application)
-- [Upgrading the Application](#upgrading-the-application)
-  - [Using Deployment Slots (Recommended for Production/Staging)](#using-deployment-slots-recommended-for-productionstaging)
-  - [Using Direct Deployment to Production (Simpler, for Dev/Test or Low Impact Changes)](#using-direct-deployment-to-production-simpler-for-devtest-or-low-impact-changes)
-  - [Automate via CI/CD](#automate-via-cicd)
-- [Return to Setup Instructions](./setup_instructions.md)
-
-
-> <a href="#simple-chat---manual-setup-instructions" style="text-decoration: none;">Return to top</a>
+---
+layout: showcase-page
+title: "Manual Setup"
+permalink: /setup_instructions_manual/
+menubar: docs_menu
+accent: slate
+eyebrow: "Deployment Reference"
+description: "Use the manual path when you need direct control over Azure resources, identity wiring, environment variables, and deployment mechanics."
+hero_icons:
+  - bi-terminal
+  - bi-cloud-check
+  - bi-tools
+hero_pills:
+  - Direct Azure provisioning
+  - Explicit identity setup
+  - Best for controlled enterprise rollouts
+hero_links:
+  - label: Back to getting started
+    url: /setup_instructions/
+    style: primary
+  - label: Special setup scenarios
+    url: /setup_instructions_special/
+    style: secondary
+show_nav: true
+nav_links:
+  prev:
+    title: Getting Started
+    url: /setup_instructions/
+  next:
+    title: Special Setup Scenarios
+    url: /setup_instructions_special/
+---
+This guide is for teams that need to provision every dependency themselves, integrate with existing standards, or understand the full deployment surface before they automate it.
+
+<section class="latest-release-card-grid">
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-cloud-plus"></i></div>
+        <h2>Provision Azure resources</h2>
+        <p>Stand up App Service, Azure OpenAI, Search, Cosmos DB, Document Intelligence, and the optional services needed for your chosen feature set.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-person-lock"></i></div>
+        <h2>Configure identity and auth</h2>
+        <p>Set up the Entra app registration, App Service authentication, Graph permissions, app roles, and any managed identity access the runtime requires.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-code-square"></i></div>
+        <h2>Deploy application code</h2>
+        <p>Clone the repo, populate settings, initialize search indexes, and deploy through VS Code or Azure CLI depending on your workflow.</p>
+    </article>
+    <article class="latest-release-card">
+        <div class="latest-release-card-icon"><i class="bi bi-arrow-repeat"></i></div>
+        <h2>Run and upgrade safely</h2>
+        <p>Use deployment slots or another controlled promotion flow when you move from dev/test installs into production operations.</p>
+    </article>
+</section>
+
+<div class="latest-release-note-panel">
+    <h2>How to use this page</h2>
+    <p>Read it top to bottom the first time. After that, treat it as a reference for the specific step you are automating or verifying.</p>
+</div>
 
 ## Provision Azure Resources
 
diff --git a/docs/setup_instructions_special.md b/docs/setup_instructions_special.md
index 08332aed..c94da512 100644
--- a/docs/setup_instructions_special.md
+++ b/docs/setup_instructions_special.md
@@ -1,16 +1,55 @@
-# Simple Chat - Special Setup Instructions 
-
-- [Azure Government Configuration](#azure-government-configuration)
-- [How to use Managed Identity](#how-to-use-managed-identity)
-- [Enterprise Networking](#enterprise-networking)
-
-- [Return to Setup Instructions](./setup_instructions.md)
-
+---
+layout: showcase-page
+title: "Special Setup Scenarios"
+permalink: /setup_instructions_special/
+menubar: docs_menu
+accent: teal
+eyebrow: "Advanced Deployment Conditions"
+description: "Use this guide when the environment is not a standard commercial Azure rollout, or when identity and networking requirements are stricter than the default path."
+hero_icons:
+  - bi-shield-lock
+  - bi-globe-americas
+  - bi-diagram-3
+hero_pills:
+  - Azure Government support
+  - Managed identity patterns
+  - Enterprise private networking
+hero_links:
+  - label: Back to getting started
+    url: /setup_instructions/
+    style: primary
+  - label: Manual setup reference
+    url: /setup_instructions_manual/
+    style: secondary
+show_nav: true
+nav_links:
+  prev:
+    title: Manual Setup
+    url: /setup_instructions_manual/
+---
+
+This page covers the deployment conditions that usually force teams off the quickest path: sovereign cloud requirements, secretless runtime access, and private network topologies.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-building-lock"></i></div>
+      <h2>Azure Government</h2>
+      <p>Adjust environment settings, endpoints, and identity registration so the application uses the correct sovereign cloud authorities and service domains.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-person-badge"></i></div>
+      <h2>Managed identity</h2>
+      <p>Replace stored keys with role-assigned resource access where the service supports it, and keep App Registration focused on user authentication.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+      <h2>Enterprise networking</h2>
+      <p>Use private endpoints, VNet integration, dedicated subnets, and private DNS zones so app-to-service traffic stays on the Azure backbone.</p>
+   </article>
+</section>
 
 ## Azure Government Configuration
 
-> <a href="#simple-chat---special-setup-instructions" style="text-decoration: none;">Return to top</a>
-
 To run the application in Azure Government cloud:
 
 1. **Deploy Resources**: Provision all necessary Azure resources (App Service, OpenAI, Cosmos DB, etc.) within your Azure Government subscription and appropriate Gov regions.
@@ -31,8 +70,6 @@ To run the application in Azure Government cloud:
 
 ## How to use Managed Identity
 
-> <a href="#simple-chat---special-setup-instructions" style="text-decoration: none;">Return to top</a>
-
 Using Managed Identity allows the App Service to authenticate to other Azure resources securely without needing to store secrets (like API keys or connection strings) in Application Settings.
 
 > [!TIP]
@@ -91,7 +128,6 @@ Using Managed Identity allows the App Service to authenticate to other Azure res
    - **Speech and Video Indexer**: In Search & Extract → Multimedia Support, the Speech section is shared by audio uploads, speech-to-text input, and text-to-speech. Video Indexer uses the App Service managed identity and the cloud/end-point selector rather than a Video Indexer API key.
 
 ## Enterprise Networking
-> <a href="#simple-chat---special-setup-instructions" style="text-decoration: none;">Return to top</a>
 
 ![Architecture with Private Endpoints](./images/architecture-private-endpoints.png)
 
diff --git a/docs/troubleshooting/troubleshooting.md b/docs/troubleshooting/troubleshooting.md
index 12c646dd..96c73018 100644
--- a/docs/troubleshooting/troubleshooting.md
+++ b/docs/troubleshooting/troubleshooting.md
@@ -1,40 +1,78 @@
-# Troubleshooting
+---
+layout: showcase-page
+title: "Troubleshooting"
+permalink: /troubleshooting/
+menubar: docs_menu
+accent: rose
+eyebrow: "Diagnose The Right Layer"
+description: "Start with telemetry, narrow the failing request path, and then decide whether the issue is instrumentation, configuration, or a backend dependency."
+hero_icons:
+  - bi-wrench-adjustable-circle
+  - bi-bug
+  - bi-activity
+hero_pills:
+  - Observe before changing config
+  - Use Application Insights traces
+  - Restart only when required
+hero_links:
+  - label: Review workflows
+    url: /application_workflows/
+    style: primary
+  - label: Check admin configuration
+    url: /admin_configuration/
+    style: secondary
+---
+Most support work on Simple Chat starts with one question: is the failure in the app layer, in telemetry wiring, or in a downstream Azure dependency? This page gives the shortest path to answer that question.
 
-- [OpenTelemetry Settings](#opentelemetry-settings)
-- [Backend call failing](#backend-call-failing)
-- [Flask Instrumentation Startup Error](#flask-instrumentation-startup-error)
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-bar-chart"></i></div>
+		<h2>OpenTelemetry settings</h2>
+		<p>Use the official Azure Monitor and OpenTelemetry references when instrumentation variables or exporter settings are in question.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-diagram-3"></i></div>
+		<h2>Failing backend calls</h2>
+		<p>Trace the failed request in Application Insights first, capture the `operation_Id`, and pivot from requests into exceptions.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-power"></i></div>
+		<h2>Startup instrumentation errors</h2>
+		<p>If Flask instrumentation itself is breaking startup, disable it explicitly with an environment variable and restart the app.</p>
+	</article>
+</section>
 
 ## OpenTelemetry Settings
 
-- [Azure Monitor Info](https://pypi.org/project/azure-monitor-opentelemetry)
-- [OpenTelemetry Settings](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/)
+- [Azure Monitor OpenTelemetry distribution](https://pypi.org/project/azure-monitor-opentelemetry/)
+- [OpenTelemetry SDK environment variable reference](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/)
 
-## Backend call failing
+## Backend Call Failing
 
-SimpleChat uses flask instrumentation by default and backend calls are logged to Application Insights.  Query the 'requests' table to find the failing call and note the 'operation_Id'.  Use the operation ID to find associated exceptions like below.
+Simple Chat uses Flask instrumentation by default, and backend calls are logged to Application Insights. Start with the `requests` table to find the failing call, capture the `operation_Id`, and use that identifier to pivot into related exceptions.
 
 ### Query failed requests
 
-```
+```kusto
 requests
 | where success == false
 ```
 
 ### Query most recent exceptions
 
-```
+```kusto
 exceptions
 | top 10 by timestamp
 ```
 
-### Query exceptions associated with a specific operation_Id
+### Query exceptions associated with a specific `operation_Id`
 
-```
+```kusto
 exceptions
 | where operation_Id == '61a97b6a6ddc11b465b5289738bddcf1'
 ```
 
 ## Flask Instrumentation Startup Error
 
-If startup logs show an error initializing Flask Instrumentation it can be disabled using environment variable DISABLE_FLASK_INSTRUMENTATION.  Set it to '1' or 'true' to disable flask instrumentation. **REQUIRES APP RESTART**.
+If startup logs show an error while Flask instrumentation is initializing, disable it with the `DISABLE_FLASK_INSTRUMENTATION` environment variable. Set the value to `1` or `true`, then restart the app service so the process starts cleanly without the instrumentation hook.
 
diff --git a/docs/tutorials/classifying_documents.md b/docs/tutorials/classifying_documents.md
index de86f41a..c04ad10b 100644
--- a/docs/tutorials/classifying_documents.md
+++ b/docs/tutorials/classifying_documents.md
@@ -1,22 +1,55 @@
-# Document Classification Tutorial
-
-Document classification helps you organize, categorize, and manage your content in Simple Chat. This tutorial will guide you through setting up and using classification schemes to improve your document organization and discovery.
-
-## What You'll Learn
-
-By the end of this tutorial, you'll:
-- Understand the benefits of document classification
-- Set up classification categories as an admin
-- Apply classifications when uploading documents
-- Use classifications to organize and filter content
-- Create workflows that leverage document types
-- Understand how classifications improve AI responses
-
-## Prerequisites
+---
+layout: showcase-page
+title: "Document Classification Tutorial"
+permalink: /tutorials/classifying_documents/
+menubar: docs_menu
+accent: emerald
+eyebrow: "Tutorial 4"
+description: "Build a classification scheme that helps users organize content, filter retrieval, and support real workflows instead of just adding labels for decoration."
+hero_icons:
+  - bi-tags
+  - bi-funnel
+  - bi-grid-3x3-gap
+hero_pills:
+  - Better organization
+  - Better filtering
+  - Better context for AI responses
+hero_links:
+  - label: Tutorial index
+    url: /tutorials/
+    style: primary
+  - label: Admin configuration
+    url: /admin_configuration/
+    style: secondary
+show_nav: true
+nav_links:
+   prev:
+      title: Uploading and Managing Documents
+      url: /tutorials/uploading_documents/
+   next:
+      title: How-to Guides
+      url: /how-to/
+---
 
-- Simple Chat deployed with admin access
-- Some documents already uploaded (recommended)
-- Understanding of your organization's document types
+Classification works when the categories reflect how your organization actually handles content. This tutorial focuses on making the labels operational, not decorative.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-list-check"></i></div>
+      <h2>Plan the scheme</h2>
+      <p>Choose categories that match departments, document types, sensitivity, or project flows your users already recognize.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-sliders"></i></div>
+      <h2>Configure and apply</h2>
+      <p>Enable classification as an admin, expose the categories to users, and make classification part of the upload flow.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-chat-quote"></i></div>
+      <h2>Use the context</h2>
+      <p>Once documents are classified, filtering, search, routing, and chat context become more predictable and more useful.</p>
+   </article>
+</section>
 
 ## What Is Document Classification?
 
diff --git a/docs/tutorials/first_agent.md b/docs/tutorials/first_agent.md
index 93fdfc6c..6a2e7be6 100644
--- a/docs/tutorials/first_agent.md
+++ b/docs/tutorials/first_agent.md
@@ -1,22 +1,55 @@
-# Create Your First Agent
-
-Agents in Simple Chat allow you to create specialized AI assistants with custom behavior, knowledge, and capabilities. This tutorial will guide you through creating your first agent from scratch.
-
-## What You'll Learn
-
-By the end of this tutorial, you'll:
-- Understand what agents are and how they work
-- Create a custom agent with specialized knowledge
-- Configure agent behavior and personality
-- Test your agent with real conversations
-- Understand how agents use workspaces and documents
-
-## Prerequisites
+---
+layout: showcase-page
+title: "Create Your First Agent"
+permalink: /tutorials/first_agent/
+menubar: docs_menu
+accent: violet
+eyebrow: "Tutorial 2"
+description: "Create a focused agent, connect it to the right knowledge scope, and test whether its behavior matches the role you intended."
+hero_icons:
+  - bi-person-badge
+  - bi-lightning-charge
+  - bi-chat-dots
+hero_pills:
+  - Define the role clearly
+  - Scope the knowledge correctly
+  - Test and refine behavior
+hero_links:
+  - label: Tutorial index
+    url: /tutorials/
+    style: primary
+  - label: Review admin configuration
+    url: /admin_configuration/
+    style: secondary
+show_nav: true
+nav_links:
+   prev:
+      title: Getting Started with Simple Chat
+      url: /tutorials/getting_started/
+   next:
+      title: Uploading and Managing Documents
+      url: /tutorials/uploading_documents/
+---
 
-- Simple Chat already deployed and configured
-- Basic familiarity with the Simple Chat interface
-- Completed [Getting Started tutorial](getting_started) (recommended)
-- Some documents uploaded to work with
+Agents are most useful when they are specific. This tutorial shows how to define that specificity in instructions, data access, and testing rather than relying on a generic assistant prompt.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-bullseye"></i></div>
+      <h2>Focus the role</h2>
+      <p>Give the agent a clear purpose, a clear audience, and a response style that fits the work you expect it to do.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-folder-check"></i></div>
+      <h2>Attach the right knowledge</h2>
+      <p>Choose only the workspaces and documents that support the role so retrieval stays relevant and the agent does not wander.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-arrow-repeat"></i></div>
+      <h2>Refine quickly</h2>
+      <p>Test realistic prompts, tighten the instructions, and repeat until the behavior is consistently useful.</p>
+   </article>
+</section>
 
 ## What Are Agents?
 
diff --git a/docs/tutorials/getting_started.md b/docs/tutorials/getting_started.md
index bd100c08..2b6668e2 100644
--- a/docs/tutorials/getting_started.md
+++ b/docs/tutorials/getting_started.md
@@ -1,21 +1,52 @@
-# Getting Started with Simple Chat
-
-Welcome! This tutorial will walk you through your first experience with Simple Chat - from deployment to having your first AI-powered conversation with your own documents.
-
-## What You'll Learn
-
-By the end of this tutorial, you'll:
-- Deploy Simple Chat to Azure
-- Set up your first workspace  
-- Upload a document
-- Have a conversation that uses your document for context
-- Understand the basic navigation and features
-
-## Prerequisites
+---
+layout: showcase-page
+title: "Getting Started with Simple Chat"
+permalink: /tutorials/getting_started/
+menubar: docs_menu
+accent: blue
+eyebrow: "Tutorial 1"
+description: "Deploy the app, enable a workspace, upload one document, and ask the first retrieval-backed question."
+hero_icons:
+  - bi-rocket-takeoff
+  - bi-cloud-arrow-up
+  - bi-chat-left-text
+hero_pills:
+  - First deployment
+  - First workspace
+  - First grounded conversation
+hero_links:
+  - label: Deployment reference
+    url: /setup_instructions/
+    style: primary
+  - label: Tutorial index
+    url: /tutorials/
+    style: secondary
+show_nav: true
+nav_links:
+   next:
+      title: Create Your First Agent
+      url: /tutorials/first_agent/
+---
 
-- An Azure subscription with permissions to create resources
-- Basic familiarity with Azure portal
-- A document you'd like to chat with (PDF, Word doc, or text file)
+This tutorial is the shortest useful path into the product. You will deploy Simple Chat, wire the essentials, add one document, and prove the retrieval loop works.
+
+<section class="latest-release-card-grid">
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-check2-square"></i></div>
+      <h2>You will do</h2>
+      <p>Deploy the app, enable a workspace, upload a document, and run a cited conversation against your own content.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-list-task"></i></div>
+      <h2>You need</h2>
+      <p>An Azure subscription with resource permissions, basic Azure familiarity, and a sample document you can safely upload.</p>
+   </article>
+   <article class="latest-release-card">
+      <div class="latest-release-card-icon"><i class="bi bi-arrow-right-circle"></i></div>
+      <h2>After this</h2>
+      <p>Move on to agents once the base chat and retrieval loop is working end to end.</p>
+   </article>
+</section>
 
 ## Step 1: Deploy Simple Chat
 
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
index e3a776e9..9624d2e9 100644
--- a/docs/tutorials/index.md
+++ b/docs/tutorials/index.md
@@ -1,13 +1,52 @@
 ---
-layout: page
-title: Tutorials
-subtitle: Learn by doing
+layout: showcase-page
+title: "Tutorials"
+permalink: /tutorials/
 menubar: docs_menu
+accent: amber
+eyebrow: "Learn By Doing"
+description: "Follow the tutorial track from first deployment through agents, document handling, and classification without needing to jump between the full reference sections."
+hero_icons:
+  - bi-mortarboard
+  - bi-signpost-split
+  - bi-lightbulb
+hero_pills:
+  - Guided product onboarding
+  - End-user and admin basics
+  - Short practical sequences
+hero_links:
+  - label: Start the first tutorial
+    url: /tutorials/getting_started/
+    style: primary
+  - label: Browse how-to guides
+    url: /how-to/
+    style: secondary
 ---
+This section is written for teams that want momentum first. Each page is a short path through one capability, with enough context to be useful and not so much detail that onboarding stalls.
 
-Welcome to the **Tutorials** section. Here you’ll find step-by-step lessons to get started with Simple Chat.
-
-- [Getting Started](/tutorials/getting_started/)
-- [Create Your First Agent](/tutorials/first_agent/)
-- [Upload and Use Documents](/tutorials/uploading_documents/)
-- [Classify Documents](/tutorials/classifying_documents/)
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-rocket-takeoff"></i></div>
+		<h2>Getting Started</h2>
+		<p>Deploy Simple Chat, configure the basics, upload a document, and run the first grounded conversation.</p>
+		<p><a href="{{ '/tutorials/getting_started/' | relative_url }}">Open tutorial</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-person-badge"></i></div>
+		<h2>Create Your First Agent</h2>
+		<p>Define an agent role, tune its instructions, connect it to the right knowledge sources, and test the behavior.</p>
+		<p><a href="{{ '/tutorials/first_agent/' | relative_url }}">Open tutorial</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-file-earmark-arrow-up"></i></div>
+		<h2>Upload and Use Documents</h2>
+		<p>Learn the workspace types, supported content formats, processing states, and the best practices for keeping retrieval clean.</p>
+		<p><a href="{{ '/tutorials/uploading_documents/' | relative_url }}">Open tutorial</a></p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-tags"></i></div>
+		<h2>Classify Documents</h2>
+		<p>Set up document classification and use it to organize uploads, filter content, and improve team workflows.</p>
+		<p><a href="{{ '/tutorials/classifying_documents/' | relative_url }}">Open tutorial</a></p>
+	</article>
+</section>
diff --git a/docs/tutorials/uploading_documents.md b/docs/tutorials/uploading_documents.md
index d1c7ab99..82aca44b 100644
--- a/docs/tutorials/uploading_documents.md
+++ b/docs/tutorials/uploading_documents.md
@@ -1,22 +1,54 @@
-# Uploading and Managing Documents
-
-Documents are the foundation of Simple Chat's Retrieval-Augmented Generation (RAG) capabilities. This tutorial will teach you everything you need to know about uploading, organizing, and managing your documents effectively.
-
-## What You'll Learn
-
-By the end of this tutorial, you'll:
-- Upload documents to different workspace types
-- Understand document processing and status indicators
-- Organize documents effectively
-- Handle different file types and formats
-- Troubleshoot common upload issues
-- Manage document versions and updates
-
-## Prerequisites
-
-- Simple Chat deployed and configured
-- Basic workspace setup completed
-- Admin permissions for workspace configuration
+---
+layout: showcase-page
+title: "Uploading and Managing Documents"
+permalink: /tutorials/uploading_documents/
+menubar: docs_menu
+accent: orange
+eyebrow: "Tutorial 3"
+description: "Learn how to put the right files into the right workspace, recognize processing states, and keep retrieval clean as content grows."
+hero_icons:
+  - bi-file-earmark-arrow-up
+  - bi-folder2-open
+  - bi-search
+hero_pills:
+  - Workspace-aware uploads
+  - Processing and status basics
+  - Retrieval quality starts here
+hero_links:
+  - label: Tutorial index
+    url: /tutorials/
+    style: primary
+  - label: Feature overview
+    url: /features/
+    style: secondary
+show_nav: true
+nav_links:
+  prev:
+    title: Create Your First Agent
+    url: /tutorials/first_agent/
+  next:
+    title: Document Classification Tutorial
+    url: /tutorials/classifying_documents/
+---
+Retrieval quality starts with disciplined uploads. This tutorial explains where documents belong, how processing works, and how to keep the knowledge base understandable as it expands.
+
+<section class="latest-release-card-grid">
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-diagram-2"></i></div>
+		<h2>Pick the right workspace</h2>
+		<p>Personal, group, and ephemeral content each serve a different purpose. Start by placing the file where the future conversation should happen.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-filetype-doc"></i></div>
+		<h2>Know the input types</h2>
+		<p>Text, Office, image, audio, and video inputs follow different extraction paths, so supported types and file quality matter.</p>
+	</article>
+	<article class="latest-release-card">
+		<div class="latest-release-card-icon"><i class="bi bi-tags"></i></div>
+		<h2>Organize for reuse</h2>
+		<p>Classification, naming, and cleanup practices matter because they directly shape how easy it is to search, cite, and maintain content later.</p>
+	</article>
+</section>
 
 ## Understanding Workspaces
 
diff --git a/ui_tests/test_docs_showcase_pages.py b/ui_tests/test_docs_showcase_pages.py
new file mode 100644
index 00000000..ed94beda
--- /dev/null
+++ b/ui_tests/test_docs_showcase_pages.py
@@ -0,0 +1,116 @@
+# test_docs_showcase_pages.py
+"""
+UI test for docs showcase pages.
+Version: 0.241.010
+Implemented in: 0.241.010
+
+This test ensures that the redesigned docs landing pages, reference guides,
+how-to guides, tutorials, and troubleshooting pages render the shared
+latest-release-style hero and page-specific content blocks at desktop and
+mobile viewport sizes, and that features page preview images open in the
+shared popup modal.
+"""
+
+import os
+
+import pytest
+from playwright.sync_api import expect
+
+
+DOCS_BASE_URL = os.getenv("SIMPLECHAT_DOCS_BASE_URL", "").rstrip("/")
+
+VIEWPORTS = [
+    pytest.param({"width": 1440, "height": 960}, id="desktop"),
+    pytest.param({"width": 390, "height": 844}, id="mobile"),
+]
+
+PAGES = [
+    pytest.param("/", "Simple Chat Documentation", ".latest-release-note-panel", id="home"),
+    pytest.param("/setup_instructions/", "Getting Started", "nav.page-navigation", id="getting-started"),
+    pytest.param("/features/", "Features", "[data-latest-feature-image-src] img", id="features"),
+    pytest.param("/faqs/", "FAQ", ".latest-release-archive-panel", id="faq"),
+    pytest.param("/about/", "About Simple Chat", "h2:has-text('Built as an open repo')", id="about"),
+    pytest.param("/contributing/", "Working in the repo", "h2:has-text('Contribution workflow')", id="contributing"),
+    pytest.param("/admin_configuration/", "Admin Configuration", "img[src*='admin_settings_page.png']", id="admin-config"),
+    pytest.param("/application_scaling/", "Application Scaling", "img[src*='scale-cosmos.png']", id="scaling"),
+    pytest.param("/application_workflows/", "Application Workflows", "img[src*='workflow-content_safety.png']", id="workflows"),
+    pytest.param("/demos/", "Solution Demonstrations", "img[src*='UploadDocumentDemo.gif']", id="demos"),
+    pytest.param("/external_apps_overview/", "External Applications Overview", ".latest-release-note-panel", id="external-apps"),
+    pytest.param("/setup_instructions_manual/", "Manual Setup", "h2:has-text('Provision Azure Resources')", id="manual-setup"),
+    pytest.param("/setup_instructions_special/", "Special Setup Scenarios", "img[src*='architecture-private-endpoints.png']", id="special-setup"),
+    pytest.param("/tutorials/", "Tutorials", "a[href$='/tutorials/classifying_documents/']", id="tutorials-index"),
+    pytest.param("/tutorials/getting_started/", "Getting Started with Simple Chat", "h2:has-text('Step 1: Deploy Simple Chat')", id="tutorial-getting-started"),
+    pytest.param("/tutorials/first_agent/", "Create Your First Agent", "h2:has-text('What Are Agents?')", id="tutorial-first-agent"),
+    pytest.param("/tutorials/uploading_documents/", "Uploading and Managing Documents", "h2:has-text('Understanding Workspaces')", id="tutorial-uploading"),
+    pytest.param("/tutorials/classifying_documents/", "Document Classification Tutorial", "h2:has-text('What Is Document Classification?')", id="tutorial-classifying"),
+    pytest.param("/troubleshooting/", "Troubleshooting", "text=DISABLE_FLASK_INSTRUMENTATION", id="troubleshooting"),
+    pytest.param("/reference/admin_configuration/", "Admin Configuration Reference", "h2:has-text('Read the settings in dependency order')", id="reference-admin-config"),
+    pytest.param("/reference/api_reference/", "API Reference", "h2:has-text('Documentation endpoints')", id="reference-api"),
+    pytest.param("/reference/features/", "Features Reference", "h2:has-text('Feature map by operating area')", id="reference-features"),
+    pytest.param("/reference/deploy/", "Deployment Reference", "h2:has-text('Recommended order')", id="reference-deploy"),
+    pytest.param("/reference/deploy/azd-cli_deploy/", "Azure Developer CLI Deployment", "h2:has-text('Startup command rule for this path')", id="reference-azd"),
+    pytest.param("/reference/deploy/azurecli_powershell_deploy/", "Azure CLI with PowerShell Deployment", "h2:has-text('When to choose this path')", id="reference-azurecli"),
+    pytest.param("/reference/deploy/bicep_deploy/", "Bicep Deployment", "h2:has-text('Recommended workflow')", id="reference-bicep"),
+    pytest.param("/reference/deploy/manual_deploy/", "Manual Deployment Notes", "h2:has-text('Native Python App Service Startup Command')", id="reference-manual"),
+    pytest.param("/reference/deploy/terraform_deploy/", "Terraform Deployment", "h2:has-text('Current behavior')", id="reference-terraform"),
+    pytest.param("/how-to/", "How-To Guides", "a[href$='/how-to/agents/ServiceNow/']", id="howto-index"),
+    pytest.param("/how-to/add_documents/", "Add Documents", "h2:has-text('Recommended upload flow')", id="howto-add-documents"),
+    pytest.param("/how-to/create_agents/", "Create Agents", "h2:has-text('Minimum viable agent setup')", id="howto-create-agents"),
+    pytest.param("/how-to/docker_customization/", "Docker Customization", "h2:has-text('Custom Certificate Authorities')", id="howto-docker"),
+    pytest.param("/how-to/enterprise_networking/", "Enterprise Networking", "img[src*='architecture-private-endpoints-commercial.png']", id="howto-enterprise-networking"),
+    pytest.param("/how-to/scaling_on_azure/", "Scale Simple Chat on Azure", "h2:has-text('When to Scale')", id="howto-scaling"),
+    pytest.param("/how-to/upgrade_paths/", "Upgrade Paths", "h2:has-text('Choose the Right Upgrade Path')", id="howto-upgrade-paths"),
+    pytest.param("/how-to/use_managed_identity/", "Use Managed Identity", "h2:has-text('What is Managed Identity?')", id="howto-managed-identity"),
+    pytest.param("/how-to/azure_speech_managed_identity_manul_setup/", "Azure Speech Managed Identity Setup", "h2:has-text('Authentication Methods')", id="howto-speech-managed-identity"),
+    pytest.param("/how-to/agents/ServiceNow/", "ServiceNow Agent Guides", "a[href$='/how-to/agents/ServiceNow/servicenow_oauth_setup/']", id="howto-servicenow-index"),
+    pytest.param("/how-to/agents/ServiceNow/servicenow_integration/", "ServiceNow Integration", "h2:has-text('Integration Architecture')", id="howto-servicenow-integration"),
+    pytest.param("/how-to/agents/ServiceNow/servicenow_oauth_setup/", "ServiceNow OAuth 2.0 Setup", "h2:has-text('Part 1: Configure OAuth in ServiceNow')", id="howto-servicenow-oauth"),
+    pytest.param("/how-to/agents/ServiceNow/two_agent_setup/", "ServiceNow Two-Agent Setup", "h2:has-text('Agent 1: ServiceNow Support Agent')", id="howto-servicenow-two-agent"),
+    pytest.param("/how-to/agents/ServiceNow/servicenow_asset_management_setup/", "ServiceNow Asset Management Setup", "h2:has-text('Step 1: Create ServiceNow Actions')", id="howto-servicenow-asset"),
+    pytest.param("/explanation/", "Explanation", "h2:has-text('Continue into deeper references')", id="explanation-index"),
+    pytest.param("/explanation/architecture/", "Architecture", "h2:has-text('System Overview')", id="explanation-architecture"),
+    pytest.param("/explanation/design_principles/", "Design Principles", "h2:has-text('Core Philosophy')", id="explanation-design-principles"),
+    pytest.param("/explanation/feature_guidance/", "Feature Guidance", "h2:has-text('Rollout groups')", id="explanation-feature-guidance"),
+    pytest.param("/explanation/running_simplechat_locally/", "Running Simple Chat Locally", "h2:has-text('VS Code Python 3.12 Setup')", id="explanation-running-locally"),
+    pytest.param("/explanation/running_simplechat_azure_production/", "Running Simple Chat in Azure Production", "h2:has-text('Default Azure Production Model in This Repo')", id="explanation-running-azure"),
+]
+
+
+def _require_docs_base_url():
+    if not DOCS_BASE_URL:
+        pytest.skip("Set SIMPLECHAT_DOCS_BASE_URL to run this docs UI test.")
+
+
+@pytest.mark.ui
+@pytest.mark.parametrize("viewport", VIEWPORTS)
+@pytest.mark.parametrize("path, heading, specific_selector", PAGES)
+def test_docs_showcase_pages(playwright, viewport, path, heading, specific_selector):
+    """Validate the redesigned docs pages at desktop and mobile breakpoints."""
+    _require_docs_base_url()
+
+    browser = playwright.chromium.launch()
+    context = browser.new_context(viewport=viewport)
+
+    try:
+        page = context.new_page()
+        response = page.goto(
+            f"{DOCS_BASE_URL}{path}",
+            wait_until="domcontentloaded",
+            timeout=60000,
+        )
+        assert response is not None, f"Expected a navigation response when loading {path}."
+        assert response.ok, f"Expected {path} to load successfully, got HTTP {response.status}."
+
+        expect(page.locator(".latest-release-hero")).to_be_visible()
+        expect(page.get_by_role("heading", name=heading, exact=True)).to_be_visible()
+        expect(page.locator(".latest-release-hero-actions .btn").first).to_be_visible()
+        expect(page.locator(".latest-release-card-grid").first).to_be_visible()
+        expect(page.locator(specific_selector).first).to_be_visible()
+
+        if path == "/features/":
+            page.locator("[data-latest-feature-image-src]").first.click()
+            expect(page.locator("#latestFeatureImageModal")).to_be_visible()
+            expect(page.locator("#latestFeatureImageModalLabel")).to_have_text("Architecture overview")
+    finally:
+        context.close()
+        browser.close()
\ No newline at end of file