Refresh CLI and internal restore documentation for current behavior

docs/internal/command-restore.md

@@ -1,65 +1,84 @@
 # Internal: Command Restore
 
 ## Purpose
-Document the implemented `narratio session restore` command contract:
+Define the implemented `narratio session restore` command contract:
+
 - committed remote current-state discovery;
-- deterministic restore plan classification;
+- deterministic restore planning;
 - safe local install semantics;
 - durable restore reporting.
 
 ## Discovery Contract
-Restore discovers remote committed state using:
-- `current/run_id.txt` (required, non-empty)
-- `current/manifest.json` (required, decodable)
 
-Discovered manifest identity must match requested `session_id` and `campaign`.
+Restore resolves remote committed state from the session publish current pointers:
 
-## Plan Contract
-Planner actions:
-- `download`
-- `skip_same`
-- `conflict`
+- `current/run_id.txt` (required, non-empty);
+- `current/manifest.json` (required, decodable).
+
+Current-state discovery uses shared artifacts-level mechanics and validates identity against the resolved request config:
+
+- campaign must match;
+- session ID must match.
+
+Restore treats any missing or invalid remote current state as a command error.
+
+## Planning Contract
+
+Restore planner action kinds:
+
+- `download`;
+- `skip_same`;
+- `conflict`.
+
+Planner behavior:
 
-Plan behavior:
 - remote list scope is the resolved session prefix;
-- mapping to local paths is traversal-safe;
+- remote-to-local mapping is traversal-safe;
 - actions are sorted deterministically by local relative path.
 
 Restore scope from current remote state:
-- include `manifest.json`
-- include `transcripts/**`
-- include `artifacts/**`
-- include `audio/**` only with `--include-audio`
+
+- include `manifest.json`;
+- include `transcripts/**`;
+- include `artifacts/**`;
+- include `audio/**` only with `--include-audio`.
 
 Explicit exclusions from current remote state mapping:
-- `current/**`
-- `runs/**`
-- `logs/**`
-- `reports/**`
-- `config/**`
-- `inputs/**`
-- `previous/**`
 
-Previous-cache restore files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist.
+- `current/**`;
+- `runs/**`;
+- `logs/**`;
+- `reports/**`;
+- `config/**`;
+- `inputs/**`;
+- `previous/**`.
+
+Previous-cache files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist.
 
 ## Execution Contract
+
+Execution order and safety:
+
 - non-manifest downloads happen before manifest install;
-- `manifest.json` is installed last;
-- downloads use sibling temp files + atomic rename;
+- `manifest.json` installs last;
+- downloads use sibling temp files plus atomic rename;
 - manifest replacement is validated before rename;
-- failed installs do not roll back previously written files.
+- failed installs do not roll back files already written in the same execution.
 
 Audio restore path:
+
 - uses `audio.MaterializeS3Audio`;
 - integrates spool and S3 audio cache paths;
-- supports cache hit reuse without object redownload.
+- supports cache-hit reuse without object redownload.
 
 ## Reporting Contract
-- dry-run: summary only (no writes).
+
+- `--dry-run`: prints summary only; no local writes.
 - non-dry-run: writes `reports/restore-latest.json`.
-- report captures plan counts, action status, and execution failures.
+- report includes plan counts, per-action status, and execution failures.
 
 ## Invariants
-- restore uses only committed remote current state as authority.
-- `current/run_id.txt` is the remote commit marker.
-- restore is a standalone command and does not run stages.
+
+- restore uses committed remote current state as authority;
+- `current/run_id.txt` is the remote publish commit marker;
+- restore does not execute pipeline stages.