docs: refresh Agents, Fluso Local, and API guides

.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"
   ]
 }

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

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.

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({

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;