Context

PraisonAI PR #1503 was merged into main (commit 9386823). It brings bots/gateways up to parity with modern agent frameworks by adding:

• Workspace sandboxing (new module praisonaiagents.workspace)
• Self-improving skill management (write API on SkillManager + skill_manage tool)
• 20+ expanded bot default tools (files, planning, skills, delegation, session)

These are user-facing features that agents use automatically when deployed as a bot. No end-user documentation exists yet for them. This issue defines exactly what needs to be created/updated and provides SDK source references so a follow-up agent can implement the docs per AGENTS.md.

Summary of SDK Changes

Documentation Plan

Each page below uses the standard template from AGENTS.md: frontmatter, hero Mermaid diagram (standard color scheme), Quick Start with <Steps>, How It Works, Configuration Options table, Common Patterns, Best Practices with <AccordionGroup>, Related <CardGroup>.

All examples must be agent-centric (open with an Agent(...) snippet), beginner-friendly, and use simple imports like from praisonaiagents import Agent.

1. NEW — docs/features/workspace.mdx

Why: Workspace sandboxing is brand-new and has zero documentation.

Frontmatter:

---
title: "Workspace"
sidebarTitle: "Workspace"
description: "Sandbox agent file operations inside a safe, per-session directory"
icon: "folder-lock"
---

Agent-centric opening example (Quick Start Step 1):

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(
    name="Assistant",
    instructions="You help users with files and tasks"
)

# Workspace is applied automatically when agent runs as a bot
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

Quick Start Step 2 — Custom workspace:

from praisonaiagents import Agent
from praisonai.bots import TelegramBot
from praisonaiagents.bots import BotConfig

config = BotConfig(
    token="YOUR_TOKEN",
    workspace_dir="./my-bot-workspace",  # custom path
    workspace_access="rw",                # "rw" | "ro" | "none"
    workspace_scope="session",            # "shared" | "session" | "user" | "agent"
)

bot = TelegramBot(config=config, agent=agent)

Hero Mermaid diagram:

graph LR
    subgraph "Workspace Sandbox"
        A[🤖 Agent] --> T[🛠️ File Tools]
        T --> W[📁 Workspace Root]
        W --> OK[✅ Inside = Allowed]
        W --> NO[🚫 Outside = Rejected]
    end
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef safe fill:#10B981,stroke:#7C90A0,color:#fff
    classDef danger fill:#F59E0B,stroke:#7C90A0,color:#fff
    class A agent
    class T,W tool
    class OK safe
    class NO danger

Access-mode decision diagram (to help users pick):

graph TD
    Q1["What should the agent do with files?"]
    Q1 -->|"Read AND write"| RW["rw (default)"]
    Q1 -->|"Only read"| RO["ro"]
    Q1 -->|"Isolated scratch only"| NONE["none (sandbox)"]
    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef a fill:#10B981,stroke:#7C90A0,color:#fff
    class Q1 q
    class RW,RO,NONE a

Configuration options table (extract exactly from praisonaiagents/workspace/__init__.py):

BotConfig fields (from praisonaiagents/bots/config.py):

Must cover:

• Why workspaces exist (security by construction, path-traversal protection, macOS symlink safety)
• The four scope modes (shared / session / user / agent) and when to use each
• That file tools fall back to os.getcwd() when no workspace is configured (backward compatibility)
• Workspace.contains(path) and Workspace.resolve(path) usage for advanced users
• Default path layout: ~/.praisonai/workspaces/<scope>/<session_key>/

Related cards: BotOS, Skills (Manage), Bot Default Tools

2. NEW — docs/features/skill-manage.mdx (self-improving skills)

Why: The skill_manage write API + SkillManager write methods are entirely new. Existing docs/concepts/skills.mdx and docs/features/skills.mdx only cover reading/loading skills, not creating/editing them at runtime.

Frontmatter:

---
title: "Self-Improving Skills"
sidebarTitle: "Skill Manage"
description: "Let agents create, edit, and patch their own skills at runtime"
icon: "wand-magic-sparkles"
---

Agent-centric opening:

from praisonaiagents import Agent

agent = Agent(
    name="Skill Builder",
    instructions="When users teach you something, save it as a skill for next time.",
    tools=["skill_manage", "skills_list", "skill_view"]  # auto-injected in bots
)

agent.start("Create a skill called 'weekly-summary' that summarises the week's work.")

Hero diagram — the self-improving loop:

