Migrate internal architecture docs to docs/internal

docs/internal/overview.md

@@ -0,0 +1,92 @@
+# Audita Internal Overview
+
+## Scope
+
+This document is the internal architecture entry point for developers and coding agents.
+
+It summarizes:
+- package boundaries;
+- the main `process` execution path;
+- where to add new code safely.
+
+## Package Map
+
+CLI and command orchestration:
+- `internal/cli`
+
+Core deterministic components:
+- `internal/core/config`
+- `internal/core/schema`
+- `internal/core/normalization`
+- `internal/core/chunking`
+- `internal/core/outputschema`
+- `internal/core/diagnostics`
+- `internal/core/reporting`
+- `internal/core/modulecatalog`
+
+Framework orchestration and contracts:
+- `internal/framework/contracts`
+- `internal/framework/modules`
+- `internal/framework/proposal_generation`
+- `internal/framework/proposals`
+- `internal/framework/runner`
+- `internal/framework/validators`
+- `internal/framework/llm`
+- `internal/framework/responseschema`
+- `internal/framework/structuredoutput`
+- `internal/framework/processreport`
+- `internal/framework/promptcontext`
+- `internal/framework/stagename`
+
+Domain implementations:
+- `internal/modules/*`
+- `internal/validators/*`
+- `internal/prompts`
+
+## Main Execution Path (`audita process`)
+
+High-level flow:
+1. CLI loads effective config and validates CLI requirements.
+2. Run directory is created and invocation/effective config artifacts are written.
+3. Transcript/glossary files are loaded and parsed.
+4. Transcript is normalized and chunked.
+5. `runner.Run` executes configured module instances.
+6. Proposals are validated, applied deterministically, and serialized in selected output schema.
+7. Process report, utilization diagnostics, correction ledger, and retention decisions are finalized.
+
+## Boundary Summary
+
+- `internal/core/*` owns deterministic, reusable logic and persistence-independent rules.
+- `internal/framework/*` owns orchestration contracts and reusable runtime plumbing.
+- `internal/modules/*` owns module-specific proposal behavior and prompt usage.
+- `internal/validators/*` owns validator composition and built-in chain assembly.
+- `internal/prompts` owns embedded prompt assets and metadata registry.
+
+## Where To Add New Code
+
+Add config fields:
+- `internal/core/config`
+
+Add module behavior:
+- one package under `internal/modules/<module_key>`
+- registration/wiring through `internal/framework/modules` and config module list
+
+Add validators:
+- implementation under `internal/validators/<validator_key>`
+- registry/chain wiring in `internal/validators`
+
+Add runtime orchestration behavior:
+- `internal/framework/*` (runner/proposal/validator/LLM plumbing)
+
+Add CLI surface:
+- `internal/cli`
+
+## Related Internal Docs
+
+- [`docs/internal/pipeline.md`](pipeline.md)
+- [`docs/internal/modules.md`](modules.md)
+- [`docs/internal/validators.md`](validators.md)
+- [`docs/internal/llm-runtime.md`](llm-runtime.md)
+- [`docs/internal/diagnostics-reporting.md`](diagnostics-reporting.md)
+- [`docs/internal/prompts.md`](prompts.md)
+- [`docs/internal/output-schemas.md`](output-schemas.md)