# sm121-launcher — Claude Code

Read CONVENTIONS.md before any git operation.

<!-- BEGIN bigpowers:project -->
## Project

Rust CLI for launching vLLM/SGLang inference containers across DGX Spark clusters via SSH.
Docker default. tmux alternative.

Stack: Rust edition 2024. clap, tokio, russh, anyhow, tracing, fluent-i18n.

## Commands

| Action    | Command                                      |
|-----------|----------------------------------------------|
| Build     | `cargo build`                                |
| Test      | `cargo test` (128 tests)                     |
| Lint      | `cargo clippy` (`-D warnings`)               |
| Preflight | `make check` (fmt→clippy→test→≤500 lines)    |
| Dry-run   | `cargo run -- -d serve --recipe <name>`     |
| CI        | `gh pr checks` (when a PR is open)           |

## Architecture

CLI dispatches subcommands: serve, stop, logs, health, doctor, exec, power, tmux, build.
orchestrate/ ties cluster selection, before_serve hooks, docker launch, ssh exec.
config/ loads config.toml + recipes. docker/ owns build, sync, command, compose, mods.
ssh.rs wraps russh for per-node remote execution.
See `specs/tech-architecture/tech-stack.md` for the full architectural map.

## Conventions

- Files MUST stay ≤500 lines. Extract submodules near the limit.
- `make check` MUST pass before every commit. No exceptions.
- NEVER add `#[allow(...)]` attributes. Refactor to fix clippy.
- NEVER add `Co-authored-by` footers. Author solely as the user.
- Use Conventional Commits: `feat(...)`, `fix(...)`, `docs(...)`.
- Run `sm121 health` before `stop` or `power off`. The cluster serves live traffic.

## Never

- Never run `stop` or `power off` without `health` + user confirmation.
- Never dismiss reproducible gate failures as pre-existing.
- Never proceed on red Preflight. Invoke quick-fix or fix-bug first.
- Never assume the cluster is idle. Verify with `health` first.
<!-- END bigpowers:project -->

<!-- BEGIN bigpowers:context-routing -->
## Context Routing

| Glob | Source of truth |
|------|-----------------|
| `recipes/**`, `docker-images/**`, `host-scripts/**` | `AGENTS.md` |
| `src/**`, `locales/**` | `CONVENTIONS.md` + `specs/` |
| Cluster/recipe/config format questions | `AGENTS.md` (cluster ops SoT) |
| Dev workflow / planning / lifecycle | `specs/` (bigpowers SoT) |
<!-- END bigpowers:context-routing -->

<!-- BEGIN bigpowers:learned-preferences -->
## Learned User Preferences

- (none recorded yet)

## Workspace Facts

- Project root: `/Volumes/main/projects/git.kilork.org/kilork/sm121-launcher`
- Remote: `git.kilork.org/sm121/sm121-launcher.git`
- SSH user: `kilork` (from config.toml)
- bigpowers scripts: `~/.pi/agent/npm/node_modules/bigpowers/scripts/`
<!-- END bigpowers:learned-preferences -->

## Agent Rules

- **Workflow Mandate:** Use bigpowers skills for tasks. DO NOT write code directly.
- **Always Green:** Preflight MUST pass before forward work.
- Read `specs/` before writing code.
- Write minimum code that solves the stated problem. Nothing extra.
- Run tests after every change. Show evidence before declaring done.
- One clarifying question beats a wrong assumption baked into 200 lines of code.
- **Dual SoT:** `AGENTS.md` owns cluster/recipe ops. `CONVENTIONS.md` owns dev workflow.