Document Agent evaluations, versions, and exports

content/docs/developers/api-ref/agents-and-versions.mdx

@@ -7,6 +7,8 @@ description: Create Agents, read their current immutable configuration, and publ
 
 An Agent record points at one immutable configuration through `currentConfigId`. Use that ID as `baseConfigId` when you update the Agent.
 
+For the product flow, including reviewing changes and rolling back safely, see [Versions](/developers/versions).
+
 Agent-owned work runs in [threads](/developers/api-ref/threads-and-messages) and can start from [schedules](/developers/api-ref/schedules) or [webhooks](/developers/webhooks).
 
 ## List Agents

content/docs/developers/evaluations.mdx

@@ -0,0 +1,61 @@
+---
+title: Agent evaluations
+sidebarTitle: Evaluations
+icon: flask-conical
+description: Test one response or a short conversation before relying on an Agent for live work.
+---
+
+Evaluations answer a practical question: does this Agent handle an important case the way you expect? Save a test once, run it after an Agent change, and compare the result with earlier runs.
+
+Open an Agent and select **Evaluations**, then select **Add test**.
+
+## Choose the test type
+
+| Type | Use it for | What runs |
+| --- | --- | --- |
+| **Check** | One clear decision or response | One prompt and one Agent response |
+| **Simulation** | A conversation that depends on follow-up details | A starting message, then one participant reply per line |
+
+Use a check when one answer is enough to judge the behavior. Use a simulation when the Agent should ask questions, keep a decision consistent, or reach a safe handoff over several turns.
+
+## Example: test an escalation Agent
+
+Create this check:
+
+- **Name:** `P0 escalation`
+- **Prompt:** `Production checkout is down for every customer.`
+- **Expected outcome:** `Classifies the incident as P0, identifies missing context and a next owner, and does not send an external message.`
+- **Evaluation guidance:** `The response must stop for approval before any external action.`
+
+Then create this simulation:
+
+- **Name:** `Delayed P1 customer`
+- **Starting message:** `Our enterprise checkout workflow is severely degraded and customers cannot complete purchases.`
+- **Participant replies:** one line each: `It affects our European stores.`; `We have a workaround, but it is slow.`; `When can you escalate this?`; `Please draft an acknowledgement.`
+- **Expected outcome:** `Keeps the incident at P1, gathers the customer, impact and urgency, prepares an acknowledgement and internal escalation, and stops for approval.`
+
+Write the expected outcome as observable behavior. Prefer “classifies as P0 and names the next owner” over “handles the incident well.” Add guidance only for a boundary that is easy to miss.
+
+## Run and review
+
+Select **Run** beside a test. The result shows:
+
+- Passed or failed and a score out of 100.
+- A short explanation of what met or missed the expected outcome.
+- The Agent response, or the full transcript for a simulation.
+- A link to the evaluation thread.
+- Score history after the same test has completed more than once.
+
+The run uses the Agent's current saved version. The run record keeps that version ID, so results from before and after an edit remain distinguishable.
+
+Evaluation runs cannot call tools or update Agent memory. They test the response safely; they do not send messages, change external data, or train the Agent. Edit the Agent or test definition yourself, then run the test again.
+
+## A useful release loop
+
+1. Add checks for the decisions that must never regress.
+2. Add one short simulation for the main handoff or follow-up flow.
+3. Run them before editing the Agent and note the results.
+4. Save the Agent change and run the same tests again.
+5. Open a new Agent thread for a final live test, including any tool approval you expect a person to review.
+
+If the change performs worse, use [Versions](/developers/versions) to restore the last known-good setup.

content/docs/developers/export-import-and-share-agents.mdx

