docs: improve clarity, active language, and add Google Analytics

docs/docs/concepts/anti-patterns.md

@@ -3,7 +3,7 @@ title: Common anti-patterns
 description: Avoid common mistakes when building flows, writing prompts, and handling control flow in the PolyAI ADK.
 ---
 
-This page collects common implementation mistakes that make agents harder to reason about, harder to maintain, or more likely to behave incorrectly at runtime.
+This page collects common implementation mistakes that make agents harder to predict, harder to maintain, or more likely to behave incorrectly at runtime.
 
 The general rule is simple: keep prompts focused on conversation, keep Python focused on deterministic logic, and make control flow explicit.
 
@@ -71,9 +71,9 @@ Implement the check in Python and transition to the correct step or flow explici
 
 When branching logic is buried in prompts:
 
-- behavior becomes harder to test
+- behavior becomes harder to test and verify
 - routing becomes harder to debug
-- the agent becomes more dependent on model interpretation for deterministic behavior
+- deterministic behavior becomes dependent on how the model interprets the instruction
 
 <div class="grid cards" markdown>
 
@@ -172,9 +172,8 @@ If the user is expected to answer, put the full question in the utterance and le
 
 ## Design principle
 
-When in doubt:
-
 - make control flow explicit
 - keep prompts conversational
 - keep code deterministic
-- prefer simple, testable paths over clever prompt tricks
+- prefer simple, testable paths over clever prompt tricks
+

docs/docs/concepts/multi-user-and-guardrails.md

@@ -69,9 +69,7 @@ You can also use:
 
 ## Validation as a guardrail
 
-Before pushing, the ADK can validate the project locally.
-
-This is one of the main guardrails in the workflow. It helps catch issues early, before they are pushed into Agent Studio.
+Run `poly validate` before pushing to catch issues locally, before they reach Agent Studio.
 
 Examples of what validation protects against include:
 
@@ -82,7 +80,7 @@ Examples of what validation protects against include:
 
 !!! info "Validate before pushing"
 
-    In collaborative workflows, `poly validate` should be treated as a normal part of the editing cycle, not as an optional afterthought.
+    In collaborative workflows, treat `poly validate` as a standard step in the editing cycle, not an optional one.
 
 ## Pulling and merge behavior
 
@@ -94,25 +92,23 @@ poly pull
 
 If the pulled changes conflict with your own local edits, the ADK will merge them and surface merge markers where conflicts occur.
 
-That means the local workflow is not isolated from Agent Studio UI work — both sides can affect branch state, and developers should be aware of that.
+The local workflow is not isolated from Agent Studio UI work - both sides affect branch state. Keep that in mind when collaborating.
 
 ## Review workflow
 
-When changes are ready for review, the ADK can help generate a review artifact using:
+When changes are ready for review, generate a review artifact:
 
 ~~~bash
 poly review
 ~~~
 
-This can be used to compare:
+Use this to compare:
 
 - local changes against the remote project
 - one branch against another
 - a feature branch against `main` or `sandbox`
 
-A GitHub environment token is required for this step.
-
-The review flow is useful when you want to share changes without asking a reviewer to inspect the raw local filesystem.
+A GitHub environment token is required. The output lets reviewers inspect changes without access to your local filesystem.
 
 ## Guardrails inherited from Agent Studio
 

docs/docs/concepts/working-locally.md

@@ -3,15 +3,9 @@ title: Working locally
 description: Understand how the PolyAI ADK maps Agent Studio projects onto a local development workflow.
 ---
 
-The **PolyAI ADK** is a CLI tool and Python package for managing **PolyAI Agent Studio** projects locally.
+With the ADK, you work on Agent Studio projects from your local machine instead of exclusively through the browser.
 
-It provides a Git-like workflow for synchronizing project configuration between your local filesystem and the Agent Studio platform, so agent development can fit into normal engineering build, review, and collaboration cycles.
-
-## What “working locally” means
-
-With the ADK, you are not building an agent only inside the browser.
-
-Instead, you work with a project on your machine, where you can:
+Your local filesystem becomes your primary editing surface. You can:
 
 - edit agent resources directly
 - review changes with Git-style workflows
@@ -57,7 +51,7 @@ A typical project structure looks like this:
 
 ~~~text
 <account>/<project>/
-├── _gen/                               # Generated stubs — do not edit
+├── _gen/                               # Generated stubs - do not edit
 ├── agent_settings/                     # Agent identity and behavior
 │   ├── personality.yaml
 │   ├── role.yaml
