docs: align identity command reference

Author: geroldsteiner67

docs/cli/identity-commands.md

@@ -11,17 +11,24 @@ title: Identity Commands
 # Create with default path
 modal id create --path alice.passfile
 
-# Create with password protection
-modal id create --path alice.passfile --password
+# Create with passfile encryption
+modal id create --path alice.passfile --encrypt
+
+# Create in the standard passfile directory
+modal id create --name alice
 ```
 
+`modal id create` writes a passfile. Use `--path <PATH>` for an explicit
+location, `--dir <DIR>` for an output directory, or `--name <NAME>` for the
+standard `~/.modality/<name>.mod_passfile` location.
+
 ## Derive Sub-Identity
 
 ```bash
-modal id derive --path alice.passfile --sub "escrow-key" --output alice-escrow.passfile
+modal id derive --mnemonic "abandon abandon ..." --path alice-escrow.passfile
 ```
 
-Derives a deterministic sub-key from your main identity. Useful for:
+Derives a keypair from a BIP39 mnemonic seed phrase. Useful for:
 - Contract-specific keys
 - Rotating access keys
 - Hierarchical key management
@@ -38,13 +45,13 @@ modal id get --path alice.passfile
 ### Encrypt a Passfile
 
 ```bash
-modal passfile encrypt --path alice.passfile --password
+modal passfile encrypt --path alice.passfile
 ```
 
 ### Decrypt a Passfile
 
 ```bash
-modal passfile decrypt --path alice.passfile.enc --password
+modal passfile decrypt --path alice.passfile
 ```
 
 ## Best Practices

tests/README.md

@@ -19,6 +19,8 @@ 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 contract command reference preserves the
 current `create`, `checkout`, `set`, and `set-named-id` help shapes, checks
+that the identity command reference preserves the current passfile creation,
+mnemonic derivation, and encrypt/decrypt flag shapes, checks
 that older tutorials still use the current
 `set-named-id <path> <passfile>` and `commit --sign <passfile>` shapes, checks
 that the real `modality` model help surface matches the documented language CLI

tests/docs/check-cli-identity-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/identity-commands.md"
+
+required_patterns=(
+  "# Identity Commands (\`modal id\`)"
+  "modal id create --path alice.passfile"
+  "modal id create --path alice.passfile --encrypt"
+  "modal id create --name alice"
+  "\`--path <PATH>\`"
+  "\`--dir <DIR>\`"
+  "\`--name <NAME>\`"
+  "modal id derive --mnemonic"
+  "BIP39 mnemonic seed phrase"
+  "modal id get --path alice.passfile"
+  "modal passfile encrypt --path alice.passfile"
+  "modal passfile decrypt --path alice.passfile"
+)
+
+for pattern in "${required_patterns[@]}"; do
+  if ! grep -Fq -- "$pattern" "$DOC"; then
+    echo "identity command reference is missing current help-surface text: $pattern" >&2
+    exit 1
+  fi
+done
+
+for forbidden_pattern in \
+  "modal id create --path alice.passfile --password" \
+  "modal id derive --path alice.passfile --sub" \
+  "--output alice-escrow.passfile" \
+  "modal passfile encrypt --path alice.passfile --password" \
+  "modal passfile decrypt --path alice.passfile.enc --password"; do
+  if grep -Fq -- "$forbidden_pattern" "$DOC"; then
+    echo "identity command reference still contains stale help-surface text: $forbidden_pattern" >&2
+    exit 1
+  fi
+done
+
+echo "identity command doc check passed"

tests/run-onboarding-smokes.sh

@@ -86,6 +86,7 @@ fi
 "$ROOT_DIR/tests/docs/check-installation-doc.sh"
 "$ROOT_DIR/tests/docs/check-cli-index-doc.sh"
 "$ROOT_DIR/tests/docs/check-cli-contract-doc.sh"
+"$ROOT_DIR/tests/docs/check-cli-identity-doc.sh"
 "$ROOT_DIR/tests/docs/check-cli-tutorials-doc.sh"
 "$ROOT_DIR/tests/docs/check-first-contract-doc.sh"
 "$ROOT_DIR/tests/docs/check-verifier-rejections-doc.sh"