docs: add Agent guides and nested API reference

AGENTS.md

@@ -10,14 +10,16 @@
 
 ## Information architecture
 
-The IA tracks the user's journey from "just landed" to "pro user". Beta documentation sits first, followed by the core product journey, Remote access, Reference, and Release notes:
-
-- **Agents (Beta)** - `/developers/*`. The public REST reference and a source-backed architecture overview.
-- **Get started** — `/introduction`, `/quickstart`, `/going-deeper`. The path from "is this for me?" through "I have it set up" to "I've made it part of my work".
-- **Workflows** — `/workflows/*`. Six concrete stories: morning brief, meetings, research-to-deck, content launch, bug-to-PR, knowledge recall.
-- **Features** — the five primitives: `/features/{chat, mcp, skills, tasks, memory}`. Everything Fluso does is some combination of these five.
-- **App setup** — `/integrations/{gmail, google-calendar, slack, github}`. Per-app permissions and prompts, not feature pages. All of them connect through the Apps tab of the Add MCP dialog.
-- **Reference** — `/resources/{pricing, security, privacy, faq}`. Security covers infrastructure; Privacy covers data handling; they're distinct pages.
+The navigation keeps Home first, then sorts the top-level sections and the pages inside each section alphabetically:
+
+- **Agents (Beta)** - `/developers/*`. Guides cover Agent setup, threads, context, projects, schedules, and preferences. Architecture and the REST API reference live here too, with API pages under `/developers/api-ref/*`.
+- **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.
+- **Features** - `/features/*`. Approvals and permissions, Apps and MCP servers, Chat, Confidential mode, Imports, Memory, Skills, and Tasks.
+- **Get started** - `/going-deeper`, `/introduction`, `/quickstart`. These pages explain the path from first setup to daily use.
+- **Reference** - `/resources/{faq, pricing, privacy, security}`. Security covers infrastructure; Privacy covers data handling; they're distinct pages.
+- **Release notes** - `/release-notes`. Customer-facing changes, newest first.
+- **Remote access** - `/remote/*`. Ways to use Fluso away from the desktop app.
+- **Workflows** - `/workflows/*`. Six concrete stories: bug-to-PR, content launch, knowledge recall, meetings, morning brief, and research-to-deck.
 
 The home page (`/`) is a router into the journey, with three sections: just landed, already set up, daily user.
 

content/docs/developers/agent-builder.mdx

@@ -0,0 +1,40 @@
+---
+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.
+---
+
+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.
+
+> *"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."*
+
+## Build the first draft
+
+A useful request names four things:
+
+- 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.
+
+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.
+
+## Refine without starting over
+
+Use the Studio message box to change the draft:
+
+> *"Only use P0 and P1. Run the Gmail and Drive lookups in parallel. Stop for approval before sending a customer reply."*
+
+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.
+
+## Create or open the editor
+
+- 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.
+
+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.
+
+## Next
+
+See [Agent description](/developers/agent-description) for field boundaries and [Threads and contexts](/developers/threads-and-contexts) for what a new Agent thread receives.

content/docs/developers/agent-description.mdx

@@ -0,0 +1,35 @@
+---
+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).

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

@@ -7,7 +7,7 @@ description: Create Agents, read their current immutable configuration, and publ
 
 An Agent record points at one immutable configuration through `currentConfigId`. Use that ID as `baseConfigId` when you update the Agent.
 
-Agent-owned work runs in [threads](/developers/threads-and-messages) and can start from [schedules](/developers/schedules).
+Agent-owned work runs in [threads](/developers/api-ref/threads-and-messages) and can start from [schedules](/developers/api-ref/schedules).
 
 ## List Agents
 
@@ -206,4 +206,4 @@ HTTP/1.1 204 No Content
 
 ## Next
 
-Start Agent work through [Threads and messages](/developers/threads-and-messages), or automate it with [Schedules](/developers/schedules).
+Start Agent work through [Threads and messages](/developers/api-ref/threads-and-messages), or automate it with [Schedules](/developers/api-ref/schedules).

content/docs/developers/authentication.mdx → content/docs/developers/api-ref/authentication.mdx

@@ -22,7 +22,7 @@ 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/agents-and-versions).
+Once authenticated, start with [Agents and versions](/developers/api-ref/agents-and-versions).
 
 ## Start client sign-in
 
@@ -132,4 +132,4 @@ curl "$FLUSO_API/v1/auth/me" \
 
 ## Next
 
-Use the token with [Agents and versions](/developers/agents-and-versions), or open a turn through [Threads and messages](/developers/threads-and-messages).
+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).

content/docs/developers/files-and-projects.mdx → content/docs/developers/api-ref/files-and-projects.mdx

@@ -7,7 +7,7 @@ description: Work with durable project metadata and files in a user's Agent work
 
 Workspace projects and files use the `/v1/agent/*` routes. They belong to the authenticated user's durable workspace, outside disposable runtime compute.
 
-[Agents](/developers/agents-and-versions) bind new chats to one of these projects by name.
+[Agents](/developers/api-ref/agents-and-versions) bind new chats to one of these projects by name.
 
 ## List projects
 
