Rewrite configuration and CLI references for native commands

This commit is contained in:
2026-11-22 06:20:54 +00:00
parent 3cf389db78
commit 5e58327032
3 changed files with 673 additions and 845 deletions

View File

@@ -1,299 +1,367 @@
# CLI Reference # CLI Reference
This is the canonical reference for the implemented Notarius command-line This is the canonical reference for Notarius invocation, command inputs, reports,
interface. For the shortest successful run, see the [README](../README.md). and outcome codes. [Configuration](config.md) owns fields, defaults, resource
Configuration fields, discovery rules, and selectable module keys are defined selection, and module keys; [Operations](operations.md) owns runtime state;
in [Configuration](config.md); runtime state and recovery procedures are integration contracts own domain payloads.
defined in [Operations](operations.md).
Configuration-consuming commands share the same selection: explicit `--config`, Notarius uses native CommandKit commands with ckconfig and ckprompt. The
then `NOTARIUS_CONFIG`, then working-directory, user, and system searches. A [upstream CLI reference][native-cli] owns their general parser, report, inspection,
selected file's loading failure is terminal. Reports use that selected source; and smoke semantics. The examples below show Notarius-specific selections.
the [configuration reference](config.md#configuration-discovery-and-precedence) Use help for every installed command's current options.
defines the filename groups and value precedence. Use `--config` for a fixed
service or subprocess selection.
## Command Summary ## Command Summary
~~~ ~~~text
notarius help notarius --help
notarius --version notarius help pipeline run
notarius run <pipeline-id> --input path/to/source.json [--json] [flags] notarius version
notarius config validate [--config path/to/config.yml] [--config-overlay name] [--pipeline pipeline-id] [--only lane-a,lane-b] notarius completion bash
notarius config effective [--scope notarius|promptkit] [--config path/to/config.yml] [--config-overlay name] notarius pipeline list
notarius config explain [--scope notarius|promptkit] [--config path/to/config.yml] [--config-overlay name] <json-pointer> notarius pipeline show PIPELINE_ID
notarius config profile [--config path/to/config.yml] [--config-overlay name] <profile-id> notarius pipeline validate PIPELINE_ID
notarius pipelines list [--config path/to/config.yml] [--config-overlay name] [--json] notarius pipeline run PIPELINE_ID --input-file PATH
notarius run PIPELINE_ID --input-file PATH
notarius config scopes
notarius config validate
notarius config show
notarius config sources
notarius config explain
notarius config diff
notarius promptkit list prompts
notarius promptkit show profile PROFILE_ID
notarius promptkit requirements show PROMPT_ID
notarius promptkit requirements validate PROMPT_ID
notarius promptkit show prepared PROMPT_ID
notarius promptkit test KIND
~~~ ~~~
Running Notarius without arguments, or with **help**, **--help**, or **-h**, Bare invocation, `help`, `--help`, and `-h` display native help. Help also works
writes the command summary to standard output and exits with status 0. on subcommands without their execution-only required inputs. Help, version, and
Bash/Zsh/Fish completion need no configuration, credentials, or run storage.
`notarius --version` is valid only as the sole root argument. It writes exactly `version` reports the application identity; `version --scope commandkit` selects
`notarius <version>` followed by a newline to standard output and exits with the library identity. Source-tagged installation and release-linked build identity
status 0. A tagged `go install` build can report its main-module stable tag, remain available; an unversioned checkout reports `development`. Version output
and controlled builds can inject a stable tag at link time through uses native report formats, not a custom root flag.
`gitea.maximumdirect.net/eric/notarius/internal/buildinfo.Override`; an ordinary
unversioned checkout reports `development`. Invalid injected version content is
a runtime error with exit status 1, while extra `--version` arguments are a
syntax error with exit status 2. This diagnostic does not replace the
[run-result](integrations/run-result.md) or artifact contracts for downstream
compatibility decisions.
## run ## Syntax And Supplied Values
~~~ Put flags after the **complete command path**, optionally interspersed with its
notarius run <pipeline-id> --input path/to/source.json [--json] [flags] operands. Value flags accept `--name value` or `--name=value`. Boolean flags
accept presence and explicit values such as `--debug=false`. `--` ends option
parsing; later tokens are operands.
Singleton flags may repeat; the last successfully parsed occurrence supplies
the value. Every occurrence is parsed, so a malformed earlier value remains an
error. Repeatable flags retain occurrence order and do not split commas.
Omission differs from supplied empty, false, and zero. Semantic validity still
depends on the selected command and native request. See
[registered syntax][syntax] for the shared rules.
## Configuration Selection
`--config PATH` fixes the main source; explicit empty fails instead of discovering
another file. Omission uses [configuration discovery](config.md#configuration-discovery-and-precedence).
Commands that support `--overlay NAME` select the native application overlay.
Configuration and pipeline commands also expose repeated `--set POINTER=JSON`:
~~~sh
notarius config show --config examples/dnd-minimal/config.yml \
--set /concurrency/workers=1 --path /concurrency/workers --format json
~~~ ~~~
The **run** command executes the named pipeline for one input file. The The value is JSON, so strings require JSON quoting. Preserve shell quoting:
pipeline ID and **--input** are required.
| Flag | Meaning | ~~~sh
notarius pipeline validate dnd-session \
--config examples/dnd-minimal/config.yml \
--set '/pipelines/dnd-session/mode="permissive"' \
--set /pipelines/dnd-session/max_additional_turns=0
~~~
Assignments use non-root mapping paths, not sequence indexes. To change a record
inside a steps/resource list, use an appropriate source/overlay or replace the
complete list. Duplicate or overlapping assignments fail. Version and inheritance
controls are not assignment targets. Overrides follow native loading and recorded
resolution; they are not an alternate YAML parser. PromptKit commands expose
their own native selection/request flags; use help rather than assuming every
configuration flag applies to them.
## Pipeline Commands
`pipeline list` lists configured IDs in sorted order without module resolution
or engine construction. `pipeline show PIPELINE_ID` resolves modules, controls,
validator chains, static prompt dependencies, steps/lanes, and reference bindings,
without expanding every LLM profile or reading input/reference content.
`pipeline validate PIPELINE_ID` performs offline domain resolution and known
prompt/profile dependency checks using the shared load and engine when needed.
It requires no input transcript, reference file bytes, credential values,
provider call, or output/cache/debug directories. Partial profiles remain valid.
This is distinct from native configuration validation: request preparation and
dynamic selections are checked when used.
Show and validate accept configuration selection and native report controls.
They inspect the complete configured pipeline; lane selection belongs to run:
~~~sh
notarius pipeline list --config examples/dnd-complete/config.yml --format json
notarius pipeline show dnd-session --config examples/dnd-complete/config.yml
notarius pipeline validate dnd-session --config examples/dnd-complete/config.yml
~~~
### Run
~~~text
notarius run PIPELINE_ID --input-file PATH [flags]
notarius pipeline run PIPELINE_ID --input-file PATH [flags]
~~~
`run` is a native alias for `pipeline run`: both resolve to the same declaration
and handler. One pipeline ID and a nonempty `--input-file` are required.
| Run flag | Meaning |
| --- | --- | | --- | --- |
| **--config path** | Use this configuration file. When omitted, configuration discovery applies; see [Configuration](config.md). | | `--config PATH`, `--overlay NAME`, `--set POINTER=JSON` | Configuration selection above. |
| **--config-overlay name** | Select a ConfigKit configuration overlay. Empty and **default** select the composed base configuration. | | `--input-file PATH` | Required source input file. |
| **--input path** | Source input file to process. Required. | | `--lane ID` | Repeat to select literal artifact lane IDs; commas are part of an ID, not separators. |
| **--output-dir path** | Override the configured output root for this run. | | `--output-dir PATH` | Nonempty invocation-relative override of the output root. |
| **--json** | Write the successful run-result receipt as JSON to standard output. | | `--cache auto\|bypass\|refresh` | Invocation-wide selection over binding and pipeline cache controls. |
| **--chunk_cache auto\|bypass\|refresh** | Override chunk-plan cache handling for this run. | | `--reference SELECTOR=PATH` | Repeatable external reference bind. |
| **--resume** | Reuse compatible recorded checkpoints when checkpoint recording is enabled. | | `--without-reference SELECTOR` | Repeatable external reference unbind. |
| **--recompute-step step-id** | With **--resume**, recompute the selected ordered step and its dependent lanes. It cannot be combined with **--only**. | | `--debug[=true\|false]` | Native debug verbosity and independent run capture selection. |
| **--debug** | Retain a debug bundle for this run. | | `--debug-dir PATH` | Capture destination override; explicit empty disables capture. |
| **--debug-dir path** | Override the debug-bundle root. Requires **--debug**. | | `--llm-profile ID`, `--llm-session-id ID` | Native resource/session selections below. |
| **--only lane-a,lane-b** | Run only the selected comma-separated artifact lanes when that selection is valid for the configured pipeline. | | `--llm-*` execution controls | Run-wide request overrides below. |
| **--llm-profile id** | Highest-precedence configured profile for selected LLM-backed bindings and validators; it replaces binding and [pipeline](config.md#pipelines) defaults. | | `--format`, `--quiet`, `--verbose`, `--progress` | Native presentation controls below. |
| **--session-id id** | Override the generated prompt session identifier with a non-empty value for LLM-backed module calls. |
| **--reasoning-effort value** | Replace the selected PromptKit profile's reasoning effort for every LLM-backed call in this run. The value must be non-empty and the flag may be specified only once. |
| **--clear-reasoning-effort** | Clear reasoning effort inherited from the selected PromptKit profile for every LLM-backed call in this run. |
| **--reference selector=path** | Add or replace external file reference bindings at pipeline, lane, chunk, or binding scope. Repeatable. |
| **--without-reference selector** | Remove matching configured external reference bindings. Repeatable. |
**--chunk_cache** accepts only **auto**, **bypass**, or **refresh**. A directory alone does not enable capture. A nonempty debug-directory override
**--debug-dir**, **--output-dir**, **--session-id**, and can re-enable capture over an empty configured root, but still needs debug
**--reasoning-effort**, and **--recompute-step** reject explicit empty values. selection. `--debug --quiet` captures while suppressing stdout; `--quiet --debug`
**--reasoning-effort** and **--clear-reasoning-effort** are mutually exclusive. selects debug visibility and capture. `--debug=false` disables capture. Debug
When neither is present, reasoning effort comes from the selected PromptKit on inspection commands changes native visibility without allocating a pipeline
profile. These controls apply to the shared run client, including retries and bundle. [Configuration](config.md#concurrency-output-cache-and-debug) defines
LLM-backed validators, and do not modify configuration or profile files. directory defaults; [Operations](operations.md) owns capture lifecycle.
Persistent reasoning settings remain a PromptKit profile concern.
**--recompute-step** requires **--resume**; checkpoint requirements and reuse
behavior are documented in [Operations](operations.md).
Every run uses one effective prompt session. Without **--session-id**, Notarius Example using the maintained minimal configuration and input:
generates a stable `notarius:v1:` identifier from the trimmed resolved input
module key and the input file's exact raw bytes. The same module and bytes
therefore produce the same identifier, regardless of pipeline, references,
profile, retries, or run settings. An explicit non-empty value replaces that
default. Session identifiers are visible to providers; they are non-secret
correlation identifiers, not credential storage. See
[Operations](operations.md#operational-limits) for privacy and workflow
guidance.
### Reference selectors
Use **--reference** only for reference slots declared by the selected
configured targets. Qualification narrows the scope of an override:
| Form | Target |
| --- | --- |
| slot=path | Every selected target that declares slot. |
| chunk.slot=path | The chunker. |
| lane.slot=path | Every extractor, merger, or normalizer in lane that declares slot. |
| lane.extract.slot=path | The extractor in lane. |
| lane.merge.slot=path | The merger in lane. |
| lane.normalize.slot=path | The normalizer in lane. |
Pipeline- and lane-scoped selectors are expected to match multiple targets and
fail if they match none. A stage-specific selector fails when its lane is not
selected or its target does not declare the slot. There is no stage-wide
`merge.slot` shorthand; name the lane when targeting a merger.
CLI bindings override configured external paths. For overlapping CLI
selectors, a binding-specific or chunk selector overrides a lane selector, and
a lane selector overrides a pipeline selector. The last occurrence wins at
equal scope. Binding and unbinding the same concrete target at equal scope is
an error; a narrower bind or unbind may create an intentional exception to a
broader action.
**--without-reference** uses the same selector forms without `=path` and
removes external bindings only. Neither flag replaces or removes a generated
artifact handoff; an external/generated collision is a resolution error.
Required slots are checked after all effective changes. CLI reference paths
are resolved relative to the process working directory, so subprocess and
service callers should use absolute paths. Slot names, accepted media types,
size limits, requiredness, and configured generated bindings are part of the
[configuration contract](config.md).
For example, one shared campaign reference can reach every compatible target,
with an optional lane-specific exception:
~~~sh
notarius run dnd-session --config examples/dnd-minimal/config.yml \
--input-file examples/dnd-minimal/transcript.json --format json
~~~ ~~~
notarius run dnd-session \
--input /data/transcript.json \ This run uses a configured provider and needs its credentials when required.
Offline validation does not.
### Run-wide LLM Overrides
These canonical ckprompt flags reach initial producers, semantic corrections,
and LLM validators on the shared native engine without mutating configuration:
| Flag | Value |
| --- | --- |
| `--llm-profile` | Exact profile ID; qualified for collection resources. |
| `--llm-session-id` | Session selection. |
| `--llm-endpoint` | Native endpoint override. |
| `--llm-model` | Model override. |
| `--llm-temperature` | Numeric temperature. |
| `--llm-max-tokens` | Integer token limit. |
| `--llm-top-p` | Numeric top-p. |
| `--llm-timeout-seconds` | Integer native request timeout. |
| `--llm-service-tier` | Service tier selection. |
| `--llm-reasoning-effort` | Reasoning selection; explicit empty suppresses inherited reasoning. |
| `--llm-api-key-env` | Credential environment-variable name, not its value. |
| `--llm-transient-retries` | Integer native transient-failure retry selection; explicit zero disables these retries. |
| `--llm-extra-params` | JSON provider-parameter object, preserving false/zero/null values. |
Omitted values remain unspecified, not the display defaults in help.
`--llm-temperature=0` and `--llm-reasoning-effort=` retain their supplied meaning.
Native target validation and provider-map rules apply; this interface does not
add a repair-model selection, structural-repair count, or generic stage retry.
Use application configuration for semantic turns and native prompt configuration
for structural contracts.
Omitted profile selection preserves binding/pipeline/prompt precedence.
Explicit `--llm-profile=` clears the application profile selection so native
prompt default selection applies. Without an explicit session flag, Notarius
generates a stable `notarius:v1:` session from the trimmed resolved input module
key and exact raw input bytes, independent of references and pipeline/profile
settings. An explicit value replaces it; explicit empty clears that generated
selection and leaves native prompt/session behavior in control. Sessions are
provider-visible correlation identifiers, not secret storage.
PromptKit convenience spellings are scoped to `promptkit` commands; run uses
the canonical `--llm-*` names above. [Native request validation][requests]
documents execution controls in detail.
### Reference Selectors
Bind declared slots using `--reference SELECTOR=PATH`:
| Selector | Target |
| --- | --- |
| `slot` | Every selected compatible target declaring the slot. |
| `chunk.slot` | Chunker. |
| `lane.slot` | Compatible extract/merge/normalize bindings in that lane. |
| `lane.extract.slot` | That lane's extractor. |
| `lane.merge.slot` | That lane's merger. |
| `lane.normalize.slot` | That lane's normalizer. |
Pipeline/lane selectors may match several targets and fail if they match none.
A binding-specific selector requires its selected target to declare the slot.
There is no stage-wide merger shorthand. CLI paths override configured external
paths; narrower selectors beat broader ones, with last occurrence winning at
equal scope. Binding and unbinding the same concrete target at equal scope fails;
narrower actions can make intentional exceptions to broader actions.
`--without-reference` uses the selector without `=PATH`. It removes external
bindings only. Neither action replaces/removes generated handoffs; collisions
fail resolution and required slots must remain bound. CLI paths use the invocation
working directory. Configuration defines slot compatibility and path origins in
[References And Ordered Handoffs](config.md#references-and-ordered-handoffs).
For a complete D&D workflow, pipeline-level references are first-class inputs:
~~~sh
notarius run dnd-session --config examples/dnd-complete/config.yml \
--input-file examples/dnd-complete/transcript.json \
--reference party=/data/references/party.txt \ --reference party=/data/references/party.txt \
--reference npc-registry.party=/data/references/npc-party-context.txt --reference glossary=/data/references/glossary.txt \
--output-dir /data/results --format json
~~~ ~~~
### Run output ### Completion Report
Without **--json**, standard output contains the completed pipeline ID, counts Successful runs publish domain files and finalize requested capture before
of normalized and rejected outputs, and the output directory. A debug-enabled reporting one small value:
run also prints its debug-bundle path to standard output. A successful run with
actionable process warnings reports their group and occurrence counts to
standard error. When the selected output module publishes `warnings.json`, the
summary also reports that durable file's path. Advisory and observation findings
do not produce a warning line. The published JSON bundle
is defined by the [JSON output contract](integrations/json-output.md).
With **--json**, successful standard output is exactly one | Field | Meaning |
`notarius.run-result.v2` JSON document followed by a newline, with no | --- | --- |
human-oriented status or debug-path line. Its fields and compatibility policy | `pipeline` | Selected pipeline ID. |
are defined by the [run-result contract](integrations/run-result.md). A caller | `artifact_count` | Published deliverable files, including reused artifacts and enabled auxiliaries; excludes intermediates/cache/debug. |
must check for exit status 0 before decoding this output; a failed write can | `output_directory` | Absolute run-specific publication directory, not the configured root. |
leave incomplete standard-output bytes that are not a result document. | `debug_directory` | Optional absolute run capture directory; omitted when disabled. |
| `fallback_count` | Producer operations that emitted fallback, present only when positive. |
Example: Text summarizes pipeline, count, and path, appending capture location when
available. Fallback success is explicitly qualified, even when warnings are
hidden. Affected downstream artifacts, attempts, and validators are not extra
fallbacks. JSON/YAML serialize the same value; report format does not change
domain artifact encoding. There is no persisted receipt, execution ledger,
universal envelope, or automatic duplicate report file.
~~~ Consumers check status, optionally decode the report, and read configured
OPENROUTER_API_KEY=your-api-key \ lane/auxiliary paths. A failed stdout write may leave partial bytes. A failure
go run ./cmd/notarius run dnd-session \ after publication can leave valid artifacts; the failure explanation identifies
--config examples/dnd-minimal.config.yml \ available paths. [JSON output](integrations/json-output.md) owns logical artifact
--input examples/seriatim-minimal-transcript.json paths and payload contracts, not this report.
## Configuration Commands
The native scopes are `app` (default) and `promptkit`. Both inspect the same
application-owned load; the latter focuses native PromptKit settings. Use
`config scopes` for supported operations. No inspection command implicitly runs
a pipeline or provider.
~~~sh
notarius config validate --config examples/dnd-minimal/config.yml
notarius config show --scope app --config examples/dnd-minimal/config.yml
notarius config sources --config examples/dnd-complete/config.yml
notarius config explain --config examples/dnd-minimal/config.yml \
--path /concurrency/workers --format json
notarius config show --scope promptkit --config examples/dnd-minimal/config.yml
notarius config diff --config examples/dnd-minimal/config.yml \
--against-config examples/dnd-complete/config.yml --check
~~~ ~~~
## config validate Show supports `--path`; explain supports `--list`, `--path`, and native history/
filter options. Focused PromptKit paths retain the `/promptkit` prefix, for
example `/promptkit/collections/notarius/profiles`. Diff accepts separate
right-side configuration, overlay, and assignment inputs; differences with
`--check` yield status 3. These commands
report native values and secret-aware source evidence, not copied Notarius
inspection objects. Consult [native configuration commands][configuration]
for complete report and comparison semantics. Use `pipeline validate`, not
configuration validation, for production module/reference/resource preflight.
~~~ ## PromptKit Commands
notarius config validate [--config path/to/config.yml] [--config-overlay name] [--pipeline pipeline-id] [--only lane-a,lane-b]
The installed native suite includes:
- listings of prompts, profiles, backends, namespaces, and collections;
- inspection of a named prompt, profile, or backend;
- requirements discovery, concrete request validation, and prepared preview;
- explicit smoke tests: `reachability`, `authentication`, `text_inference`,
`structured_output`, or `all`.
~~~sh
notarius promptkit list prompts --config examples/dnd-minimal/config.yml \
--namespace notarius
notarius promptkit show profile notarius/dnd-extraction \
--config examples/dnd-minimal/config.yml --format json
notarius promptkit requirements show notarius/dnd.spells \
--config examples/dnd-minimal/config.yml
~~~ ~~~
This command loads and validates the selected composed configuration. With **--pipeline**, it also Resource/requirements inspection needs no transcript, credential values, or
resolves that pipeline against the production module catalog. **--only** selects provider call. Profile reports describe the stored profile before backend
lanes during that resolution and requires **--pipeline**. completion and request overrides; partial profiles are valid. Request validation
and `show prepared` actually prepare native requests and may read supplied
resources or require credentials according to the target, but do not call a
model. Prepared reports can contain rendered application data.
Success is written to standard output as either config "<path>" is valid or Use `--llm-var KEY=VALUE`, `--llm-input-text NAME=TEXT`, or
config "<path>" is valid for pipeline "<pipeline-id>". `--llm-input-file NAME=PATH` for concrete prompt inputs. These are not the
pipeline's source input. Namespace flags choose namespaces for short IDs;
already-qualified IDs remain unchanged. Native convenience aliases are installed
only on their applicable PromptKit commands; use help to see them.
Examples: Smoke tests are explicit and may contact providers or perform inference.
Read support, applicability, and observation results; status zero alone does
~~~ not mean every observation passed. Neither debug nor inspection silently
go run ./cmd/notarius config validate \ launches a smoke test. Full native mechanics are documented under
--config examples/dnd-minimal.config.yml \ [inspection][inspection], [preview][preview], [requirements][requirements],
--pipeline dnd-session [resource listings][catalogs], and [smoke tests][smoke].
OPENROUTER_API_KEY=validation-placeholder \
go run ./cmd/notarius config validate \
--config examples/dnd-complete.config.yml \
--pipeline dnd-session
~~~
The placeholder in the second command is sufficient only for offline
validation; it cannot run a provider-backed pipeline.
## config effective
~~~
notarius config effective [--config path/to/config.yml] [--config-overlay name]
~~~
This command writes the selected composed configuration as deterministic,
redacted YAML. By default, it reports the Notarius configuration. Set
**--scope promptkit** to report PromptKit's captured effective configuration;
**--scope notarius** is equivalent to the default. Only the PromptKit scope
constructs the PromptKit inspection engine, using the selected configuration
and registered application assets. Engine construction validates and captures
the definitions. Standard output contains only the selected report: the
command does not validate a pipeline, prepare modules, materialize references,
resolve credentials, or contact a provider. PromptKit output can include
ordinary inline prompt and provider-parameter data; credential-shaped provider
parameters are redacted.
## config explain
~~~
notarius config explain [--config path/to/config.yml] [--config-overlay name] <json-pointer>
~~~
This command writes a redacted, human-readable explanation for one canonical
JSON Pointer. Supply `""` explicitly to explain the root. By default, it
explains Notarius configuration; **--scope promptkit** selects PromptKit
configuration history, while **--scope notarius** is equivalent to the default.
A malformed pointer is a syntax error; a well-formed unknown path is a command
failure. The explanation can describe values displaced by source overlays or
imports. Standard output contains only the selected explanation. PromptKit
scope constructs and validates its captured definitions, and its report can
include ordinary inline prompt and provider-parameter data.
## config profile
~~~
notarius config profile [--config path/to/config.yml] [--config-overlay name] <profile-id>
~~~
This command inspects one exact, nonblank PromptKit profile ID and writes one
JSON object followed by a newline:
The following illustrates the JSON shape; field values vary with the selected
profile and its configured backend.
~~~json
{"profile_id":"example","api_key_required":true,"effective_model_params":{"backend_id":"openrouter","endpoint":"https://provider.example/v1","model":"example-model","temperature":0,"max_tokens":0,"top_p":0,"timeout_seconds":600,"service_tier":"","reasoning_effort":"","api_key_env":"PROVIDER_API_KEY","extra_params":null}}
~~~
The object reports the resolved target, including backend-completed endpoint
and credential-name settings. An empty **backend_id** identifies an
endpoint-only profile. Credential names and **api_key_required** are configured
metadata; the command does not look up credential values or report whether an
environment variable is set. Credential-shaped keys in **extra_params** are
redacted.
This is the named profile's configured target, not a prediction of provider
defaults or the profile selected by an individual request. A request may omit
its profile and let its prompt select a default, and a run may supply a profile
override; this command applies neither behavior. Zero-valued fields show the
effective value but do not distinguish omission from an explicit zero. Use
[effective configuration](#config-effective) and
[configuration explanation](#config-explain) to inspect source presence and
history. Profile/configuration failures use exit status 1; malformed command
syntax, a blank ID, or an incorrect argument count use exit status 2. No
transcript or model call is involved.
## pipelines list
~~~
notarius pipelines list [--config path/to/config.yml] [--config-overlay name] [--json]
~~~
This command lists configured pipeline IDs in sorted order. By default, it
writes one ID per line to standard output. **--json** writes an object shaped as
{"pipelines":[...]} instead.
~~~
go run ./cmd/notarius pipelines list \
--config examples/dnd-minimal.config.yml
~~~
## Output Streams And Exit Statuses ## Output Streams And Exit Statuses
Successful commands write their primary result to standard output. Warnings and Results go to stdout; failures, native diagnostics, and progress go to stderr.
errors are written to standard error. `--format text|json|yaml` selects report presentation. Default run presentation
uses its human template; other structured native reports ordinarily use YAML.
`--format` does not reformat help, completion scripts, diagnostics, or domain
payloads.
Configuration load errors include ConfigKit's field diagnostics and source Only one visibility mode is active; the last enabled `--quiet`, `--verbose`,
coordinates, followed by a source-ID legend identifying the acquired files or or `--debug` wins. Ordinary mode hides optional warning/info/debug messages;
source labels. This includes imported files and the selected configuration overlay. verbose shows warning/info; debug adds debug and default progress. Explicit
`--progress=false` disables progress, and quiet suppresses it. Quiet suppresses
stdout but retains failure explanations; formatting errors can still fail a
quiet command. Run capture selection remains independent of that final mode.
For **run --json**, actionable process warnings remain on standard error and standard output is a `--format json --verbose` keeps successful stdout report-only JSON while useful
machine-readable success result only. Syntax and runtime diagnostics remain on diagnostics go to stderr. No application-wide structured error envelope is
standard error. Parse the result only after the process exits with status 0. introduced; failed stdout is not a success document.
| Status | Meaning | | Status | Meaning |
| --- | --- | | --- | --- |
| 0 | The command completed successfully, including root help. | | `0` | Command completed, including supported permissive fallback with report qualification. |
| 1 | Command syntax was valid but configuration loading or validation, pipeline resolution or execution, provider use, output, or requested debug handling failed. | | `1` | Operational failure, cancellation, publication/capture/presentation failure, or an unclassified/mixed failure. |
| 2 | The command or flag syntax was invalid, including unknown commands, missing required arguments, invalid flag values, or invalid flag combinations. | | `2` | Invalid invocation or identifiable invalid configuration. |
| `3` | Native configuration differences with diff check mode. |
The root help spellings are the supported help path. Invoking **--help** on Native causes and classification remain intact. Not every resource/preflight
**run**, a **config** subcommand, or **pipelines list** is handled by the flag failure is identifiable invalid configuration. Rendering or diagnostic delivery
parser as a usage error: it writes an error to standard error and exits with failure can change an otherwise successful result to failure; callers check the
status 2. actual process status. See [native outcomes][outcomes] for library conventions.
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md
[syntax]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#registered-command-syntax
[configuration]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#configuration-scopes
[requests]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#concrete-request-validation
[inspection]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-definition-inspection
[preview]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-prepared-request-preview
[requirements]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-requirements
[catalogs]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-catalogs
[smoke]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-smoke-testing
[outcomes]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#outcome-status

File diff suppressed because it is too large Load Diff

View File

@@ -1894,6 +1894,28 @@ implemented behavior. Check ADR status links and accepted-body preservation;
## Stage 39: Rewrite Canonical Configuration And CLI References ## Stage 39: Rewrite Canonical Configuration And CLI References
**Status:** Complete. Rewrote the canonical configuration and CLI references for
version 6, shared native source selection/companions, whole-record resource
replacement and inheritance, null/presence and schema-root semantics, qualified
profiles, workers, semantic turns, strict/permissive modes, and unified reuse
controls. Documented native pipeline/standard commands, supplied/repeated values,
references, complete run-wide execution overrides, presentation/streams, the small
completion report, and outcome classifications. Removed retired syntax and old
example paths rather than preserving compatibility examples. Native default
repair/retry and backend admission remain upstream-owned. Retained domain module,
reference-slot, output-option, and default-validator definitions, checking all 20
D&D extract/normalize chains against the real resolved complete pipeline.
Compared declarations, configuration/resolver tests, actual help, maintained
examples, and the selected upstream module documentation. Twenty direct offline
help/completion/configuration/inspection/preflight/diff checks pass with the
OpenRouter credential variable unset; assignment/explicit-zero examples also
pass. All 46 local links/anchors and 20 pinned upstream destinations/anchors
resolve against repository/module sources. Whole-tree tests, vet, a temporary
executable build with `GOWORK=off`, and `git diff --check` pass. No live inference
or real credential was used. Operations, migration, integration, and internal
documentation retain their following assigned stages.
**Goal:** operators can configure and invoke only the implemented native surface. **Goal:** operators can configure and invoke only the implemented native surface.
**Inspect/change:** `docs/config.md`, `docs/cli.md`, final command declarations, **Inspect/change:** `docs/config.md`, `docs/cli.md`, final command declarations,