ancongui · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,16 @@ SPDX-License-Identifier: Apache-2.0
 
 ## Unreleased
 
+- Studio has one place to set up AI: **Settings › AI models**. It shows provider cards, your AI connections, a
+  readiness checklist with **Publish**, **Authorize** and **Test connection**, and the Weave AI card. The AI
+  connection side sheet is the only AI connection form; it also opens from Build › Connections, an AI task and
+  Home's **Connect a model**. It offers plain HTTP only for endpoints a platform operator approved, asks for a secret
+  handle (never a key), lists the approved models the provider serves, and tests a model through the AI gateway with
+  tool support. The old AI setup wizard and the Weave AI settings in the Ask Weave AI panel are gone.
+- Studio waits up to 140 seconds for an AI connection test, so a local model loading for the first time no longer
+  fails the test early; canceling the test in Studio stops it on the platform.
+- `weave platform up --username` grants the new account the local owner roles, and
+  `weave platform user grant --username NAME --role ROLE` adds roles to an account the local platform created.
 - Run state, history, tasks, deadlines, and incidents name each run of a step by
   its instance key, which equals the step ID outside loops, so existing workflows
   keep byte-identical transitions and history. Deadline scans, incident

diff --git a/docs/guides/ai-workers.md b/docs/guides/ai-workers.md
@@ -116,18 +116,21 @@ used, which is separate from changing the grant list. Follow
 for the supported file and environment providers. Saving a handle in Studio does
 not provision its secret or grant access to it.
 
-Studio's **New AI connection** uses the standard OpenAI or Anthropic endpoint
-automatically. **Advanced: custom endpoint** is available for an approved proxy
-or compatible service. Azure requires the resource endpoint and API version
-from its administrator. Review shows the exact saved endpoint; hostname case
-and the default HTTPS port are normalized, while the base path and trailing
-slash are preserved. The worker or Weave AI gateway must still allow that exact
-endpoint. Existing endpoint policies are not changed by saving a connection.
-
-**Saved · Not tested** means that the connection configuration passed validation.
-It does not prove provider access, model availability, or worker/gateway readiness.
-Workflow AI profiles and Weave AI settings remain separate and select their own model
-or Azure deployment using the approved connection.
+AI connections are created and tested in Studio's **Settings › AI models**. The
+same AI connection side sheet opens from **Build › Connections › New AI
+connection** and from an AI task's connection step. Choose a provider and one of
+the platform's approved endpoints; a custom address must use `https://`, and plain
+`http://` works only for an address a platform operator approved. Cloud providers
+take a **Secret handle**, never the key itself, and the sheet shows the
+`weave platform secret set --handle HANDLE` command that stores the key. Azure
+also needs its **API version**. The worker or Weave AI gateway must still allow
+the saved endpoint; saving a connection does not change endpoint policy.
+
+A saved connection has passed validation only. **Test connection** in the side
+sheet sends one request through the AI gateway to the model you choose and says
+whether it answered and can call tools; the model list shows the platform's
+approved models that the provider serves. Workflow AI profiles and Weave AI
+choose their own model or Azure deployment on the approved connection.
 
 **Hosting Weave in Azure does not select an AI provider.** The Azure operator
 still deploys the worker, supplies its configuration and token file, permits its
@@ -256,31 +259,26 @@ after an ambiguous network failure.
 
 ## Configure the provider connection
 
