docs(agent-platform): add named agents page and cross-link from related pages

Adds a new dedicated page for named agents (agent identities) under cloud
agents, and reconciles a handful of existing pages so that automation
guidance and service-account references point to the new page.

- New: src/content/docs/agent-platform/cloud-agents/agents.mdx — what a
  named agent is, plan limits, attaching descriptions/secrets/skills,
  REST endpoints, API keys bound to a named agent, running as a specific
  identity, and where named agents surface in the product.
- Edit: agent-platform/cloud-agents/secrets.mdx — forward-links from the
  team-secrets recommendation and adds a brief note that secrets can be
  attached directly to a named agent.
- Edit: agent-platform/cloud-agents/deployment-patterns.mdx — Pattern 1
  checklist now references a named agent (recommended for automation)
  instead of an unscoped "service account".
- Edit: agent-platform/cloud-agents/oz-web-app.mdx — reconciles the two
  meanings of the Agents page (skills browser + named-agent management)
  with a clear section split and a forward link.
- Edit: reference/cli/index.mdx — keeps the literal `oz whoami` output
  intact and adds a one-line note pointing readers to the new agents
  page for what a service-account principal represents.
- Edit: reference/cli/federate.mdx — keeps the literal
  `service_account:my-sa-id` example and adds a cross-reference to the
  new agents page.

Hard rules: no edits to sidebar.ts, vercel.json, landing pages, or any
pages owned by the five orchestration-launch PRs.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: hongyi-chen

src/content/docs/agent-platform/cloud-agents/agents.mdx

@@ -0,0 +1,96 @@
+---
+title: Named agents
+description: >-
+  Named agents are team-scoped identities that own and execute cloud agent
+  runs. Use them to separate workflows, scope credentials, and attribute
+  automated work to a specific bot account.
+sidebar:
+  label: "Named agents"
+---
+
+A **named agent** is a team-scoped identity that can own and execute Oz cloud agent runs. Every Warp team starts with a single default agent. Creating additional named agents lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person.
+
+Named agents are useful when you want to:
+
+* **Separate workflows** - Give the deploy bot, the dependency-update bot, and the code-review bot distinct identities so runs are easier to filter and audit.
+* **Scope credentials** - Attach a specific set of managed secrets and skills to one identity so its runs receive only the configuration that workflow needs.
+* **Attribute automated work** - Bind an API key to a named agent so CI pipelines and webhooks show up as that bot in run history rather than as a teammate.
+
+## How named agents work
+
+Each team has one default agent that runs receive automatically when no specific identity is chosen. You can create additional named agents on top of that default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of named agents.
+
+You can attach the following configuration to a named agent:
+
+* **Description** - A short, human-readable summary teammates see when picking the agent.
+* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to.
+* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the agent comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments.
+
+Skill specs are stored in their normalized fully-qualified form, and managed secret references are validated against the team's secret scope at attach time. If a secret is missing or a skill repo is not accessible to the team's GitHub App installation, the request is rejected before anything is saved.
+
+## Plan limits
+
+Each plan caps the number of named agents (including the default) a team can have:
+
+* **Free** - 1 named agent.
+* **Build** - 1 named agent.
+* **Business** - 5 named agents.
+* **Enterprise** - Unlimited.
+
+When a team is over its plan limit (for example, after downgrading), the extra identities remain visible in the list but are marked as unavailable. Unavailable identities cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited.
+
+## Managing named agents
+
+You can create, list, update, and delete named agents through the public API. The full request and response shapes — including error codes — live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `getAgent`, `updateAgent`, and `deleteAgent` under the **agent** tag.
+
+The endpoints behave as follows:
+
+* **Create** - `POST /agent/identities` with a `name` and optional `description`, `secrets`, and `skills`. Returns `201` with the new agent's `uid`, `name`, and `available` flag.
+* **List** - `GET /agent/identities` returns every named agent on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit.
+* **Retrieve** - `GET /agent/identities/{uid}` returns a single agent by its UID.
+* **Update** - `PUT /agent/identities/{uid}` replaces individual fields. Omitting a field preserves the current value; passing an empty string or empty array clears it.
+* **Delete** - `DELETE /agent/identities/{uid}` soft-deletes the agent and atomically deletes every API key bound to it. The default agent cannot be deleted.
+
+### Caller requirements
+
+A few constraints apply across every endpoint:
+
+* **Team-scoped** - Named agents belong to a team. The caller must be a member of exactly one team. If the caller is on zero teams or multiple teams, the request is rejected.
+* **Human callers only** - Only human users can create, update, or delete a named agent. A request authenticated as a named agent itself is rejected.
+* **Availability is enforced on use** - Over-plan-limit agents are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs.
+
+## API keys bound to a named agent
+
+A team API key can be bound to a specific named agent at creation time. Calls authenticated with that key run as the chosen agent. The team is resolved automatically from the agent — you don't need to specify a team when generating the key.
+
+To create a key bound to a named agent, pass the agent's UID to the `generateApiKey` mutation. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys.
+
+Once the key exists, the CLI and SDK authenticate as that named agent for every call. There is no extra flag to set; the binding is on the key itself.
+
+## Running as a named agent
+
+There are two ways to run a cloud agent as a specific named agent:
+
+* **Authenticate with a key bound to the agent** - Every run started with that key executes as the bound named agent. This is the typical path for CI pipelines and scheduled work.
+* **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the named agent's `uid` in the request body. The field is only valid for team-owned runs.
+
+When neither path is used, runs execute under the default identity ("Quick run" in the web app).
+
+## Where named agents appear in the product
+
+Named agents surface across several Oz surfaces:
+
+* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete named agents. The same page lists the skills available to your team.
+* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default option (runs execute as the calling user); selecting a named agent runs as that identity instead.
+* **Run filters and detail** - The Runs view lets you filter by named agent, and individual run detail pages show which identity executed the run.
+* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by named-agent runs to the team rather than to a person.
+
+## Related pages
+
+* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to a named agent.
+* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use a named agent for automation versus a personal identity.
+* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the named agent endpoints.
+* [API Keys](/reference/cli/api-keys/) - Create keys bound to a specific named agent.
+* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as a named agent.
+* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage named agents and inspect their runs.
+* [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls.

src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx

@@ -53,7 +53,7 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte
 #### Minimal setup checklist
 
 * A Warp team
-* A service account (recommended for automation)
+* A [named agent](/agent-platform/cloud-agents/agents/) (recommended for automation)
 * The Oz CLI installed on the runner / box
 * Any needed credentials (often via secrets + environment variables)
 

src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx

@@ -119,7 +119,12 @@ The skill provides base instructions; your prompt adds context for this particul
 
 ## Agents
 
-The **Agents** page (`/agents`) shows all skills available from your environments, plus suggested skills from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills).
+The **Agents** page (`/agents`) covers two related but distinct concepts:
+
+* **Skills** - Reusable instruction sets stored in repositories that an agent can execute. Browse skills available from your environments, plus suggested skills from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills).
+* **Named agents** - Team-scoped identities that own and execute runs. The same page is where teams create and manage named agents, attach descriptions and secrets to them, and bind API keys to a specific identity.
+
+For the full reference on named agents — including plan limits, the REST endpoints, and how to run as a specific identity — see [Named agents](/agent-platform/cloud-agents/agents/).
 
 ### Skill details
 
