Commit 07ea8af

docs: help cmd

 1@@ -190,7 +190,57 @@ func newLogger(space string, levelStr string) *slog.Logger {
 2 }
 3 
 4 func printMainHelp() {
 5-	fmt.Println(`pici — minimal parallel CI runner & monitor powered by zmx
 6+	fmt.Println(`pici - minimal parallel CI runner & monitor powered by zmx
 7+
 8+HOW IT WORKS: pici runs your project's CI pipeline defined in pico.sh:
 9+  1. Syncs workspace to a clean temporary directory (/tmp).
10+  2. Executes pico.sh inside zmx, running each task in its own isolated PTY.
11+  3. Bring your own isolation: tasks run on host unless wrapped (e.g. Docker, Podman, Nix).
12+  4. Tasks execute serially ('zmx run <name> <cmd>') or concurrently in detached mode ('zmx run <name> -d <cmd>').
13+  5. Concurrent background tasks are joined using 'zmx wait "*"' to block until all complete.
14+  6. Streams live terminal output & generates HTML reports in /tmp/pici-artifacts/.
15+  7. Interactive debugging: on failure, attach with 'zmx attach <session>' to inspect logs or rerun commands.
16+  8. Optionally rsyncs rendered logs & artifacts to a destination when specified.
17+
18+PROJECT SETUP
19+  1. Create a pico.sh script in your project root:
20+
21+       #!/usr/bin/env bash
22+       set -euo pipefail
23+
24+       # Read environment metadata (with fallbacks for standalone execution)
25+       JOB_ID="${PICI_JOB:-local}"
26+       REPO="${PICI_REPO:-myrepo}"
27+       BRANCH="${PICI_BRANCH:-main}"
28+       COMMIT="${PICI_COMMIT:-dev}"
29+       EVENT="${PICI_EVENT:-local}"
30+       ZMX_SESSION_PREFIX="${ZMX_SESSION_PREFIX:-local.}"
31+
32+       echo "Running CI for $REPO ($BRANCH@$COMMIT, job: $JOB_ID, event: $EVENT)"
33+
34+       # Run serial setup step on host or container
35+       zmx run setup npm install
36+
37+       # Run concurrent steps using Docker for environment isolation
38+       zmx run lint -d docker run --rm -v "$(pwd):/app" -w /app golangci/golangci-lint golangci-lint run
39+       zmx run test -d docker run --rm -v "$(pwd):/app" -w /app golang:1.26 go test ./...
40+
41+       # Wait for all background steps to finish
42+       zmx wait "*"
43+
44+  2. Make it executable: chmod +x pico.sh
45+  3. Run locally:        pici
46+
47+ENVIRONMENT VARIABLES: pici injects these vars into pico.sh:
48+    PICI_JOB            Unique job identifier (timestamp or commit SHA)
49+    PICI_REPO           Repository name (default: directory basename)
50+    PICI_EVENT          Event type ('local', 'git.push', 'git.tag')
51+    PICI_BRANCH         Git branch name (auto-detected)
52+    PICI_COMMIT         Git commit SHA (auto-detected)
53+    PICI_TAG            Git tag name (set for tag events)
54+    ZMX_SESSION_PREFIX  Internal session prefix managed by pici
55+
56+  Pass custom env vars or overrides with -e / -env (e.g. pici -e CGO_ENABLED=0).
57 
58 LOCAL DEVELOPER USAGE
59   pici [destination] [flags]                  Run ./pico.sh locally in /tmp & render HTML logs
60@@ -219,16 +269,28 @@ func printMissingPicoHelp(cwd string) {
61 
62 To run local CI tasks, create a pico.sh script in your project root:
63 
64-  #!/usr/bin/env bash
65-  set -euo pipefail
66+	#!/usr/bin/env bash
67+	set -euo pipefail
68 
69-  # Run parallel steps using zmx
70-  zmx run lint -d <your lint command>
71-  zmx run test -d <your test command>
72+	# Read environment metadata (with fallbacks for standalone execution)
73+	JOB_ID="${PICI_JOB:-local}"
74+	REPO="${PICI_REPO:-myrepo}"
75+	BRANCH="${PICI_BRANCH:-main}"
76+	COMMIT="${PICI_COMMIT:-dev}"
77+	EVENT="${PICI_EVENT:-local}"
78+	ZMX_SESSION_PREFIX="${ZMX_SESSION_PREFIX:-local.}"
79 
80-  # Wait for all steps to finish
81-  zmx wait "*"
82-  printf "\x1b[32msuccess!\x1b[0m\n"
83+	echo "Running CI for $REPO ($BRANCH@$COMMIT, job: $JOB_ID, event: $EVENT)"
84+
85+	# Run serial setup step on host or container
86+	zmx run setup npm install
87+
88+	# Run concurrent steps using Docker for environment isolation
89+	zmx run lint -d docker run --rm -v "$(pwd):/app" -w /app golangci/golangci-lint golangci-lint run
90+	zmx run test -d docker run --rm -v "$(pwd):/app" -w /app golang:1.26 go test ./...
91+
92+	# Wait for all background steps to finish
93+	zmx wait "*"
94 
95 For full command documentation and daemon options, run:
96   pici help