Reorganize user and operator documentation

docs/integrations/json-output.md

@@ -3,16 +3,9 @@
 This document is the durable JSON output file-format contract produced by the
 implemented `json` output module and written by the CLI.
 
-## Output Directory
-
-The CLI writes logical output files under:
-
-```text
-<output-root>/<run-id>/
-```
-
-The default output root is `./notarius-output`. Operational behavior is covered
-in [Operations](../operations.md).
+The output module produces the logical bundle described here. The CLI's
+physical placement and lifecycle for that bundle are defined in
+[Operations](../operations.md#output-directory).
 
 ## Files
 
@@ -25,6 +18,7 @@ The `json` output module writes:
 - `warnings.json`
 
 Files are pretty-printed JSON with a trailing newline when the payload is JSON.
+Logical file paths are relative, slash-separated, and may not contain `..`.
 
 ## `index.json`
 
@@ -58,22 +52,21 @@ sanitizing the lane ID:
 - empty sanitized names are rejected;
 - two lanes that sanitize to the same output file are rejected.
 
+`manifest_file`, `rejected_file`, and `warnings_file` contain the fixed paths
+shown above. Each `output_files` entry requires `lane_id` and `file`. It also
+contains the normalized payload `media_type`, normalizer `module_key`, and
+response `schema_id`, `schema_name`, and `schema_version` when those values are
+available.
+
 ## `manifest.json`
 
-`manifest.json` contains a run manifest:
+`manifest.json` contains a run manifest. This abridged example shows its core
+structure:
 
 ```json
 {
   "run_id": "run-123",
   "pipeline_id": "dnd-session",
-  "pipeline_digest": "sha256:...",
-  "input_module": "seriatim",
-  "chunker": "dnd/scenes",
-  "source_digests": ["sha256:..."],
-  "extractors": ["dnd/spells"],
-  "merger": "appendorder",
-  "normalizer": "noop",
-  "output_encoder": "json",
   "artifact_lanes": [
     {
       "id": "spells",
@@ -82,35 +75,6 @@ sanitizing the lane ID:
       "normalizer": "noop"
     }
   ],
-  "validator_chains": [
-    {
-      "stage": "extract",
-      "lane_id": "spells",
-      "module_key": "dnd/spells",
-      "validators": [
-        {
-          "key": "generic/valid_json",
-          "execution_class": "deterministic"
-        },
-        {
-          "key": "generic/valid_json_schema",
-          "execution_class": "deterministic"
-        },
-        {
-          "key": "extract/dnd/spells/shape",
-          "execution_class": "deterministic"
-        },
-        {
-          "key": "extract/dnd/spells/source_refs",
-          "execution_class": "deterministic"
-        },
-        {
-          "key": "extract/dnd/spells/source_relatedness",
-          "execution_class": "deterministic"
-        }
-      ]
-    }
-  ],
   "validation_status": "approved",
   "started_at": "2026-01-01T00:00:00Z",
   "completed_at": "2026-01-01T00:00:01Z"
@@ -119,6 +83,23 @@ sanitizing the lane ID:
 
 Fields with empty values may be omitted by JSON encoding.
 
+The manifest fields are:
+
+- `run_id`, `pipeline_id`, and `pipeline_digest`: run and resolved-pipeline
+  identity;
+- `input_module`, `chunker`, `extractors`, `merger`, `normalizer`, and
+  `output_encoder`: resolved module keys;
+- `module_metadata` and `artifact_lanes`: module and per-lane provenance,
+  including prompt and response-schema provenance when provided;
+- `validator_chains`: resolved validation points and validators;
+- `source_digests` and `references`: source and reference provenance;
+- `normalized_outputs` and `rejected_outputs`: payload-free result summaries;
+- `llm_profiles`: selected profile IDs and provider or model names when
+  available;
+- `metadata`: the effective prompt `session_id`;
+- `validation_status`: `approved` or `rejected`;
+- `started_at` and `completed_at`: UTC run timestamps.
+
 `source_digests` contains source document digests only. Bound references are
 recorded separately under `references`, which contains provenance only: target
 stage, lane ID when present, slot name, origin type and URI, digest, media
@@ -152,27 +133,8 @@ Each normalized raw output is written to `lanes/<sanitized-lane-id>.json`.
 The JSON output encoder accepts only `application/json` normalized outputs. The
 file contains the raw JSON payload pretty-printed.
 
-For the current D&D spell extractor, `lanes/spells.json` has this shape:
-
-```json
-{
-  "spell_casts": [
-    {
-      "caster": "Aria",
-      "spell": "Cure Wounds",
-      "effect": "heals an injured ally",
-      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
-      "source_refs": [
-        {
-          "source_id": "session-alpha",
-          "start_unit_id": 1,
-          "end_unit_id": 1
-        }
-      ]
-    }
-  ]
-}
-```
+The schema of each lane payload is owned by that artifact contract. For the
+current D&D spell lane, see [D&D Spell Raw Output](dnd-spell-artifacts.md).
 
 ## `rejected.json`
 
@@ -184,10 +146,10 @@ Shape:
 }
 ```
 
-When raw output validation rejects an output, entries use the
-`contracts.RejectedOutput` shape, including stage, lane ID, module key,
-validator name, reason code, message, attempt count, and optional diagnostic
-artifact path.
+When raw output validation rejects an output, each entry contains `stage` and
+`message`. It includes `lane_id`, `module_key`, `chunk_id`, `chunk_index`,
+`validator_name`, `reason_code`, `attempt_count`, and
+`diagnostic_artifact_path` when applicable.
 
 ## `warnings.json`
 
@@ -206,3 +168,5 @@ Shape:
 ```
 
 `warnings` is an empty array when no warnings are reported.
+Each warning requires `reason_code` and `message`; `scope` is omitted when it is
+empty.