Prepare roadmap for documentation policy update

docs/policy/testing.md

@@ -0,0 +1,296 @@
+# Testing Policy
+
+## Purpose
+
+Our tests exist to make **incorrect changes expensive and correct changes cheap**.
+
+We do not optimize for test count, line coverage, exhaustive isolation, or the fewest possible tests. We optimize for sufficient confidence in important behavior while imposing as little unnecessary friction as possible on future development.
+
+## Every test has a cost
+
+Testing is not an unqualified good. Every test imposes both an immediate cost and a continuing lifetime cost.
+
+A test must be:
+
+- written and reviewed;
+- understood by future maintainers and coding agents;
+- executed in local and CI workflows;
+- diagnosed when it fails;
+- updated when legitimate behavior changes;
+- maintained as fixtures, APIs, and dependencies evolve; and
+- removed or rewritten when it becomes redundant, brittle, misleading, or obsolete.
+
+Tests also create cognitive and architectural friction. They can constrain refactoring, duplicate policy, slow feedback loops, add noise to failures, and cause harmless implementation changes to require unrelated edits across the suite.
+
+A test is warranted only when the confidence it provides justifies these costs.
+
+Apply this cost-benefit analysis at two levels:
+
+1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
+2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
+
+The preferred test suite is a **lean suite that provides sufficient confidence in the risks that matter, without redundant or low-value tests**. We seek sufficient confidence with the least unnecessary testing friction, not the fewest possible tests.
+
+Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. They should not make ordinary internal changes needlessly expensive.
+
+The cost of a test is not a reason to omit testing by default. Do not cite maintenance cost abstractly. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
+
+## Default testing style
+
+Use a **classical/Detroit-style** approach:
+
+- Test observable behavior, resulting state, contracts, and invariants.
+- Use real internal collaborators when they are fast and deterministic.
+- Use fakes, stubs, or mocks primarily at expensive, nondeterministic, destructive, or external boundaries.
+- Prefer package-level behavioral tests over tests coupled to private helpers or internal call sequences.
+- Treat exact collaborator interactions as testable behavior only when the interaction itself is a requirement.
+
+Examples of appropriate seams include clocks, randomness, subprocesses, remote APIs, object storage, email, and paid LLM calls.
+
+## Test execution requirements
+
+Tests in the default suite must be deterministic, offline, and independent of real credentials. They must not invoke paid APIs or depend on mutable external services. Tests that require live infrastructure must be explicitly opt-in and clearly separated from the default suite.
+
+Control clocks, randomness, environment variables, and other process-global or machine-specific state when they affect behavior. Tests should be safe to run repeatedly and alongside other tests without depending on execution order or state left by an earlier test.
+
+## What deserves tests
+
+Prioritize tests for:
+
+1. Public and package-level contracts.
+2. Domain rules and important invariants.
+3. Boundary conditions and malformed input.
+4. Failure handling, cancellation, retries, recovery, and partial success.
+5. Serialization, schemas, compatibility, and round trips.
+6. Previously observed or plausible regressions.
+7. Representative integration and end-to-end workflows.
+
+A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation.
+
+For behavior involving **data integrity, destructive operations, compatibility, security, concurrency, idempotency, or recovery**, presume that durable tests are required unless the behavior is already credibly protected at another layer.
+
+Do not add tests merely because a function, branch, or line exists. Do not add a test when the same meaningful risk is already adequately protected elsewhere.
+
+## Choose the right test boundary
+
+Test through the narrowest stable boundary that expresses the behavior clearly.
+
+This is often the package API, but it may instead be:
+
+- a smaller pure function when dense domain logic is most clearly isolated there;
+- a package-level operation when several internal collaborators jointly produce the behavior; or
+- a larger integration boundary when correctness emerges from interaction with a real dependency.
+
+Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling.
+
+## Test behavior, not implementation
+
+A test should protect a decision, contract, or invariant—not memorialize the current implementation.
+
+Before adding or retaining a test, ask:
+
+> What realistic defect would this test catch?
+
+A test is suspect when its main purpose is to detect that someone:
+
+- changed an internal constant;
+- renamed or split a private helper;
+- reordered equivalent internal operations;
+- changed incidental formatting;
+- replaced one correct algorithm with another; or
+- refactored internal object structure without changing behavior.
+
+Refactoring should normally require no test edits unless the refactored structure is itself part of the contract.
+
+A test can be factually correct and still have negative value. Accurately describing current behavior is not enough; the protected behavior must be important enough to justify the future friction.
+
+## Expected effects of different changes
+
+Use the following expectations when evaluating test failures and test maintenance:
+
+| Change | Expected effect on tests |
+|---|---|
+| Internal refactor that preserves behavior | Existing tests should normally remain unchanged and continue to pass. |
+| Change to an internal default with no contractual significance | Behavioral tests should normally remain unchanged; tests should derive expectations from configuration or relationships rather than duplicate the old value. |
+| Intentional change to public behavior, policy, schema, or compatibility guarantees | The relevant tests should be reviewed and changed deliberately. |
+| Accidental violation of a contract or invariant | Tests should fail; fix the production code rather than rewriting the tests to accept the defect. |
+
+A test failing is not the same as a test needing to be edited. Many tests may correctly fail because of one production defect. The maintenance smell is a correct internal change that requires unrelated expectation updates throughout the suite.
+
+## Separate mechanism from policy
+
+Configurable thresholds and defaults must not be duplicated throughout the test suite.
+
+For example, do not encode an internal concurrency limit indirectly:
+
+```go
+// Production policy:
+const maxConcurrency = 4
+
+// Brittle test:
+err := startProcesses(5)
+require.Error(t, err)
+```
+
+Instead, test the mechanism relationally:
+
+```go
+const limit = 2
+runner := NewRunner(limit)
+
+require.NoError(t, runner.Start(limit))
+require.ErrorIs(t, runner.Start(limit+1), ErrTooMuchConcurrency)
+```
+
+The test should prove:
+
+- the configured limit is accepted; and
+- one beyond the configured limit is rejected.
+
+The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
+
+Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior, not duplicated literals.
+
+For concurrency limits, test both kinds of behavior when relevant:
+
+1. **Configuration enforcement:** invalid or excessive requested values are handled correctly.
+2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
+
+Use a test-controlled limit and measure the behavior relative to that limit. Do not merely assert today's default value.
+
+## Avoid semantic duplication across layers
+
+Each behavior should have a clear test owner.
+
+- Parser tests own parsing cases.
+- Validator tests own validation rules.
+- Domain tests own transformations and invariants.
+- Adapter tests own external integration behavior.
+- Orchestrator tests own coordination and failure propagation.
+- CLI tests own argument and configuration mapping.
+- End-to-end tests prove that representative assembled workflows work.
+
+Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files.
+
+Tests that are individually reasonable may still be collectively redundant. Evaluate the marginal value of each additional test in light of the protection already provided by the rest of the suite.
+
+## Use test doubles deliberately
+
+Choose the least elaborate test double that provides the required control or observation.
+
+As a default:
+
+1. Prefer real collaborators when they are fast and deterministic.
+2. Use small in-memory fakes when realistic stateful behavior is helpful.
+3. Use stubs when a dependency only needs to provide controlled responses.
+4. Use mocks when the interaction itself is contractual.
+
+Mocks are appropriate when the contract includes facts such as:
+
+- a notification is sent exactly once;
+- a transaction is committed only after successful writes;
+- cancellation reaches a subprocess;
+- an expensive API is called no more than once; or
+- a security audit event is emitted.
+
+Do not use mocks merely to isolate every object or reproduce the implementation's call graph.
+
+## Go-specific guidance
+
+Use:
+
+- table-driven tests for meaningful behavioral categories and boundaries;
+- `t.TempDir()` for real filesystem behavior;
+- `httptest.Server` for realistic HTTP interactions;
+- fuzz tests for parsers, normalization, path handling, and broad input spaces;
+- golden files only when the complete output is intentionally stable;
+- integration tests where correctness depends on component interaction; and
+- a small number of representative end-to-end tests.
+
+Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields.
+
+At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual.
+
+Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
+
+Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs.
+
+## Coverage
+
+Coverage is a diagnostic, not a target.
+
+Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone.
+
+Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
+
+Increasing coverage is valuable only when the newly covered behavior protects a meaningful risk at an acceptable cost.
+
+## Regression tests
+
+A bug fix should normally include a regression test that fails before the fix and passes afterward.
+
+Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant; do not preserve accidental implementation details from the original bug.
+
+Not every historical bug requires a permanent test. If the underlying design has made recurrence impossible, the test has become redundant, or a stronger invariant test now subsumes it, remove or consolidate it.
+
+## Deleting or rewriting tests
+
+Tests are maintained code, not permanent historical artifacts.
+
+Delete or rewrite a test when its maintenance cost exceeds the confidence it provides.
+
+Strong candidates include tests that:
+
+- require updates after harmless internal changes;
+- directly assert private constants without protecting a real contract;
+- duplicate the same policy across several layers;
+- verify mock choreography rather than outcomes;
+- snapshot large amounts of incidental output;
+- test trivial private helpers already exercised through stable package behavior;
+- protect risks already covered more effectively elsewhere;
+- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
+- no longer correspond to a plausible failure mode.
+
+Several brittle tests may encode one genuine requirement. Replace them with one durable behavior-level or invariant test rather than preserving all of them.
+
+Deleting a low-value test can improve the quality of the suite by reducing noise, maintenance burden, and friction around legitimate change.
+
+## Reviewing a proposed test
+
+Use the following questions when the value, boundary, or durability of a proposed test is not self-evident. Significant test additions should be reviewable against them, but written answers are not required for every routine test.
+
+1. What realistic defect would it catch?
+2. How likely is that defect?
+3. How consequential would it be?
+4. Is the behavior already protected elsewhere?
+5. At which layer should this behavior be owned?
+6. Does the test assert a durable contract or an incidental implementation detail?
+7. Could the implementation be refactored without changing the behavior and without editing this test?
+8. What should cause this test to fail?
+9. What legitimate changes should not cause this test to fail?
+10. What ongoing maintenance, execution, and diagnostic cost will the test impose?
+11. Is there a smaller or more direct test that protects the same risk?
+
+Do not add the test when its expected lifetime cost exceeds its expected protective value.
+
+When deciding not to test plausible behavior, record or be able to explain why the risk is low, already protected, obvious, reversible, or cheaper to detect elsewhere.
+
+## Definition of sufficient
+
+A test suite is sufficient when:
+
+- important contracts and invariants are protected;
+- meaningful boundaries and failure modes are exercised;
+- realistic and consequential regressions are credibly protected against silent recurrence;
+- behavior involving data integrity, destructive operations, compatibility, security, concurrency, idempotency, and recovery is credibly protected;
+- important external boundaries have realistic integration coverage;
+- representative complete workflows are tested;
+- failures provide useful signal rather than redundant noise;
+- legitimate internal changes usually do not require test edits; and
+- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
+
+Sufficiency is a risk judgment, not a coverage percentage or test count. Reassess it as the application, its users, and the consequences of failure evolve.
+
+The governing rule is:
+
+> Test heavily where failure is consequential, subtle, or difficult to detect after the fact. Test lightly where failure is obvious, reversible, and inexpensive—and retain no test whose lifetime cost exceeds the confidence it provides.