@@ -0,0 +1,44 @@
+---
+title: Export, import, and share Agents
+sidebarTitle: Export, import & share
+icon: share-2
+description: Move an Agent definition between workspaces or give someone a safe copy to review.
+---
+
+Export, import, and share create portable copies of an Agent's setup. They do not transfer a live Agent, its chat history, or ownership of the original.
+
+Open the Agent and select its name in the top bar to find **Export YAML**, **Import Agent**, and **Share**.
+
+## Export a file
+
+Select **Export YAML** to download an `.agent.yaml` definition. Keep the file in source control when you want a reviewable handoff or a backup outside Fluso.
+
+The file includes the portable Agent fields and its saved workflow. It leaves out workspace identities, secrets, deliveries, project ownership, and knowledge-file contents. The names of omitted knowledge files are included so the recipient knows what must be added again.
+
+## Import a copy
+
+Select **Import Agent** and choose a Fluso Agent YAML, YML, or JSON definition. Fluso opens a new Agent draft; it does not overwrite the Agent whose menu you used.
+
+Before creating the copy:
+
+1. Review the name, instructions, and conversation starters.
+2. Choose the destination project. Imports start in **Home**.
+3. Add the required knowledge files again.
+4. Review every skill and App. These are references, not transferred credentials, and must be available in the destination workspace.
+5. Create the Agent and test it in a new thread.
+
+Agent definition files are limited to 128 KB. Import rejects an incomplete definition or an unsupported format version rather than creating a partial Agent.
+
+## Share a review link
+
+Select **Share**, then **Copy link**. Anyone with the link can review the read-only setup and choose **Import this Agent** to make a separate copy in their own workspace.
+
+A shared link contains the portable definition. Treat it like the exported file: send it only to people who may read the Agent's instructions and configuration. It does not include workspace secrets, identities, chat history, project files, or knowledge-file contents.
+
+The link is a snapshot, not ongoing collaboration. Later edits to the source Agent do not update an imported copy, and changes to the copy do not affect the source. Share a new link when you want someone to review a newer setup.
+
+## Example handoff
+
+For a customer escalation Agent, export the definition or share its link with the support lead. They can review the P0/P1 rules and approval boundary, import a copy, connect their own Gmail and Slack access, add their escalation runbook, and test it without touching your Agent or threads.
+
+For ordinary project and conversation imports, see [Imports](/features/imports). Those imports bring context and files into projects; they are separate from importing an Agent definition.

content/docs/developers/meta.json

@@ -5,11 +5,14 @@
     "api-ref",
     "architecture",
     "context-isolation-in-threads",
+    "evaluations",
+    "export-import-and-share-agents",
     "parent-and-child-threads",
     "project-context",
     "schedules",
     "threads-and-contexts",
     "user-preferences",
+    "versions",
     "webhooks"
   ]
 }

content/docs/developers/threads-and-contexts.mdx

@@ -7,6 +7,18 @@ description: Understand which Agent settings, conversation history, project data
 
 A thread is one conversation with a saved Agent. Its context is assembled from several sources with different lifetimes.
 
+## Start a new chat with an Agent
+
+In the Agents workspace, find the Agent in the left sidebar and select the **+** beside its name. You can also open the Agent and select **New thread** in the top right.
+
+The new chat opens with that Agent's saved name, instructions, knowledge, Apps, and project. Send the first request as you would in an ordinary chat. For example:
+
+> *"A customer says checkout is unavailable for their whole company. Classify the incident, list the missing details, and prepare the internal escalation. Do not contact anyone yet."*
+
+Use one thread for one case or outcome. Start another thread for a different customer, incident, or piece of work. This keeps the conversations separate while both can still use files and working memory from the Agent's configured project.
+
+If you edit the Agent, start a new thread to test the change. A thread keeps the Agent setup it started with; it does not switch versions midway through a conversation.
+
 ## Context map
 
 | Source | Scope | What happens in a new thread |

content/docs/developers/versions.mdx

@@ -0,0 +1,40 @@
+---
+title: Agent versions
+sidebarTitle: Versions
+icon: history
+description: Review saved Agent changes, restore a known-good setup, and verify it in a new thread.
+---
+
+Fluso keeps saved Agent configurations as versions. A version records the Agent fields used by a thread, including its instructions, response mode, knowledge-file list, Apps, project, skills, and thread settings.
+
+Open the Agent, select its name in the top bar, then select **Version history**.
+
+## Review what changed
+
+The newest entry is marked **Current**. Expand **changes** on an entry to compare it with the version saved immediately before it. Each entry also shows when it was saved and a short configuration ID.
+
+Use this history when an edit changes an Agent's behavior unexpectedly. It lets you identify the last setup that produced a good result without guessing which fields changed.
+
+## Roll back safely
+
+1. Find the last known-good saved configuration.
+2. Select **Roll back**.
+3. Review the fields listed in the confirmation dialog.
+4. Select **Promote to current**.
+5. Start a **New thread** and repeat the request or [evaluation](/developers/evaluations) that exposed the problem.
+
+Rollback does not erase history. Fluso creates a new current configuration from the selected version, so the change is visible and can itself be reversed later.
+
+Existing threads keep the configuration they started with. Only new threads use the restored configuration. This prevents a long-running conversation from changing behavior halfway through.
+
+<Warning>
+  Rollback restores saved Agent fields. It does not restore an older Agent Studio workflow preview, recreate deleted project files, or copy back a project that no longer exists.
+</Warning>
+
+If the selected version points to a deleted project, choose a current project in the editor first. If the Agent changed in another browser tab, refresh the history, review the newest version, and retry.
+
+## Example
+
+Suppose a customer escalation Agent begins treating degraded service as P0 after its severity instructions were edited. Open **Version history**, compare the instruction changes, and promote the last version that kept degraded-but-usable service at P1. Then start a new thread with the same case and confirm the severity, next owner, and approval boundary.
+
+For API-based version updates, see [Agents and versions](/developers/api-ref/agents-and-versions).

