docs: align CLI overview with onboarding wrapper

Author: geroldsteiner67

docs/cli/index.md

@@ -10,28 +10,40 @@ The `modal` command-line tool is your interface to Modality.
 ## Installation
 
 ```bash
-# macOS/Linux
-curl -fsSL https://get.modality.org | sh
+# First-contract onboarding wrapper
+cd rust
+cargo build --release -p modal --no-default-features --features contract-onboarding
 
-# Or build from source
-cd rust && cargo build --release
+# Language/model CLI used by the first-contract guide
+cargo build --release -p modality
 ```
 
+The lean onboarding wrapper exposes the contract and identity surfaces needed by
+the first-contract guide: `modal contract`, `modal c`, `modal id`,
+`modal passfile`, `modal status`, `modal commit`, and `modal set`. It omits the
+runtime-heavy hub, node, network, predicate, program, chain, local, run,
+`killall`, and upgrade surfaces.
+
+Build the full wrapper with `cargo build --release -p modal` when you need those
+broader command groups. Use `modality` for model and rule authoring tasks such
+as `modality model lint`, `modality model synthesize`, and
+`modality model validate`.
+
 ## Command Groups
 
 | Command | Alias | Description |
 |---------|-------|-------------|
 | `modal contract` | `modal c` | Contract management (create, commit, push, pull) |
 | `modal id` | `modal identity` | Identity management (create, derive, get) |
 | `modal passfile` | — | Passfile encryption/decryption |
-| `modal hub` | — | Contract hub server and collaboration |
-| `modal predicate` | — | Predicate listing and testing |
-| `modal program` | — | Program management |
-| `modal node` | — | Network node operations |
-| `modal net` | `modal network` | Network information |
-| `modal local` | — | Local development utilities |
-| `modal run` | — | Quick node runners |
-| `modal chain` | — | Chain validation |
+| `modal hub` | — | Contract hub server and collaboration; full wrapper only |
+| `modal predicate` | — | Predicate listing and testing; full wrapper only |
+| `modal program` | — | Program management; full wrapper only |
+| `modal node` | — | Network node operations; full wrapper only |
+| `modal net` | `modal network` | Network information; full wrapper only |
+| `modal local` | — | Local development utilities; full wrapper only |
+| `modal run` | — | Quick node runners; full wrapper only |
+| `modal chain` | — | Chain validation; full wrapper only |
 
 ## Global Commands
 
@@ -47,10 +59,10 @@ modal <command> --help
 # Show status (in contract directory)
 modal status
 
-# Kill all local nodes
+# Kill all local nodes (full wrapper only)
 modal killall
 
-# Upgrade to latest version
+# Upgrade to latest version (full wrapper only)
 modal upgrade
 ```
 

tests/README.md

@@ -16,6 +16,8 @@ commitment-versus-enabledness trap warning, checks that the first-contract guide
 adds rules, synthesizes the witness model with `--verify`, validates it with
 `modality model validate`, and then commits, checks that the installation guide
 keeps the `modal` contract CLI and `modality` model CLI split explicit, checks
+that the CLI overview keeps the lean onboarding wrapper separate from full
+runtime command groups, checks
 that the real `modality` model help surface matches the documented language CLI
 when a language binary is present, checks that the verifier rejection reference
 preserves current-state, closest-candidate, and missing-predicate diagnostics,

tests/docs/check-cli-index-doc.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DOC="$ROOT_DIR/docs/cli/index.md"
+
+required_patterns=(
+  "# CLI Reference"
+  "cargo build --release -p modal --no-default-features --features contract-onboarding"
+  "cargo build --release -p modality"
+  "The lean onboarding wrapper exposes"
+  "\`modal contract\`, \`modal c\`, \`modal id\`"
+  "It omits the"
+  "runtime-heavy hub, node, network, predicate, program, chain, local, run,"
+  "\`killall\`, and upgrade surfaces"
+  "Build the full wrapper with \`cargo build --release -p modal\`"
+  "Use \`modality\` for model and rule authoring tasks"
+  "\`modality model lint\`"
+  "\`modality model synthesize\`"
+  "\`modality model validate\`"
+  "full wrapper only"
+  "modal c create"
+  "modal c set /parties/alice.id --named alice"
+  "modal c commit --all --sign alice.passfile"
+)
+
+for pattern in "${required_patterns[@]}"; do
+  if ! grep -Fq -- "$pattern" "$DOC"; then
+    echo "CLI index is missing onboarding/help-surface text: $pattern" >&2
+    exit 1
+  fi
+done
+
+for forbidden_pattern in "curl -fsSL https://get.modality.org | sh" "cd rust && cargo build --release"; do
+  if grep -Fq -- "$forbidden_pattern" "$DOC"; then
+    echo "CLI index still contains stale install text: $forbidden_pattern" >&2
+    exit 1
+  fi
+done
+
+echo "CLI index doc check passed"

tests/run-onboarding-smokes.sh

@@ -84,6 +84,7 @@ fi
 "$ROOT_DIR/tests/docs/check-contract-evolution-doc.sh"
 "$ROOT_DIR/tests/docs/check-language-traps-doc.sh"
 "$ROOT_DIR/tests/docs/check-installation-doc.sh"
+"$ROOT_DIR/tests/docs/check-cli-index-doc.sh"
 "$ROOT_DIR/tests/docs/check-first-contract-doc.sh"
 "$ROOT_DIR/tests/docs/check-verifier-rejections-doc.sh"
 "$ROOT_DIR/tests/docs/check-synthesis-review-doc.sh"