# Migrating To Native Configuration And Commands This guide maps retired Notarius interfaces to the implemented native workflow. It is migration material: the old spellings below are not accepted aliases. [Configuration](../config.md), [CLI Reference](../cli.md), and [Operations](../operations.md) own the current contracts. Domain artifact schemas and lane filename mapping are unchanged. ## Update Caller Arguments | Former interface | Current equivalent / intent | | --- | --- | | `notarius --version` | `notarius version`. | | `pipelines list` | `pipeline list`. | | `config validate --pipeline ID` | `pipeline validate ID`; native `config validate` checks the application document. | | `config effective` | `config show`; scopes are `app` and `promptkit`. | | Positional `config explain POINTER` | `config explain --path POINTER`; use native list/history options for discovery. | | `config profile ID` | `promptkit show profile QUALIFIED_ID`; this reports stored fields, not a copied completed target. | | `--config-overlay NAME` | `--overlay NAME`. | | Run `--input PATH` | `--input-file PATH`. | | `--only a,b` | Repeat literal `--lane a --lane b`; commas are no longer separators. | | `--json` | `--format json`; YAML/text are also native report formats. | | `--session-id ID` | `--llm-session-id ID`. | | `--reasoning-effort VALUE` | `--llm-reasoning-effort VALUE`. | | `--clear-reasoning-effort` | Explicit `--llm-reasoning-effort=`; omission retains native inheritance. | | `--resume`, `--recompute-step`, separate `--chunk_cache`/`--chunk-cache` | Ordinary accepted-result reuse, with invocation-wide `--cache auto\|bypass\|refresh`. No explicit resume or selective checkpoint barrier. | `run` and `pipeline run` are two native routes to the same command. Put flags after the complete command path. Singleton occurrences are all parsed, with the last successfully parsed value retained. False/zero/empty supplied values are not omission. Canonical `--llm-*` execution overrides reach producers, correction, and validators; shorter ckprompt aliases apply only to their installed PromptKit commands. Help works offline on subcommands. ## Migrate Configuration And Resources Version 6 is the sole application version; bumping the header alone does not translate old fields. Use the maintained [minimal](../../examples/dnd-minimal/config.yml) or [complete](../../examples/dnd-complete/config.yml) configuration as a starting point. - Replace `promptkit.profile_file`, `profile_dir`, and `local_backend` wrappers with native settings beneath the main file's `promptkit`, or wrapperless `prompts.yml` / recursive `prompts/` companions beside that selected main file. Companion files form strict peers, not filename-priority layers. - Use identified `backends`, `profiles`, and `prompts` lists with literal `id` values and collections. The embedded profile is `notarius/dnd-extraction`; initial/correction prompt IDs are also qualified, for example `notarius/dnd.spells` and `notarius/dnd.spells.repair`. - The root bundled backend is `openrouter`. Retired external provider catalogs are not loaded as parallel sources; declare needed backends/profiles through native resources. Do not infer backend identity from an endpoint or model. - Use native root `config` imports and preserve declaration-relative paths. Remove old per-prompt resource-version wrappers such as `v1`; resource IDs no longer select those versions. - A later same-ID resource replaces the whole earlier record. Use a distinct sibling with `extends: {id: parent}` to retain fields, not a partial same-ID replacement or self-inheritance. Profile/backend references to collection resources use qualified IDs; sibling inheritance is local to its list. - Preserve deliberate null/empty/zero choices under native semantics. Null endpoint/key-environment values can allow backend fallback; empty strings can clear those sources. Inspect native effective values/history rather than assuming old wrapper null behavior. - Keep prompt-declared schemas. Inline schemas, source-relative `schema_file`, and explicit-root `schema_path` are native alternatives. Replacing a collection schema root does not retain missing-file fallback to embedded resources. Review [native resource and schema rules](../config.md#promptkit-profiles) before reusing an old profile file. The complete example's [companion](../../examples/dnd-complete/prompts.yml) demonstrates current inheritance. ## Separate Retry Intent, Mode, And Capacity Producer `retries` intended for semantic correction becomes `max_additional_turns`, excluding the initial response. Binding overrides pipeline; omission inherits and explicit zero disables semantic correction. Native growing continuation replaces latest-only manual replay, and each revised candidate gets the full applicable assessment chain, including its final permitted turn. Remove validator `retries`, generic deterministic retries, `structured_output_repair_attempts`, and the application `promptkit.transient_retries` wrapper. PromptKit owns transient failures and structural repair. Run-wide transient customization uses `--llm-transient-retries`; structural customization belongs in native prompt output contracts. Bundled prompts leave repair counts unspecified. Former total provider-attempt parity is not promised. Replace failure-category `validation_policy` and its `fail_run`, `reject_output`, and `warn_continue` choices with producer `mode: strict|permissive`. Strict is the default, including normalization. Permissive explicitly requests a supported module fallback, not incomplete ordinary acceptance. Cancellation does not fall back; unsupported fallback construction fails. Completion discloses actual fallback emitters independently of warning visibility. Replace `concurrency.total_llm` and `concurrency.stage_workers.extract` with `concurrency.workers`, covering ready extraction and lane completion together. Choose native backend capacity independently. There is no cross-backend global LLM ceiling, inferred per-backend translation, or extra capacity queue/retry. The [configuration reference](../config.md#concurrency-output-cache-and-debug) owns current defaults and controls. ## Replace Both Legacy Caches Replace nested `cache.chunk_plans` / `cache.checkpoints` directories and recording switches with root `cache_directory` and pipeline/binding `cache`. An explicit invocation `--cache` overrides every binding. Auto reads/stores acceptance; bypass does neither; refresh skips reads and replaces only after new acceptance. The initial prepared native message-content hash selects final accepted artifacts and LLM plans. A hit is decoded/usability-checked, not semantically revalidated. Model/settings/policy changes can still hit; use refresh/bypass for experiments requiring fresh work. Source identity alone no longer fixes chunk boundaries. Fallback and actually affected consumers skip reuse; unaffected predecessors remain reusable after downstream failure. Failed refresh preserves old acceptance. Do not copy, convert, or delete legacy records as an upgrade prerequisite. They remain ignored and untouched, and the new cache populates through ordinary work. [Operations](../operations.md#accepted-result-cache-and-recovery) owns recovery and deployment-permission guidance. ## Replace Receipt And Sidecar Traversal Stop expecting `notarius.run-result.v2`, `index_file`, validation histories, warning counts, `index.json`, `manifest.json`, or reporting-only rejection/ warning/diagnostic files. Check process status, optionally decode the [native completion report](../cli.md#completion-report), then read configured lane/auxiliary [domain paths](../integrations/json-output.md). Use the report's absolute run directory, not a guessed run ID or newest-folder scan. Count actual deliverables rather than old normalized-output totals. The report does not establish fresh validation or model quality; decide whether positive fallback qualification is acceptable. Failed stdout can be partial, and post-publication failure can leave valid artifacts with a nonzero status. Debug remains explicitly selected and independent of native visibility modes. Directory-only configuration does not enable it; explicit empty disables it. The relative `latest` link updates at start, not completion. Full selected evidence replaces the old summary/trace hierarchy; filenames/JSON shapes remain private and arbitrary application content is not heuristically sanitized. Do not replace receipt traversal with a debug-layout dependency or a new manifest. Update callers using the [subprocess guide](subprocess.md) or [complete D&D workflow](dnd-pipeline.md). These changes do not publish a new release or rewrite historical release notes.