Align internal documentation and maintained examples

docs/internal/artifacts.md

@@ -1,17 +1,28 @@
 # Internal: Artifacts
 
 ## Purpose
-Define canonical artifact IDs, runtime catalog behavior, source resolution rules, and shared current-state mechanics used by app and previous-cache code.
+
+Explain the artifact registry, runtime catalog, resolver, previous-input
+requirements, and shared remote current-state mechanics implemented by
+`internal/artifacts`. Configuration fields that accept source IDs belong in
+[Configuration](../config.md); physical placement belongs in
+[Operations](../operations.md).
 
 ## 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`)
-- `narratio.transcript.final_trimmed` -> `transcripts/final.trimmed.json` (`trim`)
-- `narratio.transcript.final_markdown` -> `transcripts/final.md` (`render`)
-- `narratio.transcript.final_trimmed_markdown` -> `transcripts/final.trimmed.md` (`render`)
-- `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`)
+The internal registry recognizes these stable built-in source IDs:
+
+- `narratio.transcript.base`
+- `narratio.transcript.polished`
+- `narratio.transcript.final`
+- `narratio.transcript.final_trimmed`
+- `narratio.transcript.final_markdown`
+- `narratio.transcript.final_trimmed_markdown`
+- `narratio.bounds.session`
+
+Registry entries bind each ID to its producer, output kind, canonical fallback,
+and content validator. The focused stage documents own their input/output flow;
+[Configuration](../config.md) owns where operators may select these IDs.
 
 ## Configured and Previous-Session Sources
 
@@ -72,7 +83,8 @@ Validation by content type:
 
 ## Current-State Helpers
 
-Artifacts package owns shared remote current-state loading mechanics used by restore, status/validate checks, and previous-cache planning.
+Artifacts package owns shared remote current-state loading mechanics used by
+restore, status and validation checks, and previous-cache planning.
 
 Core helpers:
 
@@ -107,9 +119,27 @@ Caller policy is intentionally outside artifacts helpers:
 - spool/cache paths;
 - S3 session/run/current-state key layout.
 
+See [Workspace Internals](workspace.md) for how callers consume local helpers
+and [Operations](../operations.md#local-state-layout) for the authoritative
+physical layout.
+
 ## Invariants
 
 - source ID formats are stable contracts;
 - 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.
+
+## Implementation And Tests
+
+- Registry and resolution: `internal/artifacts/artifact_resolver.go`,
+  `internal/artifacts/catalog.go`, `internal/artifacts/transcripts.go`
+- Current state: `internal/artifacts/current_state.go`
+- Paths and keys: `internal/artifacts/paths.go`,
+  `internal/artifacts/s3_keys.go`
+- Previous requirements: `internal/artifacts/previous_requirements.go`
+- Tests: `internal/artifacts/artifact_resolver_test.go`,
+  `internal/artifacts/catalog_test.go`,
+  `internal/artifacts/current_state_test.go`,
+  `internal/artifacts/paths_model_test.go`,
+  `internal/artifacts/previous_requirements_test.go`