fix: moving cli skill (#591)

* fix: moving cli skills to root

* chore: updating cli readme

* chore: updating language

* chore: updating docs

.claude/skills/honcho-cli/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: honcho-cli
+description: Inspect and debug Honcho workspaces via the `honcho` CLI. Use when investigating peer representations, memory state, session context, queue status, or dialectic quality — any task that requires introspection of a Honcho deployment.
+allowed-tools: Bash(honcho:*), Bash(jq:*), Read, Grep
+---
+
+# Honcho CLI
+
+`honcho` wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation. Use it to inspect workspace state, debug peer memory, and diagnose the dialectic.
+
+## Output & config
+
+- **TTY**: human-readable tables (default when interactive)
+- **Piped / `--json`**: JSON — collection commands emit arrays, single-resource commands emit objects
+- **Exit codes**: `0` success · `1` client error (bad input, not found) · `2` server error · `3` auth error
+- **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars.
+
+## Command groups
+
+- `honcho config` — CLI configuration
+- `honcho workspace` — inspect, delete, search
+- `honcho peer` — inspect, card, chat, search
+- `honcho session` — inspect, messages, context, summaries
+- `honcho message` — list and get
+- `honcho conclusion` — list, search, create, delete
+
+## Rules
+
+- Always pass `--json` when processing output programmatically.
+- Run `honcho peer inspect` before `honcho peer chat` to understand context.
+- Use `honcho session context` to see exactly what an agent receives.
+- Never run `honcho workspace delete` without `honcho workspace inspect` first.
+- Check queue status when derivation seems stalled.
+- Compare peer card with conclusions to understand memory state.
+
+## Inspection tour
+
+When orienting to a Honcho deployment, walk outside-in:
+
+### 1. Understand the workspace
+
+```bash
+honcho workspace inspect --json
+```
+
+### 2. Find the peer
+
+```bash
+honcho peer list --json
+honcho peer inspect <peer_id> --json
+```
+
+### 3. Check peer's memory
+
+```bash
+honcho peer card <peer_id> --json
+honcho conclusion list --observer <peer_id> --json
+honcho conclusion search "topic" --observer <peer_id> --json
+```
+
+### 4. Debug a session
+
+```bash
+honcho session inspect <session_id> --json
+honcho message list <session_id> --last 20 --json
+honcho session context <session_id> --json
+honcho session summaries <session_id> --json
+```
+
+### 5. Search across workspace
+
+```bash
+honcho workspace search "query" --json
+honcho peer search <peer_id> "query" --json
+```
+
+## Debugging playbook
+
+### Peer not learning?
+
+```bash
+# Is observation enabled?
+honcho peer inspect <peer_id> --json | jq '.configuration'
+
+# Is the deriver queue processing messages?
+honcho workspace queue-status --json
+
+# What conclusions exist?
+honcho conclusion list --observer <peer_id> --json
+honcho conclusion search "expected topic" --observer <peer_id> --json
+```
+
+### Session context looks wrong?
+
+```bash
+# Raw context an agent would receive
+honcho session context <session_id> --json
+
+# Summaries feeding the context
+honcho session summaries <session_id> --json
+
+# Recent message history
+honcho message list <session_id> --last 50 --json
+```
+
+### Dialectic giving bad answers?
+
+```bash
+# What the peer card says
+honcho peer card <peer_id> --json
+
+# Conclusions on the specific topic
+honcho conclusion search "topic" --observer <peer_id> --json
+
+# Exercise the dialectic directly
+honcho peer chat <peer_id> "what do you know about X?" --json
+```

docs/v3/documentation/introduction/vibecoding.mdx

@@ -66,6 +66,24 @@ claude mcp add honcho \
 
 ---
 
+## CLI
+
+Inspect and debug a running Honcho deployment from your terminal. The honcho CLI wraps the Python SDK with agent-friendly defaults — JSON output, structured errors, and commands for every primitive (workspaces, peers, sessions, messages, conclusions).
+
+**Get started:**
+
+```bash
+uv tool install honcho-cli
+honcho init      # configure apiKey + environmentUrl
+honcho doctor    # verify connectivity
+```
+
+The CLI also ships an agent skill. Install it with `npx skills add plastic-labs/honcho` and pick `honcho-cli` from the list.
+
+See the [full CLI reference](/v3/documentation/reference/cli) for all commands, flags, and environment variables.
+
+---
+
 ## Claude Code Plugin
 
 Use Honcho to build with Honcho! The [plugin](/v3/guides/integrations/claudecode) provides Claude Code persistent memory that survives context wipes and session restarts.
@@ -109,6 +127,12 @@ curl -o ~/.claude/skills/honcho-integration.md https://raw.githubusercontent.com
 
 Invoke with `/honcho-integration` in your coding agent.
 
+#### honcho-cli
+
+**For inspection & debugging.** Teaches your coding agent the right commands and flags for the [honcho CLI](#cli) — peer memory, session context, queue status, dialectic quality.
+
+Invoke implicitly when you ask your agent to inspect a Honcho deployment.
+
 #### migrate-honcho-py / migrate-honcho-ts
 
 **For SDK upgrades.** Migrates code from v1.6.0 to v2.0.0 (required for Honcho 3.0.0+). Use when upgrading the SDK or seeing errors about removed APIs like `observations`, `Representation`, `.core`, or `get_config`.
@@ -140,6 +164,7 @@ I want to start building with Honcho - an open source memory library for buildin
 - Core repo: https://github.com/plastic-labs/honcho
 - Python SDK: https://github.com/plastic-labs/honcho-python
 - TypeScript SDK: https://github.com/plastic-labs/honcho-node
+- CLI (inspect & debug a deployment): https://github.com/plastic-labs/honcho/tree/main/honcho-cli
 - Discord bot starter: https://github.com/plastic-labs/discord-python-starter
 - Telegram bot example: https://github.com/plastic-labs/telegram-python-starter
 

honcho-cli/README.md

@@ -19,16 +19,6 @@ As a standalone tool (recommended):
 uv tool install honcho-cli
 ```
 
-As an extra on the Honcho SDK (if you want both the SDK and the CLI in one project):
-
-```bash
-uv add honcho-ai[cli]
-# or
-pip install honcho-ai[cli]
-```
-
-Either way, you'll get the `honcho` command on your PATH.
-
 ## Quick Start
 
 ```bash
@@ -142,6 +132,16 @@ Non-interactive onboarding:
 HONCHO_API_KEY=hch-v3-xxx honcho init --base-url https://api.honcho.dev
 ```
 
+## Agent skill
+
+`honcho-cli` ships with a skill that teaches agents the right commands and conventions for inspecting and debugging a Honcho deployment. Install it anywhere skills are accepted (Claude Code, other skill-aware agents):
+
+```bash
+npx skills add plastic-labs/honcho
+```
+
+The picker lists every skill for Honcho — select `honcho-cli` .
+
 ## Environment Variables
 
 All `HONCHO_*` env vars work at runtime — no config file required.

honcho-cli/src/honcho_cli/skills/CONTEXT.md

@@ -1,50 +0,0 @@
----
-name: honcho-cli
-version: 0.1.0
-description: A terminal for Honcho — memory that reasons.
----
-
-# Honcho CLI — Agent Interface
-
-## Overview
-
-`honcho` is a CLI for administering and debugging Honcho workspaces. It wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation.
-
-## Output Modes
-
-- **TTY**: Human-readable tables (default when interactive)
-- **Piped/scripted**: JSON automatically
-- `--json`: Force JSON output
-
-## Exit Codes
-
-- 0: Success
-- 1: Client error (bad input, not found)
-- 2: Server error
-- 3: Auth error
-
-## Config
-
-Shared with other Honcho tools at `~/.honcho/config.json`. The CLI owns only
-`apiKey` and `environmentUrl` at the top level. Host-specific
-entries under `hosts` are untouched.
-
-Run `honcho init` to confirm or set those two values. Workspace / peer /
-session are per-command — pass them via flags or env vars:
-
-```bash
-honcho peer card -w my-workspace -p my-peer
-# or
-export HONCHO_WORKSPACE_ID=my-workspace
-export HONCHO_PEER_ID=my-peer
-honcho peer card
-```
-
-## Command Groups
-
-- `honcho config` — Manage CLI configuration
-- `honcho workspace` — Inspect, delete, search workspaces
-- `honcho peer` — Inspect, card, chat, search peers
-- `honcho session` — Inspect, messages, context, summaries
-- `honcho message` — List and get messages
-- `honcho conclusion` — List, search, create, delete conclusions

honcho-cli/src/honcho_cli/skills/honcho-debug.md

@@ -1,54 +0,0 @@
----
-name: honcho-cli-debug
-version: 0.1.0
-description: Debug Honcho peer representations and memory
----
-
-# Honcho CLI — Debug Skills
-
-## Rules
-
-- Check queue status when derivation seems stalled
-- Compare peer card with conclusions to understand memory state
-
-## Debugging Memory Issues
-
-### Peer not learning?
-
-```bash
-# Check if observation is enabled
-honcho peer inspect <peer_id> --json | jq '.configuration'
-
-# Check queue — are messages being processed?
-honcho workspace queue-status --json
-
-# Check what conclusions exist
-honcho conclusion list --observer <peer_id> --json
-honcho conclusion search "expected topic" --observer <peer_id> --json
-```
-
-### Session context looks wrong?
-
-```bash
-# See raw context
-honcho session context <session_id> --json
-
-# Check summaries
-honcho session summaries <session_id> --json
-
-# Check message history
-honcho message list <session_id> --last 50 --json
-```
-
-### Dialectic giving bad answers?
-
-```bash
-# Check what the peer card says
-honcho peer card <peer_id> --json
-
-# Check conclusions for the specific topic
-honcho conclusion search "topic" --observer <peer_id> --json
-
-# Try the dialectic directly
-honcho peer chat <peer_id> "what do you know about X?" --json
-```

honcho-cli/src/honcho_cli/skills/honcho-inspect.md

@@ -1,53 +0,0 @@
----
-name: honcho-cli-inspect
-version: 0.1.0
-description: Inspect Honcho workspace state for debugging
----
-
-# Honcho CLI — Inspection Skills
-
-## Rules
-
-- Always use `--json` when processing output programmatically
-- Run `honcho peer inspect` before `honcho peer chat` to understand context
-- Use `honcho session context` to see exactly what an agent receives
-- Never run `honcho workspace delete` without `honcho workspace inspect` first
-
-## Inspection Workflow
-
-### 1. Understand the workspace
-
-```bash
-honcho workspace inspect --json
-```
-
-### 2. Find the peer
-
-```bash
-honcho peer list --json
-honcho peer inspect <peer_id> --json
-```
-
-### 3. Check peer's memory
-
-```bash
-honcho peer card <peer_id> --json
-honcho conclusion list --observer <peer_id> --json
-honcho conclusion search "topic" --observer <peer_id> --json
-```
-
-### 4. Debug a session
-
-```bash
-honcho session inspect <session_id> --json
-honcho message list <session_id> --last 20 --json
-honcho session context <session_id> --json
-honcho session summaries <session_id> --json
-```
-
-### 5. Search across workspace
-
-```bash
-honcho workspace search "query" --json
-honcho peer search <peer_id> "query" --json
-```