diff --git a/.cspell.json b/.cspell.json
index 31f2158..066fcfb 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -43,6 +43,7 @@
     "Hubspot",
     "hypervisor",
     "Intercom",
+    "journalctl",
     "Kimi",
     "Linear",
     "MDX",
@@ -82,6 +83,11 @@
     "Supabase",
     "timecode",
     "uvx",
-    "webhook"
+    "uuidgen",
+    "webhook",
+    "healthz",
+    "OpenRouter",
+    "versionable",
+    "xhigh"
   ]
 }
diff --git a/AGENTS.md b/AGENTS.md
index 4d8593a..13d7b61 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,13 +10,15 @@
 
 ## Information architecture
 
-The navigation keeps Home first, then sorts the top-level sections and the pages inside each section alphabetically:
+The navigation keeps Home first and sorts the top-level sections alphabetically. Agents follows the user journey. Other sections keep their existing order:
 
 - **Administration** - `/admin-panel`. Browser-admin access, dashboards, governance records, runtime controls, and network policy.
-- **Agents (Beta)** - `/developers/*`. Guides cover Agent setup, threads, context, projects, schedules, preferences, and webhooks. Architecture and the REST API reference live here too, with API pages under `/developers/api-ref/*`.
+- **Agents (Beta)** - `/developers/*`. Start with a familiar task, then improvement and scheduling. Keep Examples and More about Agents (`/developers/guides/*`) collapsed by default. Introduce features when they help the reader's current task. Keep prompts natural and explain terms before using them.
 - **App setup** - `/integrations/{github, gmail, google-calendar, slack}`. Per-app permissions and prompts, not feature pages. All of them connect through the Apps tab of the Add MCP dialog.
 - **Deployment models** - `/deployment-models`. Current availability and operating boundaries for Fluso Cloud, dedicated AWS VPC, planned Azure VNet, and scoped on-premises deployments.
 - **Features** - `/features/*`. Approvals and permissions, Apps and MCP servers, Chat, Confidential mode, Imports, Memory, Projects, Skills, and Tasks.
+- **Fluso API** - `/api/*`. Start with access and a first request. Keep Cloud and daemon credentials and administration separate. Document shared workflows once under Use the API. Lead with a useful task, runnable requests, and the expected result. Reuse the deployment's example helpers. Put protocol details and recovery rules beside the step that needs them. Each deployment's `/docs` and `/v1/openapi.json` own exact request and response schemas. Keep endpoint tables collapsed after the workflow. Preserve old API URLs with redirects.
+- **Fluso Local** - `/workspaces/*`. Setup and everyday use on your own machine, followed by settings and maintenance. Keep macOS and Linux as choices inside one setup guide. Request daemon download links from support; do not publish unlisted release URLs. API access is documented under Fluso API.
 - **Get started** - `/going-deeper`, `/introduction`, `/quickstart`. These pages explain the path from first setup to daily use.
 - **Reference** - `/resources/{faq, legal, pricing}`. Legal links to the terms of service at `https://fluso.ai/terms` and privacy policy at `https://fluso.ai/privacy`; do not duplicate the policies in the docs.
 - **Release notes** - `/release-notes`. Customer-facing changes, newest first.
@@ -42,7 +44,8 @@ Email, calendar, code, content, research are skills, not separate features. The
 ## Terminology
 
 - **Fluso** — the product.
-- **Apps** / **MCP connections** — the connections to third-party apps. There is no separate connector system; "Plugins" is the sidebar item, and connections live under **Plugins → MCP**. Don't introduce "connector" in new copy except where the app itself still says "connector tools" (the approvals settings).
+- **Apps** / **MCP connections** — the connections to third-party apps. There is no separate connector system; connections live under **Plugins → MCP**. Use **Connectors** when referring to the Agent editor's capability picker.
+- **Agent** — saved setup and a continuing main conversation. **Manager** refines that one Agent; **sessions** are delegated conversations; **routines** are scheduled messages. Main conversations take saved setup changes on their next turn; existing delegated sessions retain their setup.
 - **Knowledge graph** — Fluso's persistent memory. Lowercase.
 - **Skills** — specialised capabilities that activate automatically. Built-in or custom (`SKILL.md`).
 - **Projects** — workspaces that scope context, files, and tasks.
@@ -69,6 +72,8 @@ The docs follow Wikipedia's "Signs of AI writing" guide. The bans below aren't s
 
 **Have opinions, vary rhythm.** Mix short and long sentences. Don't just describe; the writer's actual take should come through.
 
