docs: add tool reference pages

docs/.vitepress/config.ts

@@ -63,12 +63,40 @@ export default defineConfig({
           { text: "Orchestration", link: "/concepts/orchestration" },
         ],
       },
+      {
+        text: "Tools",
+        collapsed: false,
+        items: [
+          { text: "Overview", link: "/tools/index" },
+          { text: "Bash", link: "/tools/bash" },
+          { text: "Read", link: "/tools/read" },
+          { text: "Write", link: "/tools/write" },
+          { text: "Edit", link: "/tools/edit" },
+          { text: "Grep", link: "/tools/grep" },
+          { text: "Glob", link: "/tools/glob" },
+          { text: "WebFetch", link: "/tools/web-fetch" },
+          { text: "WebSearch", link: "/tools/web-search" },
+          { text: "AskUserQuestion", link: "/tools/ask-user-question" },
+          { text: "TodoWrite", link: "/tools/todo-write" },
+          { text: "Sleep", link: "/tools/sleep" },
+          { text: "Python", link: "/tools/python" },
+          { text: "BrowserNavigate", link: "/tools/browser-navigate" },
+          { text: "BrowserContent", link: "/tools/browser-content" },
+          { text: "BrowserScroll", link: "/tools/browser-scroll" },
+          { text: "BrowserAction", link: "/tools/browser-action" },
+          { text: "spawn_agent", link: "/tools/spawn-agent" },
+          { text: "close_agent", link: "/tools/close-agent" },
+          { text: "send_input", link: "/tools/send-input" },
+          { text: "wait_agent", link: "/tools/wait-agent" },
+        ],
+      },
       {
         text: "Guides",
         items: [
           { text: "Build a Profile", link: "/guides/build-a-profile" },
           { text: "Manage Prompts", link: "/guides/manage-prompts" },
           { text: "Add Tools", link: "/guides/add-tools" },
+          { text: "Tool Permissions", link: "/guides/tool-permissions" },
           { text: "Add Context", link: "/guides/add-context" },
           { text: "Configure Sessions", link: "/guides/configure-sessions" },
           { text: "Consume Stream (SSE)", link: "/guides/consume-stream" },

docs/examples/deep-research.md

@@ -32,16 +32,16 @@ That separation is one of the main design goals of Agentrail.
 Start with these files:
 
 - example route wiring:
-  - [examples/deep-research/src/routes/run.ts](../../examples/deep-research/src/routes/run.ts)
-  - [examples/deep-research/src/routes/deep-research.ts](../../examples/deep-research/src/routes/deep-research.ts)
+  - [examples/deep-research/src/routes/run.ts](https://github.com/yai-dev/agentrail/blob/main/examples/deep-research/src/routes/run.ts)
+  - [examples/deep-research/src/routes/deep-research.ts](https://github.com/yai-dev/agentrail/blob/main/examples/deep-research/src/routes/deep-research.ts)
 - example runtime config:
-  - [examples/deep-research/src/config.ts](../../examples/deep-research/src/config.ts)
+  - [examples/deep-research/src/config.ts](https://github.com/yai-dev/agentrail/blob/main/examples/deep-research/src/config.ts)
 - workflow package entrypoint:
-  - [packages/deep-research/src/index.ts](../../packages/deep-research/src/index.ts)
+  - [packages/deep-research/src/index.ts](https://github.com/yai-dev/agentrail/blob/main/packages/deep-research/src/index.ts)
 - workflow coordinator:
-  - [packages/deep-research/src/coordinator.ts](../../packages/deep-research/src/coordinator.ts)
+  - [packages/deep-research/src/coordinator.ts](https://github.com/yai-dev/agentrail/blob/main/packages/deep-research/src/coordinator.ts)
 - workflow prompt assembly:
-  - [packages/deep-research/src/prompts.ts](../../packages/deep-research/src/prompts.ts)
+  - [packages/deep-research/src/prompts.ts](https://github.com/yai-dev/agentrail/blob/main/packages/deep-research/src/prompts.ts)
 
 ## Execution Shape
 

docs/examples/playground-server.md

@@ -191,13 +191,13 @@ Both routes share the same surrounding infrastructure. The stream route adds:
 
 ## Source Files To Read
 
-| File                                                                                            | What it shows                            |
-| ----------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| [routes/stream.ts](../../examples/playground-server/src/routes/stream.ts)                       | Full `createStreamRoute` options         |
-| [profiles/default-profile.ts](../../examples/playground-server/src/profiles/default-profile.ts) | `defineProfile` + capability descriptors |
-| [prompts/index.ts](../../examples/playground-server/src/prompts/index.ts)                       | Fragment + bundle composition            |
-| [plugins/index.ts](../../examples/playground-server/src/plugins/index.ts)                       | Plugin registration                      |
-| [context/index.ts](../../examples/playground-server/src/context/index.ts)                       | Singleton managers                       |
+| File                                                                                                                                     | What it shows                            |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| [routes/stream.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/routes/stream.ts)                       | Full `createStreamRoute` options         |
+| [profiles/default-profile.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/profiles/default-profile.ts) | `defineProfile` + capability descriptors |
+| [prompts/index.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/prompts/index.ts)                       | Fragment + bundle composition            |
+| [plugins/index.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/plugins/index.ts)                       | Plugin registration                      |
+| [context/index.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/context/index.ts)                       | Singleton managers                       |
 
 ## What Is Framework-Level vs Example-Level
 

docs/examples/playground-ui.md

@@ -254,8 +254,8 @@ async function chatNonStream(message: string): Promise<string> {
 Read in this order to understand the full client-server loop:
 
 1. [Examples: Playground Server](playground-server.md) — how the server produces events
-2. [examples/playground-ui/src/api.ts](../../examples/playground-ui/src/api.ts) — how the UI calls the API
-3. [examples/playground-ui/src/App.tsx](../../examples/playground-ui/src/App.tsx) — top-level state and routing
+2. [examples/playground-ui/src/api.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-ui/src/api.ts) — how the UI calls the API
+3. [examples/playground-ui/src/App.tsx](https://github.com/yai-dev/agentrail/blob/main/examples/playground-ui/src/App.tsx) — top-level state and routing
 4. [Reference: Events](../reference/events.md) — full event type reference
 
 ## Related Docs

docs/guides/add-context.md

@@ -76,13 +76,13 @@ That path is especially useful when you want to compose:
 
 The current implementation lives in:
 
-- [packages/capabilities/src/memory/context.ts](../../packages/capabilities/src/memory/context.ts)
+- [packages/capabilities/src/memory/context.ts](https://github.com/yai-dev/agentrail/blob/main/packages/capabilities/src/memory/context.ts)
 
 ## Repository Example
 
 The playground example builds request context here:
 
-- [examples/playground-server/src/context/index.ts](../../examples/playground-server/src/context/index.ts)
+- [examples/playground-server/src/context/index.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/context/index.ts)
 
 That file is a good example of how to:
 

docs/guides/build-a-profile.md

@@ -77,7 +77,7 @@ const app = createAgentApp({
 
 The playground example follows this pattern in:
 
-- [examples/playground-server/src/profiles/default-profile.ts](../../examples/playground-server/src/profiles/default-profile.ts)
+- [examples/playground-server/src/profiles/default-profile.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/profiles/default-profile.ts)
 
 That profile:
 

docs/guides/manage-prompts.md

@@ -93,7 +93,7 @@ const systemPromptBuilder = createPromptBuilder(
 
 This is the same style used by the playground example in:
 
-- [examples/playground-server/src/prompts/index.ts](../../examples/playground-server/src/prompts/index.ts)
+- [examples/playground-server/src/prompts/index.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/prompts/index.ts)
 
 ## Layering Strategy
 
@@ -148,9 +148,9 @@ For example:
 Current examples in this repository:
 
 - playground hosted system prompt:
-  - [examples/playground-server/src/prompts/index.ts](../../examples/playground-server/src/prompts/index.ts)
+  - [examples/playground-server/src/prompts/index.ts](https://github.com/yai-dev/agentrail/blob/main/examples/playground-server/src/prompts/index.ts)
 - deep-research workflow prompts:
-  - [packages/deep-research/src/prompts.ts](../../packages/deep-research/src/prompts.ts)
+  - [packages/deep-research/src/prompts.ts](https://github.com/yai-dev/agentrail/blob/main/packages/deep-research/src/prompts.ts)
 
 These show two useful patterns: