Refresh CLI and internal restore documentation for current behavior

docs/cli.md

@@ -40,14 +40,31 @@ Most session-aware commands accept:
 - `--campaign <id>`
 - `--campaign-file <campaign.yml>`
 - `--session <session.yml>`
-- `--previous-session-id <id>`
+- `--session-id <session_id>`
+- `--previous-session-id <session_id>`
 
 Rules:
 
 - `--campaign` and `--campaign-file` are mutually exclusive.
 - `--session` is not used by `session init`.
+- if both positional `<session_id>` and `--session-id` are provided, values must match.
 - `clean --all` cannot be combined with campaign/session selectors.
 
+## Session ID Input Rules
+
+Session-aware commands accept one of these forms:
+
+- positional session ID: `... <session_id>`
+- compatibility flag: `... --session-id <session_id>`
+
+When both are present, command parsing requires an exact match.
+
+Commands with additional positionals keep their command-specific order:
+
+- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
+- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
+- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
+
 ## Command Reference
 
 ### `run`
@@ -187,7 +204,7 @@ Options:
 Rules:
 
 - `--audio-dir` and `--audio-s3-prefix` are mutually exclusive.
-- if campaign `session_template_file` is configured, `session init` renders it;
+- if campaign `session_template_file` is configured, `session init` renders it.
 - generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders).
 
 ### `session restore`