Merge branch 'main' of https://github.com/githubnext/gh-aw

Author: dsyme

README.md

@@ -2,7 +2,7 @@
 
 Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/).
 
-> [!WARNING]
+> [!CAUTION]
 > This extension is a research demonstrator. It is in early development and may change significantly. Using agentic workflows in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
 
 ## 🚀 Quick Start

docs/concepts.md

@@ -1,4 +1,4 @@
-# 📖 Introduction to Agentic Workflows
+# 📖 Introduction to GitHub Agentic Workflows
 
 Now that you've [got your first workflow running](quick-start.md), let's dive deeper into the concepts and capabilities of GitHub Agentic Workflows.
 
@@ -17,7 +17,9 @@ Traditional GitHub Actions follow pre-programmed steps. Agentic workflows use AI
 - **Use tools** — Interact with GitHub APIs, external services, and repository files
 - **Generate content** — Create meaningful comments, documentation, and code changes
 - **Learn and adapt** — Adjust behavior based on past action, feedback and outcomes
-- **Productive ambiguity** — Interpret natural language instructions flexibly and productively
+- **Use ambiguity productively** — Interpret natural language instructions flexibly and productively
+
+One crucial difference from regular agentic prompting is that GitHub Agentic Workflows can contain **both** traditional GitHub Actions steps and agentic natural language instructions. This allows the best of both worlds: traditional steps for deterministic actions, and agentic steps for flexible, context-aware AI-driven actions.
 
 ### The anatomy of an agentic workflow
 
@@ -38,7 +40,7 @@ steps: ...
 Analyze this issue and provide helpful triage comments...
 ```
 
-One crucial difference from traditional agentic prompting is that GitHub Agentic Workflows can contain **both** traditional GitHub Actions steps and agentic natural language instructions. This allows the best of both worlds: traditional steps for deterministic actions, and agentic steps for flexible, context-aware AI-driven actions.
+Another crucial difference from traditional agentic prompting is that GitHub Agentic Workflows can contain triggers, permissions and other declarative elements. This works towards more reliable and more secure agentic programming, setting the AI up to contribute to success, in a partially sandboxed way, at the right time in your team's work.
 
 See [Workflow Structure](workflow-structure.md) and [Frontmatter Options](frontmatter.md) for details of file layout and configuration options.
 
@@ -139,4 +141,4 @@ Ready to build more sophisticated workflows? Explore:
 - **[Security Notes](security-notes.md)** — Important security considerations
 - **[VS Code Integration](vscode.md)** — Enhanced authoring experience
 
-The power of agentic workflows lies in their ability to understand context, make intelligent decisions, and take meaningful actions — all while maintaining the reliability you expect from GitHub Actions.
+The power of agentic workflows lies in their ability to understand context, make intelligent decisions, and take meaningful actions — all while maintaining the reliability you expect from GitHub Actions.