Refresh docs for finalized cleanup architecture

README.md

@@ -27,19 +27,19 @@ go run ./cmd/seriatim merge \
 - Configuration reference: [docs/config.md](docs/config.md)
 - Operations guide: [docs/operations.md](docs/operations.md)
 - Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
-- Integrations:
+- Integration references:
   - [docs/integrations/whisperx-json.md](docs/integrations/whisperx-json.md)
   - [docs/integrations/output-schemas.md](docs/integrations/output-schemas.md)
-- Development architecture policy: [docs/policy/architecture.md](docs/policy/architecture.md)
+- Development policies:
-- Contributor workflow: [docs/policy/development.md](docs/policy/development.md)
+  - [docs/policy/architecture.md](docs/policy/architecture.md)
-- Documentation policy: [docs/policy/documentation.md](docs/policy/documentation.md)
+  - [docs/policy/development.md](docs/policy/development.md)
-- Internal implementation docs:
+  - [docs/policy/documentation.md](docs/policy/documentation.md)
+- Internal implementation references:
   - [docs/internal/pipeline.md](docs/internal/pipeline.md)
   - [docs/internal/artifacts.md](docs/internal/artifacts.md)
   - [docs/internal/modules.md](docs/internal/modules.md)
-- Public JSON schemas:
+- Public JSON schema files:
   - [schema/minimal-output.schema.json](schema/minimal-output.schema.json)
   - [schema/intermediate-output.schema.json](schema/intermediate-output.schema.json)
   - [schema/full-output.schema.json](schema/full-output.schema.json)
 - Synthetic examples: [examples/README.md](examples/README.md)
-- Documentation roadmap: [docs/roadmap/documentation.md](docs/roadmap/documentation.md)

docs/cli.md

@@ -179,4 +179,3 @@ go run ./cmd/seriatim normalize \
   - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json)
   - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json)
   - [../schema/full-output.schema.json](../schema/full-output.schema.json)
-- Documentation roadmap: [roadmap/documentation.md](roadmap/documentation.md)

docs/config.md

@@ -165,4 +165,3 @@ All commands:
   - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json)
   - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json)
   - [../schema/full-output.schema.json](../schema/full-output.schema.json)
-- Documentation roadmap: [roadmap/documentation.md](roadmap/documentation.md)

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`).
+1. Parse selector from validated config.
-2. Parse input artifact and detect schema (`ParseArtifactJSON`).
+2. Read and parse input artifact JSON.
-3. Apply keep/remove projection with sequential ID renumbering.
+3. Apply trim projection through schema-aware artifact handling.
-4. Recompute overlap groups only for full-schema artifacts.
+4. Resolve output schema (preserve input schema unless overridden).
-5. Optionally convert output schema when supported.
+5. Validate output artifact.
-6. Validate output artifact before write.
+6. Write output JSON.
+7. Optionally write report JSON with `trim-audit`.
 
-Schema-conversion limits:
+Apply layer (`apply.go`):
 
-- full -> intermediate/minimal supported.
+- one shared projection policy for selector mode, input ID validation, selected
-- intermediate -> minimal supported.
+  ID existence checks, keep/remove filtering, removed IDs, and old-to-new ID
-- minimal -> intermediate supported.
+  mappings
-- intermediate/minimal -> full is rejected.
+- 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:
 

docs/roadmap/audit.md

@@ -28,7 +28,7 @@ Reviewed documentation and policy:
 - `docs/internal/modules.md`
 - `docs/integrations/output-schemas.md`
 - `docs/integrations/whisperx-json.md`
-- `docs/roadmap/documentation.md`
+- `docs/roadmap/cleanup.md`
 
 Reviewed implementation areas: