Document native configuration and toolchain requirements

This commit is contained in:
2026-11-17 20:56:06 +00:00
parent 5bab35f096
commit 244f258413
6 changed files with 91 additions and 26 deletions

View File

@@ -4,6 +4,6 @@ when:
steps: steps:
- name: validate-release - name: validate-release
image: golang:1.25.5 image: golang:1.27.0
commands: commands:
- ./scripts/check-release-source.sh "$CI_COMMIT_TAG" - ./scripts/check-release-source.sh "$CI_COMMIT_TAG"

View File

@@ -31,7 +31,7 @@ demonstrates all implemented D&D lanes and the supporting campaign references.
## Install A Source Release ## Install A Source Release
Source builds require Go at or above the consumer minimum declared in Source builds require Go at or above the consumer minimum declared in
[`go.mod`](go.mod). Its patch-level minimum is required by the selected PromptKit [`go.mod`](go.mod). Go 1.27.0 is required by the selected ConfigKit
dependency. dependency.
Install a pinned source release with Go: Install a pinned source release with Go:

View File

@@ -6,6 +6,13 @@ Configuration fields, discovery rules, and selectable module keys are defined
in [Configuration](config.md); runtime state and recovery procedures are in [Configuration](config.md); runtime state and recovery procedures are
defined in [Operations](operations.md). defined in [Operations](operations.md).
Configuration-consuming commands share the same selection: explicit `--config`,
then `NOTARIUS_CONFIG`, then working-directory, user, and system searches. A
selected file's loading failure is terminal. Reports use that selected source;
the [configuration reference](config.md#configuration-discovery-and-precedence)
defines the filename groups and value precedence. Use `--config` for a fixed
service or subprocess selection.
## Command Summary ## Command Summary
~~~ ~~~

View File

@@ -1,7 +1,7 @@
# Configuration # Configuration
This is the canonical reference for Notarius configuration. Configuration files This is the canonical reference for Notarius configuration. Configuration files
are YAML and must declare version 5. They select pipelines and their modules; are YAML; the main file must declare version 5. They select pipelines and their modules;
the [CLI reference](cli.md) owns invocation syntax, and the [CLI reference](cli.md) owns invocation syntax, and
[Operations](operations.md) owns run-state procedures. [Operations](operations.md) owns run-state procedures.
@@ -11,17 +11,30 @@ Commands that load configuration choose a file in this order:
1. a non-empty **--config** CLI value; 1. a non-empty **--config** CLI value;
2. a non-empty **NOTARIUS_CONFIG** environment value; 2. a non-empty **NOTARIUS_CONFIG** environment value;
3. the installed default file at **/usr/local/etc/notarius/config.yml**, when 3. `notarius.yml`, then `notarius.yaml` in the working directory;
it exists. 4. the user configuration directory; then
5. the Unix system configuration directories.
The command fails if none of these paths provides a configuration file. The user search checks `<user-config>/notarius/` for `notarius.yml`,
`notarius.yaml`, `config.yml`, `config.yaml`, `main.yml`, and `main.yaml`, in
that order, then `<user-config>/notarius.yml` and `notarius.yaml`. The system
search uses the same groups under `/usr/local/etc/notarius/` and `/etc/notarius/`,
then `/etc/notarius.yml` and `/etc/notarius.yaml`. Generic filenames in the
working directory are not candidates. Home-directory search is not enabled.
Discovery selects one main file; it does not layer all candidates. A missing
candidate advances the search, but an explicitly selected missing file, access
error, or invalid selected file fails without fallback. An exhausted search
fails. Use an explicit `--config` for services and subprocesses that need a
fixed selection independent of their working directory.
For configuration values, precedence is: For configuration values, precedence is:
1. built-in defaults; 1. built-in defaults;
2. composed YAML sources, including imports; 2. composed YAML sources, including imports;
3. the selected ConfigKit overlay; and 3. the selected ConfigKit overlay and inheritance;
4. explicitly supplied configuration-valued run flags. 4. typed decoding and explicitly supplied configuration-valued run flags; and
5. Notarius resolution and validation.
`--config-overlay` selects a ConfigKit overlay from `overlays/<name>.yml` `--config-overlay` selects a ConfigKit overlay from `overlays/<name>.yml`
beneath the selected configuration root. Empty and `default` select no overlay. beneath the selected configuration root. Empty and `default` select no overlay.
@@ -38,7 +51,8 @@ have no effect; `NOTARIUS_CONFIG` remains a source-discovery input.
ordered steps, all implemented D&D lanes, generated references, state ordered steps, all implemented D&D lanes, generated references, state
settings, bounded LLM concurrency, and the maintained settings, bounded LLM concurrency, and the maintained
[LLM profile](../examples/llm-profiles/dnd-extraction.yml) and imports its [LLM profile](../examples/llm-profiles/dnd-extraction.yml) and imports its
pipeline from [a fragment](../examples/pipelines/dnd-session.yml). pipeline from [a fragment](../examples/pipelines/dnd-session.yml), which imports
its [first step](../examples/pipelines/dnd-session.describe-session.yml).
The complete fragment also defines `dnd-session-development`, which inherits The complete fragment also defines `dnd-session-development`, which inherits
the complete pipeline and profile while setting the complete pipeline and profile while setting
@@ -102,24 +116,42 @@ Built-in relative destinations use the selected main configuration file's
directory; explicit `--output-dir` and `--debug-dir` values use the invocation directory; explicit `--output-dir` and `--debug-dir` values use the invocation
working directory. Absolute values remain unchanged. working directory. Absolute values remain unchanged.
The root file can use ConfigKit imports to compose disjoint definitions. Imports Use source-root `config` controls for imports and collection declarations. For
and selected overlays remain under the configuration root; they do not merge or example, an essential fragment should explicitly be required:
append a pipeline's `steps` sequence. An overlay replaces sequences as defined
by ConfigKit, so changing an individual ordered binding requires supplying the ~~~yaml
whole replacement sequence. config:
imports:
- path: pipelines/session.yml
required: true
~~~
Imports are optional by default. ConfigKit supports paths, lists, directories,
globs, exclusions, recursive selection, destinations, and sequence-item placement;
its native input-root rules apply. Imported fragments need not declare a version.
The complete example places a mapping fragment at a step-list destination. Nested
application data named `config` is ordinary data, not a control block.
When migrating application files, rename genuine root `configkit` control
blocks to `config` in the main file and fragments. This is not a compatibility
alias: `configkit` is ordinary data under the new reader. PromptKit profile
documents still use their separate older engine and retain `configkit` controls;
see [PromptKit Profiles](#promptkit-profiles).
## Sibling Inheritance ## Sibling Inheritance
ConfigKit v0.5.0 supports native `extends` composition in mappings. A directive ConfigKit supports native `extends` composition in mappings and identified
sequence records. A directive
names exactly one immediate sibling in the same mapping; it is not a path or a names exactly one immediate sibling in the same mapping; it is not a path or a
cross-scope lookup. Imports, the selected overlay, and explicit overrides are cross-scope lookup. Imports and the selected overlay are composed before
composed before inheritance, which runs before typed decoding and normal inheritance and typed decoding. Explicit CLI assignments follow decoding and
Notarius validation. Every definition, including a parent and definitions not inheritance, before Notarius resolution and validation; they cannot repair an
earlier structural or decoding error. Every definition, including a parent and definitions not
selected for a run, remains subject to ordinary validation. selected for a run, remains subject to ordinary validation.
Child mappings recursively overlay parent mappings. A child sequence, scalar, Child mappings recursively overlay parent mappings. Scalars and null replace
or null replaces the inherited value. This makes pipeline inheritance useful inherited values. Unidentified sequences replace as whole values; pipeline
for reusing a complete pipeline while replacing whole ordered lists: steps are identified by `id` and use native upsert by default:
~~~yaml ~~~yaml
pipelines: pipelines:
@@ -133,10 +165,31 @@ pipelines:
~~~ ~~~
Pipeline names are siblings within `pipelines`; nested mappings such as named Pipeline names are siblings within `pipelines`; nested mappings such as named
artifact lanes also have their own sibling namespace. Step entries are a artifact lanes also have their own sibling namespace. Distinct imported step IDs
sequence, so a step cannot extend another step. Replacing `steps` or a validator combine in source order; duplicate peer IDs conflict. Across an overlay or
chain supplies the complete replacement sequence; entries are not appended or inheritance, upsert replaces a matching step as a complete record in place and
merged by identifier. appends new IDs. It does not merge individual fields of a matching step. An
identified record can itself use native `extends`. Authors may select `replace`
or `append` with a `config.sequences` declaration at the relevant destination;
an explicit replacement with `[]` clears the list, while empty append or upsert
does not. Notarius then validates the resulting pipeline, including its nonempty
step requirement. Validator chains are not automatically identified. Authors
may declare identities for other lists when needed. CLI list assignment replaces
the complete decoded list.
For example, an overlay can opt into replacing a pipeline's steps:
~~~yaml
config:
sequences:
- destination: [pipelines, production, steps]
mode: replace
pipelines:
production:
steps:
- id: extract
artifacts: {spells: {extract: {module: dnd/spells}}}
~~~
Inherited values count as explicit input for Notarius's existing Inherited values count as explicit input for Notarius's existing
presence-sensitive rules: zero, false, and empty-list overrides stay explicit presence-sensitive rules: zero, false, and empty-list overrides stay explicit

View File

@@ -8,7 +8,7 @@ who need implementation mechanics should read [Run State Internals](internal/sta
## Source Deployment ## Source Deployment
Linux is the supported deployment platform. Install a pinned source release Linux is the supported deployment platform. Install a pinned source release
with the Go version declared in `go.mod` (currently Go 1.25.5): with the Go version declared in `go.mod` (currently Go 1.27.0):
~~~sh ~~~sh
GOWORK=off go install \ GOWORK=off go install \

View File

@@ -402,6 +402,11 @@ Prompt size: one supporting fragment and existing example coverage.
## Stage 9 — Update Operator And Consumer Documentation ## Stage 9 — Update Operator And Consumer Documentation
**Complete.** Operator references now describe native discovery, composition,
override timing, path bases, and the separate PromptKit format. Source-install,
release-validation, and advisory CI toolchain guidance select Go 1.27.0.
Maintained-example resolution and validation tests pass.
Goal: document implemented native behavior and migration in canonical homes. Goal: document implemented native behavior and migration in canonical homes.
Work: Work: