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`

docs/internal/artifacts.md

@@ -1,9 +1,10 @@
 # Internal: Artifacts
 
 ## Purpose
-Define canonical artifact IDs, runtime catalog behavior, and source resolution rules for stage execution and publish output selection.
+Define canonical artifact IDs, runtime catalog behavior, source resolution rules, and shared current-state mechanics used by app and previous-cache code.
 
 ## Built-in Source IDs
+
 - `narratio.transcript.base` -> `transcripts/base.json` (`merge`)
 - `narratio.transcript.polished` -> `transcripts/polished.json` (`polish`)
 - `narratio.transcript.final` -> `transcripts/final.json` (`normalize`)
@@ -11,58 +12,101 @@ Define canonical artifact IDs, runtime catalog behavior, and source resolution r
 - `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`)
 
 ## Configured and Previous-Session Sources
-- Configured artifact source ID: `narratio.artifact.<artifact_key>`
-- Previous-session source ID: `narratio.previous_session.artifact.<artifact_key>`
 
-Configured and previous-session source IDs are validated by strict regex rules.
+- configured source ID format: `narratio.artifact.<artifact_key>`
+- previous-session source ID format: `narratio.previous_session.artifact.<artifact_key>`
+
+Both formats are validated by strict source-policy rules.
 
 ## Runtime Catalog
+
 `ArtifactCatalog` tracks:
-- `planned`: source registered for run context.
+
-- `executable`: selected and enabled for analyze execution.
+- `planned`: source registered for run context;
-- `available`: local file exists and validated.
+- `executable`: selected and enabled for analyze execution;
+- `available`: local file exists and validates;
 - `provenance`: availability source.
 
 Current provenance values:
+
 - `generated.current_analyze_run`
 - `filesystem.disabled_artifact_output`
 - `manifest.inputs.previous_cache`
 - `current_session.previous_cache`
 
 ## Resolution Rules
+
 Built-ins:
+
 1. manifest producer outputs (when present)
-2. canonical session path fallback
+2. canonical session-path fallback
 
 Configured sources (`narratio.artifact.*`):
+
 - resolve only through runtime catalog availability.
 
 Previous-session sources (`narratio.previous_session.artifact.*`):
-- resolve only from local `previous/` cache state.
+
-- prefer manifest-backed previous input paths.
+- resolve only from local `previous/` cache state;
+- prefer manifest-backed previous-input paths;
 - fallback to existing previous-cache filesystem paths.
 
 Validation by content type:
-- transcript built-ins: JSON with top-level `segments` array.
+
-- bounds built-in: valid JSON.
+- transcript built-ins: JSON with top-level `segments` array;
+- bounds built-in: valid JSON;
 - configured/previous-session artifact files: non-empty text file.
 
 ## Previous Requirement Collection
+
 `CollectPreviousArtifactRequirements`:
+
 - scans enabled configured artifacts only;
 - extracts only canonical previous-session sources;
 - deduplicates by artifact key;
-- merges required/optional (required wins);
+- merges required and optional references (required wins);
 - returns deterministic ordering and source locations.
 
+## Current-State Helpers
+
+Artifacts package owns shared remote current-state loading mechanics used by restore, status/validate checks, and previous-cache planning.
+
+Core helpers:
+
+- `LoadCurrentRunPointer`
+- `LoadCurrentManifest`
+- `LoadCurrentState`
+- `ValidateCurrentStateIdentity`
+
+Typed missing-state errors:
+
+- `CurrentRunPointerMissingError` (`ErrCurrentRunPointerMissing`)
+- `CurrentManifestMissingError` (`ErrCurrentManifestMissing`)
+
+Identity validation supports caller-provided expectations:
+
+- expected campaign;
+- expected session ID;
+- expected run ID, or pointer/manifest run-ID consistency check.
+
+Caller policy is intentionally outside artifacts helpers:
+
+- some callers fail on missing current state;
+- some callers downgrade missing state to status/findings;
+- some callers skip optional behavior when state is missing.
+
 ## Key Path Helpers
-`internal/artifacts/paths.go` defines canonical helpers for:
+
+`internal/artifacts/paths.go` and S3-key helpers define canonical helpers for:
+
 - session/work/run paths;
 - previous-cache paths;
 - spool/cache paths;
-- S3 key layout helpers for session/run/current pointers.
+- S3 session/run/current-state key layout.
 
 ## Invariants
-- Source ID formats are stable contracts.
+
-- Resolution is deterministic and manifest-aware.
+- source ID formats are stable contracts;
-- Previous-session source resolution does not call remote storage in `analyze`; remote hydration is `prepare` responsibility.
+- artifact resolution is deterministic and manifest-aware;
+- previous-session source resolution in `analyze` is local-only;
+- remote current-state key construction remains centralized in artifacts helpers.

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
+- `current/run_id.txt` (required, non-empty);
-Planner actions:
+- `current/manifest.json` (required, decodable).
-- `download`
+
-- `skip_same`
+Current-state discovery uses shared artifacts-level mechanics and validates identity against the resolved request config:
-- `conflict`
+
+- 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 `manifest.json`;
-- include `artifacts/**`
+- include `transcripts/**`;
-- include `audio/**` only with `--include-audio`
+- 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;
+- `manifest.json` installs last;
-- downloads use sibling temp files + atomic rename;
+- 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 uses committed remote current state as authority;
-- restore is a standalone command and does not run stages.
+- `current/run_id.txt` is the remote publish commit marker;
+- restore does not execute pipeline stages.