Merge pull request #19 from ipbabble/docs/templates-update-for-deep-agent

docs: Deep Agent stack documentation update (August 2026)

Author: ipbabble

CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to the AI Templates documentation site will be documented in
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.1.0] - 2026-08-12
+
+### Added
+
+**Deep Agent stack documentation (August 2026)**
+
+- Homepage "What's New" block and updated template cards for Deep Agent merge
+- **News** section with layouts and three launch posts (Deep Agent merge, config-as-code, template-ui BFF update)
+- **Reference** section: stack architecture, config-as-code, enterprise features matrix, migration guide
+- Agent template: rewritten docs + new [Architecture](/templates/agent/architecture/) page
+- UI template: rewritten docs + new [Configuration](/templates/ui/configuration/) page (BFF explained)
+- MCP template quick-start: `make install` / `make local` workflow and port **5001**
+- External resource links (LangGraph, Deep Agents, Agent Skills, MCP, Langfuse) on reference hub
+
+### Changed
+
+- **Agent template docs** — Deep Agents + Aegra, `config/agent/`, LangGraph API on port 5002, Postgres/Redis prerequisites
+- **UI template docs** — Fastify BFF, `config/ui/settings.yaml`, `AGENT_HOST`, unified `npm run dev` workflow
+- **Guides** — [Agentic AI Workshop](/guides/agentic-ai-workshop/) updated for Deep Agent stack (MCP `make install`, `mcp.json`, LangGraph API, BFF)
+- **Reference tables** — aligned with template-mcp-server (OAuth server role, `deployment/openshift/`, MCP Postgres port note)
+- Figure caption styling for architecture diagrams (`.figure-caption` in custom CSS)
+
+### Documentation
+
+- Cross-links between templates, reference, news, and workshop guide
+- Navigation: News menu item (weight 45)
+
+---
+
 ## [1.0.0] - 2025-11-05
 
 ### Added
@@ -56,11 +85,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Track upcoming changes and enhancements here as the project evolves.
 
-### Planned for v1.1
-- Expand Guides section with tutorials
-- Add Reference section with API docs
+### Planned for v1.2
 - Complete Contribute section placeholders
 - Additional tool integrations
+- **MCP template quick-start** — `make install` / `make local` on port 5001
+
+### Completed in v1.1
+- Guides section workshop (agentic-ai-workshop)
+- Reference section (architecture, config, enterprise, migration)
+- News section
 
 ### Under Consideration
 

CONTRIBUTING.md

@@ -73,8 +73,44 @@ cd website
    - Go to https://github.com/redhat-data-and-ai/website
    - Click "New Pull Request"
    - Describe your changes
+   - Confirm the **Super linter** GitHub Actions check passes (required)
 