@@ -74,7 +68,7 @@ A typical project structure looks like this:
 │   └── response_control/
 ├── chat/                               # Chat channel settings
 │   └── configuration.yaml
-├── flows/                              # Optional — flow definitions
+├── flows/                              # Optional - flow definitions
 ├── functions/                          # Global functions
 ├── topics/                             # Knowledge base topics
 └── project.yaml                        # Project metadata
@@ -135,21 +129,11 @@ These placeholders are used in prompts, rules, topic actions, and related text f
 | `{{ho:handoff_name}}` | Handoff destination | Rules |
 | `{{vrbl:variable_name}}` | State variable | Prompts, topic actions, SMS templates |
 
-These references make the local project composable: settings, prompts, and behaviors can refer to resources by name rather than hard-coding values.
-
-## Why local development matters
-
-Working locally makes the ADK especially useful for teams that want to:
-
-- review changes before deployment
-- reuse patterns across projects
-- work with large or complex resource trees
-- generate or modify resources using coding agents
-- fit agent development into existing engineering processes
+These references let settings, prompts, and behaviors point to resources by name rather than repeating hard-coded values.
 
 !!! tip "A Git-like workflow for Agent Studio"
 
-    The ADK is easiest to understand if you think of it as a synchronization layer between your local project files and the Agent Studio platform.
+    Think of the ADK as a synchronization layer between your local files and the Agent Studio platform.
 
 ## Related pages
 

docs/docs/development/docs.md

@@ -1,11 +1,11 @@
 ---
 title: Build an agent with the ADK
-description: Go from a blank Agent Studio project to a production-ready voice agent using the PolyAI ADK and an AI coding agent.
+description: Go from a blank Agent Studio project to a production-ready voice agent using the PolyAI ADK and a coding tool such as Claude Code.
 ---
 
 # Build an agent with the ADK
 
-This guide walks through how to go from a blank slate to a production-ready voice agent with a real backend using **PolyAI ADK**, **Agent Studio**, and a coding agent such as **Claude Code**.
+This guide walks through how to go from a blank slate to a production-ready voice agent with a real backend using **PolyAI ADK**, **Agent Studio**, and a coding tool such as **Claude Code**.
 
 The intended workflow is simple:
 
@@ -17,23 +17,23 @@ The intended workflow is simple:
 
     Gather the project requirements, business rules, API information, and reference material.
 
--   **The coding agent builds**
+-   **The coding tool builds**
 
     ---
 
-    Using the ADK, the coding agent generates the files needed for the agent.
+    Using the ADK, the coding tool generates the project files.
 
 -   **Agent Studio hosts and deploys**
 
     ---
 
-    The generated work is pushed back into Agent Studio, where it can be reviewed, merged, and deployed.
+    The generated work is pushed into Agent Studio, where it can be reviewed, merged, and deployed.
 
 </div>
 
 !!! info "No manual flow-building required"
 
-    This workflow is designed so that the coding agent does the heavy lifting of building the agent, while Agent Studio remains the place where the finished work is reviewed, tested, and deployed.
+    In this workflow, the coding tool generates the project files. Agent Studio is where the output is reviewed, tested, and deployed.
 
 ## Architecture at a glance
 
@@ -43,11 +43,11 @@ The intended workflow is simple:
 | **Claude Code + ADK** | Generate project files and push changes |
 | **Agent Studio** | Host, preview, review, and deploy the agent |
 
-## Step 1 — Gather requirements
+## Step 1 - Gather requirements
 
-Collect the project context from your team’s communication channels before you begin.
+Collect the project context from your team's communication channels before you begin.
 
-This should include anything the coding agent will need to produce a working agent, such as:
+Include anything needed to produce a working agent:
 
 - API endpoint URLs
 - business rules
@@ -56,13 +56,13 @@ This should include anything the coding agent will need to produce a working age
 - reference material
 - links to relevant documentation
 
-The more complete and structured the input is, the better the coding agent’s output will be.
+The more complete and structured your input, the less correction the output requires.
 
 !!! tip "Front-load the context"
 
-    This workflow works best when you gather the requirements up front rather than feeding them in piecemeal later.
+    Gather everything up front. Providing context piecemeal produces piecemeal output.
 
-## Step 2 — Create a new project in Agent Studio
+## Step 2 - Create a new project in Agent Studio
 
 Open **Agent Studio** and create a brand-new project.
 
@@ -72,50 +72,61 @@ The project starts empty:
 - no flows
 - no configuration
 