docs/roadmap/documentation.md

@@ -0,0 +1,355 @@
+# Documentation Policy And Structure Alignment
+
+## Status
+
+Proposed.
+
+## Purpose
+
+Align Narratio's documentation policy, organization, and maintenance practices
+with the current Notarius approach while preserving Narratio-specific product,
+operational, and integration needs.
+
+The resulting documentation set should assign each authoritative topic to one
+canonical owner, distinguish current behavior from future work, make audience
+boundaries explicit, and minimize duplicated contracts that can drift as the
+application changes.
+
+This roadmap defines the scope and intended final state. Execution guidance is
+maintained separately in the [Implementation Plan](implementation.md).
+
+## Motivation
+
+Narratio already has substantial user, operator, integration, and internal
+documentation, but its documentation policy predates the current Notarius
+policy. The existing policy prescribes document profiles and detailed outlines
+without defining ownership boundaries precisely enough. Several policy files
+also refer to obsolete or nonexistent paths, and some concrete inventories and
+contract details are repeated across documents.
+
+The alignment should retain useful Narratio documentation while adopting the
+stronger Notarius principles:
+
+- one canonical owner for each authoritative fact;
+- current behavior outside the roadmap and future behavior inside it;
+- audience-appropriate detail;
+- maintained, valid, secret-free examples;
+- explicit boundaries among user, operator, integration, architecture, and
+  internal documentation;
+- a defined lifecycle for architectural decision records; and
+- verification of documentation against implemented behavior.
+
+## Target Documentation Model
+
+### Canonical Ownership
+
+The final documentation policy should assign the following responsibilities.
+
+| Topic | Canonical owner | Intended responsibility |
+| --- | --- | --- |
+| Product orientation and minimal end-to-end quickstart | `README.md` | Explain what Narratio is, why it is useful, show the shortest successful invocation, and route readers onward. |
+| Contributor entry point | `docs/development.md` | Provide a task-oriented reading guide, baseline validation commands, and links to canonical policies and contracts. |
+| Current application architecture | `docs/policy/architecture.md` | Define system shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. |
+| Documentation organization | `docs/policy/documentation.md` | Define canonical ownership, audience boundaries, maintenance rules, and the ADR and document lifecycle. |
+| Testing policy | `docs/policy/testing.md` | Define test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, and test lifecycle decisions. |
+| CLI contract | `docs/cli.md` | Define commands, arguments, flags, invocation semantics, output conventions, and exit behavior. |
+| Configuration contract | `docs/config.md` | Define discovery, precedence, schemas, fields, defaults, environment overrides, and validation rules. |
+| Operations | `docs/operations.md` | Define runtime workflows, physical state layout, resume, cleanup, permissions, recovery, and operational limits. |
+| Troubleshooting | `docs/troubleshooting.md` | Provide symptom-driven diagnosis and safe remedies, linking to the owning CLI, configuration, operations, or integration contract. |
+| External and durable integration contracts | `docs/integrations/` | Define the external formats, protocols, logical artifact shapes, and compatibility behavior Narratio relies on. |
+| Implemented component inventory | `docs/internal/overview.md` | Inventory current packages and components, summarize their implemented responsibilities, and route readers to focused internal documents. |
+| Internal component behavior | Other files under `docs/internal/` | Explain implementation flow, internal collaborators, state transitions, package-local guarantees and failures, and relevant tests. |
+| Architectural decision history | `docs/adr/` | Record significant decisions, alternatives, rationale, consequences, and supersession history when ADRs are warranted. |
+| Future work and implementation status | `docs/roadmap/` | Describe proposed, accepted, deferred, rejected, or completed work and its implementation status. |
+| Complete copyable artifacts | `examples/` | Hold maintained configuration, inputs, and other files intended to be copied or run. |
+
+Documents for interfaces that Narratio does not expose should not be created as
+placeholders. In particular, public API or consumer documentation should be
+added only if a corresponding public interface exists.
+
+### Structural Parity With Notarius
+
+Narratio should follow the current Notarius policy layout where the same
+responsibility exists. In the aligned structure:
+
+- `docs/internal/overview.md` is the internal component inventory;
+- `docs/development.md` is the first-read contributor landing page;
+- all navigation and relative links use those canonical paths;
+- `docs/adr/` and sequentially numbered ADR filenames are used when architectural
+  decisions need durable records; and
+- Narratio-specific canonical documents remain, including the troubleshooting
+  guide, stage documentation, and integration contracts.
+
+Structural parity does not require placeholder documents, removal of useful
+Narratio-specific material, or identical prose where the applications have
+different contracts.
+
+## Policy Alignment
+
+### Documentation Policy
+
+The documentation policy should follow the current Notarius policy, adapted to
+Narratio. It should:
+
+- define one canonical owner for every contract or authoritative fact;
+- identify volatile details that must not be maintained in multiple places;
+- permit non-owning documents to provide only short, stable summaries with
+  links;
+- describe implemented behavior only outside `docs/roadmap/`;
+- allow accepted ADRs to precede implementation without presenting the
+  decision as implemented behavior;
+- distinguish user, operator, contributor, integration, and internal detail;
+- require complete copyable files to live under `examples/`;
+- define documentation security and privacy requirements;
+- specify ownership boundaries for orientation, CLI, configuration,
+  operations, troubleshooting, integrations, architecture, and internals;
+- define the ADR format and supersession rules; and
+- require contract, example, link, and sensitive-data checks when behavior or
+  documentation changes.
+
+### Architecture Policy
+
+The architecture policy should remain the normative owner of Narratio's system
+boundaries and invariants rather than a concrete package inventory or secondary
+testing and documentation policy. It should:
+
+- preserve Narratio's explicit, stage-driven orchestration model;
+- preserve adapter, manifest, artifact, path-safety, publish-commit, security,
+  privacy, and determinism invariants;
+- link to the testing and documentation policies for their general rules;
+- link to internal documentation for implemented component mechanics;
+- link to external contracts rather than redefining them; and
+- use the canonical `docs/policy/` paths consistently.
+
+### Testing Policy
+
+The copied Notarius testing policy is Narratio's canonical testing policy. Its
+place in the documentation set requires:
+
+- linking it from architecture and contributor guidance;
+- removing or reducing duplicated general test philosophy elsewhere;
+- retaining subsystem-specific test guidance only where it helps maintain a
+  concrete contract; and
+- ensuring project commands and examples remain accurate for Narratio.
+
+The alignment should not require Narratio and Notarius to have identical test
+suites. The shared policy governs how Narratio evaluates test value,
+boundaries, doubles, regression protection, coverage, and sufficiency.
+
+### Contributor Policy
+
+The development document should be a concise contributor entry point. It should
+route maintainers and coding agents to canonical documentation based on the
+task at hand and provide the minimum repository orientation and validation
+commands needed to begin work.
+
+Detailed package inventories belong in `docs/internal/overview.md`;
+architecture rules belong in the architecture policy; application contracts
+belong in their user, operator, or integration documents; and general testing
+rules belong in the testing policy. Any retained change recipes should avoid
+redefining those owners.
+
+## Documentation Set Alignment
+
+### README And Navigation
+
+Keep the README short and outward-facing. It should own product orientation and
+one minimal successful workflow, then link to the CLI, configuration,
+operations, troubleshooting, contributor, architecture, testing, integration,
+and internal entry points as appropriate.
+
+Navigation should use the final canonical paths and should not rely on obsolete
+aliases or duplicate index files.
+
+### CLI, Configuration, And Operations
+
+Separate these contracts consistently:
+
+- CLI documentation answers how Narratio is invoked and what its command-line
+  interface means;
+- configuration documentation answers how configuration is discovered,
+  interpreted, defaulted, overridden, and validated; and
+- operations documentation answers what happens to runtime state and how an
+  operator runs, resumes, cleans, diagnoses, or recovers the application.
+
+Cross-cutting workflows should have one task-oriented owner and link to the
+other contracts rather than copying their flags, fields, defaults, or path
+definitions.
+
+### Troubleshooting
+
+Keep troubleshooting as a Narratio-specific canonical document. Each entry
+should begin from an observable symptom and provide a likely cause, a safe
+diagnostic step, a safe remedy, and links to the canonical contract or
+operational procedure.
+
+Troubleshooting should not become a second CLI, configuration, or operations
+reference.
+
+### Integrations
+
+Integration documents should own the externally observable contracts Narratio
+uses: subprocess behavior, file formats, protocols, logical artifact paths and
+schemas, compatibility expectations, and upstream or downstream
+responsibilities.
+
+They should describe only the portions of WhisperX, Seriatim, Audita,
+Scriptorium, object storage, or future integrations that Narratio actually
+depends on. Internal adapter mechanics belong under `docs/internal/`, while
+configuration defaults, CLI syntax, and physical runtime placement remain with
+their respective owners.
+
+### Internal Documentation
+
+`docs/internal/overview.md` is the canonical implemented component inventory. It
+should summarize current components and route readers to focused documents
+without restating normative architecture.
+
+Focused internal documents should describe implemented behavior at useful
+component boundaries, including collaborators, data and state transitions,
+failures, and tests worth consulting. They may identify an external field,
+file, or protocol when explaining a dependency, but should link to the
+canonical contract for its definition.
+
+The internal set should be reviewed for duplicate definitions of:
+
+- stage order and stage contracts;
+- manifest states and transitions;
+- artifact identities, paths, and schemas;
+- workspace and object-storage layout;
+- restore, resume, cleanup, and publish behavior;
+- adapter invocation and compatibility rules; and
+- configuration fields and defaults.
+
+### Examples
+
+Complete copyable configuration and input files should remain under
+`examples/`. Documentation may include small illustrative fragments, but it
+should link to maintained examples instead of embedding alternate complete
+files.
+
+Examples should remain secret-free, loadable, valid, and covered by automated
+tests where practical. Their commands, filenames, fields, defaults, and
+templates must agree with implemented Narratio behavior.
+
+### Roadmaps And ADRs
+
+Roadmaps should own future work, implementation status, and sequencing. They
+must not be treated as current behavior references. When roadmap work lands,
+the relevant current-behavior documents should be updated in the same change,
+and the roadmap status should accurately reflect completion.
+
+Use ADRs for significant architectural decisions whose context, alternatives,
+and consequences should remain durable. Use the lightweight Nygard structure:
+title, status, date, context, decision, alternatives considered, and
+consequences. Accepted decision content is immutable; a later change should
+supersede it with a new ADR. Rejected architectural alternatives belong in the
+ADR, while rejected product ideas remain roadmap material.
+
+No empty `docs/adr/` directory or retrospective ADR catalog is required merely
+to satisfy structural parity.
+
+## Canonical-Ownership Audit
+
+The existing documentation should be audited for repeated authoritative facts,
+with priority given to details most likely to drift:
+
+- commands, arguments, flags, output conventions, and exit behavior;
+- configuration discovery, fields, defaults, environment variables, and
+  validation rules;
+- stage order, prerequisites, invalidation, skip, force, resume, and failure
+  semantics;
+- manifest states, artifact identities, and publish commit behavior;
+- local workspace, cache, spool, log, report, and remote object paths;
+- integration arguments, formats, schemas, timeouts, and compatibility rules;
+  and
+- security, credential, permission, and sensitive-artifact handling.
+
+For each repeated fact, choose the canonical owner defined by policy. Remove
+the duplicate definition or reduce it to the smallest stable summary needed
+for orientation, with a link to the owner.
+
+This audit should preserve useful task-oriented guidance. Canonical ownership
+means eliminating parallel contract definitions, not forcing readers to
+assemble every workflow from isolated reference fragments.
+
+## Intended Final State
+
+When this roadmap is complete:
+
+- Narratio's documentation policy closely matches the current Notarius policy
+  in principles, organization, terminology, and lifecycle rules;
+- every authoritative documentation topic has one stated canonical owner;
+- `docs/internal/overview.md` is the internal component index and no references
+  to `docs/internal/README.md` remain;
+- all policy and navigation links use real canonical paths;
+- architecture, documentation, testing, and contributor policies have distinct
+  responsibilities and link to one another;
+- current-behavior documentation contains no unimplemented claims;
+- roadmap documents clearly own future behavior and implementation status;
+- user and operator documents avoid unnecessary implementation detail;
+- internal documents do not redefine external or user-facing contracts;
+- volatile commands, fields, defaults, schemas, paths, and guarantees are not
+  maintained authoritatively in multiple places;
+- complete examples live under `examples/` and remain valid and secret-free;
+- the documentation remains concise enough to navigate but complete enough for
+  users, operators, developers, integrators, and coding agents; and
+- future behavior changes can identify the documentation that must change by
+  consulting the ownership table.
+
+## Validation
+
+Completion should include:
+
+- a repository-wide review of Markdown links and canonical paths;
+- verification of documented commands and flags against the CLI
+  implementation;
+- verification of configuration fields, defaults, environment overrides, and
+  validation rules against the configuration implementation;
+- verification of stage, manifest, artifact, restore, resume, cleanup, and
+  publish claims against implemented behavior;
+- validation of maintained examples through existing runtime config paths and
+  tests;
+- `go test ./...`;
+- confirmation that non-owning documents summarize and link rather than
+  redefine volatile contracts;
+- confirmation that unimplemented behavior appears only under
+  `docs/roadmap/`, subject to the accepted-ADR exception; and
+- a review for credentials, private campaign content, sensitive environment
+  data, and private infrastructure details.
+
+If the repository has no automated Markdown link checker, validation should use
+a focused, reproducible scripted link check supplemented by manual review of
+directory links and anchors.
+
+## Acceptance Criteria
+
+- `docs/policy/documentation.md` expresses the Narratio-adapted canonical
+  ownership model and boundary rules from the current Notarius policy.
+- `docs/policy/architecture.md`, `docs/policy/testing.md`, and
+  `docs/development.md` have clear, non-overlapping responsibilities.
+- `docs/policy/development.md` has moved to `docs/development.md`, with all
+  inbound links updated.
+- `docs/internal/README.md` has been renamed to
+  `docs/internal/overview.md`, with all inbound links updated.
+- README, CLI, configuration, operations, troubleshooting, integration,
+  internal, roadmap, example, and ADR responsibilities match the ownership
+  model.
+- No known obsolete documentation paths remain.
+- High-volatility contracts have one authoritative definition.
+- Current and future behavior are clearly separated.
+- Maintained examples and documented commands agree with the implementation.
+- Documentation validation and the full Go test suite pass, or any unrelated
+  pre-existing failure is recorded precisely.
+
+## Non-Goals
+
+- Changing Narratio runtime behavior solely to make existing documentation
+  true.
+- Implementing features described by other roadmap documents.
+- Rewriting every document for stylistic uniformity when its ownership and
+  content are already correct.
+- Copying Notarius product, CLI, configuration, integration, or internal
+  contracts into Narratio.
+- Creating placeholder API, consumer, ADR, or integration documents for
+  interfaces that do not exist.

