Refresh docs for finalized cleanup architecture

docs/internal/artifacts.md

@@ -51,37 +51,45 @@ Unknown/empty selection falls back to intermediate conversion.
 
 ## Trim internals
 
-`internal/trim` is artifact-level projection, not merge reprocessing.
+`internal/trim` handles artifact-level projection and does not execute merge
+pipeline modules.
 
-Core flow:
+Run layer (`run.go`):
 
-1. Parse selector (`internal/trim/selector.go`).
-2. Parse input artifact and detect schema (`ParseArtifactJSON`).
-3. Apply keep/remove projection with sequential ID renumbering.
-4. Recompute overlap groups only for full-schema artifacts.
-5. Optionally convert output schema when supported.
-6. Validate output artifact before write.
+1. Parse selector from validated config.
+2. Read and parse input artifact JSON.
+3. Apply trim projection through schema-aware artifact handling.
+4. Resolve output schema (preserve input schema unless overridden).
+5. Validate output artifact.
+6. Write output JSON.
+7. Optionally write report JSON with `trim-audit`.
 
-Schema-conversion limits:
+Apply layer (`apply.go`):
 
-- full -> intermediate/minimal supported.
-- intermediate -> minimal supported.
-- minimal -> intermediate supported.
-- intermediate/minimal -> full is rejected.
+- one shared projection policy for selector mode, input ID validation, selected
+  ID existence checks, keep/remove filtering, removed IDs, and old-to-new ID
+  mappings
+- schema-specific segment reconstruction for full/intermediate/minimal outputs
+- overlap-group recomputation only for full-schema outputs
+
+Artifact layer (`artifact.go`):
+
+- schema detection for full/intermediate/minimal artifacts
+- schema-preserving trim application
+- supported schema conversions:
+  - full -> intermediate/minimal
+  - intermediate -> minimal
+  - minimal -> intermediate
+- rejected conversion:
+  - intermediate/minimal -> full
 
 Trim invariants:
 
 - selected IDs must exist in input.
 - input IDs must be positive, unique, sequential.
-- retained order follows input transcript order.
+- retained segment order follows input transcript order.
 - output IDs are reassigned to `1..N`.
 
-Run layer (`run.go`):
-
-- executes end-to-end trim orchestration from validated config
-- writes output JSON
-- optionally writes report JSON with `trim-audit`
-
 ## Normalize internals
 
 `internal/normalize` canonicalizes transcript-like JSON input into a selected

docs/internal/modules.md

@@ -55,7 +55,8 @@ Output writer:
 - `autocorrect`: applies YAML replacement rules when configured.
 - `assign-ids`: assigns final sequential IDs.
 - `validate-output`: validates selected public artifact shape.
-- `json`: writes artifact JSON to `cfg.OutputFile`.
+- `json`: writes artifact JSON to `cfg.OutputFile` through shared deterministic
+  JSON file writing.
 
 Filesystem side effects are limited to: