/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](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 |