explain-command

name	explain-command
description	Explain any command, concept, or log entry in plain English with a risk rating. Triggers: "what does this do", "explain", "what is", "what happened here", "what does this mean".

Explain Command

MANDATORY: Explain everything at a level a non-developer can understand.

For Commands

When Trent asks "what does [command] do?":

1. Plain English: What this command does, like explaining to a friend over coffee.
2. Analogy: Compare to a real-world action where helpful:
   • systemctl restart openclaw-gateway = "Turning the agent off and on again"
   • chmod 444 = "Laminating a document so nobody can write on it"
   • chmod 600 = "Putting it in a locked drawer only you have the key to"
   • journalctl = "Reading the machine's diary to see what happened"
   • scp = "Copying files from your computer to the server over a secure cable"
   • tar -czf = "Zipping files into an archive for safekeeping"
   • rsync = "Syncing files, like Dropbox but manual"
   • ssh = "Opening a secure remote control session to the server"
   • systemd = "The program that keeps your services running, even after a reboot"
   • grep = "Searching through text for a specific word or pattern"
   • kill = "Telling a program to stop running"
   • nano = "A simple text editor that runs in the terminal"
3. Risk Rating: GREEN / YELLOW / RED
4. What could go wrong: If YELLOW or RED, explain the worst realistic case.
5. Is it reversible?: Can we undo this? How?

For Concepts

When Trent asks "what is [concept]?":

1. One-sentence definition in plain English
2. Why it matters for the KURK agent system specifically
3. Common gotchas or things to watch out for

Common concepts Trent might ask about:

• systemd: The program that manages services on the server. It makes sure the agent starts on boot and restarts if it crashes.
• SSH key: A digital key file that lets you log into the server without a password. Safer than passwords.
• chmod: Sets who can read, write, or run a file. The numbers (like 600 or 444) are shorthand for different permission levels.
• API key: A password that lets one program talk to another program's service. Each service has its own key.
• Gateway: The main OpenClaw program that runs on the server. It manages the agent and handles messages from Telegram.
• Cron job: A scheduled task that runs automatically at set times (like an alarm clock for the computer).
• Model failover: When the primary AI model is unavailable, the system automatically tries backup models.

For Log Output

When Trent shows log lines or error messages:

1. Start with: "Here's what this means in plain English: [summary]"
2. Is this a problem? (yes / no / maybe)
3. If yes: what to do about it (offer /troubleshoot)
4. If no: "This is normal. [brief explanation]"

Common log patterns:

• "429 Too Many Requests" = "The AI provider is rate-limiting us. We're sending too many requests. The system will automatically slow down and retry."
• "Model not allowed" = "CRITICAL: The fallback model isn't in the allowed list. This is the config coupling bug."
• "ECONNREFUSED" = "Can't connect to a service. It might be down or the address might be wrong."
• "401 Unauthorized" = "An API key has expired or is wrong. Need to check and possibly rotate it."

For Files

When Trent asks about a file in the system:

1. What this file is (plain English)
2. Who/what uses it
3. Should Trent ever need to change it? (usually "no" or "only through the proper workflow")
4. What happens if it gets deleted or corrupted?

Rules

• Never assume Trent knows what something means.
• If a concept requires another concept, explain the dependency first.
• Use concrete examples from the KURK system, not abstract ones.
• If unsure about a command's safety, rate it RED and suggest caution.
• Keep explanations short. One paragraph, not an essay.