### Setup docx-js for Document Creation

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/docx/SKILL.md

Imports necessary components from the 'docx' library and initializes a new Document. Installs via 'npm install -g docx'.

```javascript
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
        TabStopType, TabStopPosition, Column, SectionType,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* content */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
```

--------------------------------

### Python Dependency Check Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/15-core-skills-system.md

Demonstrates how to check for Python package installation using `python3 -c`. This is used to verify if a required package is available in the environment.

```python
# One-liner per import, run with PYTHONPATH=scriptsDir
python3 -c "import openpyxl"   # success = installed
python3 -c "import missing_pkg" # exit 1 = missing
```

--------------------------------

### Full Plugin Marketplace Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/plugin-marketplace-schema.md

Provides a comprehensive example of a marketplace configuration including metadata and multiple plugins with different source types.

```json
{
  "name": "company-tools",
  "owner": { "name": "DevTools Team", "email": "devtools@example.com" },
  "metadata": { "description": "Internal dev tools", "version": "1.0.0", "pluginRoot": "./plugins" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": { "name": "DevTools Team" }
    },
    {
      "name": "deployment-tools",
      "source": { "source": "github", "repo": "company/deploy-plugin" },
      "description": "Deployment automation tools"
    }
  ]
}
```

--------------------------------

### Node.js Dependency Check Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/15-core-skills-system.md

Shows how to verify Node.js module installation using `node -e` and `require.resolve`. This confirms if a specific npm package is accessible.

```javascript
// cmd.Dir = scriptsDir
node -e "require.resolve('marked')"  // success = installed
```

--------------------------------

### Local Configuration Examples

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/internal/bootstrap/templates/TOOLS.md

Examples of local configurations for cameras, SSH, and TTS. These are environment-specific notes that complement shared skills.

```markdown
### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod
```

--------------------------------

### Install Dependencies

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/skill-creation-workflow.md

Commands to install Python or Node.js packages if dependencies are missing after publishing a skill.

```bash
pip3 install <pkg>        # Python packages
```

```bash
npm install -g <pkg>      # Node.js packages
```

--------------------------------

### Error Handling Example for Connection Failure

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/writing-effective-instructions.md

Illustrates how to include error handling instructions, specifically for a 'Connection refused' error, by providing a step-by-step troubleshooting guide.

```markdown
## Common Issues
### MCP Connection Failed
If "Connection refused":
1. Verify MCP server running: Settings > Extensions
2. Confirm API key valid
3. Reconnect: Settings > Extensions > [Service] > Reconnect
```

--------------------------------

### Local Marketplace Walkthrough

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/plugin-marketplace-overview.md

Steps to set up, add, install, and test a local plugin marketplace. This includes creating the necessary directory structure and files, adding the marketplace, and installing a plugin.

```bash
# 1. Create structure
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/skills/review

# 2. Create skill (SKILL.md), plugin manifest (plugin.json), marketplace catalog (marketplace.json)

# 3. Add and install
/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-plugins

# 4. Test
/review
```

--------------------------------

### SnapshotWorker Usage

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/10-tracing-observability.md

Example Go code for initializing, starting, and stopping the SnapshotWorker.

```APIDOC
## SnapshotWorker Usage

```go
worker := tracing.NewSnapshotWorker(db, snapshotStore)
worker.Start()

// Later:
hoursBackfilled, err := worker.Backfill(ctx)
worker.Stop()
```
```

--------------------------------

### SKILL.md Structure Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/writing-effective-instructions.md

Provides a recommended structure for SKILL.md files, including metadata, instructions, examples, and troubleshooting sections.

```markdown
---
name: your-skill  # optional namespace: ck:your-skill
description: [What + When + Key capabilities]
---
# Skill Name
## Instructions
### Step 1: [First Major Step]
Clear explanation. Example with expected output.
### Step 2: [Next Step]
(Continue as needed)
## Examples
### Example 1: [Common scenario]
**User says:** "[trigger phrase]"
**Actions:** 1. Do X  2. Do Y
**Result:** [Expected outcome]
## Troubleshooting
**Error:** [Message] → **Solution:** [Fix]
```

