lobstah 0.1.0 → 0.1.2

package/README.md

@@ -1,32 +1,41 @@
-# lobstah
+# lobstah 🦞✨
+
+*Nobody stares at the water.*
 
 [![CI](https://github.com/aequitas-labs/lobstah/actions/workflows/ci.yml/badge.svg)](https://github.com/aequitas-labs/lobstah/actions/workflows/ci.yml)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
 ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)
+[![npm](https://img.shields.io/npm/v/lobstah)](https://www.npmjs.com/package/lobstah)
 ![Harnesses](https://img.shields.io/badge/harnesses-Claude%20Code%20%7C%20Codex-8A2BE2)
 
-Harness-agnostic, token-efficient supervisor for local coding agents.
+Harness-agnostic, token-efficient supervision framework for coding agents.
 
-One coding agent in a terminal is fine. Three is tab-juggling: which one is
-stuck, which one is waiting on a question nobody saw, which one died forty
-minutes ago? And the cloud sandboxes can't help when the work needs your
-actual machine — private toolchains, local services, unpushed branches,
-credentials that never leave the laptop.
+You were promised agents that do the work. Somehow, watching them became the
+work: which one is stuck, which one is waiting on an answer nobody saw, which
+one died forty minutes ago. Watching is why you run two agents instead of
+ten.
 
-Lobstah runs coding agents like services instead of terminal tabs. Each
-dispatch gets an isolated git worktree; a daemon tells a dead process from a
-wedged one and treats them differently (auto-restart vs. a bounded
-fork-with-nudge ladder); status and evidence land on disk. Supervision spends
-zero tokens — no model watches the models.
+A trap doesn't fish faster for being watched, and an agent doesn't code
+faster either. You **lob** bait into a trap and walk away. Each dispatch runs
+in its own git worktree; the daemon tells a dead process from a wedged one
+and recovers each; status and evidence land on disk. Supervision costs
+nothing — no tokens, no attention — so the whole fleet fits in one
+conversation, and **your agents just bring home the lobstahs**.
 
-## Requirements
+## Requirements 📋
 
 - Node 20+, git, pnpm
 - An authenticated harness CLI: `claude` (Claude Code) and/or Codex. Lobstah
   never handles harness login — you authenticate your own CLI; lobstah invokes it.
 
-## Install
+## Install ⚓
+
+```bash
+npm i -g lobstah
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/aequitas-labs/lobstah
@@ -35,12 +44,16 @@ pnpm install && pnpm build
 ln -s "$PWD/bin/lobstah" /usr/local/bin/lobstah   # Windows: add .\bin to PATH
 ```
 
-## Quick start
+## Quick start 🪝
 
 ```bash
-lobstah init                 # ~/.lobstah + example config
+lobstah init --scan ~/src    # ~/.lobstah + a [repos.*] block per repo found
+                             # (bare `init` writes an example config instead;
+                             #  `lobstah repos add <path>` appends one repo)
 $EDITOR ~/.lobstah/config.toml
-lobstah daemon &             # under tmux/pm2/launchd for real use
+lobstah doctor               # binaries, config, repos, harnesses, heartbeat
+lobstah daemon install       # launchd agent / systemd user unit — survives
+                             # reboots, restarts on crash (`daemon &` for a try)
 lobstah dispatch --repo myapp --brief ./brief.md
 ```
 
@@ -65,34 +78,38 @@ lobstah swap <uuid> --harness codex   # hand an active dispatch to a fresh sessi
 lobstah catch <uuid>                  # the evidence: branch, commits, PR, session
 lobstah cancel <uuid>
 lobstah cull --apply                  # sweep aged results and orphaned worktrees
+lobstah man tend                      # the whole string: fleet verdict, waiting
+                                      # questions, each item's chain + PR + gate
 ```
 
-(Prefer the water? `set --bait`, `buoys`, and `buoy` alias `dispatch`, `ls`,
-and `status`.)
+Prefer the water? 🌊 `set --bait`, `buoys`, and `buoy` alias `dispatch`,
+`ls`, and `status`.
 
-Dispatches report six verbs — `working`, `needs-decision`, `blocked`,
-`paused`, `done`, `failed` — validated at the write path. `done` means the
-brief is fulfilled; merging is never the dispatch's job.
+Dispatches report six verbs: `working`, `needs-decision`, `blocked`,
+`paused`, `done`, `failed`. The write path rejects anything else. `done`
+means the brief is fulfilled. Merging is never the dispatch's job.
 
-Everything lives under `$LOBSTAH_HOME` (default `~/.lobstah`); multiple
-isolated instances are just multiple homes, one daemon per home (enforced).
+Everything lives under `$LOBSTAH_HOME` (default `~/.lobstah`). To run more
+instances, use more homes. One daemon per home, enforced.
 
-## When something needs you
+## When something needs you 🛎️
 
-Set one config line and the daemon pings you on `needs-decision`, `blocked`,
-`done`, and `failed` — `notifyCommand = "ntfy pub my-topic ..."` — no model in
-the loop. Driving lobstah from an agent session instead? `lobstah man` prints
-the lobsterman's manual: `man wait` blocks until a dispatch needs attention
-(unanswered questions re-fire until answered), and `man init` installs a
-Claude Code Stop hook that parks the session on the fleet and continues the
-turn the moment something does.
+Set one config line — `notifyCommand = "ntfy pub my-topic ..."` — and the
+daemon pings you on `needs-decision`, `blocked`, `done`, and `failed`. No
+model in the loop. Driving lobstah from an agent session instead? `lobstah
+man` prints the lobsterman's manual. `man wait` blocks until a dispatch needs
+attention, and unanswered questions re-fire until answered. `man init`
+installs a Claude Code Stop hook that parks the session on the fleet and
+continues the turn the moment something needs it.
 
-## Add-ons
+## Add-ons 🎣
 
 - **Tracker pickup** — `lobstah pick` polls Linear and GitHub outbound (no
   webhooks, no tunnel), dispatches assigned work, streams status back as
   comments, forwards replies into the running dispatch, reconciles drift, and
-  optionally merges approved PRs. [docs/pickup.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/pickup.md)
+  optionally merges approved PRs. GitHub pickup spans every repo you mark
+  `pickup = true`; `lobstah pick install` runs it as a service.
+  [docs/pickup.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/pickup.md)
 - **OpenClaw plugin** — gives fleet agents `lobstah_dispatch` / `lobstah_status`
   / `lobstah_send` / `lobstah_cancel` tools and operators a `/lobstah` command.
   [docs/openclaw.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/openclaw.md)
@@ -100,7 +117,7 @@ turn the moment something does.
   supervises, and hands you outcomes, woken by the `lobstah man` commands.
   [docs/lobsterman.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/lobsterman.md)
 
-## How it holds together
+## How it holds together 🧭
 
 ```
 CLI / pick / OpenClaw plugin / anything ──writes──>  ~/.lobstah/queue/
@@ -111,10 +128,12 @@ daemon ──spawn──> runner (one per dispatch) ──SDK──> harness CLI
    └── dead/wedged classification · bounded restart ladder · zero tokens
 ```
 
-Design: [docs/design.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/design.md).
-Verified by CI on Linux and Windows, live end-to-end runs on both harnesses,
-and fault-injection drills (SIGKILL'd runners respawn and complete; SIGSTOP'd
-ones are classified wedged, killed cleanly, and recover with a nudge).
+Design: [docs/design.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/design.md). Every verb, verdict, and gate in
+one place: [docs/vocabulary.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/vocabulary.md).
+Verified by CI on Linux and Windows, by live end-to-end runs on both
+harnesses, and by fault-injection drills. A SIGKILL'd runner respawns and
+completes. A SIGSTOP'd one is classified wedged, killed cleanly, and recovers
+with a nudge.
 
 ## Non-goals