docs(goclaw-skill): complete reference documentation

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
 

claude-skill/references/agents-core.md → 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 <id>` / `create` / `update <id>` / `delete <id>` — 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 <id>` — wake sleeping agent (source: `agents_wake.go`)
 
 ## Verified flags
 
-### `agents create` / `agents update`
+### `agents create/update`
 | Flag | Type | Purpose |
 | --- | --- | --- |
 | `--name <n>` | 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 <agent-id> --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 <agent-id> --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 <agent-id> --output json
+```
 
+### Update agent
+```bash
+goclaw agents update <agent-id> --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 <file-id> --yes
+```
 
+### Create per-user instance
+```bash
 goclaw agents instances create --user-id user-42 --output json
-goclaw agents wake <agent-id>
+goclaw agents instances list --user-id user-42 --output json
 ```
 
-### Example 5: delete agent (always confirm)
+### Wake agent
 ```bash
-# Claude: echo back "Delete agent <id>? This is permanent." before running:
-goclaw agents delete <agent-id> --yes
+goclaw agents wake <agent-id>
 ```
 
 ## 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)

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 <id> [-o file]` — export agent as .tar.gz (source: `cmd/agents_export.go`)
+- `goclaw agents import <file>` — import with preview (dry-run by default) (source: `cmd/agents_import.go`)
+- `goclaw agents import <file> --apply` — perform import (overwrites)
+- `goclaw agents import-merge <file>` — merge imported agent into existing agent
+
+## Verified flags
+
+### `agents export`
+| Flag | Type | Purpose |
+| --- | --- | --- |
+| `<id>` | agent ID | Agent to export |
+| `-o, --file <path>` | string | Output file (default: stdout) |
+
+### `agents import`
+| Flag | Type | Purpose |
+| --- | --- | --- |
+| `<file>` | path | Archive file (.tar.gz) |
+| `--apply` | bool | Perform import (default: preview only) |
+
+### `agents import-merge`
+| Flag | Type | Purpose |
+| --- | --- | --- |
+| `<file>` | 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 <agent-id> -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)