Add user documentation for Notarius CLI and config

docs/cli.md

@@ -0,0 +1,126 @@
+# CLI Reference
+
+This is the canonical reference for the implemented Notarius command-line
+interface.
+
+## Quick Run
+
+```sh
+NOTARIUS_LLM_DEFAULT_BASE_URL=http://127.0.0.1:8080/v1 \
+NOTARIUS_LLM_DEFAULT_MODEL=your-model \
+go run ./cmd/notarius run dnd-session \
+  --config examples/dnd-spells.config.yml \
+  --input examples/seriatim-minimal-transcript.json
+```
+
+Set `NOTARIUS_LLM_DEFAULT_API_KEY` if the OpenAI-compatible provider requires
+a bearer token.
+
+## Commands
+
+```text
+notarius help
+notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b]
+notarius config validate --config path/to/config.yml [--pipeline pipeline-id] [--only lane-a,lane-b]
+notarius pipelines list --config path/to/config.yml [--json]
+```
+
+Running `notarius` with no arguments, `notarius help`, `notarius --help`, or
+`notarius -h` prints usage and exits successfully.
+
+## `run`
+
+`notarius run <pipeline-id>` executes a configured pipeline against one input
+file.
+
+Flags:
+
+- `--input path`: required source input file.
+- `--config path`: config file path. If omitted, Notarius checks
+  `NOTARIUS_CONFIG`, then `/usr/local/etc/notarius/config.yml`.
+- `--only lane-a,lane-b`: run only the named artifact lanes. Values are
+  comma-separated and must be non-empty.
+- `--output-dir path`: output root. The run writes to `<path>/<run-id>/`.
+  Defaults to `./notarius-output`.
+- `--diagnostics-dir path`: diagnostics work directory override for this
+  invocation.
+- `--llm-profile id`: override every effective module binding to use one LLM
+  profile.
+
+On success, the command prints the completed pipeline ID, approved and rejected
+artifact counts, and the output directory. If the run completes with warnings,
+the warning count is printed to stderr.
+
+The current `run` command requires the resolved pipeline to use exactly one
+distinct LLM profile after defaults and overrides are applied.
+
+## `config validate`
+
+`notarius config validate` loads and validates configuration.
+
+Flags:
+
+- `--config path`: config file path. If omitted, discovery uses
+  `NOTARIUS_CONFIG`, then `/usr/local/etc/notarius/config.yml`.
+- `--pipeline pipeline-id`: additionally resolve one configured pipeline against
+  the production module catalog.
+- `--only lane-a,lane-b`: validate resolution for selected artifact lanes. This
+  flag requires `--pipeline`.
+
+Examples:
+
+```sh
+go run ./cmd/notarius config validate \
+  --config examples/dnd-spells.config.yml
+
+go run ./cmd/notarius config validate \
+  --config examples/dnd-spells.config.yml \
+  --pipeline dnd-session \
+  --only spells
+```
+
+## `pipelines list`
+
+`notarius pipelines list` prints configured pipeline IDs in sorted order.
+
+Flags:
+
+- `--config path`: config file path. If omitted, discovery uses
+  `NOTARIUS_CONFIG`, then `/usr/local/etc/notarius/config.yml`.
+- `--json`: print `{"pipelines":[...]}` instead of one ID per line.
+
+Examples:
+
+```sh
+go run ./cmd/notarius pipelines list \
+  --config examples/dnd-spells.config.yml
+
+go run ./cmd/notarius pipelines list \
+  --config examples/dnd-spells.config.yml \
+  --json
+```
+
+## Exit Codes
+
+- `0`: command succeeded.
+- `1`: command syntax was valid, but loading config, resolving modules, running
+  the pipeline, calling the provider, writing output, or writing diagnostics
+  failed.
+- `2`: command syntax was invalid, a command was unknown, a required argument
+  was missing, or a flag value was malformed.
+
+## Implemented Production Pipeline Modules
+
+The production CLI currently registers these module keys:
+
+- input: `seriatim`
+- chunk: `generic`
+- extract: `dnd/spells`
+- merge: `appendorder`
+- normalize: `noop`
+- output: `json`
+
+The production CLI does not currently register validator modules.
+
+For YAML structure, defaults, environment overrides, and module binding syntax,
+see [Configuration](config.md).