Align internal documentation and maintained examples

docs/internal/stage-publish.md

@@ -1,23 +1,29 @@
 # Stage: publish
 
 ## Purpose
+
 Upload run/session outputs to object storage and atomically advance remote current state.
 
 ## Inputs
-- successful prerequisite stages: `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `render`, `analyze`
-- run root `runs/{run_id}/**`
-- publish output rules (`pipeline.publish.outputs`)
+
+- successful preceding stages from the [canonical stage set](overview.md#pipeline-stage-set)
+- invocation-scoped run files
+- resolved publish output rules
 - effective publish locks (static + remote merged lock set)
-- local `previous/**` files when present
+- durable previous-session cache files when present
 
 ## Outputs
-- uploaded run files under remote `runs/{run_id}/...` (excluding `audio/**`)
-- uploaded selected publish outputs under session prefix
-- uploaded `previous/**` files under session prefix when present
-- uploaded `current/manifest.json`
-- uploaded `current/run_id.txt` written last
+
+- uploaded invocation record and selected publish outputs;
+- uploaded durable previous-session cache files when present;
+- updated remote current manifest; and
+- remote current-run commit marker, written last.
+
+Exact remote placement and the operator workflow belong in
+[Operations](../operations.md#publish-workflow).
 
 ## Key Behavior
+
 - stage can self-skip when publish disabled or run upload disabled.
 - validates prerequisite stage success and object-store availability.
 - collects deterministic run file list plus run `manifest.json`.
@@ -28,6 +34,7 @@ Upload run/session outputs to object storage and atomically advance remote curre
 - writes remote current manifest before current run pointer.
 
 ## Metadata Signals
+
 Includes counts/lists for:
 - run uploads
 - published output uploads
@@ -39,6 +46,22 @@ Includes counts/lists for:
 - `current_pointer_written`
 
 ## Invariants
+
 - `current/run_id.txt` is the remote commit marker and is written last.
 - run upload excludes `audio/**`.
 - publish locks are not overridden by `--force`.
+
+The commit boundary and cleanup gate are normative architecture invariants; see
+[Architecture](../policy/architecture.md#publish-commit-boundary).
+
+## Related Contracts And Tests
+
+- [Configuration](../config.md#publish-configuration-summary) owns output and
+  static-lock fields.
+- [Operations](../operations.md#publish-locks) owns remote lock lifecycle and
+  physical remote state.
+- [Artifact Internals](artifacts.md) explains source resolution and current-state
+  helpers.
+- Implementation and tests: `internal/stage/publish.go`,
+  `internal/stage/publish_test.go`, `internal/app/operator_helpers_test.go`,
+  `internal/app/post_publish_cleanup_test.go`