graph LR
    subgraph "Self-Improving Loop"
        U[👤 User Request] --> A[🤖 Agent]
        A --> M{🔍 Skill Exists?}
        M -->|Yes| USE[⚡ Use Skill]
        M -->|No| NEW[✨ create/edit/patch]
        NEW --> SAVE[💾 SKILL.md]
        SAVE --> A
    end
    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef decide fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef action fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef done fill:#10B981,stroke:#7C90A0,color:#fff
    class U,A user
    class M decide
    class NEW,SAVE action
    class USE done

Actions table — document every action in skill_manage (from praisonaiagents/tools/skill_tools.py::skill_manage):

Python-level API (from praisonaiagents/skills/manager.py):

from praisonaiagents.skills import SkillManager

mgr = SkillManager()
mgr.discover()

mgr.create_skill("weekly-summary", "# Weekly Summary\nSteps...", category="reporting")
mgr.edit_skill("weekly-summary", "# Weekly Summary v2\n...")
mgr.patch_skill("weekly-summary", old_string="v2", new_string="v3")
mgr.delete_skill("weekly-summary")

mgr.write_skill_file("weekly-summary", "scripts/report.py", "print('hi')")
mgr.remove_skill_file("weekly-summary", "scripts/report.py")

Must cover:

• Security guards: 100KB SKILL.md limit, 1MB file limit, atomic writes via temp files, name validation, path validation
• Why this matters: agents can teach themselves and persist knowledge across sessions
• Typical user interaction flow (example): user teaches agent a new workflow in chat → agent calls skill_manage(action="create", ...) → agent uses that skill on the next matching request
• How workspace containment applies (skill files are written under the workspace root)
• Link to docs/concepts/skills.mdx for what skills are

Related cards: Workspace, Skills (concepts), Bot Default Tools

3. NEW — docs/features/bot-default-tools.mdx

Why: BotConfig.default_tools now ships with 20+ tools auto-injected. Existing docs/concepts/bot-os.mdx mentions --memory --web flags only. Users need a single place that shows what a bot can do out of the box.

Frontmatter:

---
title: "Bot Default Tools"
sidebarTitle: "Bot Default Tools"
description: "The 20+ tools every bot gets automatically"
icon: "toolbox"
---

Agent-centric opening — "zero-config bot" with every superpower:

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(
    name="Assistant",
    instructions="You help users. Use any tool you need."
)

# No tools= passed — bot auto-injects safe defaults
TelegramBot(token="YOUR_TOKEN", agent=agent).start()

Hero diagram — tool categories:

graph TB
    subgraph "Auto-Injected Bot Tools"
        BOT[🤖 Bot]
        BOT --> FILE[📁 Files<br/>read/write/edit/list/search]
        BOT --> PLAN[📋 Planning<br/>todo_add/list/update]
        BOT --> SKILL[🧠 Skills<br/>skill_manage/list/view]
        BOT --> WEB[🌐 Web<br/>search_web/web_crawl]
        BOT --> MEM[💾 Memory<br/>store/search memory & learning]
        BOT --> SCHED[⏰ Schedule<br/>schedule_add/list/remove]
    end
    classDef bot fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef cat fill:#189AB4,stroke:#7C90A0,color:#fff
    class BOT bot
    class FILE,PLAN,SKILL,WEB,MEM,SCHED cat

Full default tool table (extract verbatim from BotConfig.default_tools in praisonaiagents/bots/config.py):

Opt-in (not auto-injected): delegate_task, session_search — both are stub implementations right now and return honest "not configured" errors. Document this clearly so users aren't surprised.

Customising defaults:

from praisonaiagents.bots import BotConfig

config = BotConfig(
    token="YOUR_TOKEN",
    default_tools=["search_web", "read_file", "todo_add"],  # override list
    auto_approve_tools=True,  # default True for bots
)

Must cover:

