From e349bf03ca49f6746c5fff4ea8fe38a04fe0977c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 03:18:14 +0000 Subject: [PATCH] Document shared downstream development overlay workflow --- docs/operations.md | 69 ++++++++++++++++++++++++++++++------ docs/roadmap/audita-debug.md | 10 ------ 2 files changed, 58 insertions(+), 21 deletions(-) delete mode 100644 docs/roadmap/audita-debug.md diff --git a/docs/operations.md b/docs/operations.md index 7e1e3a9..6d54f53 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -282,7 +282,60 @@ earlier checkpoints are reused and execution resumes with failed, stale, or missing work in dependency order. `--force` is unnecessary unless the operator intends to replace otherwise-current artifacts. -### Developing With A Notarius Configuration Overlay +### Developing With Audita And Notarius Overlays + +All three applications use ConfigKit, but each owns its root configuration and +its own `overlays/` directory beside that file. A Narratio testing overlay can +explicitly select downstream testing overlays without requiring their names to +match. For example, Narratio's `overlays/testing.yml` may contain: + +```yaml +audita: + overlay: testing +notarius: + config_overlay: downstream-economy +``` + +Place Audita's settings in `overlays/testing.yml` beside its configuration, and +Notarius's settings in `overlays/downstream-economy.yml` beside its configuration. +Use each tool's own schema for model/profile selection and other settings; +Narratio neither copies those settings nor implicitly forwards its overlay name. +Select the Narratio file with `--overlay testing` on the desired command. Each +downstream selector is used only when its stage actually executes: `polish` for +Audita and `extract` for Notarius. Production can omit both selectors. + +For Audita debug inspection, its testing overlay can include: + +```yaml +diagnostics: + debug: true + work_dir: /path/to/audita-debug +``` + +Audita retains detailed artifacts under that directory. Inspect them there; +Narratio does not collect or manage them. Ordinary Audita reports remain a +separate existing integration. Leave debug disabled in Audita's production +configuration unless deliberately needed. + +Notarius's debug controls are different: `debug.directory` selects a location +but does not enable capture. Capture requires its `--debug` flag, which Narratio +does not currently forward. Selecting a Notarius testing overlay therefore does +not by itself enable a debug bundle. See the upstream +[Audita configuration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md) +and [Notarius CLI](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/cli.md) +for their respective controls. + +Edits inside downstream configuration behind an unchanged selector are not +automatically detected by Narratio. To inspect a fresh Audita debug run, explicitly +rerun polish, for example: + +```sh +narratio run SESSION --overlay testing --force --from polish --through polish +``` + +This replaces polish output and invalidates dependent results; it is not a +diagnostics-only operation. Selecting testing does not create an isolated +workspace or retain a separate current result. Notarius v0.8+ defaults to two additional eligible transient provider attempts per generation. Review downstream retry settings and Narratio's extraction @@ -291,14 +344,6 @@ Notarius v0.8.1 refreshes its built-in profile checkpoint identity, so older checkpoints may not be reused. Source-keyed chunk plans and already published outputs are unaffected; no manual cache deletion is required. -A Narratio development overlay can explicitly select a Notarius overlay without -requiring the names to match. For example, `overlays/testing.yml` may contain: - -```yaml -notarius: - config_overlay: downstream-economy -``` - Selecting Narratio's `testing` overlay then supplies `downstream-economy` only when extraction executes. Switching that explicit selector makes a recorded extraction non-current and reruns it when `extract` is in the selected stage @@ -310,8 +355,10 @@ selector. Force extraction after such an edit when a replacement is intended. Use `regenerate-artifacts` when both extraction and analysis must be rebuilt; use `analyze` when the existing extraction bundle should be preserved. Field semantics belong in [Configuration](./config.md#notarius-configuration-overlay), -and the exact downstream invocation belongs in the -[Notarius integration contract](./integrations/notarius.md#invocation). +with Audita selectors covered under +[Audita selection and credentials](./config.md#audita-selection-and-credentials). +Exact downstream invocations belong in the [Audita](./integrations/audita.md) +and [Notarius](./integrations/notarius.md#invocation) integration contracts. ## Artifact Selection diff --git a/docs/roadmap/audita-debug.md b/docs/roadmap/audita-debug.md deleted file mode 100644 index 132c7a0..0000000 --- a/docs/roadmap/audita-debug.md +++ /dev/null @@ -1,10 +0,0 @@ -# Optional Audita Debug Reporting - -Status: Deferred; not a v3.0.0 release prerequisite. - -Potential future work: enable Audita debug reporting through Narratio's testing -overlay and collect Audita's debug-only execution artifacts. Scope and design -remain undecided; this is not an implementation commitment. - -Current reporting behavior is documented in the -[Audita integration contract](../integrations/audita.md).