content/docs/features/meta.json

@@ -1,11 +1,12 @@
 {
   "pages": [
     "approvals",
-    "mcp",
     "chat",
     "confidential",
     "imports",
+    "mcp",
     "memory",
+    "open-architecture",
     "projects",
     "skills",
     "tasks",

content/docs/features/open-architecture.mdx

@@ -0,0 +1,59 @@
+---
+title: Open architecture
+sidebarTitle: Open architecture
+icon: blocks
+description: Keep a usable copy of your work and move it through documented files, links, and APIs.
+---
+
+Fluso keeps core work in ordinary formats instead of locking every object behind one interface. You can download project files, move Agent definitions, export operational records, and read conversation history through the API.
+
+Different exports serve different purposes. A project ZIP is a file backup; an Agent YAML is a reusable setup; a shared chat is a reviewable snapshot.
+
+## What you can take out
+
+| Data | Export path | What you receive |
+| --- | --- | --- |
+| **Projects and files** | Open **Projects**, use the project's **••• → Export as zip**, or open a project and select **Export** | A ZIP of the project's regular files, folders, `context.md`, and project metadata |
+| **Individual files** | Open a project file and select **Download** | The original file in its stored format |
+| **Agents** | Open an Agent, select its name, then **Export YAML** | A portable `.agent.yaml` definition with the Agent's saved setup and workflow |
+| **Agent review copies** | Open an Agent, select its name, then **Share** | A read-only link that another person can inspect and import as a separate Agent |
+| **Conversation history** | Open a chat and select **Share chat**, or read messages with the Threads API | A revocable public snapshot, or structured persisted messages through the API |
+| **Audit logs** | In Fluso Admin, filter **Audit log**, then select **Export _N_ rows** | CSV containing the currently filtered rows from the latest 100 recorded identity and access events |
+| **Usage records** | In Fluso Admin, open **Observability → Export CSV** | CSV of the recorded daily gateway cost and token totals shown in the 14-day view |
+
+Project ZIPs skip dotted runtime entries and symbolic links. They do not serve as a complete conversation archive. Use the [Threads and messages API](/developers/api-ref/threads-and-messages#read-message-history) when you need persisted chat records in a system you control.
+
+## Skills stay readable
+
+Open **Plugins → Skills** and select a skill to read its `SKILL.md`. This is the instruction document Fluso follows.
+
+The skill document is view-only, and there is no one-click skill bundle export today. For a custom skill you own, copy its `SKILL.md` and keep its source files in your own version control before removing it from Fluso. Built-in and marketplace skills can be inspected in Fluso but are not exported as workspace-owned packages.
+
+## What an Agent export leaves behind
+
+Agent export and sharing deliberately omit:
+
+- Workspace identities and credentials.
+- App connection secrets.
+- Chat history and deliveries.
+- Project ownership and project files.
+- Knowledge-file contents.
+- Schedules, webhook triggers, evaluations, and version history.
+
+The export names omitted knowledge files so the recipient can add them again. Skills and Apps remain references to review and reconnect in the destination workspace. See [Export, import, and share Agents](/developers/export-import-and-share-agents) for the full handoff flow.
+
+## A practical handoff
+
+To hand a customer-support workflow to another team:
+
+1. Export the support project as ZIP so they receive the runbooks and working files.
+2. Export the Agent as YAML, or send its review link.
+3. Share any example conversation as a snapshot, removing sensitive messages first.
+4. Export the relevant filtered audit rows separately if the reviewer needs access evidence.
+5. In the destination workspace, import the Agent, upload the project files, reconnect Apps, and run its evaluations before live use.
+
+These exports are independent snapshots. Later Fluso changes do not silently rewrite the copies you already saved.
+
+## APIs for continuous access
+
+Use the [API reference](/developers/api-ref/authentication) when a one-time download is not enough. The API exposes Agents and versions, projects and files, threads and messages, schedules, runs, and usage. Authenticate each request with a scoped bearer token and store only the data your integration needs.