Add developer and internal architecture documentation

docs/internal/diagnostics.md

@@ -0,0 +1,88 @@
+# Diagnostics Internals
+
+Diagnostics internals live in `internal/core/diagnostics`. Operator-facing run
+behavior is documented in [Operations](../operations.md).
+
+## Purpose
+
+Diagnostics provide local inspection artifacts for a run without becoming the
+durable output contract. Durable user output is produced by output modules and
+written by the CLI.
+
+Diagnostics must not expose secrets.
+
+## Run Directory
+
+`NewRunDirectory(workDir, retention)` creates:
+
+```text
+<workDir>/run-<unix-nanoseconds>/
+```
+
+If `workDir` is empty, it defaults to `/tmp/notarius`. Empty retention defaults
+to `auto`.
+
+The writer makes the work directory if needed, then attempts to create a unique
+run directory. It retries run ID creation a bounded number of times if a
+collision occurs.
+
+## Artifact Writers
+
+Implemented artifact names:
+
+- `invocation.json`
+- `effective-config.json`
+- `resolved-pipeline.json`
+- `source-document.json`
+- `run-manifest.json`
+- `run-report.json`
+- `warnings.json`
+- `error.log`
+
+JSON artifacts are encoded with indentation and a trailing newline. Writes are
+atomic through a temporary file in the target directory followed by rename.
+
+Artifact names must be single relative file names. Absolute paths, path
+separators, and names resolving outside the run directory are rejected.
+
+## Redacted Effective Config
+
+Diagnostics writers accept payloads that implement
+`RedactedDiagnosticsPayload`. `internal/core/config` uses this to redact API
+keys in effective config diagnostics while preserving resolved pipeline context.
+
+The redaction path clones config data before replacing secret values.
+
+## Retention
+
+Retention is decided by `ShouldRetainRunDirectory`.
+
+- Failed runs are always retained.
+- `always` retains successful runs.
+- `never` removes successful runs.
+- `auto` retains successful runs only when warnings exist.
+- Unknown retention values are treated as retain by the retention decision, but
+  config validation rejects unsupported values before normal runs.
+
+`ApplyRetention` removes only the specific run directory.
+
+## CLI Failure Behavior
+
+The CLI creates the diagnostics run directory after config loading and before
+pipeline resolution. Failures before that point do not have diagnostics.
+
+After diagnostics creation, run failures call `WriteErrorLog` and apply
+retention with `RunSucceeded: false`, so the run directory remains available.
+
+When the pipeline returns a partial manifest on failure, the CLI writes that
+manifest before logging the failure.
+
+## Invariants
+
+- Diagnostics paths must be narrow and run-directory scoped.
+- Writes should be atomic where practical.
+- Secrets must be redacted.
+- Diagnostics write failures are command failures because they can hide the
+  information needed for recovery.
+- Durable output file contracts belong to output modules and integration docs,
+  not to diagnostics.