-## Documentation Standards
+## Before Submitting a Pull Request
+
+This site does **not** use [pre-commit](https://pre-commit.com/) hooks. Validation runs in CI and via Makefile targets.
+
+### Required checks
+
+```bash
+# Production Hugo build — must complete without errors
+hugo --gc --minify
+```
+
+Confirm the **Super linter** workflow passes on your pull request. That job runs on every PR and is the lint gate for this repository.
+
+### Optional local checks
+
+```bash
+# Super Linter (same as CI)
+make super-linter
+
+# Link checker (htmltest — also runs on a nightly schedule)
+make test
+
+# Spell check
+make spellcheck
+```
+
+**Apple Silicon Macs:** `make super-linter` often fails locally with `no image found ... architecture "arm64"` because the slim Super Linter image is x86-only. Use the PR's GitHub Actions result instead.
+
+### Checklist
+
+- [ ] `./serve.sh` — preview looks correct in the browser
+- [ ] `hugo --gc --minify` — builds without errors
+- [ ] Super linter CI check passes on the PR
+- [ ] Commands and paths in docs match the current template repositories
+- [ ] Code examples tested where applicable
+- [ ] No emojis in headings (see [Documentation Standards](#documentation-standards))
 
 ### Writing Style
 
@@ -139,11 +175,12 @@ content/
 
 ### Before Submitting
 
-- [ ] Test locally with `./serve.sh`
-- [ ] No build errors (check Hugo output)
-- [ ] All links work
-- [ ] Code examples are tested
-- [ ] Spelling checked
+- [ ] Preview with `./serve.sh`
+- [ ] `hugo --gc --minify` completes without errors
+- [ ] Super linter CI check passes (use GitHub Actions if `make super-linter` fails on Apple Silicon)
+- [ ] Commands and links verified against current template repos
+- [ ] Code examples tested
+- [ ] Spelling checked (`make spellcheck` optional)
 - [ ] Follows style guide
 
 ### PR Description Template
@@ -159,9 +196,10 @@ Brief description of changes
 - [ ] Documentation structure change
 
 ## Checklist
-- [ ] Tested locally
-- [ ] No build errors
-- [ ] Links verified
+- [ ] Previewed with `./serve.sh`
+- [ ] `hugo --gc --minify` succeeds
+- [ ] Super linter CI check passes
+- [ ] Links and commands verified
 - [ ] Follows style guide
 ```
 

README.md

@@ -21,12 +21,35 @@ brew install hugo asciidoctor
 ### Building
 
 ```bash
-# Build static site
-hugo --cleanDestinationDir
+# Production build (run before opening a PR)
+hugo --gc --minify
 
 # Output in public/ directory
 ```
 
+### Before Opening a Pull Request
+
+This repository does **not** use pre-commit hooks (unlike the template repos). CI runs **[Super Linter](https://github.com/super-linter/super-linter)** on every push and pull request.
+
+Run these checks locally before you push:
+
+```bash
+# 1. Production Hugo build (required — fast, works on all platforms)
+hugo --gc --minify
+
+# 2. Super Linter (matches CI — see note for Apple Silicon below)
+make super-linter
+
+# 3. Optional: link checker (nightly in CI, not PR-gated)
+make test
+```
+
+**Apple Silicon (M-series Mac):** `make super-linter` may fail locally because the slim Super Linter container image has no `linux/arm64` build. In that case, rely on the **Super linter** check on your pull request in GitHub Actions.
+
+**Development preview:** `./serve.sh` is for browsing changes at http://localhost:1313/ — it does not replace the production build step above.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#before-submitting-a-pull-request) for the full checklist.
+
 ## Repository Structure
 
 ```

config.yaml

@@ -56,6 +56,9 @@ menus:
     - name: Reference
       url: /reference/
       weight: 40
+    - name: News
+      url: /news/
+      weight: 45
     - name: GitHub
       url: https://github.com/redhat-data-and-ai
       weight: 50

content/_index.md

@@ -6,13 +6,17 @@ title: "AI Templates"
 
 Go beyond demos and proofs of concept. AI Templates deliver battle-tested, production-ready components for building AI applications on Kubernetes, following best practices.
 
+{{< info title="What's New" >}}
+**Deep Agent update (August 2026):** The Agent and UI templates have moved to [LangGraph Deep Agents](https://github.com/langchain-ai/deepagents). **template-agent** is now a config-as-code Deep Agent runtime (orchestrator, subagents, skills, MCP integration). **template-ui** has been updated to work with the new Deep Agent streaming API, including HITL interrupts, task progress, and markdown-first rendering. [Read the announcement →](/news/)
+{{< /info >}}
+
 ## What are AI Templates?
 
 AI Templates are reusable, modular components that accelerate your AI development journey. Each template is designed to work independently or as part of a complete AI application stack:
 
 - **[MCP Server Template](/templates/mcp-server/)** - Build Model Context Protocol servers that extend AI agent capabilities
-- **[Agent Template](/templates/agent/)** - Create LangGraph-based AI agents with enterprise security and observability
-- **[UI Template](/templates/ui/)** - Deploy modern chat interfaces that work seamlessly with our agent template
+- **[Agent Template](/templates/agent/)** - Deep Agent orchestration with config-as-code, subagents, skills, and enterprise observability
+- **[UI Template](/templates/ui/)** - React chat UI for the Deep Agent streaming API
 
 ## Why Use AI Templates?
 
@@ -38,7 +42,7 @@ Deploy anywhere - OpenShift, EKS, GKE, or any Kubernetes cluster.
 
 {{< mermaid >}}
 graph TD
-    A[User Interface<br/>template-ui] --> B[AI Agent Layer<br/>template-agent]
+    A[User Interface<br/>template-ui BFF] --> B[AI Deep Agent Layer<br/>template-agent]
     B --> C[MCP Server<br/>template-mcp-server]
     C --> D[External Systems<br/>Databases, APIs, Services]
 

content/contribute/contributing-docs.md

@@ -24,8 +24,8 @@ content/
 │   ├── agent/         # Agent guides
 │   └── ui/            # UI guides
 ├── tools/             # Tool setup guides
-├── guides/            # Tutorials (placeholder)
-└── reference/         # Technical reference (placeholder)
+├── guides/            # Tutorials and workshops
+└── reference/         # Stack architecture, config, enterprise features
 ```
 
 ## Writing Guidelines
@@ -68,17 +68,26 @@ graph TD
 
 ## Testing Changes
 
-Before submitting:
+This site does **not** use pre-commit hooks. Run these before opening a pull request:
 
 ```bash
-# Run local server
+# Preview in the browser
 ./serve.sh
 
-# Check for broken links
-# Verify formatting
-# Test on multiple screen sizes
+# Production build (required)
+hugo --gc --minify
+
+# Super Linter — same as CI (may not run on Apple Silicon; check the PR workflow)
+make super-linter
+
+# Optional: broken-link scan (nightly in CI)
+make test
 ```
 
+On **M-series Macs**, `make super-linter` can fail because the container image has no ARM build. Confirm the **Super linter** check passes on your pull request in GitHub Actions instead.
+
+Also verify formatting in the browser and test at multiple screen sizes.
+
 ## Submitting Changes
 
 1. **Create a branch**: `git checkout -b fix/improve-docs`

content/guides/_index.md

@@ -7,7 +7,7 @@ Comprehensive guides for building production-ready AI applications.
 
 ## Workshops
 
-- [Zero to Production: Agentic AI Workshop](/guides/agentic-ai-workshop/) - Build a complete AI application using all three templates
+- [Zero to Production: Agentic AI Workshop](/guides/agentic-ai-workshop/) — Run the full MCP → Deep Agent → UI stack locally (updated August 2026)
 
 ## Quick Starts
 
@@ -17,13 +17,20 @@ Get started quickly with individual templates:
 - [Agent Template Quick Start](/templates/agent/quick-start/)
 - [UI Template Quick Start](/templates/ui/quick-start/)
 
+## Reference
+
+Stack-wide architecture, configuration, and migration:
+
+- [Stack Architecture](/reference/architecture/)
+- [Config-as-code](/reference/config-as-code/)
+- [Enterprise Features](/reference/enterprise-features/)
+- [Migration from pre-Deep Agent](/reference/migration-deep-agent/)
+
 ## Planned Guides
 
 We're working on additional guides including:
 
-- End-to-end tutorials
-- Architecture patterns
-- Integration guides
+- Integration patterns beyond the workshop
 - Best practices across templates
 
 For questions, visit [GitHub Discussions](https://github.com/redhat-data-and-ai/website/discussions).