@@ -142,15 +147,25 @@ Click any skill to view its details, then click **Run** to start an agent with t
 For more details on how skills work with cloud agents, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/).
 :::
 
-### Creating new agents
+### Creating new skills
 
-Click **New agent** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs.
+Click **New skill** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs.
 
 <figure>
 ![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png)
-<figcaption>Creating a new agent skill in the Oz web app.</figcaption>
+<figcaption>Creating a new skill in the Oz web app.</figcaption>
 </figure>
 
+### Named agents
+
+Named agents are managed from the same Agents page. From the named-agents view, you can:
+
+* **Create a named agent** - Give it a name, an optional description, a default model and harness, and the secrets and skills runs as that agent should receive.
+* **Edit an existing agent** - Update its description, attached secrets, attached skills, or default configuration.
+* **Delete an agent** - Soft-deletes the agent and atomically deletes every API key bound to it. The default agent cannot be deleted.
+
+When you start a new run or schedule from the web app, the form's **Agent** dropdown lets you pick which named agent should execute the run. **Quick run** is the default option and runs as your own user. See [Named agents](/agent-platform/cloud-agents/agents/) for the full reference.
+
 ---
 
 ## Schedules
@@ -259,6 +274,7 @@ For detailed integration setup instructions, see [Slack](/agent-platform/cloud-a
 ## Related resources
 
 * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Learn about cloud agents and when to use them
+* [Named agents](/agent-platform/cloud-agents/agents/) — Team-scoped identities that own and execute runs
 * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — Run agents based on reusable skill definitions
 * [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) — Run agents automatically on a cron schedule
 * [Environments](/agent-platform/cloud-agents/environments/) — Configure runtime context for cloud agents

src/content/docs/agent-platform/cloud-agents/secrets.mdx

@@ -57,7 +57,7 @@ Team secrets are shared across the entire team and are available to all cloud ag
 * Ideal for shared infrastructure credentials, service accounts, and read-only API keys
 
 :::note
-Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person.
+Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. When you want a credential to be available to one workflow only, attach it to a [named agent](/agent-platform/cloud-agents/agents/) instead of giving every run access to it.
 :::
 
 **For example:**
@@ -68,6 +68,10 @@ Because team secrets are broadly available and may be used by fully automated or
 
 This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies.
 
+:::note
+Team secrets can also be attached directly to a [named agent](/agent-platform/cloud-agents/agents/), so only runs executing as that agent receive them. The secret itself still lives in the team's secret scope; the named agent just references it by name.
+:::
+
 #### Personal secrets
 
 Personal secrets belong to an **individual user**.

src/content/docs/reference/cli/federate.mdx

@@ -44,7 +44,7 @@ oz federate issue-token \
 
 The subject claim is what your cloud provider's policy will match on, so pick the combination that gives you the IAM granularity you need. Supported components:
 
-* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`.
+* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. A `service_account:` principal corresponds to a [named agent](/agent-platform/cloud-agents/agents/) on your team.
 * **`scoped_principal`** - The principal scoped to a team, like `principal:my-team-id/user:my-user-id`.
 * **`email`** - The principal's email, like `email:user@warp.dev`.
 * **`teams`** - The principal's team, like `teams:my-team-id`.

src/content/docs/reference/cli/index.mdx

@@ -156,7 +156,7 @@ Use `oz whoami` to print information about the currently authenticated principal
 oz whoami
 ```
 
-The output includes your user or service account ID, display name, email, and team (when available). For machine-readable output, set `--output-format json` or `--output-format text`.
+The output includes your user or service account ID, display name, email, and team (when available). When the CLI is authenticated as a service account principal, that principal is a [named agent](/agent-platform/cloud-agents/agents/) on your team. For machine-readable output, set `--output-format json` or `--output-format text`.
 
 ```sh
 # JSON output for scripts