docs: update getting started for poly start (#147)

## Summary
- Reworks the getting started flow to lead with `poly start` as the
primary onboarding path — signup, API key generation, and project
creation in one command
- Manual API key setup via env vars kept as an alternative for existing
users
- Documents the credential file (`~/.poly/credentials.json`) and the
resolution order (credential file → region env var → `POLY_ADK_KEY`)
- Addresses Naorin's ask to update docs ahead of `poly start` going to
prod

### Pages changed
- **get-started.md** — Steps 1–5 (manual signup, find IDs, generate key)
collapsed into a single `poly start` step
- **prerequisites.md** — Option A (`poly start`) / Option B (manual) for
API key setup, credential resolution order documented
- **installation.md** — "Set your API key" points at `poly start`,
credential file fallback noted

## Test plan
- [x] `mkdocs serve` — all three pages render correctly
- [ ] Internal links between pages resolve (prerequisites ↔ installation
↔ get-started)
- [ ] Screenshot/image references still work (no images were changed)
- [ ] Should be merged after or alongside Ruari's `poly start` PRs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: AaronForinton

docs/docs/get-started/get-started.md

@@ -1,134 +1,199 @@
 ---
 title: Getting started with PolyAI
-description: Learn how to build your first PolyAI agent in minutes, then connect it to the ADK for local development.
+description: Go from zero to a working local agent project in minutes using the ADK CLI.
 ---
 
-# Not sure where to start?
+# Getting started
 
-If you do not yet have an agent in Agent Studio, or you want a working starting point before setting up the ADK, you can build a personalized agent from your company website in a few minutes — no configuration required. The agent lives in Agent Studio as a normal project, so you can pull it straight into the ADK and continue development locally as soon as it is ready.
+The fastest way to get up and running is entirely from the command line. Two steps — install the ADK, then run `poly start` — take you from an empty machine to a local project you can edit, push, and deploy.
 
 ---
 
-## New to PolyAI — build your first agent
+## Step 1 — Install the ADK
 
-If you do not yet have access to Agent Studio or an existing agent, start here.
+You need **uv** to manage the Python environment. If you already have it, skip the first line.
 
-### Step 1 — Get access to Agent Studio
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # or: brew install uv
+```
 
-Go to [studio.poly.ai](https://studio.poly.ai) and sign up. You can sign up with your email or login with SSO.
+Then create a virtual environment and install the ADK:
 
-![Agent Studio sign up for the first time](../assets/agent-studio-login.png)
+```bash
+uv venv --python=3.14 --seed
+source .venv/bin/activate
+pip install polyai-adk
+```
 
-### Step 2 — Create an agent from your website
+Confirm it worked:
 
-![Quick setup button Agent Studio](../assets/quick-agent-setup.png)
+```bash
+poly --help
+```
 
-Once you are inside Agent Studio:
+!!! info "Suppress SyntaxWarnings from platform-generated code"
 
-1. Click the **+ Agent** button in the top-right corner.
-2. Select **Quick Agent Setup** from the dropdown.
-3. Enter your company website URL and click **Create agent**.
+    Platform-generated code uses regex patterns (such as `\d`) that trigger `SyntaxWarning` in Python 3.14's stricter string handling. This produces 40+ warning lines on every `poly` command and obscures normal output.
 
-Agent Studio crawls your website and generates a working agent configuration — usually within a few minutes. Before it builds, you can choose the voice your agent will use.
+    To suppress them, set this before running any `poly` command:
 
-![Agent building step — showing Analyzing website, Retrieving data, and voice selection](../assets/agent-build.png)
+    ```bash
+    export PYTHONWARNINGS=ignore
+    ```
 
-!!! tip "What gets generated"
+!!! tip "Optional — install the VS Code / Cursor extension"
+
+    If you plan to work in **VS Code** or **Cursor**, you can also install the [PolyAI ADK extension](../reference/tooling.md#polyai-adk-extension-for-vs-code-and-cursor) for resource-aware editing on top of the CLI. The extension is additive — the `poly` command remains the source of truth for every workflow.
+
+## Step 2 — Sign in and set up your API key
+
+```bash
+poly start
+```
+
+`poly start` handles everything you need to authenticate:
+
+1. **Sign up or sign in** — opens a browser window for authentication. This can be on any device, not just the machine running the CLI.
+2. **API key** — generates a key and saves it to `~/.poly/credentials.json`. Future `poly` commands pick it up automatically — no environment variables to manage.
+3. **Create a project** — optionally creates a new Agent Studio project and pulls it down locally so you can start editing immediately.
 
-    Agent Studio populates **topics** (knowledge base entries) and basic **agent settings** (personality, role, rules) from your website's public content. This gives you an agent that knows about your company and can answer questions — but it does not generate flows, variants, entities, handoffs, or integrations. Those are for you to build locally with the ADK. Everything that is generated is standard ADK-compatible configuration and fully editable once pulled down.
+!!! tip "Already have an account?"
+    If `poly start` detects an existing API key (from the credential file or an environment variable), it skips authentication and goes straight to project creation.
 
-### Step 3 — Test your agent in Agent Studio
+??? note "Manual API key setup"
 
-![Completed lite builder](../assets/setup-agent.png)
+    If you prefer to manage API keys through the Agent Studio UI:
 
-Once the agent is ready, test it inside Agent Studio to confirm it's filled in with information as expected. This gives you a working baseline before you move to local development.
+    1. Log in to [Agent Studio](https://studio.poly.ai) and open your workspace.
+    2. In the **API Keys** tab (next to the **Users** tab), click **+ API key**.
 
-### Step 4 — Find your account and project IDs
+    ![Generating an API key in Agent Studio — API Keys tab with the + API key button highlighted](../assets/api-key-data-access.png)
 
-To pull the agent into the ADK, you need two identifiers from Agent Studio. You can find them in the URL when your project is open:
+    Then export the key:
 
-~~~
-https://studio.poly.ai/<account_id>/<project_id>/...
-~~~
+    ```bash
+    export POLY_ADK_KEY=<your-api-key>
+    ```
 
-Copy both values — you will need them in the next step.
+    To make it permanent, add the export line to your shell profile (`~/.zshrc` or `~/.bashrc`).
 
-### Step 5 — Generate an API key
+!!! info "How the ADK resolves API keys"
+    The ADK checks for credentials in the following order:
 
-![Go back to key](../assets/go-back-to-key.png)
+    1. **Credential file** — `~/.poly/credentials.json` (written by `poly start`)
+    2. **Region-specific env var** — e.g. `POLY_ADK_KEY_US`
+    3. **General env var** — `POLY_ADK_KEY`
 
-The ADK uses an API key to authenticate with Agent Studio. Click **Back to agents** to return to your **workspace**, then follow the steps in [Prerequisites — Generate API key](./prerequisites.md#generate-api-key) to create and export your key.
+    The first match wins. If nothing is found, the CLI raises an error.
 
-### Step 6 — Pull the agent into the ADK
+    If you work across multiple regions, you can set region-scoped variables. See [per-region API keys](#per-region-api-keys) below.
 
-Once the [ADK is installed](./installation.md), link your local folder to the project:
+## Step 3 — Start building
+
+If `poly start` created a project for you, `cd` into the project directory. Otherwise, connect to an existing project:
 
 ```bash
 poly init
 ```
 
-[`poly init`](../reference/cli.md#poly-init) walks you through interactive dropdowns to pick a region, account, and project. It creates a subdirectory and pulls the configuration automatically. Change into the project directory before running any further commands. See [First commands](./first-commands.md) for the full walkthrough.
-
-You now have a fully editable local copy of your agent.
+[`poly init`](../reference/cli.md#poly-init) walks you through interactive dropdowns to pick a region, account, and project, then pulls the configuration locally.
 
-### Step 7 — Continue with the ADK
+From inside your project directory, the core workflow is:
 
-From here, the standard ADK workflow applies. You can:
+```bash
+poly status              # see what's changed
+poly diff                # inspect changes in detail
+poly branch create dev   # work on a branch
+poly push                # push changes to Agent Studio
+poly chat                # talk to your agent
+```
 
-- edit resources locally with any tooling
-- create branches with `poly branch create`
-- track changes with `poly status` and `poly diff`
-- validate and push changes back with `poly push`
+Edit flows, functions, topics, and other resources in your editor of choice — they're just YAML and Python files. Push when you're ready to test in Agent Studio.
 
 <div class="grid cards" markdown>
 
 -   **Build an agent with the ADK**
 
     ---
 
-    Follow the full step-by-step workflow for local development.
+    Follow the full step-by-step tutorial for local development.
     [Open the tutorial](../tutorials/build-an-agent.md)
 
+-   **First commands**
+
+    ---
+
+    Explore the full set of CLI commands available to you.
+    [Open first commands](./first-commands.md)
+
 </div>
 
 ---
 
-## Already have an agent in Agent Studio?
+## Seed an agent from your website
 
-If you already have an agent in Agent Studio — built in the browser editor, by a PolyAI team, or using any other method — you can connect it directly to the ADK. The ADK connects to any existing Agent Studio project using the same `poly init` + `poly pull` workflow described above.
+If you're starting from scratch and want a working baseline, you can generate an agent from your company website inside Agent Studio. This gives you topics and agent settings pre-populated from your site's public content — a useful starting point before building locally.
 
-1. Complete [Prerequisites](./prerequisites.md) to generate your API key and install local tools.
-2. Follow [Installation](./installation.md) to install the ADK.
-3. Run:
+1. Open [Agent Studio](https://studio.poly.ai) and sign in (your `poly start` account works here).
+2. Click **+ Agent** → **Quick Agent Setup**.
+3. Enter your website URL and click **Create agent**.
 
-    ~~~bash
-    poly init
-    ~~~
+![Quick setup button Agent Studio](../assets/quick-agent-setup.png)
+
+Agent Studio crawls your site and generates a configuration — usually within a few minutes. Once it's ready, pull it into your local project:
+
+```bash
+poly pull
+```
 
-    `poly init` shows interactive dropdowns to pick your project. See [First commands](./first-commands.md) for details.
+!!! tip "What gets generated"
 
-Your local folder will mirror the project in Agent Studio and you can begin editing immediately.
+    Agent Studio populates **topics** (knowledge base entries) and basic **agent settings** (personality, role, rules) from your website's public content. It does not generate flows, variants, entities, handoffs, or integrations — those are for you to build locally with the ADK.
 
 ---
 
-## Next step
+## Already have an agent in Agent Studio?
 
-Install the ADK and confirm your local tools are in place before running your first commands.
+If you have an existing project — built in the browser, by a PolyAI team, or by any other method — connect it to the ADK in two commands:
 
-<div class="grid cards" markdown>
+```bash
+poly start    # sign in and save your API key (skip if already done)
+poly init     # interactive prompts to pick region, account, and project
+```
 
--   **Installation**
+`poly init` creates a local directory and pulls the full project configuration. From there the standard `poly status` / `poly push` / `poly pull` workflow applies.
 
-    ---
+---
+
+## Per-region API keys
+
+If you work across multiple regions, you can set region-scoped environment variables. The ADK checks the credential file first, then region-scoped env vars, then `POLY_ADK_KEY`.
+
+| Region | Environment variable |
+|---|---|
+| `us-1` | `POLY_ADK_KEY_US` |
+| `euw-1` | `POLY_ADK_KEY_EUW` |
+| `uk-1` | `POLY_ADK_KEY_UK` |
+| `studio` | `POLY_ADK_KEY_STUDIO` |
+| `staging` | `POLY_ADK_KEY_STAGING` |
+| `dev` | `POLY_ADK_KEY_DEV` |
+
+```bash
+export POLY_ADK_KEY_US=<your-us-api-key>
+export POLY_ADK_KEY=<your-fallback-api-key>   # used for any other region
+```
+
+---
 
-    Install the ADK and set up your local environment.
-    [Open installation](./installation.md)
+## Next step
+
+<div class="grid cards" markdown>
 
 -   **What is the ADK?**
 
     ---
 
-    Understand what the ADK does and how it fits into the Agent Studio workflow.
+    Understand what the ADK does and how it fits into Agent Studio.
     [Read the overview](./what-is-the-adk.md)
 
 </div>