diff --git a/agents.mdx b/agents.mdx
deleted file mode 100644
index fe6194e..0000000
--- a/agents.mdx
+++ /dev/null
@@ -1,152 +0,0 @@
----
-title: "Agents"
-description: "Deploy hosted OpenClaw agents through Pinata"
-icon: "lobster"
----
-
-Pinata Agents are hosted [OpenClaw](https://openclaw.org) instances. Each agent runs in an isolated container with its own environment, skills, and secrets. Pick a personality, connect an LLM provider, deploy — your agent is live.
-
-
- Agents require a paid Pinata plan. [Upgrade here](https://app.pinata.cloud/billing).
-
-
-## Agents Workspace
-
-Open **Agents** in the [Pinata App](https://app.pinata.cloud) sidebar to access the Agents workspace.
-
-{/* screenshot: agents landing page with "Go to Agents Portal" button */}
-
-The workspace has three tabs: **My Agents**, **Skills**, and **Secrets**.
-
-
- 
-
-
-## Before You Start
-
-Your agent needs an LLM provider API key to run. Add it as a [secret](#secrets) before creating an agent — the setup wizard looks for it during the Connect step.
-
-Pinata supports three providers:
-
-| Provider | Models |
-| ---------- | ------------------- |
-| Anthropic | Claude |
-| OpenAI | GPT |
-| OpenRouter | Multi-model routing |
-
-## Creating an Agent
-
-Click **Create Agent** to start the setup wizard. There are four steps.
-
-### 1. Identity
-
-Choose a personality template or create a custom one:
-
-- **Atlas** — analytical, methodical
-- **Nova** — creative, exploratory
-- **Sage** — patient, accuracy-focused
-- **Custom** — define your own personality and purpose
-
-Give the agent a name and an optional personality description.
-
-
- 
-
-
-### 2. Agent Workspace
-
-Select a workspace template. The **Pinata Optimized Agent** environment includes Node.js, Python, and common CLI tools. State persists and syncs automatically.
-
-
- 
-
-
-### 3. Connect
-
-Choose your AI provider. If the API key is already in the Secrets vault, the provider shows "Key available."
-
-
- 
-
-
-You can also configure messaging channels on this step.
-
-**Telegram**
-
-Create a bot through [@BotFather](https://t.me/botfather), copy the bot token, set a DM policy, and optionally restrict access to specific user IDs.
-
-**Slack**
-
-Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps), enable Socket Mode, and generate an App-Level Token with the `connections:write` scope. Under **OAuth & Permissions**, add these Bot Token Scopes:
-
-| Scope | Description |
-| ------------------- | --------------- |
-| `chat:write` | Send messages |
-| `im:write` | Open DMs |
-| `im:history` | Read DM history |
-| `im:read` | DM info |
-| `users:read` | User lookup |
-| `app_mentions:read` | Hear @mentions |
-
-For public channel support, also add `channels:history` and `channels:read`. Install the app to your workspace, then paste the Bot Token and App Token.
-
-### 4. Deploy
-
-Click **Deploy Agent**. The container spins up and your agent starts running.
-
-## Managing Agents
-
-Click into any agent to view its detail page with the Agent ID, version, and controls for Chat, Settings, and Restart.
-
-
- 
-
-
-The detail page also includes:
-
-- **Snapshots** — snapshots of the agent environment, recorded every minute when changes are detected
-- **Channels** — Telegram and Slack configuration
-- **Skills** — attached skill packages
-- **Secrets** — environment variables injected at startup
-
-### Chat
-
-Click **Chat** to open a direct session through the OpenClaw gateway. You can send messages, paste images, and start new sessions.
-
-
- 
-
-
-The gateway dashboard also provides access to instance management, sessions, usage metrics, and logs.
-
-### Settings
-
-Click **Settings** to open the full OpenClaw configuration panel covering environment, updates, authentication, channels, commands, hooks, skills, tools, gateway, models, and logging.
-
-
- 
-
-
-## Skills
-
-Skills are reusable capability packages pinned to private IPFS. You manage them at the workspace level and attach them to agents during creation.
-
-Each skill folder needs a `SKILL.md` with YAML frontmatter (name and description) and can optionally include a `metadata` JSON file for required environment variables. Click **Upload Skill**, name it (letters, numbers, hyphens, and underscores), add an optional description, and click **Upload & Register**.
-
-
- 
-
-
-Once an agent is deployed, its skills are managed through the OpenClaw instance directly.
-
-## Secrets
-
-The Secrets Vault stores encrypted API keys and credentials at the workspace level. You attach secrets to agents during creation, and they're injected as environment variables at startup. Values can't be viewed after saving.
-
-Click **Add Secret**, enter the environment variable name (e.g., `ANTHROPIC_API_KEY`) and its value, then save. Each secret shows which agents are using it.
-
-
- 
-
-
-After deployment, per-agent secrets are managed through the OpenClaw instance
\ No newline at end of file
diff --git a/agents/channels.mdx b/agents/channels.mdx
new file mode 100644
index 0000000..3f5b92b
--- /dev/null
+++ b/agents/channels.mdx
@@ -0,0 +1,61 @@
+---
+title: "Channels"
+description: "Connect your agent to messaging platforms"
+icon: "comments"
+---
+
+Channels connect your agent to external messaging platforms. Configure during agent creation or from the **Channels** section in your agent's detail page.
+
+| Channel | Status |
+| ------- | ------ |
+| Telegram | Available |
+| Slack | Available |
+| Discord | Available |
+| WhatsApp | Coming Soon |
+
+## Telegram
+
+1. Create a bot through [@BotFather](https://t.me/botfather)
+2. Copy the bot token
+3. Configure in Pinata
+
+| Option | Description |
+| ------ | ----------- |
+| **Bot Token** | Token from BotFather |
+| **DM Policy** | `open` (anyone) or `pairing` (approval required) |
+| **Allow From** | Allowed user IDs |
+
+## Slack
+
+1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps)
+2. Enable **Socket Mode**
+3. Generate an **App-Level Token** with `connections:write` scope
+4. Add Bot Token Scopes: `chat:write`, `im:write`, `im:history`, `im:read`, `users:read`, `app_mentions:read`
+5. Install to your workspace
+
+| Option | Description |
+| ------ | ----------- |
+| **Bot Token** | Bot User OAuth Token |
+| **App Token** | App-Level Token |
+
+## Discord
+
+1. Create an application at [discord.com/developers](https://discord.com/developers/applications)
+2. Create a Bot and copy the token
+3. Invite the bot to your server
+
+| Option | Description |
+| ------ | ----------- |
+| **Bot Token** | Discord bot token |
+
+## Managing Channels
+
+Configured channels show an **ENABLED** badge. Click **RECONFIGURE** to update settings.
+
+- Enable/disable channels without removing configuration
+- Token fields are optional when reconfiguring
+- Changes take effect after gateway restart
+
+
+ Keep bot tokens secure. Store them as [secrets](/agents/secrets) and never commit to version control.
+
diff --git a/agents/overview.mdx b/agents/overview.mdx
new file mode 100644
index 0000000..a1f17eb
--- /dev/null
+++ b/agents/overview.mdx
@@ -0,0 +1,76 @@
+---
+title: "Overview"
+description: "Deploy hosted OpenClaw agents through Pinata"
+icon: "lobster"
+---
+
+Pinata Agents are hosted [OpenClaw](https://openclaw.org) instances. Each agent runs in an isolated container with its own workspace, skills, and secrets.
+
+
+ Agents require a paid Pinata plan. [Upgrade here](https://app.pinata.cloud/billing).
+
+
+## Quick Start
+
+### 1. Add an LLM Provider Key
+
+Your agent needs an LLM provider to run. Add one of these as a [secret](/agents/secrets) first:
+
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `OPENROUTER_API_KEY`
+
+### 2. Create an Agent
+
+Open [agents.pinata.cloud](https://agents.pinata.cloud) and click **Create Agent**.
+
+**Step 1: Identity** — Choose a personality preset (Atlas, Nova, Sage) or create a custom one. Enter a name and optional description.
+
+**Step 2: Workspace** — The default Pinata workspace includes Node.js, Python, and common tools. Optionally add [skills](/agents/skills/overview).
+
+**Step 3: Connect** — Select your LLM provider (shows "Available" when the key exists). Add any additional secrets your agent needs. Optionally configure [channels](/agents/channels).
+
+**Step 4: Deploy** — Click **Deploy Agent**. Once provisioning completes, you're redirected to your agent's detail page.
+
+## Agent Detail Page
+
+The sidebar provides access to all agent features:
+
+| Section | Purpose |
+| ------- | ------- |
+| **Chat** | Conversation interface |
+| **Channels** | Messaging platform connections |
+| **Snapshots** | Workspace versions and git access |
+| **Skills** | Attached skill packages |
+| **Secrets** | Environment variables |
+| **Routes** | Port forwarding and domains |
+| **Tasks** | Scheduled jobs |
+
+**Dev Tools:** Console (terminal access), Logs, and Danger (delete agent).
+
+### Git Access
+
+Clone and edit your agent's workspace directly:
+
+```bash
+git clone https://agents.pinata.cloud/v0/agents/{agentId}/git {name}
+```
+
+Click **Copy with Token** in the Snapshots section to include authentication.
+
+## Next Steps
+
+
+
+ Expose services to the internet
+
+
+ Connect messaging platforms
+
+
+ Extend agent capabilities
+
+
+ Manage credentials
+
+
diff --git a/agents/routes.mdx b/agents/routes.mdx
new file mode 100644
index 0000000..15106a5
--- /dev/null
+++ b/agents/routes.mdx
@@ -0,0 +1,92 @@
+---
+title: "Routes"
+description: "Expose agent services to the internet"
+icon: "network-wired"
+---
+
+Routes expose services running inside your agent container to the internet. Open the **Routes** section from your agent's detail page.
+
+Click **ADD** to create a new route:
+
+| Option | Description |
+| ------ | ----------- |
+| **Path Route** | Map a URL path prefix to a container port |
+| **Custom Domain** | Route a hostname to a container port |
+
+## Path Routes
+
+Path routes forward traffic from a URL path to an internal port. The path prefix is stripped before reaching your service.
+
+Example: A request to `/app/api/users` with path prefix `/app` arrives at your service as `/api/users`.
+
+### Adding a Path Route
+
+| Field | Description |
+| ----- | ----------- |
+| **Path Prefix** | URL path (e.g., `/app`) |
+| **Port** | Container port (1025–65535) |
+| **Protected** | Require gateway token authentication |
+
+### Path Format
+
+- Must start with `/`
+- Letters, numbers, hyphens, underscores only
+- Cannot overlap with reserved paths (`/v0`, `/chat`, `/config`)
+
+## Custom Domains
+
+
+ Custom Domains is currently in beta.
+
+
+Custom domains route traffic from a dedicated hostname to a container port. Unlike path routes, the full request path is forwarded as-is.
+
+### Pinata Subdomains
+
+Get a random platform-assigned subdomain on `*.apps.pinata.cloud`.
+
+| Field | Description |
+| ----- | ----------- |
+| **Port** | Container port (1025–65535) |
+| **Protected** | Require gateway token authentication |
+
+Result: `https://swift-fox-347.apps.pinata.cloud` → your port
+
+### Bring Your Own Domain
+
+Use your own domain (e.g., `app.example.com`).
+
+| Field | Description |
+| ----- | ----------- |
+| **Domain** | Your domain |
+| **Port** | Container port |
+| **Protected** | Require gateway token authentication |
+
+#### DNS Setup
+
+After registering, configure these DNS records:
+
+1. **TXT record** — Verify domain ownership
+2. **CNAME record** — Point to the Pinata proxy
+
+Domain status progresses: `pending` → `pending_ssl` → `active`
+
+## Public vs Protected
+
+| Mode | Behavior |
+| ---- | -------- |
+| **Protected** | Requests require a gateway token |
+| **Public** | Open to the internet |
+
+
+ Public routes expose your service without authentication. Only use for services that handle their own auth.
+
+
+## Constraints
+
+| Limit | Value |
+| ----- | ----- |
+| Path routes per agent | 10 |
+| Custom domains per agent | 5 |
+| Port range | 1025–65535 |
+| Reserved port | 18789 (gateway) |
diff --git a/agents/secrets.mdx b/agents/secrets.mdx
new file mode 100644
index 0000000..d1db94f
--- /dev/null
+++ b/agents/secrets.mdx
@@ -0,0 +1,54 @@
+---
+title: "Secrets"
+description: "Store API keys and credentials securely"
+icon: "key"
+---
+
+Secrets are encrypted credentials available as environment variables in your agents. Manage them at [agents.pinata.cloud/secrets](https://agents.pinata.cloud/secrets).
+
+
+ Secret values cannot be viewed after saving. Store credentials securely before adding.
+
+
+## Secrets Vault
+
+The vault has two sections:
+
+**AI Providers** — Quick-access cards for LLM provider keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`). Shows "Connected" when configured.
+
+**Variables and Secrets** — All other secrets, showing name and which agents use them.
+
+## Adding Secrets
+
+Click **Add Secret**:
+
+| Option | Description |
+| ------ | ----------- |
+| **Add secret** | Create a single secret |
+| **Import .env file** | Bulk import |
+
+Enter a **Name** (the environment variable name) and **Value**, then save.
+
+## Using Secrets with Agents
+
+**During creation:** Add secrets in Step 3 (Connect) under "Variables and Secrets".
+
+**After deployment:** Open the agent's **Secrets** section and add from your vault.
+
+
+ New secrets require an agent restart to take effect.
+
+
+## Updating and Deleting
+
+Click the **...** menu on any secret to update or delete.
+
+- Updated secrets require agent restart
+- Secrets in use by agents cannot be deleted — detach first
+
+## Security
+
+- Encrypted at rest with AES-GCM
+- Unique derived key per user
+- Values never returned by API
+- Injected as environment variables, not written to disk
diff --git a/agents/skills/overview.mdx b/agents/skills/overview.mdx
new file mode 100644
index 0000000..e034dac
--- /dev/null
+++ b/agents/skills/overview.mdx
@@ -0,0 +1,86 @@
+---
+title: "Skills"
+sidebarTitle: "Skills"
+description: "Extend agent capabilities with reusable packages"
+icon: "wand-magic-sparkles"
+---
+
+Skills are IPFS-pinned code bundles that extend agent capabilities. Browse skills at [agents.pinata.cloud/skills](https://agents.pinata.cloud/skills).
+
+## Skills Library
+
+The library has three tabs:
+
+| Tab | Description |
+| --- | ----------- |
+| **All \| Installed** | Skills in your library |
+| **By Pinata** | Official verified skills |
+| **ClawHub Community** | Community marketplace |
+
+## Official Pinata Skills
+
+| Skill | Description |
+| ----- | ----------- |
+| **@pinata/api** | Pinata IPFS API for file storage, gateways, and vector search |
+| **@pinata/erc-8004** | Register AI agents on-chain |
+| **@pinata/memory-salience** | Salient memory with novelty, retention, and decay |
+| **@pinata/paraspace** | PARA-based workspace organization |
+| **@pinata/sqlite-sync** | SQLite with Pinata backup and versioning |
+
+Pinata skills show **BY PINATA** and **VERIFIED** badges.
+
+## ClawHub Community
+
+Browse community-created skills in the **ClawHub Community** tab. Each skill shows:
+
+- **Downloads** — Install count
+- **Stars** — Community rating
+
+Popular skills include Self-Improving-Agent, Ontology, Obsidian integration, and API Gateway.
+
+Click a skill card, then **Install** to add it to your library.
+
+## Skill Details
+
+Click any skill to view:
+
+- **Description** — Documentation
+- **CID** — IPFS identifier
+- **Required Secrets** — Environment variables needed
+- **Used By** — Agents using this skill
+
+## Uploading Custom Skills
+
+Click **Upload Skill** to create your own.
+
+Your skill folder must contain `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+---
+
+# My Skill
+
+Instructions for using this skill.
+```
+
+
+ Skills are uploaded to the public IPFS network.
+
+
+## Attaching Skills to Agents
+
+**During creation:** Add skills in Step 2 (Workspace) of the setup wizard.
+
+**After deployment:** Open the agent's **Skills** section and add from your library.
+
+Skills are copied into the agent workspace. Detaching removes the files but keeps the skill in your library.
+
+## Constraints
+
+| Limit | Value |
+| ----- | ----- |
+| Skills per agent | 10 |
+| Skill name | Letters, numbers, hyphens, underscores |
diff --git a/agents/templates.mdx b/agents/templates.mdx
new file mode 100644
index 0000000..2be5810
--- /dev/null
+++ b/agents/templates.mdx
@@ -0,0 +1,69 @@
+---
+title: "Templates"
+description: "Deploy pre-configured agents in one click"
+icon: "clone"
+---
+
+
+ Templates are currently in beta.
+
+
+Templates are pre-configured agent packages with bundled skills, required secrets, and default settings. Browse at [agents.pinata.cloud/templates](https://agents.pinata.cloud/templates).
+
+## Browsing Templates
+
+Filter by category:
+
+| Tab | Description |
+| --- | ----------- |
+| **All** | All templates |
+| **Data & Analytics** | Data processing agents |
+| **DeFi** | Decentralized finance tools |
+| **General** | General-purpose agents |
+| **Social** | Messaging bots |
+| **My Submissions** | Your submitted templates |
+
+### Featured Templates
+
+| Template | Description |
+| -------- | ----------- |
+| **IPFS Expert** | File storage, pinning, and content distribution |
+| **Telegram Bot** | Responds to messages and commands |
+| **Personal AI** | Personal assistant that learns your preferences |
+| **Frontend Dev Agent** | Frontend development with Vite, React, TypeScript |
+| **DeFi Monitor** | On-chain monitoring for protocols and whale activity |
+
+## Template Details
+
+Click a template to view:
+
+- **Description** — What it does
+- **Category** and **Tags**
+- **Version**
+- **Required Setup** — Secrets you need to provide
+
+### Required Setup
+
+Templates list the secrets needed before deployment. Example for Telegram Bot:
+
+| Secret | Description |
+| ------ | ----------- |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude |
+| `TELEGRAM_BOT_TOKEN` | Token from BotFather |
+
+Add these to your [Secrets vault](/agents/secrets) before deploying.
+
+## Deploying
+
+1. Select a template
+2. Review **Required Setup**
+3. Add any missing secrets
+4. Click **Deploy This Agent**
+
+## Paid Templates
+
+Some templates require payment via x402 micropayments (USDC on Base). Free templates show `FREE`.
+
+## Submitting Templates
+
+Click **Submit** to add your own template to the marketplace. Submissions appear in **My Submissions**.
diff --git a/docs.json b/docs.json
index 59e81e1..7c8e38a 100644
--- a/docs.json
+++ b/docs.json
@@ -61,7 +61,18 @@
{
"group": "AI",
"pages": [
- "agents",
+ {
+ "group": "Agents",
+ "icon": "lobster",
+ "pages": [
+ "agents/overview",
+ "agents/routes",
+ "agents/channels",
+ "agents/skills/overview",
+ "agents/secrets",
+ "agents/templates"
+ ]
+ },
"tools/cli/agents",
"llm-docs",
{
@@ -631,6 +642,10 @@
}
},
"redirects": [
+ {
+ "source": "/agents",
+ "destination": "/agents/overview"
+ },
{
"source": "/sdk",
"destination": "/sdk/getting-started"