octo-agent 0.11.2

data/lib/octo/default_skills/product-help/docs/create-your-first-skill.md

@@ -0,0 +1,47 @@
+# Create Your First Skill
+
+## Step 1: Create the Skill Directory
+
+```bash
+mkdir -p ~/.octo/skills/hello-world
+```
+
+## Step 2: Write SKILL.md
+
+```bash
+cat > ~/.octo/skills/hello-world/SKILL.md << 'EOF'
+---
+name: hello-world
+description: 'Use this skill when the user wants a greeting'
+---
+
+# Hello World Skill
+
+When invoked, greet the user warmly and ask how you can help today.
+EOF
+```
+
+## Step 3: Test It
+
+Start octo and invoke your skill:
+
+```bash
+$ octo
+> /hello-world
+```
+
+## Step 4: Iterate
+
+Refine the instructions based on how the agent behaves. Add more detail, examples, or constraints.
+
+## Step 5: Share (Optional)
+
+Skills are plain Markdown. Zip the directory and share it:
+
+```bash
+cd ~/.octo/skills && zip -r hello-world.zip hello-world/
+```
+
+Others can install it with `/skill-add hello-world.zip`.
+
+That's it — no compilation, no registration, no encryption keys.

data/lib/octo/default_skills/product-help/docs/faq.md

@@ -0,0 +1,98 @@
+# FAQ & Troubleshooting
+
+## General
+
+### Q: What models are supported?
+
+Any model speaking Anthropic Messages, OpenAI (Chat Completions / Responses), or AWS Bedrock protocols. Out-of-the-box presets include:
+
+- **Claude** (Anthropic)
+- **GPT** (OpenAI)
+- **DeepSeek**
+- **Kimi** (Moonshot)
+- **MiniMax**
+- **OpenRouter**
+- **AWS Bedrock**
+- **Qwen**
+- **GLM**
+
+### Q: Can I use a custom endpoint?
+
+Yes. Set `base_url` to any OpenAI-compatible or Anthropic-compatible endpoint.
+
+### Q: How do I update Octo?
+
+```bash
+gem update octo-agent
+```
+
+Or pull latest and `bundle install` if running from source.
+
+## Configuration
+
+### Q: Where is the config file stored?
+
+`~/.octo/config.yml`
+
+### Q: Can I have multiple models configured?
+
+Yes. The config supports multiple model entries with different types (default, lite, fallback).
+
+### Q: What if I don't have an API key?
+
+Octo requires your own API key (BYOK). Get one from your model provider (Anthropic, OpenAI, etc.).
+
+## Web UI
+
+### Q: What port does the web UI use?
+
+Default is `8888`. Change with `--port`.
+
+### Q: Can I access the web UI from another device?
+
+Use `--host 0.0.0.0` to listen on all interfaces.
+
+## Restart / Upgrade / Downgrade
+
+### Normal Restart
+
+```bash
+kill -USR1 $OCTO_MASTER_PID
+```
+
+This performs a hot restart with zero downtime.
+
+### Restart or Upgrade Failure
+
+If restart fails:
+1. Check if another process is using the port (`lsof -i :8888`)
+2. Kill the stale process and restart
+3. If issues persist, run `gem uninstall octo-agent && gem install octo-agent` for a clean reinstall
+
+### Downgrade
+
+```bash
+gem install octo-agent -v <desired-version>
+```
+
+## Session Management
+
+### Q: Where are sessions stored?
+
+`~/.octo/sessions/`
+
+### Q: How do I continue a previous session?
+
+```bash
+octo -c
+# or
+octo --continue
+```
+
+### Q: How do I list recent sessions?
+
+```bash
+octo -l
+# or
+octo --list
+```

data/lib/octo/default_skills/product-help/docs/how-to-use-a-skill.md

