docs(TSP-1096): add agent tagging documentation

admin/project-management/project-tags.mdx

@@ -0,0 +1,86 @@
+---
+title: Project tags
+sidebarTitle: Project tags
+description: "Use colored tags to visually organize agents within your project."
+---
+
+Tags are colored labels that you assign to agents for visual organization. They appear in the agents list and when viewing an individual agent, letting you scan your workspace at a glance and understand each agent's status or category without opening it.
+
+Each agent can have one tag at a time. Tags are managed at the project level, so all members of a project share the same set of tags.
+
+## Default tags
+
+When a new project is created, three tags are automatically added:
+
+| Tag | Suggested use |
+|-----|---------------|
+| **Draft** | Agents under initial development |
+| **Editing** | Agents being revised or refined |
+| **In production** | Agents actively running in live workflows |
+
+These defaults support a basic development lifecycle, but you can rename, recolor, or delete them to fit your team's conventions.
+
+## Creating custom tags
+
+1. Go to **Settings** in the left-side pane of the dashboard.
+2. Select **Tags** under your project settings.
+3. Click **Create tag**.
+4. Enter a name and choose a color.
+5. Click **Save**.
+
+The new tag is immediately available to assign to any agent in the project.
+
+## Managing tags
+
+### Editing a tag
+
+1. Go to **Settings** > **Tags**.
+2. Click the edit icon next to the tag you want to change.
+3. Update the name, color, or both.
+4. Click **Save**.
+
+Changes apply immediately — agents already using that tag will display the updated name and color.
+
+### Deleting a tag
+
+1. Go to **Settings** > **Tags**.
+2. Click the delete icon next to the tag.
+3. Confirm the deletion.
+
+<Warning>
+Deleting a tag removes it from all agents it was assigned to. Those agents will no longer have a tag until you assign a new one.
+</Warning>
+
+## Assigning tags to agents
+
+### Assigning or changing a tag
+
+1. Open the agent you want to tag from your agents list.
+2. Click the tag selector in the agent header or use the context menu in the agents list.
+3. Select a tag from the dropdown.
+
+The tag is applied immediately and visible in the agents list.
+
+### Removing a tag from an agent
+
+1. Open the agent or access its context menu in the agents list.
+2. Click the tag selector and choose **No tag** (or the clear option).
+
+## Best practices
+
+**Use tags to reflect lifecycle stage.** The default "Draft", "Editing", "In production" tags work well for most teams — agents move through stages as they're built, tested, and deployed.
+
+**Combine tags with folders.** Folders group agents by function or team; tags indicate status within those groups. For example, a "Sales" folder might contain agents tagged "Draft", "In production", or "Editing" at any given time.
+
+**Keep tag sets small.** A short list of clearly defined tags is easier to apply consistently than a long list with overlapping meanings. Aim for five or fewer tags per project.
+
+**Establish team conventions.** Agree with your team on what each tag means before creating agents, so tags stay meaningful as the project grows.
+
+<Tip>
+To see all agents with a specific tag, filter the agents list by tag name.
+</Tip>
+
+## Related
+
+- [Organize your agents](/build/agents/manage-your-agent/organize-your-agents) — folders and other organizational tools
+- [Agents overview](/get-started/core-concepts/agents#organizing-your-agents) — overview of all organization methods including pinning, folders, and tags

docs.json

@@ -511,6 +511,7 @@
               "admin/project-management/remove-members",
               "admin/project-management/delete-project",
               "admin/project-management/change-project-and-org-name",
+              "admin/project-management/project-tags",
               "admin/project-management/usage-alerts",
               "admin/project-management/usage-limits",
               "admin/project-management/ids"

get-started/core-concepts/agents.mdx

@@ -6,7 +6,7 @@
 
 ## What are Agents?
 
 Agents are powered by LLMs that plan and complete tasks on autopilot. They are given tools, and decide how to use tools to achieve goals prompted by you.
 
 Unlike traditional automation that follows rigid, pre-programmed rules, AI agents can:
 
@@ -29,7 +29,7 @@
     If an agent doesn't know something, it can escalate to a human, store the answer, and use it next time. Ours posts unknowns to Slack for fast input and learning.
   </Card>
   <Card title="Works solo or with you" icon="user-gear">
     Agents can run fully autonomously or in co-pilot mode. One of ours builds Webflow pages daily—no human touch required.
   </Card>
   <Card title="Responds flexibly" icon="arrows-split-up-and-left">
     Unlike rule-based tools, agents adapt their responses to each task. A support agent might troubleshoot one day and resolve billing the next.
@@ -84,6 +84,18 @@
 
 You can organize your Agents into folders within your project, making it easier to categorize and find Agents based on their purpose, department, or use case. This is particularly useful for teams managing large numbers of Agents across different functions.
 
+### Tagging agents
+
+Tags are colored labels you can assign to agents for visual organization. Each agent can have one tag at a time, giving you a quick visual indicator of an agent's status or category when browsing your agents list.
+
+New projects automatically include three default tags: **Draft**, **Editing**, and **In production** — designed to support a basic development lifecycle. You can create additional tags, rename existing ones, or change their colors to match your team's workflow.
+
+Tags appear in the agents list and when viewing an individual agent, making it easy to scan your workspace at a glance. Use them alongside folders and pinning to keep your agents organized as your project grows.
+
+<Tip>
+Manage your project's tags — including creating, editing, and deleting them — from the [project tags settings](/admin/project-management/project-tags).
+</Tip>
+
 ## How to get the most from your Agents?
 
 When inventing or creating an agent, you'd want to utilize domain expertise or model an agent after a Domain expert:
@@ -170,8 +182,9 @@
 
     - **Pin important Agents**: Keep your most frequently used Agents at the top of your agents list in the main app for quick access
     - **Use folders**: Organize Agents into folders based on purpose, department, or use case
+    - **Assign tags**: Apply a colored tag to each agent to indicate its status or category at a glance
     - **Project organization**: Separate Agents across different projects based on your team structure
-    
+
     These organizational features help you manage large collections of Agents efficiently.
   </Accordion>
 </AccordionGroup>