--------------------------------

### Vault Link Tool Example Call

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/24-knowledge-vault.md

Example agent interaction with the vault_link tool to connect an authentication guide to the SOUL file, providing a context description.

```text
Agent: "Link the authentication guide to the SOUL file"
Tool call: vault_link(from="docs/auth.md", to="SOUL.md", context="Persona reference")
Result: Explicit link created in vault_links
```

--------------------------------

### Start GoClaw with Docker

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/README.md

Starts the GoClaw services using Docker. This command generates a .env file, requires API keys, and starts the web dashboard.

```bash
# Generate .env with auto-generated secrets
chmod +x prepare-env.sh && ./prepare-env.sh

# Add at least one GOCLAW_*_API_KEY to .env, then:
make up

# Web Dashboard at http://localhost:18790 (built-in)
# Health check: curl http://localhost:18790/health

# Optional: separate nginx for custom SSL/reverse proxy
# make up WITH_WEB_NGINX=1  → Dashboard at http://localhost:3000
```

--------------------------------

### Build and Start GoClaw Gateway

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/23-multi-tenant-architecture.md

Build the GoClaw executable and start the gateway. Ensure to source your environment variables first. Access the dashboard via HTTP.

```bash
# 1. Build and onboard
go build -o goclaw .
./goclaw onboard

# 2. Start the gateway
source .env.local && ./goclaw

# 3. Open dashboard at http://localhost:3777
#    Log in with your gateway token + user ID "system"
```

--------------------------------

### Develop Goclaw Web Dashboard

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/CLAUDE.md

Installs dependencies and starts the development server for the Goclaw web dashboard. This provides a local environment for UI development with hot reloading.

```bash
cd ui/web
pnpm install
pnpm dev
```

--------------------------------

### Install Packages at Runtime

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/script-quality-criteria.md

Install Python or Node.js packages at runtime within the GoClaw container. Packages are installed to persistent volumes and do not require sudo privileges.

```bash
pip3 install <package>        # installs to PIP_TARGET, persists in volume
npm install -g <package>      # installs to NPM_CONFIG_PREFIX, persists in volume
```

--------------------------------

### Install Single Dependency

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/15-core-skills-system.md

Installs a single specified dependency and broadcasts WebSocket events related to the installation process.

```APIDOC
## POST /v1/skills/install-dep

### Description
Installs a single dependency and broadcasts related WebSocket events.

### Method
POST

### Endpoint
/v1/skills/install-dep

### Parameters
#### Request Body
- **dep** (string) - Required - The name of the dependency to install.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the single dependency installation has started.

#### Response Example
```json
{
  "message": "Installation of dependency 'some-package' initiated."
}
```
```

--------------------------------

### Install GoClaw Lite on Windows

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/README.md

Installs the GoClaw Desktop Edition on Windows using PowerShell to download and execute an installation script.

```powershell
irm https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install-lite.ps1 | iex
```

--------------------------------

### Install Plugin from Local Marketplace

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/plugin-marketplace-hosting.md

Install a specific plugin from a locally added marketplace. This command allows you to test plugins directly from your development environment.

```shell
/plugin install test-plugin@my-local-marketplace
```

--------------------------------

### Cleanup Unused Example Files

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/structure-organization-criteria.md

After initializing a skill, remove any unused example files from the scripts/, references/, and assets/ directories to maintain a clean project structure.

```bash
rm -f scripts/example.py
rm -f references/api_reference.md
rm -f assets/example_asset.txt
```

--------------------------------

### Test Local Plugin Installation

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/plugin-marketplace-overview.md

Commands to test a local plugin before distribution. This involves adding the local marketplace and then installing a plugin from it.

```bash
# Test locally before distribution
/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace
```

--------------------------------

### Example Manifest for End-of-Task Summary

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/workspace-organizing/SKILL.md

This example shows the format for summarizing created files, deliverables, and related Vault documents or KG entities after a complex task.

