eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 27 Wiki Activity

Document shared downstream development overlay workflow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 03:18:14 +00:00
parent 23c4686b84
commit e349bf03ca
2 changed files with 58 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/operations.md
View File

@@ -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

10
docs/roadmap/audita-debug.md
View File

@@ -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).