docs: add domain boundary READMEs for governance anchors

calibration/README.md

@@ -0,0 +1,17 @@
+# Calibration Package
+
+`calibration/` is the deterministic operator-parameter replay and tuning
+package. It explores bounded `CalibrationParams` candidates against eval cases
+and emits before/after metrics for review.
+
+It is not the ADR-0175 reliability ledger and it does not grant serving
+licenses. Serving discipline is owned by `core.reliability_gate`; Workbench reads
+that evidence through `workbench/calibration.py` without re-running lanes or
+mutating license state.
+
+This boundary is intentional:
+
+- `calibration/params.py`, `calibration/replay.py`, `calibration/tune.py`, and
+  `calibration/report.py` support deterministic parameter audits.
+- `workbench/calibration.py` projects committed practice and serving artifacts
+  into a read-only UI/API surface.

contemplation/README.md

@@ -0,0 +1,17 @@
+# Contemplation Artifacts
+
+This directory is an artifact namespace for committed contemplation process
+reports, especially the `runs/` evidence consumed by teaching queue and
+Workbench readers.
+
+It is intentionally not a Python package:
+
+- no `contemplation/__init__.py`
+- no Python source files under this tree
+- executable contemplation code lives under `core/contemplation/`
+- always-on runtime life writes local reports under
+  `<engine_state>/contemplation_runs/`
+
+Keeping this split explicit prevents `import contemplation` ambiguity while
+preserving the deterministic JSON evidence shape expected by queue and
+Workbench surfaces.

core/demos/README.md

@@ -0,0 +1,14 @@
+# Demo Composition Layer
+
+`core/demos/` contains the typed composition surface for demos:
+contracts, adapters, showcase rendering, and expert-demo packaging.
+
+It does not own standalone scenario fixtures. Those live under top-level
+`demos/`, where each demo package can pin its inputs, expected artifacts, and
+honesty ledger.
+
+Boundary:
+
+- `demos/` proves a narrow claim inside a deterministic local envelope.
+- `core/demos/` adapts proven demos into shared presentation and Workbench
+  surfaces.

core_ingest/README.md

@@ -0,0 +1,16 @@
+# Core Ingest
+
+`core_ingest/` converts external source material into typed candidate pressure:
+content-addressed packets with provenance, modality, determinism class, review
+level, and semantic keys.
+
+Its durable path runs the three-gate `IngestCompiler` and can export
+`LearningArtifact` objects. Its read-only CLI surface (`core ingest compile`) is
+for inspection and does not write vault entries, mutate packs, ratify learning,
+or call `ingest/gate.py`.
+
+Boundary:
+
+- `core_ingest` prepares and validates candidate pressure.
+- `ingest/gate.py` injects runtime field state into the versor manifold.
+- durable mutation still belongs to the reviewed teaching path.

demos/README.md

@@ -0,0 +1,15 @@
+# Deterministic Demo Packages
+
+`demos/` contains standalone, claim-scoped demonstration packages. Each demo
+has its own fixtures, expected artifacts, local authority code, and runner.
+
+These packages are intentionally importable because tests and Workbench demo
+routes execute them as deterministic envelopes. They are not generic runtime
+adapters and they must not perform hidden side effects.
+
+Use this directory for bounded proof demos such as proposer authority,
+proof-carrying promotion, epistemic truth-state refusal, or domain-specific
+decision substrates.
+
+Use `core/demos/` for composition contracts, showcase adapters, and runtime
+presentation of already-proven demos.

ingest/README.md

@@ -0,0 +1,12 @@
+# Runtime Ingest Gate
+
+`ingest/` owns the runtime injection boundary: raw token/state material enters
+the versor manifold through `ingest/gate.py`.
+
+This is an allowed normalization boundary. `inject()` calls
+`algebra.versor.normalize_to_versor()` once at construction time and returns a
+`FieldState` satisfying the field invariant.
+
+It is not the durable learning compiler. Candidate learning material should be
+prepared by `core_ingest` and reviewed through the teaching/governance path
+before it becomes durable standing.

language_packs/README.md

@@ -0,0 +1,15 @@
+# Language Packs
+
+`language_packs/` owns reviewed language-pack loading and compilation. It turns
+pack manifests, lexicon rows, morphology, grammar attractors, and alignment
+metadata into runtime vocab/manifold structures.
+
+This compiler is distinct from `core_ingest.compiler`:
+
+- `language_packs.compiler` consumes reviewed pack data and builds linguistic
+  runtime structures.
+- `core_ingest.compiler` consumes external candidate pressure and produces
+  validation reports plus provisional learning artifacts.
+
+The shared word "compiler" means "deterministic lowering across a boundary";
+the source material, trust boundary, and output structures are different.

workbench/README.md

@@ -0,0 +1,22 @@
+# CORE Workbench Backend
+
+`workbench/` is the local operator/auditor API package for CORE. It exposes
+read models over committed artifacts, runtime traces, evidence bundles, demo
+envelopes, calibration ledgers, and narrow allowlisted actions.
+
+It is distinct from:
+
+- `workbench-ui/` — the React/Vite frontend.
+- `workbench_data/` — ignored local read-model artifacts such as turn journals.
+- `docs/workbench/` — plans, contracts, guides, and design documentation.
+
+Backend modules should preserve the Workbench trust boundary:
+
+- read-only by default;
+- no hidden model calls or background execution;
+- execution only through explicit allowlisted endpoints;
+- artifact projections must include source paths/digests when available.
+
+`apple_uma_report.py` belongs here because it projects a persisted benchmark
+report into a stable UI/API read model. It does not run benchmarks, import MLX,
+mutate reports, or authorize serving.