```markdown
Created:
- projects/q2-forecast/reports/forecast-summary.md   
- projects/q2-forecast/assets/forecast-chart.png     
- projects/q2-forecast/source/build-chart.py         
- projects/q2-forecast/research/raw-sales-2026.csv   
Related (existing): [[2026-q1-forecast]], KG entity "Sales Team"
```

--------------------------------

### Manually Start Backup Service

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/deployment-guide.md

Initiate a manual backup process by starting the backup service. This is useful for on-demand backups outside the regular schedule.

```bash
sudo systemctl start goclaw-backup-r2.service
```

--------------------------------

### Configure Auto-Prompt Marketplace Install

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/plugin-marketplace-hosting.md

Add this JSON configuration to your `.claude/settings.json` file to define custom marketplaces that users will be prompted to install. This allows for centralized management of plugin sources.

```json
{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  }
}
```

--------------------------------

### Start GoClaw with Optional Docker Services

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/README.md

Starts GoClaw services with additional optional features enabled via environment flags, such as browser automation, tracing, or a sandbox environment.

```bash
# Start with browser automation and tracing
make up WITH_BROWSER=1 WITH_OTEL=1
```

--------------------------------

### Install Package Request

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Initiates the installation of a package. The package name can specify the manager (e.g., "pip:pandas") or default to system (apk). Validation ensures package names adhere to specific patterns to prevent injection.

```http
POST /v1/packages/install
```

```json
{
  "package": "github-cli"
}
```

--------------------------------

### Sequential Workflow Orchestration Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/skill-design-patterns.md

Illustrates a multi-step workflow for onboarding a new customer, showing explicit step ordering and tool calls.

```markdown
## Workflow: Onboard New Customer
### Step 1: Create Account
Call MCP tool: `create_customer` → Parameters: name, email, company
### Step 2: Setup Payment
Call MCP tool: `setup_payment_method` → Wait for verification
### Step 3: Create Subscription
Call MCP tool: `create_subscription` → Uses customer_id from Step 1
```

--------------------------------

### Setup and Basic Presentation

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/pptx/pptxgenjs.md

Initializes PptxGenJS, sets presentation properties, adds a slide with text, and saves the presentation to a file.

```javascript
const pptxgen = require("pptxgenjs");

let pres = new pptxgen();
pres.layout = 'LAYOUT_16x9';  // or 'LAYOUT_16x10', 'LAYOUT_4x3', 'LAYOUT_WIDE'
pres.author = 'Your Name';
pres.title = 'Presentation Title';

let slide = pres.addSlide();
slide.addText("Hello World!", { x: 0.5, y: 0.5, fontSize: 36, color: "363636" });

pres.writeFile({ fileName: "Presentation.pptx" });
```

--------------------------------

### List Voices Response

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example response for the GET /v1/voices endpoint, detailing available voice configurations.

```json
[
  {
    "voice_id": "pMsXgVXv3BLzUgSXRplE",
    "name": "Alice",
    "preview_url": "https://...",
    "category": "premade",
    "labels": {
      "use_case": "conversational",
      "accent": "american"
    }
  }
]
```

--------------------------------

### Provider Quota Response

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example response for quota endpoints (e.g., GET /v1/auth/chatgpt/{provider}/quota), detailing usage and reset times.

```json
{
  "provider_name": "openai-codex",
  "success": true,
  "plan_type": "team",
  "windows": [
    {
      "label": "Primary",
      "used_percent": 24,
      "remaining_percent": 76,
      "reset_after_seconds": 3600,
      "reset_at": "2026-03-24T20:15:00Z"
    }
  ],
  "core_usage": {
    "five_hour": {
      "label": "Primary",
      "remaining_percent": 76,
      "reset_after_seconds": 3600,
      "reset_at": "2026-03-24T20:15:00Z"
    },
    "weekly": {
      "label": "Secondary",
      "remaining_percent": 62,
      "reset_after_seconds": 604800,
      "reset_at": "2026-03-31T19:15:00Z"
    }
  },
  "last_updated": "2026-03-24T19:15:00Z"
}
```

--------------------------------

### Get Known Users in a Team Request

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/19-websocket-rpc.md