• How smart defaults work (agent has no tools → bot auto-injects safe defaults from apply_bot_smart_defaults)
• How to disable: explicitly pass tools=[] (bot respects _explicit_empty_tools)
• Relationship with workspace: destructive file tools (write_file, edit_file, skill_manage) are filtered out unless a workspace is configured
• auto_approve_tools flag (default True for bots because chat UIs can't show approval prompts)

Related cards: BotOS, Workspace, Tools

4. NEW — docs/features/todo-planning.mdx

Why: todo_tools.py is a brand-new module. Great for "agent-centric planning" per AGENTS.md principle (show how an agent uses todos in a real flow).

Frontmatter:

---
title: "Todo Planning"
sidebarTitle: "Todos"
description: "Let agents plan multi-step tasks with a persistent todo list"
icon: "list-check"
---

Agent-centric Quick Start:

from praisonaiagents import Agent

agent = Agent(
    name="Planner",
    instructions="Break tasks into todos, then execute them one by one.",
    tools=["todo_add", "todo_list", "todo_update"]
)

agent.start("Plan a blog launch — research, draft, publish.")

User interaction flow diagram:

sequenceDiagram
    participant U as 👤 User
    participant A as 🤖 Agent
    participant T as 📋 Todos
    U->>A: "Plan a blog launch"
    A->>T: todo_add("research topic")
    A->>T: todo_add("draft post")
    A->>T: todo_add("publish")
    A->>T: todo_list()
    T-->>A: 3 pending todos
    A->>T: todo_update(1, status="completed")
    A-->>U: "Done ✅ — moving to drafting"

Parameters table (from praisonaiagents/tools/todo_tools.py):

Must cover:

• Persistence: todos are stored at <workspace.root>/todos.json (or ~/.praisonai/todos.json without workspace)
• Use as a planning primitive for longer-horizon tasks
• How it combines with skill_manage and file tools

5. NEW — docs/features/file-editing.mdx

Why: edit_tools.py (edit_file, search_files) is new and workspace-aware. file_tools.py gained a create_file_tools(workspace=...) factory.

Frontmatter:

---
title: "File Editing"
sidebarTitle: "File Editing"
description: "Fuzzy find-and-replace across files, scoped to a workspace"
icon: "file-pen"
---

Must cover:

• edit_file(filepath, old_string, new_string, replace_all=False) — approval-gated at risk level high
• search_files(directory, pattern, file_pattern="*") — returns JSON with match locations
• read_file / write_file / list_files from file_tools.py
• Workspace scoping: destructive ops require a configured Workspace
• Error message for escaping the workspace: "Path escapes workspace: ..."

Agent-centric opening:

from praisonaiagents import Agent

agent = Agent(
    name="Code Editor",
    instructions="Edit code files carefully using fuzzy search and replace.",
    tools=["edit_file", "search_files", "read_file"]
)

6. UPDATE — docs/features/skills.mdx

Why: Current file covers reading/loading skills. Needs a new section pointing to the new "Self-Improving Skills" page.

Add to the existing file:

• A "Managing skills at runtime" sub-section with a short blurb + CardGroup link to the new docs/features/skill-manage.mdx
• Note that skills_list and skill_view are now tools agents can call directly

Do NOT touch docs/concepts/skills.mdx — it is in the human-only folder.

7. UPDATE — docs.json

Add the new features pages under the Features group (never under Concepts). Expected entries:

"features/workspace",
"features/skill-manage",
"features/bot-default-tools",
"features/todo-planning",
"features/file-editing"

Verify docs.json stays valid JSON after editing.

Writing Rules Recap (from AGENTS.md)

For every page the follow-up agent writes:

• Open with a short (one-line) description; no filler intros
• Agent-centric code example at the very top
• Hero Mermaid diagram using the standard palette: #8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text, #7C90A0 stroke
• Simple imports only (from praisonaiagents import Agent), not deep subpaths
• <Steps> in Quick Start, <AccordionGroup> in Best Practices, <CardGroup> in Related
• Configuration tables extracted verbatim from the SDK files listed above
• Show a user-interaction flow diagram where there are choices (e.g. access modes, skill actions)
• No forbidden phrases ("As you can see…", "It's important to note…", etc.)
• Pages live under docs/features/ — never docs/concepts/
• Register pages in docs.json under the Features group

References

• PR: feat: workspace sandboxing + self-improving skill management + expanded bot toolset PraisonAI#1503
• Head SHA: 93868235518512d872cd72cbb6dc30d6a51a8928
• Issue it fixes: Feature: Bot/Gateway parity with hermes-agent + openclaw — expanded defaults, self-improving skill_manage, per-session workspace sandbox PraisonAI#1499

Exact SDK source files to read (in MervinPraison/PraisonAI at PR head)

• src/praisonai-agents/praisonaiagents/workspace/__init__.py
• src/praisonai-agents/praisonaiagents/bots/config.py
• src/praisonai-agents/praisonaiagents/skills/manager.py
• src/praisonai-agents/praisonaiagents/tools/skill_tools.py
• src/praisonai-agents/praisonaiagents/tools/todo_tools.py
• src/praisonai-agents/praisonaiagents/tools/edit_tools.py
• src/praisonai-agents/praisonaiagents/tools/file_tools.py
• src/praisonai-agents/praisonaiagents/tools/session_tools.py
• src/praisonai-agents/praisonaiagents/tools/delegation_tools.py
• src/praisonai/praisonai/bots/_defaults.py
• src/praisonai/praisonai/bots/bot.py

Remember: session_search and delegate_task are stubs — don't invent behaviour they don't have. Document them as planned/opt-in placeholders.