docs/roadmap/implementation.md

@@ -0,0 +1,544 @@
+# Documentation Policy And Structure Implementation Plan
+
+## Status
+
+Proposed.
+
+## Objective
+
+Implement the target documentation model defined in
+[Documentation Policy And Structure Alignment](documentation.md). This is a
+documentation-only effort: do not change Go code, runtime behavior,
+configuration schemas, generated assets, or application features while
+following this plan.
+
+Complete the stages below in order. Treat each stage as an independently
+reviewable change boundary and run its stated checks before proceeding. Preserve
+the technical intent of the feature roadmap and the existing current-behavior
+documentation unless repository evidence shows that it is stale.
+
+## Governing Decisions
+
+- Use `../notarius/docs/policy/documentation.md` as the structural and policy
+  baseline for Narratio's documentation policy, adapting project names,
+  canonical paths, and Narratio-specific document types.
+- Keep architecture, documentation, and testing under `docs/policy/`.
+- Move contributor orientation from `docs/policy/development.md` to
+  `docs/development.md`.
+- Rename `docs/internal/README.md` to `docs/internal/overview.md`.
+- Replace the root `AGENTS.md` with the exact two-line content specified in
+  Stage 4.
+- Keep `docs/troubleshooting.md` as a Narratio-specific canonical owner even
+  though the current Notarius ownership table has no corresponding row.
+- Add `docs/integrations/whisperx.md`; WhisperX is an implemented external HTTP
+  boundary and is the only current first-class integration missing a focused
+  integration contract.
+- Keep directory index filenames not otherwise selected by this plan unchanged.
+  In particular, do not rename `docs/integrations/README.md`.
+- Do not create `docs/adr/` until Narratio has an ADR to record. Do not create
+  placeholder API or consumer documentation.
+- Do not copy Notarius product or runtime contracts. Use Notarius only as the
+  policy and information-architecture model.
+- Outside `docs/roadmap/`, describe implemented behavior only. Roadmaps may
+  describe proposed behavior but must not be cited as current contracts.
+- When documentation and implementation disagree, inspect the implementation
+  and tests and make current-behavior documentation accurate. Do not alter code
+  in this effort. Record a genuine runtime defect or unresolved ambiguity for
+  separate work rather than silently documenting desired behavior as current.
+- Do not add a documentation tool dependency solely for this migration. Use
+  repository scripts only if they already exist; otherwise use the validation
+  procedure in Stage 8.
+
+## Stage 1: Replace The Documentation Policy
+
+### Goal
+
+Make `docs/policy/documentation.md` the authoritative Narratio documentation
+ownership and lifecycle policy before changing the rest of the documentation.
+
+### Work
+
+1. Read the complete current files:
+   - `../notarius/docs/policy/documentation.md`;
+   - `docs/roadmap/documentation.md`;
+   - `docs/policy/documentation.md`; and
+   - the current Narratio documentation tree.
+2. Replace `docs/policy/documentation.md` with a Narratio-adapted version of the
+   current Notarius policy. Preserve the Notarius section model:
+   - Purpose;
+   - Core Rules;
+   - Canonical Ownership;
+   - Boundary Rules;
+   - Architecture Decision Records; and
+   - Maintenance.
+3. Make these Narratio-specific adaptations:
+   - use Narratio rather than Notarius throughout;
+   - set the contributor owner to `docs/development.md`;
+   - set architecture, documentation, and testing owners to their files under
+     `docs/policy/`;
+   - set the implemented component inventory to
+     `docs/internal/overview.md`;
+   - retain the Notarius conditional rows for public HTTP and consumer
+     documentation;
+   - add a troubleshooting row assigning symptom-driven diagnosis and safe
+     remedies to `docs/troubleshooting.md` while keeping commands,
+     configuration, and operational procedures with their existing owners;
+   - retain `docs/integrations/` as the owner of external and durable contracts;
+     and
+   - retain the rule that nonexistent interface-specific documents are not
+     required until the interface exists.
+4. In the boundary rules, explicitly separate:
+   - README orientation, contributor routing, normative architecture, and the
+     implemented internal inventory;
+   - CLI invocation, configuration meaning, operations, and troubleshooting;
+   - integration contracts and internal implementation; and
+   - documentation security rules, application security invariants,
+     credential-supply mechanisms, operational handling, and internal
+     mechanisms.
+5. Preserve the lightweight Nygard ADR format and supersession rules from the
+   Notarius policy. Do not create an ADR directory in this stage.
+6. Remove the old documentation profiles, prescribed per-document outlines,
+   and obsolete paths rather than appending the new policy beneath them.
+
+### Checks
+
+- Search the finished policy for `Notarius`, `docs/architecture.md`,
+  `docs/policy/development.md`, and `docs/internal/README.md`; none should
+  remain.
+- Confirm every canonical owner in the feature roadmap appears consistently in
+  the policy.
+- Run `git diff --check -- docs/policy/documentation.md`.
+
+### Completion Criteria
+
+- The policy closely follows the current Notarius policy while expressing the
+  Narratio-specific ownership model.
+- It describes target canonical paths even when a later stage will perform the
+  physical rename.
+- It contains no implementation sequence or future runtime claim.
+
+## Stage 2: Refocus The Architecture Policy
+
+### Goal
+
+Make `docs/policy/architecture.md` the concise normative owner of Narratio's
+current system shape, dependency boundaries, invariants, safety properties,
+and non-goals.
+
+### Work
+
+1. Review the current architecture policy, the feature roadmap, the new
+   documentation policy, `../notarius/docs/policy/architecture.md`, and the
+   current internal overview and focused internal documents.
+2. Rewrite or reorganize `docs/policy/architecture.md` using the Notarius
+   architecture policy as a style and ownership reference, not as a source of
+   Narratio runtime facts.
+3. Preserve and clearly state Narratio's existing normative decisions:
+   - a small, explicit, stage-driven orchestrator rather than a generic DAG or
+     workflow engine;
+   - Narratio ownership of orchestration, configuration resolution, run and
+     session state, artifact and path modeling, manifests, resume, and publish;
+   - isolation of WhisperX, Seriatim, Audita, Scriptorium, notification, and
+     object-storage details behind adapters;
+   - strict, centralized configuration and narrow templating;
+   - centralized local and remote path construction and confined writes;
+   - manifest-driven stage progress and transactional stage completion;
+   - the remote publish commit boundary in which `current/run_id.txt` is
+     written last;
+   - private campaign-data and secret-handling invariants;
+   - deterministic ordering and repeatable orchestration where practical; and
+   - the existing architectural non-goals.
+4. Keep package names and concrete component inventories out of architecture
+   except where a name is essential to express a boundary. Route concrete
+   ownership to `../internal/overview.md` and focused internal docs.
+5. Replace the general testing inventory with a short architectural testing
+   expectation and a link to `testing.md`. Package- or subsystem-specific test
+   details belong in internal docs when useful.
+6. Replace documentation-rule duplication with a short requirement and a link
+   to `documentation.md`.
+7. Link operational layout and lifecycle statements to `../operations.md` and
+   external contract statements to `../integrations/` where useful. Do not
+   duplicate their complete contracts.
+8. Remove all obsolete references, especially
+   `docs/documentation/policy.md` and `docs/architecture.md`.
+9. Do not invent ADR links. Mention `docs/adr/` only as the future home of
+   significant decision history.
+
+### Checks
+
+- Search the file for `docs/documentation/policy.md`, `docs/architecture.md`,
+  and `docs/internal/README.md`; none should remain.
+- Confirm links resolve relative to `docs/policy/`.
+- Compare every retained invariant with the existing architecture policy and
+  relevant current internal documentation; no invariant may be weakened by
+  omission merely to shorten the document.
+- Run `git diff --check -- docs/policy/architecture.md`.
+
+### Completion Criteria
+
+- Architecture owns normative system rules but not the package inventory,
+  general testing policy, documentation policy, CLI reference, configuration
+  reference, or operational procedures.
+- Existing Narratio safety and publish invariants remain explicit.
+
+## Stage 3: Move And Rewrite The Contributor Guide
+
+### Goal
+
+Create the canonical first-read contributor landing page at
+`docs/development.md` and remove its obsolete policy location.
+
+### Work
+
+1. Move `docs/policy/development.md` to `docs/development.md` using a normal
+   repository rename so history remains recognizable.
+2. Rewrite it as a concise, table-of-contents-adjacent landing page modeled on
+   `../notarius/docs/development.md`, adapted entirely to Narratio.
+3. Begin with a short orientation stating that Narratio is a stage-driven Go
+   orchestrator and route readers to:
+   - `README.md` for product context;
+   - `policy/architecture.md` for normative system boundaries; and
+   - `internal/overview.md` for implemented component ownership.
+4. Add a `What To Read` table with task-specific routes for at least:
+   - locating current component ownership;
+   - architecture, boundaries, invariants, or safety changes;
+   - documentation changes;
+   - adding, reviewing, rewriting, or deleting tests;
+   - CLI behavior;
+   - configuration loading or user-visible configuration;
+   - session workflow, restore, status, cleanup, and object storage;
+   - stage behavior and pipeline sequencing;
+   - adapters and external contracts;
+   - manifests, artifacts, workspace paths, and publish behavior;
+   - examples; and
+   - proposed or unimplemented behavior.
+5. For each row, link both the internal implementation guide and public or
+   external contract when those have distinct ownership. Do not restate their
+   rules in the table.
+6. End with concise validation guidance:
+   - use focused package tests while iterating;
+   - run `go test ./...`;
+   - run `go vet ./...`; and
+   - run `go build ./cmd/narratio` for repository-wide changes.
+7. Remove the old repository-layout inventory, detailed change playbooks,
+   dependency policy, and duplicated coding conventions. Route those topics to
+   architecture, internal documentation, public contracts, examples, and the
+   testing or documentation policy instead.
+8. Update direct references to the contributor guide in files already changed
+   in Stages 1 and 2 if any transitional link remains. Broader navigation is
+   handled in Stage 5.
+
+### Checks
+
+- Confirm `docs/development.md` exists and
+  `docs/policy/development.md` does not.
+- Confirm all links in the new file resolve relative to `docs/`.
+- Confirm the guide contains no package inventory or second definition of a
+  public contract.
+- Run `git diff --check -- docs/development.md`.
+
+### Completion Criteria
+
+- A new maintainer or coding agent can choose the correct canonical reading
+  path from one short document.
+- The contributor guide is navigational rather than a fourth normative policy.
+
+## Stage 4: Replace The Repository Agent Instruction
+
+### Goal
+
+Make `AGENTS.md` a stable pointer to the task-specific contributor guide.
+
+### Work
+
+Replace the entire root `AGENTS.md` contents with exactly these two lines,
+including the line break and final period:
+
+```text
+Please review `docs/development.md` for initial orientation in this repository
+and follow its task-specific reading guide.
+```
+
+Do not retain the previous instruction, add headings, add generated markers, or
+append repository policy details.
+
+### Checks
+
+- Run `git diff --check -- AGENTS.md`.
+- Verify exact content with:
+
+  ```sh
+  diff -u <(printf '%s\n' 'Please review `docs/development.md` for initial orientation in this repository' 'and follow its task-specific reading guide.') AGENTS.md
+  ```
+
+### Completion Criteria
+
+- The comparison is empty and `AGENTS.md` contains no other text.
+
+## Stage 5: Align Structural Entry Points And Navigation
+
+### Goal
+
+Complete the selected structural parity changes and make every primary entry
+point use the new canonical paths.
+
+### Work
+
+1. Rename `docs/internal/README.md` to `docs/internal/overview.md`.
+2. Refocus the renamed file as the implemented component inventory:
+   - state its boundary against architecture and public/operator contracts;
+   - show the high-level execution path from `cmd/narratio` through
+     `internal/app`, configuration and composition, stages and adapters,
+     manifests and artifacts, and durable outputs;
+   - provide a compact component table for the executable, app orchestration,
+     configuration, stages, adapters, manifests, artifacts/path safety,
+     previous-session cache, logging, and artifact policy; and
+   - retain links to every focused internal document.
+3. Keep the canonical stage order in the internal overview only as an
+   implemented inventory summary. Link to stage documents for mechanics and to
+   CLI/operations for user-visible execution semantics.
+4. Update `README.md` while keeping it short:
+   - preserve Narratio's product description and minimal successful command;
+   - link to `docs/development.md` and `docs/internal/overview.md`;
+   - include the documentation, architecture, and testing policies in a
+     maintainer-oriented portion of the link list without turning the README
+     into contributor guidance; and
+   - retain user links to CLI, configuration, operations, troubleshooting,
+     integrations, and examples.
+5. Update all references throughout `README.md`, `docs/`, and roadmap files from
+   `docs/policy/development.md` to `docs/development.md`, and from
+   `docs/internal/README.md` to `docs/internal/overview.md`. Fix relative links
+   according to the referencing file's directory rather than performing a
+   blind textual replacement.
+6. Correct other obsolete structural references already known in
+   `docs/roadmap/notarius-extract-stage.md`, including `docs/architecture.md`,
+   so it points to `docs/policy/architecture.md` and the now-existing
+   `docs/development.md`. Do not change that roadmap's feature design or claim
+   that extraction is implemented.
+7. Keep `docs/integrations/README.md` as the integrations index for now; update
+   its links and ownership language as necessary, but do not rename it.
+
+### Checks
+
+- Search the repository documentation, excluding this implementation plan and
+  its feature roadmap, for `docs/policy/development.md`,
+  `docs/internal/README.md`, `docs/architecture.md`, and
+  `docs/documentation/policy.md`; none should remain. The two planning documents
+  may name old paths when specifying the required migrations.
+- Confirm `README.md`, `docs/development.md`, and
+  `docs/internal/overview.md` form a coherent orientation chain.
+- Run `git diff --check` for all changed Markdown files.
+
+### Completion Criteria
+
+- The physical file layout matches the canonical ownership table.
+- All primary entry points and known inbound links use the new locations.
+- No compatibility stub is left at either old path.
+
+## Stage 6: Audit User, Operator, And Integration Contracts
+
+### Goal
+
+Give volatile public and external facts one canonical owner while preserving
+useful task-oriented guidance.
+
+### Work
+
+1. Review `docs/cli.md`, `docs/config.md`, `docs/operations.md`,
+   `docs/troubleshooting.md`, every file under `docs/integrations/`, maintained
+   examples, and the corresponding Go implementations and tests.
+2. For code discovery, follow repository instructions: use the codebase
+   knowledge graph first, then use text search for literal commands, fields,
+   defaults, paths, messages, Markdown, YAML, and other non-code content.
+3. Make ownership conform to policy:
+   - CLI owns commands, arguments, flags, invocation semantics, output
+     conventions, and exits;
+   - configuration owns discovery, precedence, fields, defaults, environment
+     overrides, and validation;
+   - operations owns runtime workflows, physical local and remote layout,
+     resume, cleanup, permissions, recovery, and operational limits;
+   - troubleshooting owns symptom-led diagnosis and safe fixes, linking rather
+     than redefining other contracts; and
+   - integrations own external protocols, file formats, request/result shapes,
+     logical durable outputs, and compatibility behavior.
+4. Preserve concise cross-cutting workflows in the document whose audience
+   owns the task. Replace repeated volatile definitions with stable summaries
+   and direct links.
+5. Create `docs/integrations/whisperx.md`. Derive its current contract from
+   `internal/adapters/whisperx`, `internal/stage/transcribe.go`, configuration,
+   and tests. Cover only:
+   - Narratio's purpose for the integration;
+   - the HTTP adapter boundary;
+   - request and response expectations;
+   - retry, timeout, cancellation, validation, and failure semantics;
+   - deterministic or concurrency behavior that is externally relevant; and
+   - links to configuration for operator-selected values and to internal docs
+     for implementation mechanics.
+   Do not duplicate the configuration field table or physical workspace paths.
+6. Add WhisperX to `docs/integrations/README.md` and correct the index's
+   description: integration contracts are externally observable boundaries,
+   not merely implementation-level references.
+7. Review the Audita, Scriptorium, and Seriatim documents for the same boundary.
+   Keep their protocol and data contracts; move or replace configuration field
+   definitions and internal runner wiring with links when duplicated.
+8. Verify every documented command, flag, field, default, environment
+   override, exit behavior, path, and integration guarantee against code or a
+   focused test. If a current fact cannot be verified, remove unsupported
+   specificity or record the issue for separate follow-up.
+
+### Checks
+
+- Compare CLI command and flag inventories with `internal/app` command parsing
+  and its tests.
+- Compare configuration tables with `internal/config` structs, defaults,
+  normalization, loading, validation, and tests.
+- Compare operational path and lifecycle claims with `internal/artifacts`,
+  `internal/manifest`, `internal/app`, `internal/stage`, and their tests.
+- Compare each integration contract with its adapter and stage boundary tests.
+- Confirm troubleshooting entries use symptom, likely cause, diagnostic step,
+  safe fix, and relevant links.
+- Run focused tests only when needed to verify a disputed contract; no code
+  changes are authorized.
+- Run `git diff --check` for changed documentation.
+
+### Completion Criteria
+
+- Each volatile user, operator, and integration fact has one authoritative
+  definition.
+- The new WhisperX contract is discoverable and implementation-accurate.
+- Task-oriented workflows remain usable without maintaining parallel reference
+  tables.
+
+## Stage 7: Audit Internal Documentation And Examples
+
+### Goal
+
+Make internal documents explain implementation without redefining architecture,
+public contracts, external contracts, or future work, and confirm maintained
+examples remain canonical.
+
+### Work
+
+1. Review every focused file under `docs/internal/` against its current package
+   implementation and focused tests.
+2. For each internal document, retain or establish:
+   - purpose and implemented owner;
+   - internal collaborators and execution flow;
+   - inputs, outputs, and state transitions expressed at the internal boundary;
+   - package-local guarantees, failures, and safety invariants;
+   - links to relevant tests or test areas when they materially help a
+     maintainer; and
+   - links to public, operator, configuration, or integration contracts rather
+     than duplicate definitions.
+3. Audit the highest-drift topics explicitly:
+   - canonical stage order, prerequisites, invalidation, skip, force, resume,
+     and failure behavior;
+   - session and run manifest states and transitions;
+   - artifact identities, resolution rules, checksums, and current-state
+     pointers;
+   - workspace, cache, spool, logs, reports, and object-storage keys;
+   - restore discovery, planning, conflict handling, execution, and reporting;
+   - publish upload ordering and commit semantics;
+   - adapter composition and subprocess behavior; and
+   - path confinement, deletion, and cleanup safety.
+4. Where the same internal fact appears in several focused documents, select
+   the component that owns it and use links from consumers. Do not over-prune a
+   short invariant when repeating it is necessary to prevent an unsafe local
+   change; in that case, state the invariant briefly and link to its normative
+   owner.
+5. Review all complete YAML and input artifacts under `examples/`:
+   - keep complete copyable files there rather than in prose;
+   - ensure documentation links to them rather than maintaining full duplicate
+     examples;
+   - confirm they contain no credentials or private campaign content; and
+   - verify they load and validate through existing tests where such coverage
+     already exists.
+6. Do not modify application code or invent new test infrastructure. A missing
+   example test may be recorded for later code work; it is not in scope for
+   this documentation-only implementation.
+
+### Checks
+
+- Search internal docs for duplicated configuration field/default tables, CLI
+  flag tables, complete external schemas, and physical operations procedures;
+  replace inappropriate copies with links.
+- Compare the stage inventory in `docs/internal/overview.md` with the
+  implemented stage registry.
+- Run the existing example/config validation tests identified in
+  `docs/development.md` or the current test suite.
+- Run `git diff --check` for changed documentation and examples.
+
+### Completion Criteria
+
+- Internal documentation is an accurate component-level implementation guide.
+- Architecture and public/external contracts remain authoritative at their
+  respective boundaries.
+- Complete examples are centralized, valid, discoverable, and secret-free.
+
+## Stage 8: Perform Repository-Wide Validation And Close The Roadmap
+
+### Goal
+
+Verify the migrated documentation as a coherent whole and record completion
+only after every acceptance criterion is satisfied.
+
+### Work
+
+1. Review `README.md`, `AGENTS.md`, `docs/development.md`, all policy files,
+   all user/operator references, all integration and internal documents, all
+   roadmaps, and all maintained examples as one navigation system.
+2. Search for obsolete paths and project-name leakage:
+
+   ```sh
+   rg -n 'docs/policy/development\.md|docs/internal/README\.md|docs/architecture\.md|docs/documentation/policy\.md' README.md AGENTS.md docs --glob '!docs/roadmap/implementation.md' --glob '!docs/roadmap/documentation.md'
+   rg -n 'Notarius' README.md AGENTS.md docs --glob '!docs/roadmap/notarius-extract-stage.md'
+   ```
+
+   The first search must return no matches. Review every match from the second;
+   Narratio may legitimately mention the Notarius product or integration, but
+   copied Notarius policy language must not remain.
+3. Validate local Markdown file and directory links with a reproducible script
+   that scans `README.md`, `AGENTS.md`, and `docs/**/*.md`, resolves relative
+   targets from each source file, strips anchors and query fragments, ignores
+   external URLs and pure anchors, and fails for missing local targets. Use an
+   existing repository checker if present. Otherwise run a temporary script
+   without adding it or a new dependency to the repository.
+4. Manually inspect anchor links and directory links because a basic local-path
+   checker may not validate them fully.
+5. Check formatting and whitespace:
+
+   ```sh
+   git diff --check
+   ```
+6. Run the complete existing validation suite:
+
+   ```sh
+   go test ./...
+   go vet ./...
+   go build ./cmd/narratio
+   ```
+7. Review the feature roadmap acceptance criteria one by one. Confirm that:
+   - canonical ownership is explicit and reflected by actual content;
+   - current behavior and future roadmap work are separated;
+   - examples and commands match implementation;
+   - no sensitive data was introduced;
+   - no obsolete path or compatibility stub remains; and
+   - this effort changed documentation only.
+8. If all criteria and checks pass, change the status in
+   `docs/roadmap/documentation.md` from `Proposed.` to `Completed.` and change
+   this plan's status from `Proposed.` to `Completed.`. Do not mark either
+   complete while required work or an unexplained validation failure remains.
+9. If a validation failure predates this work and is demonstrably unrelated,
+   record the exact command, failure, and evidence in the implementation handoff
+   rather than changing application code. Documentation-link or content failures
+   introduced or exposed by this migration must be fixed before completion.
+
+### Completion Criteria
+
+- All Stage 8 searches and documentation checks pass.
+- `go test ./...`, `go vet ./...`, and `go build ./cmd/narratio` pass, or a
+  precisely evidenced unrelated pre-existing failure is reported.
+- Both roadmap documents are marked `Completed.` only after the intended final
+  state is present.
+- The final handoff lists changed documents, validation commands and results,
+  and any explicitly out-of-scope follow-up without claiming unperformed work.

