Hero Skills

Claude Code skills and the lab CLI / library for the Hero stack.

---

What is lab?

lab is the Hero environment manager and build orchestrator. It bootstraps developer machines, manages secrets and SSH keys, installs the full toolchain, builds Rust binaries with fingerprint-based caching, and runs AI agents.

lab is both a binary and a Rust library crate — all logic lives in lib.rs modules returning Result<T>; the binary (main.rs) is thin CLI dispatch only.

---

Quick reference

lab bootstrap core            guided first-run: runtime only (nushell, hero_proc, hero_router)
lab bootstrap core --dev      same + Rust toolchain + ONNX (for developing Hero from source)

lab user init                 bootstrap Hero env (PATH_ROOT, init.sh, env.nu, nushell, secrets)
lab user verify               health-check PATH_ROOT, FORGE_TOKEN, shell shims, Forge reachability

lab install core [--reset]    install Rust, nushell, base tools, start hero_proc + hero_router
lab install rust              Rust toolchain only (idempotent, --reset to force)
lab install nu                nushell only

lab secrets sync              pull secrets repo, import into hero_proc, install SSH keys
lab secrets push              push local secrets to Forge

lab build [REPO]              build binaries (fingerprint-cached, copies to PATH_ROOT/bin)
lab repo <verb>               Forgejo repo management (clone, list, create, …)
lab skills edit|sync          manage Claude Code skills
lab agent 'instruction'       run an AI agent instruction
lab service <name> --start    start a hero service via hero_proc

---

Getting started

1. Install lab

curl -sSfL https://forge.ourworld.tf/lhumina_code/hero_skills/raw/branch/development/scripts/lab_install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

Downloads the pre-built binary for your platform (macOS/Linux, arm64/x86_64) to ~/.local/bin/lab.

2. Guided setup (recommended)

lab bootstrap core

Prompts for quality level, runs lab user init, lab install core, downloads hero binaries, and verifies the environment.

3. Manual setup

lab user init          # pick PATH_ROOT, generate shell files, clone repos, install nushell
source ~/hero/cfg/init.sh
lab install core       # Rust toolchain + base tools + hero_proc + hero_router
lab secrets sync       # import secrets (run after hero_proc is up)

---

Configuration (hero.cfg)

All environment settings live in {PATH_ROOT}/cfg/hero.cfg (TOML). Created by lab start core.

quality = "development"   # development | integration | main
dev_mode = false          # true = also install Rust + ONNX (for developing Hero itself)

[pins]
# Per-repo branch overrides — take precedence over the quality-level default.
hero_skills = "development"   # lab always comes from the development branch

Quality levels

Level	Release tag fallback	Git branch
development	dev → integration → latest	development
integration	integration → latest	integration
main	latest	main

dev_mode

dev_mode = false (default) installs: base tools, Claude Code, Python, nushell, hero_proc, hero_router.
dev_mode = true additionally installs: Rust toolchain, ONNX Runtime.

Set via lab bootstrap core --dev or edit hero.cfg directly.

---

SSH key management

Add named keys to secrets.toml:

[ssh.mykey]
public_key  = "ssh-ed25519 AAAA... user@host"
private_key = """
-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----
"""

After lab secrets sync:

• ~/.ssh/mykey (0600) and ~/.ssh/mykey.pub (0644) are written
• ~/.ssh/config gets a fenced hero-managed block with IdentityFile ~/.ssh/mykey
• Key is added to the running ssh-agent (macOS: Keychain; Linux: stable socket at $PATH_VAR/ssh-agent.sock)
• Duplicate keys (same content under a different name) are detected and skipped

---

What lab user init sets up

File	Description
{PATH_ROOT}/cfg/init.sh	Generated bash env — sets PATH_ROOT, CARGO_HOME, FORGE_TOKEN, etc. Sourced at login.
{PATH_ROOT}/cfg/env.nu	Nushell equivalent. Sets NU_LIB_DIRS, PATH, all hero vars.
~/.config/nushell/env.nu	Fenced shim that sources the above.
~/.config/nushell/config.nu	Fenced block: use lib/skills.nu * (hero-managed section only).
~/.bashrc, ~/.zshrc	Fenced shim that sources init.sh.

Hero only manages its own fenced blocks (# >>> hero env >>> … # <<< hero env <<<). Everything outside those blocks is never touched.

---

Building a release

lab build --upload --platforms allbase -v

Builds for macos-arm64, linux-musl-arm64, linux-musl-x86_64 and uploads to Forgejo.

---

FORGE_TOKEN

Required for lab repo, lab secrets, and private repo clones.

1. Go to https://forge.ourworld.tf/user/settings/applications
2. Create a token with read:repository + write:repository scopes
3. Pass via --forge-token, set $FORGE_TOKEN, or let lab user init prompt for it