docs: add Workspaces and Tool Optimization guides (#164)

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

docs/guide/meta.json

@@ -6,10 +6,12 @@
     "getting-started",
     "---Core Concepts---",
     "spaces",
+    "workspaces",
     "feature-sets",
     "clients",
     "servers",
     "---Advanced---",
+    "tool-optimization",
     "gateway",
     "server-definitions",
     "security"

docs/guide/tool-optimization.mdx

@@ -0,0 +1,43 @@
+---
+title: Tool Optimization — Let the AI Curate Its Toolset
+description: McpMux ships built-in meta-tools so an AI assistant can keep its own toolset lean — discover what's available, compose a focused FeatureSet, and pin it to the current folder, all from chat. Reads are silent; writes are gated by a one-click approval.
+---
+
+Hand an assistant a hundred tools and it burns tokens and reaches for the wrong one. **Tool Optimization** is a built-in capability that lets the AI keep *itself* lean — straight from chat, no config files.
+
+It's a per-Space, built-in server McpMux exposes alongside your real MCP servers. Toggle it from the **Built-in** page.
+
+![Tool Optimization — the built-in self-management tools the AI drives, reads silent and writes gated](https://mcpmux.com/screenshots/tool-optimization.png)
+
+## The `@mux` trigger
+
+Start a request with **`@mux`** and the assistant knows to drive these tools instead of your real ones. The trigger keeps self-management cleanly separated from your actual work:
+
+> *"@mux build a minimal toolset for this Next.js repo and pin it to this folder."*
+
+## The meta-tools
+
+| Tool | Access | What it does |
+|---|---|---|
+| `mcpmux_list_spaces` | read | List all Spaces so the AI can target one by id |
+| `mcpmux_list_all_tools` | read | Browse every tool available in a Space, unfiltered |
+| `mcpmux_search_tools` | read | Find tools by keyword without pulling the whole catalog |
+| `mcpmux_list_feature_sets` | read | See the FeatureSets defined in the Space |
+| `mcpmux_manage_feature_set` | write · approval | Create, update, or delete a custom FeatureSet of chosen tools |
+| `mcpmux_bind_current_workspace` | write · approval | Map the current folder to a FeatureSet so it persists |
+
+A typical flow: **discover** what's available (`list`/`search`), **compose** a focused FeatureSet of just the tools needed (`manage_feature_set`), then **pin** the current folder to it (`bind_current_workspace`) so it sticks for every future session.
+
+## Reads are silent, writes are gated
+
+Read tools run silently — the AI explores freely. Anything that changes your setup pops a **one-click approval dialog** that names the **exact Space** it will affect and shows the precise tool diff. The AI proposes; you decide.
+
+![Approval — every self-management write asks first, showing the target Space and the exact tool diff](https://mcpmux.com/screenshots/meta-tool-approval.png)
+
+Every operation can target a specific Space by id, so the AI can curate one context without touching another. An audit log records each approved change.
+
+## Next steps
+
+- [FeatureSets](/docs/feature-sets/) — the curated toolsets the AI composes
+- [Workspaces](/docs/workspaces/) — what `bind_current_workspace` pins a folder to
+- [Spaces](/docs/spaces/) — the contexts every meta-tool operation targets by id

docs/guide/workspaces.mdx

@@ -0,0 +1,56 @@
+---
+title: Workspaces — Folder-Based Routing
+description: Map a project folder to the exact toolset it should get. McpMux routes each workspace to its own Space and FeatureSet automatically, so every AI app sees the right tools for the folder it has open.
+---
+
+Workspaces map a **project folder** to the exact toolset it should get. When an AI app opens that folder, McpMux hands it the Space and FeatureSet you mapped — and nothing else.
+
+## Why Workspaces
+
+[Spaces](/docs/spaces/) isolate *contexts*; Workspaces decide which context a session actually gets — automatically, per folder.
+
+Your AI app (Cursor, VS Code, Windsurf, Claude Code) tells McpMux which folder it's working in — its MCP **root**. McpMux uses that to route each folder to its own toolset:
+
+- Open your **backend repo** and the AI sees your database, cloud, and deploy tools.
+- Open a **docs folder** and it sees only search and filesystem.
+- Open an **untrusted project** and it gets a read-only set — or nothing.
+
+Map a folder once and every future session from that exact path resolves automatically. Matching is **per-folder and exact**, so nothing leaks across projects.
+
+![Workspaces — map a project folder to the Space and FeatureSet it should get](https://mcpmux.com/screenshots/workspaces.png)
+
+## How a request resolves
+
+When an AI app makes a request, McpMux resolves the toolset in order:
+
+1. The app reports its **workspace root** (the folder it has open).
+2. McpMux looks for a **Workspace mapping** for that exact path.
+3. The mapping points at a **Space** (which servers + credentials) and a **FeatureSet** (which tools, prompts, and resources from those servers).
+4. The FeatureSet's included features **are** the effective toolset the session resolves to.
+
+Because routing is driven by the reported folder, it is decided **per session, not per app** — the same app gets different tools depending on which project it has open.
+
+## Creating a mapping
+
+Open the **Workspaces** tab and click **Add mapping**:
+
+- **Workspace folder** — browse for a folder or paste an absolute path. Accepts `/unix`, `C:\windows`, and `file://` forms.
+- **Space** — the profile whose servers and credentials this folder draws from.
+- **FeatureSet** — the curated bundle of tools this folder is allowed to use. Pick one, or combine several into a single effective set.
+
+Unmapped folders receive no tools until you map them — an explicit, fail-closed default so a new project never silently inherits another's access.
+
+## Let the AI map it for you
+
+You don't have to open the Workspaces tab at all. With [Tool Optimization](/docs/tool-optimization/), an assistant can compose a FeatureSet and pin the current folder to it from chat:
+
+> *"@mux build a minimal toolset for this Next.js repo and pin it to this folder."*
+
+The pin is a Workspace mapping — it sticks for every future session from that path. Changes are gated behind a one-click approval that names the exact Space.
+
+## Next steps
+
+- [Spaces](/docs/spaces/) — the isolated contexts a Workspace routes to
+- [FeatureSets](/docs/feature-sets/) — the curated toolsets a Workspace grants
+- [Tool Optimization](/docs/tool-optimization/) — let the AI map folders for itself
+- [Clients](/docs/clients/) — how connected apps report the folder that drives routing