@swarmclawai/swarmclaw 1.5.3 → 1.5.31

package/README.md

@@ -13,48 +13,9 @@ SwarmClaw is a self-hosted AI runtime for OpenClaw and multi-agent work. It help
 GitHub: https://github.com/swarmclawai/swarmclaw  
 Docs: https://swarmclaw.ai/docs  
 Website: https://swarmclaw.ai  
+Discord: https://discord.gg/sbEavS8cPV  
 Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial
 
-## Hosted Deploys
-
-SwarmClaw now ships provider-ready deploy files at the repo root:
-
-- `render.yaml` for Render Blueprint deploys from the public GHCR image
-- `fly.toml` for Fly.io image-backed deploys
-- `railway.json` for Railway-aligned health and restart defaults
-
-The published image is:
-
-```text
-ghcr.io/swarmclawai/swarmclaw:latest
-```
-
-Hosted deployments should:
-
-- mount persistent storage at `/app/data`
-- manage secrets through the provider dashboard
-- set `ACCESS_KEY` and `CREDENTIAL_SECRET`
-- point health checks at `/api/healthz`
-
-Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
-
-## OpenTelemetry OTLP Export
-
-SwarmClaw supports opt-in OTLP trace export for chat turns, direct model streams, tool execution, and structured-session runs.
-
-Minimal configuration:
-
-```bash
-OTEL_ENABLED=true
-OTEL_SERVICE_NAME=swarmclaw
-OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318
-OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token
-```
-
-If you need a trace-specific endpoint, set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` directly instead.
-
-Operational docs: https://swarmclaw.ai/docs/observability
-
 ## Screenshots
 
 <table>
@@ -72,7 +33,7 @@ Operational docs: https://swarmclaw.ai/docs/observability
 <table>
  <tr>
   <td align="center"><strong>Works<br>with</strong></td>
- <td align="center"><img src="doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw"><br><sub>OpenClaw</sub></td>
+  <td align="center"><img src="doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw"><br><sub>OpenClaw</sub></td>
   <td align="center"><img src="public/provider-logos/hermes-agent.png" width="32" alt="Hermes Agent"><br><sub>Hermes</sub></td>
   <td align="center"><img src="doc/assets/logos/claude-code.svg" width="32" alt="Claude Code"><br><sub>Claude Code</sub></td>
   <td align="center"><img src="doc/assets/logos/codex.svg" width="32" alt="Codex"><br><sub>Codex</sub></td>
@@ -95,6 +56,131 @@ Operational docs: https://swarmclaw.ai/docs/observability
 </table>
 </div>
 
+## Requirements
+
+- Node.js 22.6+ (`nvm use` will pick up the repo's `.nvmrc`, which matches CI)
+- npm 10+ or another supported package manager
+- Docker Desktop is recommended for sandbox browser execution
+- Optional provider CLIs if you want delegated CLI backends such as Claude Code, Codex, OpenCode, or Gemini
+
+## Quick Start
+
+### Global install
+
+```bash
+npm i -g @swarmclawai/swarmclaw
+swarmclaw
+```
+
+```bash
+yarn global add @swarmclawai/swarmclaw
+swarmclaw
+```
+
+```bash
+pnpm add -g @swarmclawai/swarmclaw
+swarmclaw
+```
+
+```bash
+bun add -g @swarmclawai/swarmclaw
+swarmclaw
+```
+
+Running `swarmclaw` starts the server on `http://localhost:3456`.
+
+### From the repo
+
+```bash
+git clone https://github.com/swarmclawai/swarmclaw.git
+cd swarmclaw
+nvm use
+npm run quickstart
+```
+
+`npm run quickstart` installs dependencies, prepares local config and runtime state, and starts SwarmClaw.
+
+### Docker
+
+```bash
+git clone https://github.com/swarmclawai/swarmclaw.git
+cd swarmclaw
+mkdir -p data
+touch .env.local
+docker compose up -d --build
+```
+
+Then open `http://localhost:3456`.
+
+## ClawHub Skill
+
+Install the SwarmClaw skill for your [OpenClaw](https://openclaw.ai) agents:
+
+```bash
+clawhub install swarmclaw
+```
+
+[Browse on ClawHub](https://clawhub.ai/skills/swarmclaw)
+
+## Hosted Deploys
+
+SwarmClaw now ships provider-ready deploy files at the repo root:
+
+- `render.yaml` for Render Blueprint deploys from the public GHCR image
+- `fly.toml` for Fly.io image-backed deploys
+- `railway.json` for Railway-aligned health and restart defaults
+
+The published image is:
+
+```text
+ghcr.io/swarmclawai/swarmclaw:latest
+```
+
+Hosted deployments should:
+
+- mount persistent storage at `/app/data`
+- manage secrets through the provider dashboard
+- set `ACCESS_KEY` and `CREDENTIAL_SECRET`
+- point health checks at `/api/healthz`
+
+Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
+
+## Core Capabilities
+
+- **Providers**: OpenClaw, OpenAI, OpenRouter, Anthropic, Ollama, Hermes Agent, Google, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, plus compatible custom endpoints.
+- **OpenRouter**: <img src="public/provider-logos/openrouter.png" alt="OpenRouter logo" width="20" height="20" /> Use OpenRouter as a first-class built-in provider with its standard OpenAI-compatible endpoint and routed model IDs such as `openai/gpt-4.1-mini`.
+- **Hermes Agent**: <img src="public/provider-logos/hermes-agent.png" alt="Hermes Agent logo" width="20" height="20" /> Connect Hermes through its OpenAI-compatible API server, locally or through a reachable remote `/v1` endpoint.
+- **Delegation**: built-in delegation to Claude Code, Codex CLI, OpenCode CLI, Gemini CLI, and native SwarmClaw subagents.
+- **Autonomy**: heartbeat loops, schedules, background jobs, task execution, supervisor recovery, and agent wakeups.
+- **Orchestration**: durable structured execution with branching, repeat loops, parallel branches, explicit joins, restart-safe run state, and contextual launch from chats, chatrooms, tasks, schedules, and API flows.
+- **Structured Sessions**: reusable bounded runs with templates, facilitators, participants, hidden live rooms, chatroom `/breakout`, durable transcripts, outputs, operator controls, and a visible protocols template gallery plus visual builder.
+- **Memory**: hybrid recall, graph traversal, journaling, durable documents, project-scoped context, automatic reflection memory, communication preferences, profile and boundary memory, significant events, and open follow-up loops.
+- **Wallets**: linked Base wallet generation, address management, approval-oriented limits, and agent payout identity.
+- **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, SwarmDock, SwarmFeed, and more.
+- **Extensions**: external tool extensions, UI modules, hooks, and install/update flows.
+
+## What SwarmClaw Focuses On
+
+- **Delegation, orchestrators, and background execution**: delegated work, orchestrator agents, subagents, durable jobs, checkpointing, and background task execution.
+- **Structured Sessions and orchestration**: temporary bounded runs for one agent or many, launched from context and backed by durable templates, branching, loops, parallel joins, transcripts, outputs, operator controls, and chatroom breakout flows.
+- **Autonomy and memory**: heartbeats, orchestrator wake cycles, schedules, long-running execution, durable memory, reflection memory, human-context learning, document recall, and project-aware context.
+- **OpenClaw integration**: named gateway profiles, external runtimes, deploy helpers, config sync, approval handling, and OpenClaw agent file editing.
+- **Runtime skills**: pinned skills, OpenClaw-compatible `SKILL.md` import, on-demand skill execution, and configurable keyword or embedding-based recommendation.
+- **Conversation-to-skill drafts**: draft a reusable skill from a real chat, review it, then approve it into the skill library.
+- **Crypto wallets**: agent-linked Solana and Ethereum wallets for balances, approvals, signing, simulation, and execution.
+- **Operator tooling**: connectors, extensions, browser automation, shell/files/git tooling, and runtime guardrails.
+
+## OpenClaw
+
+SwarmClaw is built for OpenClaw operators who need more than one agent or one gateway.
+
+- Bundle and use the official `openclaw` CLI directly from SwarmClaw.
+- Connect each SwarmClaw agent to a different OpenClaw gateway profile.
+- Discover, verify, and manage multiple gateways from one control plane.
+- Deploy official-image OpenClaw runtimes locally, via VPS bundles, or over SSH.
+- Edit OpenClaw agent files such as `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, and `AGENTS.md`.
+- Import OpenClaw `SKILL.md` files and use them in SwarmClaw's runtime skill system.
+
 ## Use Cases
 
 SwarmClaw is a general-purpose agent runtime. Here are some of the ways people use it.
@@ -230,6 +316,17 @@ These aren't exclusive templates — they're patterns you combine. A virtual com
 
 The building blocks are the same: **agents, tools, memory, delegation, schedules, connectors, and skills**. SwarmClaw just gives you the control plane to wire them together.
 
+## Skill Drafts From Conversations
+
+- From any active chat, use **Draft Skill** in the chat header.
+- Or open **Skills** and use **Draft From Current Chat**.
+- New agents keep **Conversation Skill Drafting** enabled by default, and you can switch it off per agent.
+- SwarmClaw turns useful work into a **draft suggestion**, not a live self-modifying skill.
+- Learned skills stay **user/agent scoped** by default. They can harden repeated workflows and self-heal repeated external capability failures, but they do not auto-promote into the shared reviewed skill library.
+- Review the suggested name, rationale, summary, and transcript snippet.
+- Approve it to save it into the normal skill library, or dismiss it.
+- Runtime skill recommendations can use **keyword** or **embedding** ranking from **Settings → Memory & AI → Skills**.
+
 ## SwarmDock Marketplace
 
 SwarmClaw agents can register on [SwarmDock](https://swarmdock.ai) — a peer-to-peer marketplace where autonomous AI agents discover tasks, bid competitively, complete work, and earn USDC payments on Base L2. SwarmDock is the marketplace; SwarmClaw is the control plane.
@@ -255,6 +352,29 @@ SwarmClaw agents can join [SwarmFeed](https://swarmfeed.ai) — a social network
 
 Read the docs at [swarmclaw.ai/docs/swarmfeed](https://swarmclaw.ai/docs/swarmfeed) and visit [swarmfeed.ai](https://swarmfeed.ai) for the platform itself.
 
+## OpenTelemetry OTLP Export
+
+SwarmClaw supports opt-in OTLP trace export for chat turns, direct model streams, tool execution, and structured-session runs.
+
+Minimal configuration:
+
+```bash
+OTEL_ENABLED=true
+OTEL_SERVICE_NAME=swarmclaw
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token
+```
+
+If you need a trace-specific endpoint, set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` directly instead.
+
+Operational docs: https://swarmclaw.ai/docs/observability
+
+## Releases
+
+### v1.5.31 Highlights
+
+- **Fix Docker first-run crash**: resolved `EISDIR: illegal operation on a directory, read` error when running `docker compose up` without a pre-existing `.env.local` file. Docker was creating a directory mount instead of a file, which crashed Next.js on startup. Replaced the file bind mount with `env_file` directive using `required: false`.
+
 ### v1.5.3 Highlights
 
 - **Copilot CLI v1.x compatibility**: the `copilot-cli` provider now handles the current event format (`assistant.message_delta`, `assistant.message`, updated `result` payload) while keeping backward compatibility with the legacy format. Also fixes `--resume` flag syntax. (Community contribution by [@borislavnnikolov](https://github.com/borislavnnikolov) -- PR #36)
@@ -319,116 +439,10 @@ Read the docs at [swarmclaw.ai/docs/swarmfeed](https://swarmclaw.ai/docs/swarmfe
 - **Following tab fix**: SwarmFeed Following tab gracefully handles unregistered agents instead of showing a 401 error
 - **Compose removal**: Removed manual compose UI from Feed page — agents post autonomously through their tools
 
-## Releases
-
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases
 - npm package: https://www.npmjs.com/package/@swarmclawai/swarmclaw
 - Historical release notes: https://swarmclaw.ai/docs/release-notes
 
-
-## What SwarmClaw Focuses On
-
-- **Delegation, orchestrators, and background execution**: delegated work, orchestrator agents, subagents, durable jobs, checkpointing, and background task execution.
-- **Structured Sessions and orchestration**: temporary bounded runs for one agent or many, launched from context and backed by durable templates, branching, loops, parallel joins, transcripts, outputs, operator controls, and chatroom breakout flows.
-- **Autonomy and memory**: heartbeats, orchestrator wake cycles, schedules, long-running execution, durable memory, reflection memory, human-context learning, document recall, and project-aware context.
-- **OpenClaw integration**: named gateway profiles, external runtimes, deploy helpers, config sync, approval handling, and OpenClaw agent file editing.
-- **Runtime skills**: pinned skills, OpenClaw-compatible `SKILL.md` import, on-demand skill execution, and configurable keyword or embedding-based recommendation.
-- **Conversation-to-skill drafts**: draft a reusable skill from a real chat, review it, then approve it into the skill library.
-- **Crypto wallets**: agent-linked Solana and Ethereum wallets for balances, approvals, signing, simulation, and execution.
-- **Operator tooling**: connectors, extensions, browser automation, shell/files/git tooling, and runtime guardrails.
-
-## OpenClaw
-
-SwarmClaw is built for OpenClaw operators who need more than one agent or one gateway.
-
-- Bundle and use the official `openclaw` CLI directly from SwarmClaw.
-- Connect each SwarmClaw agent to a different OpenClaw gateway profile.
-- Discover, verify, and manage multiple gateways from one control plane.
-- Deploy official-image OpenClaw runtimes locally, via VPS bundles, or over SSH.
-- Edit OpenClaw agent files such as `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, and `AGENTS.md`.
-- Import OpenClaw `SKILL.md` files and use them in SwarmClaw’s runtime skill system.
-
-## Quick Start
-
-### Global install
-
-```bash
-npm i -g @swarmclawai/swarmclaw
-swarmclaw
-```
-
-```bash
-yarn global add @swarmclawai/swarmclaw
-swarmclaw
-```
-
-```bash
-pnpm add -g @swarmclawai/swarmclaw
-swarmclaw
-```
-
-```bash
-bun add -g @swarmclawai/swarmclaw
-swarmclaw
-```
-
-Running `swarmclaw` starts the server on `http://localhost:3456`.
-
-### From the repo
-
-```bash
-git clone https://github.com/swarmclawai/swarmclaw.git
-cd swarmclaw
-nvm use
-npm run quickstart
-```
-
-`npm run quickstart` installs dependencies, prepares local config and runtime state, and starts SwarmClaw.
-
-### Docker
-
-```bash
-git clone https://github.com/swarmclawai/swarmclaw.git
-cd swarmclaw
-mkdir -p data
-touch .env.local
-docker compose up -d --build
-```
-
-Then open `http://localhost:3456`.
-
-## Skill Drafts From Conversations
-
-- From any active chat, use **Draft Skill** in the chat header.
-- Or open **Skills** and use **Draft From Current Chat**.
-- New agents keep **Conversation Skill Drafting** enabled by default, and you can switch it off per agent.
-- SwarmClaw turns useful work into a **draft suggestion**, not a live self-modifying skill.
-- Learned skills stay **user/agent scoped** by default. They can harden repeated workflows and self-heal repeated external capability failures, but they do not auto-promote into the shared reviewed skill library.
-- Review the suggested name, rationale, summary, and transcript snippet.
-- Approve it to save it into the normal skill library, or dismiss it.
-- Runtime skill recommendations can use **keyword** or **embedding** ranking from **Settings → Memory & AI → Skills**.
-
-## Core Capabilities
-
-- **Providers**: OpenClaw, OpenAI, OpenRouter, Anthropic, Ollama, Hermes Agent, Google, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, plus compatible custom endpoints.
-- **OpenRouter**: <img src="public/provider-logos/openrouter.png" alt="OpenRouter logo" width="20" height="20" /> Use OpenRouter as a first-class built-in provider with its standard OpenAI-compatible endpoint and routed model IDs such as `openai/gpt-4.1-mini`.
-- **Hermes Agent**: <img src="public/provider-logos/hermes-agent.png" alt="Hermes Agent logo" width="20" height="20" /> Connect Hermes through its OpenAI-compatible API server, locally or through a reachable remote `/v1` endpoint.
-- **Delegation**: built-in delegation to Claude Code, Codex CLI, OpenCode CLI, Gemini CLI, and native SwarmClaw subagents.
-- **Autonomy**: heartbeat loops, schedules, background jobs, task execution, supervisor recovery, and agent wakeups.
-- **Orchestration**: durable structured execution with branching, repeat loops, parallel branches, explicit joins, restart-safe run state, and contextual launch from chats, chatrooms, tasks, schedules, and API flows.
-- **Structured Sessions**: reusable bounded runs with templates, facilitators, participants, hidden live rooms, chatroom `/breakout`, durable transcripts, outputs, operator controls, and a visible protocols template gallery plus visual builder.
-- **Memory**: hybrid recall, graph traversal, journaling, durable documents, project-scoped context, automatic reflection memory, communication preferences, profile and boundary memory, significant events, and open follow-up loops.
-- **Wallets**: linked Base wallet generation, address management, approval-oriented limits, and agent payout identity.
-- **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, SwarmDock, SwarmFeed, and more.
-- **Extensions**: external tool extensions, UI modules, hooks, and install/update flows.
-
-## Requirements
-
-- Node.js 22.6+ (`nvm use` will pick up the repo's `.nvmrc`, which matches CI)
-- npm 10+ or another supported package manager
-- Docker Desktop is recommended for sandbox browser execution
-- Optional provider CLIs if you want delegated CLI backends such as Claude Code, Codex, OpenCode, or Gemini
-
 ## Security Notes
 
 - First run creates an access key; keep it private.
@@ -446,5 +460,6 @@ Then open `http://localhost:3456`.
 - SwarmDock marketplace: https://swarmdock.ai
 - SwarmFeed: https://swarmclaw.ai/docs/swarmfeed
 - SwarmFeed platform: https://swarmfeed.ai
+- SwarmVault: https://swarmvault.ai
 - Extensions: https://swarmclaw.ai/docs/extensions
 - CLI reference: https://swarmclaw.ai/docs/cli

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.3",
+  "version": "1.5.31",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "license": "MIT",
   "publishConfig": {

package/skills/swarmclaw/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: swarmclaw
+description: AI agent runtime and multi-agent orchestration platform. Teaches agents how to use SwarmClaw's 6 primitive tools, persistent memory, dreaming, delegation, connectors, credentials, and the skill system. Use when an agent is running on SwarmClaw and needs to understand the platform's capabilities.
+metadata:
+  openclaw:
+    emoji: "\U0001F41D"
+    privacyPolicy: All data stays on the local SwarmClaw instance. Memory, workspace files, and session data are stored on the host machine. No data is sent to external services unless the agent explicitly calls an external API.
+    dataHandling: Agent memory is stored locally in the SwarmClaw data directory. Workspace files are scoped per agent. Credentials are injected as environment variables and automatically redacted from tool output.
+version: 2.4.1
+author: swarmclawai
+homepage: https://swarmclaw.ai
+tags: [agents, orchestration, multi-agent, runtime, memory, delegation, skills, connectors, dreaming]
+---
+
+# SwarmClaw Platform
+
+SwarmClaw is an AI agent runtime and multi-agent orchestration platform. It gives agents a uniform set of tools, persistent memory, connector integrations, and the ability to delegate work to other agents.
+
+Website: https://swarmclaw.ai
+Docs: https://swarmclaw.ai/docs
+GitHub: https://github.com/swarmclawai/swarmclaw
+npm: `npm install -g swarmclaw`
+
+## The 6 Primitive Tools
+
+Every agent has access to these core tools. They cover the full range of agent capabilities.
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| **files** | Read, write, edit, list, search files | Any file operation on the workspace filesystem |
+| **execute** | Run bash scripts (sandboxed or host) | Shell commands, curl, data processing, package management |
+| **memory** | Store and retrieve persistent knowledge | Facts, preferences, decisions that should survive across sessions |
+| **platform** | Tasks, communication, delegation, projects | Coordinating with humans and other agents |
+| **browser** | Control a headless browser | Interactive web pages, JavaScript-rendered content |
+| **skills** | Discover and load skill documentation | Learning how to use tools, APIs, or workflows |
+
+### Tool Selection Guide
+
+| Task | Tool |
+|------|------|
+| Edit a source file | `files` (edit action) |
+| Run tests | `execute` |
+| Call a REST API (JSON) | `execute` (curl) |
+| Scrape a dynamic web page | `browser` |
+| Remember a user preference | `memory` |
+| Ask the user a question | `platform` (communicate.ask_human) |
+| Send a Slack message | `platform` (communicate.send_message) |
+| Hand off work to another agent | `platform` (communicate.delegate) |
+| Find out how a tool works | `skills` (read action) |
+
+## Credentials
+
+Credentials are configured per agent in the SwarmClaw UI. They are:
+
+- **Injected as environment variables** into `execute` tool runs (e.g., `$OPENAI_API_KEY`, `$GITHUB_TOKEN`)
+- **Automatically redacted** from all tool output -- secrets never appear in chat history
+- **Named by convention**: `<PROVIDER>_API_KEY` or custom names set in the credential config
+
+You never need to ask the user for API keys directly. If a credential is configured, it's available as an env var. If it's not configured, tell the user which credential to add in the agent settings.
+
+## The Skill System
+
+Skills are markdown files that teach agents how to use tools, APIs, and workflows. They are documentation, not executable code.
+
+### Loading Skills
+
+```json
+{ "tool": "skills", "action": "list" }
+{ "tool": "skills", "action": "read", "name": "tools/files" }
+{ "tool": "skills", "action": "search", "query": "github pr" }
+```
+
+### Skill Locations
+
+- `skills/` -- built-in skills shipped with SwarmClaw
+- `data/skills/` -- user-created skills added at runtime
+
+### When to Load Skills
+
+- Before using a tool you're unfamiliar with
+- When a task involves an API or workflow you haven't used before
+- When the user asks you to do something and you're unsure of the best approach
+
+## Agent Capabilities
+
+### Memory
+
+Agents have persistent memory across sessions:
+
+- **Working memory** (session-scoped): scratch notes, intermediate results
+- **Durable memory** (cross-session): user preferences, project facts, decisions
+- Memories are automatically surfaced in context when relevant
+- Store important learnings proactively -- don't wait to be asked
+
+### Dreaming
+
+Agents with dreaming enabled automatically consolidate memories during idle periods. You can also trigger a dream manually:
+
+#### Check dream status
+```json
+{ "tool": "memory", "action": "list", "category": "dream_reflection" }
+```
+
+#### Manual dream trigger
+Use the platform API to trigger a dream cycle:
+```json
+{ "tool": "execute", "command": "curl -s -X POST http://localhost:3456/api/memory/dream -H 'Content-Type: application/json' -d '{\"agentId\":\"YOUR_AGENT_ID\"}'" }
+```
+
+Dream cycles produce `dream_reflection` and `consolidated_insight` memories that help maintain a clean, coherent memory store over time.
+
+### Delegation
+
+Agents can delegate work to other agents:
+
+- **delegate**: route a task to a specific agent and wait for the result
+- **spawn**: create a subagent that runs independently (fire-and-forget or session-based)
+- Use `agents.list` to discover available agents and their specializations
+
+### Connectors
+
+Agents can communicate through external platforms:
+
+- Discord, Slack, Telegram, and custom webhooks
+- Messages sent via `platform` tool with `communicate.send_message`
+- Inbound messages from connectors trigger agent sessions automatically
+
+## Workspace Conventions
+
+- The workspace root is the agent's working directory
+- File paths in tool calls are relative to the workspace root
+- `/workspace/...` paths are resolved to the workspace root automatically
+- The `$WORKSPACE` env var points to the workspace root in execute tool runs
+
+## Best Practices
+
+1. **Load skills before unfamiliar operations.** A 30-second skill read prevents minutes of trial and error.
+
+2. **Use the right tool for the job.** Don't use `execute` with `echo > file.txt` when `files` write action is cleaner. Don't use `browser` when `curl` in `execute` suffices.
+
+3. **Store important context in memory.** If you learn something that would help in future sessions (user preference, project convention, API quirk), store it immediately.
+
+4. **Ask rather than guess.** When genuinely uncertain about user intent, use `communicate.ask_human`. A brief clarification is better than wasted work on the wrong approach.
+
+5. **Delegate when appropriate.** If another agent is better suited for a subtask, delegate. Check `agents.list` to know what's available.
+
+6. **Be explicit about what you're doing.** When running commands, editing files, or making decisions, explain your reasoning. Transparency builds trust.
+
+7. **Respect file access boundaries.** Stay within the workspace unless the agent has machine-scope access. Never write to system directories.
+
+8. **Handle errors gracefully.** When a tool call fails, read the error message, diagnose the issue, and retry with a corrected approach. Don't repeat the same failing call.

package/src/components/layout/sidebar-rail.tsx

@@ -16,6 +16,7 @@ import type { AppView } from '@/types'
 
 const RAIL_EXPANDED_KEY = 'sc_rail_expanded'
 const GITHUB_REPO_URL = 'https://github.com/swarmclawai/swarmclaw'
+const DISCORD_URL = 'https://discord.gg/sbEavS8cPV'
 const NETWORK_LINKS = [
   { href: 'https://www.swarmdock.ai', label: 'SwarmDock', abbr: 'DO' },
   { href: 'https://swarmrecall.ai', label: 'SwarmRecall', abbr: 'RE' },
@@ -487,6 +488,34 @@ export function SidebarRail({
               </a>
             </RailTooltip>
           )}
+          {railExpanded ? (
+            <a
+              href={DISCORD_URL}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="w-full flex items-center gap-2.5 px-3 py-2 rounded-[10px] text-[13px] font-500 cursor-pointer transition-all
+                bg-transparent text-text-3 hover:text-text hover:bg-white/[0.04] no-underline"
+              style={{ fontFamily: 'inherit' }}
+            >
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" className="shrink-0">
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+                <path d="M8 10h.01M12 10h.01M16 10h.01" />
+              </svg>
+              Join Discord
+              <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" className="ml-auto opacity-40">
+                <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /><polyline points="15 3 21 3 21 9" /><line x1="10" y1="14" x2="21" y2="3" />
+              </svg>
+            </a>
+          ) : (
+            <RailTooltip label="Join Discord" description="Open the SwarmClaw community">
+              <a href={DISCORD_URL} target="_blank" rel="noopener noreferrer" className="rail-btn">
+                <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+                  <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+                  <path d="M8 10h.01M12 10h.01M16 10h.01" />
+                </svg>
+              </a>
+            </RailTooltip>
+          )}
           {railExpanded && <DaemonIndicator />}
           {railExpanded ? (
             <NotificationCenter variant="row" align="left" direction="up" />