-In Studio, open **Settings → AI models → New AI connection**. The same action is
-available from **Connections** and the AI task inspector. You need
-`connection.manage` in the environment. If the provider Connector is not yet
-published, the form explains the prerequisite; an author cannot bypass it.
-
-Studio alpha11 guides this setup through three steps. Alpha10 presents the
-same fields in a single form.
-
-1. **Provider:** enter a **Connection name** that identifies the intended account
-   or purpose, choose **Provider**, and select **Continue**. The model or Azure
-   deployment name belongs in the workflow profile.
-2. **Access:** copy the exact operator-approved **Provider endpoint**. For Azure,
-   also enter the explicit **Azure API version**. Enter the **API key secret
-   handle** supplied by the operator, never the raw API key, then select
-   **Review connection**. The Azure endpoint hint has no trailing slash; copy
-   the approved endpoint exactly rather than inventing a different spelling.
-3. **Review:** check the name, provider, endpoint, API version when applicable,
-   and secret handle. **Back** preserves these details so you can correct them.
-   Select **Create AI connection** only when they are ready. Earlier steps do
-   not create a connection or send a model request.
-4. Record the created connection and revision. Studio restricts allowed
-   destinations to the endpoint's HTTPS origin, and the operator's worker policy
-   must also permit the endpoint. The platform checked configuration, not live
-   provider connectivity. Complete worker release and credential grants before
-   binding it to an executable workflow.
+In Studio, open **Settings › AI models** and choose **Connect** on a provider
+card. The same side sheet opens from **Build › Connections › New AI connection**
+and from the AI task's connection step. Creating a connection needs
+`connection.manage` in the environment; people with only `connection.bind` see
+AI connections read-only.
+
+1. **Provider** and **Endpoint:** pick the provider and one of the approved
+   endpoints the platform lists, or **Custom address…** for an approved proxy or
+   compatible service. For OpenAI and Azure OpenAI choose the **API style**; for
+   Azure also enter the **API version**.
+2. **Connection name:** a name that identifies the account or purpose.
+3. **Secret handle:** for cloud providers, the handle the operator maps to the
+   key, never the key itself. Local endpoints use no credential.
+4. Select **Save connection**. Studio restricts allowed destinations to the
+   endpoint's origin, and the operator's worker policy must also permit it.
+5. In **Test a model**, choose a model and select **Test connection**. The result
+   says whether the model answered and whether it can call tools; **Show details**
+   lists the error code when it did not. Complete the worker release and
+   credential grants (the **Readiness** checklist's **Publish** and **Authorize**)
+   before binding the connection to an executable workflow.
 
 The API also publishes the canonical provider Connector and the AI task Action for
 you: `ai_setup.publish` (`definition.publish` at project scope) publishes the

diff --git a/docs/guides/docker-development.md b/docs/guides/docker-development.md
@@ -64,16 +64,15 @@ longer than later starts. The CLI prints the API address and sign-in instruction
 `platform status` also shows the interactive API docs address. Copy the generated password when it appears:
 it is shown once, and subsequent starts do not change it.
 
-A default development account can author and run workflows, inspect executions,
-and participate in human tasks. To also administer connections and reviewer groups,
-choose these roles when creating the account:
+Without `--role`, `up` gives this first account the local owner roles in the demo
+workspace: `developer`, `deployer`, `operator`, `viewer`, `task_participant`, `tenant_admin`, `lumi_manager`, `execution_manager`, `worker_operator`, `deployment_reader`, `deployment_planner`, `deployment_approver` and `deployment_operator`. That is enough to author, run and operate workflows,
+administer connections, and set up AI models and Weave AI in Studio. To manage
+reviewer groups, add `task_manager` later; `user grant` adds roles to an account
+this platform created and never removes any:
 
 ```sh
-# Development only: create an account that can follow the administration guides.
-# Use this INSTEAD of the first up command, with a new username.
-weave platform up --username localadmin --role tenant_admin --role developer \
-  --role deployer --role operator --role viewer --role task_participant \
-  --role task_manager
+# Development only: add a role to the account `up` created.
+weave platform user grant --username developer --role task_manager
 ```
 
 Your installation lives in `.local/platform`. Its containers and volumes have

diff --git a/docs/guides/local-platform.md b/docs/guides/local-platform.md
@@ -237,9 +237,9 @@ read runs, and work on human tasks:
 | `viewer` | Demo environment | Read runs, deliveries, status, and the catalog |
 | `task_participant` | Demo environment | Read, claim, complete, and release assigned human tasks |
 
-**Choose the roles now: you cannot add them later with this command.** An
-existing username is never changed, and `--role` replaces the defaults, so list
-every role you want. The defaults miss two roles that later guides need:
+**`user` never changes an existing username**, and `--role` replaces the
+defaults. To add roles to an account this platform created, use `user grant`
+(below). The defaults miss two roles that later guides need:
 
 - **Integration connections** need `tenant_admin` (step 8 and
   [Call a REST API without code](../connectors/http-without-code.md)).
@@ -257,9 +257,25 @@ weave platform user --username YOUR_NAME --role tenant_admin --role developer \
 
 Expected: the same output, with `tenant_admin (demo tenant)` first in `Roles:`.
 `weave platform user --help` lists every role you can grant; `platform_admin` and
-`worker` are never offered. **Already created your person with fewer roles?**
-Create a second username with the full set, then sign in as it with
-`weave auth login --switch-account`.
+`worker` are never offered.
+
+**Already created your person with fewer roles?** Add the missing ones with
+`user grant`. Grants are added, never removed, and are scoped like the roles
+`user` gives; sign in again to use them:
+
+```sh
+# Development only: add roles to an account this platform created.
+weave platform user grant --username YOUR_NAME --role tenant_admin --role lumi_manager
+```
+
+`user grant` works for accounts that `weave platform user` or
+`weave platform up --username` created with this version or later, which keep a
+private record of the account. For an older account, assign roles in Studio's
+**Settings › People and access** instead.
+
+The account `weave platform up --username NAME` creates (see the
+[Docker development guide](docker-development.md)) gets the local owner roles
+instead of the defaults: `developer`, `deployer`, `operator`, `viewer`, `task_participant`, `tenant_admin`, `lumi_manager`, `execution_manager`, `worker_operator`, `deployment_reader`, `deployment_planner`, `deployment_approver` and `deployment_operator`.
 
 ## 6. Sign in from the CLI
 

diff --git a/docs/guides/ollama.md b/docs/guides/ollama.md
@@ -97,6 +97,21 @@ On macOS, Docker cannot use the Apple GPU, so `--ollama host` is much faster
 when Ollama runs on your Mac; `weave platform ai status` warns about CPU-only
 inference when Ollama runs in a container on macOS.
 
+## Set up models in Studio
+
+Open **Settings › AI models**. The **Readiness** checklist shows what the platform checked: the Agentic worker, the
+published AI actions, a worker online, an AI connection, its key and authorization, a model that answered a test in
+the last 24 hours, and Weave AI. Each item you can fix has its button: **Publish** publishes the built-in AI actions,
+**Authorize** lets the worker use your credentialed connections, and **Test connection** opens the connection to test.
+
+Choose **Connect** on the Ollama card (**Manage** after `weave platform ai enable`) to open the AI connection side
+sheet. Pick an approved endpoint; plain `http://` addresses work only when a platform operator approved them, and
+local endpoints use no credential. **Save connection**, choose a model (Studio suggests `qwen3:4b` when it is
+installed) and **Test connection**. A first test of a local model can take up to two minutes while the model loads;
+**Cancel** stops it.
+
+Weave AI can't use a connection without a key yet, so on a local platform every item but **Weave AI** turns ready.
+
 ## Choose a model
 
 | Use | Model | Download |

diff --git a/docs/guides/people-and-access.md b/docs/guides/people-and-access.md
@@ -405,6 +405,19 @@ command, `weave auth setup http://127.0.0.1:API_PORT`. The default roles are
 different set instead. An existing username is never reset. Never use this
 command with a shared or production identity provider.
 
+`weave platform up --username NAME` creates its first account with the local
+owner roles instead: `developer`, `deployer`, `operator`, `viewer`, `task_participant`, `tenant_admin`, `lumi_manager`, `execution_manager`, `worker_operator`, `deployment_reader`, `deployment_planner`, `deployment_approver` and `deployment_operator`. To add roles later to an account this platform
+created, use `user grant`; it adds grants, never removes them, and first checks
+that the sign-in still belongs to the recorded person:
+
+```sh
+# Development only: add roles to an account this platform created.
+weave platform user grant --username alice --role tenant_admin --role lumi_manager
+```
+
+Accounts created by earlier versions have no local record, so `user grant`
+refuses them; assign their roles in Studio's **Settings › People and access**.
+
 **To practise platform-administrator commands locally,** act as the local host
 application, which `weave platform setup` bootstrapped as platform
 administrator. `weave platform user` never offers `platform_admin`. From the

diff --git a/docs/guides/studio-step-reference.md b/docs/guides/studio-step-reference.md
@@ -257,7 +257,8 @@ slot without changing the model, select that slot directly in the inspector.
    not contact the model or verify credentials.
 2. **Connection:** choose the **AI connection slot**, or select **Add AI connection
    slot** to include a new slot when you apply. An authorized administrator can
-   also open **New AI connection** to create an environment connection using an
+   also select **New AI connection**, which opens the AI connection side sheet
+   over the editor, to create an environment connection using an
    operator-provisioned secret handle. Activation binds the slot to that
    environment connection; this wizard does not activate the workflow.
 3. **Review:** check the profile, provider, model, slot, and list of affected AI
@@ -275,7 +276,8 @@ read. See [Share context between AI steps](shared-ai-context.md) for a complete
 example and the limits across branches, waits, and retries.
 
 Provider credentials belong to an authorized connection, not the prompt or
-profile. Workflow AI profiles are separate from Studio's Weave AI settings.
+profile. Workflow AI profiles are separate from Weave AI's settings in
+**Settings › AI models**.
 The [AI worker guide](ai-workers.md) covers deployment, supported providers,
 credential binding and execution limits. A configured inspector alone does not
 install the action or start a worker.

diff --git a/docs/guides/studio.md b/docs/guides/studio.md
@@ -457,6 +457,14 @@ proves who you are; your administrator's link and grants on the platform decide
 what you may do. Follow [People and access](people-and-access.md) for that
 onboarding step.
 
+**Settings has a tab for each kind of setup, each at its own address.**
+**Platforms** (`/settings/platforms`) holds your saved platforms; **People and
+access** (`/settings/people`) appears for administrators; **AI models**
+(`/settings/ai`) appears once a platform is connected and holds provider cards,
+your AI connections, the readiness checklist and the Weave AI card (see
+[Set up models in Studio](ollama.md#set-up-models-in-studio)); **Preferences**
+(`/settings/preferences`) holds Studio's own options.
+
 ### Manage saved platforms
 
 **Saved platforms are shared with the `weave` command line on this computer.**

diff --git a/docs/guides/weave-ai.md b/docs/guides/weave-ai.md
@@ -107,9 +107,10 @@ explains the shared operator/administrator handoff.
 
 **New conversation** clears the current exchange. Conversations remain in memory
 and clear when the workspace, identity, or sign-in session changes. They are not
-workflow history. Managers can open **Weave AI settings** to configure the enabled
-flag, pinned connection revision, and model profile separately from workflow AI
-profiles. Studio supplies the fixed reply schema from the canonical contract;
+workflow history. Managers configure Weave AI in the **Weave AI** card of
+**Settings › AI models**; **Set up Weave AI** in the panel opens it. The card sets
+the enabled flag, pinned connection revision, and model separately from workflow
+AI profiles. Studio supplies the fixed reply schema from the canonical contract;
 changing a workflow's AI profile does not configure Weave AI.
 
 ## Explain Operations records
@@ -209,26 +210,27 @@ separate from the administrator's editable environment Weave AI configuration.
 
 ### Save the settings in Studio
 
-1. Open **Settings → AI models → Weave AI settings**, or open **Weave AI settings** from
-   the assistant. These settings belong to the current environment.
-2. The **Model → Connection → Review** wizard keeps changes local until
-   **Save Weave AI settings**. Choose the provider, an explicit model, and maximum
-   response length. For Azure, supply the Azure deployment name. Expand
-   **Advanced model settings** to change generation controls, reasoning, call
-   limits, or time limits. Studio supplies the fixed reply schema and checks
-   incompatible settings before you continue. This local validation does not
-   contact the provider. Select **Continue to connection**.
-3. Choose **Provider connection**. The list displays the connection name and
-   revision and filters for the selected provider. Weave AI pins the exact revision,
-   so a later connection revision does not silently change the assistant.
-4. If needed, select **New AI connection** and follow the
-   [provider connection steps](ai-workers.md#configure-the-provider-connection).
-   Use **Refresh connections** to reload available choices.
-5. Select **Review settings**, check the model and pinned connection, then select
-   **Save Weave AI settings**. **Back** preserves your draft. Use a simple request
-   without attachments to confirm the complete path, as described
+1. Open **Settings › AI models** and find the **Weave AI** card, or select
+   **Set up Weave AI** in the Ask Weave AI panel. These settings belong to the
+   current environment. Configuring them needs the Weave AI manager role, and
+   choosing the connection also needs the tenant administrator role.
+2. Select **Turn on Weave AI**, choose the **Connection**, and choose the
+   **Model**; Studio suggests one of the platform's approved models for that
+   connection. Weave AI pins the connection's exact revision, so a later
+   revision does not silently change the assistant. When the connection has a
+   newer revision, the card says so and saving moves Weave AI to it; a newer
+   revision without a key can't be used, so choose another connection.
+   Connections without a key (such as a local Ollama endpoint) can't be used for
+   Weave AI yet and are listed as unavailable.
+3. Select **Save Weave AI settings**. Saving keeps the stored profile's
+   generation options, reasoning, call and time limits; a new configuration
+   starts from Weave AI's defaults. Studio supplies the fixed reply schema. Use a
+   simple request without attachments to confirm the complete path, as described
    [below](#confirm-setup-without-sharing-sensitive-source).
 
+To create the connection first, use the
+[provider connection steps](ai-workers.md#configure-the-provider-connection).
+
 A workflow AI profile never fills these fields automatically. Likewise, a saved
 Weave AI profile does not change a workflow's model or authorize its worker.