Update documentation for the new analyze stage and artifact registry

docs/internal/artifacts.md

@@ -1,39 +1,40 @@
 # Internal: Artifacts
 
 ## Purpose
-Describe supported session artifact IDs, transcript tiers, and artifact resolution/provenance behavior used by stage logic and Scriptorium input configuration.
+Define Narratio's artifact identity and resolution model for built-in transcript/bounds artifacts and runtime-configured analyze artifacts.
 
 ## Inputs and outputs
 Inputs:
-- Artifact source identifiers from stage config/runtime (for example `pipeline.scriptorium.artifacts.*.inputs.*.source`).
-- Session paths and optional session manifest stage outputs.
+- artifact sources from config/runtime (`pipeline.scriptorium.artifacts.*.inputs.*.source`)
+- session paths and optional session manifest stage outputs
+- runtime artifact catalog state for configured artifact sources
 
 Outputs:
-- Resolved local artifact path + provenance (`ResolvedSessionArtifact`).
-- Validation errors for unsupported or unreadable artifact sources.
+- resolved local artifact path and provenance (`ResolvedSessionArtifact`)
+- runtime catalog entries for planned/executable/available artifacts
+- validation errors for unsupported, missing, or invalid artifact sources
 
 ## Boundaries
 Owns:
-- Canonical artifact ID registry and metadata (`internal/artifacts/artifact_resolver.go`).
-- Alias normalization for legacy source names.
-- Resolution order and artifact content validation.
+- built-in artifact registry and content validation rules
+- runtime artifact catalog for configured artifact source IDs
+- source resolution behavior for built-in and configured artifact sources
 
 Does not own:
-- Artifact generation (stages produce files).
-- Manifest transition policy.
-- Remote archive publishing behavior.
+- artifact generation (stages produce files)
+- manifest transition policy
+- archive promotion behavior
 
 ## Config fields used
-Artifact source usage is driven by:
+- `pipeline.scriptorium.artifacts.<name>.enabled`
+- `pipeline.scriptorium.artifacts.<name>.output_path`
 - `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
-- Optional source-specific fields for previous artifact input (`artifact`, `path`, `required`).
 
 ## External adapters used
-- No external service adapters.
-- Resolver relies on local filesystem checks + session manifest state.
+- none
 
 ## State and manifest behavior
-Supported canonical IDs and current mappings:
+Built-in registry entries:
 
 | Artifact ID | Canonical file | Producer stage | Output kind |
 | --- | --- | --- | --- |
@@ -42,39 +43,45 @@ Supported canonical IDs and current mappings:
 | `narratio.transcript.full` | `transcripts/normalized.json` | `normalize` | `transcript_normalized` |
 | `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
 | `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
-| `narratio.artifact.session_recap` | `artifacts/session_recap.md` | `analyze` | `session_recap` |
 
-Resolution order:
-1. Session manifest producer-stage outputs (if readable/valid).
-2. Canonical session path fallback.
+Runtime catalog entries include built-ins and configured `narratio.artifact.<name>` sources.
 
-Provenance fields:
-- `ProducerStage`
-- `OutputKind`
-- `ProducerRunID` (when resolved from manifest output)
-- `Provenance` (`manifest.<stage>.outputs` or `fallback.canonical_path`)
+Catalog states:
+- `planned`: source is registered and known for this run
+- `executable`: configured artifact is selected for analyze execution
+- `available`: artifact has a usable file path (generated this run or reused from disk)
 
-Content validation by artifact type:
-- Transcript artifacts: JSON with top-level `segments` array.
-- `narratio.bounds.session`: valid JSON.
-- `narratio.artifact.session_recap`: non-empty text.
+Resolution behavior:
+- built-in sources resolve via manifest producer outputs first, then canonical fallback path
+- configured `narratio.artifact.<name>` sources resolve through runtime catalog availability
+- configured source lookup requires catalog context
+
+Configured artifact provenance values:
+- `generated.current_analyze_run`
+- `filesystem.disabled_artifact_output`
+
+Content validation:
+- transcript built-ins: JSON with top-level `segments` array
+- bounds built-in: valid JSON
+- configured artifacts: non-empty text file
 
 ## Skip and resume behavior
-- Resolver has no direct skip/resume logic.
-- Resolver output influences stage behavior (for example analyze input resolution and required-input failures).
+- resolver and catalog have no direct skip/resume decisions
+- stage/runner skip-resume behavior consumes catalog/resolver results
 
 ## Failure behavior
-- Unsupported or empty artifact source -> normalization error.
-- Known source not found/readable -> `ErrSessionArtifactNotFound` wrapped error.
-- Found but invalid content -> validation error.
+- unsupported source -> source validation error
+- known source unavailable -> `ErrSessionArtifactNotFound`
+- configured source without catalog -> resolution error
+- resolved file with invalid content -> validation error
 
 ## Tests to inspect before changing
 - `internal/artifacts/artifact_resolver_test.go`
-- `internal/artifacts/resolve_test.go`
+- `internal/artifacts/catalog_test.go`
 - `internal/stage/analyze_test.go`
 - `internal/config/scriptorium_test.go`
 
 ## Architectural invariants
-- Artifact IDs are canonical interface values for stage/config integration.
-- Alias support is compatibility behavior layered on top of canonical IDs.
-- Manifest producer outputs are preferred over canonical fallback when both exist.
+- built-in IDs are static and registry-backed
+- configured artifact IDs are runtime-derived (`narratio.artifact.<name>`) and catalog-backed
+- built-in/source resolution remains deterministic and validation-gated