diff --git a/AGENTS.md b/AGENTS.md index cef0aba..55d1dbe 100644 --- a/AGENTS.md +++ b/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. diff --git a/content/docs/developers/agent-builder.mdx b/content/docs/developers/agent-builder.mdx new file mode 100644 index 0000000..879e42d --- /dev/null +++ b/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. diff --git a/content/docs/developers/agent-description.mdx b/content/docs/developers/agent-description.mdx new file mode 100644 index 0000000..c2aa449 --- /dev/null +++ b/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). diff --git a/content/docs/developers/agents-and-versions.mdx b/content/docs/developers/api-ref/agents-and-versions.mdx similarity index 95% rename from content/docs/developers/agents-and-versions.mdx rename to content/docs/developers/api-ref/agents-and-versions.mdx index b536039..31db932 100644 --- a/content/docs/developers/agents-and-versions.mdx +++ b/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). diff --git a/content/docs/developers/authentication.mdx b/content/docs/developers/api-ref/authentication.mdx similarity index 94% rename from content/docs/developers/authentication.mdx rename to content/docs/developers/api-ref/authentication.mdx index 0d946ce..eb0e118 100644 --- a/content/docs/developers/authentication.mdx +++ b/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). diff --git a/content/docs/developers/files-and-projects.mdx b/content/docs/developers/api-ref/files-and-projects.mdx similarity index 94% rename from content/docs/developers/files-and-projects.mdx rename to content/docs/developers/api-ref/files-and-projects.mdx index 837359d..0905c46 100644 --- a/content/docs/developers/files-and-projects.mdx +++ b/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). diff --git a/content/docs/developers/api-ref/meta.json b/content/docs/developers/api-ref/meta.json new file mode 100644 index 0000000..4b3d096 --- /dev/null +++ b/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" + ] +} diff --git a/content/docs/developers/runs.mdx b/content/docs/developers/api-ref/runs.mdx similarity index 91% rename from content/docs/developers/runs.mdx rename to content/docs/developers/api-ref/runs.mdx index f0cf041..f0e6e04 100644 --- a/content/docs/developers/runs.mdx +++ b/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). diff --git a/content/docs/developers/api-ref/schedules.mdx b/content/docs/developers/api-ref/schedules.mdx new file mode 100644 index 0000000..4ee3bd6 --- /dev/null +++ b/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 + + + +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 + + + +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 + + + +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 + + + +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/threads-and-messages.mdx b/content/docs/developers/api-ref/threads-and-messages.mdx similarity index 93% rename from content/docs/developers/threads-and-messages.mdx rename to content/docs/developers/api-ref/threads-and-messages.mdx index c59a7b4..8eeb577 100644 --- a/content/docs/developers/threads-and-messages.mdx +++ b/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). diff --git a/content/docs/developers/usage.mdx b/content/docs/developers/api-ref/usage.mdx similarity index 95% rename from content/docs/developers/usage.mdx rename to content/docs/developers/api-ref/usage.mdx index 37dd4e5..1bb9622 100644 --- a/content/docs/developers/usage.mdx +++ b/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). diff --git a/content/docs/developers/architecture.mdx b/content/docs/developers/architecture.mdx index ae4b987..999819d 100644 --- a/content/docs/developers/architecture.mdx +++ b/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). @@ -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). diff --git a/content/docs/developers/context-isolation-in-threads.mdx b/content/docs/developers/context-isolation-in-threads.mdx new file mode 100644 index 0000000..0045423 --- /dev/null +++ b/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. diff --git a/content/docs/developers/meta.json b/content/docs/developers/meta.json index 4c27a7f..e6f86db 100644 --- a/content/docs/developers/meta.json +++ b/content/docs/developers/meta.json @@ -1,12 +1,14 @@ { "pages": [ - "agents-and-versions", + "agent-builder", + "agent-description", + "api-ref", "architecture", - "authentication", - "files-and-projects", - "runs", + "context-isolation-in-threads", + "parent-and-child-threads", + "project-context", "schedules", - "threads-and-messages", - "usage" + "threads-and-contexts", + "user-preferences" ] } diff --git a/content/docs/developers/parent-and-child-threads.mdx b/content/docs/developers/parent-and-child-threads.mdx new file mode 100644 index 0000000..9802750 --- /dev/null +++ b/content/docs/developers/parent-and-child-threads.mdx @@ -0,0 +1,41 @@ +--- +title: Parent and child threads +sidebarTitle: Parent & child threads +icon: git-fork +description: Let a top-level Agent thread coordinate independent work without mixing every conversation together. +--- + +A top-level Agent thread can create direct child threads for separate tasks. The parent coordinates the request. 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 + +Agent setup offers three choices: + +| Setting | Behavior | +| --- | --- | +| Off | The Agent cannot manage other threads. | +| Explicit | The Agent creates a child only when you ask or its standing instructions require one. This is the default. | +| Proactive | The Agent may create direct children for distinct tasks that can progress independently. | + +Proactive mode does not mean every step becomes a child. Use child threads only for distinct tasks. Reuse a child that already owns the task, and keep related changes that must move together in the parent. + +## Give a child enough context + +A child sees the task message, not the parent conversation. A good task message includes: + +- The task and what the child owns. +- The source material to use. +- Any constraints and actions that need approval. +- What counts as done and what the child should return. + +The parent can request the child's final result and receive it automatically. It can also send more work to an existing child. Only the parent that created a child can cancel its delegated request or delete that child. + +## Safe parallel work + +Use separate children for read-only research or changes to different outputs. Keep changes to the same files or shared APIs in one thread, and combine the results there. + +## Next + +Read [Context isolation in threads](/developers/context-isolation-in-threads) before splitting work, then see [Threads and messages](/developers/api-ref/threads-and-messages) for the public thread API. diff --git a/content/docs/developers/project-context.mdx b/content/docs/developers/project-context.mdx new file mode 100644 index 0000000..073c77f --- /dev/null +++ b/content/docs/developers/project-context.mdx @@ -0,0 +1,32 @@ +--- +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 [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 3f236cb..24d02b2 100644 --- a/content/docs/developers/schedules.mdx +++ b/content/docs/developers/schedules.mdx @@ -2,138 +2,40 @@ title: Schedules sidebarTitle: Schedules icon: calendar-clock -description: Create, inspect, pause, and delete Agent schedules. +description: Wake an existing Agent thread with a saved message once or on a recurring schedule. --- -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/threads-and-messages) for the target thread and [Runs](/developers/runs) for execution state. - -## List 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 - - - -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 returns the existing schedule with `200`. Reusing the ID with different fields returns a conflict. - -## Pause or edit a schedule - - - -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 - - - -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 -``` +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. + +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. + +To create or manage schedules from an Agent chat, enable thread management for that Agent. + +## One-time and recurring schedules + +Ask the Agent in plain language: + +> *"Tomorrow at 9:00 AM Asia/Kolkata, check whether the release blockers are closed and prepare a status update."* + +> *"Every weekday at 9:30 AM Europe/London, review new P0 and P1 escalations and prepare the triage list."* + +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. + +## What to put in the saved message + +The message should still make sense when it runs later. Include: + +- The condition to check or work to perform. +- The source the Agent should read. +- The expected output. +- Any approval boundary before an external action. + +## Manage a schedule + +Ask the Agent to list, pause, resume, change, or delete schedules for the current thread. Deleting the target thread also removes its schedules. + +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. ## Next -Inspect each execution in [Runs](/developers/runs), or manage the target in [Threads and messages](/developers/threads-and-messages). +Use [Schedules](/developers/api-ref/schedules) for the REST endpoints and [Runs](/developers/api-ref/runs) to inspect each accepted turn. diff --git a/content/docs/developers/threads-and-contexts.mdx b/content/docs/developers/threads-and-contexts.mdx new file mode 100644 index 0000000..572960e --- /dev/null +++ b/content/docs/developers/threads-and-contexts.mdx @@ -0,0 +1,37 @@ +--- +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. + +## 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. + +## 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. + +## Next + +Read [Context isolation in threads](/developers/context-isolation-in-threads), [Project context](/developers/project-context), and [User preferences](/developers/user-preferences) for each boundary. diff --git a/content/docs/developers/user-preferences.mdx b/content/docs/developers/user-preferences.mdx new file mode 100644 index 0000000..106762f --- /dev/null +++ b/content/docs/developers/user-preferences.mdx @@ -0,0 +1,35 @@ +--- +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/features/approvals.mdx b/content/docs/features/approvals.mdx index 95fc6c6..ba9e562 100644 --- a/content/docs/features/approvals.mdx +++ b/content/docs/features/approvals.mdx @@ -1,6 +1,7 @@ --- 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. --- diff --git a/content/docs/features/chat.mdx b/content/docs/features/chat.mdx index 35a13c9..5c11f3e 100644 --- a/content/docs/features/chat.mdx +++ b/content/docs/features/chat.mdx @@ -1,6 +1,7 @@ --- title: Chat sidebarTitle: Chat +icon: message-square description: How conversation with Fluso works. What happens when you send a message, how to ask well, and what you can do inside the chat. --- diff --git a/content/docs/features/confidential.mdx b/content/docs/features/confidential.mdx index c380910..9f361c8 100644 --- a/content/docs/features/confidential.mdx +++ b/content/docs/features/confidential.mdx @@ -1,6 +1,7 @@ --- title: Confidential mode sidebarTitle: Confidential +icon: lock-keyhole description: Run your work through models hosted in a hardware-sealed enclave. --- diff --git a/content/docs/features/connectors.mdx b/content/docs/features/connectors.mdx index 7090a76..142d4fd 100644 --- a/content/docs/features/connectors.mdx +++ b/content/docs/features/connectors.mdx @@ -1,6 +1,7 @@ --- title: Connectors sidebarTitle: Connectors +icon: plug description: Connectors have been replaced by MCP connections. Everything now connects through the Plugins page. --- diff --git a/content/docs/features/imports.mdx b/content/docs/features/imports.mdx index 4982ed1..29d4400 100644 --- a/content/docs/features/imports.mdx +++ b/content/docs/features/imports.mdx @@ -1,6 +1,7 @@ --- title: Imports sidebarTitle: Imports +icon: import description: Bring useful context from ChatGPT, Claude, or another agent into Fluso as projects, files, and context. --- diff --git a/content/docs/features/mcp.mdx b/content/docs/features/mcp.mdx index 1da0fb2..16cd1a0 100644 --- a/content/docs/features/mcp.mdx +++ b/content/docs/features/mcp.mdx @@ -1,6 +1,7 @@ --- title: Apps and MCP servers sidebarTitle: Apps & MCP +icon: plug-zap description: Every connection in Fluso is an MCP connection. One-click managed apps, custom servers by URL, and per-tool permissions. --- diff --git a/content/docs/features/memory.mdx b/content/docs/features/memory.mdx index a3d5c20..78a37a8 100644 --- a/content/docs/features/memory.mdx +++ b/content/docs/features/memory.mdx @@ -1,6 +1,7 @@ --- title: Memory sidebarTitle: Memory +icon: brain description: How Fluso remembers what's worth remembering across sessions, without turning every chat into part of a permanent transcript. --- @@ -30,6 +31,13 @@ With every message, Fluso pulls in three things as background context: Memory is context for the conversation, not a script. Your current message still drives the response. + + 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). + + ## How it updates Two paths. Both are conservative on purpose. diff --git a/content/docs/features/meta.json b/content/docs/features/meta.json index 9c69ea4..470bd71 100644 --- a/content/docs/features/meta.json +++ b/content/docs/features/meta.json @@ -1,13 +1,13 @@ { "pages": [ - "chat", "approvals", "mcp", + "chat", + "confidential", "imports", + "memory", "skills", "tasks", - "memory", - "confidential", "!connectors" ] } diff --git a/content/docs/features/skills.mdx b/content/docs/features/skills.mdx index c891e79..13a0bf7 100644 --- a/content/docs/features/skills.mdx +++ b/content/docs/features/skills.mdx @@ -1,6 +1,7 @@ --- title: Skills sidebarTitle: Skills +icon: wand-sparkles description: Capabilities Fluso reaches for when a request matches one. Some come built in, some you add from the marketplace, some you make by asking Fluso to build them. --- diff --git a/content/docs/features/tasks.mdx b/content/docs/features/tasks.mdx index 2bfcf8b..3d44b79 100644 --- a/content/docs/features/tasks.mdx +++ b/content/docs/features/tasks.mdx @@ -1,6 +1,7 @@ --- title: Tasks sidebarTitle: Tasks +icon: list-checks description: Fluso's task list, mostly populated automatically from email, meetings, and Slack. Where tasks come from, how to open one, and how to keep the list tidy. --- diff --git a/content/docs/going-deeper.mdx b/content/docs/going-deeper.mdx index c127e99..562bfaa 100644 --- a/content/docs/going-deeper.mdx +++ b/content/docs/going-deeper.mdx @@ -1,6 +1,7 @@ --- title: Going deeper sidebarTitle: Going deeper +icon: layers description: Patterns, projects, custom skills, and the prompt habits that separate daily users from pros. --- diff --git a/content/docs/index.mdx b/content/docs/index.mdx index d109b17..18dbf85 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -1,6 +1,7 @@ --- title: Fluso docs sidebarTitle: Home +icon: house description: Get set up, see Fluso work on a real task, and build the habits that turn it into your daily assistant. --- @@ -53,8 +54,8 @@ Pick a workflow that matches a problem you have right now. Each one is a story, The connection model and the full catalog of supported apps. - - Authenticate a client and use the versioned REST API. + + Build a saved Agent, split work across threads, and schedule follow-ups. Request flow, durable data boundaries, and replaceable components. diff --git a/content/docs/integrations/github.mdx b/content/docs/integrations/github.mdx index d1981a8..c58d66b 100644 --- a/content/docs/integrations/github.mdx +++ b/content/docs/integrations/github.mdx @@ -1,6 +1,7 @@ --- title: GitHub sidebarTitle: GitHub +icon: git-branch description: Connect GitHub. Setup, repository scope, common prompts, and the project-context pattern that makes generated code fit your codebase. --- diff --git a/content/docs/integrations/gmail.mdx b/content/docs/integrations/gmail.mdx index 74a7ea2..359df7b 100644 --- a/content/docs/integrations/gmail.mdx +++ b/content/docs/integrations/gmail.mdx @@ -1,6 +1,7 @@ --- title: Gmail sidebarTitle: Gmail +icon: mail description: Connect Gmail. Permissions, prompts that work well, and troubleshooting when something goes sideways. --- diff --git a/content/docs/integrations/google-calendar.mdx b/content/docs/integrations/google-calendar.mdx index 5e1d5fd..4594794 100644 --- a/content/docs/integrations/google-calendar.mdx +++ b/content/docs/integrations/google-calendar.mdx @@ -1,6 +1,7 @@ --- title: Google Calendar sidebarTitle: Google Calendar +icon: calendar-days description: Connect Google Calendar. Setup, permissions, prompts, and troubleshooting. --- diff --git a/content/docs/integrations/meta.json b/content/docs/integrations/meta.json index 6f3dead..2008d59 100644 --- a/content/docs/integrations/meta.json +++ b/content/docs/integrations/meta.json @@ -1,3 +1,3 @@ { - "pages": ["gmail", "google-calendar", "slack", "github"] + "pages": ["github", "gmail", "google-calendar", "slack"] } diff --git a/content/docs/integrations/slack.mdx b/content/docs/integrations/slack.mdx index f292664..e13ed94 100644 --- a/content/docs/integrations/slack.mdx +++ b/content/docs/integrations/slack.mdx @@ -1,6 +1,7 @@ --- title: Slack sidebarTitle: Slack +icon: messages-square description: Connect Slack. Setup, channel scope, common prompts, and the cross-app workflows that get sharper with Slack in the mix. --- diff --git a/content/docs/introduction.mdx b/content/docs/introduction.mdx index 2980355..9e62b5b 100644 --- a/content/docs/introduction.mdx +++ b/content/docs/introduction.mdx @@ -1,6 +1,7 @@ --- title: Introduction sidebarTitle: Introduction +icon: book-open description: Fluso is a private AI workspace that turns scattered work into finished documents, tasks, and drafts. --- diff --git a/content/docs/meta.json b/content/docs/meta.json index 501694f..4954c05 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -3,21 +3,21 @@ "index", "---Agents (Beta)---", "...developers", + "---App setup---", + "...integrations", + "---Features---", + "...features", "---Get started---", + "going-deeper", "introduction", "quickstart", - "going-deeper", - "---Features---", - "...features", - "---Remote access---", - "...remote", - "---Workflows---", - "...workflows", - "---App setup---", - "...integrations", "---Reference---", "...resources", "---Release notes---", - "release-notes" + "release-notes", + "---Remote access---", + "...remote", + "---Workflows---", + "...workflows" ] } diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx index 2cf8e31..1693b97 100644 --- a/content/docs/quickstart.mdx +++ b/content/docs/quickstart.mdx @@ -1,6 +1,7 @@ --- title: Quickstart sidebarTitle: Quickstart +icon: rocket description: Set up your first Fluso project, add useful context, connect your first tools, and run practical prompts. --- diff --git a/content/docs/remote/telegram.mdx b/content/docs/remote/telegram.mdx index 5ad3117..c3f1d85 100644 --- a/content/docs/remote/telegram.mdx +++ b/content/docs/remote/telegram.mdx @@ -1,6 +1,7 @@ --- title: Telegram sidebarTitle: Telegram +icon: send description: Fluso's Telegram bot. Sign in once, then chat with Fluso from a private Telegram conversation. --- diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx index e415571..88f9c4b 100644 --- a/content/docs/resources/faq.mdx +++ b/content/docs/resources/faq.mdx @@ -1,6 +1,7 @@ --- title: FAQ sidebarTitle: FAQ +icon: circle-help description: The questions that come up most often. What Fluso is, how it works, security, pricing, getting started, and the occasional troubleshooting nudge. --- diff --git a/content/docs/resources/meta.json b/content/docs/resources/meta.json index ed29c48..2aa753b 100644 --- a/content/docs/resources/meta.json +++ b/content/docs/resources/meta.json @@ -1,3 +1,3 @@ { - "pages": ["pricing", "security", "privacy", "faq"] + "pages": ["faq", "pricing", "privacy", "security"] } diff --git a/content/docs/resources/pricing.mdx b/content/docs/resources/pricing.mdx index 7dc3864..76cf70c 100644 --- a/content/docs/resources/pricing.mdx +++ b/content/docs/resources/pricing.mdx @@ -1,6 +1,7 @@ --- title: Pricing sidebarTitle: Pricing +icon: credit-card description: Compare plan limits, storage, automation, and workspace controls. --- diff --git a/content/docs/resources/privacy.mdx b/content/docs/resources/privacy.mdx index b5a62ad..84fe617 100644 --- a/content/docs/resources/privacy.mdx +++ b/content/docs/resources/privacy.mdx @@ -1,6 +1,7 @@ --- title: Privacy sidebarTitle: Privacy +icon: eye-off description: What Fluso collects, what it stores, what it doesn't, and your rights to access, delete, and export. The full picture, plainly. --- diff --git a/content/docs/resources/security.mdx b/content/docs/resources/security.mdx index d21942e..963477f 100644 --- a/content/docs/resources/security.mdx +++ b/content/docs/resources/security.mdx @@ -1,6 +1,7 @@ --- title: Security sidebarTitle: Security +icon: shield description: How Fluso is built to protect your data. Encryption, authentication, infrastructure isolation, and how to report a vulnerability. --- diff --git a/content/docs/workflows/content-launch.mdx b/content/docs/workflows/content-launch.mdx index a6dd311..8b6d377 100644 --- a/content/docs/workflows/content-launch.mdx +++ b/content/docs/workflows/content-launch.mdx @@ -1,6 +1,7 @@ --- title: A launch in an afternoon sidebarTitle: Content launch +icon: megaphone description: Landing page, blog post, social graphics for a product launch. Forty-five minutes instead of two or three days. --- diff --git a/content/docs/workflows/dev-bug-fix.mdx b/content/docs/workflows/dev-bug-fix.mdx index 7db3e6d..6d0f566 100644 --- a/content/docs/workflows/dev-bug-fix.mdx +++ b/content/docs/workflows/dev-bug-fix.mdx @@ -1,6 +1,7 @@ --- title: A bug to a PR sidebarTitle: Bug → PR +icon: bug description: Bug report to merged PR in fifteen minutes. Fluso traces the code, finds the cause, writes the fix, opens the pull request for your review. --- diff --git a/content/docs/workflows/knowledge-recall.mdx b/content/docs/workflows/knowledge-recall.mdx index 2bebb57..cdae38e 100644 --- a/content/docs/workflows/knowledge-recall.mdx +++ b/content/docs/workflows/knowledge-recall.mdx @@ -1,6 +1,7 @@ --- title: Recall, mid-meeting sidebarTitle: Knowledge recall +icon: search description: That company you researched in January, the decision from the April planning meeting, the Slack thread from last summer. Retrieved in time to sound informed. --- diff --git a/content/docs/workflows/meetings.mdx b/content/docs/workflows/meetings.mdx index 1a10420..6fca7bf 100644 --- a/content/docs/workflows/meetings.mdx +++ b/content/docs/workflows/meetings.mdx @@ -1,6 +1,7 @@ --- title: A meeting, end to end sidebarTitle: Meetings +icon: calendar-clock description: The full lifecycle on a real Tuesday. Prep at 9:55, meeting at 10, processed and follow-ups drafted by 10:47. --- diff --git a/content/docs/workflows/meta.json b/content/docs/workflows/meta.json index 2952867..43471d9 100644 --- a/content/docs/workflows/meta.json +++ b/content/docs/workflows/meta.json @@ -1,10 +1,10 @@ { "pages": [ - "morning-brief", + "dev-bug-fix", + "content-launch", "meetings", "research-to-deck", - "content-launch", - "dev-bug-fix", + "morning-brief", "knowledge-recall" ] } diff --git a/content/docs/workflows/morning-brief.mdx b/content/docs/workflows/morning-brief.mdx index f14e709..da51d2e 100644 --- a/content/docs/workflows/morning-brief.mdx +++ b/content/docs/workflows/morning-brief.mdx @@ -1,6 +1,7 @@ --- title: Morning brief sidebarTitle: Morning brief +icon: sunrise description: The two-minute version of the morning routine. Inbox triage, schedule, tasks, follow-ups, all in one prompt. --- diff --git a/content/docs/workflows/research-to-deck.mdx b/content/docs/workflows/research-to-deck.mdx index 602adc9..7f4fe94 100644 --- a/content/docs/workflows/research-to-deck.mdx +++ b/content/docs/workflows/research-to-deck.mdx @@ -1,6 +1,7 @@ --- title: From a CEO request to a board deck sidebarTitle: Research to deck +icon: presentation description: "The classic Monday-morning ask. Old version: twelve hours over three days. New version: an hour total, deck ready three days early." ---