hostctl 0.1.40 → 0.1.42

package/README.md

@@ -1,1039 +1,197 @@
 # hostctl
 
-`hostctl` is a modern, lightweight alternative to tools like Ansible, designed with simplicity and ease of use at its core. The primary goal of `hostctl` is to provide a straightforward and consistent way to execute scripts on both local and remote hosts. It aims for portability across all POSIX-style systems.
+`hostctl` is a modern task runner for managing fleets of hosts. It executes TypeScript or JavaScript automations locally or over SSH while keeping inventories, tags, and secrets in one place.
 
-For detailed information on Hostctl's architecture and design, please see the [ARCHITECTURE.md](ARCHITECTURE.md) document.
-For notes on developing and contributing to Hostctl, refer to the [CONTRIBUTING.md](CONTRIBUTING.md) document.
+## Why hostctl
+- Treat remote automation like regular code: tasks are modules with strong typing and structured logging.
+- First-class inventory and secrets management built around [AGE](https://age-encryption.org/).
+- Layered runtime cleanly separates CLI parsing, orchestration, and execution for easy extension.
 
-## Quick start
+## System Requirements
+- Node.js **24+** (CLI runs through `tsx`).
+- [`age`](https://age-encryption.org) for encrypting secrets.
+- Git (recommended) for cloning packages and publishing tasks.
 
-### Install age
-
-```
-❯ brew install age
-
-```
-
-### Generate keys
-
-```
-~
-❯ mkdir -p ~/.hostctl/age
-
-~
-❯ cd .hostctl
-
-~/.hostctl
-❯ age-keygen -o age/johndoe.priv
-Public key: age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-
-~/.hostctl
-❯ age-keygen -y age/johndoe.priv
-age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-
-~/.hostctl
-❯ age-keygen -y age/johndoe.priv > age/johndoe.pub
-
-~/.hostctl
-❯ cat age/johndoe.priv
-# created: 2025-05-24T14:24:12-05:00
-# public key: age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-AGE-SECRET-KEY-1G403WGS9Z599V2NMK923LWCUFJGRR6LXZ72A3UT95U7AMM5SADESZH7M7P
-
-~/.hostctl
-❯ cat age/johndoe.pub
-age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-
-~/.hostctl
-❯ age-keygen -o age/janedoe.priv
-Public key: age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
-
-~/.hostctl
-❯ age-keygen -y age/janedoe.priv > age/janedoe.pub
-
-~/.hostctl
-❯ cat age/janedoe.priv
-# created: 2025-05-24T14:26:36-05:00
-# public key: age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
-AGE-SECRET-KEY-1M4P4NQY8HEUGRJMWSPQ35J5W2SMUR7VLQULYX7HQ639C6XX8NGPQQ8Z5M7
-
-~/.hostctl
-❯ cat age/janedoe.pub
-age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
-```
-
-### Create hostctl config file
-
-```
-~
-❯ mkdir -p ~/.hostctl/age
-
-~
-❯ cd .hostctl
-
-~/.hostctl
-❯ cat <<EOF > hostctl.yaml
-hosts:
-  debian-vm:
-    hostname: 192.168.56.11
-    user: vagrant
-    password: !secret vagrant-password
-    tags: [debian, testvm]
-
-  ubuntu-vm:
-    hostname: 192.168.56.15
-    user: vagrant
-    password: !secret vagrant-password
-    tags: [ubuntu, testvm]
-
-secrets:
-  vagrant-password:
-    ids: johndoe, janedoe
-    value: vagrant
-
-ids:
-  johndoe: age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-  janedoe: age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
-EOF
-
-~/.hostctl
-❯ tree
-.
-├── age
-│   ├── janedoe.priv
-│   ├── janedoe.pub
-│   ├── johndoe.priv
-│   └── johndoe.pub
-└── hostctl.yaml
-
-2 directories, 5 files
-```
-
-#### Host Configuration Details
-
-When defining hosts in your `hostctl.yaml`:
-
-- The **key** for each entry under the `hosts:` map **is** the network identifier (hostname or IP address) for that host. This key is directly used as the `hostname` for connection and identification purposes.
-
-For example:
-
-```yaml
-hosts:
-  # The key '192.168.56.11' is the hostname.
-  192.168.56.11:
-    alias: debian1 # An optional alias for convenience
-    user: vagrant
-    # Any 'hostname: some.other.address' field here would be ignored for connection.
-
-  # The key 'my-web-server' is treated as the hostname.
-  # Ensure 'my-web-server' is resolvable if it's not an IP.
-  my-web-server:
-    user: admin
-```
-
-The `Host` object within `hostctl` stores this key as its `hostname` property. When the configuration is saved (e.g., after decryption or other modifications), this `hostname` (which was the original key) will be written to an explicit `hostname` field in the YAML output for that host entry. This ensures that even if the key was, for example, an IP address, it's preserved and clearly identifiable in the output YAML.
-
-### Run a task
-
-The `hostctl run <script_path> [params...]` command executes the specified script on your local machine. Within the script, you can use the `context.ssh(...)` method to connect to remote hosts defined in your inventory and perform operations on them.
-
-export AGE_IDS="~/.hostctl/age/johndoe.priv ~/.hostctl/age/janedoe.priv"
-
-hostctl on  HEAD (dd3d7ff) [?] is 📦 v0.1.31 via 🥟 v1.2.10 via 🦕 via  v23.11.0 took 13s
-❯ hostctl run example/reachable.ts
-run: /home/david/sync/projects/monopod/hostctl/example/reachable.ts {}
-✔ Enter your password
-=== Evaluation ===
-✓ Reachable
-✓ echo foo,bar,baz
-✓ echo foo,bar,baz
-✓ os
-✓ echo 1,1,1
-✓ echo 2,2,2
-✓ echo 3,3,4
-=== Result ===
-{ value: 'foo' }
-
-hostctl on  HEAD (dd3d7ff) [?] is 📦 v0.1.31 via 🥟 v1.2.10 via 🦕 via  v23.11.0 took 17s
-❯ hostctl run example/echo.ts args:foo,bar
-run: /home/david/sync/projects/monopod/hostctl/example/echo.ts { args: [ 'foo', 'bar' ] }
-=== Evaluation ===
-✓ echo foo,bar
-=== Result ===
-undefined
-
-```
-
-### Encrypt and decrypt inventory
-
-
-```
-
-hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
-❯ hostctl inventory -c example/hostctl.yaml encrypt
-Encrypting inventory file: example/hostctl.yaml
-
-hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
-❯ cat example/hostctl.yaml
-hosts:
-debian-vm:
-user: vagrant
-password: !secret vagrant-password
-tags: - debian - test - example - debian-vm
-ubuntu-vm:
-user: vagrant
-password: !secret vagrant-password
-tags: - ubuntu - test - example - ubuntu-vm
-secrets:
-vagrant-password:
-ids: - johndoe - janedoe
-value: |
------BEGIN AGE ENCRYPTED FILE-----
-YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBRc0NING5YRlpJdFFoQjJS
-MGdzdVIzWElkMDBPM2RkNVE2ZUpucDhGVVN3CnpsdlpxQzJWaTRwSXl0WmxUT2tJ
-bER5SEk5Wm9IWmhTVXkrNFRpL3BsbzAKLT4gWDI1NTE5IFZ2OU94aThZQXJQNjl5
-ZEk1eWg0QWE5T2pKQVA2a1dvOC9FeXAvL3Q2RFEKbHpGUzJiU1dMNEV4OHFkd0pt
-dS9TSVEwRlU2ZW9mUnhNdk9JdmEwVGU1RQotLS0gdkM3VmwvYzNEejE4OUU2blJI
-d3NzVzZsREJ6Q3NjbEh2ai9qc3JxMGVOVQrgAqyjMEvOF2ifd02P/fr/AJzVKGdO
-qjcfnTSO6aztc8oLxqvvb+w=
------END AGE ENCRYPTED FILE-----
-ids:
-johndoe: - age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-janedoe: - age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
-
-hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
-❯ AGE_IDS="example/sample-age-ids/\*.priv" hostctl inventory -c example/hostctl.yaml decrypt -v
-Decrypting inventory file: example/hostctl.yaml
-Decrypted with one or more of the following private keys:
-example/sample-age-ids/johndoe.priv
-example/sample-age-ids/janedoe.priv
-
-hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
-❯ cat example/hostctl.yaml
-hosts:
-debian-vm:
-user: vagrant
-password: !secret vagrant-password
-tags: - debian - test - example - debian-vm
-ubuntu-vm:
-user: vagrant
-password: !secret vagrant-password
-tags: - ubuntu - test - example - ubuntu-vm
-secrets:
-vagrant-password:
-ids: - johndoe - janedoe
-value: vagrant
-ids:
-johndoe: - age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
-janedoe: - age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
-
-````
-
-## Vision
-
-The vision for `hostctl` is to be an Ansible replacement that is significantly easier to use, with simple and intuitive semantics. It empowers users to manage and interact with hosts efficiently, whether for development, operations, or personal use.
-
-## Key Features
-
-*   **Simplified Host Interaction:** Run scripts seamlessly on local or remote machines.
-*   **Cross-Platform Portability:** Designed to work consistently across POSIX-compliant systems.
-*   **Flexible Scripting:** Write `hostctl` scripts in JavaScript or TypeScript.
-
-## Core Tasks
-
-`hostctl` includes a library of core tasks that can be used within your scripts to perform common system administration operations. These tasks are designed to be idempotent and portable across POSIX-compliant systems.
-
-### File and Directory Management
-- **`core.dir.copy`**: Recursively copies a directory.
-- **`core.dir.create`**: Creates a directory.
-- **`core.dir.exists`**: Checks if a directory exists.
-- **`core.file.chgrp`**: Changes the group of a file.
-- **`core.file.chmod`**: Changes the mode of a file.
-- **`core.file.chown`**: Changes the owner of a file.
-- **`core.file.copy`**: Copies a file.
-- **`core.file.delete`**: Deletes a file.
-- **`core.file.edit`**: Edits a file in place.
-- **`core.file.exists`**: Checks if a file exists.
-- **`core.file.grep`**: Searches for a pattern in a file.
-- **`core.file.link`**: Creates a symbolic link.
-- **`core.file.touch`**: Creates an empty file.
-
-### System and Host Management
-- **`core.host.hostname`**: Get or set the hostname.
-- **`core.host.info`**: Gathers information about the host (OS, architecture, etc.).
-- **`core.host.os`**: Provides OS-specific information.
-- **`core.hosts_file.add_entry`**: Adds an entry to `/etc/hosts`.
-- **`core.system.reboot`**: Reboots the system.
-- **`core.system.reboot_if_needed`**: Reboots the system if a reboot is required.
-- **`core.system.reboot_needed`**: Checks if a reboot is required.
-- **`core.system.shutdown`**: Shuts down the system.
-
-### User and Group Management
-- **`core.group.create`**: Creates a user group.
-- **`core.group.delete`**: Deletes a user group.
-- **`core.group.exists`**: Checks if a user group exists.
-- **`core.group.list`**: Lists user groups.
-- **`core.group.modify`**: Modifies a user group.
-- **`core.user.add_groups`**: Adds a user to groups.
-- **`core.user.create`**: Creates a user.
-- **`core.user.delete`**: Deletes a user.
-- **`core.user.exists`**: Checks if a user exists.
-- **`core.user.get_gid`**: Gets the group ID of a user.
-- **`core.user.get_groups`**: Gets the groups a user belongs to.
-- **`core.user.get_uid`**: Gets the user ID of a user.
-- **`core.user.get_username`**: Gets the username of the current user.
-- **`core.user.home_dir`**: Gets the home directory of a user.
-- **`core.user.set_groups`**: Sets the groups for a user.
-- **`core.user.set_shell`**: Sets the login shell for a user.
-- **`core.whoami`**: Gets the current user's username.
-
-### Package Management
-- **`core.pkg.info`**: Gathers information about a package.
-- **`core.pkg.install`**: Installs a package.
-- **`core.pkg.is_installed`**: Checks if a package is installed.
-- **`core.pkg.remove`**: Removes a package.
-- **`core.pkg.update`**: Updates a package.
-
-#### Abstract Package Management (Cross-Platform, Non-Interactive)
-- **`core.pkg.abstract-install`**: Install packages using auto-detected or specified package manager (non-interactive, no progress bars).
-- **`core.pkg.abstract-uninstall`**: Uninstall packages using auto-detected or specified package manager (non-interactive, no progress bars).
-- **`core.pkg.abstract-update`**: Update package sources using auto-detected or specified package manager (non-interactive, no progress bars).
-- **`core.pkg.abstract-upgrade`**: Upgrade packages using auto-detected or specified package manager (non-interactive, no progress bars).
-- **`core.pkg.abstract-search`**: Search for packages using auto-detected or specified package manager (non-interactive, no progress bars).
-- **`core.pkg.abstract-list`**: List installed packages using auto-detected or specified package manager (non-interactive, no progress bars).
-- **`core.pkg.abstract-clean`**: Clean package cache using auto-detected or specified package manager (non-interactive, no progress bars).
-
-**Supported Package Managers**: Apt, Apk, Yum, Dnf, Pacman, Zypper, Eopkg, Winget, Choco, Brew
-
-**Non-Interactive Features**: All abstract package management tasks run completely non-interactively with:
-- No user prompts or confirmations
-- No progress bars or interactive indicators
-- No color output or terminal formatting
-- Automatic confirmations via environment variables and command flags
-- Clean, machine-readable output suitable for CI/CD pipelines
-
-### Service and Process Management
-- **`core.systemd.disable`**: Disables a systemd service.
-- **`core.systemd.enable`**: Enables a systemd service.
-- **`core.systemd.reload`**: Reloads a systemd service.
-- **`core.systemd.restart`**: Restarts a systemd service.
-- **`core.systemd.start`**: Starts a systemd service.
-- **`core.systemd.status`**: Gets the status of a systemd service.
-- **`core.systemd.stop`**: Stops a systemd service.
-
-### Version Control
-- **`core.git.checkout`**: Checks out a git branch or commit.
-- **`core.git.clone`**: Clones a git repository.
-- **`core.git.pull`**: Pulls changes from a git repository.
-
-### Networking and Firewall
-- **`core.ufw.deny`**: Denies traffic with UFW.
-- **`core.ufw.disable`**: Disables UFW.
-- **`core.ufw.enable`**: Enables UFW.
-- **`core.ufw.install`**: Installs UFW.
-- **`core.ufw.reload`**: Reloads UFW rules.
-
-### Miscellaneous
-- **`core.echo`**: Prints a message.
-- **`core.remote.runAllRemote`**: Runs a task on all remote hosts.
-- **`core.ssh.copy_id`**: Copies an SSH key to a remote host.
-- **`core.sudoers.check`**: Checks the sudoers file for a user.
-- **`core.sudoers.grant-nopasswd`**: Grants passwordless sudo to a user.
-- **`core.template.write`**: Writes a file from a template.
-- **`core.k3s.k3sup-install`**: Installs k3s using k3sup.
-
-## CLI Usage
-
-The `hostctl` command-line interface (CLI) is the primary way to interact with the tool.
-
-### Global Options
-
-These options can be applied to most `hostctl` commands:
-
-*   `-q, --quiet`: Reduces the verbosity of output. Can be specified multiple times (e.g., `-qq`) for even less output.
-*   `-v, --verbose`: Increases the verbosity of output. Can be specified multiple times (e.g., `-vv`, `-vvv`) for more detailed logs. The default level typically shows warnings and errors.
-*   `-c, --config <path>`: Specifies the path to the configuration file (e.g., `my-config.yaml`) or an HTTP/HTTPS URL for a remote configuration. Defaults to `./hostctl.yaml`.
-*   `-o, --output <style>`: Sets the output style. Supported styles are `plain` (default, human-readable) and `json` (machine-readable).
-*   `--json`: A convenient shortcut for `-o json`.
-*   `--api`: Enables API mode, which implies JSON output and may include more structured data suitable for programmatic consumption.
-*   `-p, --password`: If set, `hostctl` will prompt the user for a password (e.g., for `sudo` access on hosts) if a task requires it.
-*   `-t, --tag <tags...>`: Filters the target hosts based on tags defined in the inventory. Only hosts matching all specified tags will be selected. For example, `-t webapp backend` or `-t region:europe`.
-
-### Commands
-
-#### `run` (alias: `r`)
-
-This is the **default command**. It executes a `hostctl` script.
-
-**Usage:**
+Check your toolchain:
 
 ```bash
-hostctl run [package_or_bundle] [script] [script_arguments...]
-````
-
-- **`package_or_bundle`** (optional):
-  - A path to a local directory containing the script or package (e.g., `./scripts`, `/opt/myproject`).
-  - A URL to a Git repository (e.g., `https://github.com/yourorg/hostctl-scripts.git`). `hostctl` will clone it temporarily.
-  - A path to a local `.zip` file (a "bundle") created by the `bundle` command.
-- **`script`** (optional, especially if `package_or_bundle` is a bundle with a default script):
-  - The name or path of the script file to execute (e.g., `main.ts`, `deploy.js`).
-  - If `package_or_bundle` is provided, this is relative to the package root.
-  - If `package_or_bundle` is omitted, this is treated as a path relative to the current working directory.
-- **`script_arguments...`** (optional):
-  - Any additional arguments passed directly to the script being executed. These can be simple values or key-value pairs.
-
-**Options:**
-
-- `-f, --file <path>`: Loads script parameters from a specified JSON file. The file should contain a single JSON object.
-- `--params "<json_string>"`: Supplies script parameters as a JSON string directly on the command line (e.g., `--params '{"target_env":"production","retries":3}'`).
-- `-r, --remote`: Executes the script on remote hosts (as defined in the inventory and filtered by tags) instead of on the local machine. Defaults to `false` (local execution).
-
-**Examples:**
-
-```bash
-# Run a local script
-hostctl run deploy.ts
-
-# Run a script from a local directory, passing arguments
-hostctl run ./my-scripts provision.js server_name=app01 zone=us-west
-
-# Run a script from a Git repository with parameters from a file
-hostctl run https://github.com/user/hostctl-scripts.git setup-db.ts -f params.json --remote
-
-# Run a script on remote hosts tagged 'database'
-hostctl run -t database -r check-replication.ts
+node -v
+npm -v
+age --version
 ```
 
-**Task Script Return Value**
-
-When a task script is executed using `hostctl run`, the value returned by the main task function (typically the default export of your script) is considered the primary result of the task.
-
-- **Standard Output:** By default, `hostctl` will display this result along with other evaluation details.
-- **JSON Output (`--json` or `-o json`):** If the `--json` flag (or its equivalent `-o json`) is specified, `hostctl` will output a JSON-serialized representation of the script's return value. When in JSON mode, this serialized result is the _only_ value rendered to standard output, suppressing other logs and evaluation details to ensure clean, machine-readable output. This is particularly useful for programmatic consumption of task results.
-
-#### `exec` (alias: `e`)
-
-Executes an ad-hoc shell command on the selected hosts.
-
-**Usage:**
+## Install hostctl
 
+### Clone & Develop
 ```bash
-hostctl exec "<command_string>"
+git clone https://github.com/monopod/hostctl.git
+cd hostctl
+npm install
 ```
+Use `./hostctl` during development or `npm run build && ./dist/bin/hostctl.js ...` to test the bundled CLI.
 
-- **`<command_string>`**: The shell command to execute. Enclose in quotes if it contains spaces or special characters.
-
-**Examples:**
-
-```bash
-# Check disk space on all targeted hosts
-hostctl exec "df -h"
-
-# Restart a service on hosts tagged 'webserver'
-hostctl exec -t webserver "sudo systemctl restart nginx"
-```
-
-#### `bundle` (alias: `b`)
-
-Packages a directory (typically a project with scripts and a `package.json`) into a deployable `.zip` bundle.
-
-**Usage:**
-
+### Global CLI
 ```bash
-hostctl bundle [path]
+npm install -g hostctl
+hostctl --help
 ```
 
-- **`[path]`** (optional): The path to the directory to bundle. Defaults to the current directory (`.`).
-
-**Examples:**
-
-```bash
-# Bundle the project in the current directory
-hostctl bundle
-
-# Bundle a project in a specific directory
-hostctl bundle ./my-hostctl-project
-```
-
-#### `pkg`
-
-Manages `hostctl` packages with a comprehensive package management system that maintains a manifest of installed packages and their tasks.
-
-**Usage:**
-
+### One-off Execution
+Run straight from npm without installing globally:
 ```bash
-hostctl pkg [subcommand]
-```
-
-**Subcommands:**
-
-- **`create <package-name>`**
-  - Scaffolds a new `hostctl` package in the current directory.
-  - **Usage:** `hostctl pkg create my-new-task`
-  - **Options:**
-    - `--lang <language>`: Specify the language for the package (`typescript` or `javascript`). Defaults to `typescript`.
-
-- **`install <package-source>`**
-  - Installs a `hostctl` package and maintains it in the package manifest.
-  - The `<package-source>` can be a local path, a Git URL, or an npm package name.
-  - **Usage:**
-
-    ```bash
-    # Install from a local directory
-    hostctl pkg install ./my-local-task
-
-    # Install from a Git repository
-    hostctl pkg install https://github.com/user/my-hostctl-task.git
-
-    # Install from npm
-    hostctl pkg install my-npm-hostctl-task
-    ```
-
-- **`list`** (alias: `ls`)
-  - Lists all installed `hostctl` packages with their discovered tasks.
-  - **Usage:** `hostctl pkg list` or `hostctl pkg ls`
-  - **Output Example:**
-
-    ```
-    Found 1 package(s):
-
-    • hostsfile (v1.0.0) - hostsfile package [https_github.com_davidkellis_hostsfile]
-      └─ add_entry
-    ```
-
-- **`remove <package-identifier>`** (alias: `rm`)
-  - Removes an installed `hostctl` package and updates the manifest.
-  - The `<package-identifier>` can be either the package name or the directory name.
-  - **Usage:** `hostctl pkg remove my-package` or `hostctl pkg rm my-package`
-
-## Package Management System
-
-`hostctl` includes a comprehensive package management system that allows you to install, manage, and run tasks from external packages. This system maintains a manifest of installed packages and provides intelligent task discovery and resolution.
-
-### Package Manifest
-
-The package management system maintains a `manifest.json` file in `~/.hostctl/packages/` that tracks all installed packages. This manifest contains:
-
-- **Package Source Mapping**: Each package source (URL, Git repo, local path) is mapped to package information
-- **Package Metadata**: Name, version, description, and installation directory
-- **Task Discovery**: Automatically discovered tasks within each package
-- **Persistent Storage**: Package information persists across sessions
-
-### Task Discovery
-
-When a package is installed, `hostctl` automatically discovers tasks within the package by scanning for:
-
-- **TypeScript/JavaScript Files**: `.ts` and `.js` files in the package root
-- **Subdirectories**: Tasks in `tasks/` and `src/` subdirectories
-- **Default Tasks**: Common default task files like `index.ts`, `main.ts`, etc.
-
-### Task Resolution
-
-The `hostctl run` command now supports multiple resolution strategies:
-
-1. **Built-in Core Tasks**: `hostctl run core.echo hello`
-2. **Installed Package Tasks**:
-   - Default task: `hostctl run https://github.com/user/repo`
-   - Specific task: `hostctl run https://github.com/user/repo:taskname`
-3. **Relative Paths**: `hostctl run ./script.ts`
-
-### Package Resolution Examples
-
+npx hostctl run core.echo message:hello
+```
+
+## Bootstrap identities, inventory, and secrets
+1. **Generate AGE identities**
+   ```bash
+   mkdir -p ~/.hostctl/age
+   age-keygen -o ~/.hostctl/age/you.priv
+   age-keygen -y ~/.hostctl/age/you.priv > ~/.hostctl/age/you.pub
+   ```
+2. **Author an inventory** at `~/.hostctl/hostctl.yaml`:
+   ```yaml
+   hosts:
+     ubuntu-vm:
+       hostname: 192.168.56.15
+       user: vagrant
+       password: !secret vagrant-password
+       tags: [ubuntu, testvm]
+   secrets:
+     vagrant-password:
+       ids: you
+       value: vagrant
+   ids:
+     you: age1...
+   ```
+3. **Manage the file**
+   ```bash
+   hostctl inventory encrypt   # wrap with AGE recipients
+   hostctl inventory decrypt   # view/edit locally
+   hostctl inventory list      # inspect hosts & tags
+   ```
+   Set `AGE_IDS="~/.hostctl/age/*.priv"` before running commands if the file is encrypted.
+
+## Running tasks
+- **Local script**
+  ```bash
+  npm run build
+  ./dist/bin/hostctl.js run example/echo.ts args:hello
+  ```
+- **Local package**
+  ```bash
+  hostctl run ./my-package hello name:Sam
+  ```
+- **Remote orchestration**
+  ```bash
+  hostctl run -r -t ubuntu core.net.interfaces --json
+  ```
+  - `-r/--remote` targets hosts selected by tags via SSH.
+  - `-t/--tag` is greedy; use `--` before positional args when needed.
+- **From npm or git**
+  ```bash
+  hostctl run hostctl-hello greet name:Phil
+  hostctl run https://github.com/monopod/hostctl-example echo args:hello,world
+  ```
+- **Install Docker anywhere**
+  ```bash
+  hostctl run -r -t ubuntu core.docker.install users:hostctl
+  ```
+  The task follows Docker’s official installation guides for Ubuntu/Debian and Fedora/RHEL/Rocky (matching the current `xcpng-e2e` templates), so the same invocation works across your lab images.
+- **Run containers**
+  ```bash
+  hostctl run core.docker.run-container image:alpine command:'["/bin/sh","-c","echo from container"]'
+  hostctl run core.docker.run-container-detached image:redis name:ci-cache
+  ```
+  The first task streams container output back to the CLI; the detached variant returns the created container ID/name so you can manage it later.
+
+**Passing parameters**
+- `key:value` pairs after the task name.
+- `--params '{"key":"value"}'` for JSON blobs.
+- `--file params.json` to load structured arguments.
+
+## Managing task packages
+`hostctl pkg` commands wrap the npm-only package manager:
 ```bash
-# Install a package
-hostctl pkg install https://github.com/davidkellis/hostsfile
-
-# List installed packages and their tasks
+hostctl pkg create my-task --lang typescript
+hostctl pkg install hostctl-hello
 hostctl pkg list
-
-# Run the default task from an installed package
-hostctl run https://github.com/davidkellis/hostsfile names:foo,bar
-
-# Run a specific task from an installed package
-hostctl run https://github.com/davidkellis/hostsfile:add_entry names:foo,bar
-
-# Run core tasks
-hostctl run core.echo hello
-
-# Run relative paths (still works)
-hostctl run example/echo.ts hello
+hostctl pkg remove hostctl-hello
 ```
+Installed packages live under `~/.hostctl/packages` and can be run offline once cached.
 
-### Abstract Package Management Examples
-
-The abstract package management system automatically detects your platform's package manager and provides a unified interface:
-
-```bash
-# Auto-detect and update package sources
-hostctl run core.pkg.abstractUpdate
-
-# Search for packages (auto-detects package manager)
-hostctl run core.pkg.abstractSearch query:nginx
-
-# Install packages (auto-detects package manager)
-hostctl run core.pkg.abstractInstall package:curl
-
-# Install multiple packages
-hostctl run core.pkg.abstractInstall package:curl,wget,git
-
-# Force use of specific package manager
-hostctl run core.pkg.abstractInstall package:nginx packageManager:apt
-
-# List installed packages
-hostctl run core.pkg.abstractList
+## Designing tasks
+Define tasks with the `task` helper and a typed `TaskContext`:
 
-# Upgrade all packages
-hostctl run core.pkg.abstractUpgrade
-
-# Clean package cache
-hostctl run core.pkg.abstractClean
-```
-
-**Supported Platforms**: Ubuntu/Debian (apt), Alpine (apk), CentOS/RHEL (yum/dnf), Arch Linux (pacman), openSUSE (zypper), Solus (eopkg), Windows (winget/choco), macOS (brew)
-
-### Package Structure
-
-A `hostctl` package should follow this structure:
-
-```
-my-hostctl-package/
-├── package.json          # Package metadata
-├── index.ts             # Default task (optional)
-├── task1.ts             # Individual task
-├── task2.ts             # Individual task
-├── tasks/               # Task subdirectory (optional)
-│   ├── task3.ts
-│   └── task4.ts
-└── src/                 # Source subdirectory (optional)
-    ├── task5.ts
-    └── task6.ts
-```
-
-### Package Dependencies
-
-Each installed package maintains its own `node_modules` directory, ensuring that:
-
-- Dependencies are isolated per package
-- The `hostctl` runtime is available to each package
-- Packages can have their own version requirements
-
-### Package Sources
-
-The package management system supports multiple source types:
-
-- **Local Paths**: `./my-package` or `/path/to/package`
-- **Git Repositories**: `https://github.com/user/repo.git` or `git@github.com:user/repo.git`
-- **GitHub Shorthand**: `github.com/user/repo`
-- **NPM Packages**: `@scope/package-name` or `package-name`
-
-### Task Execution Context
-
-When running tasks from installed packages:
-
-- Tasks have access to the full `hostctl` runtime API
-- Package dependencies are available in the task's `node_modules`
-- Tasks can use all core tasks and utilities
-- Remote execution works seamlessly with installed package tasks
-
-#### `inventory` (alias: `i`)
-
-Manages and displays information about the host inventory.
-
-**Usage:**
-
-```bash
-hostctl inventory [subcommand]
-```
-
-Running `hostctl inventory` without a subcommand prints a report of the current inventory.
-
-**Subcommands:**
-
-- **`encrypt`** (alias: `e`)
-  - Encrypts the inventory file (determined by the global `--config` option).
-  - **Usage:** `hostctl inventory encrypt`
-- **`decrypt`** (alias: `d`)
-  - Decrypts the inventory file.
-
-#### `runtime` (alias: `rt`)
-
-Manages the `hostctl` runtime environment, particularly for Node.js scripts.
-
-**Usage:**
-
-```bash
-hostctl runtime [subcommand]
-```
-
-Running `hostctl runtime` without a subcommand prints a report about the detected/configured runtime environment.
-
-**Subcommands:**
-
-- **`install`** (alias: `i`)
-  - Installs or verifies a temporary Node.js runtime environment on the local host if `hostctl` determines one is needed (e.g., if a global Node.js is not found or a specific version is required).
-  - **Usage:** `hostctl runtime install`
-
-## Inventory File Structure
-
-`hostctl` uses a YAML file (defaulting to `hostctl.yaml`) to define its inventory of hosts, manage secrets, and specify encryption recipients. The file can contain three top-level keys: `hosts`, `secrets`, and `ids`.
-
-### `hosts` Section
-
-This section defines the machines `hostctl` can interact with.
-
-```yaml
-hosts:
-  server1.example.com:
-    user: deploy_user
-    ssh-key: !secret server1_ssh_key # References a secret
-    tags: [webserver, production, dc1]
-
-  192.168.1.100:
-    alias: db_server_primary
-    user: admin
-    password: !secret db_admin_password
-    tags: [database, primary, dc1]
-
-  localhost:
-    user: mylocaluser
-    tags: [local, dev]
-
-  another.server.com:
-    # Minimal configuration, will use global defaults or prompt if needed
-    tags: [staging]
-```
-
-- Each key under `hosts` (e.g., `server1.example.com`, `192.168.1.100`) is the hostname or IP address.
-- **Properties for each host:**
-  - `alias` (optional): A friendly name for the host.
-  - `user` (optional): The username for SSH connections.
-  - `password` (optional): The password for SSH. Can be a plain string or a `!secret` reference (e.g., `!secret my_password_name`).
-  - `ssh-key` (optional): Path to an SSH private key file or the private key content itself. Can also be a `!secret` reference.
-  - `tags` (optional): A list of strings for categorizing and selecting hosts.
-
-### `secrets` Section
-
-This section stores sensitive data, typically encrypted using AGE encryption.
-
-```yaml
-secrets:
-  server1_ssh_key:
-    ids: [age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, admin_keys_group] # AGE public key or id group ref
-    value: |
-      -----BEGIN AGE ENCRYPTED FILE-----
-      xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-      -----END AGE ENCRYPTED FILE-----
-
-  db_admin_password:
-    ids: db_admins_group # Reference to an 'ids' group
-    value: 'plaintextpasswordbeforeencryption' # This will be encrypted by 'hostct inventory encrypt'
-```
-
-- Each key under `secrets` (e.g., `server1_ssh_key`) is a unique name for the secret.
-- **Properties for each secret:**
-  - `ids`: A single string or a list of strings specifying the AGE public keys or named recipient groups (from the `ids` section) that can decrypt this secret.
-  - `value`: The secret content. If `hostctl inventory encrypt` has been run, this will be an AGE encrypted block.
-
-### `ids` Section
-
-This section defines named groups of AGE public keys, simplifying secret management.
-
-```yaml
-ids:
-  admin_keys_group:
-    - age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Alice's public key
-    - age1yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy # Bob's public key
-
-  db_admins_group:
-    - admin_keys_group # Nested group reference
-    - age1zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz # CI server's public key
-
-  single_key_user: age1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq
-```
-
-- Each key under `ids` (e.g., `admin_keys_group`) is a unique name for a group of recipients.
-- The value can be a single AGE public key string, a list of AGE public key strings, or a list containing references to other `ids` group names.
-
-This structure allows for a flexible and secure way to manage host information and sensitive credentials. The `hostct inventory encrypt` and `hostct inventory decrypt` commands interact with the `secrets` and `ids` sections to manage encryption.
-
-### Inventory Decryption Behavior
-
-When working with the inventory decryption functionality, it's important to understand these key behaviors:
-
-1. **Hostname Storage**: In the YAML configuration, hostnames are stored as the keys in the `hosts` map, not as properties inside each host object. When a host is serialized to YAML via `Host.toYAML()`, the `hostname` field is not included because it's represented by the map key.
-
-2. **Verbosity and Logging**: The inventory decryption process follows the general verbosity rules of hostctl:
-   - By default, only ERROR level messages are shown
-   - INFO level messages (like "No encrypted secrets found to decrypt. Inventory is already decrypted.") require the `-v` flag to be visible
-   - For idempotent operations like decrypting an already-decrypted inventory, you need to use the `-v` flag to see confirmation messages
-
-3. **Idempotent Operations**: The `inventory decrypt` command is designed to be idempotent - running it on an already decrypted inventory will not cause errors, but will only show a message if the `-v` flag is used.
-
-## Writing Tasks
-
-A `hostctl` task is a TypeScript file that exports a default function created by the `task()` factory. This function receives a `context` object, which provides APIs for interacting with the system, hosts, and the user.
-
-### Task Structure
-
-Here is a basic example of a task that echoes a message:
-
-```typescript
-// src/core/echo.ts
-import { task, type TaskContext, Verbosity } from '../runtime';
-
-export interface EchoParams {
-  message: string;
-}
-
-export interface EchoResult {
-  echo: string;
-}
-
-async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
-  const { params, log } = context;
-  const { message } = params;
-  log(Verbosity.INFO, `Echoing message: ${message}`);
-  return { echo: message };
-}
-
-export default task(run, {
-  description: 'Echoes a message back to the caller.',
-});
-```
-
-### The `TaskContext` API
-
-The `context` object passed to your task's `run` function contains several helpful properties and methods for task execution:
-
-- `params`: An object containing the parameters passed to the task.
-- `id`: A unique identifier for the current task invocation.
-- `host`: The `Host` object the task is currently running against. This is only available in a remote context (e.g., inside `context.ssh`).
-- `config`: The resolved application configuration (`AppConfig`).
-- `log(level, ...message)`: A function to log messages with a specific verbosity level. Levels are available from `Verbosity` (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).
-- `info(...)`, `debug(...)`, `warn(...)`, `error(...)`: Shortcuts for `log()` with the corresponding verbosity level.
-- `exec(command, options)`: Executes a shell command on the target host. The `command` can be a string or an array of strings. It returns a `Promise<CommandResult>`, which contains `stdout`, `stderr`, `exitCode`, and boolean `success`/`failure` properties.
-- `run(taskFn)`: Executes another `hostctl` task as a sub-task. This is the preferred way to compose tasks and reuse logic. For example: `await context.run(someOtherTask({ param: 'value' }))`.
-- `ssh(tags, remoteTaskFn)`: Executes a function on a set of remote hosts matching the given tags, enabling parallel remote execution.
-- `file`: An object providing a file system API (`read`, `write`, `exists`, `mkdir`, `rm`) that is contextualized to the target host (local or remote).
-- `inventory(tags)`: Returns a list of `Host` objects from the inventory that match the given tags.
-- `getPassword()`: Prompts the user for a password interactively.
-- `getSecret(name)`: Retrieves a decrypted secret value from the configuration by its name.
-- `exit(exitCode, message)`: Immediately terminates the `hostctl` application with a given exit code and optional message.
-
-This API provides the core building blocks for creating powerful and flexible automation tasks with `hostctl`.
-
-## Writing hostctl Scripts
-
-`hostctl` scripts are powerful tools for automating tasks on local and remote machines. They are written in TypeScript or JavaScript and follow a simple, consistent structure. This guide covers everything you need to know to write your own `hostctl` scripts.
-
-### The Basic Structure
-
-A `hostctl` script is a module that exports a default `task` object. This object is created using the `task()` factory function, which takes your main logic function and an optional description.
-
-```typescript
-// src/tasks/my-task.ts
-import { task, type TaskContext, Verbosity } from 'hostctl';
-
-// Define the parameters your task accepts
-export interface MyTaskParams {
-  targetSystem: string;
-  enableFeature: boolean;
-}
-
-// Define the structure of the value your task returns
-export interface MyTaskResult {
-  status: string;
-  rebootRequired: boolean;
-}
-
-// The core logic of your task
-async function run(context: TaskContext<MyTaskParams>): Promise<MyTaskResult> {
-  const { params, log, exec } = context;
-
-  log(Verbosity.INFO, `Configuring ${params.targetSystem}...`);
-
-  if (params.enableFeature) {
-    await exec('echo "Feature enabled" >> /etc/config.conf');
-  }
-
-  const result = await exec('check-reboot-status');
-
-  return {
-    status: 'Configuration applied successfully.',
-    rebootRequired: result.stdout.includes('reboot required'),
-  };
-}
-
-// Export the task with a description that can use Handlebars templating
-export default task(run, 'Configures {{targetSystem}} with feature: {{enableFeature}}');
-```
-
-### The `task()` Factory
-
-The `task()` function is the entry point for defining your script.
-
-`task(runFunction, description?)`
-
-- `runFunction`: An `async` function that contains the core logic of your task. It receives a `TaskContext` object.
-- `description` (optional): A string describing the task. It supports [Handlebars](https://handlebarsjs.com/) templating to dynamically insert parameter values, e.g., `"Deploying version {{version}} to {{environment}}"`.
-
-### The `TaskContext` Object
-
-The `TaskContext` is the heart of the scripting API. It's passed to your `run` function and provides all the necessary tools to interact with the system.
-
-- `params: TParams`: A strongly-typed object containing the parameters passed to your script from the command line or a params file.
-- `log(level: LogLevel, ...message)`: A logging function for structured output.
-  - **Levels**: Use the `Verbosity` enum for log levels: `Verbosity.DEBUG`, `Verbosity.INFO`, `Verbosity.WARN`, `Verbosity.ERROR`, `Verbosity.TRACE`.
-  - **Usage**: `context.log(Verbosity.INFO as LogLevel, "This is an info message");`
-- `info(...message)`: A convenience function that calls `log(Verbosity.INFO, ...message)`
-- `error(...message)`: A convenience function that calls `log(Verbosity.ERROR, ...message)`
-- `warn(...message)`: A convenience function that calls `log(Verbosity.WARN, ...message)`
-- `debug(...message)`: A convenience function that calls `log(Verbosity.DEBUG, ...message)`
-- `trace(...message)`: A convenience function that calls `log(Verbosity.TRACE, ...message)`
-- `exec(command: string, options?: ExecOptions): Promise<CommandResult>`: Executes a shell command on the target host.
-  - **`options`**:
-    - `cwd`: The working directory for the command.
-    - `sudo`: If `true`, runs the command with `sudo`.
-    - `stdin`: A string or Buffer to pass to the command's standard input when it starts.
-    - `input`: An object where keys are regular expression strings (to match command output) and values are the corresponding strings to send to the command's standard input. Used for automating interactive prompts.
-    - `pty`: If `true`, allocates a pseudo-terminal, useful for interactive commands.
-    - `env`: An object of environment variables.
-  - **`CommandResult`**: The promise resolves to an object containing `stdout`, `stderr`, `exitCode`, and `signal`.
-- `ssh(hostSelector, taskDefinition, params?): Promise<TRemoteReturn[] | Error>`: Executes another `hostctl` task on one or more remote hosts.
-  - **`hostSelector`**: A string, an array of strings, a `Host` object, or an array of `Host` objects to specify the target hosts from your inventory.
-  - **`taskDefinition`**: The task to execute on the remote host(s).
-  - `params`: The parameters to pass to the remote task.
-- `file: FileOperations`: An object for performing file operations on the target host.
-  - `read(path)`: Reads the content of a file.
-  - `write(path, content)`: Writes content to a file.
-  - `exists(path)`: Checks if a file or directory exists.
-  - `mkdir(path)`: Creates a directory.
-  - `rm(path)`: Removes a file or directory.
-- `cwd: Path`: The current working directory of the task.
-- `app: App`: A reference to the main `App` instance, giving you access to global configuration, the full host inventory, and secret management (`context.app.getSecretValue()`).
-- `host?: Host`: If the task is running on a specific host (e.g., via `ssh`), this object contains details about that host.
-
-### Handling Interactive Commands
-
-For commands that require user input (e.g., password prompts, confirmation dialogs), `hostctl` provides a straightforward way to automate these interactions through the `input` option in `context.exec()`.
-
-You don't need to create an `InteractionHandler` instance directly in your task script. Instead, you provide an object to the `input` option where:
-
-- Each **key** is a string representing a regular expression. `hostctl` will monitor the command's standard output for lines matching this regex.
-- Each **value** is the string that `hostctl` will send to the command's standard input when the corresponding key's regex is matched.
-
-```typescript
+```ts
 import { task, type TaskContext } from 'hostctl';
 
-async function run(context: TaskContext): Promise<void> {
-  const { exec, log } = context;
+interface EchoParams { message: string }
+interface EchoResult { repeated: string }
 
-  log(Verbosity.INFO as LogLevel, 'Attempting an operation that requires interactive confirmation...');
-
-  const result = await exec('your-interactive-command --with-prompt', {
-    pty: true, // A PTY is usually required for interactive commands
-    input: {
-      // When the command outputs "Enter your password:", respond with "mysecretpassword"
-      'Enter your password:': 'mysecretpassword',
-      // When the command outputs something like "Are you sure you want to continue (yes/no)?", respond with "yes"
-      'Are you sure you want to continue \\(yes\\/no\\)\\?': 'yes',
-    },
-  });
-
-  if (result.exitCode === 0) {
-    log(Verbosity.INFO as LogLevel, 'Interactive command completed successfully.');
-  } else {
-    log(
-      Verbosity.ERROR as LogLevel,
-      `Interactive command failed with exit code ${result.exitCode}. Stderr: ${result.stderr}`,
-    );
-  }
-}
-
-export default task(run, 'Demonstrate handling of an interactive command');
-```
-
-**Important Considerations:**
-
-- **PTY Allocation**: Interactive commands usually require a pseudo-terminal (PTY) to behave correctly. Always set `pty: true` in the `ExecOptions` when using the `input` map for interactions.
-- **Regex Specificity**: Make your regular expressions specific enough to avoid unintended matches. Test them thoroughly.
-- **Order of Interactions**: If a command has multiple prompts, `hostctl` will respond to them as they appear in the output and match the keys in your `input` object.
-
-#### Using the `withSudo` Helper
-
-Since running commands with `sudo` is a very common pattern, `hostctl` provides a convenient helper function, `withSudo`, to simplify this process. It automatically creates the correct input mapping for the `sudo` password prompt.
-
-```typescript
-import { task, type TaskContext, withSudo } from 'hostctl';
-
-async function run(context: TaskContext): Promise<void> {
-  const { exec, log, getPassword } = context;
-
-  const sudoPassword = await getPassword(); // Prompts user if not already provided
-  if (!sudoPassword) {
-    throw new Error('Sudo password is required but was not provided.');
-  }
-
-  // Use the helper to build the input map
-  const input = withSudo(sudoPassword);
-
-  log(Verbosity.INFO as LogLevel, 'Running a command with sudo...');
-
-  // Pass the generated input map to the exec options
-  const result = await exec('sudo apt-get update', { pty: true, input });
-
-  if (result.exitCode === 0) {
-    log(Verbosity.INFO as LogLevel, "'apt-get update' completed successfully.");
-  } else {
-    log(Verbosity.ERROR as LogLevel, "'apt-get update' failed.");
-  }
-}
-
-export default task(run, 'Demonstrate using the withSudo helper');
-```
-
-The `withSudo` helper can also be combined with other interactions:
-
-`const input = withSudo(password, { "Do you want to continue?": "yes" });`
-
-### A Complete Example: Installing a Package
-
-Here is a realistic example of a task that installs a package on a Debian-based system.
-
-```typescript
-// src/tasks/install-nginx.ts
-import { task, type TaskContext, Verbosity, type LogLevel } from 'hostctl';
-
-export interface InstallNginxParams {
-  updateCache?: boolean;
-}
-
-async function run(context: TaskContext<InstallNginxParams>): Promise<void> {
-  const { params, log, exec } = context;
-
-  log(Verbosity.INFO as LogLevel, 'Starting Nginx installation...');
-
-  if (params.updateCache) {
-    log(Verbosity.DEBUG as LogLevel, 'Updating package cache...');
-    await exec('sudo apt-get update');
-  }
-
-  log(Verbosity.INFO as LogLevel, 'Installing nginx package...');
-  const installResult = await exec('sudo apt-get install -y nginx');
-
-  if (installResult.exitCode !== 0) {
-    log(Verbosity.ERROR as LogLevel, 'Failed to install Nginx.');
-    throw new Error(`apt-get failed with exit code ${installResult.exitCode}`);
-  }
-
-  log(Verbosity.INFO as LogLevel, 'Nginx installed successfully.');
+async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
+  const { params, info } = context;
+  info(`Echo: ${params.message}`);
+  return { repeated: params.message };
 }
 
-export default task(run, 'Install Nginx on a Debian-based system');
-```
-
-## TODO
-
-- [ ] Further refine the script execution interface.
-- [ ] Expand documentation for script development.
-- [ ] Add more examples for common use cases.
+export default task(run, { name: 'example.echo', description: 'Prints a message' });
+```
+
+Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for details):
+- Structured logging via `info`, `warn`, `error`, `debug`, or `log(level, ...)`.
+- Command execution with `exec(command, { sudo, env, cwd, stdin, pty })`.
+- Remote fan-out using `ssh(tags, remoteFn)`.
+- Subtask orchestration with `run(otherTask(params))`.
+- Secrets & credentials via `getSecret(name)` and `getPassword()`.
+- Inventory helpers: `inventory(tags)` and `selectedInventory(tags?)`.
+- File helpers: `file.read`, `file.write`, `file.exists`, `file.mkdir`, `file.rm` that respect local vs. remote runtime.
+
+## Building & testing task packages
+1. Scaffold: `hostctl pkg create awesome-firewall --lang typescript`.
+2. Install deps: `cd awesome-firewall && npm install`.
+3. Build: `npm run build` (defaults to `tsc`).
+4. Test locally without publishing: `npx hostctl run . args:foo`.
+5. Add unit tests with Vitest if needed, or invoke tasks directly in scripts.
+
+## Publishing task packages
+1. Update `package.json` metadata (`name`, `version`, `description`, `files`).
+2. Build artifacts (`npm run build` or rely on `prepublishOnly`).
+3. Authenticate with npm (`npm login` or `NPM_TOKEN`).
+4. Publish:
+   ```bash
+   npm version patch   # or minor/major
+   npm publish --access public
+   ```
+5. Tag releases in git or automate with tools like `release-it` (this repo ships `release.sh` as an example flow).
+6. Verify: `npm info your-package version`.
+
+## Consuming published packages
+- One-off: `npx hostctl run your-package taskName param:value`.
+- Cache locally: `hostctl pkg install your-package@1.2.3` then run offline.
+- Compose in other codebases by adding the package to `dependencies` and importing its exported tasks.
+
+## Troubleshooting
+- **Task not found**: confirm the package exports the task name and that `exports` exposes it.
+- **Version mismatch**: keep `package.json`, `src/version.ts`, and `jsr.json` in sync before releasing.
+- **SSH failures**: verify inventory entries (hostname, user, auth) and only pass `-r` when you intend remote execution.
+- **Secrets**: when inventories are encrypted, ensure `AGE_IDS` includes the private keys so `hostctl` can decrypt secrets.
+- **Environment drift**: run `hostctl runtime` to inspect prerequisites or `hostctl runtime install` to bootstrap them.
+
+## Developer workflow
+- Format & typing: `npm run format` (Prettier) and `npm run lint` (`tsc --noEmit`).
+- Build artifacts: `npm run build` (tsup) produces `dist/` bundles for the CLI and published package.
+- Tests:
+  - `npm run test` → unit + functional suites.
+  - `npm run test:unit`, `npm run test:functional`, `npm run test:e2e` for focused runs.
+- VM helpers (`npm run vm:*`) are legacy while XCP-ng provisioning matures; see `docs/xcp-ng-operations.md`.
+- Releases rely on `npm run release` + `release-it`; see `NPM_MIGRATION_PLAN.md` for npm-only context.
+
+## Documentation map
+- **Task API reference**: [`docs/task-api.md`](docs/task-api.md).
+- **Operational guides**: `docs/*.md` (process, package, system management, etc.).
+- **Architecture & design**: [`ARCHITECTURE.md`](ARCHITECTURE.md) and supporting design docs.
+- **Contributor guide**: [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md).
+- **Issue tracking**: <https://github.com/monopod/hostctl/issues>.
+
+Explore the examples under `example/`, get familiar with the task API, and share automations with the community via npm-compatible packages.