Documentation update for the restore subcommand

docs/operations.md

@@ -6,7 +6,7 @@ For field-level configuration, see [docs/config.md](./config.md). For full comma
 
 ## Normal workflow (S3-first path)
 
-1. Upload session `.flac` files to object storage under the session audio prefix.
+1. Upload session `.flac` files to object storage under the configured session audio prefix.
 2. Run Narratio:
 
 ```bash
@@ -21,6 +21,37 @@ Notes:
 - default config/session discovery applies unless `--config` and `--session` are passed.
 - S3 audio mode requires `session.inputs.audio_s3.prefix` and valid object-store access.
 
+## Restore workflow
+
+Use restore when local durable session state is missing or stale and archive current state is authoritative.
+
+Dry-run (no local writes):
+
+```bash
+narratio restore --session-id 2026-04-04 --dry-run
+```
+
+Execution:
+
+```bash
+narratio restore --session-id 2026-04-04
+```
+
+Post-restore analyze rerun pattern:
+
+```bash
+narratio run-stage --session-id 2026-04-04 --force analyze
+```
+
+Restore source-of-truth:
+- remote commit marker: `current/run_id.txt`
+- remote current manifest: `current/manifest.json`
+
+Restore default scope:
+- includes `manifest.json`, `transcripts/**`, `artifacts/**`
+- includes `audio/**` only with `--include-audio`
+- excludes `runs/**`, `logs/**`, `reports/**`, `config/**`, `inputs/**`, and `current/**` (except remote `current/manifest.json` as source)
+
 ## Local filesystem layout and state artifacts
 
 Session root:
@@ -29,7 +60,7 @@ Session root:
 Primary state:
 - `manifest.json`: session-level stage state.
 - `runs/{run_id}/manifest.json`: invocation-level state.
-- `.lock`: session lock while a run is active.
+- `.lock`: session lock while a modifying command is active.
 
 Canonical session directories:
 - `inputs/`
@@ -48,6 +79,7 @@ Run-local stage directories:
 Behavior:
 - directory creation is idempotent.
 - stage outputs are generally generated run-local first, then promoted to canonical paths on success.
+- restore installs downloaded files to canonical session paths and does not recreate historical run sandboxes.
 
 ## Analyze artifact execution lifecycle
 
@@ -91,7 +123,7 @@ Archive promotion is explicit and source-based:
 - missing optional promotion sources are skipped.
 - invalid resolved artifacts fail archive stage.
 
-## Resume, retry, and safe rerun behavior
+## Resume, retry, restore, and safe rerun behavior
 
 Default skip:
 - `run` and `run-stage` skip already-succeeded stages unless `--force` is set.
@@ -100,6 +132,11 @@ Resume:
 - `resume` starts at first non-succeeded stage.
 - `resume --force` runs full stage order.
 
+Restore conflict policy:
+- restore classifies local differences as conflicts.
+- without `--force`, restore fails when conflicts exist.
+- with `--force`, conflicting local files are overwritten by remote archive files.
+
 Forced reruns:
 - force-rerunning an upstream succeeded stage marks downstream succeeded stages as `stale`.
 
@@ -125,13 +162,18 @@ No cleanup for failed/incomplete/unarchived/archive-skipped runs.
 
 ## Failure and recovery playbooks
 
-After failure, Narratio keeps:
+After run failure, Narratio keeps:
 - session manifest
 - run manifest
 - run-local artifacts/logs/config/reports
 
 Failed or incomplete runs remain local-only.
 
+After restore failure:
+- already-installed restore files remain in place.
+- restore does not roll back prior successful installs.
+- existing local manifest is preserved if restored manifest validation/install fails.
+
 Recommended recovery:
 
 1. inspect state:
@@ -140,8 +182,27 @@ Recommended recovery:
 narratio status --manifest <manifest-path>
 ```
 
-2. fix root cause (config/input/credentials/service availability).
-3. continue with `resume`, or targeted `run-stage --force` followed by `resume`.
+2. for restore-specific checks, run:
+
+```bash
+narratio restore --session-id 2026-04-04 --dry-run
+```
+
+3. fix root cause (config/input/credentials/storage/service availability).
+4. continue with `resume`, or targeted `run-stage --force` followed by `resume`.
+
+## Restore report
+
+Non-dry-run restore writes a durable report at:
+- `reports/restore-latest.json`
+
+Report content includes:
+- identity (`campaign`, `session_id`, `run_id`)
+- mode flags (`dry_run`, `force`, `include_audio`)
+- plan counts and execution counts
+- per-action status
+
+Dry-run does not write restore report files.
 
 ## Operational caveats
 
@@ -149,3 +210,4 @@ narratio status --manifest <manifest-path>
 - local and S3 audio input modes are mutually exclusive.
 - archive publish requires upstream stages through `analyze` to be `succeeded`.
 - required promotion rules can fail when selected analyze artifacts did not generate a required file path.
+- restore requires configured remote object storage and committed remote current state.