component-management

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](references/install.md) — Add new components
• [Upgrade](references/upgrade.md) — Upgrade components and zylos-core (self-upgrade)
• [Uninstall](references/uninstall.md) — 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) |