Example request payload for retrieving a list of known user IDs within a specific team.

```json
{teamId}
```

--------------------------------

### Minimal Plugin Marketplace Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/plugin-marketplace-schema.md

Demonstrates the basic structure for a marketplace configuration with a single plugin.

```json
{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [{
    "name": "review-plugin",
    "source": "./plugins/review-plugin",
    "description": "Adds a review skill for quick code reviews"
  }]
}
```

--------------------------------

### Build and Run Goclaw Application

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/CLAUDE.md

Builds the Goclaw executable, onboards the application, sources environment variables, and then runs the application. Use this for initial setup and running the main application.

```bash
go build -o goclaw .
./goclaw onboard
source .env.local
./goclaw
```

--------------------------------

### Specific Instruction Example with Validation

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/writing-effective-instructions.md

Demonstrates how to provide specific, actionable instructions for running a validation script, including common error scenarios and their solutions.

```markdown
Run `python scripts/validate.py --input {filename}` to check format.
If validation fails, common issues:
- Missing required fields (add to CSV)
- Invalid date formats (use YYYY-MM-DD)
```

--------------------------------

### Referencing Bundled Resources

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/writing-effective-instructions.md

Shows how to clearly reference bundled resources, such as API pattern documentation, to guide users on best practices before they start writing queries.

```markdown
Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling
```

--------------------------------

### Gateway Startup Sequence Diagram

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/00-architecture-overview.md

Visualizes the step-by-step process of the GoClaw gateway starting up, from parsing CLI flags to listening on host:port.

```mermaid
sequenceDiagram
    participant CLI as CLI (cmd/root.go)
    participant GW as runGateway()
    participant PG as PostgreSQL
    participant Engine as Core Engine

    CLI->>GW: 1. Parse CLI flags + load config
    GW->>GW: 2. Resolve workspace + data dirs
    GW->>GW: 3. Create Message Bus

    GW->>PG: 4. Connect to Postgres (pg.NewPGStores)
    PG-->>GW: PG stores created
    GW->>GW: 5. Start tracing collector
    GW->>PG: 6. Register providers from DB
    GW->>PG: 7. Wire embedding provider to PGMemoryStore
    GW->>PG: 8. Backfill memory embeddings (background)

    GW->>GW: 9. Register config-based providers
    GW->>GW: 10. Create tool registry (filesystem, exec, web, memory, browser, TTS, subagent, MCP)
    GW->>GW: 11. Load bootstrap files (DB)
    GW->>GW: 12. Create skills loader + register skill_search tool
    GW->>GW: 13. Wire skill embeddings

    GW->>GW: 14. Create agents lazily (set ManagedResolver)
    GW->>GW: 15. wireManagedExtras (interceptors, cache subscribers)
    GW->>GW: 16. Wire managed HTTP handlers (agents, skills, traces, MCP)

    GW->>Engine: 17. Create gateway server (WS + HTTP)
    GW->>Engine: 18. Register RPC methods
    GW->>Engine: 19. Register + start channels (Telegram, Discord, Feishu, Zalo, WhatsApp)
    GW->>Engine: 20. Start cron, scheduler (4 lanes)
    GW->>Engine: 21. Start skills watcher + inbound consumer
    GW->>Engine: 22. Listen on host:port
```

--------------------------------

### Initializing a New Skill

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/16-skill-publishing.md

Use this script to set up the initial directory structure and basic files for a new skill.

```python
scripts/init_skill.py <name> --path <dir>
```

--------------------------------

### DelegationEventPayload Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/13-ws-team-events.md

Payload for delegation lifecycle events like started, completed, failed, or cancelled. Includes details about the delegation, agents involved, and associated chat/task information.

```json
{
  "delegation_id": "a1b2c3d4",
  "source_agent_id": "<source-agent-id>",
  "source_agent_key": "default",
  "source_display_name": "Default Agent",
  "target_agent_id": "<target-agent-id>",
  "target_agent_key": "content-writer",
  "target_display_name": "Content Writer",
  "user_id": "<user-id>",
  "channel": "telegram",
  "chat_id": "<chat-id>",
  "mode": "async",
  "task": "Create Instagram image",
  "team_id": "<team-id>",
  "team_task_id": "<team-task-id>",
  "status": "running",
  "created_at": "2026-03-05T10:00:00Z"
}
```

