tweak index

Author: dsyme

docs/src/content/docs/index.mdx

@@ -25,7 +25,7 @@ Imagine a world where improvements to your repositories are automatically delive
 
 GitHub Agentic Workflows deliver this: repository automation, running the coding agents you know and love, in GitHub Actions, with strong guardrails and security-first design principles.
 
-Use GitHub Copilot, Claude by Anthropic or OpenAI Codex for event-triggered, recurring and scheduled jobs to improve, document and analyze your repository. GitHub Agentic Workflows are designed to [augment](https://github.github.io/gh-aw/reference/faq/#i-like-deterministic-cicd-isnt-this-non-deterministic) your existing, deterministic CI/CD with [Continuous AI](https://githubnext.com/projects/continuous-ai) capabilities
+Use GitHub Copilot, Claude by Anthropic or OpenAI Codex for event-triggered, recurring and scheduled jobs to improve, document and analyze your repository. GitHub Agentic Workflows are designed to [augment](https://github.github.io/gh-aw/reference/faq/#determinism) your existing, deterministic CI/CD with [Continuous AI](https://githubnext.com/projects/continuous-ai) capabilities
 
 GitHub Agentic Workflows has been developed by GitHub Next and Microsoft Research with guardrails in mind. Agentic workflows run with minimal permissions by default, with explicit allowlisting for write operations and sandboxed execution to help keep your repository safe.
 

docs/src/content/docs/reference/faq.md

@@ -8,6 +8,18 @@ sidebar:
 > [!NOTE]
 > GitHub Agentic Workflows is in early development and may change significantly. Using automated agentic workflows 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.
 
+## Determinism
+
+### I like deterministic CI/CD. Isn't this non-deterministic?
+
+We fully embrace the need for deterministic CI/CD, especially in build, release, and test pipelines. Agentic workflows are **100% additive** to your existing CI/CD - they don't replace or modify your deterministic pipelines.
+
+Think of it this way: your build, test, and release workflows should remain fully deterministic and reproducible. Agentic workflows complement these by handling tasks that are inherently non-deterministic anyway - like triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review.
+
+The key insight is that many valuable automation tasks don't require determinism. When a coding agent reviews an issue and suggests a label, or drafts release notes from commits, the exact wording doesn't need to be reproducible - it needs to be helpful. Agentic workflows excel at these judgment-based tasks while your critical CI/CD pipelines remain unchanged.
+
+Your first call should be reliable, deterministic CI/CD. If you use agentic workflows, you should use them for tasks that benefit from a coding agent's flexibility, not for core build and release processes that require strict reproducibility.
+
 ## Capabilities
 
 ### Can I edit workflows directly on GitHub.com without recompiling?
@@ -26,16 +38,6 @@ Agentic workflows use AI to interpret natural language instructions in markdown
 
 While you could install and run a coding agent directly in a standard GitHub Actions workflow, agentic workflows provide a structured framework with simpler markdown format, built-in security controls, pre-defined tools for GitHub operations, and easy switching between AI engines.
 
-### I like deterministic CI/CD. Isn't this non-deterministic?
-
-We fully embrace the need for deterministic CI/CD, especially in build, release, and test pipelines. Agentic workflows are **100% additive** to your existing CI/CD - they don't replace or modify your deterministic pipelines.
-
-Think of it this way: your build, test, and release workflows should remain fully deterministic and reproducible. Agentic workflows complement these by handling tasks that are inherently non-deterministic anyway - like triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review.
-
-The key insight is that many valuable automation tasks don't require determinism. When a coding agent reviews an issue and suggests a label, or drafts release notes from commits, the exact wording doesn't need to be reproducible - it needs to be helpful. Agentic workflows excel at these judgment-based tasks while your critical CI/CD pipelines remain unchanged.
-
-Your first call should be reliable, deterministic CI/CD. If you use agentic workflows, you should use them for tasks that benefit from a coding agent's flexibility, not for core build and release processes that require strict reproducibility.
-
 ### Can agentic workflows write code and create pull requests?
 
 Yes! Agentic workflows can create pull requests using the `create-pull-request` safe output. This allows the workflow to propose code changes, documentation updates, or other modifications as pull requests for human review and merging.