CLI cleanup to consolidate session-related subcommands

docs/operations.md

@@ -11,22 +11,22 @@ For field-level configuration, see [docs/config.md](./config.md). For full comma
 3. Run Narratio:
 
 ```bash
-narratio run --session-id 2026-04-04
+narratio run 2026-04-04
 ```
 
 4. Read success output:
 - `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
-- use `manifest=<path>` with `status` for inspection.
+- use `narratio session status <session_id>` for inspection.
 
 Notes:
 - default config/campaign/session discovery checks system config locations unless `--config`, `--campaign`, and `--session` are passed.
-- when local `session.yml` discovery misses, `--session-id` loads remote `session.yml` from `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`.
+- when local `session.yml` discovery misses, positional `<session_id>` loads remote `session.yml` from `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`.
 - S3 audio mode requires `session.inputs.audio_s3.prefix` and valid object-store access.
 
 Initialize a remote session skeleton:
 
 ```bash
-narratio session init --session-id 2026-04-04 --remote
+narratio session init 2026-04-04 --remote
 ```
 
 Remote init uses normal default config discovery and writes `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml`. If `campaign.yml` sets `session_template_file`, init renders that template from the supplied flags and writes concrete YAML. Pass `--config` and `--campaign` when testing non-system config files. It fails if the object already exists unless `--force` is passed.
@@ -34,7 +34,7 @@ Remote init uses normal default config discovery and writes `{root_prefix}/campa
 Validate before running:
 
 ```bash
-narratio session validate --session-id 2026-04-04
+narratio session validate 2026-04-04
 ```
 
 ## Restore workflow
@@ -44,19 +44,19 @@ Use restore when local durable session state is missing or stale and archive cur
 Dry-run (no local writes):
 
 ```bash
-narratio restore --session-id 2026-04-04 --dry-run
+narratio session restore 2026-04-04 --dry-run
 ```
 
 Execution:
 
 ```bash
-narratio restore --session-id 2026-04-04
+narratio session restore 2026-04-04
 ```
 
 Post-restore analyze rerun pattern:
 
 ```bash
-narratio analyze --session-id 2026-04-04
+narratio analyze 2026-04-04
 ```
 
 Restore source-of-truth:
@@ -73,9 +73,9 @@ Restore default scope:
 Reset local state before restore testing:
 
 ```bash
-narratio clean --session-id 2026-04-04 --dry-run
-narratio clean --session-id 2026-04-04
-narratio restore --session-id 2026-04-04 --include-audio
+narratio clean 2026-04-04 --dry-run
+narratio clean 2026-04-04
+narratio session restore 2026-04-04 --include-audio
 ```
 
 `clean` removes the local session work directory and session spool directory. It preserves the durable S3 audio cache by default, so repeated restore or forced prepare tests do not re-download large audio files.
@@ -136,18 +136,18 @@ Canonical previous-session input behavior:
 - canonical sources use `narratio.previous_session.artifact.<artifact_key>`.
 - these inputs are hydrated by `prepare` and by `restore`; `analyze` expects the local previous cache to already exist.
 - if analyze fails due to missing canonical previous cache, rerun:
-  - `narratio run-stage --session-id <id> --force prepare`
-  - or `narratio restore --session-id <id>` when remote archive current state is authoritative.
+  - `narratio run-stage prepare <id> --force`
+  - or `narratio session restore <id>` when remote archive current state is authoritative.
 
 ## Remote archive layout and publish contract
 
 Preferred manual publish command:
 
 ```bash
-narratio publish --session-id <id>
+narratio publish <id>
 ```
 
-`publish` is equivalent to `narratio run-stage --force archive`; use `run-stage` when you need the general single-stage command form.
+`publish` is equivalent to `narratio run-stage archive <id> --force`; use `run-stage` when you need the general single-stage command form.
 
 When archive is enabled and run upload is enabled, archive publishes under:
 
@@ -176,10 +176,10 @@ Archive promotion is explicit and source-based:
 - locked required promotions are treated as intentional successful skips and are recorded in archive metadata.
 
 Lock helper behavior:
-- `narratio locks --session-id <id>` lists effective static and remote locks.
-- `narratio locks add --session-id <id> --reason <text> <source>` writes a remote lock.
-- `narratio locks add --session-id <id> --force --reason <text> <source>` updates an existing remote lock reason.
-- `narratio locks remove --session-id <id> <source>` removes only a remote lock.
+- `narratio session locks <id>` lists effective static and remote locks.
+- `narratio session locks add <id> <source> --reason <text>` writes a remote lock.
+- `narratio session locks add <id> <source> --force --reason <text>` updates an existing remote lock reason.
+- `narratio session locks remove <id> <source>` removes only a remote lock.
 - `locks remove` cannot remove static pipeline locks.
 - remote lock writes check whether the lock store exists, but are not compare-and-swap atomic.
 
@@ -214,7 +214,7 @@ Automatic cleanup toggles:
 - `pipeline.workspace.cleanup_after_archive=true` deletes run-scoped local run directory.
 
 Manual cleanup:
-- `narratio clean --session-id <id>` deletes `{workspace.root}/work/{campaign}/{session_id}` and `{spool.root}/{campaign}/{session_id}`.
+- `narratio clean <id>` deletes `{workspace.root}/work/{campaign}/{session_id}` and `{spool.root}/{campaign}/{session_id}`.
 - `narratio clean --all` deletes all local session work under `{workspace.root}/work` and all spool children under `{spool.root}`.
 - `--dry-run` prints targets without deleting.
 - `--clear-cache` also removes matching S3 audio cache files. Without it, cache is preserved.
@@ -248,25 +248,19 @@ Recommended recovery:
 1. inspect state:
 
 ```bash
-narratio status --session-id 2026-04-04
+narratio session status 2026-04-04
 ```
 
 This reports local manifest state, committed remote current state, expected remote transcript/artifact availability, and archive locks.
 
-2. for one manifest file, run:
+2. for restore-specific checks, run:
 
 ```bash
-narratio status --manifest <manifest-path>
+narratio session restore 2026-04-04 --dry-run
 ```
 
-3. for restore-specific checks, run:
-
-```bash
-narratio restore --session-id 2026-04-04 --dry-run
-```
-
-4. fix root cause (config/input/credentials/storage/service availability).
-5. continue with `resume`, or targeted `run-stage --force` followed by `resume`.
+3. fix root cause (config/input/credentials/storage/service availability).
+4. continue with `resume`, or targeted `run-stage <stage> <id> --force` followed by `resume`.
 
 ## Restore report
 
@@ -283,9 +277,8 @@ Dry-run does not write restore report files.
 
 ## Operational caveats
 
-- `status` with no config/session flags still requires explicit `--manifest`.
-- `status --session-id <id>` uses normal config/session loading, including remote session fallback.
-- `status --session-id <id>` includes the same promoted remote output availability view as `artifacts list --remote` when storage is configured.
+- `session status <session_id>` uses normal config/session loading, including remote session fallback.
+- `session status <session_id>` includes the same promoted remote output availability view as `session artifacts <session_id> --remote` when storage is configured.
 - local and S3 audio input modes are mutually exclusive.
 - archive publish requires upstream stages through `analyze` to be `succeeded`.
 - required configured artifact promotions for unselected `--artifacts` keys are skipped intentionally; selected required promotions still fail if their files are missing.