component-management

name	component-management
description	Guidelines for managing zylos components via CLI and C4 channels. Use when installing, upgrading, or uninstalling components, or when user asks about available components.

Component Management

Guidelines for installing, upgrading, and managing zylos components.

CLI

zylos is a global npm command (installed via npm install -g zylos). Run it directly as zylos, NOT as ~/zylos/zylos or ./zylos.

General Principles

1. Always confirm before executing - User must explicitly approve install/upgrade/uninstall
2. Guide interactively - Never just tell user to "manually edit files"
3. Read SKILL.md - Each component declares its requirements in SKILL.md frontmatter
4. Detect execution mode - Handle both Claude session and C4 channels differently
5. CLI = mechanical, Claude = intelligent - CLI handles downloads, backups, file sync. Claude handles config, hooks, service management, user interaction.

Workflows

Detailed step-by-step workflows for each operation (Session + C4 modes):

• Install — Add new components
• Upgrade — Upgrade components and zylos-core (self-upgrade)
• Uninstall — Remove components with data options

Quick Commands

# Check zylos-core version
zylos --version

# List installed components (with versions)
zylos list

# Search available components
zylos search <keyword>

# Component status
zylos status

# Check for zylos-core updates
zylos upgrade --self --check

# Check for beta/prerelease updates
zylos upgrade --self --check --beta

# Check all components for updates
zylos upgrade --all --check

SKILL.md Config Format

Components declare their configuration requirements in SKILL.md frontmatter:

---
name: my-component
version: 1.0.0
description: Component description

config:
  required:
    - name: ENV_VAR_NAME
      description: Human-readable description
      sensitive: true  # Optional: marks as secret
  optional:
    - name: OPTIONAL_VAR
      description: Optional setting
      default: "default-value"
---

When sensitive: true, the value should be handled carefully and not logged.

New components may declare a non-interactive configure hook:

lifecycle:
  hooks:
    configure: hooks/configure.js

When present, collect config.required values and pipe them as stdin JSON to the hook. The component owns how those values are stored, usually in ~/zylos/components/<name>/config.json. Components without hooks.configure are legacy-compatible and still receive collected values through ~/zylos/.env.

---

C4 Mode (IM Channels)

When user sends requests via C4 comm-bridge (Telegram, Lark, etc.), use streamlined flows with two-step confirmation. Replies must be plain text (no markdown).

Detecting C4 Mode

The request is from C4 when the message arrives via a communication channel (e.g., <user> said: ... with a reply via: instruction).

C4 Reply Formatting

All --json outputs include structured data and a reply field (pre-formatted fallback).

Preferred: Use the JSON data fields to craft a clear, user-friendly plain text reply. Fallback: If you're unsure how to format the reply, use the reply field directly.

C4 Command Mapping

CRITICAL: "add <name>" and "upgrade <name>" MUST ONLY run --check. NEVER execute install/upgrade without the word "confirm" in the user's message.

CRITICAL: confirm flow now always re-downloads (no temp-dir reuse):

• --check is for preview/analysis only; any temporary download from check is cleaned up after the check completes.
• upgrade <name> confirm and upgrade zylos confirm always download a fresh package.
• Do not pass --temp-dir; it is no longer supported and the CLI will fail fast.

User says	CLI command
list / list components	zylos list
info <name>	zylos info <name> --json
check / check updates	zylos upgrade --all --check --json
check <name>	zylos upgrade <name> --check --json
upgrade <name>	zylos upgrade <name> --check --json (CHECK ONLY)
upgrade <name> confirm	zylos upgrade <name> --yes --skip-eval --json
upgrade <name> beta	zylos upgrade <name> --check --beta --json (CHECK ONLY)
upgrade <name> beta confirm	zylos upgrade <name> --yes --skip-eval --beta --json
add <name>	zylos add <name> --check --json (CHECK ONLY)
add <name> confirm	zylos add <name> --json
upgrade zylos	zylos upgrade --self --check --json (CHECK ONLY)
upgrade zylos confirm	zylos upgrade --self --yes --json
upgrade zylos beta	zylos upgrade --self --check --beta --json (CHECK ONLY)
upgrade zylos beta confirm	zylos upgrade --self --yes --beta --json
uninstall <name>	zylos uninstall <name> --check --json (CHECK ONLY)
uninstall <name> confirm	zylos uninstall <name> confirm --json
uninstall <name> purge	zylos uninstall <name> purge --json

C4 Output Formatting

• Plain text only, no markdown
• For info --json: format as <name> v<version>\nType: <type>\nRepo: <repo>\nService: <name> (<status>)
• For add --check --json: format as <name> (v<version>)\n<description>\nType: <type>\nRepo: <repo>, ask user to confirm
• For add --json (install result): format as <name> installed (v<version>), mention required config if any
• For check --json: format as <name>: <current> -> <latest>, actively analyze changes
• For upgrade result: format as <name> upgraded: <from> -> <to>, include change summary
• For errors: when JSON has both error and message fields, display message (human-readable)

C4 vs Session Differences

Aspect	Claude Session	C4
Confirmation	Interactive dialog	Two-step: preview + "confirm" command
Output format	Rich (emoji, formatting)	Plain text only
Config collection	Interactive prompts	User provides via follow-up messages
Upgrade eval	Claude evaluation runs	Skipped (--skip-eval)