-That blank starting point is intentional. The coding agent will populate the project in later steps.
+That blank starting point is intentional. The coding tool populates the project in later steps.
 
 !!! note "Think of Agent Studio as the deployment target"
 
-    Agent Studio is where the project lives, but the coding agent does most of the actual building work.
+    Agent Studio is where the project lives, but the coding tool generates the actual content.
 
-## Step 3 — Launch the coding agent via the CLI
+## Step 3 - Start the coding tool via the CLI
 
-Open your command line interface and launch your coding agent.
+Open your terminal and start your coding tool.
 
 At this stage:
 
 - the ADK must already be installed
-- the new Agent Studio project should already exist
-- the coding agent should be linked to the project using the ADK
+- the new Agent Studio project must already exist
+- the coding tool should initialize and link the project using the ADK
 
-The ADK acts as the bridge between your local development environment and Agent Studio in the cloud. It allows the coding agent to read from and write back to the project.
+~~~bash
+poly init --region <region> --account_id <account_id> --project_id <project_id>
+poly pull
+~~~
 
-## Step 4 — Feed context to the coding agent
+The ADK acts as the bridge between your local environment and Agent Studio. It lets the coding tool read from and write back to the project.
 
-Now provide the coding agent with the information you gathered earlier.
+## Step 4 - Give the coding tool its context
 
-This is the core input step. Include:
+Provide the coding tool with the information you gathered earlier.
+
+Include:
 
 - the project-specific requirements
-- the URL to the business’s public API documentation
+- the URL to the business's public API documentation
 - any relevant internal project context
 - best practices or patterns from previous projects
 
-Reusing proven patterns from earlier projects can improve both speed and output quality.
+Use the docs command to generate a reference file the coding tool can read:
+
+~~~bash
+poly docs --all
+~~~
 
-## Step 5 — Let the agent build
+Including patterns from earlier projects reduces correction time and improves consistency.
 
-Once the context has been provided, let the coding agent generate the project files.
+## Step 5 - Generate the project files
 
-The coding agent can produce the assets needed for the agent, including:
+Once the context is in place, the coding tool generates the project files.
+
+This produces the assets the agent needs, including:
 
 <div class="grid cards" markdown>
 
 -   **Conversation flows**
 
     ---
 
-    Dialogue logic and routing for the agent.
+    Dialogue logic and routing.
 
 -   **Callable functions**
 
@@ -127,7 +138,7 @@ The coding agent can produce the assets needed for the agent, including:
 
     ---
 
-    Information the agent can reference when answering questions.
+    Information the agent can retrieve when answering questions.
 
 -   **API integrations**
 
@@ -137,13 +148,13 @@ The coding agent can produce the assets needed for the agent, including:
 
 </div>
 
-The generated assets are structured for Agent Studio and prepared to be pushed back to the platform.
+The generated files follow ADK structure and are ready to push to Agent Studio.
 
-## Step 6 — Push back to Agent Studio
+## Step 6 - Push to Agent Studio
 
-Once the coding agent has generated the project files, it uses the ADK to push them back into Agent Studio.
+Once the files are generated, use the ADK to push them to Agent Studio.
 
-A new branch is created in the project so the generated work can be reviewed safely before anything goes live.
+A new branch is created so the generated work can be reviewed safely before anything goes live.
 
 When you switch to that branch in Agent Studio, you should see the generated changes, such as:
 
@@ -156,11 +167,11 @@ When you switch to that branch in Agent Studio, you should see the generated cha
 
     The branch-based workflow makes it possible to inspect what was generated before merging it into the main project.
 
-## Step 7 — Review, merge, and deploy
+## Step 7 - Review, merge, and deploy
 
 Review the generated work inside Agent Studio.
 
-Check that the key parts of the agent look correct:
+Check the key parts of the agent:
 
 - flows
 - functions
@@ -174,23 +185,13 @@ Once everything looks right:
 
 At that point, the agent is live.
 
-## Summary
-
-| Metric | Value |
-|---|---|
-| **Steps** | 7 |
-| **Total time** | ~30 minutes |
-| **Manual flows built** | 0 |
-
-The overall loop is straightforward:
+## The overall loop
 
 1. provide context
-2. let the coding agent generate the project assets
-3. use the ADK to push them into Agent Studio
+2. generate the project files using the coding tool
+3. push to Agent Studio with the ADK
 4. review, merge, and deploy
 
-By reusing patterns from previous projects, the coding agent can produce production-grade output much faster than a fully manual workflow.
-
 ## Next steps
 
 <div class="grid cards" markdown>