@@ -228,4 +228,4 @@ curl -G "$FLUSO_API/v1/agent/files" \
 
 ## Next
 
-Attach project context to [Agents and versions](/developers/agents-and-versions), or create project-bound [Threads and messages](/developers/threads-and-messages).
+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).

content/docs/developers/api-ref/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "API ref",
+  "icon": "code-xml",
+  "defaultOpen": false,
+  "pages": [
+    "agents-and-versions",
+    "authentication",
+    "files-and-projects",
+    "runs",
+    "schedules",
+    "threads-and-messages",
+    "usage"
+  ]
+}

content/docs/developers/runs.mdx → content/docs/developers/api-ref/runs.mdx

@@ -7,7 +7,7 @@ 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/threads-and-messages) and [schedules](/developers/schedules).
+Runs originate from [messages](/developers/api-ref/threads-and-messages) and [schedules](/developers/api-ref/schedules).
 
 ## List runs
 
@@ -106,4 +106,4 @@ The status can also be `already_terminal` when the run settled before cancellati
 
 ## Next
 
-Inspect token cost in [Usage](/developers/usage), or create recurring and one-time [Schedules](/developers/schedules).
+Inspect token cost in [Usage](/developers/api-ref/usage), or create recurring and one-time [Schedules](/developers/api-ref/schedules).

content/docs/developers/api-ref/schedules.mdx

@@ -0,0 +1,139 @@
+---
+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).

content/docs/developers/threads-and-messages.mdx → content/docs/developers/api-ref/threads-and-messages.mdx

@@ -7,7 +7,7 @@ description: Create threads, manage their metadata, read history, and stream a t
 
 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/agents-and-versions), and each accepted turn creates a [run](/developers/runs).
+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
 
@@ -171,4 +171,4 @@ curl "$FLUSO_API/v1/threads/thread_release?project_id=Release%20Review" \
 
 ## Next
 
-Bind new threads to [Agents and versions](/developers/agents-and-versions), or follow accepted turns in [Runs](/developers/runs).
+Bind new threads to [Agents and versions](/developers/api-ref/agents-and-versions), or follow accepted turns in [Runs](/developers/api-ref/runs).

content/docs/developers/usage.mdx → content/docs/developers/api-ref/usage.mdx

@@ -7,7 +7,7 @@ description: Read current-user totals, session summaries, and filtered raw usage
 
 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/runs).
+Filter entries by the request and thread identifiers returned from [Runs](/developers/api-ref/runs).
 
 ## Read usage totals
 
@@ -141,4 +141,4 @@ curl "$FLUSO_API/v1/token-usage/entries?threadId=thread_agent_release&limit=100"
 
 ## Next
 
-Correlate costs with [Runs](/developers/runs), or review the service boundaries in [Architecture](/developers/architecture).
+Correlate costs with [Runs](/developers/api-ref/runs), or review the service boundaries in [Architecture](/developers/architecture).

content/docs/developers/architecture.mdx

@@ -7,7 +7,7 @@ description: How requests, runtime compute, platform state, workspace data, and
 
 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/authentication).
+Client requests enter these boundaries through the [authenticated REST API](/developers/api-ref/authentication).
 
 <ArchitectureDiagram />
 
@@ -54,4 +54,4 @@ External data stays under the source system's own controls until an approved too
 
 ## Next
 
-Start with [Authentication](/developers/authentication), then create an Agent through [Agents and versions](/developers/agents-and-versions).
+Start with [Authentication](/developers/api-ref/authentication), then create an Agent through [Agents and versions](/developers/api-ref/agents-and-versions).

content/docs/developers/context-isolation-in-threads.mdx

@@ -0,0 +1,34 @@
+---
+title: Context isolation in threads
+sidebarTitle: Context isolation
+icon: lock-keyhole
+description: Understand what an Agent thread keeps to itself and what it shares with other threads.
+---
+
+Each Agent thread has its own conversation history and session state. Starting a new thread gives you a clean conversation. Sending work to a child thread passes the message you send, not the parent's full transcript.
+
+A new thread does not receive another thread's conversation history, but it can still access shared project files and other resources.
+
+## What stays in one thread
+
+- The message history for that conversation.
+- In-progress turn state and temporary session data.
+- The Agent definition captured when the thread was created.
+- References to attached files in that thread's history.
+
+## What threads can share
+
+Each thread uses the resources in the saved Agent definition it started with. Threads started from the same definition can use the same knowledge files and capabilities. Threads in the same configured project can also use:
+
+- The project's files.
+- Short project working-memory summaries from other threads.
+
+If two threads edit the same resource at once, their changes can conflict.
+
+## When to start a new thread
+
+Use a new thread when the topic has changed, when a task needs its own history, or when two independent tasks can progress separately. Keep the current thread when the next step depends on the full conversation.
+
+## Next
+
+See [Parent and child threads](/developers/parent-and-child-threads) for delegation rules and [Threads and contexts](/developers/threads-and-contexts) for the complete context map.