+Use the [ASD-STE100 writing skill](https://github.com/danyuchn/asd-ste100-skill/blob/master/SKILL.md) for Agents guides. Keep procedures to one action per sentence. Use short sentences, active voice, consistent terms, and explicit conditions. Preserve uncertainty and UI labels. These guidelines do not certify compliance with the official dictionary.
+
 ## Style preferences
 
 - Active voice, second person ("you").
@@ -83,7 +88,8 @@ The docs follow Wikipedia's "Signs of AI writing" guide. The bans below aren't s
 ## Content boundaries
 
 - Never invent feature behaviour. If a capability isn't documented in source materials, leave it out.
-- Always pair "Fluso can send X" with the approval safety note: drafts are shown for review.
+- When describing external sends, explain how to request and review a draft and choose **Ask me first**. Do not claim every write requires approval: saved tool rules, connection settings, and the chat's mode determine that behavior.
+- Verify Agent behavior against both current frontend and backend code. Do not restore removed Studio graphs, evaluations, version rollback, YAML transfer, webhook triggers, or thread-management toggles from historical release notes.
 - For product actions, point users to the macOS download at `https://fluso.ai/` and to support at `support@premai.io`. Don't link to `app.fluso.ai`. Fluso is a desktop app.
 
 ## Publishing release notes
diff --git a/README.md b/README.md
index 974e532..d7b6dd5 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,31 @@ npm run start   # serve the built out/ directory
 
 Writing rules and voice live in [AGENTS.md](AGENTS.md).
 
+## Keeping the Agents guides current
+
+The October 8, 2026 refresh was checked against backend `dev` at [54df16716](https://github.com/premAI-io/premapp-backend/commit/54df16716fd37ddb1d48faff1b6f14bc05a8a6df) and frontend `dev` at [529cd9f6b](https://github.com/premAI-io/fluso-frontend/commit/529cd9f6b3b06d9cbb7c57acd6e52eb1da0e62df). These are development behavior, not a claim about production rollout.
+
+Check both sides when updating the guides:
+
+| Behavior | Backend source | Frontend source (under `apps/frontend/src/`) |
+| --- | --- | --- |
+| Setup, edits, capabilities, context | `agents/src/agent-library/{service,chat-binding}.ts`, `agents/src/context/assembler.ts`, `agents/prompts/agent-manager.md` | `features/agents/components/{agent-manager,agent-form,agent-capability-select}.tsx` |
+| Sessions and queued work | `agents/src/hosted/{flusoctl,session-controller}.ts` | `features/agents/components/agent-sessions.tsx`, `features/chats/components/ChatMessagesPanel.tsx` |
+| Routines and Inbox | `backend/aci/server/services/agent_schedules.py`, `backend/aci/server/routes/agent_runs.py` | `features/agents/components/agent-routines-page.tsx`, `app/(dashboard)/agents/inbox/page.tsx`, `stores/inbox-seen-store.ts` |
+| Sharing and starting points | `backend/aci/server/{routes/agent_shares,services/agent_templates}.py`, `agents/src/agent-library/share-resources.ts` | `features/agents/components/{agent-share-dialog,agent-import-page}.tsx` |
+| Availability and approvals | `backend/aci/common/db/crud/mcp_permission_modes.py`, `backend/aci/server/routes/mcp/permissions.py` | `lib/config.ts`, `features/mcp/lib/permission-mode.ts` |
+| API contracts | `backend/aci/server/routes/`, `backend/aci/common/schemas/` | `features/agents/api/`, `lib/api/`, `app/auth/client/page.tsx` |
+
+The examples use generalized patterns from a read-only review of development conversations, tool results, and saved files. They contain no account transcripts, customer data, or credentials. Custom service examples describe prerequisites rather than built-in capabilities.
+
+The reading path starts with one meeting-preparation task, then refinement and scheduling. Examples, detailed behavior, and developer reference are separate, collapsed sidebar groups. Introduce a feature when it helps the reader do something. Use natural requests and explain necessary terms where they first appear.
+
+Thirteen product screenshots come from these `dev` revisions running locally with a Clerk test account and real model calls. The first walkthrough uses clearly identified sample workshop notes, including a correction to the Agent's cost assumptions. Follow-up images show its saved Manager refinement, attached checklist, capabilities, schedule, library entry, and sharing choices. The sample morning routine was saved, captured, and paused. The sharing dialog was captured before publishing.
+
+The longer launch-review example used this documentation draft and its validation report. It covered file uploads, separate working sessions, Manager refinement, a one-time routine, and Inbox. Its completed sessions were renamed through the app to describe their assignments. Screenshots use the relevant dialog, section, or narrower app window to keep text readable. The creation form was recaptured without submitting another Agent; conversation images show saved history. No responses or product states were mocked. The cookie-consent dependency was built from its genuine `v1.0.0` source because private-registry access was unavailable.
+
+Use source behavior over old release notes. Remove retired pages from navigation and add their replacements to `public/_redirects`, including markdown export URLs. Cloudflare Pages serves these redirects; Next's local dev server does not.
+
 ## Deployment
 
 Pushes to `main` build and deploy via `.github/workflows/deploy.yml` (Cloudflare Pages, project `fluso-docs`). Requires the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` repo secrets.
diff --git a/app/(docs)/[[...slug]]/page.tsx b/app/(docs)/[[...slug]]/page.tsx
index 06ff2e3..b32177b 100644
--- a/app/(docs)/[[...slug]]/page.tsx
+++ b/app/(docs)/[[...slug]]/page.tsx
@@ -24,18 +24,23 @@ export default async function Page(props: PageParams) {
 
   const MDX = page.data.body;
   const markdownUrl = getPageMarkdownUrl(page).url;
+  const isAgentGuide = page.slugs[0] === 'developers' && page.slugs[1] !== 'api-ref';
 
   return (
     <DocsPage toc={page.data.toc} full={page.data.full}>
       <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription className="mb-0">{page.data.description}</DocsDescription>
-      <div className="flex flex-row gap-2 items-center border-b pb-6">
-        <MarkdownCopyButton markdownUrl={markdownUrl} />
-        <ViewOptions
-          markdownUrl={markdownUrl}
-          githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/content/docs/${page.path}`}
-        />
-      </div>
+      <DocsDescription className={isAgentGuide ? undefined : 'mb-0'}>
+        {page.data.description}
+      </DocsDescription>
+      {!isAgentGuide && (
+        <div className="flex flex-row gap-2 items-center border-b pb-6">
+          <MarkdownCopyButton markdownUrl={markdownUrl} />
+          <ViewOptions
+            markdownUrl={markdownUrl}
+            githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/content/docs/${page.path}`}
+          />
+        </div>
+      )}
       <DocsBody>
         <MDX
           components={getMDXComponents({
diff --git a/app/global.css b/app/global.css
index dce5ad6..ea1d67c 100644
--- a/app/global.css
+++ b/app/global.css
@@ -2,6 +2,16 @@
 @import 'fumadocs-ui/css/neutral.css';
 @import 'fumadocs-ui/css/preset.css';
 
+/* Quote marks, when needed, are part of the Markdown text. */
+.prose blockquote {
+  quotes: none;
+}
+
+/* Keep reference descriptions readable beside long endpoint paths on phones. */
+#nd-page details td:last-child {
+  min-width: 14rem;
+}
+
 /* Fluso brand (ported from Mintlify docs.json colors) */
 :root {
   --color-fd-primary: #5b21b6;
diff --git a/components/diagrams.tsx b/components/diagrams.tsx
index 2730caf..705f13f 100644
--- a/components/diagrams.tsx
+++ b/components/diagrams.tsx
@@ -1,14 +1,8 @@
 import {
-  Bot,
   Clock3,
-  Database,
   FileText,
   FolderClosed,
   MessageSquareText,
-  Network,
-  PlugZap,
-  Server,
-  ShieldCheck,
   Users,
 } from 'lucide-react';
 
@@ -49,7 +43,7 @@ function ProjectMemory({ name }: { name: string }) {
         <FolderClosed aria-hidden="true" className="size-4 text-fd-primary" />
         {name}
         <span className="ms-auto rounded-full bg-fd-muted px-2 py-0.5 text-[11px] font-normal text-fd-muted-foreground">
-          private scope
+          context scope
         </span>
       </div>
       <div className="space-y-2">
@@ -76,7 +70,7 @@ export function MemoryScopeDiagram() {
     >
       <Layer
         label="Global preferences"
-        detail="Your timezone, response style, and standing instructions apply in every project"
+        detail="Response style and standing instructions for ordinary chats across projects"
         icon={Users}
         emphasis
       />
@@ -91,8 +85,8 @@ export function MemoryScopeDiagram() {
         id="memory-scope-caption"
         className="mt-4 text-center text-xs leading-relaxed text-fd-muted-foreground"
       >
-        Global preferences apply everywhere. Project context and working memory
-        stay inside their project.
+        Ordinary chats load global preferences. Saved Agents use their own
+        instructions. Project working memory is recalled within its project.
       </figcaption>
     </figure>
   );
@@ -208,316 +202,3 @@ export function KnowledgeGraphDiagram() {
     </figure>
   );
 }
-
-const architectureServices = [
-  {
-    label: 'Fluso client',
-    detail: 'Desktop or remote',
-    x: 10,
-    icon: MessageSquareText,
-  },
-  {
-    label: 'Edge',
-    detail: 'TLS + routing',
-    x: 162,
-    icon: ShieldCheck,
-  },
-  {
-    label: 'REST API',
-    detail: 'Identity + records',
-    x: 314,
-    icon: Server,
-  },
-  {
-    label: 'Agent gateway',
-    detail: 'Admission + routing',
-    x: 466,
-    icon: Network,
-    emphasis: true,
-  },
-  {
-    label: 'User runtime',
-    detail: 'Thread worker + tools',
-    x: 618,
-    icon: Bot,
-  },
-] as const;
-
-const architectureData = [
-  {
-    label: 'PostgreSQL',
-    detail: 'Platform records',
-    owner: 'REST API',
-    x: 380,
-    icon: Database,
-  },
-  {
-    label: 'Isolated user storage',
-    detail: 'Projects, sessions, Agents',
-    owner: 'Gateway + runtime',
-    x: 532,
-    icon: FolderClosed,
-  },
-] as const;
-
-const ARCHITECTURE_NODE_WIDTH = 132;
-
-function ArchitectureNode({
-  label,
-  detail,
-  x,
-  icon: Icon,
-  emphasis = false,
-}: {
-  label: string;
-  detail: string;
-  x: number;
-  icon: typeof FolderClosed;
-  emphasis?: boolean;
-}) {
-  return (
-    <g transform={`translate(${x} 54)`}>
-      <rect
-        className={
-          emphasis
-            ? 'fill-fd-primary/10 stroke-fd-primary/50'
-            : 'fill-fd-card stroke-fd-border'
-        }
-        width={ARCHITECTURE_NODE_WIDTH}
-        height="76"
-        rx="10"
-        strokeWidth="1.5"
-      />
-      <Icon
-        aria-hidden="true"
-        className={
-          emphasis ? 'text-fd-primary' : 'text-fd-muted-foreground'
-        }
-        x={ARCHITECTURE_NODE_WIDTH / 2 - 8}
-        y="11"
-        width="16"
-        height="16"
-      />
-      <text
-        className="fill-fd-foreground text-[14px] font-semibold"
-        x={ARCHITECTURE_NODE_WIDTH / 2}
-        y="45"
-        textAnchor="middle"
-      >
-        {label}
-      </text>
-      <text
-        className="fill-fd-muted-foreground text-[11px]"
-        x={ARCHITECTURE_NODE_WIDTH / 2}
-        y="63"
-        textAnchor="middle"
-      >
-        {detail}
-      </text>
-    </g>
-  );
-}
-
-export function ArchitectureDiagram() {
-  return (
-    <figure
-      aria-labelledby="architecture-caption"
-      className="not-prose my-6 overflow-hidden rounded-xl border bg-fd-muted/30 p-3 sm:p-5"
-    >
-      <p className="mb-2 text-xs text-fd-muted-foreground sm:hidden">
-        Scroll horizontally to view the full diagram.
-      </p>
-      <div
-        aria-label="Scrollable architecture diagram"
-        className="overflow-x-auto"
-        tabIndex={0}
-      >
-        <svg
-          role="img"
-          aria-labelledby="architecture-title architecture-description"
-          className="h-auto w-full min-w-[760px]"
-          viewBox="0 0 760 386"
-        >
-          <title id="architecture-title">
-            Fluso request and data boundaries
-          </title>
-          <desc id="architecture-description">
-            A Fluso client sends an authenticated request through the edge, REST
-            API, Agent gateway, and a user runtime. The API owns platform
-            records. The gateway and runtime use durable workspace storage. The
-            runtime queries knowledge and calls governed MCP servers.
-          </desc>
-
-          <defs>
-            <marker
-              id="architecture-arrow"
-              markerHeight="8"
-              markerWidth="8"
-              orient="auto"
-              refX="7"
-              refY="4"
-              viewBox="0 0 8 8"
-            >
-              <path className="fill-fd-muted-foreground" d="M0 0 8 4 0 8Z" />
-            </marker>
-          </defs>
-
-          <text
-            className="fill-fd-muted-foreground text-[11px] font-medium"
-            x="20"
-            y="24"
-          >
-            Request path
-          </text>
-
-          <g
-            className="stroke-fd-muted-foreground/70"
-            fill="none"
-            markerEnd="url(#architecture-arrow)"
-            strokeWidth="1.5"
-          >
-            <path d="M142 92H156" />
-            <path d="M294 92H308" />
-            <path d="M446 92H460" />
-            <path d="M598 92H612" />
-            <path d="M380 130V204" />
-            <path d="M532 130V204" />
-            <path d="M684 130V204" />
-          </g>
-
-          {architectureServices.map((node) => (
-            <ArchitectureNode key={node.label} {...node} />
-          ))}
-
-          <rect
-            className="fill-fd-card stroke-fd-border"
-            x="302"
-            y="210"
-            width="448"
-            height="156"
-            rx="12"
-            strokeWidth="1.5"
-          />
-          <text
-            className="fill-fd-muted-foreground text-[11px] font-medium"
-            x="318"
-            y="235"
-          >
-            Data and context
-          </text>
-          <line
-            className="stroke-fd-border"
-            x1="318"
-            x2="734"
-            y1="250"
-            y2="250"
-          />
-          <line
-            className="stroke-fd-border"
-            x1="452"
-            x2="452"
-            y1="264"
-            y2="350"
-          />
-          <line
-            className="stroke-fd-border"
-            x1="602"
-            x2="602"
-            y1="264"
-            y2="350"
-          />
-
-          {architectureData.map(({ label, detail, owner, x, icon: Icon }) => (
-            <g key={label} transform={`translate(${x} 0)`}>
-              <Icon
-                aria-hidden="true"
-                className="text-fd-muted-foreground"
-                x="-8"
-                y="270"
-                width="16"
-                height="16"
-              />
-              <text
-                className="fill-fd-foreground text-[13px] font-semibold"
-                textAnchor="middle"
-                y="307"
-              >
-                {label}
-              </text>
-              <text
-                className="fill-fd-muted-foreground text-[10px]"
-                textAnchor="middle"
-                y="327"
-              >
-                {detail}
-              </text>
-              <text
-                className="fill-fd-muted-foreground text-[10px] font-medium"
-                textAnchor="middle"
-                y="349"
-              >
-                {owner}
-              </text>
-            </g>
-          ))}
-
-          <g transform="translate(684 0)">
-            <Bot
-              aria-hidden="true"
-              className="text-fd-muted-foreground"
-              x="-8"
-              y="267"
-              width="16"
-              height="16"
-            />
-            <text
-              className="fill-fd-foreground text-[13px] font-semibold"
-              textAnchor="middle"
-              y="301"
-            >
-              Runtime context
-            </text>
-            <g transform="translate(-68 314)">
-              <FileText
-                aria-hidden="true"
-                className="text-fd-muted-foreground"
-                width="13"
-                height="13"
-              />
-              <text
-                className="fill-fd-muted-foreground text-[10px]"
-                x="18"
-                y="11"
-              >
-                Knowledge service
-              </text>
-            </g>
-            <g transform="translate(-68 338)">
-              <PlugZap
-                aria-hidden="true"
-                className="text-fd-muted-foreground"
-                width="13"
-                height="13"
-              />
-              <text
-                className="fill-fd-muted-foreground text-[10px]"
-                x="18"
-                y="11"
-              >
-                MCP servers
-              </text>
-            </g>
-          </g>
-        </svg>
-      </div>
-
-      <figcaption
-        id="architecture-caption"
-        className="mt-1 text-center text-xs leading-relaxed text-fd-muted-foreground"
-      >
-        Compute, platform state, workspace data, knowledge, and external sources
-        meet through explicit service boundaries.
-      </figcaption>
-    </figure>
-  );
-}
diff --git a/components/mintlify.tsx b/components/mintlify.tsx
index 11edc66..5211d6d 100644
--- a/components/mintlify.tsx
+++ b/components/mintlify.tsx
@@ -213,12 +213,16 @@ export function AccordionGroup({ children }: { children: ReactNode }) {
 export function Frame({
   caption,
   children,
+  className,
 }: {
   caption?: ReactNode;
   children: ReactNode;
+  className?: string;
 }) {
   return (
-    <figure className="my-6 overflow-hidden rounded-xl border bg-fd-card p-2 not-prose">
+    <figure
+      className={cn('my-6 overflow-hidden rounded-xl border bg-fd-card p-2 not-prose', className)}
+    >
       <div className="overflow-hidden rounded-lg [&_img]:my-0 [&_img]:w-full">
         {children}
       </div>
diff --git a/content/docs/admin-panel.mdx b/content/docs/admin-panel.mdx
index 63ab80e..439ff2b 100644
--- a/content/docs/admin-panel.mdx
+++ b/content/docs/admin-panel.mdx
@@ -45,7 +45,7 @@ The **Admin** organization role does not grant access to Fluso Admin. Panel acce
 
 Each governance event records the actor, action, target, detail, and time. Current action types cover Microsoft Entra metadata, tenant configuration, teams, roles, access requests, and Agent access records.
 
-This is not an Agent activity trace or a complete record of Admin mutations. It does not show tool calls, logins, prompts, document edits, messages, files, knowledge graphs, runtime controls, Sponsored Confidential changes, or network-policy changes. Use an Agent's **Analytics** page for its recorded runs.
+This is not an Agent activity trace or a complete record of Admin mutations. It does not show tool calls, logins, prompts, document edits, messages, files, knowledge graphs, runtime controls, Sponsored Confidential changes, or network-policy changes. Inspect the Agent's conversation and [Inbox](/developers/guides/inbox) for work and failures, or use the [Runs API](/api/workflows/runs) for recorded request state.
 
 ## Runtime and user controls
 
diff --git a/content/docs/api/cloud/apps.mdx b/content/docs/api/cloud/apps.mdx
new file mode 100644
index 0000000..67799bc
--- /dev/null
+++ b/content/docs/api/cloud/apps.mdx
@@ -0,0 +1,44 @@
+---
+title: Managed app connections
+icon: plug
+description: Connect a supported Cloud app when your integration needs its data or tools.
+---
+
+Cloud can guide users through connecting supported apps, such as Google Workspace. A connection belongs to the authenticated account. Completing sign-in does not remove its tool-approval rules.
+
+For a daemon or a custom server, use [custom MCP connections](/api/workflows/connections).
+
+## Connect the requested app
+
+For example, a morning-brief Agent may need a calendar connection. Its run can enter `waiting_action` with an `mcp_connect` action in thread state.
+
+1. Read the action to identify the requested `app_id`.
+2. Check the managed connection list for that app.
+3. Send `POST /v1/mcp-oauth/catalog/{app_id}/connect` if it needs connection.
+4. If the response says `redirect`, open its `authorization_url` for the user.
+5. Let the user complete the provider sign-in and Fluso callback.
+6. Check connection status and thread state before continuing.
+
+A `connected` response needs no browser handoff. `PROVISIONING` means provider sign-in succeeded but Fluso setup is still finishing. A refresh can complete registration. It cannot authorize an unconnected app.
+
+## Complete a custom callback client
+
+Fluso's signed-in callback normally completes the handoff. A client that handles an allowed callback itself must submit its `completion_proof` under the initiating account.
+
+Send the proof to `POST /v1/mcp-oauth/catalog/connect/complete`. Optionally set `expected_server_id` to check the returned connection. Protect the proof like a temporary credential. It expires after five minutes.
+
+A provider redirect alone does not establish that the connection is usable. Wait for the completion response or verified connection status.
+
+<Accordion title="Managed app endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/mcp-oauth/catalog` | List app IDs and connection metadata. |
+  | `GET /v1/mcp-oauth/catalog/connections` | Read provider connection status without repairing it. |
+  | `POST /v1/mcp-oauth/catalog/{app_id}/connect` | Start authorization or return an existing usable connection. |
+  | `GET /v1/mcp-oauth/catalog/callback` | Provider/browser handoff. Do not use it for polling. |
+  | `POST /v1/mcp-oauth/catalog/connect/complete` | Complete the account-bound proof exchange. |
+
+  Reads accept a developer read token. Connection changes require write access. The provider callback validates its own handoff state.
+
+  Managed apps can be unavailable in a deployment, returning 503. `redirect_url`, when supplied, must match an allowed Fluso callback location.
+</Accordion>
diff --git a/content/docs/api/cloud/client-sign-in.mdx b/content/docs/api/cloud/client-sign-in.mdx
new file mode 100644
index 0000000..30950c2
--- /dev/null
+++ b/content/docs/api/cloud/client-sign-in.mdx
@@ -0,0 +1,120 @@
+---
+title: Client sign-in
+icon: log-in
+description: Let users sign in to a configured Cloud client and keep their session active.
+---
+
+For your own script or service, use a [developer token](/api/cloud/tokens). It needs no browser callback or refresh flow.
+
+Use client sign-in when each person must connect their own Fluso account to a supported client. Fluso handles sign-in in the browser. Your client receives a one-use code and exchanges it for tokens.
+
+<Note>
+  A new client needs a configured Fluso callback. [Contact support](mailto:support@premai.io) before implementing that integration. These endpoints do not register arbitrary callback URLs.
+</Note>
+
+## Sign in once
+
+<Steps>
+  <Step title="Open Fluso sign-in">
+    Your client requests a sign-in URL. Open it in the user's browser.
+  </Step>
+  <Step title="Let the user sign in">
+    Fluso handles sign-in and returns a one-use code through your configured callback.
+  </Step>
+  <Step title="Exchange the code for tokens">
+    Your client sends the code with its private proof. Fluso returns tokens for API access and session renewal.
+  </Step>
+</Steps>
+
+The proof, called **PKCE**, keeps another client from using the returned code. Generate it once for each sign-in attempt.
+
+Use `auth.access_token` as `Authorization: Bearer TOKEN` for API requests. Save `auth.refresh_token` privately for renewal. `auth.expires_in` tells you when the access token expires.
+
+<Accordion title="Implement the sign-in exchange (Node.js)">
+  Use Node 22 or later. Set `baseUrl` to your Cloud API URL, including `/v1`. Use your configured `client` name. Set `clientUserId` to the user's stable ID within your client.
+
+  Generate the proof and request the browser URL:
+
+  ```javascript
+  import { randomBytes, createHash } from 'node:crypto';
+
+  const baseUrl = 'https://api.fluso.ai/v1';
+  const client = 'YOUR_CONFIGURED_CLIENT';
+  const clientUserId = 'YOUR_CLIENT_USER_ID';
+
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const start = await fetch(`${baseUrl}/auth/client/start`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client, client_user_id: clientUserId, code_challenge: challenge,
+    }),
+  });
+  if (!start.ok) throw new Error(`Sign-in could not start (${start.status})`);
+  const { url } = await start.json();
+  ```
+
+  Open `url` in the user's browser. Keep `verifier` on the initiating client. Do not log it or send it to the callback URL.
+
+  After the configured callback returns `code`, exchange it using the same client identity and verifier:
+
+  ```javascript
+  const exchange = await fetch(`${baseUrl}/auth/client/exchange`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client, client_user_id: clientUserId, code, code_verifier: verifier,
+    }),
+  });
+  if (!exchange.ok) throw new Error(`Sign-in exchange failed (${exchange.status})`);
+  const { auth } = await exchange.json();
+  ```
+
+  Store `auth` in the client's credential store. It includes `access_token`, `refresh_token`, `expires_in`, `session_id`, and `user`.
+
+  The browser step calls `POST /v1/auth/client/complete` with the returned state under the user's Clerk app session. Current browser callbacks support configured Fluso handoffs, including Telegram. A developer token cannot perform that browser step.
+
+  Sign-in state expires after ten minutes. The returned code expires after five minutes and works once. If the exchange response is lost, start sign-in again.
+
+  For another language, generate a verifier with 43 to 128 ASCII letters, digits, or `-._~`. Its challenge is SHA-256 encoded as unpadded base64url.
+</Accordion>
+
+## Keep the session active
+
+Before the access token expires, send the saved refresh token to `POST /v1/auth/client/refresh`:
+
+```json
+{
+  "refresh_token": "YOUR_SAVED_REFRESH_TOKEN"
+}
+```
+
+The response contains replacement `access_token` and `refresh_token` values. Save both together before sending further requests. Allow only one refresh at a time for that session.
+
+<Accordion title="Recover a lost refresh response">
+  Retry the same refresh token within 30 seconds to recover the same replacement pair. Reusing it after that window revokes the session.
+
+  Refresh extends the session's 30-day expiry. If refresh is rejected, ask the user to sign in again. Do not create a new session for each API request.
+</Accordion>
+
+## Sign out
+
+Send the refresh-token body above to `POST /v1/auth/client/revoke`. Remove the local credentials after revocation.
+
+<Accordion title="Client-session endpoint reference">
+  | Method and path | Required credential and use |
+  | --- | --- |
+  | `POST /v1/auth/client/start` | PKCE challenge. Request the browser URL. |
+  | `POST /v1/auth/client/complete` | Clerk app session and returned state. Issue the one-use code. |
+  | `POST /v1/auth/client/exchange` | Code, client identity, and original verifier. Issue tokens. |
+  | `POST /v1/auth/client/sessions` | Clerk app session. Create a client session for an already signed-in app. |
+  | `GET /v1/auth/client/sessions` | Clerk app session. List up to 100 active sessions, newest first. |
+  | `DELETE /v1/auth/client/sessions/{session_id}` | Clerk session for any owned session, or a client token for itself. |
+  | `POST /v1/auth/client/refresh` | Refresh token. Rotate the token pair. |
+  | `POST /v1/auth/client/revoke` | Refresh token. Revoke its session. Returns 204 even if already invalid. |
+
+  Client tokens cannot manage developer tokens. That operation requires Clerk sign-in.
+
+  Your [deployment's schema](/api#find-the-exact-fields) lists exact identifier constraints and response fields.
+</Accordion>
diff --git a/content/docs/api/cloud/meta.json b/content/docs/api/cloud/meta.json
new file mode 100644
index 0000000..f56a7bc
--- /dev/null
+++ b/content/docs/api/cloud/meta.json
@@ -0,0 +1,11 @@
+{
+  "title": "Cloud API",
+  "icon": "cloud",
+  "defaultOpen": false,
+  "pages": [
+    "tokens",
+    "client-sign-in",
+    "apps",
+    "sharing"
+  ]
+}
diff --git a/content/docs/api/cloud/sharing.mdx b/content/docs/api/cloud/sharing.mdx
new file mode 100644
index 0000000..cc6803b
--- /dev/null
+++ b/content/docs/api/cloud/sharing.mdx
@@ -0,0 +1,101 @@
+---
+title: Sharing
+sidebarTitle: Sharing
+icon: share-2
+description: Share an Agent, conversation, or file, and understand what a public link exposes.
+---
+
+Public sharing is Cloud-only. Anyone with a published link can read its contents. Owner operations require [authentication](/api/cloud/tokens). Public reads do not.
+
+## Share an Agent
+
+An Agent link publishes a saved copy of selected setup. It does not expose the owner's live workspace.
+
+Read `GET /v1/agents/{agent_id}/share-options` to choose resources. Publish the selection through `POST /v1/agents/{agent_id}/share`:
+
+```json
+{
+  "skills": [],
+  "knowledge_files": [],
+  "connectors": []
+}
+```
+
+Use IDs from share options for skills, knowledge names for `knowledge_files`, and server IDs for `connectors`. Instructions and portable settings are included even with empty selections. Selected skill folders and knowledge contents share limits of 20 MiB and 512 regular files. Symbolic links are rejected. Custom connection URLs with query parameters are excluded from share options.
+
+Review all selected contents and connection URLs before publishing. Stored authentication, conversations, routines, and project files are not bundled. See [Sharing and copies](/developers/guides/sharing) for the recipient experience.
+
+## Preview and import
+
+Read `GET /v1/shared/agents/{share_id}` before importing. Send its exact `published_at` with the new name and project to `POST /v1/shared/agents/{share_id}/import`:
+
+```json
+{
+  "name": "My release reviewer",
+  "project_id": "Home",
+  "published_at": "<exact value from the preview>"
+}
+```
+
+Generate and save a new `Idempotency-Key` for each import. Reuse it and the unchanged body to recover an uncertain import without creating another copy. A changed snapshot returns a conflict rather than silently importing something different from the preview.
+
+The recipient gets independent setup and selected resource copies. Imported custom skills receive distinct names. App credentials are never inherited. Read the imported Agent's `setup_requirements`, then complete missing connections and consent in its manager conversation.
+
+A revoked link becomes unavailable. Unsupported older snapshots may require republication by their owner. Revocation does not delete copies already imported.
+
+<Accordion title="Agent-sharing endpoints">
+  | Method and path | Behavior |
+  | --- | --- |
+  | `GET /v1/agents/{agent_id}/share-options` | Available custom skills, knowledge, and custom connections |
+  | `GET /v1/agents/{agent_id}/share` | Current link record or `null` |
+  | `POST /v1/agents/{agent_id}/share` | Publish a snapshot |
+  | `POST /v1/agent-shares/{share_id}/refresh` | Replace the snapshot at the same link |
+  | `DELETE /v1/agent-shares/{share_id}` | Revoke the link |
+  | `GET /v1/agent-templates` | Fluso starting-point snapshots |
+  | `GET /v1/shared/agents/{share_id}` | Public setup, resource manifest, required filenames, and `published_at` |
+  | `POST /v1/shared/agents/{share_id}/import` | Authenticated import into the recipient's workspace |
+</Accordion>
+
+## Share a conversation
+
+Publish a conversation with `POST /v1/chat-shares` and its `thread_id`. The link shows a snapshot of its saved messages. Later messages remain private until you refresh that link.
+
+Revoke the link to prevent further public reads. The private conversation remains. Deleting the conversation itself does not revoke a separately published snapshot.
+
+<Accordion title="Conversation-sharing endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `POST /v1/chat-shares/lookup-batch` | Find existing links for `thread_ids` without publishing. |
+  | `POST /v1/chat-shares` | Publish the current conversation or return its existing link. |
+  | `POST /v1/chat-shares/{share_id}/refresh` | Update saved messages at the same link. |
+  | `DELETE /v1/chat-shares/{share_id}` | Revoke the link while keeping the private conversation. |
+  | `GET /v1/shared/chats/{share_id}` | Read the public snapshot without authentication. |
+</Accordion>
+
+## Share a file
+
+Choose `share_mode` explicitly when publishing a workspace file:
+
+| Mode | What readers get |
+| --- | --- |
+| `snapshot` | A saved copy. Later file changes require a refresh. |
+| `live` | The current file at its workspace path. A view can start the owner's runtime. |
+
+Anyone with the link can download the file. Review its contents before publication.
+
+If an active link already exists, creation returns it even when you request a different mode. Revoke it before changing modes. Refreshing a live link converts it to a snapshot. A failed refresh preserves the existing link.
+
+<Accordion title="File-sharing endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `POST /v1/asset-shares/lookup-batch` | Find active links for workspace paths without publishing. |
+  | `POST /v1/asset-shares` | Publish with explicit `share_mode`. Creation can start the runtime in either mode. |
+  | `POST /v1/asset-shares/{share_id}/refresh` | Save the current file as a new snapshot at the same link. |
+  | `DELETE /v1/asset-shares/{share_id}` | Revoke the link while keeping the workspace file. |
+  | `GET /v1/shared/assets/{share_id}` | Read public bytes or follow a snapshot download redirect. |
+  | `GET /v1/shared/assets/{share_id}/{file_name}` | Read the same file with a descriptive URL suffix. |
+
+  Public reads need no bearer token. Follow redirects and inspect `Content-Type` instead of parsing the response as JSON.
+
+  Revocation blocks new public requests. A previously issued snapshot download URL can remain valid for five minutes. Revocation cannot remove copies someone already downloaded.
+</Accordion>
diff --git a/content/docs/api/cloud/tokens.mdx b/content/docs/api/cloud/tokens.mdx
new file mode 100644
index 0000000..4c60e14
--- /dev/null
+++ b/content/docs/api/cloud/tokens.mdx
@@ -0,0 +1,68 @@
+---
+title: Developer tokens
+icon: key-round
+description: Create and maintain Cloud API access for your own integration.
+---
+
+A developer token lets a script use your Fluso Cloud account. Create it in the app, then store it as your integration's secret.
+
+## Create a token in Fluso
+
+1. Open **Settings → Developer tokens** in your Cloud workspace.
+2. Click **Create token**.
+3. Enter a name that identifies the integration, such as **Weekly report**.
+4. Choose **Read only** to inspect data, or **Read and write** to submit work.
+5. Choose an expiry, then click **Create token**.
+6. Click **Copy token** before closing the result.
+
+<Frame className="mx-auto max-w-xl" caption="Give the token a name you can recognize later.">
+  <a href="/images/api/developer-token-form.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/api/developer-token-form.png" alt="Create developer token form with Weekly report, Read and write access, and a 90-day expiry." width="1024" height="800" />
+  </a>
+</Frame>
+
+The secret appears once. If you lose it, revoke that token and create a replacement.
+
+## Check access
+
+After [setting the URL and token](/api/first-request#1-get-access), check the authenticated identity:
+
+```bash
+curl --fail-with-body --silent --show-error \
+  "$FLUSO_API_URL/auth/me" \
+  -H "Authorization: Bearer $FLUSO_API_TOKEN"
+```
+
+This read does not start a runtime. Check the account and access level before your integration submits work.
+
+| Access | What it permits |
+| --- | --- |
+| `read` | Read your Agents, conversations, files, usage, and results |
+| `write` | Also submit work, change files and schedules, connect services, and decide individual tool approvals |
+| Signed-in app session | Manage developer tokens and permanent tool permissions |
+
+Access covers the account. A token is not restricted to one Agent or project. Work uses that account's limits.
+
+## Replace or revoke a token
+
+Create a replacement in Settings. Update your integration's secret, then check it with `/auth/me`. Revoke the old token after the replacement works.
+
+The default expiry is 90 days. Revocation reaches cached authentication and open streams within 30 seconds. Revocation does not stop accepted work or existing schedules. [Stop work](/api/workflows/runs#stop-work) or [pause schedules](/api/workflows/schedules) separately.
+
+<Accordion title="Token management endpoints">
+  These four management routes require the owning account's Clerk app session. Developer tokens and native client tokens cannot manage developer tokens.
+
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/account/tokens` | List metadata, including revoked tokens. Follow `next_cursor` as `after`. |
+  | `POST /v1/account/tokens` | Create with `name`, `access`, and optional `expires_at`. Requires `Idempotency-Key`. |
+  | `PATCH /v1/account/tokens/{token_id}` | Change `name` only. Replace the token to change access or expiry. |
+  | `DELETE /v1/account/tokens/{token_id}` | Revoke it. Repeated revocation returns 204. |
+  | `GET /v1/auth/me` | Read the authenticated identity. Accepts developer tokens too. |
+
+  Creation returns 201 and the secret once. Retrying the same key and body returns 200 with `secret: null`. A changed body returns 409. If the first response was lost, revoke that token and create another with a new key.
+
+  Omit `expires_at` for 90 days. Send `null` for no expiry, or a future timestamp with a timezone. An account can have at most 100 active tokens.
+</Accordion>
+
+For a native application with an existing sign-in integration, see [client sessions](/api/cloud/client-sign-in).
diff --git a/content/docs/api/daemon/meta.json b/content/docs/api/daemon/meta.json
new file mode 100644
index 0000000..839afd6
--- /dev/null
+++ b/content/docs/api/daemon/meta.json
@@ -0,0 +1,9 @@
+{
+  "title": "Daemon API",
+  "icon": "server",
+  "defaultOpen": false,
+  "pages": [
+    "pairing",
+    "settings"
+  ]
+}
diff --git a/content/docs/api/daemon/pairing.mdx b/content/docs/api/daemon/pairing.mdx
new file mode 100644
index 0000000..1d06321
--- /dev/null
+++ b/content/docs/api/daemon/pairing.mdx
@@ -0,0 +1,71 @@
+---
+title: Pair an API client
+icon: link
+description: Give a client access to your Fluso Local workspace.
+---
+
+A daemon belongs to one owner. Each paired device gets its own token for that owner's workspace. Pairing does not create a separate account or private set of files.
+
+[Set up Fluso Local](/workspaces/setup) and its provider before submitting work. For remote access, use HTTPS or an SSH tunnel.
+
+## Get a device token
+
+On the daemon's host, run this from the installed package folder. Use the same state root as your running daemon:
+
+```bash
+./fluso-daemon pair --root /path/to/state
+```
+
+Exchange its one-use code from your client:
+
+```bash
+curl --fail-with-body --silent --show-error \
+  'http://127.0.0.1:4111/daemon/v1/pair' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"code":"PAIRING_CODE","name":"Weekly report integration"}'
+```
+
+Replace the address for a remote daemon. Replace `PAIRING_CODE` with the code from the host.
+
+Save `token` privately. Keep the returned client `id` and `daemonId` with your connection settings. If that daemon identity changes later, pair again.
+
+Codes expire after ten minutes and work once. If the exchange response is lost, generate a new code. Device tokens expire after 30 idle days. Authenticated use renews them.
+
+<Note>
+  A normal device token grants read/write workspace access, including tool approvals. Add `--manage-host` only for clients that also need machine administration.
+</Note>
+
+Use the token as `Authorization: Bearer YOUR_TOKEN`. Browser requests must come from the daemon's exact origin. Use a native or server client for an integration hosted elsewhere. For the [first request](/api/first-request), set `FLUSO_API_URL` to `http://127.0.0.1:4111/v1` or your remote equivalent.
+
+## Check support and readiness
+
+`GET /v1/capabilities` reports supported features. Use it to show only the controls available on that daemon.
+
+`GET /daemon/v1/discovery` reports identity and configuration state. Its `ready` status means configuration is ready. Check `/v1/agent/runtime/status` for runtime readiness.
+
+`GET /healthz` only proves the daemon is listening. A successful health check does not prove that the model provider works.
+
+## Remove a device
+
+Send `DELETE /daemon/v1/clients/{clientId}` to revoke a token. A device can revoke itself. Host-management access also permits listing and revoking other devices.
+
+Revocation closes that device's streams and prevents further access. The workspace, accepted work, and schedules remain. [Stop work](/api/workflows/runs#stop-work) or [pause schedules](/api/workflows/schedules) separately.
+
+<Accordion title="Connection endpoints">
+  | Method and path | Access and use |
+  | --- | --- |
+  | `GET /healthz` | No token. Check liveness. |
+  | `POST /daemon/v1/pair` | One-use pairing code. Issue a device token. |
+  | `GET /daemon/v1/discovery` | Paired device. Read identity and configuration state. Host fields require host management. |
+  | `GET /v1/capabilities` | Paired device. Read feature support. |
+  | `GET /v1/confidential/attestation` | Paired device. Read the configured confidential-mode verification response. |
+  | `POST /daemon/v1/pairing-codes` | Host management. Create a code with `manageHost: true` or `false`. |
+  | `GET /daemon/v1/clients` | Host management. List current devices without token values. |
+  | `DELETE /daemon/v1/clients/{clientId}` | Self, or host management for another device. Revoke access. |
+
+  Pairing returns `expiresAt` in Unix milliseconds. Device listings use `expires_at` and `manage_host`. Use the exact field names in each response.
+</Accordion>
+
+After enabling and applying confidential mode, `/v1/confidential/attestation` reports `success`, `unavailable`, or `error`. `unavailable` can mean the mode is off or no key is active.
+
+Cloud sign-in, developer-token management, managed app catalogs, and public sharing are unavailable on a daemon. Use [custom MCP connections](/api/workflows/connections) and its own [host settings](/api/daemon/settings).
diff --git a/content/docs/api/daemon/settings.mdx b/content/docs/api/daemon/settings.mdx
new file mode 100644
index 0000000..387c7e3
--- /dev/null
+++ b/content/docs/api/daemon/settings.mdx
@@ -0,0 +1,75 @@
+---
+title: Host settings
+icon: settings-2
+description: Change a daemon's model provider, sandbox resources, and shared folders safely.
+---
+
+These operations require a device paired with `--manage-host`. Ordinary pairing already permits workspace work. Host management adds authority over this machine's configuration and connected devices.
+
+Prefer [Workspace settings in Fluso](/workspaces/manage) for interactive setup. Use this API when your client needs to manage the same settings.
+
+## Read, save, then apply
+
+Saving settings does not apply them to the running sandbox.
+
+1. Read `GET /daemon/v1/settings` and `GET /daemon/v1/sandbox`.
+2. Keep each response's `revision`.
+3. Save the change with that resource's `expectedRevision`.
+4. Keep the new revisions returned by the saves.
+5. Apply both revisions with `POST /daemon/v1/apply`.
+6. Read discovery and runtime status to check the outcome.
+
+For example, change the model while keeping the existing provider and key:
+
+```json
+{
+  "expectedRevision": "SETTINGS_REVISION_FROM_READ",
+  "settings": {
+    "FLUSO_MODEL": "MODEL_ID_SUPPORTED_BY_YOUR_PROVIDER"
+  }
+}
+```
+
+Send that body to `PATCH /daemon/v1/settings`. Omitted fields remain unchanged. `null` clears a field. Returned `secrets` are presence flags, not key values.
+
+Apply the saved revisions with:
+
+```json
+{
+  "settingsRevision": "SETTINGS_REVISION_FROM_SAVE",
+  "sandboxRevision": "SANDBOX_REVISION_FROM_READ",
+  "interrupt": false
+}
+```
+
+A 409 `INTERRUPTION_REQUIRED` means active work would be interrupted. Ask the owner before repeating with `interrupt: true`.
+
+## Change the provider or sandbox
+
+For an OpenAI-compatible endpoint, set `FLUSO_PROVIDER: "custom"`, `OPENAI_BASE_URL`, `FLUSO_MODEL`, and `OPENAI_API_KEY`. Include `/v1` in the base URL when the provider requires it. Other provider choices are `openrouter`, `openai`, and `pcci`.
+
+A saved key stays tied to its endpoint. Enter a key again when changing that destination. Audio has separate provider and key settings. The [daemon's schema](/api#find-the-exact-fields) lists every supported setting.
+
+Sandbox changes use `PUT /daemon/v1/sandbox` with `expectedRevision` and the complete `config`. Preserve all intended `hostFiles` grants. An empty list removes shared-folder access.
+
+Host paths refer to the daemon's machine, even when you connect remotely. Grant only the required folders. Writable grants permit changing or deleting the original host files. Workspace `/v1/files` paths do not grant access to arbitrary host paths.
+
+<Accordion title="Management endpoints and recovery">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /daemon/v1/settings` | Read saved provider settings and their revision. |
+  | `PATCH /daemon/v1/settings` | Save changed fields. `preview: true` validates without saving. |
+  | `GET /daemon/v1/sandbox` | Read configuration, revision, host RAM, and disk budgets. |
+  | `PUT /daemon/v1/sandbox` | Replace the sandbox configuration with revision protection. |
+  | `POST /daemon/v1/apply` | Apply the saved settings and sandbox revisions. |
+
+  Sandbox `config` contains `runtimeProfile`, `hostFiles`, `memoryGiB`, and `diskGiB`. RAM is the VM allocation. Disk is the combined saved-work and temporary-work budget. It excludes images, backups, and shared host folders. Existing workspace data must fit a smaller budget before you apply it.
+
+  On 409 `CONFIGURATION_CONFLICT`, reload both resources and review the newer changes. Do not substitute a fresh revision without reviewing them.
+
+  During an update or apply, workspace routes can return 503 with `Retry-After`. Discovery shows `applying` or `configuration_error` where applicable. Resolve a configuration error before resubmitting work. A 423 locked credential store requires recovery on the host.
+
+  Discovery exposes saved and applied revisions and `restartRequired` to host-authorized clients. After a lost apply response, read those values before another apply.
+</Accordion>
+
+Binary updates, backups, and credential-store recovery use the [daemon CLI](/workspaces/manage). The settings API does not replace those operations.
diff --git a/content/docs/api/first-request.mdx b/content/docs/api/first-request.mdx
new file mode 100644
index 0000000..442489d
--- /dev/null
+++ b/content/docs/api/first-request.mdx
@@ -0,0 +1,94 @@
+---
+title: Your first request
+icon: terminal
+description: Send a message, get an answer, and keep the conversation open for follow-ups.
+---
+
+This example asks Fluso to explain three ways to check a source. You get a complete answer and a conversation you can continue.
+
+## 1. Get access
+
+For Cloud, create a [developer token](/api/cloud/tokens) with **Read and write** access. For Fluso Local, [pair a client](/api/daemon/pairing) after configuring its model provider.
+
+Open your workspace's [API reference](/api#find-the-exact-fields) to check availability in that release.
+
+Start a Bash shell in a new, empty directory. You need cURL 7.87 or later, `jq`, and `uuidgen`.
+
+Set the URL for your workspace:
+
+```bash
+export FLUSO_API_URL='https://api.fluso.ai/v1'
+```
+
+For Fluso Dev, use `https://api.dev.khichdi.cc/v1`. For a local daemon, use `http://127.0.0.1:4111/v1`. The token must belong to that workspace.
+
+Read your token without showing it or saving it in shell history:
+
+```bash
+read -r -s -p 'Fluso token: ' FLUSO_API_TOKEN
+echo
+export FLUSO_API_TOKEN
+```
+
+## 2. Get an answer
+
+Download the example from that workspace:
+
+```bash
+curl --fail --silent --show-error \
+  "$FLUSO_API_URL/examples/quickstart.sh" -o quickstart.sh &&
+cat quickstart.sh
+```
+
+Read the script, then run it in the same Bash shell:
+
+```bash
+source quickstart.sh
+```
+
+It prints Fluso's answer after reading every result page. If work needs attention, it prints the run's status instead. Stop on an error and use [recovery](/api/workflows/runs) before submitting again.
+
+Keep this shell open. The other guides use the values and functions it provides:
+
+| Name | What it gives you |
+| --- | --- |
+| `thread_id` | The conversation to continue |
+| `run_id` | The work started by your message |
+| `input_key`, `input_body` | The exact request to reuse after a lost response |
+| `api` | An authenticated request to your chosen workspace |
+| `wait_for_run`, `read_run_items` | Wait for completion, then read all saved output |
+
+For example, `api "/threads/$thread_id/state"` reads the conversation's state. `api` adds the base URL and bearer token. It uses ordinary cURL options.
+
+<Note>
+  A timeout does not cancel work. Do not rerun the quickstart to recover: it creates a new request. Read the [saved run](/api/workflows/runs) instead.
+</Note>
+
+## 3. Continue from here
+
+[Send a follow-up](/api/workflows/conversations) to turn the answer into a checklist. You can also [attach a document](/api/workflows/files) or [create a reusable Agent](/api/workflows/agents).
+
+<Accordion title="What the example sends">
+  It sends `POST /v1/threads` with an `input` message and a new `Idempotency-Key`. The response identifies the accepted work:
+
+  ```json
+  {
+    "thread_id": "thread_example",
+    "input_id": "message-1",
+    "run_id": "message-1",
+    "disposition": "running"
+  }
+  ```
+
+  Save the returned IDs. Do not assume `input_id` and `run_id` are equal.
+
+  **202 means accepted.** The example reads `GET /v1/threads/{thread_id}/runs/{run_id}` until completion, then reads the items for that run.
+
+  An idempotency key identifies one submitted message. Save it and the body before sending. Reuse both after a lost response. A new key starts new work.
+</Accordion>
+
+<Accordion title="Finish the example or use it in your application">
+  Save any output you need. Download `$FLUSO_API_URL/examples/cleanup.sh`, read it, then run `source cleanup.sh` in the same shell. It deletes the example conversation and any files created by the file examples.
+
+  The scripts are examples, not an SDK. In your application, store tokens in a secret store and save request IDs durably. Keep credentials out of URLs, source control, logs, and screenshots.
+</Accordion>
diff --git a/content/docs/api/index.mdx b/content/docs/api/index.mdx
new file mode 100644
index 0000000..8d3a848
--- /dev/null
+++ b/content/docs/api/index.mdx
@@ -0,0 +1,57 @@
+---
+title: Fluso API
+icon: code-xml
+description: Give Fluso work from your own script or application, then read the result.
+---
+
+Use the API to send a message, attach a document, or run a saved Agent. Your integration uses the same workspace as the Fluso app.
+
+Start with one conversation. Add schedules, connections, or live updates when your application needs them.
+
+<Card title="Send your first request" icon="arrow-right" href="/api/first-request">
+  Get access, submit a short task, and read the saved answer.
+</Card>
+
+## Choose your workspace
+
+Cloud and Fluso Local share the conversation, Agent, file, and schedule APIs. Their credentials and administration differ. Data stays in the workspace you address.
+
+| | Cloud API | Daemon API |
+| --- | --- | --- |
+| Where work runs | Your Fluso Cloud workspace | Your own machine's Fluso Local workspace |
+| Access for scripts | [Developer token](/api/cloud/tokens) | [Paired device token](/api/daemon/pairing) |
+| Example base URL | `https://api.fluso.ai/v1` | `http://127.0.0.1:4111/v1` |
+| Connected apps | Managed apps and custom MCP servers | Custom MCP servers |
+| Public sharing | Agents, conversations, and files | Unavailable |
+| Machine settings | Managed by the service | [Provider, sandbox, and devices](/api/daemon/settings) |
+
+Fluso Dev uses `https://api.dev.khichdi.cc/v1`. Use credentials from the same environment as the URL.
+
+For a remote daemon, use its HTTPS address or an [SSH tunnel](/workspaces/setup#connect-from-another-mac). A Cloud token cannot access a daemon.
+
+## Find the exact fields
+
+Open **Settings → Developer tokens → API reference** in Cloud. On a daemon's host, open `http://127.0.0.1:4111/docs`.
+
+Releases with this API serve the endpoint reference at `/docs` and the OpenAPI schema at `/v1/openapi.json`. These describe the fields and operations available in that deployment. The reference also supplies runnable examples under `/v1/examples/`. The daemon serves its schema and examples locally. Its interactive reference needs internet access to load the viewer.
+
+The guides below explain how to combine those operations. Endpoint tables sit inside each guide, after the main workflow.
+
+<CardGroup cols={2}>
+  <Card title="Cloud access" icon="cloud" href="/api/cloud/tokens">
+    Create a developer token and choose its access.
+  </Card>
+  <Card title="Daemon access" icon="server" href="/api/daemon/pairing">
+    Pair a client with your own workspace.
+  </Card>
+  <Card title="Send messages" icon="messages-square" href="/api/workflows/conversations">
+    Continue work and read the complete answer.
+  </Card>
+  <Card title="Runs and retries" icon="activity" href="/api/workflows/runs">
+    Handle a timeout without starting the same work twice.
+  </Card>
+</CardGroup>
+
+<Note>
+  If your app lacks **Developer tokens** or its API reference returns 404, contact [support](mailto:support@premai.io) about availability for your release.
+</Note>
diff --git a/content/docs/api/meta.json b/content/docs/api/meta.json
new file mode 100644
index 0000000..894994d
--- /dev/null
+++ b/content/docs/api/meta.json
@@ -0,0 +1,10 @@
+{
+  "pages": [
+    "!index",
+    "[code-xml][Overview](/api)",
+    "first-request",
+    "cloud",
+    "daemon",
+    "workflows"
+  ]
+}
diff --git a/content/docs/api/workflows/agents.mdx b/content/docs/api/workflows/agents.mdx
new file mode 100644
index 0000000..a3ec4ac
--- /dev/null
+++ b/content/docs/api/workflows/agents.mdx
@@ -0,0 +1,125 @@
+---
+title: Use Agents
+icon: bot
+description: Create a meeting assistant, give it work, and improve its saved instructions.
+---
+
+An Agent keeps instructions for work you repeat. This example creates a meeting assistant that turns notes into decisions and open questions.
+
+Use the Bash shell from [your first request](/api/first-request). It provides authenticated requests through `api`.
+
+## Create the assistant
+
+```bash
+agent_key=$(uuidgen) &&
+agent_body='{
+  "name": "Meeting assistant",
+  "instructions": "Turn my notes into a meeting brief. List decisions needed and open questions."
+}' &&
+agent=$(api /agents \
+  -H "Idempotency-Key: $agent_key" \
+  -H 'Content-Type: application/json' -d "$agent_body") &&
+agent_id=$(printf '%s' "$agent" | jq -er '.agent_id')
+```
+
+This saves the Agent without starting a conversation. Keep `agent_id` for later use. If the response is lost, repeat the request with the same `agent_key` and `agent_body`.
+
+## Give it work
+
+Send a message with that Agent's ID:
+
+```bash
+agent_input_key=$(uuidgen) &&
+agent_input_body=$(jq -nc --arg agent_id "$agent_id" \
+  '{agent_id: $agent_id,
+    input: ("Notes: Maya will send the revised budget on Thursday. " +
+            "We still need to choose a launch date. Prepare my meeting brief.")}') &&
+agent_receipt=$(api /threads \
+  -H "Idempotency-Key: $agent_input_key" \
+  -H 'Content-Type: application/json' -d "$agent_input_body") &&
+agent_thread_id=$(printf '%s' "$agent_receipt" | jq -er '.thread_id') &&
+agent_run_id=$(printf '%s' "$agent_receipt" | jq -er '.run_id')
+```
+
+Read the answer with the quickstart's helpers. The parentheses keep your original conversation IDs unchanged:
+
+```bash
+(
+  thread_id=$agent_thread_id
+  run_id=$agent_run_id
+  wait_for_run && read_run_items | jq '.data'
+)
+```
+
+Opening this Agent again returns the same main conversation. Other callers share its history and queue. To open its setup conversation, include `purpose: "manager"` in the thread request.
+
+## Improve its instructions
+
+First read the current setup. Then send your edit with its `current_config_id`:
+
+```bash
+agent=$(api "/agents/$agent_id") &&
+config_id=$(printf '%s' "$agent" | jq -er '.current_config_id') &&
+edit_body=$(jq -nc --arg base "$config_id" \
+  '{base_config_id: $base,
+    instructions: ("Turn my notes into a short meeting brief. " +
+                   "Start with decisions I need to make, then open questions. " +
+                   "Do not invent owners or dates.")}') &&
+api "/agents/$agent_id" -X PATCH \
+  -H 'Content-Type: application/json' -d "$edit_body"
+```
+
+A 409 means another edit arrived first. Read the newer setup and review it before retrying. The main conversation uses saved changes on its next turn. Existing work sessions keep their saved configuration.
+
+Next, [schedule this assistant](/api/workflows/schedules) using `agent_id` and `agent_thread_id`.
+
+<Accordion title="Add skills, connections, or reference files">
+  Use skill names from [skill inventory](/api/workflows/workspace#choose-skills-for-an-agent) and server IDs from [connection inventory](/api/workflows/connections).
+
+  Omitted `skills` or `connectors` stay unchanged during an update. `null` removes the selection restriction. An empty list or map selects none. Connector `allow` still respects account consent.
+
+  Upload knowledge or copy a workspace file through the knowledge endpoints below. Add the returned reference to `knowledge_files` in an update with the current `base_config_id`.
+
+  Uploading alone does not attach knowledge to the Agent. Knowledge is a copy, so later edits to the original file do not change it.
+
+  Each Agent accepts up to 25 knowledge files, each no larger than 20 MiB. Use `knowledge_files: []` to remove the selection.
+</Accordion>
+
+<Accordion title="Reasoning effort and conversation boundaries">
+  Supported effort values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. An input's explicit effort overrides the Agent default. The runtime chooses the nearest supported effort, preferring a higher level before a lower one.
+
+  Steering without an effort keeps the active setting. An explicit change applies at the next execution attempt, without restarting an in-flight model call.
+
+  `run.execution` records the configuration, provider, model, and effort used when execution starts.
+
+  Public clients open main and manager conversations, not Agent work sessions. Omit `agent_id` for independent ordinary conversations.
+
+  Conversations share workspace files. Use distinct output paths for concurrent jobs that must not overwrite each other.
+</Accordion>
+
+<Accordion title="Copy, share, or delete an Agent">
+  Duplication creates independent setup. Retry it with the same idempotency key to recover the original copy.
+
+  [Public sharing](/api/cloud/sharing) is Cloud-only. Its snapshot excludes credentials, conversations, and schedules. After import, read `setup_requirements` and complete setup in the Manager conversation.
+
+  `DELETE /v1/agents/{agent_id}` removes the Agent, its owned conversations, and its schedules. It also revokes the Agent's share link. Save needed results before deletion.
+</Accordion>
+
+<Accordion title="Agent endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/agents` | Search or list Agents. Use numbered pages or `all=true`. |
+  | `POST /v1/agents` | Create saved setup without starting a turn. |
+  | `GET /v1/agents/{agent_id}` | Read setup and `current_config_id`. |
+  | `PATCH /v1/agents/{agent_id}` | Save changes with `base_config_id`. |
+  | `DELETE /v1/agents/{agent_id}` | Delete setup and conversations, retire schedules, and revoke its Agent link. |
+  | `POST /v1/agents/{agent_id}/avatar` | Save appearance. `avatar: null` resets it. |
+  | `POST /v1/agents/{agent_id}/star` | Set `starred` to true or false. |
+  | `POST /v1/agents/{agent_id}/duplicate` | Copy setup and knowledge. Use an idempotency key for retries. |
+  | `POST /v1/agents/{agent_id}/knowledge-files` | Store multipart `file` and return its reference. |
+  | `POST /v1/agents/{agent_id}/knowledge-files/from-workspace` | Copy `path` into knowledge and return its reference. |
+
+  Appearance and starring do not change instructions or configuration bindings. Duplication excludes conversations, schedules, and public links.
+
+  Creation and duplication receipts remain with the saved Agent. Their keys do not use the input receipt's 24-hour window. Older `creation_id` is accepted for creation. Do not supply conflicting identifiers.
+</Accordion>
diff --git a/content/docs/api/workflows/connections.mdx b/content/docs/api/workflows/connections.mdx
new file mode 100644
index 0000000..f344585
--- /dev/null
+++ b/content/docs/api/workflows/connections.mdx
@@ -0,0 +1,114 @@
+---
+title: Connections and approvals
+icon: plug
+description: Connect a service once, then help users decide when Fluso needs permission.
+---
+
+Your integration can use the services already connected to the same Fluso workspace. A connection gives access to tools. The user's permission settings decide which actions can proceed.
+
+For an initial setup, connect the service in **Plugins → MCP** in Fluso. Cloud offers managed apps such as Google Workspace. Fluso Local uses custom MCP servers.
+
+The examples below use `api`, `thread_id`, and `run_id` from [your first request](/api/first-request).
+
+## Handle a waiting run
+
+When a run reports `waiting_action`, read its pending action:
+
+```bash
+state=$(api "/threads/$thread_id/state") &&
+approval_url=$(printf '%s' "$state" | jq -er --arg run "$run_id" \
+  'first(.pending_actions[] | select(.run_id == $run)) | .url') &&
+approval_route=${approval_url#/v1} &&
+approval=$(api "$approval_route") &&
+printf '%s' "$approval" | jq '{kind, status, app_id, server_id, tool_name, arguments, expires_at}'
+```
+
+The action URL already starts with `/v1`. The example removes that prefix because `api` includes it. If there is no matching action, check the run again. It may have resumed or finished.
+
+| Action kind | What to show the user |
+| --- | --- |
+| `mcp_connect` | The service they need to connect. Follow [managed app sign-in](/api/cloud/apps) or custom setup below. |
+| `mcp_tool` | The requested tool and its actual arguments, with a choice to allow or deny. |
+
+For a **pending `mcp_tool` action**, send this only after the user approves the displayed call:
+
+```bash
+api "$approval_route/decision" \
+  -H 'Content-Type: application/json' \
+  -d '{"decision":"allow","scope":"once"}'
+```
+
+Use `decision: "deny"` to refuse it. After either decision, follow the same run. Do not resend its input.
+
+A 409 or 410 means the action needs another read. Do not approve a replacement without reviewing it. A successful decision saves consent, but does not mean the run completed.
+
+## Connect a custom MCP server
+
+MCP is the protocol that lets a service expose tools to Fluso. Start with the service's public HTTPS endpoint.
+
+Probe the endpoint before saving it. Replace the example URL with your service's URL:
+
+```bash
+api /mcp-oauth/probe \
+  -H 'Content-Type: application/json' \
+  -d '{"server_url":"https://your-service.example/mcp"}'
+```
+
+The response identifies its transport and authentication method. Choose the matching connection flow:
+
+| The service uses | Start with |
+| --- | --- |
+| No authentication, bearer token, or API key | `POST /v1/mcp-oauth/connections/static` |
+| OAuth with automatic client registration | `POST /v1/mcp-oauth/sessions` |
+| OAuth with your own client registration | `POST /v1/mcp-oauth/sessions/byo-oauth` |
+
+Open the returned `authorization_url` for OAuth. `already_connected` needs no sign-in. Wait for the session status to become `connected` before treating setup as complete.
+
+<Accordion title="OAuth completion and connection recovery">
+  On Cloud, the callback submits `completion_proof` under the initiating account. On a daemon, `/daemon/v1/oauth/callback` completes it directly. Use the returned authorization URL unchanged.
+
+  Read `GET /v1/mcp-oauth/connections` to inspect saved connections. `needs_reauth` means the user must reconnect. Saved inventory alone does not prove the service is reachable.
+
+  A developer write token can decide one-time tool approvals. Permanent rules require a Cloud app session or a paired daemon device.
+</Accordion>
+
+<Accordion title="Custom connection and tool-discovery endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `POST /v1/mcp-oauth/probe` | Discover transport and authentication. |
+  | `POST /v1/mcp-oauth/connections/static` | Save a key-based or unauthenticated connection. |
+  | `POST /v1/mcp-oauth/sessions` | Start custom OAuth authorization. |
+  | `POST /v1/mcp-oauth/sessions/byo-oauth` | Start OAuth with your client registration. |
+  | `POST /v1/mcp-oauth/sessions/complete` | Cloud only. Save the connection from its completion proof. |
+  | `GET /v1/mcp-oauth/sessions/{session_id}/status` | Read authorization progress. |
+  | `GET /daemon/v1/oauth/callback` | Daemon only. Receive the provider's OAuth callback. |
+  | `GET /v1/mcp-oauth/connections` | List connections without exposing secrets. |
+  | `POST /v1/mcp-oauth/connections/refresh` | Refresh Cloud registrations or daemon tool discovery. |
+  | `DELETE /v1/mcp-oauth/connections/{server_id}` | Disconnect and invalidate its pending authority. |
+  | `GET /v1/mcp-oauth/connections/{server_id}/tools` | Read tool descriptions, input schemas, and read-only classifications. |
+  | `POST /v1/mcp-oauth/connections/{server_id}/tools` | Refresh or repair the connection before tool discovery. |
+
+  Reusing a static connection's `server_id` updates that connection. Its `auth_method` is `bearer`, `api_key`, or `no_auth`. Only the first two accept a token. API keys use `header_name`, which defaults to `X-Api-Key`.
+
+  Tool discovery can return saved tool information with an `error`. A 409 `CONNECTION_CHANGING` includes `Retry-After: 1`. Check the connection again after that delay.
+
+  OAuth `pending` and `processing` are unfinished states. Handle `error`, `expired`, or `superseded` before a new sign-in attempt.
+</Accordion>
+
+<Accordion title="Approval and saved-permission endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/mcp-oauth/permissions/approvals/{approval_id}` | Read the action, status, and expiry. |
+  | `POST /v1/mcp-oauth/permissions/approvals/{approval_id}/decision` | Allow or deny a tool request. |
+  | `POST /v1/mcp-oauth/permissions/approvals/{approval_id}/cancel` | Dismiss the pending action without granting access. |
+  | `GET /v1/mcp-oauth/permissions/mode` | Read a thread's `auto_approve` setting and `version`. Supply `thread_id`. |
+  | `PUT /v1/mcp-oauth/permissions/mode` | Change it with `expected_version` and the same `thread_id`. |
+  | `GET /v1/mcp-oauth/permissions/default` | Read the account default. |
+  | `PUT /v1/mcp-oauth/permissions/default` | Change the default with `expected_version`. |
+  | `GET /v1/mcp-oauth/connections/{server_id}/permissions` | Read saved and effective tool policies. |
+  | `PUT /v1/mcp-oauth/connections/{server_id}/permissions` | Change persistent connection or tool policies. |
+
+  Cloud developer tokens cannot use these PUT routes or decision `scope: "always"`. Use a signed-in app session for permanent changes. Paired daemon devices can make these changes.
+
+  A stale permission version returns 409. Enabling thread auto-approval can resolve an eligible pending request. An explicitly denied tool remains denied. Changing the account default does not decide an existing pending approval.
+</Accordion>
diff --git a/content/docs/api/workflows/conversations.mdx b/content/docs/api/workflows/conversations.mdx
new file mode 100644
index 0000000..5816cdb
--- /dev/null
+++ b/content/docs/api/workflows/conversations.mdx
@@ -0,0 +1,95 @@
+---
+title: Send messages
+icon: messages-square
+description: Continue a conversation and read its complete answer.
+---
+
+Turn the answer from [your first request](/api/first-request) into a checklist. Use the same Bash shell, which already has your token, `api` helper, and conversation IDs.
+
+A **thread** is the conversation. Each message you submit is an **input**. A **run** tracks the work that follows.
+
+## Send a follow-up
+
+Save a new key and message, then send them to the existing conversation:
+
+```bash
+input_key=$(uuidgen) &&
+input_body='{
+  "input": "Turn those checks into a three-item checklist.",
+  "mode": "queue"
+}' &&
+receipt=$(api "/threads/$thread_id/inputs" \
+  -H "Idempotency-Key: $input_key" \
+  -H 'Content-Type: application/json' -d "$input_body") &&
+run_id=$(printf '%s' "$receipt" | jq -er '.run_id')
+```
+
+The receipt identifies this new run. If the conversation is busy, `queue` waits for the current work to finish. Use `steer` to guide active work instead.
+
+Keep `input_key` and `input_body` if the response is lost. [Retry those same values](/api/workflows/runs), without generating another key.
+
+## Read the answer
+
+The quickstart's helpers wait for the run and read every output page:
+
+```bash
+wait_for_run &&
+items=$(read_run_items) &&
+printf '%s' "$items" | jq '.data[] | select(.type == "message" and .role == "assistant")'
+```
+
+You receive the saved assistant messages, including any attachments. A message can contain a file without text. Use each attachment's returned path to [download its content](/api/workflows/files).
+
+If the run needs approval or fails, `wait_for_run` stops and prints its status. Follow [Runs and retries](/api/workflows/runs) before sending more work.
+
+## Start a separate conversation
+
+Send `POST /v1/threads` with an `input` and a new key, as the quickstart does. Omit `input` and `attachments` to open an empty conversation.
+
+Include `agent_id` to use a [saved Agent](/api/workflows/agents). Its main conversation is reused. Add `purpose: "manager"` to open that Agent's setup conversation.
+
+## Read message history
+
+For your own client, use `GET /v1/threads/{thread_id}/items?run_id={run_id}`. Omit `run_id` to read the whole conversation.
+
+Entries are in `data`. Pass `next_cursor` as `after`, with the unchanged `revision`, until `next_cursor` is null. Keep filters unchanged. The `read_run_items` helper performs these steps for you.
+
+An empty page does not prove completion. Check the [run status](/api/workflows/runs). To display progress while waiting, add [live updates](/api/workflows/streaming).
+
+<Accordion title="Handle a changing conversation or queued message">
+  Edits or deletions can invalidate an item snapshot. On a pagination conflict, discard the partial read and restart without `after` or `revision`. New messages alone do not invalidate it.
+
+  Read thread state before editing queued work. Active or completed inputs cannot be edited as queued messages.
+
+  A queued edit needs its own new `Idempotency-Key`. Keep that edit key on retries. If the input started meanwhile, keep the user's draft when the API returns 409.
+
+  Stopping a thread holds follow-up inputs. Review state before resuming a held input.
+</Accordion>
+
+<Accordion title="Delete a conversation">
+  `DELETE /v1/threads/{thread_id}` stops and deletes an ordinary conversation. Save needed results first. Agent main and manager conversations require deleting their Agent instead.
+
+  Conversation deletion does not remove a separately published chat snapshot or all workspace files.
+</Accordion>
+
+<Accordion title="Conversation endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/threads` | List by Agent, project, or purpose. Follow numbered `pagination.page` and `pages`. |
+  | `POST /v1/threads` | Create an ordinary chat or open an Agent's main or manager conversation. |
+  | `GET /v1/threads/{thread_id}` | Read details and configuration binding. |
+  | `PATCH /v1/threads/{thread_id}` | Change title, archive, pin, labels, or application metadata. |
+  | `DELETE /v1/threads/{thread_id}` | Stop and remove an ordinary conversation. |
+  | `POST /v1/threads/{thread_id}/inputs` | Submit new work or steer active work. |
+  | `PATCH /v1/threads/{thread_id}/inputs/{input_id}` | Replace queued content with an edit key. |
+  | `DELETE /v1/threads/{thread_id}/inputs/{input_id}` | Cancel that queued input. |
+  | `POST /v1/threads/{thread_id}/inputs/{input_id}/resume` | Resume a held input. |
+  | `GET /v1/threads/{thread_id}/items` | Read saved items with snapshot pagination. |
+  | `GET /v1/threads/{thread_id}/state` | Read active work, queues, partial output, and pending actions. |
+  | `GET /v1/threads/{thread_id}/preview` | Read the latest short message preview. |
+  | `GET /v1/threads/{thread_id}/files` | List files associated with this conversation. |
+  | `POST /v1/threads/{thread_id}/read` | Update unread tracking. Does not approve tools. |
+  | `PATCH /v1/threads/{thread_id}/reorder` | Set position within its current project. Cross-project moves are rejected. |
+
+  Agent binding and provenance belong to the server. Custom metadata cannot change them. See [live events](/api/workflows/streaming) and [cancellation](/api/workflows/runs#stop-work) for execution controls.
+</Accordion>
diff --git a/content/docs/api/workflows/files.mdx b/content/docs/api/workflows/files.mdx
new file mode 100644
index 0000000..507084e
--- /dev/null
+++ b/content/docs/api/workflows/files.mdx
@@ -0,0 +1,162 @@
+---
+title: Work with files
+icon: folder-kanban
+description: Attach a report, get a summary file, and edit saved content without losing another change.
+---
+
+Give Fluso a short report and get a summary file back. This example covers upload, attachment, execution, and download.
+
+Use the Bash shell from [your first request](/api/first-request), plus Node 22 or later. Keep the example in its own directory.
+
+## Upload a report and get a summary
+
+Download the two examples from your workspace:
+
+```bash
+curl --fail --silent --show-error \
+  "$FLUSO_API_URL/examples/upload.mjs" -o upload.mjs &&
+curl --fail --silent --show-error \
+  "$FLUSO_API_URL/examples/attach.sh" -o attach.sh
+```
+
+Read both files before running them. The example writes `report.txt` and `summary.md` locally, so use a directory where those names are unused.
+
+```bash
+source attach.sh
+```
+
+It uploads a sample report, sends it to your conversation, waits for completion, and downloads the returned attachment as `summary.md`.
+
+Keep `input_path` for the uploaded report and `output_path` for the summary in your workspace. Use returned paths for future requests. Do not guess them from the prompt.
+
+If the example stops on an error, retain its upload key and receipt. Use the recovery details below before repeating a transfer.
+
+## Download an attachment
+
+A saved message can contain attachments without text. Read all items for its run, then use each attachment's path:
+
+```bash
+api /files/download --get \
+  --data-urlencode "path=$output_path" --output downloaded-summary.md
+```
+
+Choose a local output name you can replace. `available: false` on an attachment means its file is no longer at that path.
+
+## Edit without losing another change
+
+Read the report and its current revision:
+
+```bash
+saved=$(api /files/read --get --data-urlencode "path=$input_path") &&
+printf '%s' "$saved" | jq '{content, revision}'
+```
+
+A revision identifies the content you read. Include it when saving your edit:
+
+```bash
+edit_body=$(printf '%s' "$saved" | jq --arg path "$input_path" \
+  '{path: $path, revision, content: (.content + "\nReviewed by me.\n")}') &&
+api /files/text -X PUT \
+  -H 'Content-Type: application/json' -d "$edit_body"
+```
+
+If another writer changed the file, the save fails with 409. Read the new content and merge your edit. Keep the revision check.
+
+For a new file, use `overwrite: false`. Add `recursive: true` when its parent directories do not exist. Text writes allow 1 MiB of UTF-8 content. Reads default to 5 MiB.
+
+## Projects
+
+Use `GET /v1/projects` to choose a project and `GET /v1/files` to browse its files. Project IDs are storage names. Keep their exact returned values when building paths.
+
+Deleting a project removes its conversations and files, then retires their schedules. Save or export needed results first.
+
+<Accordion title="Implement uploads in your own client">
+  1. Send `POST /v1/uploads` with the filename, MIME type, byte size, and a saved `Idempotency-Key`.
+  2. POST the bytes to `upload_url` as multipart data, with returned `upload_fields` unchanged and the file last.
+  3. Send `POST /v1/uploads/confirm` with `{"id":"UPLOAD_ID"}`.
+  4. Read `GET /v1/uploads/{upload_id}` until it finishes.
+  5. Attach the returned `target_path` to your next input.
+
+  Do not send your Fluso bearer token to `upload_url`. The downloadable example uses text files. Supply the correct MIME type for other files, such as PDFs.
+
+  `confirmed` means the file is ready. `history_unavailable` means it was saved without a new recorded version. Show that warning. For `failed`, `cancelled`, or `conflict`, inspect the saved error before another transfer.
+
+  A timeout does not prove import failure. Read the existing upload. A confirmed receipt also does not promise that later edits left its bytes unchanged.
+</Accordion>
+
+<Accordion title="History, restoration, and comments">
+  Versions and comments apply under `/files/` and `/projects/{project_id}/files/`, excluding hidden directories.
+
+  Read `/v1/files/versions` before restoring a file. Download a version through `/v1/files/versions/content` with its `path` and `commit`. A missing version returns 404, never the current bytes.
+
+  Restore preserves the replaced bytes as a version first. If preservation fails, review the warning before permitting `allow_history_loss: true`. Other files remain unchanged.
+
+  The same history protection applies to writes, uploads, copies, and moves. Directory copies can partly succeed. Inspect the destination before retrying.
+
+  File comments can refer to a passage, slide, sheet range, or image region. A comment does not start an Agent run.
+</Accordion>
+
+<Accordion title="Project endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/projects` | List projects. Follow `next_cursor` as `after`. |
+  | `POST /v1/projects` | Create a project. Its name becomes its ID. |
+  | `GET /v1/projects/{project_id}` | Read details and conversation counts. |
+  | `PATCH /v1/projects/{project_id}` | Change description, icon, labels, archive, or pin settings. Does not rename it. |
+  | `DELETE /v1/projects/{project_id}` | Delete its conversations and files, then retire schedules. |
+  | `GET /v1/projects/{project_id}/export` | Stream an export download, not JSON. |
+  | `GET /v1/projects/{project_id}/search` | Search project files with `q`. |
+  | `GET /v1/projects/{project_id}/files/origins` | Read recorded file provenance. Missing entries mean unknown origin. |
+  | `PATCH /v1/projects/{project_id}/files/pins` | Add or remove relative paths such as `files/report.pdf`. |
+
+  Names use 1 to 64 ASCII letters, digits, single spaces, hyphens, or underscores, starting with a letter or digit. URL-encode names in paths.
+
+  Deleting Home also removes its work. An empty Home is recreated on first use. Retry a failed deletion to finish schedule cleanup. If you reuse the project name, deletion addresses the new project.
+</Accordion>
+
+<Accordion title="Upload endpoints and recovery">
+  | Method and path | Use |
+  | --- | --- |
+  | `POST /v1/uploads` | Prepare transfer with `file_name`, `mime_type`, and byte `file_size`. |
+  | `POST /v1/uploads/confirm` | Confirm transfer with `id`. Repeating confirmation is safe. |
+  | `GET /v1/uploads/{upload_id}` | Read import progress and the final `target_path`. |
+  | `GET /v1/uploads` | List receipts, following `next_cursor` as `after`. |
+  | `DELETE /v1/uploads/{file_id}` | Cancel a pending transfer or dismiss a saved-file history warning. |
+
+  Save an `Idempotency-Key` when preparing a transfer. Retrying the same settings returns its receipt. Changed settings return 409. At most four uploads can be pending.
+
+  A retry after transfer credentials expire can return a receipt without `upload_url`. Read or confirm that upload before starting another. A processing or completed receipt needs no repeat transfer.
+
+  Confirmation can return 200 while import is still processing. Poll until a final status. Receipts remain for seven days after completion. Receipt expiry does not delete the saved file.
+
+  Cancelling a pending upload removes temporary bytes. Dismissing `history_unavailable` keeps the saved file. This endpoint does not delete workspace content.
+</Accordion>
+
+<Accordion title="File, history, and comment endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/files` | Browse a directory, optionally recursively. Keep filters while following `next_cursor`. |
+  | `GET /v1/files/stat` | Read metadata for a workspace `path`. |
+  | `GET /v1/files/read` | Read UTF-8 content and its revision. |
+  | `GET /v1/files/download` | Stream raw bytes and download headers. |
+  | `PUT /v1/files/text` | Write text, optionally with a revision or `overwrite: false`. |
+  | `POST /v1/files/edit` | Replace matching text. `replace_all: true` changes every occurrence. |
+  | `POST /v1/files/directories` | Create a directory. `recursive: true` creates missing parents. |
+  | `POST /v1/files/move` | Move or rename. Existing destinations require explicit overwrite. |
+  | `POST /v1/files/copy` | Copy. Directory copies require `recursive: true`. |
+  | `DELETE /v1/files` | Supply `path` in the query. Nonempty directories also need `recursive=true`. |
+  | `POST /v1/files/batch-delete` | Delete selected paths and report each result. |
+  | `GET /v1/files/versions` | List history and the current file fingerprint. |
+  | `PATCH /v1/files/versions` | Rename a recorded version. |
+  | `GET /v1/files/versions/{commit}` | Read version metadata without its bytes. |
+  | `GET /v1/files/versions/content` | Download the selected version's exact bytes. |
+  | `POST /v1/files/versions/restore` | Restore one file, preserving the replaced version first. |
+  | `GET /v1/files/comments` | Read file comments across conversations. |
+  | `POST /v1/files/comments` | Add a note with a passage or object anchor. |
+  | `PATCH /v1/files/comments` | Edit a note, anchor, or status. |
+  | `DELETE /v1/files/comments` | Remove a comment by ID. |
+
+  Script-created files may have no history until delivered. `versionable: false` means an overwrite cannot preserve the current bytes. Do not treat version history as a complete workspace backup.
+
+  File deletion revokes public links before removing content. If deletion fails, links remain revoked. Retry deletion to remove the remaining content.
+</Accordion>
diff --git a/content/docs/api/workflows/meta.json b/content/docs/api/workflows/meta.json
new file mode 100644
index 0000000..1201821
--- /dev/null
+++ b/content/docs/api/workflows/meta.json
@@ -0,0 +1,16 @@
+{
+  "title": "Use the API",
+  "icon": "workflow",
+  "defaultOpen": false,
+  "pages": [
+    "conversations",
+    "runs",
+    "streaming",
+    "agents",
+    "files",
+    "connections",
+    "schedules",
+    "workspace",
+    "usage"
+  ]
+}
diff --git a/content/docs/api/workflows/runs.mdx b/content/docs/api/workflows/runs.mdx
new file mode 100644
index 0000000..43b619b
--- /dev/null
+++ b/content/docs/api/workflows/runs.mdx
@@ -0,0 +1,109 @@
+---
+title: Runs and retries
+icon: activity
+description: Find out what happened, recover a result, or stop work without submitting it twice.
+---
+
+A request timed out, or the connection closed before the answer arrived. Start by checking the work Fluso already accepted.
+
+Use the Bash shell from [your first request](/api/first-request). It contains the `api` helper and saved IDs.
+
+## Check the run
+
+```bash
+api "/threads/$thread_id/runs/$run_id" | jq '{status, error}'
+```
+
+| Status | Your next step |
+| --- | --- |
+| `queued` or `running` | Wait, then check again. |
+| `waiting_action` | Read thread state and [handle the pending action](/api/workflows/connections#handle-a-waiting-run). |
+| `held` | Review the queue in thread state before resuming an input. |
+| `completed` | [Read every result page](/api/workflows/conversations#read-message-history). |
+| `failed` or `cancelled` | Read the error and partial results before deciding what to do next. |
+
+A completed run can contain a failed tool call. A failed run can still have changed an external service. Check the answer and tool results before repeating work.
+
+## Recover after a timeout
+
+| What you have | What to do |
+| --- | --- |
+| A receipt with `thread_id` and `run_id` | Read that run and its saved output. |
+| A saved key and body, but no receipt | Repeat the original submission with both unchanged. |
+| A disconnected stream | Reconnect for new events, then read saved state and items. |
+
+For a lost [follow-up response](/api/workflows/conversations#send-a-follow-up), resend the saved request:
+
+```bash
+receipt=$(api "/threads/$thread_id/inputs" \
+  -H "Idempotency-Key: $input_key" \
+  -H 'Content-Type: application/json' -d "$input_body") &&
+run_id=$(printf '%s' "$receipt" | jq -er '.run_id')
+```
+
+Do not generate another key for this retry. A new key can start duplicate work. For the quickstart's initial submission, retry `/threads` instead of `/threads/$thread_id/inputs`.
+
+Input receipts remain until 24 hours after completion. After that, inspect the saved run before submitting again. Saved runs remain readable until their conversation is deleted.
+
+<Accordion title="Thread created, but the first input failed">
+  An error from `POST /v1/threads` can include `error.details.thread_id`. Keep that ID and inspect its state. Thread creation alone does not prove that Fluso accepted the input.
+
+  After resolving the error, send the original input and key to that thread's `/inputs` endpoint. This can recover an uncertain acceptance within the retry window.
+</Accordion>
+
+## Stop work
+
+To cancel only the saved run:
+
+```bash
+api "/threads/$thread_id/runs/$run_id/cancel" -X POST
+```
+
+Then check its status until execution stops. Cancellation cannot undo an external action that already completed.
+
+To stop the conversation and hold its follow-up messages, use `POST /v1/threads/{thread_id}/stop` instead. Review the queue before resuming held inputs.
+
+## Decide whether to retry
+
+For temporary read failures, wait before retrying. Increase the delay between attempts, set a maximum wait, and honor `Retry-After`. Stop when `error.retryable` is explicitly false. The quickstart's read helpers already do this.
+
+For writes, use the operation's own recovery rule. Inputs use saved keys and bodies. Uploads use their receipts. Schedules use their IDs. Configuration edits use revisions.
+
+A failed run stays failed when you resend its old key. Review partial results before choosing a new message and key.
+
+<Accordion title="Errors and request identity">
+  | Response | Action |
+  | --- | --- |
+  | 400 or 422 | Correct the request fields. |
+  | 401 | Replace the credential or sign in again. |
+  | 402 | Check the account allowance and any `resets_at` value. |
+  | 403 | Use the required access level or signed-in app session. |
+  | 404 | Check the workspace and resource ID. The resource may no longer exist. |
+  | 409 | Read the resource before resolving the conflict. Keep unsent edits. |
+  | 410 | Follow the error's instructions for the expired resource or approval. |
+  | 413 or 507 | Reduce the transfer or free workspace storage. |
+  | 408, 429, 500, 502, 503, or 504 | Retry transient reads with a delay. Preserve keys for uncertain writes. |
+
+  Errors include `error.code` and `error.message`, with details and retry guidance where available. Keep `request_id` or `X-Request-ID` for support. A request ID is not an idempotency key.
+
+  Use UUIDs for new input keys. Accepted characters are ASCII letters, digits, `_`, `-`, `.`, `:`, and `@`, with a maximum of 128 characters. A single dot, consecutive dots, and the `agent-turn:` and `agent-result:` prefixes are reserved.
+
+  For historical run IDs containing `/`, use `GET /v1/runs` with URL-encoded `thread_id` and `run_id` query parameters. Read output through the items endpoint's `run_id` filter.
+</Accordion>
+
+<Accordion title="Run endpoints and admission limits">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/runs` | List saved runs or find one through query filters. |
+  | `GET /v1/threads/{thread_id}/runs` | List a conversation's runs. Follow `next_cursor` as `after`. |
+  | `GET /v1/threads/{thread_id}/runs/{run_id}` | Read status, error, and recorded execution settings. |
+  | `GET /v1/threads/{thread_id}/runs/{run_id}/usage` | Read recorded usage or `null` when unreported. |
+  | `POST /v1/threads/{thread_id}/runs/{run_id}/cancel` | Request cancellation of this run. |
+  | `POST /v1/threads/{thread_id}/stop` | Stop active work and hold follow-ups. |
+
+  An input accepts up to 200,000 text characters and 25 attachments. A thread holds up to 100 queued inputs and 50 steering inputs per active turn.
+
+  Each thread retains up to 1,000 recent input receipts. At capacity, admission refuses new work while preserving existing retry receipts. Waiting for a local timeout does not clear accepted work.
+
+  Merge `state.runs` by ID when reading multiple item pages. An old item without a saved run has an unknown outcome. Its text alone does not prove success.
+</Accordion>
diff --git a/content/docs/api/workflows/schedules.mdx b/content/docs/api/workflows/schedules.mdx
new file mode 100644
index 0000000..c72dfdc
--- /dev/null
+++ b/content/docs/api/workflows/schedules.mdx
@@ -0,0 +1,77 @@
+---
+title: Schedule work
+icon: calendar-clock
+description: Ask an Agent to review its notes every weekday, then inspect or pause the schedule.
+---
+
+A schedule sends a message to an Agent at a chosen time. In the app, schedules are called **routines**.
+
+First [create the meeting assistant](/api/workflows/agents) and give it some notes. Keep that example's `agent_id` and `agent_thread_id` in the same Bash shell.
+
+## Create a weekday review
+
+This schedule asks the assistant to review its conversation every weekday at 9 AM in Zurich. Change the message and timezone for your work.
+
+```bash
+schedule_id=$(uuidgen) &&
+schedule_body=$(jq -nc --arg id "$schedule_id" --arg thread "$agent_thread_id" \
+  '{id: $id, thread_id: $thread,
+    message: ("Review the meeting notes in this conversation. " +
+              "Summarize decisions still open and actions due next."),
+    cron: "0 9 * * 1-5", timezone: "Europe/Zurich"}') &&
+api "/agents/$agent_id/schedules" \
+  -H 'Content-Type: application/json' -d "$schedule_body"
+```
+
+The response includes `next_run_at`. Check that time before leaving the schedule active. Keep `schedule_id` and `schedule_body` for retries. A new ID creates another schedule.
+
+For a one-time task, replace `cron` with `at`, using a future timestamp with a UTC offset. For example, the format is `2030-01-02T09:00:00+01:00`.
+
+## Review and change future work
+
+Read this Agent's schedules:
+
+```bash
+api "/agents/$agent_id/schedules" | jq '.data'
+```
+
+Look at `last_run.status` for the previous result. Use its `run_id` and the schedule's `thread_id` to [read the output](/api/workflows/conversations#read-message-history).
+
+Pause future submissions when you no longer need them:
+
+```bash
+api "/schedules/$schedule_id" -X PATCH \
+  -H 'Content-Type: application/json' -d '{"status":"paused"}'
+```
+
+Check the schedule list after saving. Use `status: "active"` to resume, or `DELETE /v1/schedules/{schedule_id}` to remove it.
+
+Pausing or deleting a schedule does not cancel work already accepted. [Cancel that run separately](/api/workflows/runs#stop-work).
+
+<Accordion title="Change the message or timing">
+  Send changed fields with `PATCH /v1/schedules/{schedule_id}`. Omitted fields stay unchanged. Do not send `null` to clear fields.
+
+  To switch between recurring and one-time timing, send only the new `cron` or `at` field. It replaces the previous timing.
+
+  Use an IANA timezone such as `Europe/Zurich`. At daylight-saving changes, skipped local times move forward by the gap. Repeated times run at their first occurrence.
+</Accordion>
+
+<Accordion title="Understand late, failed, and one-time runs">
+  The daemon host must be awake for work to run. After downtime, missed recurring runs combine into one catch-up run.
+
+  Delivery failures can pause a schedule. A failed accepted run does not automatically pause recurring work.
+
+  A one-time schedule stops submitting after acceptance, even if its run later fails. Inspect the saved run before deciding whether to request that work again.
+</Accordion>
+
+<Accordion title="Schedule endpoint reference">
+  | Method and path | Use |
+  | --- | --- |
+  | `POST /v1/agents/{agent_id}/schedules` | Create with a caller-generated UUID and exactly one of `cron` or `at`. |
+  | `GET /v1/agents/{agent_id}/schedules` | List schedules for one Agent. |
+  | `GET /v1/schedules` | List all schedules. Use `attention=true` for delivery problems. |
+  | `PATCH /v1/schedules/{schedule_id}` | Edit, pause, or resume. |
+  | `DELETE /v1/schedules/{schedule_id}` | Prevent future submissions. |
+
+  Follow numbered `pagination.page` and `pages` in list responses. The target conversation must belong to the Agent.
+</Accordion>
diff --git a/content/docs/api/workflows/streaming.mdx b/content/docs/api/workflows/streaming.mdx
new file mode 100644
index 0000000..1b340fb
--- /dev/null
+++ b/content/docs/api/workflows/streaming.mdx
@@ -0,0 +1,72 @@
+---
+title: Live updates
+icon: radio
+description: Show progress as Fluso works, and recover the answer after a dropped connection.
+---
+
+Add live updates when your interface needs to show progress before the answer is ready. Keep saved results as the source for the completed conversation.
+
+## Try the watcher
+
+Use the [quickstart's shell](/api/first-request) and Node 22 or later. Download the watcher from your workspace:
+
+```bash
+curl --fail --silent --show-error \
+  "$FLUSO_API_URL/examples/watch.mjs" -o watch.mjs &&
+cat watch.mjs
+```
+
+After reading it, watch the saved run:
+
+```bash
+node watch.mjs "$thread_id" "$run_id"
+```
+
+The watcher prints saved conversation updates. It reads every page and reconnects after temporary failures without resubmitting input. Press **Ctrl+C** to stop watching. That does not cancel the run.
+
+## Connect without missing saved work
+
+Your client needs two sources:
+
+| Source | Use it for |
+| --- | --- |
+| Event stream | Show text and tool progress as it arrives. |
+| Saved state and items | Recover missed updates and read the final answer. |
+
+Open the stream first, then read state and every item page. Match updates by input, run, and item IDs. Replace temporary text with its saved item to avoid duplicates.
+
+After a disconnection, repeat that sequence. Continue checking saved state periodically while work is active. `Last-Event-ID` does not replay missed events.
+
+<Accordion title="Open the event stream directly">
+  ```bash
+  curl --no-buffer --fail-with-body --silent --show-error \
+    "$FLUSO_API_URL/threads/$thread_id/events" \
+    -H "Authorization: Bearer $FLUSO_API_TOKEN"
+  ```
+
+  The response uses Server-Sent Events (SSE). Each `data` field contains a `ThreadEvent` JSON object. A blank line ends a frame.
+
+  Buffer incomplete frames across network chunks. Ignore unknown event types and keepalive comments. Use a client that supports an Authorization header. Keep tokens out of URLs.
+
+  If you use `stream: true` during input submission, save the first `input.accepted` receipt. It contains the IDs for recovery if the stream fails.
+
+  For a daemon behind a proxy, disable response buffering for this stream.
+</Accordion>
+
+<Accordion title="Render tool progress accurately">
+  `progress.tool_start` and `progress.tool_end` describe tool execution. Your client displays these events. It does not execute the tool itself.
+
+  A preview can omit arguments or results. `args_truncated: true` means the arguments are incomplete. If that flag is absent, completeness is unknown.
+
+  For [tool approval](/api/workflows/connections#handle-a-waiting-run), fetch the pending action's actual arguments before asking the user to decide.
+</Accordion>
+
+<Accordion title="Live-update endpoint reference">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/threads/{thread_id}/events` | Stream new events. Optional `input_id` follows one input. |
+  | `GET /v1/threads/{thread_id}/state` | Recover active work, queues, partial output, and pending actions. |
+  | `GET /v1/threads/{thread_id}/items` | Recover saved messages and tool results. Follow every page. |
+
+  The watcher's run ID is optional. Supply it to check the run even when it has no saved messages. A closed stream does not establish whether work finished.
+</Accordion>
diff --git a/content/docs/api/workflows/usage.mdx b/content/docs/api/workflows/usage.mdx
new file mode 100644
index 0000000..794829f
--- /dev/null
+++ b/content/docs/api/workflows/usage.mdx
@@ -0,0 +1,45 @@
+---
+title: Check usage
+icon: chart-no-axes-combined
+description: See what a run used, then inspect the model calls behind it.
+---
+
+Use the saved conversation and run IDs to inspect the cost of a task. The examples use the Bash shell from [your first request](/api/first-request).
+
+## Check one run
+
+```bash
+api "/threads/$thread_id/runs/$run_id/usage" | jq .
+```
+
+The response contains `tokens`, estimated `cost`, and `entry_count`. A response of `null` means no usage was reported yet. A null `cost` means pricing is unknown, not zero.
+
+## See which calls contributed
+
+Filter individual usage records to that run:
+
+```bash
+api /token-usage/entries --get \
+  --data-urlencode "thread_id=$thread_id" \
+  --data-urlencode "run_id=$run_id" | jq .
+```
+
+Use the records to compare model calls within the task. Further filters include `provider`, `model`, `since`, and `limit`.
+
+## Read workspace totals
+
+```bash
+api /token-usage | jq '{totals, last_updated}'
+```
+
+Reports can arrive after execution. They are recorded estimates, not a final bill. For a daemon using your provider key, check that provider's billing too.
+
+<Accordion title="Usage endpoint reference">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/token-usage` | Workspace totals and session summaries. |
+  | `GET /v1/token-usage/entries` | Individual records with optional filters. |
+  | `GET /v1/threads/{thread_id}/runs/{run_id}/usage` | One run's recorded usage, or `null`. |
+
+  Read access is sufficient. These queries do not start workspace compute. Responses use snake_case fields, including `last_updated` and `entry_count`.
+</Accordion>
diff --git a/content/docs/api/workflows/workspace.mdx b/content/docs/api/workflows/workspace.mdx
new file mode 100644
index 0000000..a9157cd
--- /dev/null
+++ b/content/docs/api/workflows/workspace.mdx
@@ -0,0 +1,100 @@
+---
+title: Workspace tools
+icon: folder-cog
+description: Inspect skills, organize labels, and manage runtime readiness.
+---
+
+Use these operations to choose skills, organize conversations, and check whether the workspace can run work.
+
+The examples use the authenticated `api` helper from [your first request](/api/first-request).
+
+## Choose skills for an Agent
+
+List the skills already available in this workspace:
+
+```bash
+api /agent/skills | jq '.data'
+```
+
+For a meeting assistant, look for a skill that works with your document format. Use its exact name when updating the [Agent's configuration](/api/workflows/agents#improve-its-instructions).
+
+Built-in skills are already available. For a marketplace skill, read its detail and install it first. Then save its name in the [Agent's configuration](/api/workflows/agents).
+
+Selecting a missing skill does not install it. Removing a skill does not remove its name from existing Agent configurations.
+
+<Accordion title="Skill endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/agent/skills` | List built-in and workspace skills. |
+  | `GET /v1/agent/skills/marketplace` | Browse the installable catalog. |
+  | `GET /v1/agent/skills/marketplace/{skill_id}` | Read catalog and installation metadata. |
+  | `GET /v1/agent/skills/marketplace/{skill_id}/detail` | Review a skill's instructions before installation. |
+  | `GET /v1/agent/skills/repo/{skill_id}/detail` | Read a built-in skill's instructions. |
+  | `GET /v1/agent/skills/workspace/{skill_id}/detail` | Read an installed skill's instructions. |
+  | `POST /v1/agent/skills/marketplace/{skill_id}/install` | Install the selected catalog skill. |
+  | `DELETE /v1/agent/skills/marketplace/{skill_id}` | Remove its installed marketplace copy. |
+  | `DELETE /v1/agent/skills/workspace/{skill_id}` | Remove the named workspace skill directory. |
+
+  Reading a skill document does not execute it. After removal, update Agents that selected the skill or reinstall it.
+</Accordion>
+
+## Organize with labels
+
+For example, mark the quickstart conversation for review. Create a label first:
+
+```bash
+label=$(api /agent/labels \
+  -H 'Content-Type: application/json' -d '{"name":"API review"}') &&
+label_id=$(printf '%s' "$label" | jq -er '.id')
+```
+
+If that label already exists, reuse its ID from `GET /v1/agent/labels`. After a lost creation response, check that list before creating another.
+
+Add the label to the conversation without removing its existing labels:
+
+```bash
+thread=$(api "/threads/$thread_id") &&
+label_body=$(printf '%s' "$thread" | jq --arg id "$label_id" \
+  '{label_ids: ((.label_ids // []) + [$id] | unique)}') &&
+api "/threads/$thread_id" -X PATCH \
+  -H 'Content-Type: application/json' -d "$label_body"
+```
+
+The updated conversation now includes this label's ID. Projects use the same `label_ids` field. Read the latest object before changing its labels.
+
+<Accordion title="Label endpoints">
+  | Method and path | Use |
+  | --- | --- |
+  | `GET /v1/agent/labels` | Read the label registry. |
+  | `POST /v1/agent/labels` | Create with `name` and optional hex `color`. |
+  | `PATCH /v1/agent/labels` | Send `id` with a changed `name`, `color`, or `order`. |
+  | `DELETE /v1/agent/labels` | Remove the query's `id`. Keep its conversations and files. |
+</Accordion>
+
+## Check runtime readiness
+
+Input submission starts the runtime when needed. To check readiness without sending a message:
+
+```bash
+api /agent/runtime/status | jq '{status, busy, can_wake, can_stop}'
+```
+
+Use `can_wake` and `can_stop` when offering those controls. A busy runtime can refuse a stop. Stop active work through its thread or run first. Respect `Retry-After` on temporary readiness errors.
+
+<Accordion title="Runtime endpoint reference">
+
+| Method and path | Use |
+| --- | --- |
+| `GET /v1/agent/runtime/status` | Read execution and storage readiness. |
+| `POST /v1/agent/runtime/wake` | Start if needed, then wait for readiness without sending a chat message. |
+| `POST /v1/agent/runtime/stop` | Release compute while keeping saved workspace data. |
+
+</Accordion>
+
+<Accordion title="Reset an entire workspace">
+  `POST /v1/agent/workspace/reset` is destructive. It clears conversations, projects, workspace files, and installed or custom workspace skills. It also retires schedules.
+
+  Saved Agents, their knowledge files, and account settings remain. Home is recreated automatically. Reassign Agents from removed projects before reopening their conversations. Reinstall the workspace skills they need.
+
+  Use individual file, thread, or project deletion for targeted cleanup.
+</Accordion>
diff --git a/content/docs/deployment-models.mdx b/content/docs/deployment-models.mdx
index 26f67ce..0992015 100644
--- a/content/docs/deployment-models.mdx
+++ b/content/docs/deployment-models.mdx
@@ -2,7 +2,7 @@
 title: Deployment models
 sidebarTitle: Overview
 icon: server-cog
-description: Compare Fluso Cloud, dedicated AWS VPC, planned Azure VNet, and scoped on-premises deployments.
+description: Compare Fluso Cloud, a workspace on your machine, and Enterprise deployments.
 ---
 
 Your deployment model decides who operates Fluso and where its runtime, durable data, and diagnostics can live. It does not by itself control where connected Apps or external model providers process data.
@@ -10,6 +10,7 @@ Your deployment model decides who operates Fluso and where its runtime, durable
 | Model | Availability | Operations |
 | --- | --- | --- |
 | Fluso Cloud | Available | Managed by Fluso |
+| Fluso Local | Contact Fluso for a matching Mac or Linux package | You operate one owner's workspace |
 | Dedicated AWS VPC | Supported for scoped Enterprise deployments | Responsibilities agreed during deployment design |
 | Azure VNet | Coming soon | Not available today |
 | On-premises | Scoped Enterprise engagement | Responsibilities agreed before implementation |
@@ -20,6 +21,12 @@ Fluso Cloud is the standard managed service. It runs on AWS with European hostin
 
 Choose it when you want to start without operating infrastructure. See [Legal](/resources/legal) for Fluso's privacy policy.
 
+## Fluso Local
+
+Install the daemon to run one owner's workspace on an Apple Silicon Mac or a supported Linux host. Conversations and files stay on that host. You manage its provider credentials, service, updates, and backups.
+
+The desktop app connects to this workspace. It does not install or update the daemon. This is separate from an Enterprise deployment of the whole platform. Start with [Set up Fluso Local](/workspaces/setup).
+
 ## Dedicated AWS VPC
 
 A dedicated AWS VPC deployment is available for Enterprise customers whose network or residency requirements do not fit the managed service. It is a scoped deployment, not a self-service switch.
@@ -59,8 +66,9 @@ Traces can include prompt and response text. For a dedicated or on-premises depl
 ## Choose a model
 
 - Start with Fluso Cloud when managed operations and European hosting meet the requirement.
+- Use [Fluso Local](/workspaces) when you want to operate a workspace on your own machine.
 - Scope an AWS VPC deployment when you need a dedicated AWS network boundary.
 - Treat Azure VNet as future availability, not a current option.
 - Scope on-premises only after Fluso validates the infrastructure, residency, provider, telemetry, and support requirements.
 
-For a custom deployment, [contact Fluso](mailto:sales@premai.io). For the component boundaries behind these models, read [Architecture](/developers/architecture).
+For a custom deployment, [contact Fluso](mailto:sales@premai.io).
diff --git a/content/docs/developers/agent-builder.mdx b/content/docs/developers/agent-builder.mdx
index 879e42d..0f62b1a 100644
--- a/content/docs/developers/agent-builder.mdx
+++ b/content/docs/developers/agent-builder.mdx
@@ -1,40 +1,73 @@
 ---
-title: Agent builder
-sidebarTitle: Agent builder
-icon: workflow
-description: Turn a plain-language request into an Agent draft, then review or refine it before saving.
+title: Your first Agent
+icon: bot
+description: Turn a few meeting notes into a brief you can use.
 ---
 
-Open **Control Panel → Create Agent** to start in Agent Studio. Describe the job in plain language. Studio drafts the Agent definition and a small workflow preview before anything is saved.
+Let's make an assistant for meeting preparation. You supply the notes. It helps you see what matters and what you need to decide.
 
-> *"Create a customer escalation coordinator. Gather the customer, impact, urgency, and open questions. Read relevant Gmail and Google Drive context, classify the case as P0 or P1, prepare the next steps, and require approval before sending anything."*
+You can try this with pasted text, so there is no account to connect first.
 
-## Build the first draft
+## 1. Describe the help you want
 
-A useful request names four things:
+Select **Agents → New Agent**. Leave the project as **Home** for this walkthrough.
 
-- The input, such as a support request or release candidate.
-- The outcome, such as a severity decision or handoff package.
-- The sources and capabilities the Agent may use.
-- The boundaries that must hold, such as approval before an external action.
+Write this in the message box:
 
-Select **Build**. Studio returns the Agent name, description, instructions, and a short graph of the proposed steps. The graph is a design preview. It helps you check the order and decision points, but it is not executable code.
+> *"Help me prepare for meetings. I'll share notes, agendas, and documents. Give me a short brief with what matters, what we need to decide, and a few questions worth asking. If something important is missing, tell me. Keep everything here. Don't contact anyone."*
 
-## Refine without starting over
+Send the message.
 
-Use the Studio message box to change the draft:
+<Frame caption="Describe the job in your own words. You can change it later.">
+  <a href="/images/agents/meeting-create.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/meeting-create.png" alt="New Agent message box with a request for help preparing for meetings." width="1520" height="996" />
+  </a>
+</Frame>
 
-> *"Only use P0 and P1. Run the Gmail and Drive lookups in parallel. Stop for approval before sending a customer reply."*
+Fluso opens a setup conversation called **Manager**. It gives the Agent a name and saves instructions for how it should help.
 
-Studio revises the current draft and replaces the workflow preview. If a request fails, the last valid preview stays in place so you can retry.
+Read the setup beside the conversation. Ask for a change there if needed. Select **Launch agent** when you are ready.
 
-## Create or open the editor
+<Frame caption="Manager confirms that Meeting Prep is ready. Launch agent opens the working conversation.">
+  <a href="/images/agents/meeting-manager.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/meeting-manager.png" alt="The creation request and Manager's reply, with the Launch agent button below." loading="lazy" width="1600" height="1276" />
+  </a>
+</Frame>
 
-- Select **Create Agent** when the draft is ready.
-- Select **Go to editor** when you want to inspect every field, capability, knowledge file, or thread setting first.
+## 2. Give it something to work on
 
-Studio only selects capabilities already available to you. Creating the Agent saves the definition. Existing Agent threads keep the definition they started with, so test changes in a new thread.
+You are now in the Agent's working conversation. Paste your meeting notes, or try these sample notes:
 
-## Next
+> *"Help me get ready for tomorrow's planning meeting.*
+>
+> *We're organizing a half-day workshop for 18 new colleagues next month. We have €1,200. The office room is free but seats 12. A nearby venue seats 24 and costs €450. We want a welcome session and a practical exercise. Lunch and the facilitator are undecided.*
+>
+> *What do we need to settle in the meeting? Keep the brief short enough to read in two minutes."*
 
-See [Agent description](/developers/agent-description) for field boundaries and [Threads and contexts](/developers/threads-and-contexts) for what a new Agent thread receives.
+Read the brief against your notes. It should notice the seating problem and leave undecided plans open.
+
+## 3. Keep the conversation going
+
+In our run, the Agent estimated costs we had not supplied. We corrected that and gave it a change to work with:
+
+> *"We can use the larger office room after all. It seats 20 and is free. We don't have prices for lunch or a facilitator yet. Keep those as open questions and update the brief."*
+
+We also asked for a shorter version: three decisions, the missing costs, and one question to ask first.
+
+<Frame caption="The shorter brief keeps the decisions and unknown costs clear. This is a real run with sample notes.">
+  <a href="/images/agents/meeting-brief.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/meeting-brief.png" alt="Meeting Prep updates the workshop brief after a room change and a correction about unknown costs." width="1600" height="1490" />
+  </a>
+</Frame>
+
+You can correct details, attach another document, or ask for a shorter answer in the same conversation. Select the Agent in the sidebar to return later.
+
+When you find a way of working you want to keep, [teach it your preferences](/developers/improve).
+
+<Accordion title="Other ways to start">
+  **My Agents** and **New Agent** offer Fluso starting points for research, project follow-through, inbox triage, and document review. Preview one to create your own copy. Manager helps with missing app connections.
+
+  **Fill in a form instead** lets you enter the setup directly. **Continue setup** lets you return to an unfinished creation.
+
+  For work with its own files, choose a project before starting. See [Files and memory](/developers/guides/files).
+</Accordion>
diff --git a/content/docs/developers/agent-description.mdx b/content/docs/developers/agent-description.mdx
deleted file mode 100644
index c2aa449..0000000
--- a/content/docs/developers/agent-description.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Agent description
-sidebarTitle: Agent description
-icon: file-text
-description: Write a clear Agent summary and keep it separate from the goal and standing instructions.
----
-
-The description is the short answer to "What does this Agent do?" It appears in Agent lists and search, and it becomes part of the saved Agent definition when a thread starts.
-
-Keep it to one sentence. Name the responsibility, input, and output when they fit.
-
-> *"Triages customer escalations and prepares an approval-ready response plan."*
-
-## Description, goal, and instructions
-
-These fields have different jobs:
-
-| Field | Use it for | Example |
-| --- | --- | --- |
-| Name | A short label you can find quickly | Customer escalation coordinator |
-| Description | What the Agent is responsible for | Triages customer escalations and prepares a response plan. |
-| Goal | The result that marks success | Return a severity, owner, and next-step package. |
-| Instructions | Rules, sources, order, and approval boundaries | Check Gmail and Drive. Require approval before any external send. |
-
-Do not put the full workflow in the description. Long rules are harder to scan there and belong in **Instructions**.
-
-## Changes apply to new threads
-
-An Agent thread keeps the saved definition it started with. Changing the description, goal, instructions, project, capabilities, or knowledge files creates a new definition for future threads. It does not rewrite an existing conversation.
-
-Start a new thread after an edit when you need to verify the new behavior.
-
-## Next
-
-Build the first draft in [Agent builder](/developers/agent-builder), or update these fields through [Agents and versions](/developers/api-ref/agents-and-versions).
diff --git a/content/docs/developers/api-ref/agents-and-versions.mdx b/content/docs/developers/api-ref/agents-and-versions.mdx
deleted file mode 100644
index 212f201..0000000
--- a/content/docs/developers/api-ref/agents-and-versions.mdx
+++ /dev/null
@@ -1,211 +0,0 @@
----
-title: Agents and versions
-sidebarTitle: Agents & versions
-icon: bot
-description: Create Agents, read their current immutable configuration, and publish safe updates.
----
-
-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
-
-<Endpoint method="GET" path="/v1/agents" />
-
-Returns paginated Agent summaries, with optional text search through `q`.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents?page=1&limit=20&q=release" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "agents": [
-    {
-      "agentId": "agt_0123456789ab4def8123456789abcdef",
-      "currentConfigId": "cfg_11111111111141118111111111111111",
-      "name": "Release reviewer",
-      "description": "Reviews release candidates",
-      "projectName": "Release Review",
-      "responseMode": "high",
-      "createdAt": "2026-08-31T09:00:00Z",
-      "updatedAt": "2026-08-31T09:00:00Z",
-      "lastChatAt": null,
-      "chatCount": 0,
-      "activeScheduleCount": 0,
-      "nextRunAt": null
-    }
-  ],
-  "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
-}
-```
-
-## Create an Agent
-
-<Endpoint method="POST" path="/v1/agents" />
-
-Creates an Agent and its first immutable configuration.
-
-Create `Release Review` through `POST /v1/agent/projects` first. `Home` is available by default.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents" \
-  -X POST \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "name": "Release reviewer",
-    "description": "Reviews release candidates",
-    "goal": "Return a go or no-go decision",
-    "instructions": "Cite blockers and name each follow-up owner.",
-    "conversationStarters": ["Review this candidate"],
-    "responseMode": "high",
-    "projectName": "Release Review"
-  }'
-```
-
-```json title="Response: 201, selected fields"
-{
-  "agentId": "agt_0123456789ab4def8123456789abcdef",
-  "currentConfigId": "cfg_11111111111141118111111111111111",
-  "state": "active",
-  "createdAt": "2026-08-31T09:00:00Z",
-  "updatedAt": "2026-08-31T09:00:00Z",
-  "lastChatAt": null,
-  "chatCount": 0,
-  "config": {
-    "schemaVersion": 1,
-    "configId": "cfg_11111111111141118111111111111111",
-    "agentId": "agt_0123456789ab4def8123456789abcdef",
-    "name": "Release reviewer",
-    "normalizedName": "release reviewer",
-    "description": "Reviews release candidates",
-    "goal": "Return a go or no-go decision",
-    "instructions": "Cite blockers and name each follow-up owner.",
-    "conversationStarters": ["Review this candidate"],
-    "responseMode": "high",
-    "threadManagementEnabled": true,
-    "threadCreationMode": "explicit",
-    "projectName": "Release Review",
-    "knowledgeFiles": [],
-    "skills": null,
-    "connectors": null,
-    "createdAt": "2026-08-31T09:00:00Z",
-    "contentDigest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
-  }
-}
-```
-
-## Read the current configuration
-
-<Endpoint method="GET" path="/v1/agents/{agentId}" />
-
-Returns the Agent record and the configuration named by `currentConfigId`.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200, selected fields"
-{
-  "agentId": "agt_0123456789ab4def8123456789abcdef",
-  "currentConfigId": "cfg_11111111111141118111111111111111",
-  "state": "active",
-  "config": {
-    "schemaVersion": 1,
-    "configId": "cfg_11111111111141118111111111111111",
-    "name": "Release reviewer",
-    "goal": "Return a go or no-go decision"
-  }
-}
-```
-
-## Publish an update
-
-<Endpoint method="PATCH" path="/v1/agents/{agentId}" />
-
-Creates a new configuration when the submitted fields change the Agent.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef" \
-  -X PATCH \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "baseConfigId": "cfg_11111111111141118111111111111111",
-    "goal": "Return a go or no-go decision with named owners"
-  }'
-```
-
-```json title="Response: 200, selected fields"
-{
-  "agentId": "agt_0123456789ab4def8123456789abcdef",
-  "currentConfigId": "cfg_22222222222242228222222222222222",
-  "state": "active",
-  "config": {
-    "schemaVersion": 1,
-    "configId": "cfg_22222222222242228222222222222222",
-    "goal": "Return a go or no-go decision with named owners"
-  }
-}
-```
-
-An unchanged patch returns the existing config ID. A stale `baseConfigId` returns `409 STALE_AGENT_CONFIG` and includes the current config ID in `error.details.currentConfigId`.
-
-## List available configurations
-
-<Endpoint method="GET" path="/v1/agents/{agentId}/versions" />
-
-Returns up to 100 available immutable configurations, newest first. Older
-configurations that no chat uses may be reclaimed under storage pressure, so
-this endpoint is not a permanent audit ledger.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef/versions" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200, selected fields"
-{
-  "versions": [
-    {
-      "schemaVersion": 1,
-      "configId": "cfg_22222222222242228222222222222222",
-      "agentId": "agt_0123456789ab4def8123456789abcdef",
-      "goal": "Return a go or no-go decision with named owners",
-      "createdAt": "2026-08-31T10:00:00Z",
-      "contentDigest": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
-    }
-  ]
-}
-```
-
-To restore an available configuration, send its editable fields through the
-normal update endpoint and use the Agent's current `currentConfigId` as
-`baseConfigId`. The update creates a new immutable configuration. Existing
-chats keep the configuration they started with.
-
-## Delete an Agent
-
-<Endpoint method="DELETE" path="/v1/agents/{agentId}" />
-
-Deletes the Agent and removes its owned chats, configurations, knowledge, schedules, and webhook triggers.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef" \
-  -X DELETE \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```http title="Response"
-HTTP/1.1 204 No Content
-```
-
-## Next
-
-Start Agent work through [Threads and messages](/developers/api-ref/threads-and-messages), or automate it with [Schedules](/developers/api-ref/schedules) and [Webhooks](/developers/webhooks).
diff --git a/content/docs/developers/api-ref/authentication.mdx b/content/docs/developers/api-ref/authentication.mdx
deleted file mode 100644
index eb0e118..0000000
--- a/content/docs/developers/api-ref/authentication.mdx
+++ /dev/null
@@ -1,135 +0,0 @@
----
-title: Authentication
-sidebarTitle: Authentication
-icon: key-round
-description: Authenticate a client and send bearer tokens to the Fluso REST API.
----
-
-The REST API base URL is `https://api.fluso.ai`. Set it once, then assign the access token returned by the client sign-in flow:
-
-The `/v1` routes in this Beta section are the current client surface and may change during beta. Endpoints used only by the Fluso web app are internal and may change without notice.
-
-```bash
-export FLUSO_API=https://api.fluso.ai
-export FLUSO_TOKEN='<access-token>'
-```
-
-Send that token on every authenticated request:
-
-```http
-Authorization: Bearer $FLUSO_TOKEN
-```
-
-Keep access and refresh tokens out of source control. The examples below use placeholders and environment variables.
-
-Once authenticated, start with [Agents and versions](/developers/api-ref/agents-and-versions).
-
-## Start client sign-in
-
-<Endpoint method="POST" path="/v1/auth/client/start" />
-
-Creates a short-lived browser sign-in URL for a CLI or another client.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/auth/client/start" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "client": "cli",
-    "client_user_id": "device-123",
-    "metadata": {"return_to": "fluso://auth"}
-  }'
-```
-
-```json title="Response: 200"
-{
-  "url": "https://<portal-host>/auth/client/launch?state=...",
-  "expires_in": 600
-}
-```
-
-Open `url` in the user's browser. The signed-in page completes approval and returns a one-time code to the client.
-
-## Exchange the one-time code
-
-<Endpoint method="GET" path="/v1/auth/client/exchange/{code}" />
-
-Consumes the code once and returns credentials bound to the same client and client user ID.
-
-```bash title="Request"
-export FLUSO_CODE='<one-time-code>'
-
-curl "$FLUSO_API/v1/auth/client/exchange/$FLUSO_CODE?client=cli&client_user_id=device-123"
-```
-
-```json title="Response: 200"
-{
-  "status": "completed",
-  "auth": {
-    "access_token": "<access-token>",
-    "refresh_token": "<refresh-token>",
-    "expires_in": 86400,
-    "aci_api_key": "<api-key>",
-    "user": {
-      "id": "22222222-2222-4222-8222-222222222222",
-      "email": "developer@example.com",
-      "name": "Developer"
-    }
-  }
-}
-```
-
-The code expires and cannot be exchanged twice.
-
-## Refresh a client session
-
-<Endpoint method="POST" path="/v1/auth/client/refresh" />
-
-Exchanges a valid client refresh token for refreshed credentials.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/auth/client/refresh" \
-  -H 'Content-Type: application/json' \
-  -d '{"refresh_token":"<refresh-token>"}'
-```
-
-```json title="Response: 200"
-{
-  "access_token": "<new-access-token>",
-  "refresh_token": "<new-refresh-token>",
-  "expires_in": 86400,
-  "aci_api_key": "<api-key>"
-}
-```
-
-## Read the current user
-
-<Endpoint method="GET" path="/v1/auth/me" />
-
-Returns the user attached to the bearer token and their runtime API key.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/auth/me" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "user": {
-    "id": "22222222-2222-4222-8222-222222222222",
-    "email": "developer@example.com",
-    "name": "Developer",
-    "picture": null,
-    "created_at": "2026-08-31T09:00:00"
-  },
-  "aci_api_key": "<api-key>"
-}
-```
-
-<Note>
-  Workspace and usage routes also expect the bearer header. An `X-API-Key`
-  header alone does not authenticate those proxy paths.
-</Note>
-
-## Next
-
-Use the token with [Agents and versions](/developers/api-ref/agents-and-versions), or open a turn through [Threads and messages](/developers/api-ref/threads-and-messages).
diff --git a/content/docs/developers/api-ref/files-and-projects.mdx b/content/docs/developers/api-ref/files-and-projects.mdx
deleted file mode 100644
index a79d410..0000000
--- a/content/docs/developers/api-ref/files-and-projects.mdx
+++ /dev/null
@@ -1,231 +0,0 @@
----
-title: Files and projects
-sidebarTitle: Files & projects
-icon: folder-kanban
-description: Work with durable project metadata and files in a user's Agent workspace.
----
-
-Workspace projects and files use the `/v1/agent/*` routes. They belong to the authenticated user's durable workspace, outside disposable runtime compute.
-
-[Agents](/developers/api-ref/agents-and-versions) bind new chats to one of these projects by name.
-
-## List projects
-
-<Endpoint method="GET" path="/v1/agent/projects" />
-
-Returns workspace projects and their thread summaries.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent/projects?includeArchived=false" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "projects": [
-    {
-      "name": "Release Review",
-      "goal": "Decide launch readiness",
-      "createdAt": "2026-08-31T09:00:00Z",
-      "updatedAt": "2026-08-31T09:00:00Z",
-      "threads": []
-    }
-  ]
-}
-```
-
-## Create a project
-
-<Endpoint method="POST" path="/v1/agent/projects" />
-
-Creates a workspace project and its context file.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent/projects" \
-  -X POST \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "name": "Release Review",
-    "goal": "Decide launch readiness",
-    "instructions": "Keep evidence and decisions in this project."
-  }'
-```
-
-```json title="Response: 201"
-{
-  "name": "Release Review",
-  "goal": "Decide launch readiness",
-  "instructions": "Keep evidence and decisions in this project.",
-  "createdAt": "2026-08-31T09:00:00Z",
-  "updatedAt": "2026-08-31T09:00:00Z",
-  "threads": []
-}
-```
-
-## Update a project
-
-<Endpoint method="PATCH" path="/v1/agent/projects" />
-
-Updates the project named in the request body.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent/projects" \
-  -X PATCH \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "name": "Release Review",
-    "goal": "Decide launch readiness and record follow-up owners"
-  }'
-```
-
-```json title="Response: 200, selected fields"
-{
-  "name": "Release Review",
-  "goal": "Decide launch readiness and record follow-up owners",
-  "updatedAt": "2026-08-31T09:05:00Z",
-  "threads": []
-}
-```
-
-## Export a project
-
-<Endpoint method="GET" path="/v1/agent/projects/export" />
-
-Streams the named project as a ZIP archive.
-
-```bash title="Request"
-curl -G "$FLUSO_API/v1/agent/projects/export" \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  --data-urlencode 'name=Release Review' \
-  -o release-review.zip
-```
-
-```http title="Response"
-HTTP/1.1 200 OK
-Content-Type: application/zip
-Content-Disposition: attachment; filename="Release Review.zip"; filename*=UTF-8''Release%20Review.zip
-```
-
-## List files
-
-<Endpoint method="GET" path="/v1/agent/files" />
-
-Lists files or directories under a workspace path.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent/files?path=/files&recursive=false&includeStats=true" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "path": "/files",
-  "recursive": false,
-  "entries": [
-    {
-      "path": "/files/release-brief.md",
-      "name": "release-brief.md",
-      "type": "file",
-      "size": 1240,
-      "modifiedAt": "2026-08-31T09:00:00Z",
-      "mimeType": "text/markdown"
-    }
-  ]
-}
-```
-
-## Read a text file
-
-<Endpoint method="GET" path="/v1/agent/files/read" />
-
-Returns a UTF-8 text file as JSON.
-
-```bash title="Request"
-curl -G "$FLUSO_API/v1/agent/files/read" \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  --data-urlencode 'path=/files/release-brief.md'
-```
-
-```json title="Response: 200"
-{
-  "path": "/files/release-brief.md",
-  "content": "# Release candidate\n\nKnown issue: ...\n",
-  "encoding": "utf-8"
-}
-```
-
-## Upload a file
-
-<Endpoint method="POST" path="/v1/agent/files/upload" />
-
-Uploads one file with an optional destination and conflict policy.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent/files/upload" \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -F 'file=@release-brief.md' \
-  -F 'path=/files/release-brief.md' \
-  -F 'onConflict=overwrite'
-```
-
-```json title="Response: 200"
-{
-  "success": true,
-  "path": "/files/release-brief.md",
-  "size": 1240,
-  "mimeType": "text/markdown"
-}
-```
-
-`onConflict` accepts `error`, `overwrite`, or `uuid`. The default is `error`.
-
-## Download a file
-
-<Endpoint method="GET" path="/v1/agent/files/download" />
-
-Streams a file with attachment headers.
-
-```bash title="Request"
-curl -G "$FLUSO_API/v1/agent/files/download" \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  --data-urlencode 'path=/files/release-report.pdf' \
-  -o release-report.pdf
-```
-
-```http title="Response"
-HTTP/1.1 200 OK
-Content-Type: application/pdf
-Content-Disposition: attachment; filename="release-report.pdf"; filename*=UTF-8''release-report.pdf
-```
-
-## Delete a file
-
-<Endpoint method="DELETE" path="/v1/agent/files" />
-
-Deletes one file, or a directory when `recursive=true`.
-
-```bash title="Request"
-curl -G "$FLUSO_API/v1/agent/files" \
-  -X DELETE \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  --data-urlencode 'path=/files/release-brief.md' \
-  --data 'recursive=false'
-```
-
-```json title="Response: 200"
-{
-  "success": true,
-  "path": "/files/release-brief.md"
-}
-```
-
-<Warning>
-  A recursive directory delete removes every child path. List the target first
-  when its contents are not already known.
-</Warning>
-
-## Next
-
-Read [Projects](/features/projects) for the product workflow, attach project context to [Agents and versions](/developers/api-ref/agents-and-versions), or create project-bound [Threads and messages](/developers/api-ref/threads-and-messages).
diff --git a/content/docs/developers/api-ref/meta.json b/content/docs/developers/api-ref/meta.json
deleted file mode 100644
index 4b3d096..0000000
--- a/content/docs/developers/api-ref/meta.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "title": "API ref",
-  "icon": "code-xml",
-  "defaultOpen": false,
-  "pages": [
-    "agents-and-versions",
-    "authentication",
-    "files-and-projects",
-    "runs",
-    "schedules",
-    "threads-and-messages",
-    "usage"
-  ]
-}
diff --git a/content/docs/developers/api-ref/runs.mdx b/content/docs/developers/api-ref/runs.mdx
deleted file mode 100644
index f0e6e04..0000000
--- a/content/docs/developers/api-ref/runs.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: Runs
-sidebarTitle: Runs
-icon: activity
-description: Inspect Agent runs and stop work that is still active.
----
-
-Run IDs are request IDs. A run can be `queued`, `running`, `held`, `completed`, `failed`, or `cancelled`.
-
-Runs originate from [messages](/developers/api-ref/threads-and-messages) and [schedules](/developers/api-ref/schedules).
-
-## List runs
-
-<Endpoint method="GET" path="/v1/agent-runs" />
-
-Returns recent runs, with optional thread, request, and attention filters.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent-runs?threadId=thread_agent_release&limit=20" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "agent_runs": [
-    {
-      "id": "req_review_01",
-      "request_id": "req_review_01",
-      "thread_id": "thread_agent_release",
-      "target_thread_id": "thread_agent_release",
-      "agent_id": "agt_0123456789ab4def8123456789abcdef",
-      "thread_title": "Release review",
-      "status": "running",
-      "origin": "user",
-      "created_at": "2026-08-31T09:00:00Z",
-      "started_at": "2026-08-31T09:00:01Z",
-      "updated_at": "2026-08-31T09:00:02Z",
-      "completed_at": null,
-      "outcome": null,
-      "result_ref": null,
-      "error": null
-    }
-  ],
-  "settlement_cursor": "2026-08-31T09:00:02Z/req_review_01"
-}
-```
-
-Use `attention=true` to include runs that need review and schedule delivery failures.
-
-## Read one run
-
-<Endpoint method="GET" path="/v1/agent-runs/{requestId}" />
-
-Returns one matching run. Include `threadId` when request IDs may repeat across threads.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent-runs/req_review_01?threadId=thread_agent_release" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "id": "req_review_01",
-  "request_id": "req_review_01",
-  "thread_id": "thread_agent_release",
-  "target_thread_id": "thread_agent_release",
-  "agent_id": "agt_0123456789ab4def8123456789abcdef",
-  "status": "completed",
-  "origin": "user",
-  "created_at": "2026-08-31T09:00:00Z",
-  "started_at": "2026-08-31T09:00:01Z",
-  "updated_at": "2026-08-31T09:01:10Z",
-  "completed_at": "2026-08-31T09:01:10Z",
-  "outcome": "completed",
-  "result_ref": {
-    "thread_id": "thread_agent_release",
-    "request_id": "req_review_01"
-  },
-  "error": null
-}
-```
-
-## Stop a run
-
-<Endpoint method="POST" path="/v1/agent-runs/{requestId}/stop" />
-
-Requests cancellation without starting a dormant runtime only to stop it.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agent-runs/req_review_01/stop" \
-  -X POST \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{"threadId":"thread_agent_release"}'
-```
-
-```json title="Response: 200"
-{
-  "thread_id": "thread_agent_release",
-  "request_id": "req_review_01",
-  "status": "cancelled"
-}
-```
-
-The status can also be `already_terminal` when the run settled before cancellation reached it.
-
-## Next
-
-Inspect token cost in [Usage](/developers/api-ref/usage), or create recurring and one-time [Schedules](/developers/api-ref/schedules).
diff --git a/content/docs/developers/api-ref/schedules.mdx b/content/docs/developers/api-ref/schedules.mdx
deleted file mode 100644
index 4ee3bd6..0000000
--- a/content/docs/developers/api-ref/schedules.mdx
+++ /dev/null
@@ -1,139 +0,0 @@
----
-title: Schedules
-sidebarTitle: Schedules
-icon: calendar-clock
-description: Create, inspect, pause, and delete Agent schedules.
----
-
-A schedule belongs to an Agent and one of that Agent's existing threads. Supply exactly one timing field: a five-field `cron` expression or a future `at` timestamp with an offset. `timezone` must be an IANA time zone.
-
-See [Threads and messages](/developers/api-ref/threads-and-messages) for the target thread and [Runs](/developers/api-ref/runs) for execution state.
-
-## List schedules
-
-<Endpoint method="GET" path="/v1/agents/{agentId}/schedules" />
-
-Returns schedules for an Agent, optionally filtered by thread.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef/schedules?threadId=thread_agent_release&page=1&limit=100" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "schedules": [
-    {
-      "id": "11111111-1111-4111-8111-111111111111",
-      "agentId": "agt_0123456789ab4def8123456789abcdef",
-      "threadId": "thread_agent_release",
-      "message": "Review the release candidate",
-      "cron": "0 9 * * 1-5",
-      "timezone": "Asia/Kolkata",
-      "status": "active",
-      "pauseReason": null,
-      "nextRunAt": "2026-09-01T03:30:00Z",
-      "attempts": 0,
-      "createdAt": "2026-08-31T09:00:00Z",
-      "updatedAt": "2026-08-31T09:00:00Z",
-      "firedAt": null,
-      "lastRun": null
-    }
-  ],
-  "pagination": { "page": 1, "limit": 100, "total": 1, "pages": 1 }
-}
-```
-
-## Create a schedule
-
-<Endpoint method="POST" path="/v1/agents/{agentId}/schedules" />
-
-Creates a recurring or one-time schedule. The caller supplies a UUID so retries can be idempotent.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef/schedules" \
-  -X POST \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "id": "11111111-1111-4111-8111-111111111111",
-    "threadId": "thread_agent_release",
-    "message": "Review the release candidate",
-    "cron": "0 9 * * 1-5",
-    "timezone": "Asia/Kolkata"
-  }'
-```
-
-For a durable one-time schedule, replace `cron` with an offset-bearing `at` value:
-
-```json title="One-time timing fields"
-{
-  "at": "2026-09-01T09:00:00+05:30",
-  "timezone": "Asia/Kolkata"
-}
-```
-
-```json title="Response: 201"
-{
-  "id": "11111111-1111-4111-8111-111111111111",
-  "agentId": "agt_0123456789ab4def8123456789abcdef",
-  "threadId": "thread_agent_release",
-  "message": "Review the release candidate",
-  "cron": "0 9 * * 1-5",
-  "timezone": "Asia/Kolkata",
-  "status": "active",
-  "pauseReason": null,
-  "nextRunAt": "2026-09-01T03:30:00Z",
-  "attempts": 0,
-  "createdAt": "2026-08-31T09:00:00Z",
-  "updatedAt": "2026-08-31T09:00:00Z",
-  "firedAt": null,
-  "lastRun": null
-}
-```
-
-Replaying the same ID and body while the schedule is live returns the existing schedule with `200`. Reusing the live ID with different fields returns a conflict. After a one-time schedule fires or a schedule is deleted, that ID returns `410` for 24 hours.
-
-## Pause or edit a schedule
-
-<Endpoint method="PATCH" path="/v1/agents/{agentId}/schedules/{scheduleId}" />
-
-Updates submitted fields. `threadId` is always required to guard the target.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef/schedules/11111111-1111-4111-8111-111111111111" \
-  -X PATCH \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{"threadId":"thread_agent_release","status":"paused"}'
-```
-
-```json title="Response: 200, selected fields"
-{
-  "id": "11111111-1111-4111-8111-111111111111",
-  "agentId": "agt_0123456789ab4def8123456789abcdef",
-  "threadId": "thread_agent_release",
-  "status": "paused",
-  "nextRunAt": "2026-09-01T03:30:00Z"
-}
-```
-
-## Delete a schedule
-
-<Endpoint method="DELETE" path="/v1/agents/{agentId}/schedules/{scheduleId}" />
-
-Deletes a schedule after matching it to the supplied thread.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef/schedules/11111111-1111-4111-8111-111111111111?threadId=thread_agent_release" \
-  -X DELETE \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```http title="Response"
-HTTP/1.1 204 No Content
-```
-
-## Next
-
-Inspect each execution in [Runs](/developers/api-ref/runs), or manage the target in [Threads and messages](/developers/api-ref/threads-and-messages).
diff --git a/content/docs/developers/api-ref/threads-and-messages.mdx b/content/docs/developers/api-ref/threads-and-messages.mdx
deleted file mode 100644
index 8eeb577..0000000
--- a/content/docs/developers/api-ref/threads-and-messages.mdx
+++ /dev/null
@@ -1,174 +0,0 @@
----
-title: Threads and messages
-sidebarTitle: Threads & messages
-icon: messages-square
-description: Create threads, manage their metadata, read history, and stream a turn.
----
-
-Threads live inside a workspace project. Thread responses use snake_case fields. The chat stream follows the AI SDK UI message stream protocol.
-
-Agent-backed threads use an [Agent configuration](/developers/api-ref/agents-and-versions), and each accepted turn creates a [run](/developers/api-ref/runs).
-
-## List threads
-
-<Endpoint method="GET" path="/v1/threads" />
-
-Returns ordinary threads ordered by recent activity.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/threads?page=1&limit=20" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200, selected fields"
-{
-  "threads": [
-    {
-      "thread_id": "thread_release",
-      "project_id": "Release Review",
-      "name": "Release review",
-      "title": "Release review",
-      "created_at": "2026-08-31T09:00:00Z",
-      "updated_at": "2026-08-31T09:02:00Z",
-      "last_active_at": "2026-08-31T09:02:00Z",
-      "status": "ready"
-    }
-  ],
-  "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
-}
-```
-
-Agent-owned chats are omitted from this general list and remain attached to their Agent.
-
-## Create a thread
-
-<Endpoint method="POST" path="/v1/threads" />
-
-Creates a thread in the named project, creating the project when needed.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/threads" \
-  -X POST \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{"project_id":"Release Review","title":"Release review"}'
-```
-
-```json title="Response: 200"
-{
-  "thread_id": "thread_release",
-  "project_id": "Release Review"
-}
-```
-
-You can supply your own `thread_id` for an idempotent integration boundary.
-
-## Update a thread
-
-<Endpoint method="PATCH" path="/v1/threads/{threadId}" />
-
-Updates the title, metadata, pin, archive state, or label membership.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/threads/thread_release?project_id=Release%20Review" \
-  -X PATCH \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{"title":"RC decision","pinned":true}'
-```
-
-```json title="Response: 200, selected fields"
-{
-  "thread_id": "thread_release",
-  "project_id": "Release Review",
-  "name": "RC decision",
-  "title": "RC decision",
-  "pinned_at": "2026-08-31T09:03:00Z",
-  "status": "ready"
-}
-```
-
-## Read message history
-
-<Endpoint method="GET" path="/v1/threads/{threadId}/messages" />
-
-Returns the thread's persisted messages and projected tool-status records.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/threads/thread_release/messages?project_id=Release%20Review" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{
-  "messages": [
-    {
-      "message_id": "user-1",
-      "thread_id": "thread_release",
-      "type": "user",
-      "is_llm_message": false,
-      "content": "{\"content\":\"Review this release candidate\"}",
-      "metadata": "{\"request_id\":\"req_review_01\"}",
-      "created_at": "2026-08-31T09:00:00Z",
-      "updated_at": "2026-08-31T09:00:00Z"
-    }
-  ]
-}
-```
-
-## Send a message
-
-<Endpoint method="POST" path="/v1/chat" />
-
-Starts or queues a turn and streams UI message events until the request settles.
-
-Use a new thread ID for the first Agent-backed turn. The accepted send creates and binds that thread; an ordinary thread cannot later be converted.
-
-```bash title="Request"
-curl -N "$FLUSO_API/v1/chat" \
-  -H "Authorization: Bearer $FLUSO_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "threadId": "thread_agent_release",
-    "projectName": "Release Review",
-    "agentId": "agt_0123456789ab4def8123456789abcdef",
-    "requestId": "req_review_01",
-    "message": "Review this release candidate"
-  }'
-```
-
-```text title="Response: 200 text/event-stream, shortened"
-data: {"type":"start","messageId":"assistant-req_review_01"}
-
-data: {"type":"text-start","id":"final-text-req_review_01"}
-
-data: {"type":"text-delta","id":"final-text-req_review_01","delta":"Go, with one follow-up."}
-
-data: {"type":"text-end","id":"final-text-req_review_01"}
-
-data: {"type":"finish"}
-
-data: [DONE]
-```
-
-Use one unique `requestId` per intended turn. Retrying the same accepted request does not create a second turn.
-
-## Delete a thread
-
-<Endpoint method="DELETE" path="/v1/threads/{threadId}" />
-
-Deletes the thread and removes schedules that target it.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/threads/thread_release?project_id=Release%20Review" \
-  -X DELETE \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200"
-{ "deleted": true }
-```
-
-## Next
-
-Bind new threads to [Agents and versions](/developers/api-ref/agents-and-versions), or follow accepted turns in [Runs](/developers/api-ref/runs).
diff --git a/content/docs/developers/api-ref/usage.mdx b/content/docs/developers/api-ref/usage.mdx
deleted file mode 100644
index 1bb9622..0000000
--- a/content/docs/developers/api-ref/usage.mdx
+++ /dev/null
@@ -1,144 +0,0 @@
----
-title: Usage
-sidebarTitle: Usage
-icon: chart-no-axes-combined
-description: Read current-user totals, session summaries, and filtered raw usage entries.
----
-
-Usage records are user-scoped. Token counts and costs use camelCase fields, and cost values are denominated in US dollars.
-
-Filter entries by the request and thread identifiers returned from [Runs](/developers/api-ref/runs).
-
-## Read usage totals
-
-<Endpoint method="GET" path="/v1/token-usage" />
-
-Returns totals for the current user plus a map of session summaries.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/token-usage" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200, selected fields"
-{
-  "userId": "22222222-2222-4222-8222-222222222222",
-  "lastUpdated": "2026-08-31T09:05:00Z",
-  "totals": {
-    "tokens": {
-      "input": 120,
-      "output": 40,
-      "cacheRead": 0,
-      "cacheWrite": 0,
-      "total": 160
-    },
-    "cost": {
-      "input": 0.001,
-      "output": 0.002,
-      "cacheRead": 0,
-      "cacheWrite": 0,
-      "total": 0.003
-    },
-    "entryCount": 1
-  }
-}
-```
-
-## List session summaries
-
-<Endpoint method="GET" path="/v1/token-usage/sessions" />
-
-Returns the session map from the totals response as an array.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/token-usage/sessions" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200, selected fields"
-[
-  {
-    "sessionId": "sess_ddf284f4",
-    "threadId": "thread_agent_release",
-    "firstSeen": "2026-08-31T09:00:00Z",
-    "lastUpdated": "2026-08-31T09:05:00Z",
-    "entryCount": 1,
-    "tokens": {
-      "input": 120,
-      "output": 40,
-      "cacheRead": 0,
-      "cacheWrite": 0,
-      "total": 160
-    },
-    "cost": {
-      "input": 0.001,
-      "output": 0.002,
-      "cacheRead": 0,
-      "cacheWrite": 0,
-      "total": 0.003
-    }
-  }
-]
-```
-
-## List usage entries
-
-<Endpoint method="GET" path="/v1/token-usage/entries" />
-
-Returns raw usage entries that match the submitted filters.
-
-```bash title="Request"
-curl "$FLUSO_API/v1/token-usage/entries?threadId=thread_agent_release&limit=100" \
-  -H "Authorization: Bearer $FLUSO_TOKEN"
-```
-
-```json title="Response: 200, selected fields"
-[
-  {
-    "schemaVersion": 2,
-    "eventId": "use_0123456789abcdef0123456789abcdef",
-    "source": "pi-provider",
-    "ts": "2026-08-31T09:05:00Z",
-    "sessionId": "sess_ddf284f4",
-    "threadId": "thread_agent_release",
-    "component": "chat-agent",
-    "measurement": "actual",
-    "requestId": "req_review_01",
-    "provider": "openrouter",
-    "status": "success",
-    "model": "provider/model-id",
-    "tokens": {
-      "input": 120,
-      "output": 40,
-      "cacheRead": 0,
-      "cacheWrite": 0,
-      "total": 160
-    },
-    "cost": {
-      "input": 0.001,
-      "output": 0.002,
-      "cacheRead": 0,
-      "cacheWrite": 0,
-      "total": 0.003
-    },
-    "costSource": "provider"
-  }
-]
-```
-
-| Parameter | Matches | Default |
-| --- | --- | --- |
-| `sessionId` | Session ID | - |
-| `threadId` | Thread ID | - |
-| `requestId` | Request ID | - |
-| `component` | Emitting component | - |
-| `provider` | Model provider | - |
-| `providerSessionId` | Provider session ID | - |
-| `providerGenerationId` | Provider generation ID | - |
-| `model` | Model ID | - |
-| `since` | Entries at or after an RFC 3339 instant | - |
-| `limit` | Maximum entries, from 1 through 1000 | `100` |
-
-## Next
-
-Correlate costs with [Runs](/developers/api-ref/runs), or review the service boundaries in [Architecture](/developers/architecture).
diff --git a/content/docs/developers/architecture.mdx b/content/docs/developers/architecture.mdx
deleted file mode 100644
index 999819d..0000000
--- a/content/docs/developers/architecture.mdx
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: Architecture
-sidebarTitle: Architecture
-icon: network
-description: How requests, runtime compute, platform state, workspace data, and external sources fit together.
----
-
-Fluso separates request handling, runtime compute, durable workspace data, platform records, and external tools. Those boundaries keep each responsibility visible when you deploy or integrate the platform.
-
-Client requests enter these boundaries through the [authenticated REST API](/developers/api-ref/authentication).
-
-<ArchitectureDiagram />
-
-## Request path
-
-1. A Fluso client sends an authenticated request through the edge.
-2. The REST API validates identity and handles platform records.
-3. The gateway admits work, selects the user's runtime, and routes the request.
-4. A thread worker runs the turn with the Agent configuration, tools, and project context attached to that thread.
-
-The runtime can stop and return later because it does not own the only copy of durable user state.
-
-## Data ownership
-
-| Boundary           | What it owns                                                                    |
-| ------------------ | ------------------------------------------------------------------------------- |
-| PostgreSQL         | Users, organizations, access records, schedules, and other platform state       |
-| Isolated user storage | Projects, session history, Agent definitions, skills, and durable runtime files |
-| Knowledge service  | Indexed context and retrieval records under its service contract                |
-| MCP sources        | External data and actions exposed by each connected server                      |
-
-Project working memory belongs to its project. Agent configuration and chat history have separate records, so changing an Agent does not rewrite old conversations.
-
-## Replaceable components
-
-Components can change where the code defines an explicit contract:
-
-- Runtime compute sits behind a `SandboxProvider` contract. Current implementations cover local Docker and AWS ECS.
-- Models resolve through a provider-scoped catalog. Current provider paths cover PCCI and OpenRouter; the catalog does not promise that every model works through every provider.
-- Managed apps and custom servers meet the runtime through MCP and the same tool-policy boundary. A source can change while the protocol stays fixed, though tool names and semantics can still differ.
-- Services can move behind their HTTP contracts when the replacement preserves authentication, response shape, and failure behavior.
-
-## Governed external context
-
-An MCP server advertises tools. User policy decides whether each tool is allowed, denied, or requires approval. Organization policy separately governs network egress. Read-only classification can permit low-risk reads without turning every MCP connection into a read-only connection.
-
-External data stays under the source system's own controls until an approved tool reads it. Fluso may then persist selected outputs in chat history, project files, or knowledge records according to the requested work and platform policy.
-
-<Note>
-  Storage independence here means runtime compute does not own durable state.
-  PostgreSQL, workspace storage, and the knowledge service still have explicit
-  schemas and operational contracts.
-</Note>
-
-## Next
-
-Start with [Authentication](/developers/api-ref/authentication), then create an Agent through [Agents and versions](/developers/api-ref/agents-and-versions).
diff --git a/content/docs/developers/context-isolation-in-threads.mdx b/content/docs/developers/context-isolation-in-threads.mdx
deleted file mode 100644
index 3f0fb84..0000000
--- a/content/docs/developers/context-isolation-in-threads.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: Context isolation in threads
-sidebarTitle: Context isolation
-icon: lock-keyhole
-description: Find the combined guide to thread context, isolation, and delegation.
----
-
-Context isolation now lives in [Threads and contexts](/developers/threads-and-contexts#keep-contexts-isolated).
diff --git a/content/docs/developers/evaluations.mdx b/content/docs/developers/evaluations.mdx
deleted file mode 100644
index 4a7f32e..0000000
--- a/content/docs/developers/evaluations.mdx
+++ /dev/null
@@ -1,61 +0,0 @@
----
-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.
diff --git a/content/docs/developers/examples/custom-skills.mdx b/content/docs/developers/examples/custom-skills.mdx
new file mode 100644
index 0000000..353ce82
--- /dev/null
+++ b/content/docs/developers/examples/custom-skills.mdx
@@ -0,0 +1,57 @@
+---
+title: Help with the team wiki
+icon: book-open
+description: Find the right page and improve it without losing what the team still needs.
+---
+
+A team wiki is useful only if people can find the right information. An Agent can help answer questions and keep pages clear.
+
+This example uses Confluence through an MCP connection, which lets Fluso use another app's tools. The available actions depend on that connection and your account.
+
+## Start with a question
+
+Add the connection under **Plugins → MCP**. Select it for the Agent.
+
+> *"Help our team find answers in Confluence. Read the relevant pages and link to the source. If pages disagree, point that out instead of choosing an answer for us."*
+
+Try a question with an answer you can check:
+
+> *"Where should a new colleague put customer meeting notes? Show me the page that explains it."*
+
+## Improve a page
+
+Once it can find the right material, give it a specific edit:
+
+> *"Make this team's home page easier for a new colleague to use. Explain where documents belong and keep the existing links and activity sections."*
+
+Read the proposed changes before you expand the work to other pages. Page edits need write access and follow your [approval settings](/features/approvals).
+
+## Teach it the team's method
+
+If you repeat the same guidance, ask **Manager** to save it as a **skill**. A skill is a reusable set of instructions, with supporting files when needed.
+
+> *"Save our approach to wiki updates as a skill. Read the page first, preserve useful sections, and check the links after editing. Use it for this Agent."*
+
+Check that the Agent's selected skills include it. A skill does not grant access to an app.
+
+<Accordion title="When several Agents use the same skill">
+  Custom skills are shared files in your workspace. Editing one can affect other Agents that use it.
+
+  Ask for a separate skill if the change should apply only to this Agent. Keep account credentials out of the skill's instructions and files.
+
+  You can include a custom skill when you [share an Agent](/developers/guides/sharing). Review the whole folder before sharing.
+</Accordion>
+
+<Accordion title="What about a job such as making phone calls?">
+  An Agent can use other services when you provide a working integration and account access. Calling is not built into every Agent.
+
+  For example, a phone briefing needs a calling provider, a connected account, and your permission to call the chosen number.
+
+  After you confirm that setup works:
+
+  > *"Prepare a brief for each confirmed meeting tomorrow. Call my number ten minutes before it starts and keep the briefing under two minutes."*
+
+  Agree what information it may say aloud and whether it may leave voicemail. A request accepted by the provider does not prove you heard the call.
+
+  Check scheduled calls when meetings move. Routines check at set times, so approvals, other work, and service failures can delay them. Keep a written brief available too.
+</Accordion>
diff --git a/content/docs/developers/examples/document-filing.mdx b/content/docs/developers/examples/document-filing.mdx
new file mode 100644
index 0000000..377b0bc
--- /dev/null
+++ b/content/docs/developers/examples/document-filing.mdx
@@ -0,0 +1,57 @@
+---
+title: Organize customer documents
+icon: folders
+description: Make proposals and attachments easier to find after you send them.
+---
+
+Customer documents often stay buried in sent email. An Agent can copy them into the right Google Drive folders and keep track of what it already filed.
+
+This job needs a [Google Workspace connection](/integrations/gmail) with **Allowed** access, because it writes files to Drive.
+
+## Start with one week
+
+Give the Agent a destination and a rule for uncertainty:
+
+> *"Help me organize customer documents. Copy proposals and project documents from my sent email into the Customer Documents folder in Drive. Keep the original filenames. If you can't tell which customer a file belongs to, ask me. Don't change my email."*
+
+For its first task:
+
+> *"Start with last week's sent mail. Leave out signature images and internal messages. Show me where you put each document."*
+
+Open a few saved files. Check both the content and the customer folder.
+
+## Resolve the awkward cases
+
+Two customers may have similarly named files. Some documents may not identify a customer at all.
+
+You can give it a place to keep those questions:
+
+> *"Put anything uncertain in a Needs Review folder and tell me why. Keep going with the documents you can identify."*
+
+Answer a question in the same conversation:
+
+> *"Those two proposals belong to North Studio. Move them into that customer's folder."*
+
+Ask **Manager** to save a filing rule when it should apply next time.
+
+## Make repeat work safe
+
+Ask it to keep a record of each document's source and destination:
+
+> *"Keep track of what you've filed so we don't get duplicates. If a different document has the same filename, keep both with a clear date."*
+
+A file it cannot download should stay on the unfinished list. You can provide another copy or upload it yourself.
+
+Once the first run looks right:
+
+> *"Do this every night at 3 AM Chicago time. Check new sent mail since the last completed review. Tell me about anything that still needs my help."*
+
+Check the saved timezone in **Routines**. A night with no new documents is a valid result.
+
+<Accordion title="If a run stops halfway through">
+  Ask the Agent to check its record and the destination folders before it copies anything again.
+
+  It should track individual attachments, since one email can contain several files. An empty review period still counts as checked.
+
+  Keep unresolved documents on the list even when later mail has been processed.
+</Accordion>
diff --git a/content/docs/developers/examples/email.mdx b/content/docs/developers/examples/email.mdx
new file mode 100644
index 0000000..92ac073
--- /dev/null
+++ b/content/docs/developers/examples/email.mdx
@@ -0,0 +1,65 @@
+---
+title: Stay on top of email
+icon: mail
+description: Find what needs your attention, then prepare replies you can review.
+---
+
+After a busy day, the hard part is often deciding which messages still need you.
+
+An inbox Agent can read the recent conversation, identify an unanswered request, and help you write a reply.
+
+Connect [Google Workspace](/integrations/gmail) and select it in the Agent's [app access](/developers/guides/settings#grant-app-access).
+
+## Give it a clear job
+
+In **New Agent**, describe the help you want:
+
+> *"Help me stay on top of email. Find messages that need a decision or reply from me. Explain why each one matters and suggest a response. Don't change my mailbox."*
+
+Start its working conversation with a small request:
+
+> *"Look at yesterday's mail. What still needs me? Leave out anything that was resolved later in the conversation."*
+
+The result should help you choose what to do next. Check a few source conversations, including one the Agent says needs no action.
+
+## Shape the replies
+
+Ask for a draft in the same conversation:
+
+> *"Draft a reply to this one. Thank them for the proposal and ask whether the price includes setup. Keep it warm and brief."*
+
+Then correct anything that sounds unlike you:
+
+> *"That's too formal. Make it sound like a quick reply to someone I already work with."*
+
+When you like the approach, ask **Manager** to save it:
+
+> *"Use the reply style we settled on in my main conversation. Keep drafts short and natural. Ask me before promising a date I haven't confirmed."*
+
+## Keep drafts where you need them
+
+When you want drafts in Gmail:
+
+> *"Save these replies as drafts in the original Gmail conversations. Keep everyone who needs the reply. Don't send them."*
+
+Saving drafts changes Gmail, so the connection needs **Allowed** access. Review [approval settings](/features/approvals) before you expand what the Agent can do.
+
+After a useful first review, you might ask:
+
+> *"Every weekday at 9 AM, review mail since your last check. Bring me new decisions and unfinished replies. Don't make another draft for something you've already handled."*
+
+Check the time and timezone in **Routines**.
+
+<Accordion title="Use the same approach for hiring">
+  Give a Hiring Agent the role, candidate, interview length, and calendars it may check.
+
+  > *"Draft a note asking Maya when she's free for a 30-minute interview next week. Offer Monday or Wednesday afternoon. I'll review it before sending."*
+
+  After you send it:
+
+  > *"Check for her reply every 30 minutes until Friday. When she replies, check both interviewers' calendars and draft a confirmation. Stop checking after that."*
+
+  Review the routine's timing and stopping point. If a calendar is unavailable, the Agent should ask rather than assume a free slot.
+
+  Checking a calendar does not book the interview. Decide who will send the confirmation and create the invitation.
+</Accordion>
diff --git a/content/docs/developers/examples/index.mdx b/content/docs/developers/examples/index.mdx
new file mode 100644
index 0000000..a475ba3
--- /dev/null
+++ b/content/docs/developers/examples/index.mdx
@@ -0,0 +1,28 @@
+---
+title: Find an idea
+icon: lightbulb
+description: Start with work you already know, then shape the Agent around it.
+---
+
+Think about a job you would like help with more than once. These examples start with an everyday request and show how it can grow.
+
+You can adapt the words to your own work. They are examples, not extra templates in the app.
+
+<CardGroup cols={2}>
+  <Card title="Stay on top of email" icon="mail" href="/developers/examples/email">
+    Find messages that need you, prepare replies, and follow up during hiring.
+  </Card>
+  <Card title="Organize customer documents" icon="folders" href="/developers/examples/document-filing">
+    Put emailed proposals and documents where your team can find them.
+  </Card>
+  <Card title="Find people you know" icon="users" href="/developers/examples/people-graph">
+    Turn past conversations into a useful, searchable contact map.
+  </Card>
+  <Card title="Help with the team wiki" icon="book-open" href="/developers/examples/custom-skills">
+    Find the right page, improve it, and teach the Agent your team's approach.
+  </Card>
+</CardGroup>
+
+Each job depends on the apps you connect and the access you allow. Try one useful task before you ask for a regular routine.
+
+For a longer example with separate working sessions, see [Review a launch](/developers/examples/release-review).
diff --git a/content/docs/developers/examples/meta.json b/content/docs/developers/examples/meta.json
new file mode 100644
index 0000000..14d1e45
--- /dev/null
+++ b/content/docs/developers/examples/meta.json
@@ -0,0 +1,13 @@
+{
+  "title": "Examples",
+  "icon": "lightbulb",
+  "defaultOpen": false,
+  "pages": [
+    "index",
+    "email",
+    "document-filing",
+    "people-graph",
+    "custom-skills",
+    "release-review"
+  ]
+}
diff --git a/content/docs/developers/examples/people-graph.mdx b/content/docs/developers/examples/people-graph.mdx
new file mode 100644
index 0000000..bbacdfc
--- /dev/null
+++ b/content/docs/developers/examples/people-graph.mdx
@@ -0,0 +1,65 @@
+---
+title: Find people you know
+icon: users
+description: Build a contact map you can search, correct, and keep up to date.
+---
+
+You remember talking to someone at a company, but cannot remember who. A contact map can help you find that connection.
+
+An Agent can build one from your email and give you a page to search. This is a file it creates for you, separate from Fluso's own memory.
+
+## Build a useful first version
+
+Connect [Google Workspace](/integrations/gmail). Give the Agent **Read only** access if you only want it to read mail.
+
+Describe the job:
+
+> *"Help me find people I've spoken with. Build a searchable contact map from my email, grouped by company. Show where each detail came from. Leave anything you don't know blank."*
+
+Start with recent mail:
+
+> *"Use the last month first. Give me a page where I can search by name or company. Tell me what you've covered so far."*
+
+Open the page it returns. Search for someone you know and check their details against the source email.
+
+## Ask a question that matters to you
+
+> *"Who do I know at this company? Show our recent conversations so I can decide who to contact."*
+
+Or:
+
+> *"Which of these people are based in Berlin? Keep confirmed locations separate from guesses."*
+
+A person's employer does not prove where they live. Similar names do not prove two records are the same person.
+
+Correct the map in the same conversation. Ask **Manager** to save rules that should guide future research.
+
+## Add to it over time
+
+A large mailbox can take more than one run:
+
+> *"Add the previous month's mail next. Keep the contacts you've already found. Save your progress and tell me what's still left."*
+
+Ask for the underlying data as well as the page, so the Agent can improve the same map later.
+
+When the initial review is useful:
+
+> *"Every morning at 8 AM, add anything new since your last completed check. Keep the earlier contacts and give me a short note about what changed."*
+
+Check that the routine exists and uses the right timezone. A refresh mentioned in the instructions is not yet a scheduled task.
+
+<Accordion title="Add information from public profiles">
+  With a web-search connection, you can ask for a focused check:
+
+  > *"Look for public profiles for these five contacts. Match the name and company. If a match is uncertain, leave it for me to review."*
+
+  Names and search terms go to that service. Choose which contacts you want researched.
+
+  The Agent may use a separate session for this work. It still needs to check the findings before adding them to your map.
+</Accordion>
+
+<Accordion title="Recover after an incomplete run">
+  Ask it to read the saved progress before continuing. Open the latest files to see what they contain.
+
+  A failed request may still have saved useful work. Repeated attempts will not fix missing access or a fixed limit on that run.
+</Accordion>
diff --git a/content/docs/developers/examples/release-review.mdx b/content/docs/developers/examples/release-review.mdx
new file mode 100644
index 0000000..b60def4
--- /dev/null
+++ b/content/docs/developers/examples/release-review.mdx
@@ -0,0 +1,61 @@
+---
+title: Review a launch
+icon: clipboard-check
+description: See how an Agent handles a larger job with separate checks and follow-ups.
+---
+
+A launch decision can depend on several documents: what is changing, what was checked, and what is still unresolved.
+
+An Agent can compare them and keep the open questions together as the evidence changes.
+
+## Give it the decision to help with
+
+Create a reviewer through [New Agent](/developers/agent-builder). Explain what it should check and which decisions remain yours.
+
+> *"Help me decide whether we're ready to launch. Compare the notes, test results, and open issues I share. Tell me what still blocks us and what information is missing. Don't publish anything or contact anyone."*
+
+Then attach the actual material. Explain when you need the decision and what must be true before launch.
+
+<Frame caption="The review request brings the launch brief, validation notes, and draft guides together.">
+  <a href="/images/agents/review-request.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/review-request.png" alt="A launch-review request with five attached documents from this documentation project." loading="lazy" width="1440" height="386" />
+  </a>
+</Frame>
+
+## Give different checks room to run
+
+For a larger review, you can ask:
+
+> *"Have one session check what customers will experience and another check the test results. Compare their findings with our launch requirements and bring me one recommendation."*
+
+The Agent can use separate [sessions](/developers/guides/conversations) while it works on the overall review.
+
+In our local run, two sessions checked different parts of this documentation release. The Agent recommended waiting because checks and approval were still pending. It returned a report with both sessions' findings.
+
+It also misread one progress note as a contradiction. We clarified it in the conversation, and it corrected the saved report.
+
+Read the reasoning, not only the recommendation. An earlier successful check may cover an older version of the work.
+
+## Keep the review useful as things change
+
+Give it the new evidence in the same conversation:
+
+> *"The updated test report is attached. Revise the recommendation, but keep anything we still haven't checked on the open list."*
+
+If the lesson should apply to future reviews, ask [Manager](/developers/improve) to save it.
+
+You can schedule a later check with a [one-time routine](/developers/schedules). That brings the review back at a useful time without creating another conversation.
+
+<Accordion title="What happened in the scheduled follow-up?">
+  The routine reread the saved report and validation notes. It found no new evidence, so it kept the unresolved checks open.
+
+  <Frame caption="The routine returned to the same conversation and kept the pending decisions visible.">
+    <a href="/images/agents/routine-result.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+      <img src="/images/agents/routine-result.png" alt="A compact routine message and its completed follow-up in the Agent conversation." width="1760" height="1016" />
+    </a>
+  </Frame>
+
+  Its result appeared in Inbox. The routine did not approve or publish the release.
+</Accordion>
+
+The screenshots show real responses to this documentation project's files. The example requests above are wording you can adapt to your own launch.
diff --git a/content/docs/developers/export-import-and-share-agents.mdx b/content/docs/developers/export-import-and-share-agents.mdx
deleted file mode 100644
index 7bae0a0..0000000
--- a/content/docs/developers/export-import-and-share-agents.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: Export, import, and share Agents
-sidebarTitle: Export, import & share
-icon: share-2
-description: Find the combined guide to Agent versions, export, import, and sharing.
----
-
-Export, import, and sharing now live in [Agent versions](/developers/versions#move-an-agent-between-workspaces).
diff --git a/content/docs/developers/guides/conversations.mdx b/content/docs/developers/guides/conversations.mdx
new file mode 100644
index 0000000..161a483
--- /dev/null
+++ b/content/docs/developers/guides/conversations.mdx
@@ -0,0 +1,78 @@
+---
+title: Longer tasks and sessions
+icon: messages-square
+description: Keep a task moving as it grows or changes.
+---
+
+Your usual chat with an Agent is its **main conversation**. Keep using it as you add information, ask questions, or change direction.
+
+## Add a correction while it works
+
+You can send another message before the Agent finishes:
+
+> *"One change: the workshop now has 24 attendees. Please use that number when comparing the rooms."*
+
+The message waits above the composer for its own turn. **Edit** changes it. **Cancel** removes it.
+
+Choose **Send now** to bring the correction into the work already running. If that work just finished, the message starts a new turn.
+
+A message with changed Agent setup may show **Saved setup applies next turn** instead. It waits rather than changing the active work.
+
+## Let it divide a larger job
+
+Some jobs have parts that can be checked independently. An Agent can work on them in separate conversations called **sessions**.
+
+For example, one session might check venue offers while another checks the budget. The main conversation can work on the overall recommendation and bring the findings together.
+
+You usually keep talking to the main conversation. You do not need to manage each session yourself.
+
+For a real example, see [Review a launch](/developers/examples/release-review).
+
+## Inspect sessions when useful
+
+Open **Sessions** above the composer to see their progress. Select one to read its assignment and answers. **Main conversation** takes you back.
+
+**New result** marks a result you have not read. **Uses an earlier setup** means the session started before a saved change to the Agent.
+
+<Frame className="mx-auto max-w-lg" caption="Both reviews remain available after completion. They use the Agent's earlier setup.">
+  <a href="/images/agents/sessions-list.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/sessions-list.png" alt="The Sessions list shows Reader journey review and Validation evidence review as idle, both using an earlier setup." loading="lazy" width="640" height="300" />
+  </a>
+</Frame>
+
+The Agent can reuse sessions, give them corrections, and cancel work it no longer needs. Requested results return automatically.
+
+<AccordionGroup>
+  <Accordion title="What does a new session know?">
+    A **fresh** session starts with its assignment and the inputs it needs.
+
+    A **forked** session also gets completed conversation context from the point where it starts. A fork icon identifies it.
+
+    Both can use shared files and project memory. They keep the Agent setup chosen at creation. Later messages and setup changes do not automatically reach them.
+
+    A fork does not copy running work or routines. A session cannot create further sessions.
+  </Accordion>
+  <Accordion title="Keep, archive, or delete a session">
+    An idle session has no active work. The Agent can reuse it, or a routine can wake it later.
+
+    The session menu lets you rename, archive, restore, or delete it. Archiving organizes the list. It does not pause routines.
+
+    Deleting a session also removes its routines. Keep any results you still need first.
+
+    The main conversation cannot be archived or deleted on its own. Deleting its project removes it. Manager is separate from the Sessions list.
+  </Accordion>
+</AccordionGroup>
+
+## Stop or continue safely
+
+**Stop** stops the current run and pauses messages you queued. A failed run also pauses those messages. Use **Send now** when you want to continue.
+
+Stopping one run does not stop separate sessions or pause future routines. Queued routine messages and returned session results can still start work.
+
+For a failed task, read the error and check anything already saved or changed:
+
+> *"Check what you finished before the error. Continue with the remaining work, and tell me if anything needs my help."*
+
+Retrying does not undo earlier actions. You can leave the app while server work continues, and reopening it does not discard queued messages.
+
+If a session needs approval, review the action in that session, the main conversation, or [Inbox](/developers/guides/inbox). A session's report cannot approve an action for you.
diff --git a/content/docs/developers/guides/files.mdx b/content/docs/developers/guides/files.mdx
new file mode 100644
index 0000000..2e85b42
--- /dev/null
+++ b/content/docs/developers/guides/files.mdx
@@ -0,0 +1,69 @@
+---
+title: Files and memory
+icon: folder-open
+description: Give your Agent the right references and keep its work in a useful place.
+---
+
+For one task, paste the information into the conversation or attach a file. For work you return to, it helps to decide what should stay available.
+
+## Keep the work in a project
+
+**Home** is the default project. You can choose another project when you create an Agent, such as one for a customer or an ongoing project.
+
+That is where its main conversation starts. Changing the project setting later does not move the conversation or its files.
+
+Projects help organize work. Agents in your account can still use shared files elsewhere in your workspace.
+
+## Save a reference it should keep
+
+Add files under **Knowledge** in the Agent editor for material it should use repeatedly. A writing guide, review checklist, or agreed policy can fit here.
+
+<Frame caption="A saved checklist stays attached for future meeting briefs.">
+  <a href="/images/agents/knowledge-files.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/knowledge-files.png" alt="The Knowledge section contains Meeting brief checklist.md and an Add files control." loading="lazy" width="1424" height="402" />
+  </a>
+</Frame>
+
+You can also ask Manager to attach an existing workspace file:
+
+> *"Use our meeting checklist as a reference for future briefs. Keep it attached to this Agent."*
+
+Knowledge files are copies. Editing the original does not update the attached copy. Attach and save a replacement when the reference changes.
+
+Keep changing work, such as a contact list or draft report, in project files instead. The Agent can keep updating the same work there.
+
+## Tell it what should stay consistent
+
+Save your usual way of working in the Agent's instructions through [Manager](/developers/improve).
+
+Agents use those instructions instead of automatically adopting the preferences and project instructions from ordinary chats.
+
+Your conversation still gives the Agent context for the current work. For a long task, ask it to save its progress in a file:
+
+> *"Save what you've finished and what is still open, so we can continue from here next time."*
+
+Open any delivered file before relying on it. Check that it contains the work you asked for.
+
+<AccordionGroup>
+  <Accordion title="What else can it remember?">
+    Agents receive saved facts from `user_profile.md`. They can use project files and summaries of recent work in that project.
+
+    They do not automatically load ordinary-chat preferences, project instructions, or `context.md` as their own instructions.
+
+    Long conversations may be summarized. A separate fresh session does not receive the full conversation history. See [Longer tasks and sessions](/developers/guides/conversations).
+  </Accordion>
+  <Accordion title="Reference file limits and older sessions">
+    An Agent can have up to 25 knowledge files, each up to 20 MiB, within your storage allowance.
+
+    Removing a reference from the current setup does not remove its older copy from a session created earlier.
+  </Accordion>
+  <Accordion title="What happens when I delete an Agent or project?">
+    Deleting an Agent removes its knowledge copies and conversations. Separate project files remain.
+
+    Deleting a project removes its files, conversations, and their routines. The Agent's saved setup remains.
+
+    If the Agent still points to that deleted project, choose another **Project** in its setup before opening a new main conversation. Deleted history does not return.
+  </Accordion>
+</AccordionGroup>
+
+See [Projects](/features/projects) for browsing, downloading, and exporting files.
diff --git a/content/docs/developers/guides/inbox.mdx b/content/docs/developers/guides/inbox.mdx
new file mode 100644
index 0000000..b85142c
--- /dev/null
+++ b/content/docs/developers/guides/inbox.mdx
@@ -0,0 +1,39 @@
+---
+title: Inbox
+icon: inbox
+description: See what needs you without opening every Agent.
+---
+
+Open **Inbox** in the Agents sidebar to find approvals, failures, and routine results.
+
+Choose **Open result** to return to the conversation. Read the answer and open any files it produced.
+
+<Frame caption="A completed routine appears in Inbox with a link to its conversation.">
+  <a href="/images/agents/inbox-result.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/inbox-result.png" alt="Inbox showing a completed routine and an Open result link." width="1536" height="524" />
+  </a>
+</Frame>
+
+## When something needs your attention
+
+For an approval, read the requested action before allowing or denying it.
+
+For a failure, check the error and any work already completed before retrying. A routine delivery failure may need a change in **Routines**.
+
+The number beside **Inbox** counts unseen updates. Opening Inbox clears the unread state of displayed updates. It does not approve actions or resolve failures.
+
+## Find a particular update
+
+Use **Filters** to choose an Agent or show only approvals, failures, or routine results.
+
+An empty filtered list means nothing matches that view. It does not mean all work is complete.
+
+<Accordion title="More about filters and unread counts">
+  The sidebar opens **All updates**. A direct link without filters, or resetting filters, opens **Approvals & failures**.
+
+  Inbox shows recent updates rather than a complete history. Separate session results stay in their conversations, but their approvals can appear here.
+
+  Only updates displayed in a visible Inbox tab become seen. Filtered-out items keep their unread state. A changed update can become unread again.
+
+  Read state is shared across tabs in this browser. It does not sync across devices. Signing out or switching accounts clears it.
+</Accordion>
diff --git a/content/docs/developers/guides/meta.json b/content/docs/developers/guides/meta.json
new file mode 100644
index 0000000..1e783ed
--- /dev/null
+++ b/content/docs/developers/guides/meta.json
@@ -0,0 +1,12 @@
+{
+  "title": "More about Agents",
+  "icon": "book-open",
+  "defaultOpen": false,
+  "pages": [
+    "settings",
+    "files",
+    "conversations",
+    "inbox",
+    "sharing"
+  ]
+}
diff --git a/content/docs/developers/guides/settings.mdx b/content/docs/developers/guides/settings.mdx
new file mode 100644
index 0000000..258a6d8
--- /dev/null
+++ b/content/docs/developers/guides/settings.mdx
@@ -0,0 +1,81 @@
+---
+title: Settings and app access
+icon: sliders-horizontal
+description: Choose what your Agent can use and how it should respond.
+---
+
+Select the **Edit agent** pencil in a conversation to open its setup. **Edit** lets you change the fields yourself. **Manager** lets you describe the change in conversation.
+
+For changes to its usual way of working, start with [Improve your Agent](/developers/improve).
+
+## Give it the tools it needs
+
+**Skills** help an Agent do particular kinds of work, such as reading a PDF or making a spreadsheet.
+
+**Connectors** let it use apps you connect, such as Google Workspace. A meeting assistant working from pasted notes may need no connected apps.
+
+Choose what the job needs. You can add more later.
+
+<Frame className="mx-auto max-w-xl" caption="Meeting Prep uses the Meeting intelligence skill. This example needs no connected apps.">
+  <a href="/images/agents/agent-capabilities.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/agent-capabilities.png" alt="The Capabilities picker shows Meeting intelligence selected, with one skill and no connectors." loading="lazy" width="1152" height="1280" />
+  </a>
+</Frame>
+
+## Grant app access
+
+Connect your account under **Plugins → MCP**, then select the connection in the Agent's setup.
+
+| Choice | What it means |
+| --- | --- |
+| **Allowed** | The Agent can use the connection, subject to your account access and approval rules |
+| **Read only** | It can use tools identified as reads |
+| Not selected | It cannot use that connection through its app tools |
+
+A newly added connection defaults to **Allowed**. Existing read-only choices stay in place until you change them. Selecting no connections grants none.
+
+For an email assistant, reading mail and saving drafts need different access. Saving a draft is a change to Gmail.
+
+Ask for drafts when you want to review a message before anyone receives it. Check [Approvals and permissions](/features/approvals) to choose when tools should ask.
+
+<Accordion title="Why does an allowed app still need setup or approval?">
+  **Allowed** selects an app the Agent may use. You still need to connect your account, and the requested action must pass its permission rules.
+
+  A saved tool deny or an organization restriction still applies. Changing the Agent's instructions cannot supply missing access.
+</Accordion>
+
+## Choose its response style
+
+**High** gives more room for careful reasoning. **Fast** favors quicker responses.
+
+Set this in the Agent's setup. Its main conversation follows that choice.
+
+## Add useful references
+
+Use **Knowledge** in the editor for a document the Agent should keep as a reference, such as a meeting checklist or writing guide.
+
+The attachment is a saved copy. Replace it when the reference changes. See [Files and memory](/developers/guides/files).
+
+<AccordionGroup>
+  <Accordion title="Names, instructions, and conversation starters">
+    The first line of the instructions appears as the Agent's short purpose in lists. Expand **Instructions** to read the full text.
+
+    Names must be unique in your library and can contain up to 64 characters. Instructions allow 4,000 characters.
+
+    You can add three conversation starters, each up to 200 characters. They are suggestions to select, not messages that run automatically.
+  </Accordion>
+  <Accordion title="Which skills are selected by default?">
+    An Agent created through the form starts with all available skills. You can choose fewer, or turn them all off. An unrestricted selection includes skills installed later.
+
+    Manager and Fluso starting points choose skills for the job. Check the saved selection.
+
+    Custom skills are shared workspace files. Editing one can affect other Agents that use it.
+  </Accordion>
+  <Accordion title="When saved changes take effect">
+    Your main conversation uses the changed setup on its next turn. Work already running and existing separate sessions keep their earlier setup.
+
+    Changing **Project** does not move existing conversations or files.
+
+    If another tab changed the setup first, Fluso asks you to review the latest version before saving. Check those changes before trying again.
+  </Accordion>
+</AccordionGroup>
diff --git a/content/docs/developers/guides/sharing.mdx b/content/docs/developers/guides/sharing.mdx
new file mode 100644
index 0000000..4d961c3
--- /dev/null
+++ b/content/docs/developers/guides/sharing.mdx
@@ -0,0 +1,64 @@
+---
+title: Share an Agent
+icon: share-2
+description: Give someone a copy of an approach that works for you.
+---
+
+Once an Agent helps you reliably, you can share its setup with someone else. They get their own copy to try and improve.
+
+Your conversations, routines, project files, and connected account credentials are not included.
+
+## Choose what to share
+
+1. Open the Agent's actions menu.
+2. Select **Share**.
+3. Choose any reference files, custom skills, or custom connection URLs to include.
+4. Select **Create public link**.
+
+Instructions and settings are included. Anyone with the link can read the published setup and import it.
+
+Read the selected files and skill folders before publishing. Check connection URLs too: a URL can itself contain private information or an access key.
+
+<Frame className="mx-auto max-w-lg" caption="Choose the reference files to include. Review them before creating the link.">
+  <a href="/images/agents/share-options.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/share-options.png" alt="The Share Agent dialog has the meeting checklist selected and explains what the public link includes." loading="lazy" width="1024" height="804" />
+  </a>
+</Frame>
+
+## Update or close the link
+
+Private edits stay private until you select **Update shared version**. That publishes your current setup at the same link.
+
+**Stop sharing** closes the link. Deleting the Agent also closes it. Copies people already imported remain theirs.
+
+## Use someone else's Agent
+
+Open the share link to read its setup. **Import Agent** opens Fluso, where you choose a name and project. **Get Fluso** helps if the app is not installed.
+
+You can also paste the link under **New Agent → Import from a shared link**.
+
+Manager helps finish setup with your own accounts. Try a real task before scheduling it.
+
+<AccordionGroup>
+  <Accordion title="What happens to files, skills, and connections?">
+    Selected reference files and custom skill folders are copied. Imported custom skills get distinct names so they do not overwrite yours.
+
+    Built-in skills use your installed versions. Reference files the owner did not include are listed by name, so you know what is missing.
+
+    Selected custom connections include their definitions and URLs, not stored authentication. You still authorize your own accounts. Some public connections that need no sign-in can be registered during import.
+
+    Selected files and skill contents share limits of 20 MiB and 512 files. Symbolic links and custom connection URLs with query parameters cannot be included.
+  </Accordion>
+  <Accordion title="What if the shared setup changes?">
+    If it changes while you review it, Fluso asks you to review the new version before importing.
+
+    A closed link cannot be imported. An older incompatible link may need its owner to publish it again.
+  </Accordion>
+  <Accordion title="Make a copy just for yourself">
+    Use **Duplicate** in the Agent's actions menu. It copies the setup and knowledge files into your library, with no conversations or routines.
+
+    You can star a useful Agent or change its appearance from the same menu.
+  </Accordion>
+</AccordionGroup>
+
+For working files you want to pass along separately, use [project export](/features/projects#export-a-project).
diff --git a/content/docs/developers/improve.mdx b/content/docs/developers/improve.mdx
new file mode 100644
index 0000000..e7f51b0
--- /dev/null
+++ b/content/docs/developers/improve.mdx
@@ -0,0 +1,55 @@
+---
+title: Improve your Agent
+icon: pencil
+description: Keep the parts that help, and change the parts that don't.
+---
+
+Your first request is a starting point. A few real tasks will show you what you want the Agent to do differently.
+
+## Change the answer in front of you
+
+Use the Agent's conversation for a correction to the current task:
+
+> *"This is more detail than I need before the meeting. Put the decisions first and keep the background to a few lines."*
+
+You can keep working there until the answer is useful.
+
+## Make that your usual way of working
+
+Use **Manager** when you want the Agent to follow that preference in future work.
+
+1. Select the **Edit agent** pencil in the conversation.
+2. Choose **Manager** on the setup page.
+3. Explain what you want to keep.
+
+> *"For future meeting briefs, put the decisions first. Keep the background short, and finish with three questions I should ask. Save that as my usual format."*
+
+Read the saved instructions beside the conversation. Then return to the Agent and give it another task.
+
+<Frame caption="Manager confirms that the new format is saved for future briefs.">
+  <a href="/images/agents/meeting-refinement.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/meeting-refinement.png" alt="A request to put decisions first, followed by Manager's confirmation that it saved the format." loading="lazy" width="1600" height="1208" />
+  </a>
+</Frame>
+
+The change applies to its next turn. Work already underway keeps the setup it started with.
+
+## Be specific about what missed the mark
+
+Tell the Manager what happened and what you wanted instead:
+
+> *"The last brief made lunch sound confirmed, but we haven't chosen it. Keep undecided plans clearly marked as open questions."*
+
+This gives it a useful rule to save. You can also ask it to review corrections from the working conversation.
+
+Prefer to make the change yourself? **Edit** opens the saved fields. There is no version-history screen, so explain what to restore if you want to undo a change.
+
+[Settings and app access](/developers/guides/settings) explains the other controls, including response style, files, and connected apps.
+
+<Accordion title="What if work is already running?">
+  A new message with changed setup may show **Saved setup applies next turn**. It waits for a separate turn.
+
+  Sessions the Agent already created keep their earlier setup. Give them a correction if they need one. See [Longer tasks and sessions](/developers/guides/conversations).
+
+  A routine keeps its own saved message. Review that message if you change how the Agent should work.
+</Accordion>
diff --git a/content/docs/developers/index.mdx b/content/docs/developers/index.mdx
new file mode 100644
index 0000000..51a50eb
--- /dev/null
+++ b/content/docs/developers/index.mdx
@@ -0,0 +1,37 @@
+---
+title: Agents
+icon: bot
+description: Give a familiar job to an assistant you can keep coming back to.
+---
+
+Some work comes around again and again: preparing for a meeting, catching up on email, or organizing customer documents.
+
+An Agent keeps the instructions for that job. You give it new work in the same conversation, and improve how it helps as you go.
+
+## Start with a job you know
+
+You might want an inbox assistant that helps you answer important messages, or a meeting assistant that turns scattered notes into a useful brief.
+
+Choose something small enough that you can tell whether the answer helped.
+
+<Card title="Create your first Agent" icon="arrow-right" href="/developers/agent-builder">
+  Make a meeting assistant, give it a few notes, and try a follow-up.
+</Card>
+
+Prefer another starting point? [Browse the examples](/developers/examples).
+
+## Come back when you need it
+
+**My Agents** brings your assistants together and shows upcoming routines. Open an Agent to continue its conversation.
+
+<Frame caption="Return to a conversation, or see which Agent has work coming up.">
+  <a href="/images/agents/my-agents.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/my-agents.png" alt="My Agents shows Meeting Prep and Release Reviewer, with a morning routine coming up for Meeting Prep." loading="lazy" width="1280" height="600" />
+  </a>
+</Frame>
+
+As you use it, you can [improve its usual approach](/developers/improve), [schedule a task](/developers/schedules), or [share a copy](/developers/guides/sharing).
+
+<Accordion title="I don't see Agents in Fluso">
+  These guides show Fluso Dev. If **Agents** is missing from your sidebar, your version of Fluso does not have it enabled.
+</Accordion>
diff --git a/content/docs/developers/meta.json b/content/docs/developers/meta.json
index e2a141f..550ecd7 100644
--- a/content/docs/developers/meta.json
+++ b/content/docs/developers/meta.json
@@ -1,18 +1,11 @@
 {
   "pages": [
+    "!index",
+    "[bot][Overview](/developers)",
     "agent-builder",
-    "agent-description",
-    "evaluations",
-    "versions",
-    "api-ref",
-    "architecture",
-    "project-context",
+    "improve",
     "schedules",
-    "threads-and-contexts",
-    "user-preferences",
-    "webhooks",
-    "!context-isolation-in-threads",
-    "!export-import-and-share-agents",
-    "!parent-and-child-threads"
+    "examples",
+    "guides"
   ]
 }
diff --git a/content/docs/developers/parent-and-child-threads.mdx b/content/docs/developers/parent-and-child-threads.mdx
deleted file mode 100644
index 5f80220..0000000
--- a/content/docs/developers/parent-and-child-threads.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: Parent and child threads
-sidebarTitle: Parent & child threads
-icon: git-fork
-description: Find the combined guide to thread context, isolation, and delegation.
----
-
-Parent and child threads now live in [Threads and contexts](/developers/threads-and-contexts#use-parent-and-child-threads).
diff --git a/content/docs/developers/project-context.mdx b/content/docs/developers/project-context.mdx
deleted file mode 100644
index 068d467..0000000
--- a/content/docs/developers/project-context.mdx
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Project context
-sidebarTitle: Project context
-icon: folder-open
-description: See how an Agent's configured project affects files, working memory, and new threads.
----
-
-Every Agent is assigned to one project. New Agent threads start in that project and use its files and project working-memory summaries.
-
-Changing the Agent's project affects new threads. Existing threads stay with the project and Agent definition they started with.
-
-## Three project layers
-
-Fluso keeps three project concepts separate:
-
-| Layer | What it contains | Saved Agent threads |
-| --- | --- | --- |
-| Project instructions | Standing behavior for ordinary project chats | Not applied |
-| `context.md` | Durable project notes, conventions, and decisions | Not applied as Agent instructions |
-| Project working memory | Short summaries of recent work across project threads | Available |
-
-Saved Agent threads skip project instructions and `context.md` so those files cannot silently override the Agent's own definition. Put Agent-specific rules in **Instructions**. Add stable reference material as Agent knowledge files.
-
-The project still matters. Its files are available to the Agent, and short summaries from other project threads can provide useful background. Those summaries are context, not a command to continue old work.
-
-## Choosing a project
-
-Use a dedicated project when the Agent should work with one customer's files, one product area, or one set of deliverables. Use **Home** when no narrower file or memory scope is needed.
-
-## Next
-
-See [Projects](/features/projects) for the product workflow, [User preferences](/developers/user-preferences) for the other ordinary-chat layer that saved Agents skip, or [Files and projects](/developers/api-ref/files-and-projects) for project APIs.
diff --git a/content/docs/developers/schedules.mdx b/content/docs/developers/schedules.mdx
index 687f532..f8cd5f2 100644
--- a/content/docs/developers/schedules.mdx
+++ b/content/docs/developers/schedules.mdx
@@ -1,41 +1,94 @@
 ---
-title: Schedules
-sidebarTitle: Schedules
+title: Schedule a task
 icon: calendar-clock
-description: Wake an existing Agent thread with a saved message once or on a recurring schedule.
+description: Ask an Agent to help at a time you choose.
 ---
 
-A schedule saves a future message for one existing Agent thread. When it becomes due, Fluso sends that message to the same thread as a separate follow-up turn.
+Once a task is useful, you can schedule it. Fluso calls a scheduled message a **routine**.
 
-A schedule does not create a new Agent or a new conversation. It wakes the thread with its saved Agent definition, history, and project scope.
+A routine can run once or repeat. It returns to the same conversation, and you do not need to leave Fluso open.
 
-To create or manage schedules from an Agent chat, enable thread management for that Agent.
+## Tell it what to do and when
 
-## One-time and recurring schedules
+Ask in the Agent's working conversation:
 
-Ask the Agent in plain language:
+> *"Tomorrow at 8 AM, review the workshop notes in this chat. Tell me what still needs a decision before the meeting."*
 
-> *"Tomorrow at 9:00 AM Asia/Kolkata, check whether the release blockers are closed and prepare a status update."*
+For repeat work, be clear about what should change each time:
 
-> *"Every weekday at 9:30 AM Europe/London, review new P0 and P1 escalations and prepare the triage list."*
+> *"Every weekday at 9 AM, review mail since your last check. Show me what needs a reply and draft responses here. Don't send anything."*
 
-One-time schedules use a future date and time with an offset. Recurring schedules use a standard five-field cron expression and an IANA time zone.
+For that email example, the Agent needs your [Google Workspace connection](/integrations/gmail).
 
-## What to put in the saved message
+Check the saved time and timezone in **Routines**. If the timing could be ambiguous, include your timezone in the request.
 
-The message should still make sense when it runs later. Include:
+## Set it yourself
 
-- The condition to check or work to perform.
-- The source the Agent should read.
-- The expected output.
-- Any approval boundary before an external action.
+Open **Routines** in the Agents sidebar, or use the routine control in the conversation. Write the message, choose the Agent, and set the time.
 
-## Manage a schedule
+You can choose one time, daily, weekdays, weekly, or a repeating interval.
 
-Ask the Agent to list, pause, resume, change, or delete schedules for the current thread. Deleting the target thread also removes its schedules.
+<Frame className="mx-auto max-w-xl" caption="Choose the message, time, timezone, and Agent before you create the routine.">
+  <a href="/images/agents/routine-editor.png" target="_blank" rel="noreferrer" title="Open full-size image in a new tab">
+    <img src="/images/agents/routine-editor.png" alt="A one-time routine for Meeting Prep at 8 AM in Europe/Zurich, asking it to review the workshop's open decisions." loading="lazy" width="576" height="720" />
+  </a>
+</Frame>
 
-If a recurring turn is still queued, running, or waiting for approval, Fluso does not pile up duplicate occurrences. Repeated failures can pause a schedule so it does not keep retrying without attention.
+Request work in the Agent's working conversation. A routine you request in **Manager** is for reviewing the Agent's setup.
 
-## Next
+## Find the result
 
-Use [Schedules](/developers/api-ref/schedules) for the REST endpoints, [Webhooks](/developers/webhooks) for event-driven turns, and [Runs](/developers/api-ref/runs) to inspect each accepted turn.
+The scheduled message appears as a small row in the conversation. Expand it if you want to read its instructions.
+
+The answer stays in that conversation. You can also find routine results in [Inbox](/developers/guides/inbox).
+
+If the Agent is busy, the routine waits. If it needs an approval, it waits for your decision.
+
+## Change or stop it
+
+Pause a routine to stop future occurrences. Edit it to change the message or timing. Delete it when you no longer need it.
+
+Use **Cancel run** for an occurrence that is already queued, running, or waiting for approval. Pausing a routine does not cancel work already sent to the conversation.
+
+For a temporary check, give it a stopping point:
+
+> *"Check for a reply every 30 minutes until Friday. Stop checking when a reply arrives."*
+
+Check that the Agent pauses or deletes the routine when that condition is met. The instruction is not an automatic expiry setting.
+
+<AccordionGroup>
+  <Accordion title="When a routine doesn't finish">
+    Open its conversation to see what happened. It may be waiting behind other work or asking for approval.
+
+    For a failure, check any partial result before trying again. A one-time routine stops scheduling after its message is accepted, even if the later work fails.
+
+    **Last run dispatched · outcome unavailable** means delivery is recorded, but completion is unknown.
+
+    A usage limit delays the routine. Repeated delivery failures can pause it. Fix the reported problem before resuming.
+  </Accordion>
+  <Accordion title="How timing and repeat runs work">
+    An earlier occurrence of the same routine must finish before another can proceed. This includes queued work and approval waits.
+
+    Temporary delivery failures retry with delays. Delayed recurring routines do not replay every missed time.
+
+    Choose a future time for a one-time routine. The editor rejects local times skipped by daylight-saving changes. Check the timezone and next-run time before saving.
+
+    Existing custom timing stays unchanged unless you change the frequency.
+  </Accordion>
+  <Accordion title="Schedule work for several Agents">
+    On **Routines**, you can apply the same message and timing to several Agents. Each gets its own routine.
+
+    **Select all** covers the Agents currently in the picker. It does not include Agents created later.
+
+    Matching routines appear together. Changing or deleting one Agent's assignment leaves the others in place. The editor reports any assignments it could not save, so you can retry those alone.
+
+    An Agent already using the same instructions at another time needs an explicit selection to add another timing.
+  </Accordion>
+  <Accordion title="Routines in separate sessions">
+    Open the session and use its routine control. The sidebar editor targets the Agent's main conversation.
+
+    A session's routine uses that session's saved setup. A routine in the main conversation uses the setup selected for its new turn.
+
+    Deleting a session removes its routines. Archiving it does not pause them. Deleting an Agent removes all its routines.
+  </Accordion>
+</AccordionGroup>
diff --git a/content/docs/developers/threads-and-contexts.mdx b/content/docs/developers/threads-and-contexts.mdx
deleted file mode 100644
index 1c7f10e..0000000
--- a/content/docs/developers/threads-and-contexts.mdx
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: Threads and contexts
-sidebarTitle: Threads & contexts
-icon: messages-square
-description: Understand which Agent settings, conversation history, project data, and files reach each thread.
----
-
-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 |
-| --- | --- | --- |
-| Agent definition | Saved Agent configuration | Captured when the thread starts |
-| Conversation history | One thread | Starts empty |
-| Agent knowledge files | Agent configuration | The configured list is captured at start |
-| Project files | Configured project | Shared with other threads in that project |
-| Project working memory | Configured project | Recent summaries can be recalled |
-| Child task message | One child thread | Only the sent message is added, not the parent transcript |
-
-The Agent definition includes its name, description, goal, instructions, allowed capabilities, project, and knowledge files. Editing that setup changes new threads. Existing threads keep the configuration they started with.
-
-## Ordinary chat context is different
-
-Ordinary project chats can use global user preferences, project instructions, and `context.md`. Saved Agent threads use the Agent's saved definition instead. They can still use project files and working-memory summaries shared by the project.
-
-## Keep contexts isolated
-
-### What stays in one thread
-
-- Its messages and attached-file references.
-- In-progress turn state and temporary session data.
-- The Agent definition captured when the thread started.
-
-A new thread does not receive another thread's conversation history.
-
-### What threads can share
-
-Threads started from the same Agent can use the same knowledge files and capabilities. Threads in the same project can also use its files and short working-memory summaries. If two threads edit the same resource at once, their changes can conflict.
-
-### When to start a new thread
-
-Start one when the topic or customer changes, when a task needs its own history, or when independent work can progress separately. Keep the current thread when the next step depends on its full conversation.
-
-## Use parent and child threads
-
-A top-level Agent thread can create direct child threads for separate tasks. Each child receives a bounded task and works in its own conversation. The hierarchy has one level: a parent can create several children, but a child cannot create another child.
-
-### Choose when children are created
-
-| Setting | Behavior |
-| --- | --- |
-| Off | The Agent cannot manage other threads. |
-| Explicit | The Agent creates a child only when you ask or its instructions require one. This is the default. |
-| Proactive | The Agent may create direct children for distinct tasks that can progress independently. |
-
-### Give a child enough context
-
-A child sees the task message, not the parent's transcript. Include the task, source material, constraints, approval boundaries, and expected result. Its final result returns to the parent automatically; only the parent that created it can send follow-up work, cancel it, or delete it.
-
-### Work in parallel safely
-
-Use separate children for read-only research or changes to different outputs. Keep changes to the same files or shared APIs in one thread, then combine the work there.
-
-## Pick the right scope
-
-- Put stable Agent behavior in **Instructions**.
-- Put read-only reference material in Agent knowledge files.
-- Put finished and working files in the configured project.
-- Start a new thread for a clean conversation.
-- Use a child thread only when the task can progress with the context you send it.
-
-## Related guides
-
-Read [Project context](/developers/project-context) and [User preferences](/developers/user-preferences) for the remaining context boundaries. See [Threads and messages](/developers/api-ref/threads-and-messages) for the public thread API.
diff --git a/content/docs/developers/user-preferences.mdx b/content/docs/developers/user-preferences.mdx
deleted file mode 100644
index 106762f..0000000
--- a/content/docs/developers/user-preferences.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: User preferences
-sidebarTitle: User preferences
-icon: sliders-horizontal
-description: Understand where global preferences are stored and why saved Agent threads use their own instructions instead.
----
-
-Global user preferences live in `/preferences.md` in your Fluso workspace. Ordinary chats use that file as background for choices such as response style, preferred sources, or a standing sign-off.
-
-> *"Remember that I prefer concise status updates."*
-
-After a turn ends, Fluso may save a preference that you stated clearly. A passing remark may not change future behavior.
-
-## Saved Agents are separate
-
-Saved Agent threads do not load global preferences as instructions. This keeps an Agent's standing rules from changing because an unrelated chat wrote a different preference.
-
-Use these scopes instead:
-
-| Need | Put it here |
-| --- | --- |
-| A rule for every new thread of one Agent | Agent **Instructions** |
-| A correction for the current request only | Your message in that thread |
-| A preference for ordinary chats | `/preferences.md` |
-| Reference material for an Agent | Agent knowledge files |
-
-A direct request in an Agent thread can change the current response, but it does not rewrite the saved Agent definition. Edit the Agent and start a new thread when the change should persist for that Agent.
-
-## Read or edit the file
-
-Ask Fluso what it remembers about your preferences, or open `/preferences.md` through the workspace file tools. Do not store passwords, tokens, or other secrets there.
-
-## Next
-
-See [Agent description](/developers/agent-description) for the saved definition or [Files and projects](/developers/api-ref/files-and-projects) for the file API.
diff --git a/content/docs/developers/versions.mdx b/content/docs/developers/versions.mdx
deleted file mode 100644
index 38ac4bc..0000000
--- a/content/docs/developers/versions.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Agent versions
-sidebarTitle: Agent versions
-icon: git-compare-arrows
-description: Review, restore, export, import, and share an Agent's saved setup.
----
-
-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, recreate the settings you need in the editor, choose a current project, and save them as a new version. If the Agent changed in another browser tab, refresh the history, review the newest version, and retry.
-
-### Example: restore severity rules
-
-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.
-
-## Move an Agent between workspaces
-
-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. The file contains the portable Agent fields and saved workflow, but leaves out workspace identities, secrets, deliveries, project ownership, and knowledge-file contents. It lists omitted knowledge files so the recipient knows what to add again.
-
-If the Agent relies on a project, [export that project as a ZIP](/features/projects#export-a-project) separately to carry its files, `context.md`, and metadata.
-
-### Import a copy
-
-Select **Import Agent** and choose a Fluso Agent YAML, YML, or JSON definition. Fluso opens a new draft in **Home**; it does not overwrite the Agent whose menu you used.
-
-Before creating the copy, review its instructions, select the destination project, add its knowledge files, and reconnect its Apps. Named skills remain references and must exist in the destination workspace. If the source Agent could use every skill, the imported copy starts with no skills selected; choose the skills it should use.
-
-Agent definition files are limited to 128 KB. Fluso rejects an incomplete definition or unsupported format version instead of creating a partial Agent.
-
-### Share a review link
-
-Select **Share**, then **Copy link**. Anyone with the link can review the read-only definition and import a separate copy.
-
-The definition is stored in the link itself, so the link cannot be revoked. Anyone who keeps it can reopen that snapshot. Share it only with people who may read the Agent's instructions and setup. Later edits do not update the link or an imported copy; create a new link for a newer snapshot.
-
-For a customer escalation Agent, send the support lead a review link or exported definition. They can inspect the P0/P1 rules, import a copy, connect their own Gmail and Slack access, add their runbook, and test it without changing your Agent or threads.
-
-For project and conversation imports, see [Imports](/features/imports). Those imports bring context and files into projects; they are separate from importing an Agent definition.
-
-For API-based version updates, see [Agents and versions](/developers/api-ref/agents-and-versions).
diff --git a/content/docs/developers/webhooks.mdx b/content/docs/developers/webhooks.mdx
deleted file mode 100644
index f42ce0e..0000000
--- a/content/docs/developers/webhooks.mdx
+++ /dev/null
@@ -1,120 +0,0 @@
----
-title: Webhooks
-sidebarTitle: Webhooks
-icon: webhook
-description: Send authenticated JSON events into an Agent and inspect the resulting thread and delivery receipt.
----
-
-An Agent webhook receives JSON from another system and starts a follow-up Agent turn. It is an inbound trigger, not a callback that Fluso sends to another service.
-
-Choose whether events use a dedicated thread or an existing Agent thread. Each accepted event uses the Agent definition and project attached to that thread.
-
-## Create a webhook
-
-<Steps>
-  <Step title="Open Triggers">
-    Open the Agent-name menu and choose **Triggers**.
-  </Step>
-  <Step title="Add the trigger">
-    Click **Add trigger**, give it a clear name, and choose an authentication
-    method. **Header secret** is the safer default. Use a query secret only
-    when the sending service cannot set a custom header.
-  </Step>
-  <Step title="Choose the target thread">
-    Select **New thread on first event** to keep these events together in a
-    dedicated thread, or select an existing non-archived Agent thread.
-  </Step>
-  <Step title="Copy the credentials">
-    Click **Create trigger**, then copy the webhook secret. Fluso shows the
-    clear secret only after creation or rotation. The webhook URL remains
-    available on the trigger row.
-  </Step>
-</Steps>
-
-## Send an event
-
-The public delivery URL uses the webhook secret, not your Fluso bearer token. A header-authenticated request looks like this:
-
-```bash
-export FLUSO_WEBHOOK_URL='<copied-webhook-url>'
-export FLUSO_WEBHOOK_SECRET='<copied-webhook-secret>'
-
-curl "$FLUSO_WEBHOOK_URL" \
-  -X POST \
-  -H 'Content-Type: application/json' \
-  -H "X-Fluso-Webhook-Secret: $FLUSO_WEBHOOK_SECRET" \
-  -H 'Idempotency-Key: release-ready-2026-09-01' \
-  -d '{"event":"release.ready","release":"2026.09.01"}'
-```
-
-If you chose **Query secret**, send the same value through the `secret` query parameter. Query values can appear in browser, proxy, and server logs, so prefer the header when possible.
-
-The request must use `application/json`, contain valid JSON, and stay at or below 25,000 bytes. Fluso accepts any JSON shape; define the fields your Agent instructions expect.
-
-## Read the receipt
-
-A successful request returns `202 Accepted` with a delivery receipt:
-
-```json
-{
-  "id": "<delivery-id>",
-  "receivedAt": "2026-09-01T12:00:00.000Z",
-  "payloadSummary": "JSON event · 54 bytes",
-  "status": "accepted",
-  "responseCode": 202,
-  "requestId": "webhook:<trigger-id>:<delivery-id>",
-  "threadId": "<target-thread-id>",
-  "error": null
-}
-```
-
-`202 Accepted` means the Agent turn was admitted or queued. It does not mean the Agent finished. Open the target thread or the Agent's **Analytics** page to inspect the run.
-
-If the target thread is already running, the event waits as a follow-up instead of interrupting the current turn.
-
-## Test and inspect deliveries
-
-Expand **Test & deliveries** on the trigger row. Edit the sample JSON and click **Send test event**. This is a real Agent turn.
-
-The trigger shows its latest 20 completed receipts. The list shows accepted or failed status, time, a payload-size summary, and a link to an accepted event's thread. The receipt stores a payload digest and size summary instead of the full JSON body. Idempotency records can remain for 24 hours even when they are no longer in that list.
-
-The full payload is added to the Agent message and becomes part of the target thread's context and history. Do not send a secret unless the Agent is intended to receive it.
-
-## Idempotency and retries
-
-Fluso makes one admission attempt for each delivery. It does not retry a failed request automatically.
-
-Send one `Idempotency-Key` header when your sender may retry. For 24 hours on that trigger:
-
-- The same key and payload returns the original receipt without another Agent turn.
-- The same key with a different payload returns `409 Conflict`.
-- Replaying a failed key returns the same failure; use a new key only when you intend to create a new turn.
-
-Without an idempotency key, repeated requests create separate Agent turns.
-
-## Pause, rotate, or delete
-
-- Turn the trigger switch off to pause it. Requests to a paused trigger return `409`.
-- Choose **Rotate secret** if a secret may be exposed. The old secret stops working immediately, and the replacement is shown once.
-- Choose **Delete trigger** to remove its URL and delivery history. Later requests to that URL return `404`.
-
-## Security boundary
-
-Treat every payload as untrusted input. It becomes thread context, so remove credentials and fields the Agent does not need. A webhook does not bypass the Agent's saved capabilities, tool rules, or approval boundaries. Keep external writes behind approval when an event should prepare work rather than publish it.
-
-## Common errors
-
-| Status | Check |
-| --- | --- |
-| `400` | The body is valid JSON. If present, `Idempotency-Key` appears once and contains 1 to 255 characters. |
-| `401` | The header or query secret matches the current secret. |
-| `404` | The trigger, Agent, or target thread still exists. |
-| `409` | The trigger is enabled, the target is available, and the idempotency key is not conflicting or already in progress. |
-| `413` | The raw JSON body is no larger than 25,000 bytes. |
-| `415` | `Content-Type` is `application/json`. |
-| `429` | The sender's IP rate limit or the Agent owner's usage limit has been reached. Honor `Retry-After` when it is present. |
-| `502` or `503` | The Agent service and runtime are available. A repeated failed key returns the recorded failure and does not start another attempt; use a new key only when you intend one. |
-
-## Next
-
-Use [Runs](/developers/api-ref/runs) to inspect accepted turns, [Threads and contexts](/developers/threads-and-contexts) to understand the target thread, and [Schedules](/developers/schedules) for time-based triggers.
diff --git a/content/docs/features/approvals.mdx b/content/docs/features/approvals.mdx
index ba9e562..55f5344 100644
--- a/content/docs/features/approvals.mdx
+++ b/content/docs/features/approvals.mdx
@@ -2,108 +2,59 @@
 title: Approvals and permissions
 sidebarTitle: Approvals
 icon: shield-check
-description: Choose when Fluso asks before connector and MCP tool actions, review approval cards, and manage saved tool rules.
+description: Choose when app tools need approval, review exact actions, and manage saved tool rules.
 ---
 
-Approvals let you decide how much Fluso can do without stopping for confirmation. You can keep every connector and MCP tool action behind a prompt, or let Fluso run them automatically.
+The permission control in the composer determines how Fluso uses connected apps in that chat. It does not connect an account or select an app for an Agent.
 
-Your choice belongs to a chat. Existing chats keep their current mode. A choice made before a new chat starts is pending until you send the first message and the chat is created.
+## Choose a mode
 
-<Note>
-  Organization rules and your saved **Deny** rules always apply. An automatic mode cannot override them.
-</Note>
+| Mode | Behavior |
+| --- | --- |
+| **Ask me first** | Ask before actions that are not already allowed by tool or connection rules |
+| **Allow everything** | Use connected app tools automatically, while respecting denied tools and organization restrictions |
 
-## Choose an approval mode
+Read-only tools follow each connection's settings. **Ask me first** therefore does not guarantee a prompt for every read. If a particular action must always need review, check that tool's saved rule and the chat's mode.
 
-| Mode | Connector and MCP tools |
-|---|---|
-| **Ask for everything** | Ask before a tool runs |
-| **Don't ask permission** | Approve tools automatically |
+Select the hand or open-lock control in the composer to change the mode. Before the first message, a new chat's choice is pending until the chat is created.
 
-Use **Ask for everything** when you want to review each action before a tool can read or change data. **Don't ask permission** is best for work you trust Fluso to finish without waiting for you.
+For an external send, ask Fluso to prepare a draft, review its recipients and contents, and authorize the send when ready.
 
-### Set the mode from the composer
+## Set the default
 
-<Steps>
-  <Step title="Open the permission menu">
-    Start a new chat and click the shield control beside the model mode in the composer.
-  </Step>
-  <Step title="Choose a mode">
-    Pick **Ask for everything** or **Don't ask permission**. The menu explains which requests will still pause.
-  </Step>
-  <Step title="Send the first message">
-    Before a thread exists, the composer labels the choice as **Pending**. Sending your first message creates the chat and confirms its mode.
-  </Step>
-</Steps>
+Open **Settings → Approvals & permissions**. **Auto-approval** sets your default across desktop, web, and Telegram.
 
-You can change the mode between messages. The updated choice applies to later actions in that chat. It does not change other existing chats.
+Chats where you explicitly picked a mode keep it. Other chats follow the current default, including existing chats without an override. A Settings change does not itself decide an approval already waiting.
 
-## Connector tool approval cards
+## Review an approval card
 
-Connector and MCP tools can read or change data in another service. When a tool needs approval, the card shows the connector or server, tool name, a short argument summary, and an expandable view of the exact arguments.
+The card identifies the connection, tool, and arguments. Expand **Arguments** when the summary is not enough to judge the action.
 
-You can choose:
+- **Allow once** permits this pending tool call with these exact arguments.
+- **Always allow this tool** saves a rule for future calls to that tool. It is broader than this one request.
+- **Deny** rejects this request without saving a permanent deny rule.
+- **Cancel** cancels the pending approval.
 
-- **Allow once** to run this tool only with the arguments shown on the card.
-- **Always allow** to save an allow rule for this tool.
-- **Deny** to reject this request without creating a permanent tool deny.
+If the app needs authorization, finish its connection flow. Missing account access and permission to run an action are separate decisions.
 
-If the required app is not connected, the card asks you to **Connect** first. Complete sign-in and Fluso resumes the waiting action. If the request changes while you are deciding, it fails closed instead of applying your decision to different arguments.
+Expired or changed requests cannot reuse an old approval. If an approval is no longer actionable, inspect the conversation before asking for another attempt.
 
-If the card expires or the run is canceled before you decide, ask Fluso to try the action again. An organization-managed deny is locked and cannot be approved from chat.
+## Manage saved tool rules
 
-<Tip>
-  Use **Allow once** for a sensitive write or an unusual set of arguments. Use **Always allow** for a tool you expect this chat to call repeatedly.
-</Tip>
+Open **Plugins → MCP**, select the connection, and open its tool permissions. Rules can be **Allow**, **Ask**, or **Deny**. The connection also has **Auto-approve read-only tools** for tools classified as reads.
 
-## Manage approvals in Settings
+Explicit tool rules take precedence over read-only defaults. The chat's **Allow everything** mode can allow actions that would otherwise ask; it cannot override a deny. Organization restrictions and an Agent's saved app restrictions still apply.
 
-Open your account menu, choose **Settings**, then open **Approvals & permissions**. This panel controls the mode for your next new chat.
+An Agent's **Allowed** connector setting only permits use of that connection. It does not override a tool deny, supply credentials, or approve a particular pending action.
 
-### Set the default for the next chat
+## When something is blocked
 
-The **Auto-approval** section has the same modes as the composer. A Settings change is staged for your next new chat. It does not rewrite the mode of chats that already exist.
+| Situation | Check |
+| --- | --- |
+| Changing Settings did not change a chat | That chat may have its own explicit mode |
+| A read ran without a card | Check saved allow rules and the connection's read-only setting |
+| Another tool still asks after **Always allow this tool** | The saved rule applies to that tool, not every tool on the connection |
+| No approval can unblock the action | Check Agent capabilities, saved denies, organization restrictions, and connection status |
+| A delegated session waits | Review its approval in the session, main conversation, or [Inbox](/developers/guides/inbox) |
 
-## Which rule wins
-
-Fluso applies the most restrictive relevant rule. In practical terms:
-
-1. An organization **Deny** always blocks the tool.
-2. Your **Deny** can block something the organization allows.
-3. An organization **Allow** can make an action available, unless you denied it.
-4. Your **Allow** can approve an action when the organization has not blocked it.
-5. With no saved rule, the current chat mode decides whether Fluso asks or continues automatically.
-
-This is why switching to **Don't ask permission** does not open something that your organization or you explicitly blocked.
-
-## Manage MCP tool rules
-
-Open **Plugins**, select an MCP server, and open its tool permissions. Each tool can be set to **Allow**, **Ask**, or **Deny**.
-
-You can also enable automatic approval for tools classified as read-only, such as list, search, fetch, and GET operations. An explicit **Ask** or **Deny** on a tool takes precedence over that read-only setting.
-
-See [MCP servers](/features/mcp) for connection setup and credential handling.
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="I changed the mode in Settings, but this chat still asks">
-    Settings changes apply to the next new chat. Existing chats keep their current mode. Change the shield control in this chat, or start a new one.
-  </Accordion>
-  <Accordion title="The composer says Pending">
-    The chat has not been created yet. Send the first message to commit that mode to the new chat.
-  </Accordion>
-  <Accordion title="An approval card expired">
-    Ask Fluso to retry the action. Approval cards are bound to one pending request and cannot approve a later or changed request.
-  </Accordion>
-  <Accordion title="I chose Always allow, but a different connector tool still asks">
-    Tool rules apply to the specific tool, not every tool on the connector or MCP server. Review that server's tool permissions under **Plugins**.
-  </Accordion>
-  <Accordion title="A tool is blocked and no approval card appears">
-    Check that server's tool permissions under **Plugins** for a saved **Deny**. If the rule is locked or marked as managed by your organization, only an organization administrator can change it.
-  </Accordion>
-</AccordionGroup>
-
-## Next
-
-See [Chat](/features/chat) for thread and composer behavior, and [Apps and MCP servers](/features/mcp) for app access and third-party tools.
+See [Apps & MCP](/features/mcp) for connecting accounts and [Setup and capabilities](/developers/guides/settings) for selecting them for an Agent.
diff --git a/content/docs/features/chat.mdx b/content/docs/features/chat.mdx
index dc4acd7..0e933c8 100644
--- a/content/docs/features/chat.mdx
+++ b/content/docs/features/chat.mdx
@@ -17,17 +17,17 @@ Describe the outcome. Get the outcome. Review.
 
 ## Model mode
 
-Use the mode button in the composer to set how much reasoning Fluso spends on the current chat: **Quick**, **Deep**, or **Max**. `⌘\` cycles through them.
+Use the mode button in the composer to set how much reasoning Fluso spends on the current chat: **Fast**, **Medium**, or **High**. `⌘\` cycles through them.
 
-Quick answers straightforward questions and small edits. Deep takes longer on complex tasks, reviews, and planning. Max is for the hardest problems. [Composer](/interface/composer) has the full comparison.
+Fast suits straightforward questions and small edits. Medium balances speed and reasoning. High spends more reasoning on difficult work. [Composer](/interface/composer) has the full comparison.
 
-The mode is chat-specific. You can change it between messages, and new chats start in Deep unless you switch them.
+The mode is chat-specific. Ordinary new chats start in Medium unless you switch them. Saved Agents take **High** or **Fast** from their [setup](/developers/guides/settings).
 
 This only affects the chat you are using in the app. Telegram has its own conversation mode: using `/fast` in Telegram does not change an app chat, and changing the app control does not change Telegram.
 
 ## Approval mode
 
-Use the access control beside the mode button to choose when Fluso asks before connector and MCP tool actions. It shows a hand for **Ask me first**, a globe for **Allow web**, and an open lock for **Allow everything**; `⌘⇧\` steps through them. The choice belongs to the current chat. Before a new chat exists, it remains pending until you send the first message.
+Use the access control beside the mode button to choose when Fluso asks before connector and MCP tool actions. It shows a hand for **Ask me first** and an open lock for **Allow everything**; `⌘⇧\` steps through them. A choice made here belongs to the current chat. Chats without an explicit choice follow your default in Settings. Before a new chat exists, a selected mode remains pending until you send the first message.
 
 See [Approvals and permissions](/features/approvals) for the modes, in-chat approval cards, saved tool rules, and organization policy behavior.
 
@@ -43,7 +43,9 @@ Two things matter more than anything else.
 
 A thread is one conversation. It remembers what you've said and what Fluso has said back, so a follow-up prompt picks up where you left off. After Fluso summarises your inbox, *"reply to the one from Legal"* makes sense because the summary is still in context.
 
-Start a new thread when you switch topic. The plus button at the top works, or you can ask for one in chat. Old threads stay in the sidebar. Pick any of them back up and Fluso has the full history.
+Start a new thread when you switch topic. Use the new-chat control in the sidebar. Old threads remain available to reopen. Long histories may be compacted into a summary for the model; the saved conversation remains readable.
+
+Saved [Agents](/developers/agent-builder) work differently: selecting an Agent returns to its continuing main conversation. Its Manager refines the setup, and it can delegate independent work to [sessions](/developers/guides/conversations).
 
 ## Things you can do inside chat
 
@@ -69,11 +71,13 @@ Queued follow-ups wait above the composer and run in order once the current run
 
 To steer the run in progress, queue the message, then click **Send now** (the play button) on its row. Fluso sends it into the live run immediately, or starts it as a new request if the run has already finished. **Edit** (the pencil) lets you rewrite the message first; **Cancel** (the cross) removes it.
 
+For an Agent, a message submitted with a changed saved setup shows **Saved setup applies next turn** instead of **Send now** while the older turn runs. Edit and Cancel remain available.
+
 Two safeguards worth knowing. If a follow-up starts while you are still editing it, the save is refused with a notice and your text stays in the composer — nothing sends twice. And if a follow-up cannot reach the server, the row is marked failed with a retry, not silently dropped.
 
 ### Stopping pauses the queue
 
-Stop the run with the square button and queued follow-ups pause instead of firing into a conversation you cut short. The same happens if the run fails. Paused follow-ups never start on their own: **Send now** runs one, **Edit** rewrites it first, **Cancel** clears it.
+Stop the run with the square button and messages you queued pause. The same happens if the run fails. Paused follow-ups never start on their own: **Send now** runs one, **Edit** rewrites it first, **Cancel** clears it. Routine messages and returned session results do not receive this pause.
 
 <Frame>
   <img src="/images/features/chat/tray-paused.png" alt="Two queued follow-ups marked with a Paused badge after the run was stopped." />
diff --git a/content/docs/features/mcp.mdx b/content/docs/features/mcp.mdx
index de323ce..59dd58f 100644
--- a/content/docs/features/mcp.mdx
+++ b/content/docs/features/mcp.mdx
@@ -28,7 +28,7 @@ Click **Add MCP**. The dialog opens on the **Apps** tab.
   <img src="/images/features/mcp/marketplace-apps.png" alt="The Add MCP dialog on the Apps tab: a search field and a catalog listing Google Workspace, GitHub, Slack, Slackbot, Linear, Web Search (connected), Airtable, Asana, and more, each with a Connect button." />
 </Frame>
 
-Search for the app, click **Connect**, and sign in on the app's own login screen. You approve the permissions there, the window closes itself, and the row appears in your list. Fluso can use the app from the next message on.
+Search for the app, click **Connect**, and sign in on the app's own login screen. You approve the permissions there, the window closes itself, and the row appears in your list. Ordinary chats can use it from the next message. For a saved Agent, also select it under [Connectors](/developers/guides/settings#grant-app-access).
 
 A few rows worth knowing about:
 
@@ -115,7 +115,7 @@ Expand any connection row to see its tools and set rules per tool.
 </Frame>
 
 - **Auto-approve read-only tools** allows operations classified as GET, list, search, and fetch to run without asking. Explicit Ask or Deny rules still win.
-- Each tool has its own **Allow**, **Ask**, or **Deny**. Allow runs without asking, Ask pauses for your approval in chat, Deny blocks the tool outright.
+- Each tool has its own **Allow**, **Ask**, or **Deny**. Allow runs without asking, Ask pauses for approval when the chat uses **Ask me first**, and Deny blocks the tool. **Allow everything** can bypass Ask, but not Deny.
 - Tools are grouped read-only versus everything else, so you can see at a glance what can only look and what can act.
 
 These rules work together with your chat-level approval mode. See [Approvals and permissions](/features/approvals) for how the modes and rules interact.
@@ -134,7 +134,7 @@ Each row shows the connection's status. The three-dot menu holds the two actions
 
 ## Things to know
 
-- **Connections are per account, not per chat.** Sign in once; every new chat can use the connection, and it survives runtime restarts in the background.
+- **Connections are per account, not per chat.** Sign in once and reuse the connection across chats. Saved Agents can use only their selected connections. Sign-ins survive runtime restarts.
 - **The runtime never stores tokens.** Tools fetch a short-lived token from the backend per request, use it, and drop it. Sign-in happens on the app's own page — Fluso never sees your password.
 - **Custom servers have prerequisites.** Fluso supports public HTTPS Streamable HTTP endpoints with OAuth, API-key, or bearer-token access. A successful sign-in does not override network-egress or provider policy.
 - **Rules set by your organization take precedence** over anything you allow yourself.
@@ -155,7 +155,7 @@ Each row shows the connection's status. The three-dot menu holds the two actions
   The server advertises Dynamic Client Registration but rejected the registration. Switch to **OAuth (BYO)** and register an app in the server's developer console yourself.
 </Accordion>
 <Accordion title="A tool keeps asking for approval">
-  Its rule is set to **Ask**, or your chat's approval mode is **Ask for everything**. Set the tool to **Allow** in the row's tool permissions, or change the mode — see [Approvals](/features/approvals).
+  Its rule is set to **Ask**, or your chat's approval mode is **Ask me first**. Set the tool to **Allow** in the row's tool permissions, or change the mode — see [Approvals](/features/approvals).
 </Accordion>
 
 ## Next
diff --git a/content/docs/features/memory.mdx b/content/docs/features/memory.mdx
index 23693fc..bbcb474 100644
--- a/content/docs/features/memory.mdx
+++ b/content/docs/features/memory.mdx
@@ -13,17 +13,17 @@ Durable memory follows a stricter rule than you might expect: it saves stable th
 
 <MemoryScopeDiagram />
 
-**Global preferences.** User-level things that should apply everywhere. Your timezone, the response style you have asked for, workflow choices, standing instructions like *"always show me drafts in plain text"*. These live in `preferences.md` in your workspace, where you can read them.
+**Global preferences.** User-level rules for ordinary chats across projects: response style, workflow choices, and standing instructions like *"always show me drafts in plain text"*. These live in `preferences.md` in your workspace, where you can read them. Saved Agents use their own instructions instead.
 
 **Project context.** Facts, decisions, conventions, and preferences that belong only to the project you are in. The Q3 roadmap decision. The naming convention you agreed with the team. The pricing approach for this client. Each project keeps its own `context.md`.
 
 **Project working memory.** An automatic, short-lived record of what the conversations in a project have been doing: the current state of each, open items, files touched. Fluso keeps it up to date on its own, so asking *"where did we leave off?"* in a new chat gets a real answer.
 
-The split matters because Fluso is careful about scope. Project material stays in the project. One client's notes do not surface inside another client's chat.
+Automatic recall uses the current project's material. This scopes context, not file access: tools can still work with shared files elsewhere in your account.
 
 ## How it loads
 
-With every message, Fluso pulls in three things as background context:
+Ordinary chats use three sources of background context:
 
 - Your global preferences
 - The current project's context
@@ -35,18 +35,18 @@ Memory is context for the conversation, not a script. Your current message still
   Saved Agent threads are the exception. They use the Agent's own definition
   instead of global preferences, project instructions, or `context.md`. They
   can still use project files and project working-memory summaries. See
-  [Threads and contexts](/developers/threads-and-contexts).
+  [Files and context](/developers/guides/files).
 </Note>
 
 ## How it updates
 
 Two paths. Both are conservative on purpose.
 
-**You ask explicitly.** Say *"remember this"*, *"forget this"*, *"add this to project context"*, or *"update my preference"* and Fluso edits `preferences.md` or the project's `context.md` directly. Clear intent only. A passing line like *"I like detailed answers"* is not treated as a memory write; that kind of inference goes through the other path.
+**You ask explicitly.** Say *"remember this"*, *"forget this"*, *"add this to project context"*, or *"update my preference"* and Fluso edits `preferences.md` or the project's `context.md` directly. A clearly stated preference or future-facing rule can also be saved without the words "remember this". One-off task details should stay with the task.
 
-**Background learning.** After each reply, a background pass updates the project's working memory. When something durable shows up — a stated preference, a clear correction, a convention you keep repeating, a decision — it also adds that to your preferences or the project's context, marked as auto-saved and deduplicated against what is already there. Anything that looks like a secret or credential is dropped rather than saved. If nothing durable came up, it writes nothing durable.
+**Background learning.** After each reply, a background pass updates the project's working memory. When something durable shows up — a stated preference, a clear correction, a convention you keep repeating, a decision — it also adds that to your preferences or the project's context, marked as auto-saved and deduplicated against what is already there. Common credential patterns are filtered, but this is not a guarantee that sensitive text can never be saved. Keep secrets out of memory files. If nothing durable came up, it writes nothing durable.
 
-The guardrail on explicit updates exists for a reason. Vague or accidental wording should not mutate the layer that follows you across every chat.
+Saved Agents use their own standing instructions. Refine that setup through the Manager or editor when a rule should persist for one Agent.
 
 ## What gets saved
 
@@ -60,7 +60,7 @@ The guardrail on explicit updates exists for a reason. Vague or accidental wordi
 - Greetings and small talk.
 - Temporary instructions for a single chat.
 - Guesses Fluso is not confident about.
-- Secrets, credentials, or anything that looks like one.
+- Text rejected by the credential filter. Do not rely on it as a complete secret detector.
 
 One-off task details stay out of the durable files too. They live in working memory while the work is fresh, then fall away instead of following you forever.
 
diff --git a/content/docs/features/open-architecture.mdx b/content/docs/features/open-architecture.mdx
index 6f1d645..76637dd 100644
--- a/content/docs/features/open-architecture.mdx
+++ b/content/docs/features/open-architecture.mdx
@@ -7,7 +7,7 @@ description: Keep a usable copy of your work and move it through documented file
 
 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.
+Different exports serve different purposes. A project ZIP is a file backup; a shared Agent is a reusable setup; a shared chat is a reviewable snapshot.
 
 ## What you can take out
 
@@ -17,45 +17,39 @@ Different exports serve different purposes. A project ZIP is a file backup; an A
 | **Individual files** | Open a project file and select **Download** | The original file in its stored format |
 | **Shared project files** | Open a project file, select **Share**, then create a link | A revocable public link to the selected file |
 | **Generated documents and presentations** | Use the artifact's export menu | Documents as PDF, Word, HTML, or Markdown; presentations as PDF, PowerPoint, or a Google Slides copy |
-| **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 |
+| **Agent copies** | Open the Agent's actions menu, then **Share** | A revocable snapshot of the setup and selected resources that another person can import |
 | **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.
+Project ZIPs skip dotted runtime entries and symbolic links. They do not serve as a complete conversation archive. Use the [Threads and messages API](/api/workflows/conversations#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.
+The skill document is view-only. For a custom skill you own, keep its `SKILL.md` and source files before removing it from Fluso. An Agent share can include selected custom skill folders; built-in skills remain references to the recipient's installed versions.
 
-## What an Agent export leaves behind
+## What an Agent share includes
 
-Agent export and sharing deliberately omit:
+Instructions and settings are included. You choose whether to include knowledge files, complete custom skill folders, and custom connection URLs. Built-in skills and missing reference files are listed by name.
 
-- 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.
+Stored account credentials, conversations, routines, and project files stay private. The recipient connects their own apps. Publish later changes explicitly with **Update shared version**, or revoke the link with **Stop sharing**. Imported copies remain independent.
 
-The export names omitted knowledge files so the recipient can add them again. Named skills remain references to review in the destination workspace; an Agent configured to use every skill imports with none selected. Apps must be reconnected. See [Agent versions](/developers/versions#move-an-agent-between-workspaces) for the full handoff flow.
+See [Sharing and copies](/developers/guides/sharing) for the full flow and resource limits.
 
 ## 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.
+2. Share the Agent's saved setup and any reference files the recipient needs.
 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.
+5. In the destination workspace, import the Agent, upload the project files, connect Apps, and try a real task before scheduling work.
 
 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.
+Use [API access](/api/first-request) when a one-time download is not enough. The account API covers Agents, conversations, files, schedules, runs, and usage on Cloud and [daemon workspaces](/workspaces). Authenticate with a Cloud developer token or a paired daemon token. Store only the data your integration needs.
diff --git a/content/docs/features/projects.mdx b/content/docs/features/projects.mdx
index c800cef..b685c95 100644
--- a/content/docs/features/projects.mdx
+++ b/content/docs/features/projects.mdx
@@ -5,7 +5,7 @@ icon: folder-kanban
 description: Keep related chats, files, instructions, and memory together in one workspace.
 ---
 
-Projects give one body of work its own scope. A project keeps its chats, files, instructions, context, and working memory together, so work for one customer or product does not spill into another.
+Projects keep related chats, files, instructions, and working memory together. Automatic context follows the current project; tools can still access shared files elsewhere in your account.
 
 Use **Home** for general work. Create a separate project when a customer, product area, or deliverable needs its own files and history.
 
@@ -41,7 +41,7 @@ Files created in project chats stay in the same workspace. That makes the projec
 
 On **Projects**, open the project's **•••** menu and select **Export as zip**. You can also open the project and select **Export**.
 
-The ZIP contains the project's regular files, their folder paths, `context.md`, and project metadata. It omits empty folders, dotted runtime entries, and symbolic links. Conversation history is separate; use **Share chat** for a reviewable snapshot or the [Threads API](/developers/api-ref/threads-and-messages#read-message-history) for persisted messages.
+The ZIP contains the project's regular files, their folder paths, `context.md`, and project metadata. It omits empty folders, dotted runtime entries, and symbolic links. Conversation history is separate; use **Share chat** for a reviewable snapshot or the [Threads API](/api/workflows/conversations#read-message-history) for persisted messages.
 
 ## Keep context in the right place
 
@@ -49,9 +49,9 @@ Project instructions guide ordinary project chats. Durable notes and decisions l
 
 <Note>
   Saved Agent threads use the Agent's own instructions instead of project
-  instructions or `context.md`. They can still use the configured project's
-  files and working-memory summaries. See [Project
-  context](/developers/project-context) for this boundary.
+  instructions or `context.md`. They can still use their conversation's project
+  files and working-memory summaries. See [Files and
+  context](/developers/guides/files) for this boundary.
 </Note>
 
 Use one project per scope that should stay separate. For example, keep Acme support work in an Acme project and the Q3 launch in a Q3 Launch project. Start a new chat inside the same project when the topic changes but the files and background should remain available.
@@ -60,8 +60,10 @@ Use one project per scope that should stay separate. For example, keep Acme supp
 
 Use the project's sidebar actions menu to pin, archive, label, recolor, or change its icon. Use the menu on the Projects page to export or delete it. **Home** is the default workspace and cannot be deleted.
 
+Deleting a project removes its files, conversations, and attached routines. Saved Agents remain. If an Agent uses that deleted project, select another project in its setup to start a new main conversation; deleted history is not restored.
+
 If you already have useful context in ChatGPT, Claude, or another agent, use [Imports](/features/imports) to create projects and files from an export.
 
 ## Next
 
-Read [Memory](/features/memory) for the context carried between chats, or [Files and projects](/developers/api-ref/files-and-projects) for the API.
+Read [Memory](/features/memory) for the context carried between chats, or [Files and projects](/api/workflows/files) for the API.
diff --git a/content/docs/going-deeper.mdx b/content/docs/going-deeper.mdx
index 183edb1..bf3ca19 100644
--- a/content/docs/going-deeper.mdx
+++ b/content/docs/going-deeper.mdx
@@ -80,7 +80,7 @@ Memory builds itself in the background. You do not have to maintain it. A few ha
 
 **Tell Fluso to forget when you need to.** *"Forget my old timezone"*, *"don't track anything about this vendor"*. The same explicit channel works in reverse.
 
-**Scope by project when working on something specific.** Switching into a project before asking a question keeps the project's context in scope and stops one client's notes from surfacing in another client's chat.
+**Scope by project when working on something specific.** Automatic context follows the current project. Tools can still access other files in your workspace. A project is not a private filesystem boundary.
 
 **Process meeting transcripts.** Decisions and action items from the transcript become durable project context. Without processing, the meeting effectively did not happen for memory.
 
@@ -108,7 +108,7 @@ The pattern: name the inputs, name the output, let Fluso connect them.
 
 ## Approval discipline
 
-Approval follows the effective tool and chat policy. With **Ask**, a read or write pauses on an approval card. A tool set to **Allow**, or a chat using **Don't ask permission**, can continue without a per-action prompt; **Deny** always blocks it. Keep external-facing write tools on **Ask** when you want to review each draft.
+Approval follows the effective tool and chat policy. With **Ask**, a read or write pauses on an approval card. A tool set to **Allow**, or a chat using **Allow everything**, can continue without a per-action prompt; **Deny** always blocks it. Keep external-facing write tools on **Ask** when you want to review each draft.
 
 The instinct on day one is to read every draft carefully. By day twenty, you will be tempted to wave things through. Don't.
 
@@ -122,11 +122,7 @@ The instinct on day one is to read every draft carefully. By day twenty, you wil
 
 ## For teams
 
-Team plans add shared context. The patterns that matter:
-
-**Shared projects** for cross-team work. Both you and your colleague see the same memory, the same files, the same task list, scoped to that project. The Acme project becomes a real shared brain instead of two separate ones.
-
-**Shared knowledge graph** for the team. Decisions made in any team member's meetings are visible to everyone (within the shared project). Useful for executive teams; less useful for projects with strict need-to-know.
+Share a finished file or an [Agent's setup](/developers/guides/sharing) when a colleague needs your work. An imported Agent is an independent copy. It does not share your live conversations, routines, project files, or account connections.
 
 **Admin visibility, not content access.** The current [Admin panel](/admin-panel) covers identity and access records, recorded usage, runtime status, and network policy. Connected-app inventory, seat controls, and a complete organization-wide audit require their owning Enterprise integrations. The admin UI does not expose messages, files, or knowledge graphs.
 
diff --git a/content/docs/index.mdx b/content/docs/index.mdx
index 052b6ce..abc44c4 100644
--- a/content/docs/index.mdx
+++ b/content/docs/index.mdx
@@ -48,17 +48,20 @@ Pick a workflow that matches a problem you have right now. Each one is a story,
 ## When you need it
 
 <CardGroup cols={2}>
+  <Card title="Fluso Local" icon="monitor" href="/workspaces">
+    Set up Fluso on your own machine and use it with your files, Agents, and routines.
+  </Card>
   <Card title="Features" icon="sparkles" href="/features/chat">
     The five primitives: chat, apps, skills, tasks, memory.
   </Card>
   <Card title="Apps & MCP" icon="plug" href="/features/mcp">
     The connection model and the full catalog of supported apps.
   </Card>
-  <Card title="Agents (Beta)" icon="bot" href="/developers/agent-builder">
-    Build a saved Agent, split work across threads, and schedule follow-ups.
+  <Card title="Agents (Beta)" icon="bot" href="/developers">
+    Create an Agent, refine its setup, and return to its conversations, routines, and Inbox.
   </Card>
-  <Card title="Architecture" icon="network" href="/developers/architecture">
-    Request flow, durable data boundaries, and replaceable components.
+  <Card title="Fluso API" icon="code-xml" href="/api">
+    Connect a script to Cloud or Fluso Local, submit work, and read the result.
   </Card>
   <Card title="Pricing" icon="credit-card" href="/resources/pricing">
     Plans, limits, billing.
diff --git a/content/docs/integrations/github.mdx b/content/docs/integrations/github.mdx
index c58d66b..e906c37 100644
--- a/content/docs/integrations/github.mdx
+++ b/content/docs/integrations/github.mdx
@@ -58,7 +58,7 @@ Issues:
 > *"What issues are assigned to me this sprint?"*
 
 <Warning>
-  Keep GitHub write tools on **Ask** when you want every diff or comment shown before the action runs. **Allow** or **Don't ask permission** can continue without a per-action prompt; **Deny** blocks the write.
+  Choose **Ask me first** and keep GitHub write tools on **Ask** to review each requested action before it runs. Ask Fluso to show the diff or comment first. A saved **Allow** rule or **Allow everything** can continue without a per-action prompt; **Deny** blocks the write.
 </Warning>
 
 ## A small thing that makes generated code much better
diff --git a/content/docs/integrations/gmail.mdx b/content/docs/integrations/gmail.mdx
index 359df7b..c51e33a 100644
--- a/content/docs/integrations/gmail.mdx
+++ b/content/docs/integrations/gmail.mdx
@@ -60,9 +60,9 @@ Follow-ups:
 
 ## How permissions actually behave
 
-Reading happens when you ask for it (*"summarise my inbox"*) and continuously in the background for auto-task extraction. Messages are processed for the response and not stored beyond what's referenced in your knowledge graph and tasks.
+Reading happens when you ask for it (*"summarise my inbox"*), through scheduled routines, and through background task extraction. Requested work can save email content in conversation records or workspace files. Review those outputs before sharing them.
 
-Keep Gmail send tools on **Ask** when you want every draft shown before it sends. **Allow** or **Don't ask permission** can continue without a per-action prompt; **Deny** blocks the send. There is no separate batch-send mode that overrides the effective policy.
+Choose **Ask me first** and keep Gmail send tools on **Ask** to review each requested send. Ask Fluso to show the draft first. A saved **Allow** rule or **Allow everything** can continue without a per-action prompt; **Deny** blocks the send. There is no separate batch-send mode that overrides the effective policy.
 
 Header metadata is used for categorisation and handled under the same subprocessor controls as other requested email content.
 
diff --git a/content/docs/integrations/slack.mdx b/content/docs/integrations/slack.mdx
index e13ed94..ae3f784 100644
--- a/content/docs/integrations/slack.mdx
+++ b/content/docs/integrations/slack.mdx
@@ -48,7 +48,7 @@ Posting:
 > *"Post a status update in #partnerships about Acme."*
 
 <Warning>
-  Keep Slack write tools on **Ask** when you want every draft shown before it posts. **Allow** or **Don't ask permission** can continue without a per-action prompt; **Deny** blocks the post.
+  Choose **Ask me first** and keep Slack write tools on **Ask** to review each requested post. Ask Fluso to show the draft first. A saved **Allow** rule or **Allow everything** can continue without a per-action prompt; **Deny** blocks the post.
 </Warning>
 
 ## Cross-app workflows
diff --git a/content/docs/interface/composer.mdx b/content/docs/interface/composer.mdx
index 66a18f0..a9ba03d 100644
--- a/content/docs/interface/composer.mdx
+++ b/content/docs/interface/composer.mdx
@@ -173,23 +173,22 @@ The mode button on the composer toolbar sets reasoning effort for the current ch
 
 | Mode | Use it for |
 | --- | --- |
-| **Quick** | straightforward questions and small edits |
-| **Deep** | complex tasks, reviews, planning |
-| **Max** | the hardest problems, when you would rather wait |
+| **Fast** | straightforward questions and small edits |
+| **Medium** | everyday work with a balance of speed and reasoning |
+| **High** | difficult tasks, reviews, and planning |
 
-The choice belongs to the chat, not the app, so a quick lookup and a long refactor can sit side by side in your sidebar at different settings. In [confidential mode](/features/confidential) the reasoning level is fixed, so Max is not offered there.
+The choice belongs to the chat, not the app, so a quick lookup and a long refactor can sit side by side in your sidebar at different settings. Ordinary chats default to Medium. Saved Agents take High or Fast from their [setup](/developers/guides/settings), so change it there. In [confidential mode](/features/confidential), the underlying reasoning level is fixed and the extra High option is not offered for ordinary chats.
 
 ## What Fluso may do on its own
 
-Beside the mode button, one control sets how much Fluso does before checking with you. `⌘⇧\` steps through the three levels.
+Beside the mode button, one control sets how much Fluso does before checking with you. `⌘⇧\` switches between the two modes.
 
 | Level | Behaviour |
 | --- | --- |
-| **Ask me first** | asks before reaching the web and before any connected app |
-| **Allow web** | searches the web on its own, still asks before connected apps |
-| **Allow everything** | acts without asking |
+| **Ask me first** | asks when a tool is not already allowed; read-only tools follow connection settings |
+| **Allow everything** | uses connected app tools automatically; denied tools remain blocked |
 
-Your choice sticks as the default for new chats. [Approvals and permissions](/features/approvals) covers the approval cards, saved tool rules, and what an organization policy can override.
+A choice here applies to this chat. Settings controls the default for chats without their own choice. [Approvals and permissions](/features/approvals) covers the approval cards, saved tool rules, and what an organization policy can override.
 
 ## Dictating
 
@@ -245,7 +244,7 @@ Hold `⌘` and each toolbar control labels itself with its own shortcut. Hold it
 | `⇧ Enter` | new line |
 | `↑` / `↓` | walk prompt history, then back to your draft |
 | `@` | open the context menu |
-| `⌘\` | cycle Quick, Deep, Max |
+| `⌘\` | cycle Fast, Medium, High where available |
 | `⌘⇧\` | cycle what Fluso may do alone |
 | `⌘D` | start or stop dictation |
 | `⌘⇧2` | screenshot into the composer (desktop app) |
diff --git a/content/docs/meta.json b/content/docs/meta.json
index 7435c5a..3d27ac8 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -12,6 +12,10 @@
     "[server-cog][Overview](/deployment-models)",
     "---Features---",
     "...features",
+    "---Fluso API---",
+    "...api",
+    "---Fluso Local---",
+    "...workspaces",
     "---Get started---",
     "going-deeper",
     "introduction",
diff --git a/content/docs/remote/telegram.mdx b/content/docs/remote/telegram.mdx
index c3f1d85..59cee88 100644
--- a/content/docs/remote/telegram.mdx
+++ b/content/docs/remote/telegram.mdx
@@ -58,7 +58,7 @@ Once you are signed in and have at least one app connected, ask in plain English
 
 If you ask for something that needs an app you have not connected yet, the bot will say so. Send `/connect <app>` and ask again.
 
-Connector writes in Telegram follow the same effective **Allow**, **Ask**, or **Deny** policy as the app. With **Ask**, the bot shows an approval card and waits for your decision. **Allow** or **Don't ask permission** can continue without a per-action prompt; **Deny** blocks the action.
+Connector writes in Telegram follow the same effective **Allow**, **Ask**, or **Deny** policy as the app. With **Ask**, the bot shows an approval card and waits for your decision. **Allow** or **Allow everything** can continue without a per-action prompt; **Deny** blocks the action.
 
 ## Fast mode
 
@@ -68,7 +68,7 @@ Send `/fast` again in the same Telegram conversation to switch back to High mode
 
 This is conversation-specific, not an account setting. `/newchat` starts a fresh Telegram conversation back in High mode.
 
-Telegram mode and app mode are separate. Using `/fast` in Telegram does not change any chat in the app, and changing the app's High/Fast dropdown does not change Telegram.
+Telegram mode and app mode are separate. Using `/fast` in Telegram does not change any chat in the app, and changing the app's response mode does not change Telegram.
 
 ## Files, images, voice
 
diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx
index fe6e722..f608459 100644
--- a/content/docs/resources/faq.mdx
+++ b/content/docs/resources/faq.mdx
@@ -79,7 +79,7 @@ description: The questions that come up most often. What Fluso is, how it works,
     It reads emails when you ask it to (e.g., *"summarise my inbox"*) and as part of auto-task extraction. It does not keep a separate mailbox copy. See [Legal](/resources/legal) for Fluso's privacy policy.
   </Accordion>
   <Accordion title="Does it send mail without my permission?">
-    Gmail send tools follow your effective **Allow**, **Ask**, or **Deny** policy. Use **Ask** to review each draft before it sends; **Allow** or **Don't ask permission** can continue without a per-action prompt.
+    Gmail send tools follow your effective **Allow**, **Ask**, or **Deny** policy. Use **Ask** to review each draft before it sends; **Allow** or **Allow everything** can continue without a per-action prompt.
   </Accordion>
   <Accordion title="Where is my data stored?">
     In your isolated workspace on encrypted infrastructure. Files, conversations, tasks, and the knowledge graph are private to you.
diff --git a/content/docs/resources/pricing.mdx b/content/docs/resources/pricing.mdx
index 2f4ac92..a878946 100644
--- a/content/docs/resources/pricing.mdx
+++ b/content/docs/resources/pricing.mdx
@@ -7,7 +7,7 @@ description: Compare plan limits, storage, automation, and workspace controls.
 
 Four plans. Free is enough to try Fluso on real work. Plus is for daily use. Pro adds heavier automation and confidential computing. Enterprise is the path for custom deployments, data residency, and server-integrated identity or audit work.
 
-Fluso uses only open-source models across all features, including Agent Studio. Your data never trains shared models. You get roughly 3× the tokens of equivalent closed-source assistants on the same task.
+Fluso uses only open-source models across all features. Your data never trains shared models. You get roughly 3× the tokens of equivalent closed-source assistants on the same task.
 
 ## Plans
 
@@ -75,7 +75,7 @@ Fluso uses only open-source models across all features, including Agent Studio.
 
 A few things hold regardless of plan.
 
-- **Open-source models only.** All Fluso features, including Agent Studio, use open-source models.
+- **Open-source models only.** All Fluso features, use open-source models.
 - **European hosting.** GDPR-aligned by default.
 - **3× more tokens** than equivalent closed-source assistants on a like-for-like task.
 - **Your data is yours.** Nothing trains shared models.
@@ -110,7 +110,7 @@ Obligation detection scans your connected apps for things you have committed to:
     Compared against equivalent closed-source assistants on a like-for-like task. The full methodology lives on the [pricing page](https://fluso.ai/pricing.html).
   </Accordion>
   <Accordion title="What models does Fluso use?">
-    Fluso uses only open-source models across all features, including Agent Studio.
+    Fluso uses only open-source models across all features.
   </Accordion>
   <Accordion title="Where is my data stored?">
     Fluso Cloud stores workspace data in the EU by default. Model inference and connected-App processing have their own provider boundaries. Enterprise customers can scope alternative data residency. Your data is never used to train shared models. See [Legal](/resources/legal) for Fluso's privacy policy.
diff --git a/content/docs/workflows/dev-bug-fix.mdx b/content/docs/workflows/dev-bug-fix.mdx
index 6da3f02..453968c 100644
--- a/content/docs/workflows/dev-bug-fix.mdx
+++ b/content/docs/workflows/dev-bug-fix.mdx
@@ -68,7 +68,7 @@ Always read the diff. Fluso writes good code, but you're still the engineer of r
 Drop a `context.md` in the repo describing your stack, conventions, and do-not-touch zones. Fluso reads and follows. The first PR after you add it will make the value obvious.
 
 <Warning>
-  Keep GitHub write tools on **Ask** to stop on each PR or push and review the diff. **Allow** or **Don't ask permission** can continue without a per-action prompt.
+  Choose **Ask me first** and keep GitHub write tools on **Ask** to review each requested PR or push. Ask to see the diff first. A saved **Allow** rule or **Allow everything** can continue without a per-action prompt.
 </Warning>
 
 ## Related
diff --git a/content/docs/workspaces/index.mdx b/content/docs/workspaces/index.mdx
new file mode 100644
index 0000000..26fe754
--- /dev/null
+++ b/content/docs/workspaces/index.mdx
@@ -0,0 +1,52 @@
+---
+title: Fluso Local
+sidebarTitle: Overview
+icon: monitor
+description: Set up Fluso on your own machine and use it for your daily work.
+---
+
+Fluso Local runs your workspace on a computer you control. Use your Mac for work with local files, or a Linux machine for work that continues after you close your laptop.
+
+You still talk to Fluso in the desktop app. Your conversations, Agents, and workspace files stay on the machine you choose.
+
+## Choose where to run it
+
+| Where | Useful for | How you connect |
+| --- | --- | --- |
+| Your Apple Silicon Mac | Working with documents on your laptop | Choose **This Mac** in Fluso |
+| A supported Linux machine | Keeping work running while your laptop is closed | Connect from Fluso on your Mac |
+
+A Linux machine can be at home or on a server you manage. A Raspberry Pi works only with a supported 64-bit system and working hardware virtualization.
+
+<CardGroup cols={2}>
+  <Card title="Set up Fluso Local" icon="download" href="/workspaces/setup">
+    Get the download, choose macOS or Linux, and connect the app.
+  </Card>
+  <Card title="Use Fluso Local" icon="messages-square" href="/workspaces/use">
+    Work with your files, keep an Agent, and schedule useful work.
+  </Card>
+</CardGroup>
+
+## What you need
+
+You install a background program called the **daemon** on the machine that will do the work. It runs separately from the desktop app. You also supply a model provider key and keep that machine awake for work to continue.
+
+[Contact us](mailto:support@premai.io?subject=Fluso%20Local%20download) for the daemon download links. Include your operating system, processor type, and whether you use Fluso or Fluso Dev.
+
+The [setup guide](/workspaces/setup) checks your machine before installation. You do not need Docker or a source checkout. For use without the desktop app, follow [API access](/api/first-request) after setup.
+
+## Where your work stays
+
+Each machine has its own conversations, Agents, files, and connections. They are separate from Fluso Cloud. Switching workspaces does not move or synchronize your work.
+
+Fluso can use files you upload or folders you explicitly share. It has no access to your other personal folders by default.
+
+Your chosen model provider receives the content needed to answer. Connected services receive their tool requests. Local storage does not make all processing local. The desktop interface still needs internet access and Fluso sign-in.
+
+<Accordion title="What differs from Cloud?">
+  Conversations, Agents, files, routines, and custom MCP connections use the selected workspace. Cloud billing, managed app connections, ingestion services, legacy Tasks, and public sharing are not available through the daemon.
+
+  Each paired client has access to the same owner's workspace. Pairing does not create separate user accounts or private areas for different people.
+</Accordion>
+
+Start with [Set up Fluso Local](/workspaces/setup). Return to [settings and maintenance](/workspaces/manage) for provider changes, updates, and backups.
diff --git a/content/docs/workspaces/manage.mdx b/content/docs/workspaces/manage.mdx
new file mode 100644
index 0000000..bafd6d5
--- /dev/null
+++ b/content/docs/workspaces/manage.mdx
@@ -0,0 +1,140 @@
+---
+title: Manage your workspace
+sidebarTitle: Settings and maintenance
+icon: settings-2
+description: Choose a provider, share folders, adjust resources, and keep your workspace recoverable.
+---
+
+Open **Workspaces** in Fluso and select the machine you want to change. These settings belong to that host, even when you use the app on another Mac.
+
+To use the terminal instead, run the commands below from the installed package folder on the host. Add `--root /path/to/state` only when selecting a different installation.
+
+## Choose a model provider
+
+Open **Model provider**, enter your provider details, then **Save and apply**. You supply the credentials. The daemon does not include a Fluso Cloud inference allowance.
+
+| Provider | What you supply |
+| --- | --- |
+| OpenRouter or OpenAI | API key and model ID |
+| Custom | An OpenAI-compatible base URL, API key, and exact model ID |
+| Prem · Confidential | Prem API key, then **Enable confidential inference** |
+
+For terminal setup, use `./fluso-daemon configure --apply`. Prompts hide your keys. Pressing Enter keeps a saved value.
+
+Saved changes need Apply or a restart before they take effect. Applying settings can restart the workspace's compute. Finish active work first. An explicit interruption can stop a running task.
+
+<Accordion title="Custom endpoints and confidential inference">
+  A custom endpoint must support streaming and tool calls, a 128K context window, and up to 16K output tokens. Use HTTPS for a remote provider. Local or trusted-network inference endpoints can use HTTP.
+
+  `localhost` refers to the daemon's host. For a Pi workspace, it does not refer to the Mac running Fluso. Changing an endpoint requires entering its key again.
+
+  Prem confidential inference verifies the provider and encrypts inference requests. It does not encrypt every workspace file or make external tools confidential. Image generation and speech synthesis are unavailable in this mode. Turning it off restores your saved standard provider.
+
+  Provider failures do not silently switch to another provider. Media features can need separate provider credentials. Configure these with the same CLI command.
+</Accordion>
+
+## Connect an app
+
+Open **Plugins → MCP → Add MCP** and choose **Custom server**. Enter the service's public MCP endpoint and supply its credentials or complete its OAuth sign-in.
+
+The daemon does not copy Cloud connections or provide the managed app catalog. Custom MCP destinations must be public: private network addresses and redirects are blocked. Review the service's permissions before you connect it.
+
+## Share a folder
+
+No personal host files are shared by default. Uploaded workspace files are separate from these grants.
+
+1. In **File access**, add the file or folder the Agent needs.
+2. Keep **Read only** for reference material. Choose **Read and write** for files the Agent should edit.
+3. Review the native confirmation and select **Save and apply**.
+
+For a report-writing task, share a reference folder read-only and a separate drafts folder with write access. Tell the Agent which folder holds each kind of file.
+
+On a remote workspace, enter paths on that remote host. A Mac path such as `/Users/alex/Drafts` appears to tools under `/mnt/host/Users/alex/Drafts`.
+
+Read-only access prevents edits, but content can still reach the chosen model provider. Share a specific folder instead of your entire home directory.
+
+<Accordion title="Change or remove file access">
+  Use `./fluso-daemon host-files --apply` for the same settings in a terminal.
+
+  A folder grant includes its descendants. A single-file grant permits in-place edits. Share the parent folder when a tool must rename or replace files. Overlapping grants are rejected.
+
+  Remove a path and apply the change to revoke access. This does not delete content already copied into the workspace or conversation. Operating-system permissions still apply to writable grants.
+</Accordion>
+
+## Adjust memory and storage
+
+The default sandbox has **3 GiB of RAM** and a **64 GiB disk budget**. The disk grows as needed: 56 GiB holds saved work and 8 GiB is for temporary work.
+
+Change these values in the workspace settings, or run `./fluso-daemon resources --apply`. Leave memory and disk space for the operating system and other applications.
+
+Runtime images, backups, and shared host folders are outside this disk budget. Reducing a limit must still leave room for saved data. Applying the change preserves saved files and replaces temporary storage.
+
+**Resources and storage** shows the data directory. On This Mac, **Open data folder** opens it in Finder. In a terminal, `./fluso-daemon info` shows the same paths.
+
+## Update the daemon
+
+Run this on the host:
+
+```bash
+./fluso-daemon update
+./fluso-daemon version
+./fluso-daemon status
+```
+
+The command finds the latest release for the installed development or production channel. You do not need another download URL or a GitHub login.
+
+It checks the download and signature before stopping the service. Updates keep files, conversations, settings, and pairings. If the replacement cannot start correctly, the updater restores the previous package.
+
+Updates run only when requested. The desktop app updates separately. A stopped service stays stopped. Active work must finish unless you explicitly allow interruption.
+
+Keep the current and previous package folders for recovery. Internet access is required for release verification.
+
+## Back up your work
+
+Run these commands one at a time on the host. Use a new backup folder:
+
+```bash
+mkdir -p "$HOME/fluso/backups"
+./fluso-daemon shutdown
+./fluso-daemon backup --backup-dir "$HOME/fluso/backups/first-backup"
+./fluso-daemon start
+```
+
+Continue to backup only after shutdown succeeds. Shutdown refuses to interrupt active work. If backup fails, inspect the error and restart the service when ready.
+
+The backup includes workspace files and its database. It excludes shared host folders. Back up those folders separately.
+
+Keep the **encryption key and file-access settings separately**. The backup does not contain the key needed to read saved credentials.
+
+- On macOS, the key is in the owner's Keychain.
+- On Linux, the key is in the installation's `keys` folder.
+- With `--root`, file-access settings are in `<root>/sandbox/config.json`. The default Mac path is `~/.fluso/sandbox/config.json`.
+
+Backup files can contain readable documents. Store them privately and include them in your protected host backups.
+
+<Accordion title="Restore a backup">
+  Restore accepts a backup from the same installation. Keep its original encryption key available. Stop the service, then run `./fluso-daemon restore --backup-dir /path/to/backup`. Start the service after restore succeeds.
+
+  Restore keeps the pre-restore data separately. You must pair clients again, restore host-file access, and explicitly resume schedules. Pending work and approvals are not resumed automatically.
+
+  If the key is lost, ask support about a credential reset. This can preserve files and conversations, but requires new credentials and connections.
+
+  Ask support before moving a workspace to another machine. Copying only the project-files folder or SQLite database is not a complete migration.
+</Accordion>
+
+## When something needs attention
+
+Start with `./fluso-daemon status` and `./fluso-daemon doctor`. `./fluso-daemon doctor --fix` can repair startup or an interrupted update without resetting credentials or deleting workspace data.
+
+| Symptom | What to check |
+| --- | --- |
+| Settings cannot be changed | Reconnect with a code made by `pair --manage-host`. |
+| Pairing code rejected | Generate a new code. Codes expire after ten minutes and work once. |
+| Remote workspace unreachable | Check the host service and SSH tunnel or HTTPS address. |
+| Configuration saved but not active | Apply it. If another client changed settings, reload and review before saving again. |
+| Work pauses when the laptop closes | Keep the host awake, or use an always-on Linux host. |
+| Model or tool call fails | Check that provider's credentials and the saved result before retrying work. |
+
+For logs, check `daemon.log` in the Mac data directory. On Linux, use `journalctl --user -u fluso-daemon` for the user service. Share the relevant error with [support](mailto:support@premai.io), without API keys or pairing codes.
+
+Disconnecting a reachable workspace revokes that client's access. Forgetting an offline connection cannot confirm revocation. Signing out or uninstalling the desktop app does not stop the daemon.
diff --git a/content/docs/workspaces/meta.json b/content/docs/workspaces/meta.json
new file mode 100644
index 0000000..fc64b41
--- /dev/null
+++ b/content/docs/workspaces/meta.json
@@ -0,0 +1,12 @@
+{
+  "pages": [
+    "!index",
+    "[monitor][Overview](/workspaces)",
+    "!setup",
+    "[download][Setup](/workspaces/setup)",
+    "!use",
+    "[messages-square][Everyday use](/workspaces/use)",
+    "!manage",
+    "[settings-2][Settings and maintenance](/workspaces/manage)"
+  ]
+}
diff --git a/content/docs/workspaces/setup.mdx b/content/docs/workspaces/setup.mdx
new file mode 100644
index 0000000..ddb9280
--- /dev/null
+++ b/content/docs/workspaces/setup.mdx
@@ -0,0 +1,206 @@
+---
+title: Set up Fluso Local
+sidebarTitle: Setup
+icon: download
+description: Install on macOS or Linux, choose a model provider, and connect Fluso.
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+Install the daemon on the machine that will run your work. You can use the same Mac as the desktop app, or connect to a separate Linux machine.
+
+You need internet access and your own model provider key. Allow at least 8 GiB of memory and 8 GiB of free disk space, plus room for files and backups.
+
+## 1. Get the download
+
+[Email support@premai.io](mailto:support@premai.io?subject=Fluso%20Local%20download) for the daemon package. Include your operating system, processor type, and whether you use Fluso or Fluso Dev.
+
+On a Mac, find these details in **Apple menu → About This Mac**. On Linux, run `uname -m` and `cat /etc/os-release`.
+
+Ask for the release version, archive URL, and matching checksum URL:
+
+| Machine | Archive | Checksum |
+| --- | --- | --- |
+| Apple Silicon Mac | `daemon-darwin-arm64.tar.gz` | `daemon-darwin-arm64.sha256` |
+| Linux ARM64 (`aarch64`) | `daemon-linux-arm64.tar.gz` | `daemon-linux-arm64.sha256` |
+| Linux x64 (`x86_64`) | `daemon-linux-x64.tar.gz` | `daemon-linux-x64.sha256` |
+
+Use links supplied by Fluso. You do not need a GitHub account, Docker, Bun, or a source checkout.
+
+## 2. Install on your machine
+
+Choose the operating system of the machine that will run Fluso:
+
+<Tabs items={['macOS', 'Linux']}>
+<Tab value="macOS">
+
+You need an **Apple Silicon Mac**. This package does not support Intel Macs.
+
+**Download and check.** Open Terminal. Replace `ARCHIVE_URL` and `CHECKSUM_URL` with your links, keeping the quotes:
+
+```bash
+mkdir -p "$HOME/Downloads/fluso-daemon" &&
+cd "$HOME/Downloads/fluso-daemon" &&
+curl --fail --location 'ARCHIVE_URL' -o daemon-darwin-arm64.tar.gz &&
+curl --fail --location 'CHECKSUM_URL' -o daemon-darwin-arm64.sha256 &&
+shasum -a 256 -c daemon-darwin-arm64.sha256
+```
+
+Continue only if the check prints `daemon-darwin-arm64.tar.gz: OK`. If it fails, download both files again from the matching release links.
+
+**Extract the package.** Replace `RELEASE_VERSION` with the version supplied by support. Use a new folder:
+
+```bash
+mkdir -p "$HOME/fluso/releases" &&
+mkdir "$HOME/fluso/releases/RELEASE_VERSION" &&
+tar -xzf daemon-darwin-arm64.tar.gz -C "$HOME/fluso/releases/RELEASE_VERSION" &&
+cd "$HOME/fluso/releases/RELEASE_VERSION"
+```
+
+Keep the whole folder in place. The executable needs the other files beside it. For later releases, use [update](/workspaces/manage#update-the-daemon).
+
+**Start and configure.** Run these commands one at a time as your normal Mac user, without `sudo`. If a command fails, stop and check its error:
+
+```bash
+./fluso-daemon setup --manage-host
+./fluso-daemon configure --apply
+./fluso-daemon status
+```
+
+Setup checks the signed package and installs a background service. Follow the prompts to choose your model provider, model, and API key. Key entry stays hidden. Prem confidential inference needs only your Prem API key.
+
+Respond to macOS Keychain or folder-access prompts. Wait for `status` to report that the workspace is ready.
+
+The service starts when you log in. Closing Fluso leaves it running. Putting the Mac to sleep pauses its work.
+
+</Tab>
+<Tab value="Linux">
+
+Use **64-bit glibc Linux with systemd**: Ubuntu 24.04, Debian 13, or newer. The packages support ARM64 and x64.
+
+The host needs **KVM**, Linux's hardware virtualization facility. A virtual machine also needs nested virtualization from its host provider.
+
+**Check access to KVM.** Run this on the Linux machine:
+
+```bash
+test -r /dev/kvm && test -w /dev/kvm && echo 'KVM access is ready'
+```
+
+If it does not print `KVM access is ready`, stop here. Ask your administrator to enable KVM and grant your user read/write access. After a group-permission change, sign out and sign in again.
+
+<Note>
+  A Raspberry Pi needs a supported 64-bit operating system and kernel with usable KVM. An ARM64 processor alone is not enough. Send your system details and KVM check to support if you are unsure.
+</Note>
+
+On Ubuntu or Debian, install the native library and download tools:
+
+```bash
+sudo apt-get update
+sudo apt-get install libcap-ng0 curl ca-certificates
+```
+
+**Download and check.** These commands use ARM64. On x64, replace every `arm64` with `x64`. Replace the two URL placeholders with your links:
+
+```bash
+mkdir -p "$HOME/Downloads/fluso-daemon" &&
+cd "$HOME/Downloads/fluso-daemon" &&
+curl --fail --location 'ARCHIVE_URL' -o daemon-linux-arm64.tar.gz &&
+curl --fail --location 'CHECKSUM_URL' -o daemon-linux-arm64.sha256 &&
+sha256sum -c daemon-linux-arm64.sha256
+```
+
+Continue only if the check prints `OK`. If it fails, download both files again from the matching release links.
+
+**Extract the package.** Replace `RELEASE_VERSION` with the supplied version. Use a new folder:
+
+```bash
+mkdir -p "$HOME/fluso/releases" &&
+mkdir "$HOME/fluso/releases/RELEASE_VERSION" &&
+tar -xzf daemon-linux-arm64.tar.gz -C "$HOME/fluso/releases/RELEASE_VERSION" &&
+cd "$HOME/fluso/releases/RELEASE_VERSION"
+```
+
+Keep all extracted files together. Do not overwrite an installed package. Use [update](/workspaces/manage#update-the-daemon) for later releases.
+
+**Start and configure.** Run these commands one at a time as the workspace owner, without `sudo`. If a command fails, stop and check its error:
+
+```bash
+./fluso-daemon setup --root "$HOME/fluso/state" --manage-host
+./fluso-daemon configure --root "$HOME/fluso/state" --apply
+./fluso-daemon status
+```
+
+Follow the prompts for your own model provider and key. Setup keeps data and keys under `~/fluso/state`, outside the package. It remembers this installation for later commands.
+
+Wait for the workspace to become ready. Setup also arranges for the user service to run after logout and at boot. If administrator approval is needed, it prints a `sudo loginctl enable-linger` command. Have your administrator run that exact command.
+
+</Tab>
+</Tabs>
+
+`--manage-host` lets the connected app change the provider, resource limits, and shared folders. You can review these in [workspace settings](/workspaces/manage).
+
+## 3. Connect Fluso
+
+Open the matching, current [Fluso desktop app](https://fluso.ai/) on your Mac and sign in.
+
+### On the same Mac
+
+1. Open **Workspaces** from the account menu. **View → Workspace settings** opens the same page.
+2. Open the workspace selector and choose **This Mac**. Complete any native confirmation.
+
+### Connect from another Mac
+
+The machine running Fluso must be reachable through SSH or HTTPS. For a Linux host, the SSH connection below is a way to start. You do not need a daemon on the Mac that connects to it.
+
+On the host, create a pairing code from the package folder:
+
+```bash
+./fluso-daemon pair --manage-host
+```
+
+Keep the code private. Each code works once and expires after ten minutes. It gives the client workspace access and permission to change host settings.
+
+On your Mac, open Terminal. Replace `USER` and `HOST` with your host login and address:
+
+```bash
+ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:4111:127.0.0.1:4111 USER@HOST
+```
+
+Leave this terminal open. Use the same local and remote port shown by setup. The daemon checks the port in incoming requests.
+
+1. Open **Workspaces** in the current Fluso desktop app.
+2. Under **Connect a remote workspace**, enter a name, such as `Home server`.
+3. Enter `http://127.0.0.1:4111` as the **Workspace URL**, then paste the pairing code.
+4. Select **Connect**.
+
+Closing the tunnel disconnects the client. It does not stop work on the host. Reopen the tunnel to reconnect. Pairing remains valid unless revoked or unused for 30 days.
+
+<Accordion title="Port 4111 is already in use on my Mac">
+  A Mac daemon or another tunnel may already use that port. For a new host installation, choose two free ports during setup, for example `--port 4211 --control-port 4212`.
+
+  Forward `127.0.0.1:4211` to `127.0.0.1:4211` and use port `4211` in the workspace URL. For an existing host, stop its service before repeating setup with changed ports. Keep its original `--root`.
+</Accordion>
+
+<Accordion title="Use a permanent HTTPS address instead">
+  For a host with DNS and a trusted TLS certificate, add `--public-origin https://workspace.example.com` during setup. Put an HTTPS reverse proxy in front of port `4111`.
+
+  The proxy must preserve the requested Host, support streamed responses, and block `/control/*`. Keep both daemon ports on loopback. Port `4112` is private runtime control. Configure OAuth callbacks for the final HTTPS origin.
+
+  Use the HTTPS URL and a fresh pairing code in Fluso. Ordinary remote HTTP is not accepted. Ask support for help if you do not manage this infrastructure.
+</Accordion>
+
+## 4. Try your first task
+
+Open a chat in the selected workspace. Attach a short document and ask Fluso to summarize its main points.
+
+Your Cloud conversations stay in Cloud. This workspace has its own data. Continue with [Use Fluso Local](/workspaces/use) for files, Agents, and routines.
+
+<Accordion title="The workspace is missing or not ready">
+  From the package folder, run `./fluso-daemon status` and `./fluso-daemon doctor`. Use `./fluso-daemon info` to see its paths and API address.
+
+  Start a stopped service with `./fluso-daemon start`. If configuration is missing, rerun `./fluso-daemon configure --apply`.
+
+  In **Workspaces**, refresh the workspace list. A release mismatch requires a compatible desktop app and daemon. Changing the data directory does not fix it. Keep the original data and keys when diagnosing an existing installation.
+
+  If macOS cannot verify the developer, use **System Settings → Privacy & Security → Open Anyway** only for the package supplied by Fluso. Follow [Apple's instructions](https://support.apple.com/en-us/102445) after checking the download. For a damaged-file or malware warning, contact support with the exact message.
+</Accordion>
diff --git a/content/docs/workspaces/use.mdx b/content/docs/workspaces/use.mdx
new file mode 100644
index 0000000..730148e
--- /dev/null
+++ b/content/docs/workspaces/use.mdx
@@ -0,0 +1,58 @@
+---
+title: Use Fluso Local
+sidebarTitle: Everyday use
+icon: messages-square
+description: Work with your files, return to an Agent, and keep useful work running.
+---
+
+After [setup](/workspaces/setup), you use Fluso through the same desktop app. Start with a small task and check the result before giving it more work.
+
+## Open your workspace
+
+Open **Workspaces** from the account menu. Choose **This Mac** or the remote connection you saved.
+
+Each workspace has its own conversations, Agents, files, and connections. If your Cloud chats are missing, switch to **Fluso Cloud** to see them.
+
+When you reopen the app, it starts on Cloud. Select your saved local or remote workspace again.
+
+## Start with a document
+
+Open a chat and attach a document with the **+** button, or drag it into the conversation. Try a set of meeting notes:
+
+> *"Turn these notes into a short plan for next week. Separate agreed actions from open questions. Include an owner or date only where the notes give one."*
+
+Read the answer against your notes. Continue in the same chat to correct a detail or add another document.
+
+An attachment copies the file into the selected workspace. It does not give Fluso access to the rest of your computer.
+
+## Work with a folder
+
+For files you use repeatedly, [share a folder](/workspaces/manage#share-a-folder) in workspace settings. Keep reference files read-only. Grant write access only where you want Fluso to edit files.
+
+Tell Fluso the folder path shown by the settings and what you want:
+
+> *"Review the meeting notes in this folder. Give me a short list of decisions that are still open, with the source file for each. Leave the files unchanged."*
+
+For a remote workspace, shared folders belong to the remote machine. Attach a file from your Mac when you want to copy it there.
+
+## Keep an Agent for repeat work
+
+Create an [Agent](/developers/agent-builder) in this workspace to keep instructions for a job you return to. For example, keep an assistant for reviewing your project notes.
+
+Once its results are useful, ask in the Agent's working conversation:
+
+> *"Every Friday at 4 PM in Europe/Zurich, review this project's notes. Summarize progress, open decisions, and next week's priorities here."*
+
+Use your own time and timezone. Check the saved [routine](/developers/schedules) in **Routines**. Read its results in the conversation or **Inbox**.
+
+The machine running Fluso must stay awake and connected. Closing the desktop app leaves accepted work running. After downtime, missed recurring runs are combined into one catch-up run.
+
+## Return from another location
+
+For a remote machine, reopen your [SSH tunnel](/workspaces/setup#connect-from-another-mac) or use its configured HTTPS address. Your Mac must be able to reach that machine. Pairing alone does not make a home computer reachable over the internet.
+
+Select the saved connection to return to its work. Closing the tunnel disconnects your app, but leaves work running on the remote machine.
+
+To use an external service, [connect its custom MCP server](/workspaces/manage#connect-an-app) in this workspace. Cloud app connections do not carry over.
+
+For provider changes, storage, updates, and backups, open [settings and maintenance](/workspaces/manage).
diff --git a/public/_redirects b/public/_redirects
index a38137d..e8391c6 100644
--- a/public/_redirects
+++ b/public/_redirects
@@ -4,3 +4,75 @@
 /resources/security/ /resources/legal 301
 /llms.mdx/docs/resources/privacy/content.md /llms.mdx/docs/resources/legal/content.md 301
 /llms.mdx/docs/resources/security/content.md /llms.mdx/docs/resources/legal/content.md 301
+/developers/evaluations /developers/agent-builder 301
+/developers/evaluations/ /developers/agent-builder 301
+/llms.mdx/docs/developers/evaluations/content.md /llms.mdx/docs/developers/agent-builder/content.md 301
+/developers/versions /developers/improve 301
+/developers/versions/ /developers/improve 301
+/llms.mdx/docs/developers/versions/content.md /llms.mdx/docs/developers/improve/content.md 301
+/developers/webhooks /developers/schedules 301
+/developers/webhooks/ /developers/schedules 301
+/llms.mdx/docs/developers/webhooks/content.md /llms.mdx/docs/developers/schedules/content.md 301
+/developers/user-preferences /developers/guides/files 301
+/developers/user-preferences/ /developers/guides/files 301
+/llms.mdx/docs/developers/user-preferences/content.md /llms.mdx/docs/developers/guides/files/content.md 301
+/developers/context-isolation-in-threads /developers/guides/files 301
+/developers/context-isolation-in-threads/ /developers/guides/files 301
+/llms.mdx/docs/developers/context-isolation-in-threads/content.md /llms.mdx/docs/developers/guides/files/content.md 301
+/developers/parent-and-child-threads /developers/guides/conversations 301
+/developers/parent-and-child-threads/ /developers/guides/conversations 301
+/llms.mdx/docs/developers/parent-and-child-threads/content.md /llms.mdx/docs/developers/guides/conversations/content.md 301
+/developers/agent-description /developers/guides/settings 301
+/developers/agent-description/ /developers/guides/settings 301
+/llms.mdx/docs/developers/agent-description/content.md /llms.mdx/docs/developers/guides/settings/content.md 301
+/developers/threads-and-contexts /developers/guides/conversations 301
+/developers/threads-and-contexts/ /developers/guides/conversations 301
+/llms.mdx/docs/developers/threads-and-contexts/content.md /llms.mdx/docs/developers/guides/conversations/content.md 301
+/developers/project-context /developers/guides/files 301
+/developers/project-context/ /developers/guides/files 301
+/llms.mdx/docs/developers/project-context/content.md /llms.mdx/docs/developers/guides/files/content.md 301
+/developers/inbox /developers/guides/inbox 301
+/developers/inbox/ /developers/guides/inbox 301
+/llms.mdx/docs/developers/inbox/content.md /llms.mdx/docs/developers/guides/inbox/content.md 301
+/developers/export-import-and-share-agents /developers/guides/sharing 301
+/developers/export-import-and-share-agents/ /developers/guides/sharing 301
+/llms.mdx/docs/developers/export-import-and-share-agents/content.md /llms.mdx/docs/developers/guides/sharing/content.md 301
+/developers/architecture /api 301
+/developers/architecture/ /api 301
+/llms.mdx/docs/developers/architecture/content.md /llms.mdx/docs/api/content.md 301
+/workspaces/macos /workspaces/setup 301
+/workspaces/macos/ /workspaces/setup 301
+/workspaces/linux /workspaces/setup 301
+/workspaces/linux/ /workspaces/setup 301
+/llms.mdx/docs/workspaces/macos/content.md /llms.mdx/docs/workspaces/setup/content.md 301
+/llms.mdx/docs/workspaces/linux/content.md /llms.mdx/docs/workspaces/setup/content.md 301
+/developers/api-ref/authentication /api/first-request 301
+/developers/api-ref/authentication/ /api/first-request 301
+/llms.mdx/docs/developers/api-ref/authentication/content.md /llms.mdx/docs/api/first-request/content.md 301
+/developers/api-ref/threads-and-messages /api/workflows/conversations 301
+/developers/api-ref/threads-and-messages/ /api/workflows/conversations 301
+/llms.mdx/docs/developers/api-ref/threads-and-messages/content.md /llms.mdx/docs/api/workflows/conversations/content.md 301
+/developers/api-ref/runs /api/workflows/runs 301
+/developers/api-ref/runs/ /api/workflows/runs 301
+/llms.mdx/docs/developers/api-ref/runs/content.md /llms.mdx/docs/api/workflows/runs/content.md 301
+/developers/api-ref/agents-and-versions /api/workflows/agents 301
+/developers/api-ref/agents-and-versions/ /api/workflows/agents 301
+/llms.mdx/docs/developers/api-ref/agents-and-versions/content.md /llms.mdx/docs/api/workflows/agents/content.md 301
+/developers/api-ref/files-and-projects /api/workflows/files 301
+/developers/api-ref/files-and-projects/ /api/workflows/files 301
+/llms.mdx/docs/developers/api-ref/files-and-projects/content.md /llms.mdx/docs/api/workflows/files/content.md 301
+/developers/api-ref/schedules /api/workflows/schedules 301
+/developers/api-ref/schedules/ /api/workflows/schedules 301
+/llms.mdx/docs/developers/api-ref/schedules/content.md /llms.mdx/docs/api/workflows/schedules/content.md 301
+/developers/api-ref/usage /api/workflows/usage 301
+/developers/api-ref/usage/ /api/workflows/usage 301
+/llms.mdx/docs/developers/api-ref/usage/content.md /llms.mdx/docs/api/workflows/usage/content.md 301
+/developers/api-ref/sharing /api/cloud/sharing 301
+/developers/api-ref/sharing/ /api/cloud/sharing 301
+/llms.mdx/docs/developers/api-ref/sharing/content.md /llms.mdx/docs/api/cloud/sharing/content.md 301
+/developers/api-ref/architecture /api 301
+/developers/api-ref/architecture/ /api 301
+/llms.mdx/docs/developers/api-ref/architecture/content.md /llms.mdx/docs/api/content.md 301
+/api/architecture /api 301
+/api/architecture/ /api 301
+/llms.mdx/docs/api/architecture/content.md /llms.mdx/docs/api/content.md 301
diff --git a/public/images/agents/agent-capabilities.png b/public/images/agents/agent-capabilities.png
new file mode 100644
index 0000000..1c4ef6f
Binary files /dev/null and b/public/images/agents/agent-capabilities.png differ
diff --git a/public/images/agents/inbox-result.png b/public/images/agents/inbox-result.png
new file mode 100644
index 0000000..27d2c97
Binary files /dev/null and b/public/images/agents/inbox-result.png differ
diff --git a/public/images/agents/knowledge-files.png b/public/images/agents/knowledge-files.png
new file mode 100644
index 0000000..07f2d4f
Binary files /dev/null and b/public/images/agents/knowledge-files.png differ
diff --git a/public/images/agents/meeting-brief.png b/public/images/agents/meeting-brief.png
new file mode 100644
index 0000000..b782ee8
Binary files /dev/null and b/public/images/agents/meeting-brief.png differ
diff --git a/public/images/agents/meeting-create.png b/public/images/agents/meeting-create.png
new file mode 100644
index 0000000..6ca1d21
Binary files /dev/null and b/public/images/agents/meeting-create.png differ
diff --git a/public/images/agents/meeting-manager.png b/public/images/agents/meeting-manager.png
new file mode 100644
index 0000000..404db33
Binary files /dev/null and b/public/images/agents/meeting-manager.png differ
diff --git a/public/images/agents/meeting-refinement.png b/public/images/agents/meeting-refinement.png
new file mode 100644
index 0000000..1bd5424
Binary files /dev/null and b/public/images/agents/meeting-refinement.png differ
diff --git a/public/images/agents/my-agents.png b/public/images/agents/my-agents.png
new file mode 100644
index 0000000..ed4ac45
Binary files /dev/null and b/public/images/agents/my-agents.png differ
diff --git a/public/images/agents/review-request.png b/public/images/agents/review-request.png
new file mode 100644
index 0000000..2772e8a
Binary files /dev/null and b/public/images/agents/review-request.png differ
diff --git a/public/images/agents/routine-editor.png b/public/images/agents/routine-editor.png
new file mode 100644
index 0000000..e67458a
Binary files /dev/null and b/public/images/agents/routine-editor.png differ
diff --git a/public/images/agents/routine-result.png b/public/images/agents/routine-result.png
new file mode 100644
index 0000000..8b6e65c
Binary files /dev/null and b/public/images/agents/routine-result.png differ
diff --git a/public/images/agents/sessions-list.png b/public/images/agents/sessions-list.png
new file mode 100644
index 0000000..0df178a
Binary files /dev/null and b/public/images/agents/sessions-list.png differ
diff --git a/public/images/agents/share-options.png b/public/images/agents/share-options.png
new file mode 100644
index 0000000..621b924
Binary files /dev/null and b/public/images/agents/share-options.png differ
diff --git a/public/images/api/developer-token-form.png b/public/images/api/developer-token-form.png
new file mode 100644
index 0000000..832d687
Binary files /dev/null and b/public/images/api/developer-token-form.png differ