feat: add cfg skill subcommand — built-in usage guide

cfg skill outputs comprehensive documentation including architecture,
all commands, API endpoints, and tips. Keeps docs in sync with code.

packages/cfg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shazhou/cfg",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "bin": {
     "cfg": "./dist/cli.js"

packages/cfg/src/cli.ts

@@ -16,6 +16,7 @@ import {
   cmdProfile,
   cmdProfileSet,
   cmdProfileUnset,
+  showSkill,
   showHelp,
 } from "./commands.js";
 
@@ -103,6 +104,9 @@ switch (cmd) {
   case undefined:
     showHelp();
     break;
+  case "skill":
+    showSkill();
+    break;
   default:
     console.error(`Unknown command: ${cmd}`);
     showHelp();

packages/cfg/src/commands.ts

@@ -399,6 +399,97 @@ export async function cmdProfileUnset(args: string[]): Promise<void> {
   console.log(`✓ ${key} deleted from public profile`);
 }
 
+export function showSkill(): void {
+  console.log(`# cfg — Config Service CLI Skill
+
+## Overview
+cfg is the CLI for config.shazhou.work, a centralized config/secret management service
+for the 沙洲家族 agent network. Built on Cloudflare Workers + KV.
+
+## Architecture
+- **Scopes**: shared (admin-only write, all read), personal (own agent read/write)
+- **Resolution**: personal overrides shared (personal > shared fallback)
+- **Caching**: local cache with auto-sync (fresh for 1 day, retry after 2h on failure)
+- **Auth**: Bearer token per agent, stored via \`cfg token <TOKEN>\`
+
+## Shell Setup
+Add to .bashrc / .zshrc / .profile:
+  eval $(cfg env)
+
+This exports all config keys (where env=true) as environment variables.
+
+## Common Workflows
+
+### Read/Write Config
+  cfg get <KEY>                    Read from cache (auto-syncs if stale)
+  cfg get --remote <KEY>           Read directly from server
+  cfg set <KEY> <VALUE>            Write to personal scope
+  cfg set --shared <KEY> <VALUE>   Write to shared scope (admin only)
+  cfg set --secret <KEY> <VALUE>   Mark as secret (masked in UI)
+  cfg set --no-env <KEY> <VALUE>   Won't be exported by cfg env
+  cfg unset <KEY>                  Delete from personal scope
+  cfg unset --shared <KEY>         Delete from shared scope (admin only)
+
+### List & Sync
+  cfg list                         List all keys with scope/flags (from cache)
+  cfg sync                         Force sync from server
+  cfg env                          Output export statements for shell
+
+### Flags
+  cfg flags <KEY>                  Show current flags (env, secret)
+  cfg flags <KEY> --no-env         Set no-env flag
+  cfg flags <KEY> --secret         Set secret flag
+  cfg flags <KEY> --no-secret      Remove secret flag
+
+### Public Profile
+Public profile is visible to all authenticated agents. Each agent can only write their own.
+  cfg profile                      Show your own public profile
+  cfg profile <AGENT_ID>           Show another agent's public profile
+  cfg profile set <KEY> <VALUE>    Set a key in your public profile
+  cfg profile unset <KEY>          Delete a key from your public profile
+  cfg profiles                     List all agents with public profiles
+
+Example profile keys: contact, role, telegram_id, github, description
+
+### Admin (requires admin role)
+  cfg admin agents                 List all registered agents
+  cfg admin add <ID> [--admin]     Create token for new agent
+  cfg admin remove <ID>            Revoke all tokens for an agent
+  cfg admin refresh <ID>           Revoke + recreate token
+  cfg admin inspect <ID>           View an agent's resolved config
+
+### Token Management
+  cfg token <TOKEN>                Save auth token locally
+
+## Environment Variables
+  CFG_TOKEN       Auth token (overrides saved token)
+  CFG_ENDPOINT    API endpoint (default: https://config.shazhou.work)
+
+## API Endpoints (for direct HTTP access)
+  GET    /config                   List all resolved keys
+  GET    /config/:key              Read key (personal > shared fallback)
+  PUT    /config/:key?scope=...    Write key (scope: personal|shared)
+  PATCH  /config/:key?scope=...    Update flags only
+  DELETE /config/:key?scope=...    Delete key
+  POST   /config/sync              Full sync (all resolved key-values)
+  GET    /profiles                 List agents with public profiles
+  GET    /profile/:id              Get agent's public profile
+  GET    /profile/:id/:key         Get single public profile key
+  PUT    /profile/:id/:key         Set own public profile key
+  DELETE /profile/:id/:key         Delete own public profile key
+  GET    /admin/agents             List all agents (admin)
+  POST   /admin/token              Create agent token (admin)
+  DELETE /admin/token/:id          Revoke agent tokens (admin)
+  GET    /admin/agent/:id          Inspect agent config (admin)
+  GET    /health                   Health check (no auth)
+
+## Tips
+- Use --secret for sensitive values (API keys, tokens) — they're masked in the web UI
+- Use --no-env for config that shouldn't pollute the shell environment
+- Profile is great for agent contact info, roles, and public metadata
+- Cache is at ~/.config/cfg/cache.json, token at ~/.config/cfg/config.json`);
+}
+
 export function showHelp(): void {
   console.log(`cfg — config.shazhou.work CLI