docs/roadmap/notarius-extract-stage.md

@@ -0,0 +1,380 @@
+# Notarius Extraction Stage
+
+## Status
+
+Proposed.
+
+## Purpose
+
+Add a first-class Narratio `extract` stage that runs Notarius against the
+session's final trimmed transcript, validates and collects the resulting
+structured D&D artifacts, and registers those artifacts for later use by the
+`analyze` and `publish` stages.
+
+This feature should integrate Notarius through Narratio's existing stage,
+adapter, manifest, workspace, and artifact-catalog boundaries. It must not turn
+Narratio into a generic workflow engine or a second configuration language for
+Notarius pipelines.
+
+## User Outcome
+
+An operator can enable one configured Notarius pipeline for a Narratio
+campaign. During a normal run, Narratio will:
+
+1. finish producing the session transcript tiers;
+2. invoke Notarius once with the final trimmed Seriatim JSON transcript;
+3. collect and validate the configured structured artifact lanes;
+4. record their exact files and provenance in the Narratio manifest; and
+5. make those artifacts selectable as inputs to Scriptorium artifacts in the
+   later `analyze` stage.
+
+The maintained D&D example should demonstrate all ten lanes emitted by
+Notarius's complete `dnd-session` pipeline.
+
+## Target Stage Architecture
+
+### Canonical Order
+
+The canonical stage order becomes:
+
+```text
+prepare -> transcribe -> merge -> polish -> normalize -> trim -> render
+        -> extract -> analyze -> publish -> notify
+```
+
+`extract` is deliberately after all transcript-producing stages and before
+analysis. Its source document is the manifest-resolved
+`narratio.transcript.final_trimmed` artifact, normally
+`transcripts/final.trimmed.json`. It does not consume rendered Markdown.
+
+Adding the stage must update full-plan construction, explicit stage selection,
+downstream invalidation, prerequisite checks, resume behavior, run manifests,
+CLI stage validation and help, and every canonical-stage inventory. Forcing an
+upstream transcript stage must stale a previously successful `extract` stage
+and its downstream stages. Forcing `extract` must stale `analyze`, `publish`,
+and `notify` according to existing rules.
+
+### Stage Boundary
+
+The stage owns Narratio policy and state transitions:
+
+- resolve the final trimmed transcript through the runtime artifact catalog;
+- build a Narratio-level Notarius request from validated configuration and
+  run-local paths;
+- call a narrow Notarius adapter;
+- apply the configured required-output policy;
+- materialize the validated bundle into its canonical session location;
+- return manifest-ready artifact references and bounded metadata; and
+- fail without marking the stage successful when any required contract or
+  materialization step fails.
+
+The stage must not construct subprocess arguments, infer Notarius output
+filenames, parse provider logs, or decode individual D&D payload bodies.
+
+### Adapter Boundary
+
+Add a dedicated Notarius adapter package with a small interface, production
+subprocess implementation, and test fake. Its request should contain only the
+resolved Notarius binary, configuration path, pipeline ID, transcript path,
+output root, working directory, timeout, and process-log destinations needed
+for one run.
+
+The adapter owns:
+
+- optional `notarius config validate` preflight for the configured pipeline;
+- exact `notarius run ... --json` argument construction;
+- stdout and stderr separation;
+- context cancellation and timeout propagation through Narratio's shared
+  subprocess boundary;
+- exit-status handling;
+- decoding the `notarius.run-result.v1` success receipt;
+- receipt and index path-confinement checks;
+- decoding `index.json` and resolving descriptor paths safely beneath the
+  reported output directory; and
+- returning a transport-neutral result containing the bundle location,
+  receipt summary, lane descriptors, pipeline-wide descriptors, warnings and
+  rejection locations, and diagnostic log paths.
+
+Only exit status zero permits receipt decoding. Receipt, index, or descriptor
+paths that are absolute where a logical relative path is required, or that
+escape their owning root, are integration failures. Unknown fields in a
+supported receipt or index schema should be tolerated. Unsupported schema
+versions and incompatible descriptor metadata should fail clearly.
+
+The adapter must not write Narratio manifests, choose required lanes, decide
+analysis inputs, or contain D&D domain logic.
+
+## Configuration Contract
+
+Add a strict optional `pipeline.notarius` configuration section. Omission or
+`enabled: false` keeps the current workflow usable and causes `extract` to
+self-skip without outputs.
+
+The section should provide:
+
+- `enabled`: explicit opt-in;
+- `binary`: Notarius executable, defaulting to `notarius`;
+- `config_path`: required when enabled;
+- `pipeline_id`: required when enabled;
+- `timeout`: a positive stage timeout with a documented default;
+- `working_directory`: optional explicit subprocess working directory,
+  defaulting to the directory containing `config_path`; and
+- an `outputs` map defining the Notarius lane artifacts Narratio promises to
+  collect.
+
+Each output-map key is a stable Narratio extraction key. Each value must define:
+
+- the exact Notarius `lane_id`;
+- the expected `media_type`;
+- the expected `schema_id`;
+- the expected `schema_version`; and
+- optionally an expected `module_key` when the operator needs to constrain the
+  producing module as part of compatibility.
+
+Narratio derives the downstream source ID
+`narratio.extraction.<output-key>` from the map key. Keys and lane IDs must be
+non-empty, unique after normalization, path-safe under the existing artifact
+policy, and collision-free with built-in and configured artifact identities.
+Every configured output is required: a successful Notarius process that omits
+one, rejects it, or reports incompatible descriptor metadata fails the
+`extract` stage.
+
+This explicit map keeps Narratio's consumer contract stable when a Notarius
+lane ID or schema changes and avoids hard-coding the current D&D family into a
+generic adapter. It also replaces a separate `required_lanes` list, which would
+duplicate configuration.
+
+Narratio should not reproduce Notarius lane selection, references, LLM
+profiles, model settings, retries, concurrency, or prompt configuration. Those
+remain in the referenced Notarius configuration. Narratio should not expose a
+runtime lane-selection flag for `extract`; one stage invocation runs the
+configured Notarius pipeline as a unit.
+
+All configured paths should become absolute during Narratio configuration
+resolution. The deterministic default working directory allows a Notarius
+profile path relative to that directory, but operator documentation should
+still recommend absolute deployment paths where practical. Notarius reference
+paths continue to follow Notarius's own configuration-relative rules.
+
+## Output And Artifact Model
+
+### Canonical Bundle
+
+Run Notarius against a run-local output root. After all configured descriptors
+are validated, materialize the contents of the exact run-specific Notarius
+bundle into a fixed canonical session directory:
+
+```text
+artifacts/notarius/
+```
+
+Preserve its relative layout, including `index.json`, `manifest.json`,
+`rejected.json`, `warnings.json`, `lanes/`, and any indexed `chunk-map.json` or
+`evidence-context.json`. Materialize the complete directory as one narrow,
+transactional replacement so a failed or interrupted rerun cannot mix files
+from different Notarius runs.
+
+The raw subprocess receipt and stderr log belong in the run-local `extract`
+report and log directories. The raw receipt identifies the original run-local
+Notarius bundle and must not be rewritten to pretend that the canonical copy
+was its original `output_directory`. Narratio's manifest is the durable ledger
+for the canonical materialized paths.
+
+### Registered Artifact Sources
+
+For each configured output, locate the lane through the canonical copy of
+`index.json` and record a manifest artifact with:
+
+- source ID `narratio.extraction.<output-key>`;
+- canonical lane-file path discovered from the index;
+- producer stage and Narratio run ID;
+- checksum;
+- Notarius lane ID; and
+- descriptor media type, schema identity/version, and module key when present.
+
+If the current manifest model cannot carry descriptor compatibility metadata,
+extend its artifact metadata in a backward-tolerant way rather than encoding
+that information in filenames or source IDs.
+
+Also record the canonical Notarius index as a stage output or stage metadata so
+operators can discover the complete bundle, including non-lane artifacts. The
+configured lane sources are the stable interface for analysis; the index and
+bundle remain the provenance and inspection interface.
+
+## Analysis And Publish Integration
+
+Extend the runtime artifact catalog and configured Scriptorium input validation
+so an enabled analysis artifact can declare, for example:
+
+```yaml
+inputs:
+  npc_registry:
+    source: narratio.extraction.npc_registry
+```
+
+Resolution must remain manifest-first and verify that the recorded artifact
+was produced by a successful current `extract` stage. A required extraction
+source that is unavailable must fail analysis with guidance to configure or
+rerun `extract`; an optional source may be omitted according to the existing
+Scriptorium input contract.
+
+Publish source resolution should accept configured
+`narratio.extraction.<output-key>` sources through the same artifact catalog so
+operators may publish selected structured artifacts without manually copying
+paths. The existing `--artifacts` flag remains scoped to Scriptorium artifact
+selection and must not partially execute the Notarius pipeline.
+
+No current-session analysis artifact should consume an incidental file from a
+failed, stale, skipped, or superseded extraction run.
+
+## Failure, Skip, Resume, And Diagnostics
+
+- Missing or invalid enabled Notarius configuration fails configuration
+  validation before stage execution where statically discoverable.
+- A disabled or absent Notarius configuration makes `extract` skip with clear
+  stage metadata and no new outputs.
+- A missing or invalid final trimmed transcript fails `extract` before starting
+  Notarius.
+- Preflight failure, nonzero Notarius exit, cancellation, timeout, malformed or
+  unsupported receipt/index data, unsafe paths, incompatible descriptors,
+  rejected required outputs, or missing configured lanes fails the entire
+  stage.
+- Process success does not override Narratio's required-output policy.
+- A failed run retains bounded run-local receipt bytes, stderr, and the
+  unpublished Notarius bundle for diagnosis, subject to Narratio's existing
+  sensitive-data and cleanup policies.
+- The canonical bundle and manifest artifacts are updated only after complete
+  validation and materialization.
+- Resume skips a succeeded, non-stale `extract` stage only when its
+  manifest-recorded canonical index and configured lane outputs still validate.
+- Force and staleness behavior follows the ordinary stage contract; it must not
+  depend on merely finding `artifacts/notarius/` on disk.
+
+Transcripts, Notarius outputs, evidence context, manifests, receipts, and logs
+are private campaign material. Subprocess arguments and manifest metadata must
+not contain secrets. Credentials remain in the environment or in mechanisms
+owned by Notarius and PromptKit.
+
+## Maintained D&D Example
+
+Add or update a Narratio example that enables Notarius's complete
+`dnd-session` pipeline and maps these ten required lanes to stable extraction
+keys:
+
+| Output key | Notarius lane ID |
+| --- | --- |
+| `item_registry` | `item-registry` |
+| `npc_registry` | `npc-registry` |
+| `location_registry` | `location-registry` |
+| `scene_descriptions` | `scene-descriptions` |
+| `item_occurrences` | `item-occurrences` |
+| `spells` | `spells` |
+| `combat_turns` | `combat-turns` |
+| `npc_occurrences` | `npc-occurrences` |
+| `location_occurrences` | `location-occurrences` |
+| `enemy_events` | `enemy-events` |
+
+The example must include each lane's current media type and schema identity
+from Notarius's published contracts. It should also demonstrate at least one
+Scriptorium analysis artifact consuming one or more
+`narratio.extraction.*` sources. The example must use placeholders and relative
+paths suitable for the example tree, contain no credentials, and pass the
+repository's configuration validation tests.
+
+## Compatibility Policy
+
+The initial integration baseline is the public subprocess contract available
+in Notarius v0.3.0:
+
+- successful JSON receipt schema `notarius.run-result.v1`;
+- production JSON bundle discovery through `index.json`; and
+- the schema IDs and versions explicitly configured for required lanes.
+
+Runtime compatibility should be decided from those published contracts, not
+from textual parsing of `notarius --version`. New optional receipt or index
+fields must not break Narratio. An unsupported receipt version or lane schema
+must fail before the artifact is registered for analysis.
+
+## Documentation Deliverables When Implemented
+
+Update current-behavior documentation in the same change that implements the
+feature:
+
+- add `docs/integrations/notarius.md` for the external CLI, receipt, bundle,
+  and adapter contract, linking to Notarius's canonical documentation;
+- add `docs/internal/stage-extract.md` for stage inputs, outputs, collaborators,
+  state transitions, failures, and focused tests;
+- update `docs/internal/adapters.md`, `docs/internal/artifacts.md`,
+  `docs/internal/manifest.md`, and the internal stage inventory;
+- update `docs/architecture.md` to list Notarius among isolated external
+  systems and preserve the adapter/stage boundary;
+- update `docs/config.md`, `docs/cli.md`, `docs/operations.md`,
+  `docs/troubleshooting.md`, `README.md`, and maintained examples only to the
+  extent their canonical scopes require; and
+- add the missing `docs/development.md` required by the repository's
+  documentation policy, or track that repository-wide documentation gap in a
+  separate roadmap if it is intentionally outside the implementation scope.
+
+Outside this roadmap, do not describe `extract`, Notarius configuration, or
+`narratio.extraction.*` sources as implemented until the code exists.
+
+## Testing And Validation Expectations
+
+Implementation should provide focused tests for:
+
+- strict configuration decoding, defaults, required fields, path resolution,
+  output-map validation, normalized-key collisions, and example loading;
+- exact stage order, selection, downstream staleness, resume, force, and
+  prerequisite behavior;
+- adapter command construction, deterministic working directory, environment
+  inheritance, stdout/stderr separation, cancellation, timeout, and nonzero
+  exits;
+- supported and unsupported receipt versions, unknown optional fields,
+  malformed receipts, index decoding, and path escapes at every boundary;
+- descriptor lookup by lane ID rather than filename, expected metadata checks,
+  missing/rejected configured lanes, and tolerated unconfigured lanes;
+- run-local execution, transactional canonical-bundle replacement, checksums,
+  failed-run preservation, and manifest recording;
+- artifact-catalog resolution from `narratio.extraction.*` into analysis and
+  publish, including required, optional, missing, stale, and skipped cases; and
+- end-to-end stage execution with a fake Notarius adapter, without live LLM or
+  external subprocess requirements in the ordinary test suite.
+
+Run the repository-wide Go tests, vet, build, and maintained example validation
+after focused tests pass.
+
+## Acceptance Criteria
+
+- `extract` is a first-class transactional stage between `render` and
+  `analyze` everywhere Narratio models stage order or state.
+- Narratio invokes Notarius only through a narrow, tested adapter.
+- The stage consumes the manifest-resolved final trimmed Seriatim transcript.
+- The Notarius configuration remains owned by Notarius; Narratio configures
+  only invocation and its downstream consumer contract.
+- Every configured output is discovered through the receipt and `index.json`,
+  contract-checked, materialized transactionally, and recorded with a stable
+  `narratio.extraction.*` source ID.
+- The complete D&D example maps all ten current lanes and passes strict config
+  validation.
+- Analysis can consume extraction sources through the existing artifact input
+  model, and publish can select them through the artifact catalog.
+- Failed, partial, rejected, unsafe, stale, or incompatible output never becomes
+  a current analysis input.
+- Resume and force behavior remains manifest-driven.
+- Documentation accurately describes the implemented stage, adapter,
+  configuration, operations, and compatibility boundary without duplicating
+  Notarius's canonical schemas.
+
+## Non-Goals
+
+- Reimplementing Notarius extraction, prompts, schemas, references, retries,
+  profiles, or lane orchestration in Narratio.
+- Allowing one Narratio run to invoke arbitrary extractor programs or multiple
+  Notarius pipelines.
+- Making `extract` a configurable DAG or folding it into the Scriptorium
+  `analyze` stage.
+- Partially selecting Notarius lanes through Narratio's `--artifacts` flag.
+- Decoding D&D payload bodies in the generic Notarius adapter.
+- Supporting previous-session extraction artifacts in the initial feature.
+- Requiring live Notarius, PromptKit, an LLM provider, or external services in
+  the ordinary unit test suite.