feat(docs): generalize headless deployment documentation and add new guide

Author: rstrahan

CHANGELOG.md

@@ -16,6 +16,10 @@ SPDX-License-Identifier: MIT-0
   - Additive: classes without the new flag behave exactly as before.
   - See `docs/classification.md#excluding-static-pages-eg-instructions-legal-boilerplate`.
 
+### Changed
+
+- **Headless deployment documentation generalized** — headless mode is no longer documented as a GovCloud-only capability. New `docs/headless-deployment.md` is the canonical guide covering headless deployment for both Commercial and GovCloud regions (API-only / pipeline integrations, organizational restrictions on UI-layer services, cost optimization, and required for GovCloud). 
+
 ## Templates
    - us-west-2: `https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/genai-idp/idp-main_0.5.8.yaml`
    - us-east-1: `https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/genai-idp/idp-main_0.5.8.yaml`

README.md

@@ -174,6 +174,7 @@ For detailed deployment and testing instructions, see the [Deployment Guide](./d
 - [Architecture](./docs/architecture.md) - Detailed component architecture and data flow
 - [Demo Videos](./docs/demo-videos.md) - Comprehensive collection of feature demonstration videos
 - [Deployment](./docs/deployment.md) - Build, publish, deploy, and test instructions
+- [Headless Deployment](./docs/headless-deployment.md) - Backend-only deployment (no UI/AppSync/Cognito/WAF) for API-only use cases; required for GovCloud
 - [IDP CLI](./docs/idp-cli.md) - Command line interface for batch processing, evaluation workflows, and interactive Agent Chat
 - [Web UI](./docs/web-ui.md) - Web interface features and usage
 - [Agent Analysis](./docs/agent-analysis.md) - Natural language analytics and data visualization feature

VERSION

@@ -1 +1 @@
-0.5.8.rc1
+0.5.8.rc2

docs-site/astro.config.mjs

@@ -37,6 +37,7 @@ export default defineConfig({
           items: [
             { label: "Architecture", slug: "architecture" },
             { label: "Deployment", slug: "deployment" },
+            { label: "Headless Deployment", slug: "headless-deployment" },
             { label: "ALB Hosting", slug: "alb-hosting" },
             { label: "Private Network Deployment", slug: "deployment-private-network" },
             { label: "Configuration", slug: "configuration" },

docs/README.md

@@ -13,6 +13,7 @@ This folder contains detailed documentation on various aspects of the GenAI Inte
 
 - [Architecture](./architecture.md) - Detailed component architecture and data flow
 - [Deployment](./deployment.md) - Build, publish, deploy, and test instructions
+- [Headless Deployment](./headless-deployment.md) - Backend-only deployment (no UI/AppSync/Cognito/WAF) — for API-only / pipeline integrations in Commercial regions and required for GovCloud
 - [Configuration](./configuration.md) - Configuration and customization options
 - [Configuration Versions](./configuration-versions.md) - Managing multiple configuration versions
 - [IDP Configuration Best Practices](./idp-configuration-best-practices.md) - Guidelines for effective configuration design
@@ -76,8 +77,8 @@ This folder contains detailed documentation on various aspects of the GenAI Inte
 
 - [Well-Architected Framework Assessment](./well-architected.md) - Analysis based on AWS Well-Architected Framework
 - [AWS Services & IAM Roles](./aws-services-and-roles.md) - AWS services used and IAM role requirements
-- [ALB Hosting](./alb-hosting.md) - ALB+S3 hosting for private network and GovCloud deployments
-- [GovCloud Deployment](./govcloud-deployment.md) - Deployment guide for AWS GovCloud regions
+- [ALB Hosting](./alb-hosting.md) - ALB+S3 hosting to serve the full Web UI from within a VPC (alternative to CloudFront)
+- [GovCloud Deployment](./govcloud-deployment.md) - GovCloud-specific considerations on top of headless deployment
 - [EU Region Model Support](./eu-region-model-support.md) - Model availability in EU regions
 
 ## Development Setup

docs/alb-hosting.md

@@ -22,7 +22,7 @@ ALB hosting is designed for organizations that need the full IDP web UI but cann
 - **Corporate network restrictions** — organizations where users access applications exclusively through VPN or Direct Connect, and public CDN endpoints are blocked by policy
 - **Air-gapped or isolated VPCs** — environments with no internet egress where CloudFront cannot function
 
-> **Note on GovCloud**: GovCloud deployments use a separate headless template (no web UI or AppSync). ALB hosting is not applicable to GovCloud — see [GovCloud Deployment](./govcloud-deployment.md) instead.
+> **Note on Headless / GovCloud**: ALB hosting keeps the **full Web UI** but serves it privately through an ALB. It is **not** the same as a [Headless Deployment](./headless-deployment.md), which removes the UI entirely (along with AppSync, Cognito, WAF). GovCloud always uses headless mode (UI-layer services are unavailable in GovCloud) — see [GovCloud Deployment](./govcloud-deployment.md). Use ALB hosting only when you **do** want the UI but cannot use CloudFront.
 
 ## Architecture
 

docs/deployment.md

@@ -191,7 +191,7 @@ idp-cli publish --source-dir . --region <region> [--bucket-basename <bucket>] [-
 - `--verbose` or `-v`: (Optional) Enable detailed error output for debugging build failures
 - `--clean-build`: (Optional) Force a clean rebuild of all artifacts
 - `--max-workers N`: (Optional) Number of parallel build workers
-- `--headless`: (Optional) Also generate a headless (no-UI) template variant for GovCloud
+- `--headless`: (Optional) Also generate a **headless (no-UI) template variant**. Useful for API-only / pipeline integrations in Commercial regions and **required** for GovCloud deployments. See [Headless Deployment](./headless-deployment.md).
 
 **Example:**