docs: add Admin, webhook, and Projects guides

AGENTS.md

@@ -12,9 +12,10 @@
 
 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/*`.
+- **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/*`.
 - **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.
+- **Features** - `/features/*`. Approvals and permissions, Apps and MCP servers, Chat, Confidential mode, Imports, Memory, Projects, 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.

content/docs/admin-panel.mdx

@@ -0,0 +1,92 @@
+---
+title: Admin panel
+sidebarTitle: Admin panel
+icon: shield-user
+description: Review users, runtimes, recorded model usage, identity and access changes, and network policy from Fluso Admin.
+---
+
+Fluso Admin is a separate browser interface for authorized operators. It shows account, runtime, usage, and governance records without exposing the content of members' work.
+
+<Note>
+  Your organization provides its Fluso Admin address and assigns the panel
+  role. This is separate from the organization role recorded under **Teams &
+  access**.
+</Note>
+
+## Access roles
+
+The backend checks the administrator role on every request.
+
+| Role | Access |
+| --- | --- |
+| Read-only | View dashboards, users, runtimes, usage, access records, and network policy. Export available reports. |
+| Read and write | All read-only access, plus runtime controls, plan sponsorship, team and Agent access changes, and network policy changes. |
+
+The **Admin** organization role does not grant access to Fluso Admin. Panel access uses the separate read-only or read-and-write role assigned by the operator of your deployment.
+
+## View scope
+
+**Overview** and **Users** cover the configured sign-in instance. **Teams & access** and **Audit log** show one target account and default to the signed-in administrator. To inspect another account, open it from **Users**, then choose **Manage access** or **Audit trail**.
+
+## Admin views
+
+| View | What it shows or controls |
+| --- | --- |
+| **Overview** | Instance-wide identity activity, runtime health, recorded model usage, plan distribution, and users with the highest recorded cost. |
+| **Users** | An instance-wide, searchable user list. Open a user to review their plan, runtime state, usage, and aggregate storage. Read-and-write administrators can control the runtime and grant or extend Sponsored Confidential. |
+| **Runtime fleet** | A cached or refreshed snapshot of running, starting, stopped, failed, unknown, mapped, and unmapped runtimes. Click **Refresh fleet** to reconcile the snapshot before investigating availability. |
+| **LLM costs** | Global cost and token totals from the gateway usage ledger for 30, 90, 180, or 365 days. It does not show prompts, sessions, or model-level detail. |
+| **Observability** | Recorded cost and token usage for the last 14 days, with a CSV export. The current view does not record evaluation, policy, completion, or response-latency metrics. |
+| **Audit log** | The latest 100 identity and access events for the target account. Filter by user, action type, or date, then export the current rows as CSV. |
+| **Teams & access** | Microsoft Entra tenant metadata, members, organization roles, teams, access requests, and Agent access records for the target account. The metadata record does not verify or import a directory by itself. |
+| **Network egress** | Platform-wide origin and provider bundles for egress-governed sandboxes. These controls do not currently have a per-organization boundary. |
+
+## Audit log
+
+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.
+
+## Runtime and user controls
+
+Open **Users**, select a person, then review the runtime card. A read-and-write administrator can start, stop, or restart the runtime. Stop and restart are blocked during active work, warm-up, active schedules, or an unhealthy state; there is no force-stop control.
+
+The same user page shows aggregate storage. It does not open or delete the user's stored content.
+
+Sponsored Confidential changes entitlement for up to 24 months. They do not change the person's Clerk billing subscription.
+
+## Network egress
+
+Use **Network egress** to review the origins available to egress-governed sandboxes. A read-and-write administrator can create, edit, or delete provider bundles and delete existing Shared rules. The current panel does not add or edit a standalone Shared rule.
+
+<Warning>
+  A change here applies to every egress-governed user. **Ask** requests user
+  approval and saves the user's Allow or Deny choice. A global **Deny** gives no
+  prompt and cannot be overridden. Disabling or deleting a bundle removes only
+  rules created by that bundle; other global rules and user grants remain.
+</Warning>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="The Admin panel role is missing">
+    Sign in with the account your deployment operator authorized. An
+    organization role does not grant panel access. Ask the deployment operator
+    or [contact Fluso support](mailto:support@premai.io) if the panel role is
+    missing.
+  </Accordion>
+  <Accordion title="A dashboard says data is unavailable">
+    The panel distinguishes recorded data from missing telemetry. Retry the
+    view. If it remains unavailable, check the source service rather than
+    treating the empty value as zero.
+  </Accordion>
+  <Accordion title="A runtime control is unavailable">
+    Check whether the runtime is busy, warming, unhealthy, already stopped, or
+    has active schedules or other durable work. Retry after the blocking state
+    clears. Fluso does not force-stop a runtime from this panel.
+  </Accordion>
+</AccordionGroup>
+
+## Next
+
+Read [Privacy](/resources/privacy) for the admin content boundary and [Security](/resources/security) for authentication, isolation, and governance logging.

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/api-ref/threads-and-messages) and can start from [schedules](/developers/api-ref/schedules).
+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
 
@@ -192,7 +192,7 @@ chats keep the configuration they started with.
 
 <Endpoint method="DELETE" path="/v1/agents/{agentId}" />
 
-Deletes the Agent and removes its owned chats, configurations, knowledge, and schedules.
+Deletes the Agent and removes its owned chats, configurations, knowledge, schedules, and webhook triggers.
 
 ```bash title="Request"
 curl "$FLUSO_API/v1/agents/agt_0123456789ab4def8123456789abcdef" \
@@ -206,4 +206,4 @@ 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).
+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).

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

@@ -228,4 +228,4 @@ curl -G "$FLUSO_API/v1/agent/files" \
 
 ## Next
 
-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).
+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).

content/docs/developers/meta.json

@@ -9,6 +9,7 @@
     "project-context",
     "schedules",
     "threads-and-contexts",
-    "user-preferences"
+    "user-preferences",
+    "webhooks"
   ]
 }

content/docs/developers/project-context.mdx

@@ -29,4 +29,4 @@ Use a dedicated project when the Agent should work with one customer's files, on
 
 ## 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.
+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.

content/docs/developers/schedules.mdx

@@ -38,4 +38,4 @@ If a recurring turn is still queued, running, or waiting for approval, Fluso doe
 
 ## Next
 
-Use [Schedules](/developers/api-ref/schedules) for the REST endpoints and [Runs](/developers/api-ref/runs) to inspect each accepted turn.
+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.

content/docs/developers/webhooks.mdx

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

content/docs/features/imports.mdx

@@ -142,4 +142,4 @@ After importing, open one of the new projects and ask:
 
 > *"Summarise this project. What is decided, what is still unclear, and what should I do next?"*
 
-For project habits after import, see [Going deeper](/going-deeper#use-projects-properly).
+For project habits after import, see [Projects](/features/projects) and [Going deeper](/going-deeper#use-projects-properly).

content/docs/features/mcp.mdx

@@ -45,8 +45,9 @@ Switch to the **Custom server** tab and paste the endpoint URL.
 <Note>
   Use the exact Streamable HTTP endpoint. It must be reachable from Fluso over
   public HTTPS; `localhost`, private network addresses, and `stdio` commands
-  are not connection URLs. The workspace or organization network-egress
-  policy, plus any provider policy applied to that origin, must allow it.
+  are not connection URLs. The workspace or organization
+  [network-egress policy](/admin-panel#network-egress), plus any provider
+  policy applied to that origin, must allow it.
 </Note>
 
 <Frame>

content/docs/features/memory.mdx

@@ -66,7 +66,7 @@ One-off task details stay out of the durable files too. They live in working mem
 
 ## Reading and correcting it
 
-Memory is yours to read. Ask *"what do you remember about me?"* or *"what's in this project's context?"* and Fluso reads the files back to you. `preferences.md` and each project's `context.md` sit in your workspace as plain markdown you can open yourself.
+Memory is yours to read. Ask *"what do you remember about me?"* or *"what's in this project's context?"* and Fluso reads it back to you. Project context is stored in `context.md`, which is hidden from the project file explorer.
 
 Corrections work the same way: *"forget my old timezone"*, *"that decision was reversed, update the context"*. If you want a clean slate for a project's working memory, ask Fluso to reset it.
 

content/docs/features/meta.json

@@ -6,6 +6,7 @@
     "confidential",
     "imports",
     "memory",
+    "projects",
     "skills",
     "tasks",
     "!connectors"