@@ -0,0 +1,58 @@
+# How to Use a Skill
+
+A **skill** is a Markdown instruction file that guides the agent to accomplish a specific task using existing tools.
+
+## Installing a Skill
+
+```bash
+/skill-add <zip-url-or-local-path>
+```
+
+Or place skill files manually:
+
+- **Project-level**: `.octo/skills/<skill-name>/SKILL.md`
+- **User-level**: `~/.octo/skills/<skill-name>/SKILL.md`
+
+## Invoking a Skill
+
+In an active session, type `/` followed by the skill name:
+
+```bash
+> /code-explorer
+```
+
+Use Tab or fuzzy search to find skills quickly.
+
+## Built-in Skills
+
+Octo ships with built-in skills for common tasks:
+
+- `browser-setup` — Configure Chrome/Edge for browser automation
+- `channel-manager` — Set up IM platform integrations
+- `code-explorer` — Analyze and explore codebases
+- `cron-task-creator` — Create scheduled automated tasks
+- `product-help` — Help with Octo features and configuration
+- And more — type `/` to see the full list
+
+## Skill Format
+
+A skill is a single `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: my-skill
+description: 'Use this skill when...'
+fork_agent: true
+user-invocable: true
+---
+
+# Skill Instructions
+
+Write detailed instructions here...
+```
+
+## Creating a Skill
+
+Describe what you want in natural language, and the agent can draft a `SKILL.md` for you.
+
+Skills are plain Markdown — no compilation, no encryption, no license keys.

data/lib/octo/default_skills/product-help/docs/installation.md

