Refactor and clean up documentation

docs/development.md

@@ -0,0 +1,75 @@
+# Development
+
+This is the first-read landing page for people and LLM coding agents working on
+Notarius. It provides a concise repository orientation and routes each kind of
+change to its canonical documentation.
+
+## Orientation
+
+Notarius is a small Go application for extracting structured data from source
+material. It is a general extraction platform with an initial Seriatim and D&D
+implementation. Configured modules run through a fixed workflow:
+
+```text
+input -> chunk -> extract -> merge -> normalize -> output
+```
+
+The CLI is the application boundary. Core packages own deterministic models and
+policy, framework packages own reusable contracts and orchestration, and module
+and validator packages own concrete behavior.
+
+## Repository Map
+
+- `cmd/notarius`: executable entry point.
+- `internal/cli`: CLI behavior and production composition.
+- `internal/core`: deterministic source, config, artifact, diagnostics, and
+  workspace packages.
+- `internal/framework`: contracts, pipeline orchestration, validation helpers,
+  checkpoints, debug recording, and LLM runtime plumbing.
+- `internal/modules`: concrete implementations of the six pipeline stages.
+- `internal/validators`: concrete output validators.
+- `docs`: canonical policy, reference, integration, internal, ADR, and roadmap
+  documentation.
+- `examples`: maintained, secret-free example inputs and configuration.
+
+See [Internal Overview](internal/overview.md) for the implemented component
+map and links to focused internal documentation.
+
+## What To Read
+
+| When working on | Read | Why |
+| --- | --- | --- |
+| Application shape, package boundaries, contracts, dependency direction, runtime guarantees, or safety properties | [Architecture](policy/architecture.md) and relevant [ADRs](adr/) | Architecture defines the intended system and its invariants; ADRs preserve significant decision rationale. |
+| Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical homes, audiences, current-behavior rules, and maintenance requirements. |
+| Pipeline resolution or execution | [Pipeline Internals](internal/pipeline.md) | It documents profiles, references, validation, retries, checkpoints, and runner behavior. |
+| Production modules or validators | [Module Internals](internal/modules.md) | It documents implemented module contracts, capabilities, assets, and registration. |
+| LLM clients, prompts, schemas, profiles, or scheduling | [LLM Runtime](internal/llm.md) | It documents the transport boundary and Scriptorium integration. |
+| Diagnostics, workspace state, resume, or debug artifacts | [Diagnostics Internals](internal/diagnostics.md), [Operations](operations.md), and [Configuration](config.md) | These separate implementation details, operator behavior, and configuration contracts. |
+| CLI or user-visible configuration behavior | [CLI Reference](cli.md) and [Configuration](config.md) | These are the canonical user and operator references. |
+| External input formats, artifact schemas, or durable output files | [Integration Contracts](integrations/) | Integration documents define external and durable data contracts. |
+| Proposed or unimplemented behavior | [Roadmap](roadmap/) | Future work belongs only in roadmap documentation until implemented. |
+
+For an existing subsystem, also inspect its focused tests and the package-local
+types and contracts before changing behavior.
+
+## Validation
+
+Use focused package tests while iterating. Run the repository-wide checks when
+a change affects shared contracts, application behavior, or maintained
+documentation examples:
+
+```sh
+go test ./...
+go vet ./...
+go build ./cmd/notarius
+```
+
+## Universal Reminders
+
+- Keep non-roadmap documentation limited to implemented behavior.
+- Update affected documentation and maintained examples in the same change as
+  behavior.
+- Use fakes, fixtures, or local test servers instead of real external services
+  in tests.
+- Do not expose secrets in code, errors, logs, diagnostics, manifests,
+  documentation, or examples.