--------------------------------

### List Installed Packages

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/packages-github.md

Retrieves a list of all installed packages, including those installed from GitHub, pip, npm, and the system.

```APIDOC
## GET /v1/packages

### Description
Lists all installed packages.

### Method
GET

### Endpoint
/v1/packages

### Response
#### Success Response (200)
- **packages** (array) - A list of installed packages.
  - Each package object may contain details like `name`, `version`, `source`, etc.

#### Response Example
```json
{
  "packages": [
    {
      "name": "github:lazygit",
      "version": "v0.42.0"
    },
    {
      "name": "pip:requests",
      "version": "2.28.1"
    }
  ]
}
```
```

--------------------------------

### Example GitHub CLI Configuration

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/20-api-keys-auth.md

This JSON object shows a sample configuration for the GitHub CLI, including environment variables, deny patterns, and tips for agent usage.

```json
{
  "binary_name": "gh",
  "binary_path": "/usr/local/bin/gh",
  "description": "GitHub CLI for PRs and issues",
  "encrypted_env": {
    "GH_TOKEN": "ghp_xxxxxxxxxxxx"
  },
  "deny_args": ["auth", "logout"],
  "deny_verbose": ["--verbose", "-v"],
  "timeout_seconds": 60,
  "tips": "Use 'gh pr list' to search PRs, 'gh issue create' to open issues. Avoid 'auth' and 'logout' commands.",
  "agent_id": null
}
```

--------------------------------

### Manual Testing Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/script-quality-criteria.md

Perform manual testing of scripts with real use cases before packaging. Verify the script's output against expected results.

```bash
# Example: PDF rotation script
python scripts/rotate_pdf.py input.pdf 90 output.pdf
```

--------------------------------

### Install GoClaw Lite on macOS

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/README.md

Installs the GoClaw Desktop Edition on macOS using a curl command to download and execute an installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install-lite.sh | bash
```

--------------------------------

### Discovery Workflow Before Writing

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/workspace-organizing/SKILL.md

Illustrates the recommended search and discovery process before creating new files to avoid duplication and ensure proper routing of information.

```text
# Discovery before writing
vault_search → doc_id   → vault_read
             → entity_id → knowledge_graph_search
             → episodic_id → memory_expand
memory_search (match language)
knowledge_graph_search (entities + relationships)
```

--------------------------------

### Install New Package Command

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/packages-apk.md

This command is used to install a new package, which may also install its dependencies. It is part of the package management operations.

```bash
apk add <name>
```

--------------------------------

### Go Skill Loader Startup Flow

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/15-core-skills-system.md

Illustrates the sequence of operations during the GoClaw gateway's skill loader startup, including scanning, seeding, dependency checking, and file watching.

```go
cmd/gateway.go  NewSkillLoader()
       │
       ▼
internal/skills/loader.go  NewLoader(baseDir, db)
       │  ── scans filesystem skill dirs
       │  ── wires managed DB directory
       │  ── calls BumpVersion() → invalidates list cache
       │
       ▼
