diff --git a/.woodpecker/release.yml b/.woodpecker/release.yml index 2feee9f7..9aa3bf86 100644 --- a/.woodpecker/release.yml +++ b/.woodpecker/release.yml @@ -4,6 +4,6 @@ when: steps: - name: validate-release - image: golang:1.25.5 + image: golang:1.27.0 commands: - ./scripts/check-release-source.sh "$CI_COMMIT_TAG" diff --git a/README.md b/README.md index cca953e8..43a2bbff 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ demonstrates all implemented D&D lanes and the supporting campaign references. ## Install A Source Release 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. Install a pinned source release with Go: diff --git a/docs/cli.md b/docs/cli.md index 9dd70b7a..652757be 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,6 +6,13 @@ Configuration fields, discovery rules, and selectable module keys are defined in [Configuration](config.md); runtime state and recovery procedures are 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 ~~~ diff --git a/docs/config.md b/docs/config.md index df138a8a..fc86913e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,7 +1,7 @@ # Configuration 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 [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; 2. a non-empty **NOTARIUS_CONFIG** environment value; -3. the installed default file at **/usr/local/etc/notarius/config.yml**, when - it exists. +3. `notarius.yml`, then `notarius.yaml` in the working directory; +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 `/notarius/` for `notarius.yml`, +`notarius.yaml`, `config.yml`, `config.yaml`, `main.yml`, and `main.yaml`, in +that order, then `/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: 1. built-in defaults; 2. composed YAML sources, including imports; -3. the selected ConfigKit overlay; and -4. explicitly supplied configuration-valued run flags. +3. the selected ConfigKit overlay and inheritance; +4. typed decoding and explicitly supplied configuration-valued run flags; and +5. Notarius resolution and validation. `--config-overlay` selects a ConfigKit overlay from `overlays/.yml` 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 settings, bounded LLM concurrency, and the maintained [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 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 working directory. Absolute values remain unchanged. -The root file can use ConfigKit imports to compose disjoint definitions. Imports -and selected overlays remain under the configuration root; they do not merge or -append a pipeline's `steps` sequence. An overlay replaces sequences as defined -by ConfigKit, so changing an individual ordered binding requires supplying the -whole replacement sequence. +Use source-root `config` controls for imports and collection declarations. For +example, an essential fragment should explicitly be required: + +~~~yaml +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 -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 -cross-scope lookup. Imports, the selected overlay, and explicit overrides are -composed before inheritance, which runs before typed decoding and normal -Notarius validation. Every definition, including a parent and definitions not +cross-scope lookup. Imports and the selected overlay are composed before +inheritance and typed decoding. Explicit CLI assignments follow decoding and +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. -Child mappings recursively overlay parent mappings. A child sequence, scalar, -or null replaces the inherited value. This makes pipeline inheritance useful -for reusing a complete pipeline while replacing whole ordered lists: +Child mappings recursively overlay parent mappings. Scalars and null replace +inherited values. Unidentified sequences replace as whole values; pipeline +steps are identified by `id` and use native upsert by default: ~~~yaml pipelines: @@ -133,10 +165,31 @@ pipelines: ~~~ Pipeline names are siblings within `pipelines`; nested mappings such as named -artifact lanes also have their own sibling namespace. Step entries are a -sequence, so a step cannot extend another step. Replacing `steps` or a validator -chain supplies the complete replacement sequence; entries are not appended or -merged by identifier. +artifact lanes also have their own sibling namespace. Distinct imported step IDs +combine in source order; duplicate peer IDs conflict. Across an overlay or +inheritance, upsert replaces a matching step as a complete record in place and +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 presence-sensitive rules: zero, false, and empty-list overrides stay explicit diff --git a/docs/operations.md b/docs/operations.md index a9cb067d..347b1f4c 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -8,7 +8,7 @@ who need implementation mechanics should read [Run State Internals](internal/sta ## Source Deployment 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 GOWORK=off go install \ diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 57ae2dde..53efa759 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -402,6 +402,11 @@ Prompt size: one supporting fragment and existing example coverage. ## 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. Work: