From 0d5f159dc7dbddb7679f1b4a146fb1ac245d9da5 Mon Sep 17 00:00:00 2001 From: Bruno Clermont Date: Fri, 12 Jun 2026 23:03:20 -0400 Subject: [PATCH] docs(goclaw-skill): complete reference documentation - Add 20 new reference files documenting all missing goclaw CLI commands: * backup-restore.md (system/tenant backup, restore, preflight) * webhooks.md (inbound HTTP callbacks) * hooks.md (internal event routing, separate from webhooks) * vault.md (Knowledge Vault: documents, search, enrichment) * voices.md (voice catalog for TTS) * workstations.md (coding-agent isolated environments) * edition.md (server edition & feature availability) * quota.md (quota inspection: token usage) * users.md (user search & discovery) * oauth.md (OAuth authentication: ChatGPT, OpenAI) * profile.md (CLI connection profiles, separate from auth) * credentials.md (comprehensive credential management) * system-config.md (server config schema, patches, upgrades) - Reorganize agent documentation into 5 granular, content-named files: * agents-crud.md (create, list, update, delete, files, instances) * agents-sharing-delegation.md (share, delegation links, wait) * agents-export-import.md (export/import/merge archives) * agents-memory.md (episodic memory, evolution metrics) * agents-orchestration.md (orchestration, identity, prompt-preview) * Replace agents-core.md + agents-advanced.md + agents-extended.md - Reorganize chat documentation into 4 granular, content-named files: * chat-basic.md (single-shot, continue session) * chat-sessions.md (session ops: branch, reset, label, compact) * chat-history.md (history, replay) * chat-injection.md (inject, session-status, follow) * Replace chat-sessions.md + chat-extended.md - Update SKILL.md navigation table to point to all 35 reference files - 100% CLI command coverage (50+ commands, 100+ subcommands) - All references follow consistent pattern: when-to-use, commands, flags, JSON output, destructive ops, examples, edge cases, cross-refs Co-Authored-By: Claude Haiku 4.5 --- claude-skill/SKILL.md | 53 +++++-- claude-skill/references/agents-advanced.md | 106 -------------- .../{agents-core.md => agents-crud.md} | 80 +++++----- .../references/agents-export-import.md | 83 +++++++++++ claude-skill/references/agents-memory.md | 99 +++++++++++++ .../references/agents-orchestration.md | 125 ++++++++++++++++ .../references/agents-sharing-delegation.md | 132 +++++++++++++++++ claude-skill/references/backup-restore.md | 119 +++++++++++++++ claude-skill/references/chat-basic.md | 82 +++++++++++ claude-skill/references/chat-history.md | 70 +++++++++ claude-skill/references/chat-injection.md | 87 +++++++++++ claude-skill/references/chat-sessions.md | 108 ++++++++------ claude-skill/references/credentials.md | 121 +++++++++++++++ claude-skill/references/edition.md | 62 ++++++++ claude-skill/references/hooks.md | 138 ++++++++++++++++++ claude-skill/references/oauth.md | 108 ++++++++++++++ claude-skill/references/profile.md | 82 +++++++++++ claude-skill/references/quota.md | 60 ++++++++ claude-skill/references/system-config.md | 121 +++++++++++++++ claude-skill/references/users.md | 62 ++++++++ claude-skill/references/vault.md | 138 ++++++++++++++++++ claude-skill/references/voices.md | 65 +++++++++ claude-skill/references/webhooks.md | 109 ++++++++++++++ claude-skill/references/workstations.md | 117 +++++++++++++++ 24 files changed, 2123 insertions(+), 204 deletions(-) delete mode 100644 claude-skill/references/agents-advanced.md rename claude-skill/references/{agents-core.md => agents-crud.md} (51%) create mode 100644 claude-skill/references/agents-export-import.md create mode 100644 claude-skill/references/agents-memory.md create mode 100644 claude-skill/references/agents-orchestration.md create mode 100644 claude-skill/references/agents-sharing-delegation.md create mode 100644 claude-skill/references/backup-restore.md create mode 100644 claude-skill/references/chat-basic.md create mode 100644 claude-skill/references/chat-history.md create mode 100644 claude-skill/references/chat-injection.md create mode 100644 claude-skill/references/credentials.md create mode 100644 claude-skill/references/edition.md create mode 100644 claude-skill/references/hooks.md create mode 100644 claude-skill/references/oauth.md create mode 100644 claude-skill/references/profile.md create mode 100644 claude-skill/references/quota.md create mode 100644 claude-skill/references/system-config.md create mode 100644 claude-skill/references/users.md create mode 100644 claude-skill/references/vault.md create mode 100644 claude-skill/references/voices.md create mode 100644 claude-skill/references/webhooks.md create mode 100644 claude-skill/references/workstations.md diff --git a/claude-skill/SKILL.md b/claude-skill/SKILL.md index 258aed6..342fb7c 100644 --- a/claude-skill/SKILL.md +++ b/claude-skill/SKILL.md @@ -39,22 +39,45 @@ Claude: when user's intent matches, `Read` the listed reference file before cons | Intent signal | Reference | |---------------|-----------| -| exec / run shell / remote command / approvals | [references/exec-workflow.md](references/exec-workflow.md) | -| login / token / profile / tenant switch / credentials / api-keys | [references/auth-and-config.md](references/auth-and-config.md) | -| agent list/get/create/delete, agent files, instances, wake | [references/agents-core.md](references/agents-core.md) | -| agent share, link, delegate, regenerate | [references/agents-advanced.md](references/agents-advanced.md) | -| chat with agent, session list/preview/delete | [references/chat-sessions.md](references/chat-sessions.md) | -| health, status, logs, traces, usage, metrics | [references/monitoring-ops.md](references/monitoring-ops.md) | -| knowledge graph, entity dedup, memory | [references/knowledge-memory.md](references/knowledge-memory.md) | -| teams, members, team tasks, workspace files | [references/teams-collaboration.md](references/teams-collaboration.md) | -| channels, contacts, pending messages, writers | [references/channels-messaging.md](references/channels-messaging.md) | -| export / import / storage (workspace files) | [references/data-movement.md](references/data-movement.md) | -| providers, skills, built-in tools list/config, packages | [references/providers-skills-tools.md](references/providers-skills-tools.md) | -| cron, heartbeat, device pairing | [references/automation-scheduling.md](references/automation-scheduling.md) | -| MCP servers, grants, requests | [references/mcp-integration.md](references/mcp-integration.md) | -| tenants, system-config, audit activity, TTS | [references/admin-system.md](references/admin-system.md) | -| media upload/download | [references/media.md](references/media.md) | +| exec / run shell / remote command / approvals / tools builtin/custom | [references/exec-workflow.md](references/exec-workflow.md) | +| login / token / api-keys / tenant switch | [references/auth-and-config.md](references/auth-and-config.md) | +| CLI profiles (server config), connections | [references/profile.md](references/profile.md) | +| credential store, grants, presets | [references/credentials.md](references/credentials.md) | +| agents CRUD (create, list, update, delete, files, instances, wake) | [references/agents-crud.md](references/agents-crud.md) | +| agents sharing, delegation links, history, wait, regenerate, resummon | [references/agents-sharing-delegation.md](references/agents-sharing-delegation.md) | +| agents export, import, merge archives | [references/agents-export-import.md](references/agents-export-import.md) | +| agents episodic memory, evolution metrics, suggestions, skill evolution | [references/agents-memory.md](references/agents-memory.md) | +| agents orchestration, identity, skills, prompt-preview, lifecycle (summon, cancel, sync, v3-flags) | [references/agents-orchestration.md](references/agents-orchestration.md) | +| chat single-shot, continue session, connectivity test | [references/chat-basic.md](references/chat-basic.md) | +| chat session operations (list, preview, delete, reset, label, branch, compact) | [references/chat-sessions.md](references/chat-sessions.md) | +| chat message history, replay | [references/chat-history.md](references/chat-history.md) | +| chat message injection, session status, follow | [references/chat-injection.md](references/chat-injection.md) | +| health, status, logs (tail), traces, usage, metrics | [references/monitoring-ops.md](references/monitoring-ops.md) | +| knowledge graph (dedup, entities, stats), agent episodic memory | [references/knowledge-memory.md](references/knowledge-memory.md) | +| knowledge vault (documents, search, graph, enrichment, upload) | [references/vault.md](references/vault.md) | +| teams, members, team tasks, attachments, events, scopes, workspace | [references/teams-collaboration.md](references/teams-collaboration.md) | +| channels, contacts, instances, pending, tenant-users, writers | [references/channels-messaging.md](references/channels-messaging.md) | +| inter-agent messaging (send), pending message management | [references/channels-messaging.md](references/channels-messaging.md) | +| export / import agents/teams/skills/mcp (portable archives) | [references/data-movement.md](references/data-movement.md) | +| storage (list, get, upload, delete, move, size), files (sign) | [references/data-movement.md](references/data-movement.md) | +| providers (create/get/list), embedding status, skills, tools, packages | [references/providers-skills-tools.md](references/providers-skills-tools.md) | +| LLM provider management, OAuth (ChatGPT, OpenAI) | [references/oauth.md](references/oauth.md) | +| cron jobs (create, schedule, run, history) | [references/automation-scheduling.md](references/automation-scheduling.md) | +| heartbeat (agent health monitoring), device pairing, workstations | [references/automation-scheduling.md](references/automation-scheduling.md) | +| MCP servers, grants, requests, integration | [references/mcp-integration.md](references/mcp-integration.md) | +| tenants (CRUD, users), audit activity (activity log), TTS status | [references/admin-system.md](references/admin-system.md) | +| per-tenant system-config KV store | [references/admin-system.md](references/admin-system.md) | +| server-level config schema/defaults/get/patch/apply, system upgrade | [references/system-config.md](references/system-config.md) | +| media upload/download, quota | [references/media.md](references/media.md) | | API documentation browsing | [references/docs-api.md](references/docs-api.md) | +| backup/restore (system/tenant), preflight, S3 integration | [references/backup-restore.md](references/backup-restore.md) | +| inbound webhooks (HTTP callbacks to external services) | [references/webhooks.md](references/webhooks.md) | +| event hooks (internal system routing, handlers, matchers) | [references/hooks.md](references/hooks.md) | +| voice catalog management, TTS voices | [references/voices.md](references/voices.md) | +| coding-agent workstations (isolated environments, permissions, activity) | [references/workstations.md](references/workstations.md) | +| server edition info, feature availability, license | [references/edition.md](references/edition.md) | +| quota inspection (token/API usage by agent) | [references/quota.md](references/quota.md) | +| user search and discovery (cross-tenant) | [references/users.md](references/users.md) | ## Compatibility diff --git a/claude-skill/references/agents-advanced.md b/claude-skill/references/agents-advanced.md deleted file mode 100644 index 2d5c2a5..0000000 --- a/claude-skill/references/agents-advanced.md +++ /dev/null @@ -1,106 +0,0 @@ -# Agents — advanced (links, ops, delegations) - -## When to use - -User wants to share agents across users, create delegation links between agents, regenerate/resummon an agent, or wait for an agent to finish. - -## Commands in scope - -- `goclaw agents links list/create/update/delete` — delegation links (source: `cmd/agents_links.go`) -- `goclaw agents share/unshare ` — user sharing (source: `cmd/agents_ops.go:11-49`) -- `goclaw agents regenerate/resummon ` — reset agent setup -- `goclaw agents wait ` — **WS-based blocking wait** (source: `cmd/agents_ops.go:87`) -- `goclaw delegations list/get` — delegation history (source: `cmd/admin.go:86-129`) - -## Verified flags - -### `agents links create` -| Flag | Type | Default | Purpose | -| --- | --- | --- | --- | -| `--source ` | string | — | Source agent | -| `--target ` | string | — | Target agent | -| `--direction ` | string | `outbound` | `outbound`/`inbound`/`bidirectional` | -| `--max-concurrent ` | int | 3 | Concurrent delegation cap | - -### `agents share` -| Flag | Type | Default | Purpose | -| --- | --- | --- | --- | -| `--user ` | string (REQUIRED) | — | User to share with | -| `--role ` | string | `operator` | `admin`/`operator`/`viewer` | - -### `agents unshare` -| Flag | Type | Purpose | -| --- | --- | --- | -| `--user ` | string (REQUIRED) | User to revoke | - -### `agents wait` -| Flag | Type | Purpose | -| --- | --- | --- | -| `--session ` | string | Session to wait on | -| `--timeout ` | int (0 = no timeout) | Bash-safe max ~100 | - -### `delegations list` -| Flag | Type | Default | Purpose | -| --- | --- | --- | --- | -| `--agent ` | string | — | Filter by agent | -| `--limit ` | int | 20 | Max results | - -## JSON output - -- ✅ `agents links list` — JSON -- ✅ `delegations list/get` — JSON -- ✅ `agents wait` — JSON final state (blocks until complete or timeout) -- ⚠️ `share/unshare/regenerate/resummon/links create|update|delete` — success text only - -## Destructive ops - -| Command | Source | Confirm | -| --- | --- | --- | -| `agents links delete` | `agents_links.go:99` tui.Confirm | YES | -| `agents unshare` | removes user access | YES | - -## Common patterns - -### Example 1: share agent with user as operator -```bash -goclaw agents share --user user-42 --role operator -``` - -### Example 2: create bidirectional delegation link -```bash -goclaw agents links create \ - --source agent-alpha --target agent-beta \ - --direction bidirectional --max-concurrent 5 \ - --output json -``` - -### Example 3: wait for agent to finish (with timeout) -```bash -# Bash tool default timeout = 120s, set --timeout lower -goclaw agents wait --session --timeout 90 --output json -``` - -### Example 4: delegation audit -```bash -goclaw delegations list --agent --limit 50 --output json -goclaw delegations get --output json -``` - -### Example 5: regenerate after model swap -```bash -goclaw agents update --model claude-opus-4-7 -goclaw agents regenerate -``` - -## Edge cases & gotchas - -- **`agents wait` WS subscribe:** blocks until agent idle OR timeout. With `--timeout 0` it blocks indefinitely → Bash tool kills at 120s. Always set a `--timeout < 110`. -- **Direction `inbound`:** target receives delegations from source, not the other way. Mental model: "direction of the data flow". -- **Role hierarchy:** `admin` > `operator` > `viewer`. Downgrade requires `unshare` + `share` with new role. -- **`regenerate` vs `resummon`:** regenerate rebuilds agent config from current settings; resummon reruns initial setup wizard (may prompt on server side). -- **Delegations view is read-only:** no create/delete — links drive the delegation; history is automatic. - -## Cross-refs - -- Agent base CRUD: [agents-core.md](agents-core.md) -- Team tasks (different concept): [teams-collaboration.md](teams-collaboration.md) diff --git a/claude-skill/references/agents-core.md b/claude-skill/references/agents-crud.md similarity index 51% rename from claude-skill/references/agents-core.md rename to claude-skill/references/agents-crud.md index d4df909..419b7c1 100644 --- a/claude-skill/references/agents-core.md +++ b/claude-skill/references/agents-crud.md @@ -1,19 +1,19 @@ -# Agents — core lifecycle +# Agents — CRUD & lifecycle ## When to use -User wants to list/inspect/create/update/delete agents, manage agent context files, or control per-user agent instances. +User wants to create, list, inspect, update, or delete agents; manage agent context files; control per-user instances; or wake agents. ## Commands in scope -- `goclaw agents list` / `get ` / `create` / `update ` / `delete ` — base CRUD (source: `cmd/agents.go`) +- `goclaw agents list/get/create/update/delete` — agent CRUD (source: `cmd/agents.go`) - `goclaw agents files list/get/create/delete` — agent context files (source: `agents_files.go`, WS-backed) - `goclaw agents instances list/get/create/delete/trigger/reset` — per-user instances (source: `agents_instances.go`) - `goclaw agents wake ` — wake sleeping agent (source: `agents_wake.go`) ## Verified flags -### `agents create` / `agents update` +### `agents create/update` | Flag | Type | Purpose | | --- | --- | --- | | `--name ` | string | Display name | @@ -36,30 +36,24 @@ User wants to list/inspect/create/update/delete agents, manage agent context fil ## JSON output -- ✅ `agents list/get` — JSON (cmd/agents.go:30, :57) +- ✅ `agents list/get` — JSON - ✅ `agents instances list/get` — JSON -- ⚠️ `agents create/update/delete/wake` — `printer.Success` text; parse exit code + stdout ID message +- ⚠️ `agents create/update/delete/wake` — success text; parse exit code + stdout ID - ⚠️ `agents files create/delete` — success text only - ⚠️ `agents instances create/delete/trigger/reset` — success text ## Destructive ops -| Command | Source | Confirm | -| --- | --- | --- | -| `agents delete` | `agents.go:140` tui.Confirm | YES | -| `agents files delete` | `agents_files.go` tui.Confirm | YES | -| `agents instances delete` | `agents_instances.go` tui.Confirm | YES | -| `agents instances reset` | clears instance state | YES | +| Command | Confirm | +| --- | --- | +| `agents delete` | YES | +| `agents files delete` | YES | +| `agents instances delete` | YES | +| `agents instances reset` | YES (clears state) | ## Common patterns -### Example 1: list + get details -```bash -goclaw agents list --output json -goclaw agents get --output json -``` - -### Example 2: create agent +### Create agent ```bash goclaw agents create \ --name "Support Bot" \ @@ -72,39 +66,53 @@ goclaw agents create \ --output json ``` -### Example 3: update model + budget +### List agents ```bash -goclaw agents update --model claude-opus-4-7 --budget 10000 --output json +goclaw agents list --output json ``` -### Example 4: full lifecycle — create → upload file → instance → wake +### Get agent details ```bash -goclaw agents create --name "DocBot" --provider openai --model gpt-4o --type open --output json -# → AGENT_ID +goclaw agents get --output json +``` +### Update agent +```bash +goclaw agents update --model claude-opus-4-7 --budget 10000 --output json +``` + +### Manage agent files +```bash goclaw agents files create --data '{"path":"guide.md","content":"..."}' --output json +goclaw agents files list --output json +goclaw agents files delete --yes +``` +### Create per-user instance +```bash goclaw agents instances create --user-id user-42 --output json -goclaw agents wake +goclaw agents instances list --user-id user-42 --output json ``` -### Example 5: delete agent (always confirm) +### Wake agent ```bash -# Claude: echo back "Delete agent ? This is permanent." before running: -goclaw agents delete --yes +goclaw agents wake ``` ## Edge cases & gotchas -- **`--name` sets `display_name`** on create, but update maps flag `--name` to `display_name` field (source: `agents.go:107`). Both work. -- **Agent vs instance:** agent = template, instance = per-user runtime. Delete agent ⇒ cascades instances. List carefully. -- **Files WS-backed:** `agents files` subcommands use WebSocket, not HTTP — same as `teams`. Latency slightly higher but same JSON shape. -- **Budget is cents, not dollars.** $50 = `--budget 5000`. -- **Agent type:** `open` (user-designed prompt) vs `predefined` (built-in role). Check server docs for full list. +- **`--name` sets `display_name`** on create; update also accepts `--name` for `display_name` field. +- **Agent vs instance:** agent = template, instance = per-user runtime. Delete agent cascades instances. +- **Files WS-backed:** higher latency than HTTP, same JSON shape. +- **Budget in cents:** $50 = `--budget 5000`; not dollars. +- **Agent type:** `open` (user-designed) vs `predefined` (built-in role). - **Wake:** idempotent — waking awake agent is no-op. +- **Instance reset:** clears message history + state, preserves agent/user bindings. ## Cross-refs -- Sharing, linking, delegation: [agents-advanced.md](agents-advanced.md) -- Chat with agent: [chat-sessions.md](chat-sessions.md) -- Run tools as agent: [exec-workflow.md](exec-workflow.md) +- Sharing + delegation: [agents-sharing-delegation.md](agents-sharing-delegation.md) +- Export/import: [agents-export-import.md](agents-export-import.md) +- Memory + evolution: [agents-memory.md](agents-memory.md) +- Orchestration + identity: [agents-orchestration.md](agents-orchestration.md) +- Chat with agent: [chat-basic.md](chat-basic.md) diff --git a/claude-skill/references/agents-export-import.md b/claude-skill/references/agents-export-import.md new file mode 100644 index 0000000..5d35f7f --- /dev/null +++ b/claude-skill/references/agents-export-import.md @@ -0,0 +1,83 @@ +# Agents — export & import + +## When to use + +User wants to backup agents, migrate agents between systems, port agent configuration, or restore from archives. + +## Commands in scope + +- `goclaw agents export [-o file]` — export agent as .tar.gz (source: `cmd/agents_export.go`) +- `goclaw agents import ` — import with preview (dry-run by default) (source: `cmd/agents_import.go`) +- `goclaw agents import --apply` — perform import (overwrites) +- `goclaw agents import-merge ` — merge imported agent into existing agent + +## Verified flags + +### `agents export` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent to export | +| `-o, --file ` | string | Output file (default: stdout) | + +### `agents import` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | path | Archive file (.tar.gz) | +| `--apply` | bool | Perform import (default: preview only) | + +### `agents import-merge` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | path | Archive file (.tar.gz) | +| `--apply` | bool | Perform merge (default: preview only) | + +## JSON output + +- ✅ `agents export` — binary .tar.gz (use `-o` to file) +- ✅ `agents import/import-merge` preview — JSON (shows what would import) +- ⚠️ `agents import/import-merge --apply` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `agents import --apply` | YES (overwrites agent) | +| `agents import-merge --apply` | YES (merges into existing) | + +## Common patterns + +### Export agent for backup +```bash +goclaw agents export -o /tmp/agent-backup.tar.gz +# → agent-backup.tar.gz with config, files, memory, skills +``` + +### Preview import +```bash +goclaw agents import /tmp/agent-backup.tar.gz --output json +# shows what would be imported +``` + +### Perform import +```bash +goclaw agents import /tmp/agent-backup.tar.gz --apply --yes +``` + +### Merge imported agent into existing +```bash +goclaw agents import-merge /tmp/agent-backup.tar.gz --apply --yes +``` + +## Edge cases & gotchas + +- **Archive contents:** includes config, context files, episodic memory, granted skills, and metadata. +- **Archive size:** grows with agent history. Large agents (many messages, big memory) produce multi-GB archives. +- **Export to stdout:** without `-o`, exports to stdout. Can be piped but binary data → be careful. +- **Import overwrites:** replaces entire agent config. Agent ID may change on import. +- **Merge preserves existing:** merges imported config/memory into current agent. Less destructive than import. +- **Portability:** archives are version-tied. Importing into newer/older server version may fail or degrade. + +## Cross-refs + +- Agent CRUD: [agents-crud.md](agents-crud.md) +- Data movement: [data-movement.md](data-movement.md) diff --git a/claude-skill/references/agents-memory.md b/claude-skill/references/agents-memory.md new file mode 100644 index 0000000..7f44740 --- /dev/null +++ b/claude-skill/references/agents-memory.md @@ -0,0 +1,99 @@ +# Agents — memory & evolution + +## When to use + +User wants to inspect agent episodic memory, search learning history, view evolution metrics, apply AI-suggested improvements, or manage agent learning. + +## Commands in scope + +- `goclaw agents episodic list ` — list episodic memory entries (source: `cmd/agents_episodic.go`) +- `goclaw agents episodic search ` — semantic search episodic memory +- `goclaw agents evolution metrics ` — get evolution metrics (source: `cmd/agents_evolution.go`) +- `goclaw agents evolution suggestions ` — list AI-generated improvements +- `goclaw agents evolution update ` — accept/reject evolution suggestion +- `goclaw agents evolution skill ` — apply skill evolution + +## Verified flags + +### `agents episodic list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | +| `--limit ` | int | Max entries | +| `--offset ` | int | Pagination offset | + +### `agents episodic search` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | +| `` | string | Search query | +| `--limit ` | int | Max results | + +### `agents evolution update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | +| `--suggestion-id ` | string | Suggestion ID | +| `--accept` | bool | Accept suggestion | +| `--reject` | bool | Reject suggestion | + +## JSON output + +- ✅ `agents episodic list/search`, `agents evolution metrics/suggestions` — JSON +- ⚠️ `agents evolution update/skill` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `agents evolution update --reject` | YES (rejects suggestion) | + +## Common patterns + +### List episodic memory entries +```bash +goclaw agents episodic list --limit 20 --output json +``` + +### Search episodic memory +```bash +goclaw agents episodic search "user asked about pricing" --output json +``` + +### Get evolution metrics +```bash +goclaw agents evolution metrics --output json +``` + +### List evolution suggestions +```bash +goclaw agents evolution suggestions --output json +``` + +### Accept evolution suggestion +```bash +goclaw agents evolution update --suggestion-id --accept --output json +``` + +### Reject evolution suggestion +```bash +goclaw agents evolution update --suggestion-id --reject --yes +``` + +### Apply skill evolution +```bash +goclaw agents evolution skill --output json +``` + +## Edge cases & gotchas + +- **Episodic memory:** semantic search depends on embedding provider. Server must have embeddings enabled. +- **Evolution metrics:** AI-generated suggestions. Accept/reject tracked server-side for learning. +- **Search queries:** free-text; server finds semantically similar entries, not just keyword matches. +- **Skill evolution:** applies evolved skills to agent capabilities. May require agent restart. +- **History retention:** episodic memory retention depends on server config. Check `system-config` for retention window. + +## Cross-refs + +- Agent CRUD: [agents-crud.md](agents-crud.md) +- Agent identity: [agents-orchestration.md](agents-orchestration.md) diff --git a/claude-skill/references/agents-orchestration.md b/claude-skill/references/agents-orchestration.md new file mode 100644 index 0000000..c28af46 --- /dev/null +++ b/claude-skill/references/agents-orchestration.md @@ -0,0 +1,125 @@ +# Agents — orchestration & identity + +## When to use + +User wants to check agent orchestration config, view agent identity (persona, traits, goals), preview system prompts, inspect granted skills, manage lifecycle (summon, cancel, sync), or toggle experimental flags. + +## Commands in scope + +- `goclaw agents orchestration ` — get orchestration mode + delegation config (source: `cmd/agents_orchestration.go`) +- `goclaw agents identity ` — get agent identity (persona, traits, goals, constraints) +- `goclaw agents prompt-preview ` — get fully rendered system prompt +- `goclaw agents skills list ` — list skills granted to agent +- `goclaw agents cancel-summon ` — cancel pending/running summon (source: `cmd/agents_summon.go`) +- `goclaw agents sync-workspace` — admin: sync workspace for all agents +- `goclaw agents v3-flags get ` — get v3 feature flags (experimental) +- `goclaw agents v3-flags toggle ` — toggle v3 feature flag + +## Verified flags + +### `agents orchestration` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | + +### `agents identity` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Agent key | + +### `agents prompt-preview` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | + +### `agents skills list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | + +### `agents cancel-summon` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent to cancel | + +### `agents sync-workspace` +Admin-only; no flags (affects all agents). + +### `agents v3-flags toggle` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | +| `--flag ` | string | Flag name to toggle | + +## JSON output + +- ✅ `agents orchestration`, `agents identity`, `agents prompt-preview`, `agents skills list` — JSON +- ⚠️ `agents cancel-summon`, `agents sync-workspace`, `agents v3-flags get/toggle` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `agents v3-flags toggle` | YES (experimental feature) | + +## Common patterns + +### Get orchestration config +```bash +goclaw agents orchestration --output json +# → delegation mode, concurrent limits, etc. +``` + +### Get agent identity +```bash +goclaw agents identity --output json +# → persona, traits, goals, constraints +``` + +### Preview system prompt +```bash +goclaw agents prompt-preview --output json | jq '.prompt' -r +# shows final prompt after variable substitution + file inclusion +``` + +### List granted skills +```bash +goclaw agents skills list --output json +``` + +### Cancel summon in progress +```bash +goclaw agents cancel-summon +``` + +### Sync workspace (admin) +```bash +goclaw agents sync-workspace +``` + +### Get v3 feature flags +```bash +goclaw agents v3-flags get --output json +``` + +### Toggle experimental flag +```bash +goclaw agents v3-flags toggle --flag streaming-responses --yes +``` + +## Edge cases & gotchas + +- **Orchestration:** read-only endpoint showing delegation mode (independent, collaborative, hierarchical). +- **Identity:** WS-backed; includes persona, traits, goals, constraints. Read-only. +- **Prompt preview:** shows final prompt after variable substitution, context file inclusion, skill injection, etc. Useful for debugging. +- **Skills:** list only; grant/revoke via provider's `skills` commands. +- **Cancel-summon:** stops pending/running agent setup. Agent may require `resummon` to retry. +- **Sync-workspace:** admin-only. Re-syncs all agent workspaces. Long-running. +- **v3-flags:** experimental toggles. Not all agents support all flags. May require restart. + +## Cross-refs + +- Agent CRUD: [agents-crud.md](agents-crud.md) +- Sharing & delegation: [agents-sharing-delegation.md](agents-sharing-delegation.md) +- Memory & evolution: [agents-memory.md](agents-memory.md) +- Skills management: [providers-skills-tools.md](providers-skills-tools.md) diff --git a/claude-skill/references/agents-sharing-delegation.md b/claude-skill/references/agents-sharing-delegation.md new file mode 100644 index 0000000..5ac7099 --- /dev/null +++ b/claude-skill/references/agents-sharing-delegation.md @@ -0,0 +1,132 @@ +# Agents — sharing & delegation + +## When to use + +User wants to share agents with other users, create delegation links between agents, manage user access roles, view delegation history, or wait for agent completion. + +## Commands in scope + +- `goclaw agents share --user ` — grant user access (source: `cmd/agents_ops.go`) +- `goclaw agents unshare --user ` — revoke user access +- `goclaw agents links list/create/update/delete` — agent-to-agent delegation links (source: `cmd/agents_links.go`) +- `goclaw agents wait ` — block until agent reaches target state (source: `cmd/agents_ops.go`) +- `goclaw agents regenerate ` — regenerate agent config (source: `cmd/agents_ops.go`) +- `goclaw agents resummon ` — re-trigger agent setup +- `goclaw delegations list/get` — delegation history (read-only) (source: `cmd/admin.go`) + +## Verified flags + +### `agents share` +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--user ` | string | (REQUIRED) | User ID | +| `--role ` | string | `operator` | `admin`, `operator`, `viewer` | + +### `agents unshare` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--user ` | string | User to revoke | + +### `agents links create/update` +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--source ` | string | — | Source agent | +| `--target ` | string | — | Target agent | +| `--direction ` | string | `outbound` | `outbound`, `inbound`, `bidirectional` | +| `--max-concurrent ` | int | 3 | Concurrent delegation cap | + +### `agents links delete` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Link ID | + +### `agents wait` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Agent key to wait for | +| `--state ` | string | Target: `online`, `running`, `idle`, `offline` | +| `--timeout ` | duration | Wait timeout (default 5m) | + +### `agents regenerate/resummon` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | agent ID | Agent ID | + +### `delegations list` +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--agent ` | string | — | Filter by agent | +| `--limit ` | int | 20 | Max results | + +## JSON output + +- ✅ `agents links list`, `delegations list/get` — JSON +- ✅ `agents wait` — JSON final state (blocks until complete/timeout) +- ⚠️ `agents share/unshare/regenerate/resummon`, `agents links create/update/delete` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `agents unshare` | YES (revokes access) | +| `agents links delete` | YES | +| `agents regenerate` | YES (rebuilds config) | + +## Common patterns + +### Share with user +```bash +goclaw agents share --user user-42 --role operator +``` + +### Create delegation link +```bash +goclaw agents links create \ + --source agent-alpha \ + --target agent-beta \ + --direction bidirectional \ + --max-concurrent 5 \ + --output json +``` + +### View delegation links +```bash +goclaw agents links list --output json +``` + +### View delegation history +```bash +goclaw delegations list --agent --limit 50 --output json +goclaw delegations get --output json +``` + +### Wait for agent to reach state +```bash +goclaw agents wait --state idle --timeout 30s --output json +``` + +### Regenerate after model update +```bash +goclaw agents update --model claude-opus-4-7 +goclaw agents regenerate +``` + +### Revoke user access +```bash +goclaw agents unshare --user user-42 --yes +``` + +## Edge cases & gotchas + +- **Role hierarchy:** `admin` > `operator` > `viewer`. Downgrade requires `unshare` + `share` with new role. +- **Direction:** `inbound` = target receives delegations from source; `outbound` = source delegates to target. +- **Max concurrent:** caps number of active delegations at once. Excess requests queue. +- **`agents wait` timeout:** blocks until state reached OR timeout expires. Always set `--timeout < 110s` for Bash tool (default 120s timeout). +- **Regenerate vs resummon:** regenerate = rebuild config from current settings; resummon = re-trigger setup wizard. +- **Delegations read-only:** history view only; links drive the delegation. No direct delegation CRUD. + +## Cross-refs + +- Agent CRUD: [agents-crud.md](agents-crud.md) +- Export/import: [agents-export-import.md](agents-export-import.md) +- Team collaboration: [teams-collaboration.md](teams-collaboration.md) diff --git a/claude-skill/references/backup-restore.md b/claude-skill/references/backup-restore.md new file mode 100644 index 0000000..6621287 --- /dev/null +++ b/claude-skill/references/backup-restore.md @@ -0,0 +1,119 @@ +# Backup & restore + +## When to use + +Admin needs to create backups of system or tenant data, or restore from a previously created backup archive. **Requires admin role** — check `goclaw whoami` first. + +## Commands in scope + +### Backup (source: `cmd/backup.go`) +- `goclaw backup system` — create full system backup (returns download token) +- `goclaw backup system-download ` — download backup by token +- `goclaw backup system-preflight` — check disk space, pg_dump readiness +- `goclaw backup tenant` — create single tenant backup +- `goclaw backup tenant-download ` — download tenant backup by token +- `goclaw backup tenant-preflight` — check tenant backup readiness +- `goclaw backup s3 [subcommands]` — manage S3 backup integration + +### Restore (source: `cmd/restore.go`) +- `goclaw restore system ` — restore entire system from .tar.gz archive **DESTRUCTIVE** +- `goclaw restore tenant ` — restore tenant from .tar.gz archive **DESTRUCTIVE** + +## Verified flags + +### `backup system` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--exclude-db` | bool | Skip database from backup | +| `--exclude-files` | bool | Skip files from backup | +| `--file ` | string | Output file for auto-download (requires `--wait`) | +| `--wait` | bool | Wait + auto-download (used with `--file`) | + +### `backup tenant` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--tenant-id ` | string | Tenant ID to backup | +| `--file ` | string | Output file for auto-download | +| `--wait` | bool | Wait + auto-download | + +### `backup system-preflight` / `backup tenant-preflight` +No flags; read-only checks. + +### `restore system` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--confirm ` | string | **REQUIRED** — type archive filename to confirm | +| `--yes` | bool | **REQUIRED** — confirm destructive operation | + +### `restore tenant` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--tenant-id ` | string | **REQUIRED** — tenant ID to restore | +| `--confirm ` | string | **REQUIRED** — type tenant ID to confirm | +| `--yes` | bool | **REQUIRED** — confirm destructive operation | + +## JSON output + +- ✅ `backup system/tenant` — returns JSON with token (e.g., `{"token": "...",...}`) +- ✅ `backup system-preflight/tenant-preflight` — JSON readiness status +- ⚠️ `backup s3` subcommands — check `--help` per subcommand +- ⚠️ `restore system/tenant` — success text only (check exit code 0) + +## Destructive ops + +| Command | Why dangerous | +| --- | --- | +| `restore system ` | Overwrites ALL system data (db + files). No undo. | +| `restore tenant ` | Overwrites ALL tenant data (agents, sessions, memory). No undo. | + +## Common patterns + +### Example 1: check backup readiness +```bash +goclaw backup system-preflight --output json +goclaw backup tenant-preflight --tenant-id acme --output json +``` + +### Example 2: create system backup with auto-download +```bash +goclaw backup system --wait -o /tmp/backup.tar.gz --output json +# response includes token for resuming download separately +``` + +### Example 3: create tenant backup +```bash +goclaw backup tenant --tenant-id acme --wait -o /tmp/tenant-backup.tar.gz +``` + +### Example 4: restore system (VERY DESTRUCTIVE) +```bash +# Claude: confirm with user FIRST — this overwrites everything +goclaw restore system /tmp/backup-20260601.tar.gz \ + --confirm=backup-20260601.tar.gz \ + --yes \ + --output json +``` + +### Example 5: restore tenant (DESTRUCTIVE) +```bash +# Claude: confirm with user FIRST +goclaw restore tenant /tmp/tenant-backup.tar.gz \ + --tenant-id acme \ + --confirm=acme \ + --yes +``` + +## Edge cases & gotchas + +- **Download token TTL:** returned token expires after ~24h. Re-create backup if token expires. +- **Backup file size:** large systems (big databases, many files) may take minutes and produce multi-GB archives. +- **Restore requires literal file paths**, not stdin. Archive must exist locally; decompress if needed. +- **Restore `--confirm` flag is TYPO-PROOF:** you must type the exact archive basename (for system) or tenant ID (for tenant). Mismatch = rejected. +- **All connections must stop before restore:** agents, webhooks, WS streams must be idle. Server won't let you restore with active connections. +- **Restore is logged:** full audit trail server-side (who, when, what restored). +- **S3 integration:** separate `backup s3` commands for configuring automated S3 offloads. See `goclaw backup s3 --help`. + +## Cross-refs + +- Admin role check: [auth-and-config.md](auth-and-config.md) — `whoami` +- Tenant management: [admin-system.md](admin-system.md) — `tenants list/delete` diff --git a/claude-skill/references/chat-basic.md b/claude-skill/references/chat-basic.md new file mode 100644 index 0000000..514d56d --- /dev/null +++ b/claude-skill/references/chat-basic.md @@ -0,0 +1,82 @@ +# Chat — basic operations + +## When to use + +User wants to send a single-shot message to an agent, continue a previous chat session, or test agent connectivity. + +## Commands in scope + +- `goclaw chat -m ""` — single-shot message (source: `cmd/chat.go`) +- `goclaw chat -m "" --no-stream` — single-shot, wait for full response +- `goclaw chat -m "" --session ` — continue existing session +- `goclaw chat echo ` — connectivity test (source: `cmd/chat_echo.go`) +- `goclaw chat` (no args) — **interactive REPL, skill REFUSES** + +## Verified flags + +### `chat ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `-m, --message ` | string | Single-shot message (required for non-interactive) | +| `--session ` | string | Continue existing session | +| `--no-stream` | bool | Wait for full response (no NDJSON stream) | + +### `chat echo` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Agent to test | +| `--message ` | string | Message to send | + +## JSON output + +- ✅ `chat -m ... --no-stream --output json` — single JSON map +- ✅ `chat -m ... --output json` — NDJSON event stream (parse line-by-line) +- ✅ `chat echo` — JSON +- ❌ `chat` (interactive) — REPL, skill refuses + +## Destructive ops + +None — read-only operations. + +## Common patterns + +### Single-shot question (wait for full response) +```bash +goclaw chat my-agent -m "Summarize today's activity" --no-stream --output json +``` + +### Stream response (NDJSON) +```bash +goclaw chat my-agent -m "Write a poem" --output json +# → parse line-by-line, stop at run.completed event +``` + +### Continue previous session +```bash +goclaw chat my-agent -m "Based on that, what next?" --session sess_abc --output json +``` + +### Pipe input from stdin +```bash +echo "Analyze this log" | goclaw chat my-agent --output json +``` + +### Test connectivity +```bash +goclaw chat echo --message "Hello" --output json +``` + +## Edge cases & gotchas + +- **Interactive mode:** `chat ` with no `-m` and no stdin → TUI REPL with slash commands (`/exit`, `/abort`, `/sessions`, `/clear`). Skill must always pass `-m` or stdin. +- **Streaming NDJSON:** without `--no-stream`, events arrive line-by-line. Parse incrementally; stop at `run.completed` event. +- **Event types:** `chunk` (text), `tool.call`, `tool.result`, `run.completed`. Build response from chunks. +- **Session key vs ID:** API uses `session_key` (human-readable, stable); list shows both. Use key for `--session`. +- **Token accounting:** response includes `input_tokens`/`output_tokens` per message. +- **Echo:** lightweight connectivity test. Does NOT create session or affect agent state. + +## Cross-refs + +- Session operations: [chat-sessions.md](chat-sessions.md) +- Chat history: [chat-history.md](chat-history.md) +- Message injection: [chat-injection.md](chat-injection.md) diff --git a/claude-skill/references/chat-history.md b/claude-skill/references/chat-history.md new file mode 100644 index 0000000..4b300db --- /dev/null +++ b/claude-skill/references/chat-history.md @@ -0,0 +1,70 @@ +# Chat — history & replay + +## When to use + +User wants to view chat message history, replay conversations for testing/audit, or inspect past exchanges. + +## Commands in scope + +- `goclaw chat history ` — list message history (source: `cmd/chat_history.go`) +- `goclaw chat replay ` — replay conversation (source: `cmd/chat_replay.go`) + +## Verified flags + +### `chat history` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Session ID | +| `--limit ` | int | Max messages (default 50) | +| `--offset ` | int | Pagination offset | + +### `chat replay` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Session ID | +| `--speed ` | float | Replay speed (1.0 = real-time) | + +## JSON output + +- ✅ `chat history`, `chat replay` — JSON + +## Destructive ops + +None — read-only operations. + +## Common patterns + +### View message history +```bash +goclaw chat history --output json +# → list of messages with timestamps, tokens, etc. +``` + +### View history with pagination +```bash +goclaw chat history --limit 20 --offset 40 --output json +``` + +### Replay conversation at real-time speed +```bash +goclaw chat replay --speed 1.0 --output json +``` + +### Replay conversation at 2x speed +```bash +goclaw chat replay --speed 2.0 --output json +# accelerated for testing +``` + +## Edge cases & gotchas + +- **History pagination:** default limit prevents huge JSON. Use `--limit` + `--offset` for large histories. +- **Replay speed:** 1.0 = real-time (respects original timing); >1 = accelerated (distorts timing); <1 = slowed down. +- **Token accounting:** history includes `input_tokens`/`output_tokens` per message. +- **Message order:** chronological (oldest first). + +## Cross-refs + +- Basic chat: [chat-basic.md](chat-basic.md) +- Session operations: [chat-sessions.md](chat-sessions.md) +- Message injection: [chat-injection.md](chat-injection.md) diff --git a/claude-skill/references/chat-injection.md b/claude-skill/references/chat-injection.md new file mode 100644 index 0000000..81ef4fc --- /dev/null +++ b/claude-skill/references/chat-injection.md @@ -0,0 +1,87 @@ +# Chat — injection & advanced operations + +## When to use + +User wants to inject messages into a session mid-conversation, check session status/metadata, or follow session in real-time (for testing/debugging). + +## Commands in scope + +- `goclaw chat inject ` — inject message into session (source: `cmd/chat_inject.go`) +- `goclaw chat session-status ` — check session state + metadata (source: `cmd/chat_status.go`) +- `goclaw chat follow ` — **follow session in real-time, STREAMING, skill REFUSES** +- `goclaw chat abort ` — force-stop running agent + +## Verified flags + +### `chat inject` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Session ID | +| `--role ` | string | `user` or `assistant` | +| `--content ` | string | Message content | + +### `chat session-status` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Session ID | + +### `chat follow` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Session ID | + +### `chat abort` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Session ID | + +## JSON output + +- ✅ `chat session-status` — JSON +- ⚠️ `chat inject` — success text only +- ❌ `chat follow` — streaming, skill refuses + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `chat inject` | Recommended (alters session) | +| `chat abort` | Recommended (stops in-progress work) | + +## Common patterns + +### Inject user message +```bash +goclaw chat inject --role user --content "What's the status?" --output json +``` + +### Inject assistant message (for testing) +```bash +goclaw chat inject --role assistant --content "Status is good" --output json +``` + +### Check session status +```bash +goclaw chat session-status --output json +# → {"state": "active|paused|archived", "message_count": 42, "last_activity": "..."} +``` + +### Abort running agent +```bash +# Always confirm with user first +goclaw chat abort +``` + +## Edge cases & gotchas + +- **Injection:** bypasses normal chat flow. Useful for testing/recovery but affects audit trail. No undo. +- **Role:** `user` = from user perspective; `assistant` = from agent perspective. Both valid for testing. +- **Status:** read-only metadata. Session state: `active` (normal), `paused` (temporarily), `archived` (closed). +- **Abort:** force-stops mid-tool-call. No retry. May leave partial state. +- **Follow:** real-time stream; STREAMING operation. Skill refuses. Suggest user terminal. + +## Cross-refs + +- Basic chat: [chat-basic.md](chat-basic.md) +- Session operations: [chat-sessions.md](chat-sessions.md) +- Chat history: [chat-history.md](chat-history.md) diff --git a/claude-skill/references/chat-sessions.md b/claude-skill/references/chat-sessions.md index 05608f0..8336ec1 100644 --- a/claude-skill/references/chat-sessions.md +++ b/claude-skill/references/chat-sessions.md @@ -6,94 +6,108 @@ User wants to send a message to an agent, inject input mid-run, abort a running ## Commands in scope -- `goclaw chat -m "" --no-stream` — single-shot (source: `cmd/chat.go:44-47`) -- `goclaw chat inject --text "..."` — inject into running session -- `goclaw chat status ` — session run status (WS call `chat.session.status`) -- `goclaw chat abort ` — abort running agent (WS call `chat.abort`) -- `goclaw sessions list` / `get` / `preview ` / `delete` / `reset` / `label` — session CRUD -- `goclaw chat ` *without* `-m` → **interactive REPL, skill REFUSES** +- `goclaw sessions list` — list chat sessions (source: `cmd/sessions.go`) +- `goclaw sessions get ` — get session details (alias for preview) +- `goclaw sessions preview ` — preview session transcript +- `goclaw sessions delete ` — delete session +- `goclaw sessions reset ` — clear messages, keep session +- `goclaw sessions label ` — set/change session label +- `goclaw sessions branch ` — branch conversation from point +- `goclaw sessions compact` — batch delete old sessions ## Verified flags -### `chat ` +### `sessions list` | Flag | Type | Purpose | | --- | --- | --- | -| `-m, --message` | string | Single-shot message (source: `cmd/chat.go:280`) | -| `--session ` | string | Continue existing session | -| `--no-stream` | bool | Wait for full response instead of streaming | +| `--agent ` | string | Filter by agent ID | +| `--user ` | string | Filter by user ID | +| `--limit ` | int | Max results (default 20) | +| `--offset ` | int | Pagination offset | -### `chat inject` +### `sessions preview/delete/reset/label` | Flag | Type | Purpose | | --- | --- | --- | -| `--text` | string (required) | Text to inject | -| `--session` | string | Session key | +| `` | session ID | Session identifier | +| (label only) `--label ` | string | New label name | -### `sessions list` +### `sessions branch` | Flag | Type | Purpose | | --- | --- | --- | -| `--agent` | string | Filter by agent ID | -| `--user` | string | Filter by user ID | -| `--limit` | int | Max results | +| `` | session ID | Session to branch from | +| `--from-message ` | int | Branch point (message index) | +| `--label ` | string | Label for new branch | -### `sessions label` +### `sessions compact` | Flag | Type | Purpose | | --- | --- | --- | -| `--label` | string (required) | New label | +| `--older-than ` | duration | Delete sessions older than (e.g., `30d`) | ## JSON output -- ✅ `chat -m ... --output json` — NDJSON event stream (`chat.go:92-98`) -- ✅ `chat -m ... --no-stream --output json` — single JSON map -- ✅ `sessions list/preview` — JSON -- ⚠️ `sessions delete/reset/label` — `printer.Success` text only +- ✅ `sessions list/preview/get` — JSON +- ⚠️ `sessions delete/reset/label/branch/compact` — success text only ## Destructive ops -| Command | Why destructive | +| Command | Confirm | | --- | --- | -| `sessions delete` | drops session + messages (tui.Confirm at `sessions.go:80`) | -| `sessions reset` | clears messages, keeps key (tui.Confirm at `sessions.go:101`) | -| `chat abort` | force-stops running agent mid-tool-call — **no `--yes` flag**, still warn user | +| `sessions delete` | YES (permanent) | +| `sessions reset` | YES (clears history) | +| `sessions compact --older-than ` | YES (batch delete) | ## Common patterns -### Example 1: single-shot question +### List sessions for agent ```bash -goclaw chat my-agent -m "Summarize today's activity" --no-stream --output json +goclaw sessions list --agent --limit 10 --output json ``` -### Example 2: continue previous session +### Preview session transcript ```bash -goclaw chat my-agent -m "Based on that, what next?" --session sess_abc --output json +goclaw sessions preview --limit 50 --output json ``` -### Example 3: pipe stdin +### Label session for organization ```bash -echo "Analyze this log" | goclaw chat my-agent --output json +goclaw sessions label --label "Bug investigation - Q2 2026" ``` -### Example 4: list sessions for agent + preview one +### Branch conversation from point ```bash -goclaw sessions list --agent --limit 10 --output json -goclaw sessions preview --output json +goclaw sessions branch --from-message 15 --label "Alternative path" --output json +# → new session ID (child of original) +``` + +### Reset session (clear history) +```bash +goclaw sessions reset --yes +``` + +### Delete session +```bash +goclaw sessions delete --yes ``` -### Example 5: abort runaway agent +### Batch delete old sessions ```bash -# Always confirm with user first -goclaw chat abort my-agent --session +goclaw sessions compact --older-than 90d --yes +# deletes all sessions older than 90 days ``` ## Edge cases & gotchas -- **Interactive mode detection:** `chat ` with no `-m` and no stdin → TUI REPL with `/exit`, `/abort`, `/sessions`, `/clear` slash commands (`chat.go:148`). Skill MUST always pass `-m` or pipe stdin. -- **Streaming NDJSON:** when `--output json` without `--no-stream`, each event is a JSON line: `{"event":"chunk|tool.call|tool.result|run.completed","data":{...}}`. Parse line-by-line, stop at `run.completed`. -- **`chat abort` is not streaming.** Safe to call. But recovers no work done before abort. -- **Session key vs session ID:** API uses `session_key` (human-readable, stable across resets); list shows both. -- **Token accounting:** `sessions list --output json` includes `input_tokens`/`output_tokens` per session — useful for cost tracing. +- **Session key vs ID:** API uses `session_key` (human-readable, stable); list shows both. Use key for referencing. +- **Branching:** creates new session with copied history up to branch point. Original unchanged. +- **Reset:** clears all messages but preserves agent/user bindings and session key. +- **Compact:** batch deletes. `--older-than` uses relative durations (`30d`, `90d`, `6mo`). No undo. +- **Label:** purely metadata for humans; doesn't affect agent behavior. +- **Token accounting:** session responses include `input_tokens`/`output_tokens` per message. +- **Message pagination:** use `--limit` + `--offset` for large histories to avoid huge JSON. ## Cross-refs -- Approvals from tool calls: [exec-workflow.md](exec-workflow.md) (canonical home) -- Agent lifecycle: [agents-core.md](agents-core.md) -- Traces per LLM call: [monitoring-ops.md](monitoring-ops.md) +- Basic chat operations: [chat-basic.md](chat-basic.md) +- Chat history & replay: [chat-history.md](chat-history.md) +- Message injection: [chat-injection.md](chat-injection.md) +- Agent lifecycle: [agents-crud.md](agents-crud.md) diff --git a/claude-skill/references/credentials.md b/claude-skill/references/credentials.md new file mode 100644 index 0000000..6029b9b --- /dev/null +++ b/claude-skill/references/credentials.md @@ -0,0 +1,121 @@ +# Credentials store + +## When to use + +User wants to manage CLI credentials — list stored credentials, create/delete/rotate credentials, check binary credentials, manage user credential grants, or preset credential options. + +## Commands in scope + +- `goclaw credentials list` — list all stored credentials (source: `cmd/credentials.go`) +- `goclaw credentials create` — store new credential +- `goclaw credentials delete ` — remove credential +- `goclaw credentials update ` — update credential fields +- `goclaw credentials check-binary` — verify credential binary integrity +- `goclaw credentials test ` — test credential (connectivity check) +- `goclaw credentials user-credentials` — manage per-user credential grants +- `goclaw credentials agent-grants` — view/manage agent credential grants +- `goclaw credentials presets` — list credential preset templates + +## Verified flags + +### `credentials create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Credential name | +| `--type ` | string | `api-key`, `bearer`, `oauth`, `ssh`, etc. | +| `--value ` | string | Credential secret (masked in responses) | +| `--expires-in ` | duration | TTL (e.g., `90d`) | + +### `credentials delete` / `credentials test` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | credential ID | — | + +### `credentials user-credentials` +Subcommands: `list`, `grant`, `revoke` (verify with `--help`) + +### `credentials agent-grants` +Subcommands: `list`, `grant`, `revoke` (verify with `--help`) + +## JSON output + +- ✅ `credentials list`, `credentials presets`, `credentials user-credentials list`, `credentials agent-grants list` — JSON +- ⚠️ `credentials create/update/delete/test` — success text only +- ✅ `credentials check-binary` — JSON status + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `credentials delete` | YES (revokes access) | +| `credentials user-credentials revoke` | YES | +| `credentials agent-grants revoke` | YES | + +## Common patterns + +### Example 1: list stored credentials +```bash +goclaw credentials list --output json +# → [ +# {"id": "cred-1", "name": "prod-api-key", "type": "api-key", "created_at": "..."}, +# ... +# ] +``` + +### Example 2: create credential +```bash +goclaw credentials create \ + --name "github-token" \ + --type api-key \ + --value ghp_xxxxxxxxxxxx \ + --expires-in 90d \ + --output json +``` + +### Example 3: test credential +```bash +goclaw credentials test --output json +# → {"valid": true, "checked_at": "..."} +``` + +### Example 4: grant credential to user +```bash +goclaw credentials user-credentials grant \ + --credential-id \ + --user-id \ + --output json +``` + +### Example 5: grant credential to agent +```bash +goclaw credentials agent-grants grant \ + --credential-id \ + --agent-id \ + --output json +``` + +### Example 6: check binary integrity +```bash +goclaw credentials check-binary --output json +# → {"valid": true, "sha256": "..."} +``` + +### Example 7: list credential presets +```bash +goclaw credentials presets --output json +# → credential template options (GitHub, AWS, etc.) +``` + +## Edge cases & gotchas + +- **Secret masking:** `credentials list` returns ID + metadata only; never the actual secret. `create` response shows secret ONCE. +- **Expiry:** expired credentials fail on use. `test` checks before expiry. Pre-rotate before expiry date. +- **User/agent grants:** separate namespaces. User grants control CLI-level access; agent grants control agent runtime access. +- **Binary check:** verifies CLI binary hasn't been tampered with. Useful in untrusted environments. +- **Presets:** templates for common providers (GitHub, AWS, etc.). Reduces manual entry errors. + +## Cross-refs + +- API keys (scoped access): [auth-and-config.md](auth-and-config.md) — `api-keys` +- CLI profiles: [profile.md](profile.md) +- Auth + login: [auth-and-config.md](auth-and-config.md) diff --git a/claude-skill/references/edition.md b/claude-skill/references/edition.md new file mode 100644 index 0000000..702bdd0 --- /dev/null +++ b/claude-skill/references/edition.md @@ -0,0 +1,62 @@ +# Server edition & features + +## When to use + +User wants to check server edition (community, pro, enterprise), available feature set, or license info. **No authentication required** — unauthenticated users can query this. + +## Commands in scope + +- `goclaw edition` — display server edition, features, license (source: `cmd/system.go`, `edition` endpoint) + +## Verified flags + +None — simple read-only command. + +## JSON output + +- ✅ `edition` — JSON object with edition, features, limits + +## Destructive ops + +None — read-only. + +## Common patterns + +### Example 1: check server edition +```bash +goclaw edition --output json +# → { +# "edition": "enterprise", +# "license": "valid until 2026-12-31", +# "features": { +# "multi_tenant": true, +# "sso": true, +# "audit_log": true, +# "backup_restore": true, +# "workstations": true, +# ... +# } +# } +``` + +### Example 2: check specific feature availability +```bash +goclaw edition --output json | jq '.features.workstations' +# → true (feature available in this edition) +``` + +## Edge cases & gotchas + +- **No auth required:** unlike most commands, `goclaw edition` works even without token. Useful for bootstrapping. +- **License expiry:** included in response. Feature access may degrade if license expires. +- **Features vary by edition:** + - **Community:** agents, chat, basic webhooks + - **Pro:** multi-tenant, SSO, API keys, vault + - **Enterprise:** all + audit, workstations, backup/restore, custom MCP, priority support +- **Response format:** may include `trial_days_remaining` if on trial license. + +## Cross-refs + +- License + system health: [admin-system.md](admin-system.md) — `status` +- Backup/restore (enterprise): [backup-restore.md](backup-restore.md) +- Workstations (enterprise): [workstations.md](workstations.md) diff --git a/claude-skill/references/hooks.md b/claude-skill/references/hooks.md new file mode 100644 index 0000000..a89cecb --- /dev/null +++ b/claude-skill/references/hooks.md @@ -0,0 +1,138 @@ +# Event hooks (internal routing) + +## When to use + +User wants to route internal system events (agent starts, chat completes, etc.) to handlers — scripts, tool invocations, or external destinations. Different from `webhooks` (HTTP callbacks). Use hooks for event-driven automation within GoClaw itself. + +## Commands in scope + +- `goclaw hooks list` — list all hooks (source: `cmd/hooks.go`) +- `goclaw hooks get ` — get hook details +- `goclaw hooks create` — create hook from JSON config +- `goclaw hooks update ` — patch hook fields +- `goclaw hooks delete ` — delete a hook (requires `--yes`) +- `goclaw hooks toggle ` — enable/disable hook without deleting +- `goclaw hooks test ` — dry-run hook against sample event (no side-effects) +- `goclaw hooks history ` — show execution history + success/failure logs + +## Verified flags + +### `hooks create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--config ` | string | Hook config JSON (`@filepath` or literal) | + +**Required config fields (JSON):** +- `event` (string) — event type (e.g., `agent.started`, `chat.completed`) +- `scope` (string) — scope (e.g., `system`, `tenant:abc`, `agent:xyz`) +- `handler_type` (string) — handler type (`script`, `tool`, `log`, etc.) +- `name` (string) — display name + +**Optional config fields:** +- `matcher` (object) — filter condition (e.g., `{"agent_type": "coding"}`) +- `if_expr` (string) — CEL expression (if handler supports it) +- `timeout_ms` (int) — execution timeout +- `on_timeout` (string) — action if timeout (`log`, `skip`, `alert`) +- `priority` (int) — execution order +- `agent_ids` (array) — limit to specific agents +- `config` (object) — handler-specific config +- `metadata` (object) — custom metadata + +### `hooks update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--config ` | string | Patch config fields (partial) | + +### `hooks test` +| Flag | Type | Purpose | +| --- | --- | --- | +| (none) | — | Dry-run against sample event (no side-effects) | + +### `hooks toggle` +| Flag | Type | Purpose | +| --- | --- | --- | +| (none) | — | Flips enabled/disabled state | + +## JSON output + +- ✅ `hooks list/get/history` — JSON +- ⚠️ `hooks test` — JSON response (success/failure, handler output) +- ⚠️ `hooks create/update/delete/toggle` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `hooks delete` | YES (hook stops processing events) | + +## Common patterns + +### Example 1: list all hooks +```bash +goclaw hooks list --output json +``` + +### Example 2: create hook from JSON file +```bash +cat > /tmp/hook.json << 'EOF' +{ + "name": "log-agent-starts", + "event": "agent.started", + "scope": "system", + "handler_type": "log", + "config": {"level": "info"} +} +EOF +goclaw hooks create --config=@/tmp/hook.json --output json +``` + +### Example 3: create hook with conditional matcher +```bash +goclaw hooks create --config=@- << 'EOF' +{ + "name": "alert-on-chat-error", + "event": "chat.completed", + "scope": "tenant:acme", + "handler_type": "script", + "matcher": {"status": "error"}, + "config": { + "script": "curl -X POST https://alerting.example.com/hook -d @-" + } +} +EOF +``` + +### Example 4: dry-run hook before enabling +```bash +goclaw hooks test --output json +# → {"success": true, "output": "..."} +``` + +### Example 5: view hook execution history +```bash +goclaw hooks history --output json +# → list of recent executions + results +``` + +### Example 6: toggle hook without deleting +```bash +goclaw hooks toggle +# switch between enabled/disabled +``` + +## Edge cases & gotchas + +- **Event types:** varies by server. Run `goclaw hooks list --help` or check server docs for available event types. +- **Scope format:** `system` (all tenants), `tenant:abc` (specific tenant), `agent:xyz` (specific agent). Scopes are hierarchical. +- **Handler types:** `log`, `script`, `tool`, `webhook` (to external). Each type has different `config` schema. +- **CEL expressions:** `if_expr` allows conditional evaluation. Syntax varies by handler. +- **Timeouts:** if handler runs > `timeout_ms`, `on_timeout` action kicks in (log warning, skip, or escalate). +- **Hook execution order:** controlled by `priority` (lower = earlier). Hooks at same priority run in creation order. +- **Dry-run (`test`):** uses sample event, not real data. Results are indicative, not guaranteed. +- **Hook history:** retention server-dependent. Check server config for retention window. + +## Cross-refs + +- Inbound webhooks (HTTP callbacks): [webhooks.md](webhooks.md) +- Event-driven tool invocation: [exec-workflow.md](exec-workflow.md) +- System configuration: [admin-system.md](admin-system.md) diff --git a/claude-skill/references/oauth.md b/claude-skill/references/oauth.md new file mode 100644 index 0000000..14e6922 --- /dev/null +++ b/claude-skill/references/oauth.md @@ -0,0 +1,108 @@ +# OAuth providers (ChatGPT, OpenAI) + +## When to use + +User wants to authenticate with OAuth providers (ChatGPT, OpenAI) to delegate LLM inference or share account access. CLI guides the browser OAuth flow, persists tokens, checks status, or revokes access. + +## Commands in scope + +- `goclaw oauth start` — start browser OAuth flow (prints auth URL + returns auth_id) (source: `cmd/oauth.go`) +- `goclaw oauth callback ` — complete OAuth flow (submit auth code from browser redirect) +- `goclaw oauth status` — check current OAuth provider authentication status +- `goclaw oauth quota` — show OAuth provider quota/rate-limit usage +- `goclaw oauth logout` — revoke OAuth provider token (requires `--yes`) + +## Verified flags + +### `oauth start` +No flags (flow is automatic). + +### `oauth callback` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Authorization code from browser redirect | + +### `oauth status` +No flags. + +### `oauth quota` +No flags. + +### `oauth logout` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--yes` | bool | **REQUIRED** — confirm revocation | + +## JSON output + +- ✅ `oauth status/quota` — JSON +- ⚠️ `oauth start` — URL to stderr, `auth_id` to stdout (non-JSON by design) +- ⚠️ `oauth callback/logout` — success text + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `oauth logout` | YES (revokes token; agents lose access) | + +## Common patterns + +### Example 1: start OAuth flow +```bash +goclaw oauth start +# Output to stderr (user must open in browser): +# https://accounts.openai.com/authorize?code=...&state=abc123 +# Output to stdout (use in callback): +# abc123 +``` + +### Example 2: complete OAuth flow (in the same script) +```bash +AUTH_ID=$(goclaw oauth start 2>/dev/null) +# user visits URL from stderr, authorizes, browser redirects with code=XYZ +CODE="XYZ" # extracted from redirect URI +goclaw oauth callback $CODE +``` + +### Example 3: check OAuth status +```bash +goclaw oauth status --output json +# → { +# "authenticated": true, +# "provider": "openai", +# "email": "user@example.com", +# "scopes": ["chat.write"], +# "token_expiry": "2026-12-31T23:59:59Z" +# } +``` + +### Example 4: check quota +```bash +goclaw oauth quota --output json +# → { +# "tokens_used_this_period": 500000, +# "rate_limit_per_minute": 100, +# "next_reset": "2026-06-13T00:00:00Z" +# } +``` + +### Example 5: revoke OAuth token +```bash +# Claude: confirm with user — agents lose access to provider +goclaw oauth logout --yes +``` + +## Edge cases & gotchas + +- **Browser redirect:** `oauth start` prints URL to stderr (not stdout) so Claude can capture `auth_id`. User must open URL in browser manually. +- **Auth code TTL:** code from browser redirect expires within minutes. Complete callback quickly. +- **Token refresh:** server auto-refreshes expired tokens. Callback may fail if provider returns new token. +- **Provider scope:** agents access only permitted scopes (read chats, write completions, etc.). Mismatch = 403 errors. +- **Multiple accounts:** CLI tracks one OAuth session per provider. Logging out revokes that session; starting new flow for different user. +- **Quota decay:** quota resets per provider's billing period (not per calendar month). + +## Cross-refs + +- Provider management (LLM providers): [providers-skills-tools.md](providers-skills-tools.md) +- Agent LLM configuration: [agents-core.md](agents-core.md) +- Usage analytics: [monitoring-ops.md](monitoring-ops.md) diff --git a/claude-skill/references/profile.md b/claude-skill/references/profile.md new file mode 100644 index 0000000..2ecef34 --- /dev/null +++ b/claude-skill/references/profile.md @@ -0,0 +1,82 @@ +# CLI profiles (connection config) + +## When to use + +User wants to create, switch, or manage CLI connection profiles (different servers, tenants, or credentials per profile). + +## Commands in scope + +- `goclaw profile list` — list all configured profiles (source: `cmd/profile.go`) +- `goclaw profile current` — print active profile name +- `goclaw profile create` — create new profile +- `goclaw profile use ` — switch active profile (alias for `auth use-context`) +- `goclaw profile delete ` — delete profile + +## Verified flags + +### `profile create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Profile name | +| `--server ` | string | GoClaw server URL | +| `--token ` | string | Auth token (optional; prompt if omitted) | + +### `profile use` / `profile delete` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Profile name | + +## JSON output + +- ✅ `profile list/current` — JSON +- ⚠️ `profile create/use/delete` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `profile delete` | YES (removes local config) | + +## Common patterns + +### Example 1: list profiles +```bash +goclaw profile list --output json +``` + +### Example 2: create new profile +```bash +goclaw profile create \ + --name staging \ + --server https://staging-goclaw.example.com \ + --token sk-... \ + --output json +``` + +### Example 3: switch to profile +```bash +goclaw profile use staging +# subsequent commands use staging server +``` + +### Example 4: check active profile +```bash +goclaw profile current +``` + +### Example 5: delete profile +```bash +goclaw profile delete staging --yes +``` + +## Edge cases & gotchas + +- **vs auth contexts:** `profile` and `auth use-context` are equivalent. Both switch active config. +- **Token storage:** stored in credential store (OS keychain or ~/.goclaw/config.yaml). Never passed in shell history. +- **Default profile:** first profile created is active. Switch explicitly if needed. +- **Server URL:** must be valid HTTPS endpoint. TLS cert must be valid (use `--insecure` global flag to skip, dev only). + +## Cross-refs + +- Auth + login: [auth-and-config.md](auth-and-config.md) +- Credentials store: [credentials.md](credentials.md) diff --git a/claude-skill/references/quota.md b/claude-skill/references/quota.md new file mode 100644 index 0000000..5898cd8 --- /dev/null +++ b/claude-skill/references/quota.md @@ -0,0 +1,60 @@ +# Quota inspection + +## When to use + +User wants to check quota consumption (token usage, API calls, storage, etc.) across all users/agents or for a specific agent. + +## Commands in scope + +- `goclaw quota usage` — show quota consumption (source: `cmd/quota.go`) + +## Verified flags + +### `quota usage` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | string | Filter by specific agent (default: all) | + +## JSON output + +- ✅ `quota usage` — JSON object with quota metrics + +## Destructive ops + +None — read-only. + +## Common patterns + +### Example 1: check system-wide quota +```bash +goclaw quota usage --output json +# → { +# "period": "2026-06-01 to 2026-06-30", +# "total_tokens": 1000000, +# "used_tokens": 750000, +# "remaining": 250000, +# "agents": [ +# {"agent_id": "abc", "tokens_used": 500000}, +# {"agent_id": "xyz", "tokens_used": 250000} +# ] +# } +``` + +### Example 2: check quota for specific agent +```bash +goclaw quota usage --agent --output json +# → {"agent_id": "...", "tokens_used": 500000, "percentage": 50} +``` + +## Edge cases & gotchas + +- **Quota period:** typically monthly, reset on the 1st. Response includes period dates. +- **Token counting:** may vary by model (gpt-4 more expensive than gpt-3.5). Check server docs for counting rules. +- **Soft vs hard limits:** some tenants have soft warnings (80% alerts) vs hard caps (reject requests at 100%). Check `system-config` for limits. +- **Real-time lag:** quota updates may lag 1-5 minutes behind actual usage. Use for trend analysis, not immediate tracking. + +## Cross-refs + +- Usage analytics (cost): [monitoring-ops.md](monitoring-ops.md) — `usage summary/detail` +- Storage quota: [data-movement.md](data-movement.md) — `storage size` +- System configuration: [admin-system.md](admin-system.md) — `system-config` diff --git a/claude-skill/references/system-config.md b/claude-skill/references/system-config.md new file mode 100644 index 0000000..bac4c7e --- /dev/null +++ b/claude-skill/references/system-config.md @@ -0,0 +1,121 @@ +# System configuration & upgrades + +## When to use + +Admin wants to view/manage server-level configuration (schema, defaults, patches), apply bulk config changes, or upgrade the server. + +## Commands in scope + +### Configuration (source: `cmd/config.go`) +- `goclaw config schema` — get full config schema (JSON Schema) +- `goclaw config defaults` — list default config values +- `goclaw config get ` — read config value +- `goclaw config patch ` — apply partial config change (strategic merge) +- `goclaw config apply ` — apply full config (replace entire structure) + +### System Upgrades (source: `cmd/system_upgrade.go`) +- `goclaw system upgrade` — upgrade server to latest version (source: `system_upgrade.go`) + +## Verified flags + +### `config schema` +No flags; returns full JSON Schema. + +### `config defaults` +No flags; returns current defaults. + +### `config get` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Config key path (e.g., `gateway.listen_port`) | + +### `config patch` / `config apply` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | path | YAML/JSON config file (@filepath or stdin) | +| `--dry-run` | bool | Preview changes without applying | + +### `system upgrade` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--version ` | string | Target version (default: latest) | +| `--dry-run` | bool | Preview upgrade steps | +| `--yes` | bool | Skip confirmation | + +## JSON output + +- ✅ `config schema/defaults/get` — JSON +- ✅ `config patch/apply` (with `--dry-run`) — JSON preview +- ⚠️ `config patch/apply` (apply) — success text only +- ✅ `system upgrade` (with `--dry-run`) — JSON preview +- ⚠️ `system upgrade` (apply) — success text + progress + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `config patch` | Recommended (modifies config) | +| `config apply` | **YES** (full replacement) | +| `system upgrade` | **YES** (server restart) | + +## Common patterns + +### Example 1: get config schema +```bash +goclaw config schema --output json | jq '.properties | keys' +``` + +### Example 2: read single config value +```bash +goclaw config get gateway.listen_port --output json +``` + +### Example 3: preview config patch +```bash +cat > /tmp/patch.yaml << 'EOF' +gateway: + max_connections: 1000 +EOF +goclaw config patch /tmp/patch.yaml --dry-run --output json +``` + +### Example 4: apply config patch (merge) +```bash +goclaw config patch /tmp/patch.yaml --output json +# merges patch into current config +``` + +### Example 5: apply full config (replace) +```bash +# Get current, edit, apply +goclaw config get "/" --output json > current.json +# edit current.json +goclaw config apply current.json --dry-run --output json +goclaw config apply current.json --yes +``` + +### Example 6: preview server upgrade +```bash +goclaw system upgrade --version 1.2.0 --dry-run --output json +# → {"steps": [...], "duration_minutes": 5} +``` + +### Example 7: perform server upgrade +```bash +goclaw system upgrade --version 1.2.0 --yes +# → server restarts automatically after upgrade +``` + +## Edge cases & gotchas + +- **Config schema:** shows structure + validation rules. Essential reading before patching. +- **Patch vs apply:** patch = strategic merge (only specified keys updated); apply = full replacement (unspecified keys revert to file content). +- **Dry-run:** previews what *would* happen without writing. Useful for validation. +- **YAML path keys:** use `.` notation for nesting (e.g., `gateway.listen_port`). +- **Server upgrade:** automatic restart. All agents/sessions gracefully paused. Typically 2-5 min downtime. +- **Backup before upgrade:** server auto-backs up config before upgrade. But manual backup recommended. + +## Cross-refs + +- Per-tenant config: [admin-system.md](admin-system.md) — `system-config` +- Server health/status: [monitoring-ops.md](monitoring-ops.md) — `status` diff --git a/claude-skill/references/users.md b/claude-skill/references/users.md new file mode 100644 index 0000000..bc36d15 --- /dev/null +++ b/claude-skill/references/users.md @@ -0,0 +1,62 @@ +# Users (search & management) + +## When to use + +User wants to search for users by email, name, or ID, or check user details. Different from `tenants users` (which is tenant-level user management). Use this for cross-tenant user discovery. + +## Commands in scope + +- `goclaw users search ` — search users by email, name, or ID (source: `cmd/users.go`) + +## Verified flags + +### `users search` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Search term (email prefix, name, or user ID) | + +## JSON output + +- ✅ `users search` — JSON array of user objects + +## Destructive ops + +None — read-only. + +## Common patterns + +### Example 1: search by email prefix +```bash +goclaw users search alice@example.com --output json +# → [ +# {"id": "user_abc123", "email": "alice@example.com", "name": "Alice Chen", "created_at": "2025-01-15"}, +# {"id": "user_def456", "email": "alice.backup@example.com", "name": "Alice (Backup)", "created_at": "2025-02-01"} +# ] +``` + +### Example 2: search by name +```bash +goclaw users search bob --output json +# → [ +# {"id": "user_ghi789", "email": "bob.smith@example.com", "name": "Bob Smith", "created_at": "2025-03-10"}, +# {"id": "user_jkl012", "email": "bob@another.co", "name": "Bob Johnson", "created_at": "2025-04-05"} +# ] +``` + +### Example 3: search by user ID +```bash +goclaw users search user_abc123 --output json +``` + +## Edge cases & gotchas + +- **Search scope:** typically cross-tenant (returns users from all tenants). Use `--tenant-id` global flag if server supports tenant-scoped search. +- **Query format:** free-text substring match. Results ranked by relevance (exact match > prefix > substring). +- **Privacy:** visible users depend on your role and tenants. Non-admins may see only users in their own tenant. +- **Active vs inactive:** response may include deactivated users. Check `active` field. + +## Cross-refs + +- Tenant user management: [admin-system.md](admin-system.md) — `tenants users` +- Authentication + profiles: [auth-and-config.md](auth-and-config.md) +- Team collaboration: [teams-collaboration.md](teams-collaboration.md) diff --git a/claude-skill/references/vault.md b/claude-skill/references/vault.md new file mode 100644 index 0000000..eacfd6b --- /dev/null +++ b/claude-skill/references/vault.md @@ -0,0 +1,138 @@ +# Knowledge Vault + +## When to use + +User wants to manage knowledge base for agents — upload/search documents, manage links/relationships, inspect knowledge graph, or trigger indexing pipeline. Vault enables agents to retrieve relevant context during reasoning. + +## Commands in scope + +- `goclaw vault list` / `goclaw vault documents list` — list vault documents (source: `cmd/vault.go`) +- `goclaw vault documents get ` — get document content + metadata +- `goclaw vault documents create` — create document (plain text) +- `goclaw vault documents update ` — update document fields +- `goclaw vault documents delete ` — delete document +- `goclaw vault upload ` — upload file (multipart streaming; supports .pdf, .txt, .md, etc.) +- `goclaw vault search ` — full-text + vector search (FTS + embeddings) +- `goclaw vault links list ` — show related documents (graph) +- `goclaw vault tree` — show document tree (hierarchy by folder/tag) +- `goclaw vault graph` — get knowledge graph (JSON edges/nodes) +- `goclaw vault enrichment` — manage enrichment pipeline (summarize, extract entities, etc.) +- `goclaw vault rescan` — re-index all documents (admin-only; async, long-running) + +## Verified flags + +### `vault documents create/update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--title ` | string | Document title | +| `--content ` | string | Plain text content (`@filepath` or literal) | +| `--tags ` | CSV | Comma-separated tags for filtering | +| `--metadata ` | JSON | Custom metadata object | + +### `vault upload` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | path | File to upload (.pdf, .txt, .md, .docx, etc.) | +| `--title ` | string | Override detected title | +| `--tags ` | CSV | Tags for the uploaded document | + +### `vault search` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Search query (free-text or semantic) | +| `--limit ` | int | Max results (default 20) | +| `--offset ` | int | Pagination offset | + +### `vault links list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | string | Document ID | + +### `vault tree` +No flags (shows full hierarchy). + +### `vault graph` +No flags (returns full graph as JSON). + +### `vault enrichment` +See subcommands with `--help`. + +### `vault rescan` +Async; returns task ID. Admin-only. + +## JSON output + +- ✅ `vault documents list/get`, `vault search`, `vault links list`, `vault tree`, `vault graph` — JSON +- ✅ `vault upload` — JSON (document ID + metadata) +- ⚠️ `vault documents create/update/delete` — success text (check exit code) +- ✅ `vault enrichment` — varies by subcommand +- ✅ `vault rescan` — JSON task ID + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `vault documents delete` | YES (permanent removal) | + +## Common patterns + +### Example 1: upload document to vault +```bash +goclaw vault upload /tmp/design.pdf --title "System Design" --tags "architecture,v2" --output json +``` + +### Example 2: search vault +```bash +goclaw vault search "microservices scalability" --limit 10 --output json +``` + +### Example 3: list documents +```bash +goclaw vault documents list --output json +``` + +### Example 4: get document + metadata +```bash +goclaw vault documents get --output json +``` + +### Example 5: create plain-text document +```bash +goclaw vault documents create \ + --title "API Guidelines" \ + --content "Endpoints should use REST conventions..." \ + --tags "api,standards" +``` + +### Example 6: inspect knowledge graph +```bash +goclaw vault graph --output json +# → {"nodes": [...], "edges": [...]} +``` + +### Example 7: show related documents +```bash +goclaw vault links list --output json +# → documents linked (via title/tag/semantic similarity) +``` + +### Example 8: re-index vault (admin) +```bash +goclaw vault rescan --output json +# → {"task_id": "..."} +``` + +## Edge cases & gotchas + +- **File uploads:** server supports .pdf, .txt, .md, .docx, .pptx. Binary formats extracted via OCR/text-extraction; large files (>100MB) may be rejected. +- **Vector embeddings:** uploaded documents auto-vectorized for semantic search. Depends on embedding provider (OpenAI, Anthropic, local). +- **Search:** FTS (full-text) + vector search. Queries match keywords + semantic intent. +- **Knowledge graph:** auto-linked via title overlap, shared tags, semantic similarity. Manual link creation not exposed via CLI yet. +- **Rescan:** async + long-running (can take minutes for large vaults). Returns task ID; poll or check server logs. +- **Metadata:** custom fields stored but not indexed. Use tags for searchable attributes. +- **Enrichment pipeline:** optional. Extracts summaries, entities, tables. Admin can enable/configure. + +## Cross-refs + +- Memory (agent-specific, not vault): [knowledge-memory.md](knowledge-memory.md) +- Document export/import: [data-movement.md](data-movement.md) diff --git a/claude-skill/references/voices.md b/claude-skill/references/voices.md new file mode 100644 index 0000000..e929b28 --- /dev/null +++ b/claude-skill/references/voices.md @@ -0,0 +1,65 @@ +# Voice catalog + +## When to use + +User wants to list available voices for TTS (text-to-speech) agents, or refresh the voice catalog from providers (to sync new voices, models). Not for *invoking* TTS (see [exec-workflow.md](exec-workflow.md) for `tools invoke tts`). + +## Commands in scope + +- `goclaw voices list` — list available voices from all configured TTS providers (source: `cmd/voices.go`) +- `goclaw voices refresh` — refresh catalog from providers (admin-only, async) + +## Verified flags + +### `voices list` +No flags beyond globals. + +### `voices refresh` +No flags; admin-only. + +## JSON output + +- ✅ `voices list` — JSON array of voice objects +- ✅ `voices refresh` — JSON response with refresh status/timestamp + +## Destructive ops + +None — read-only or admin refresh. + +## Common patterns + +### Example 1: list all voices +```bash +goclaw voices list --output json +# → [ +# {"id": "en-US-Neural2-A", "name": "en-US Neural 2A", "lang": "en-US", "provider": "google"}, +# {"id": "elevenlabs_bella", "name": "Bella", "lang": "multi", "provider": "elevenlabs"}, +# ... +# ] +``` + +### Example 2: filter voices (client-side) +```bash +goclaw voices list --output json | jq '.[] | select(.lang | startswith("en-US"))' +``` + +### Example 3: refresh voice catalog (admin) +```bash +goclaw voices refresh --output json +# → {"refreshed_at": "2026-06-12T14:30:00Z", "voices_count": 250} +``` + +## Edge cases & gotchas + +- **Voice ID:** used in TTS tool invocation. Format varies by provider (Google: `en-US-Neural2-A`, ElevenLabs: `en_us_bella`). +- **Languages:** most voices are language-specific. Multi-lingual voices rare. +- **Voice speed/pitch:** not exposed in CLI — set in TTS tool config or agent settings. +- **Refresh latency:** providers may take seconds to respond. Refresh is async; new voices appear in `list` after refresh completes. +- **Provider status:** if a TTS provider is down, `voices list` may return stale data. Check `goclaw status` for provider health. +- **Voice deprecation:** providers retire old voices. `refresh` updates the catalog; old voice IDs may fail in TTS invocations. + +## Cross-refs + +- TTS invocation (actually generate speech): [exec-workflow.md](exec-workflow.md) — `tools invoke tts` +- TTS status check: [admin-system.md](admin-system.md) — `tts status` +- Provider management: [providers-skills-tools.md](providers-skills-tools.md) diff --git a/claude-skill/references/webhooks.md b/claude-skill/references/webhooks.md new file mode 100644 index 0000000..329d861 --- /dev/null +++ b/claude-skill/references/webhooks.md @@ -0,0 +1,109 @@ +# Webhooks (inbound) + +## When to use + +User wants to create, manage, or configure **inbound webhooks** — HTTP callbacks triggered by specific events (LLM runs, messages) that POST to external endpoints. Different from `hooks` (internal event routing). + +## Commands in scope + +- `goclaw webhooks list` — list all webhooks (source: `cmd/webhooks.go`) +- `goclaw webhooks get ` — get webhook details (including masked secret) +- `goclaw webhooks create` — create a new webhook +- `goclaw webhooks update ` — update webhook fields (URL, scopes, etc.) +- `goclaw webhooks delete ` — delete a webhook +- `goclaw webhooks rotate ` — rotate webhook signing secret + +## Verified flags + +### `webhooks create/update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Webhook display name | +| `--kind ` | string | `llm` or `message` | +| `--agent-id ` | string | Agent UUID (for LLM webhooks) | +| `--channel-id ` | string | Channel UUID (for message webhooks) | +| `--body ` | string | Webhook payload template (JSON object) | +| `--scopes ` | CSV | Comma-separated webhook scopes (e.g., `run.started,run.completed`) | +| `--require-hmac` | bool | Require HMAC-SHA256 signatures on POST | +| `--ip-allowlist ` | CSV | Comma-separated allowed IP/CIDR (e.g., `10.0.0.0/8,203.0.113.5`) | +| `--localhost-only` | bool | Restrict to localhost/127.0.0.1 callers | +| `--rate-limit-per-min ` | int | Per-webhook rate limit (invokes per minute) | + +### `webhooks delete` +| Flag | Type | Purpose | +| --- | --- | --- | +| (none — use `--yes` to skip confirm) | — | — | + +### `webhooks rotate` +| Flag | Type | Purpose | +| --- | --- | --- | +| (none) | — | Rotates secret; old secret invalidates | + +## JSON output + +- ✅ `webhooks list/get` — JSON +- ⚠️ `webhooks create/update/delete/rotate` — success text only + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `webhooks delete` | YES (webhook stops receiving events) | +| `webhooks rotate` | YES (old secret invalidates immediately; callers must update) | + +## Common patterns + +### Example 1: list webhooks +```bash +goclaw webhooks list --output json +``` + +### Example 2: create LLM webhook +```bash +goclaw webhooks create \ + --name "run-logger" \ + --kind llm \ + --agent-id abc123 \ + --scopes "run.started,run.completed" \ + --body '{"agent_id":"${{AGENT_ID}}","run_id":"${{RUN_ID}}"}' \ + --require-hmac \ + --output json +``` + +### Example 3: create message webhook with IP allowlist +```bash +goclaw webhooks create \ + --name "slack-notifier" \ + --kind message \ + --channel-id chan456 \ + --ip-allowlist "10.0.0.0/8,192.168.0.0/16" \ + --rate-limit-per-min 10 +``` + +### Example 4: update webhook +```bash +goclaw webhooks update \ + --scopes "run.started,run.failed,run.completed" +``` + +### Example 5: rotate secret +```bash +# Claude: confirm with user — old secret becomes invalid +goclaw webhooks rotate --yes +``` + +## Edge cases & gotchas + +- **Webhook secret:** returned only once on create. `webhooks get` shows masked prefix. Save it immediately or rotate. +- **Rate limiting:** per-webhook counter. Bursts exceeding limit get 429 responses; retry logic is caller's responsibility. +- **HMAC signature:** if `--require-hmac`, POST header includes `X-Webhook-Signature: sha256=...`. Caller must verify. +- **IP allowlist vs localhost-only:** mutually exclusive. Use localhost-only for testing; IP allowlist for prod. +- **Scopes vary by kind:** LLM webhooks have `run.*` scopes; message webhooks have `message.*` scopes. See `--help` for current scope list. +- **Payload templates:** `${{AGENT_ID}}`, `${{RUN_ID}}`, etc. are placeholders server substitutes at webhook trigger time. +- **Webhook retry:** if POST fails, server retries up to N times (exponential backoff). Check logs if webhook isn't firing. + +## Cross-refs + +- Event hook routing (internal): [hooks.md](hooks.md) +- LLM traces + run details: [monitoring-ops.md](monitoring-ops.md) +- Channel management: [channels-messaging.md](channels-messaging.md) diff --git a/claude-skill/references/workstations.md b/claude-skill/references/workstations.md new file mode 100644 index 0000000..1e8d213 --- /dev/null +++ b/claude-skill/references/workstations.md @@ -0,0 +1,117 @@ +# Workstations (coding-agent) + +## When to use + +User wants to set up isolated coding environments (workstations) for agents, link/unlink agents to workstations, manage file permissions, or inspect workstation activity. + +## Commands in scope + +- `goclaw workstations list` — list all workstations (source: `cmd/workstations.go`) +- `goclaw workstations get ` — get workstation details + status +- `goclaw workstations create` — create new workstation +- `goclaw workstations update ` — update workstation config +- `goclaw workstations delete ` — delete workstation +- `goclaw workstations link-agent ` — link agent to workstation over WS RPC +- `goclaw workstations unlink-agent ` — unlink agent from workstation +- `goclaw workstations permissions` — manage path-based file permissions +- `goclaw workstations activity ` — list recent activity (file ops, command invocations) + +## Verified flags + +### `workstations create/update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Display name | +| `--workstation-key ` | string | Stable key (for referencing workstation) | +| `--backend-type ` | string | Backend type (e.g., `docker`, `k8s`, `local`) | +| `--default-cwd ` | string | Default working directory (e.g., `/workspace`) | +| `--default-env ` | JSON | Default environment vars as JSON object | +| `--metadata ` | JSON | Custom metadata | + +### `workstations link-agent` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | workstation ID | Workstation to link | +| `--agent-id ` | string | Agent ID to link | + +### `workstations unlink-agent` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | workstation ID | — | +| `--agent-id ` | string | Agent to unlink | + +### `workstations permissions` +See subcommands: `list`, `grant`, `revoke` (flags vary). + +### `workstations activity` +| Flag | Type | Purpose | +| --- | --- | --- | +| `` | workstation ID | — | +| `--limit ` | int | Max log entries | + +## JSON output + +- ✅ `workstations list/get/activity` — JSON +- ⚠️ `workstations create/update/delete/link-agent/unlink-agent` — success text +- ✅ `workstations permissions list` — JSON + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `workstations delete` | YES (agents lose workspace) | + +## Common patterns + +### Example 1: list workstations +```bash +goclaw workstations list --output json +``` + +### Example 2: create workstation with environment +```bash +goclaw workstations create \ + --name "python-ml" \ + --workstation-key "ml-workspace" \ + --backend-type docker \ + --default-cwd "/workspace" \ + --default-env '{"PYTHON_VERSION":"3.11","CONDA_ENV":"ml"}' \ + --output json +``` + +### Example 3: link agent to workstation +```bash +goclaw workstations link-agent \ + --agent-id \ + --output json +``` + +### Example 4: view workstation activity +```bash +goclaw workstations activity --limit 50 --output json +# → recent command invocations, file ops, errors +``` + +### Example 5: manage file permissions +```bash +goclaw workstations permissions list --output json +goclaw workstations permissions grant \ + --path "/workspace/sensitive" \ + --agent-id \ + --access "read-only" +``` + +## Edge cases & gotchas + +- **Backend types:** `docker`, `k8s`, `local` (varies by server). Server must support chosen type. +- **Link/unlink:** WS RPC operations. If workstation unreachable, returns error. Retry or check workstation health. +- **File permissions:** path-based. Deny patterns can exclude sensitive dirs. Agents get 403 if accessing denied paths. +- **Activity log:** retention server-dependent. Check `system-config` for activity retention window. +- **Default env vars:** merged with agent-level env vars. Agent vars override workstation defaults. +- **Metadata:** custom fields stored; not indexed. Useful for tagging (e.g., `{"team": "ml", "region": "us-west"}`). + +## Cross-refs + +- Agent setup + linking: [agents-core.md](agents-core.md) +- Tool invocation (exec): [exec-workflow.md](exec-workflow.md) +- System administration: [admin-system.md](admin-system.md)