internal/skills/seeder.go  Seed(ctx, db, embedFS, baseDir)
       │
       ├─ For each bundled skill in embed.FS (skills/*/SKILL.md):
       │     1. Read SKILL.md → parse YAML frontmatter (name, slug, description, author, ...)
       │     2. Compute SHA-256 of content → FileHash
       │     3. Call GetNextVersion(slug) → next DB version number
       │     4. UpsertSystemSkill(ctx, params) ──► see §4
       │     5. Copy skill files to baseDir/<slug>/<version>/
       │
       ├─ CheckDepsAsync(ctx, seededSlugs, baseDir, skillStore, broadcaster)
       │     └─ goroutine (non-blocking):
       │           for each slug:
       │             broadcast EventSkillDepsChecking {slug}
       │             ScanSkillDeps(skillDir) → manifest
       │             CheckSkillDeps(manifest) → (ok, missing[])
       │             StoreMissingDeps(id, missing) → UPDATE skills SET deps=...
       │             if !ok: UpdateSkill(id, {status: "archived"})
       │             else:   UpdateSkill(id, {status: "active"})
       │             broadcast EventSkillDepsChecked {slug, ok, missing}
       │
       └─ Register file watcher (500ms debounce) → on SKILL.md change: re-seed + BumpVersion
```

--------------------------------

### Create Goclaw Desktop DMG Installer

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/CLAUDE.md

Creates a DMG disk image installer for the Goclaw desktop application on macOS. Specify the version number for the installer.

```bash
make desktop-dmg VERSION=0.1.0
```

--------------------------------

### Build GoClaw Desktop from Source

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/README.md

Builds the GoClaw Desktop application from source. Ensure you have Go 1.26+, pnpm, and the Wails CLI installed.

```bash
# Prerequisites: Go 1.26+, pnpm, Wails CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest)
make desktop-build                    # Build .app (macOS) or .exe (Windows)
make desktop-dmg VERSION=0.1.0        # Create .dmg installer (macOS only)
make desktop-dev                      # Dev mode with hot reload
```

--------------------------------

### Create Desktop Release Tags

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/CLAUDE.md

Create and push Git tags for stable or beta desktop releases.

```bash
git tag lite-v1.1.0 && git push origin lite-v1.1.0   # stable
git tag lite-v1.1.0-beta.1 && git push origin lite-v1.1.0-beta.1  # beta (prerelease)
```

--------------------------------

### Example .env.example File

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/script-quality-criteria.md

Define required environment variables for a script. List variables without their values.

```dotenv
API_KEY=
DATABASE_URL=
DEBUG=false
```

--------------------------------

### List installed packages via HTTP API

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/packages-github.md

Retrieve a list of all installed packages, including those installed via pip, npm, system, and GitHub binaries, using the HTTP API.

```bash
# List installed (includes pip/npm/system + github)
curl http://gateway/v1/packages -H "Authorization: Bearer $ADMIN_TOKEN"
```

--------------------------------

### Good Description Example (YAML)

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/metadata-quality-criteria.md

Use this format for a clear, action-oriented description that includes specific use cases and trigger contexts.

```yaml
description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense, lazy loading, performance optimization.
```

```yaml
description: Process PDFs with rotation, splitting, merging. Use for document manipulation, page extraction, PDF conversion.
```

--------------------------------

### Follow Trace Response Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example JSON response structure for the `/v1/traces/follow` endpoint.

```json
{
  "traces": [],
  "spans_by_trace_id": {},
  "server_time": "2026-05-20T11:23:00Z",
  "next_since": "2026-05-20T11:23:00Z",
  "limit": 50
}
```

--------------------------------

### Install Package

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/packages-github.md

Installs a specified package from GitHub Releases. The package format is `owner/repo[@tag]`.

```APIDOC
## POST /v1/packages/install

### Description
Installs a package from GitHub Releases.

### Method
POST

### Endpoint
/v1/packages/install

### Parameters
#### Request Body
- **package** (string) - Required - The package to install, in the format `owner/repo[@tag]`.

### Request Example
```json
{
  "package": "github:jesseduffield/lazygit@v0.42.0"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of successful installation.

#### Response Example
```json
{
  "message": "Package installed successfully"
}
```
```

--------------------------------

### Publish Skill Tool Call

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/16-skill-publishing.md

Example of calling the `publish_skill` tool with the path to a skill directory. This tool registers the skill in the database and copies its files to a managed store.

```go
publish_skill(path: "skills/my-skill")
```

--------------------------------

### Configuration Loading Flow

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/00-architecture-overview.md

Illustrates the configuration loading process, from identifying the config path to applying defaults and environment variable overlays.

```mermaid
flowchart TD
    A{Config path?} -->|--config flag| B[CLI flag path]
    A -->|GOCLAW_CONFIG env| C[Env var path]
    A -->|default| D["config.json"]

    B & C & D --> LOAD["config.Load()"]
    LOAD --> S1["1. Set defaults"]
    S1 --> S2["2. Parse JSON5"]
    S2 --> S3["3. Env var overlay<br/>(GOCLAW_*_API_KEY)"]
    S3 --> S4["4. Apply computed defaults<br/>(context pruning, etc.)"]
    S4 --> READY[Config ready]
```

--------------------------------

### NPM Update Install Command

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/packages-pip-npm.md

Command to install a specific version of a global npm package.

```bash
npm install --global <name>@<version>
```

--------------------------------

### Install Missing Dependencies (Bulk)

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/15-core-skills-system.md

Installs all identified missing dependencies for skills in a bulk operation.

```APIDOC
## POST /v1/skills/install-deps

### Description
Installs all missing dependencies for skills in a bulk operation.

### Method
POST

### Endpoint
/v1/skills/install-deps

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the bulk installation has started.

#### Response Example
```json
{
  "message": "Bulk installation of missing dependencies initiated."
}
```
```

--------------------------------

### Agent Orchestration Mode Response Example (Team)

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example JSON response for an agent in 'team' orchestration mode.

```json
{
  "mode": "team",
  "delegate_targets": [],
  "team": {
    "id": "uuid",
    "name": "Platform Team"
  }
}
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/15-core-skills-system.md

Shows the YAML frontmatter format for SKILL.md files, including required fields like name, slug, and description, along with optional tags.

```yaml
---
name: pdf
description: Use this skill whenever the user wants to do anything with PDF files...
author: GoClaw Team
tags: [pdf, document]
---

## Instructions

(Skill body used as system prompt injection)
```

--------------------------------

### Agent Orchestration Mode Response Example (Delegate)

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example JSON response for an agent in 'delegate' orchestration mode.

```json
{
  "mode": "delegate",
  "delegate_targets": [
    {
      "agent_key": "research-agent",
      "display_name": "Research Specialist"
    }
  ],
  "team": null
}
```

--------------------------------

### Usage Cap Policy Request Body Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example JSON body for creating or updating a usage cap policy.

```json
{
  "agent_id": "optional-agent-uuid",
  "provider_id": "optional-provider-uuid",
  "provider_type": "openrouter",
  "model_id": "anthropic/claude-sonnet-4-5",
  "window": "day",
  "max_tokens": 500000,
  "max_cost_usd": 25,
  "enabled": true
}
```

--------------------------------

### Description Optimization Examples

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/SKILL.md

Illustrates the difference between undertriggering and effective, pushy descriptions for skill auto-activation.

```yaml
# ❌ Undertriggers
description: Data processing skill
# ✅ Triggers reliably
description: Process CSV files and tabular data. Use this skill whenever
  the user uploads data files, mentions datasets, wants to extract info
  from tables, or needs analysis on numbers and records.
```

--------------------------------

### Agent V3 Flags Response Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example JSON response showing the enabled/disabled status of various v3 features for an agent.

```json
{
  "evolution_enabled": true,
  "episodic_enabled": true,
  "vault_enabled": true,
  "orchestration_enabled": false,
  "skill_evolve": true,
  "self_evolve": false
}
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/skills/skill-creator/references/skill-anatomy-and-requirements.md

Defines the required and optional metadata for a SKILL.md file, including name, description, license, compatibility, and allowed tools.

```yaml
---
name: skill-name          # required — must be kebab-case, match directory name
description: Under 1024 chars, specific triggers and use cases  # required
license: Optional         # optional
compatibility: Optional   # optional, environment requirements
metadata:                 # optional, arbitrary key-value pairs
  author: Author Name
  version: "1.0"
allowed-tools: "Bash(python3:*) Bash(node:*)"  # optional, experimental
---
```

--------------------------------

### Agent V3 Flags Update Request Example

Source: https://github.com/nextlevelbuilder/goclaw/blob/dev/docs/18-http-api.md

Example JSON request body for updating specific v3 feature flags for an agent.

```json
{
  "evolution_enabled": true,
  "episodic_enabled": false,
  "vault_enabled": true
}
```