@@ -0,0 +1,59 @@
+# Installation
+
+## Requirements
+
+- Ruby >= 3.1.0
+
+## RubyGem
+
+```bash
+gem install octo-agent
+```
+
+## One-line Installer (macOS / Ubuntu)
+
+```bash
+/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/Leihb/octo/main/scripts/install.sh)"
+```
+
+## Windows
+
+```powershell
+powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/Leihb/octo/main/scripts/install.ps1')))"
+```
+
+## From Source
+
+```bash
+git clone https://github.com/Leihb/octo.git
+cd octo
+bundle install
+bin/octo
+```
+
+## After Installation
+
+Run `octo` to start an interactive agent session. On first run, configure your API key and model:
+
+```bash
+$ octo
+> /config
+```
+
+Set your **API Key**, **Model**, and **Base URL**. Octo routes each model to its native protocol automatically.
+
+## Environment Variables
+
+You can also configure via environment variables:
+
+| Variable | Description |
+|---|---|
+| `OCTO_API_KEY` | Default model API key |
+| `OCTO_BASE_URL` | Default model base URL |
+| `OCTO_MODEL` | Default model name |
+| `OCTO_ANTHROPIC_FORMAT` | Use anthropic format (true/false) |
+| `OCTO_LITE_API_KEY` | Lite model API key |
+| `OCTO_LITE_BASE_URL` | Lite model base URL |
+| `OCTO_LITE_MODEL` | Lite model name |
+
+Or use ClaudeCode-compatible variables: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`.

data/lib/octo/default_skills/product-help/docs/memory-system.md

@@ -0,0 +1,61 @@
+# Memory System
+
+Octo maintains **long-term memory** across sessions.
+
+## Storage Location
+
+```
+~/.octo/memories/
+```
+
+Memories are stored as Markdown files with YAML frontmatter.
+
+## How It Works
+
+- The agent automatically reads relevant memories at the start of a session
+- New information can be persisted to memory during a session
+- Memories are topic-organized and searchable
+
+## Manual Memory Management
+
+Use the `persist-memory` skill to save information:
+
+```bash
+> /persist-memory
+```
+
+Use the `recall-memory` skill to retrieve information:
+
+```bash
+> /recall-memory
+```
+
+## Disabling Memory
+
+When starting the web server:
+
+```bash
+octo server --no-memory
+```
+
+## Memory Files
+
+Each memory file contains:
+
+```yaml
+---
+topics:
+  - topic-name
+created_at: 2026-01-01
+type: factual
+---
+
+Content here...
+```
+
+## Scope
+
+- **User-level**: `~/.octo/memories/` — Shared across all projects
+- **Project-level**: `.octo/memories/` — Project-specific
+
+The agent loads both scopes and merges them by relevance.

data/lib/octo/default_skills/product-help/docs/octorules.md

@@ -0,0 +1,62 @@
+# Project Rules (.octorules)
+
+The `.octorules` file contains project-specific instructions for the agent.
+
+## Location
+
+Place `.octorules` in your project root:
+
+```
+my-project/
+  .octorules
+  src/
+  ...
+```
+
+## Format
+
+A Markdown file with sections:
+
+```markdown
+# Project Rules
+
+## Overview
+
+This is a Ruby on Rails API project...
+
+## Architecture
+
+- Models in app/models/
+- Controllers in app/controllers/
+- Services in app/services/
+
+## Code Style
+
+- Use frozen_string_literal: true
+- Single quotes for strings without interpolation
+- Max line length: 100
+
+## Testing
+
+- RSpec for tests
+- Run `bundle exec rspec` before committing
+```
+
+## What to Include
+
+- Project overview and tech stack
+- Architecture conventions
+- Code style guidelines
+- Testing requirements
+- Security considerations
+- Deployment notes
+
+## How It Works
+
+When you run `octo` in a directory containing `.octorules`, the agent reads this file and incorporates the instructions into its context. This ensures consistent behavior across sessions for the same project.
+
+## User-Level Rules
+
+You can also place `.octorules` in `~/.octo/` for global defaults that apply to all projects.
+
+Project-level rules override user-level rules when there are conflicts.

data/lib/octo/default_skills/product-help/docs/session-management.md

@@ -0,0 +1,63 @@
+# Session Management
+
+## Starting a Session
+
+```bash
+octo
+```
+
+## Continuing a Session
+
+```bash
+octo -c
+octo --continue
+```
+
+## Listing Sessions
+
+```bash
+octo -l
+octo --list
+```
+
+## Attaching to a Specific Session
+
+```bash
+octo -a 2          # By number
+octo -a b6682a87   # By session ID prefix
+```
+
+## Storage
+
+Sessions are stored in:
+
+```
+~/.octo/sessions/
+```
+
+Each session is a Markdown file with conversation history and metadata.
+
+## Session Files
+
+Sessions are chunked and organized by date:
+
+```
+~/.octo/sessions/
+  2026-05-25/
+    session-id-1.md
+    session-id-2.md
+```
+
+## Web UI Sessions
+
+The web UI supports multiple concurrent sessions. Each browser tab can have its own independent session.
+
+## Session Limits
+
+- Context window depends on the model being used
+- Older messages may be compressed to fit within token limits
+- Use `--no-compression` to disable compression (saves tokens but may lose context)
+
+## Cleanup
+
+Sessions are kept indefinitely. To clean up old sessions, manually remove files from `~/.octo/sessions/`.

data/lib/octo/default_skills/product-help/docs/skill-basics.md

@@ -0,0 +1,55 @@
+# Skill Basics
+
+A **skill** is a Markdown file that teaches the agent how to perform a specific task.
+
+## File Structure
+
+```
+.skills/my-skill/
+  SKILL.md
+```
+
+Or at project/user level:
+
+```
+.octo/skills/my-skill/SKILL.md
+~/.octo/skills/my-skill/SKILL.md
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: my-skill
+description: 'Use this skill when...'
+fork_agent: true
+user-invocable: true
+---
+
+# Instructions
+
+Detailed instructions for the agent...
+```
+
+## Frontmatter Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Skill identifier |
+| `description` | string | When to trigger this skill (auto-matching) |
+| `fork_agent` | boolean | Run in a subagent (default: false) |
+| `user-invocable` | boolean | Allow `/skill-name` invocation (default: true) |
+| `auto_summarize` | boolean | Auto-summarize results |
+| `forbidden_tools` | array | Tool names the skill cannot use |
+
+## Invocation
+
+- **Auto-trigger**: Agent matches user intent against `description`
+- **Manual**: `/skill-name` in chat
+
+## Best Practices
+
+- Write `description` as a natural language trigger condition
+- Use `fork_agent: true` for complex tasks to isolate context
+- Keep instructions concrete and actionable
+- Test skills by invoking them directly

data/lib/octo/default_skills/product-help/docs/skill-frontmatter.md

@@ -0,0 +1,61 @@
+# SKILL.md Frontmatter Reference
+
+All frontmatter fields for `SKILL.md`:
+
+## Required Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Skill identifier (kebab-case recommended) |
+| `description` | string | Natural language trigger condition |
+
+## Optional Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `fork_agent` | boolean | false | Run in a subagent with isolated context |
+| `user-invocable` | boolean | true | Allow `/skill-name` manual invocation |
+| `auto_summarize` | boolean | false | Automatically summarize results |
+| `forbidden_tools` | array | [] | Tool names the skill cannot use |
+
+## Example
+
+```yaml
+---
+name: code-explorer
+description: 'Use this skill when exploring, analyzing, or understanding project/code structure'
+fork_agent: true
+user-invocable: true
+auto_summarize: true
+forbidden_tools:
+  - write
+  - edit
+  - terminal
+---
+```
+
+## Trigger Matching
+
+The `description` field is matched against user intent using semantic similarity. Write it as a condition:
+
+```yaml
+description: 'Use this skill when the user asks about browser setup, Chrome configuration, or Edge automation'
+```
+
+## fork_agent Behavior
+
+When `fork_agent: true`:
+- A new subagent is spawned
+- The subagent gets a fresh context
+- Results are summarized back to the parent session
+- Prevents long skill executions from polluting main session context
+
+## forbidden_tools
+
+Common values:
+
+- `write` — Cannot create files
+- `edit` — Cannot modify files
+- `terminal` — Cannot run shell commands
+- `web_search` — Cannot search the web
+- `browser` — Cannot control browser

data/lib/octo/default_skills/product-help/docs/web-server.md

@@ -0,0 +1,49 @@
+# Web UI
+
+Start the Octo web interface:
+
+```bash
+octo server
+```
+
+Default address: **http://localhost:8888**
+
+## Options
+
+```bash
+octo server --port 8080        # Custom port
+octo server --host 0.0.0.0     # Listen on all interfaces
+octo server --no-compression   # Disable message compression
+octo server --no-memory        # Disable automatic memory updates
+octo server --no-caching       # Disable prompt caching
+octo server --no-skill-evolution  # Disable automatic skill evolution
+```
+
+## Features
+
+- Full chat interface with markdown rendering
+- Multi-session support
+- File attachments (images, documents)
+- Session history browser
+- Real-time streaming responses
+
+## API Endpoints
+
+The web server exposes a REST API for programmatic access:
+
+- `POST /api/sessions` — Create a new session
+- `POST /api/sessions/:id/chat` — Send a message
+- `GET /api/sessions/:id` — Get session info
+- `DELETE /api/sessions/:id` — End a session
+
+## Security
+
+By default, the server binds to `127.0.0.1` (localhost only). Use `--host 0.0.0.0` with caution — there is no built-in authentication.
+
+## Hot Restart
+
+Send `USR1` to the master process for zero-downtime restart:
+
+```bash
+kill -USR1 $OCTO_MASTER_PID
+```

data/lib/octo/default_skills/product-help/docs/what-is-octo.md

@@ -0,0 +1,37 @@
+# What is Octo
+
+Octo is a **functionality-first** AI agent with three equal interfaces:
+
+- **Terminal (CLI)** — Interactive agent sessions in your shell
+- **Web UI** — Full chat interface with multi-session support at `localhost:8888`
+- **Instant Messaging** — Feishu, WeChat, WeCom, Discord, Telegram
+
+All three interfaces are first-class citizens with identical capabilities.
+
+## Core Protocols
+
+Octo speaks three API protocols natively:
+
+1. **Anthropic Messages** — Claude models with full `cache_control` fidelity
+2. **OpenAI** — Chat Completions + Responses API
+3. **AWS Bedrock** — Claude via AWS
+
+Any provider exposing one of these shapes works out of the box.
+
+## Key Features
+
+| Feature | Description |
+|---|---|
+| **Skills** | Installable capability packs in Markdown format |
+| **Autonomous Agent** | ReAct pattern with tool execution |
+| **BYOK** | Bring your own API key for any compatible model |
+| **Session Management** | Persistent conversation history |
+| **Memory** | Long-term memory across sessions |
+
+## What Octo Is Not
+
+- Not a token-minimization obsession — functionality comes first
+- Not web-first — local CLI usage has no master-worker overhead
+- Not a marketplace — skills are open Markdown, not encrypted binaries
+
+Octo is a hard fork of [clacky-ai/openclacky](https://github.com/clacky-ai/openclacky).

data/lib/octo/default_skills/product-help/docs/windows-installation.md

@@ -0,0 +1,36 @@
+# Windows Installation
+
+## PowerShell One-liner
+
+```powershell
+powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/Leihb/octo/main/scripts/install.ps1')))"
+```
+
+## Manual Installation
+
+1. Install Ruby >= 3.1.0 from [rubyinstaller.org](https://rubyinstaller.org/)
+2. Open PowerShell or Command Prompt
+3. Run:
+
+```powershell
+gem install octo-agent
+```
+
+## WSL (Recommended)
+
+For the best experience on Windows, use WSL2:
+
+```bash
+# In WSL terminal
+/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/Leihb/octo/main/scripts/install.sh)"
+```
+
+Browser automation and most features work best under WSL or native Linux/macOS.
+
+## After Installation
+
+```bash
+octo
+```
+
+Configure your API key on first run via `> /config`.