rlippmann · rlippmann · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -145,6 +145,11 @@ changes are acceptance criteria.
 Documentation examples explicitly referenced by a task are part of the
 expected deliverable.
 
+Root README owns cross-language discovery.
+
+Language-specific and example README files should avoid cross-language links or
+navigation mentions unless there is a deliberate exception.
+
 Do not treat documentation as merely illustrative unless explicitly stated.
 
 Do not silently change documented behavior because implementation is easier.

diff --git a/PROVIDER_CONTRACT.md b/PROVIDER_CONTRACT.md
@@ -0,0 +1,56 @@
+# Provider Contract
+
+This document is the shared provider contract used by live-model examples in
+this repository.
+
+Required (normal `openai` mode):
+
+```shell
+export OPENAI_API_KEY=...
+```
+
+Optional:
+
+```shell
+export PROVIDER=openai
+export MODEL=openai/gpt-4o-mini
+export PREPROCESSOR_MODEL=openai/gpt-4o-mini
+export OPENAI_BASE_URL=...
+export PREPROCESSOR_PROMPT_PROFILE=default
+```
+
+Provider mode contract (`PROVIDER`) is strict:
+
+- `openai`
+- `ollama`
+- `openai_compatible`
+
+Unknown values hard fail with a validation error.
+
+Resolution precedence:
+
+1. `OPENAI_BASE_URL` override
+2. `PROVIDER`
+3. default (`openai`)
+
+Operational behavior by mode:
+
+- `openai`
+  - default `base_url`: `https://api.openai.com/v1`
+  - requires `OPENAI_API_KEY`
+- `ollama`
+  - default `base_url`: `http://localhost:11434`
+  - API key optional
+- `openai_compatible`
+  - requires `OPENAI_BASE_URL` when explicitly selected with `PROVIDER`
+  - API key requirement depends on endpoint
+
+Startup emits one concise config line showing resolved `mode`, `base_url`,
+`model`, and resolution `source` (`default`, `PROVIDER`, or
+`OPENAI_BASE_URL override`).
+
+`MODEL` and `PREPROCESSOR_MODEL` use LiteLLM format: `<provider>/<model>`.
+`PREPROCESSOR_MODEL` is optional and defaults to `MODEL`.
+
+For heuristic-first usage, keep `PREPROCESSOR_PROMPT_PROFILE=default`.
+Use `llama` only for LLM-only preprocessing with Llama-family models.
diff --git a/README.md b/README.md
@@ -30,9 +30,9 @@ apps. Python also includes reference integrations.
 
 | Repo | Question |
 | --- | --- |
-| context-compiler | What is the authority contract? |
-| context-compiler-directive-drafter | How is authority acquired? |
-| context-compiler-example-integrations | Where can authority be enforced? |
+| [context-compiler (Python)](https://github.com/rlippmann/context-compiler), [context-compiler-ts (TypeScript)](https://github.com/rlippmann/context-compiler-ts) | What is the authority contract? |
+| [context-compiler-directive-drafter (Python)](https://github.com/rlippmann/context-compiler-directive-drafter), [context-compiler-directive-drafter-ts (TypeScript)](https://github.com/rlippmann/context-compiler-directive-drafter-ts) | How is authority acquired? |
+| [context-compiler-example-integrations](https://github.com/rlippmann/context-compiler-example-integrations) | Where can authority be enforced? |
 
 ## Enforcement-point catalog
 
@@ -67,7 +67,7 @@ This repo is:
 
 - an examples/integrations repo
 - organized around runtime enforcement points
-- not a library/package repo
+- not the core Context Compiler library package
 - not the authority contract
 - not the directive drafter
 - not an acquisition-layer repo

diff --git a/python/README.md b/python/README.md
@@ -1,10 +1,10 @@
 # Python examples
 
-This package publishes Python example integrations organized by enforcement
-point first.
+These examples show how Context Compiler state changes application behavior at
+runtime.
 
-Use it when you want concrete Python examples that show how authoritative
-Context Compiler state changes runtime behavior in a host application.
+Each example focuses on an enforcement point where saved premise and policy
+affect what a host allows, routes, retrieves, builds, or executes.
 
 The core library lives in
 [`context-compiler`](https://github.com/rlippmann/context-compiler).
@@ -14,25 +14,15 @@ but that layer is optional. This package is the examples and integration
 patterns layer.
 
 `context-compiler` defines the authority contract.
-`context-compiler-directive-drafter` is optional authority acquisition and
-drafting.
+`context-compiler-directive-drafter` can optionally help acquire and draft
+authority, but it is not the authority layer.
 This examples package shows where authority is enforced.
 
 Prompt reinjection influences model behavior.
 Context Compiler influences runtime behavior.
 
-## Start here
-
-Start with a generic example README below if you want the clearest explanation
-of one enforcement point before looking at runtime-specific integrations.
-
 ## Generic examples
 
-These generic examples are the main starting point for new readers.
-
-Open the enforcement point that matches the runtime behavior you want to
-inspect:
-
 - [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted confirmation and resume flows change host behavior across turns or requests
 - [Execution authorization](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/execution_authorization/README.md): protected host actions execute only when authoritative state allows them
 - [Gateway middleware](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
@@ -57,8 +47,6 @@ integrations to inspect a runtime-specific path:
 
 ## Run an example
 
-These published package docs are for discovery.
-
 To explore or run an example, use a repository checkout:
 
 1. Clone

diff --git a/python/examples/checkpoint_continuation/README.md b/python/examples/checkpoint_continuation/README.md
@@ -1,6 +1,8 @@
 # Checkpoint continuation
 
-This example demonstrates checkpoint continuation as an enforcement point.
+Restoring a saved checkpoint changes whether a fresh host process can resume
+and apply a pending itinerary change. This example shows checkpoint
+continuation in a generic Python travel-booking flow.
 
 ## Domain
 
@@ -73,14 +75,3 @@ uv run pytest python/tests/test_checkpoint_continuation_example.py
 
 For a request-boundary example, see
 [python/examples/checkpoint_continuation/fastapi/README.md](fastapi/README.md).
-
-## Related integrations
-
-The generic example teaches checkpoint continuation without framework-specific
-requirements.
-
-Related runtime surfaces:
-
-- [python/examples/checkpoint_continuation/fastapi/README.md](fastapi/README.md)
-- [typescript/starter_apps/node/README.md](../../../typescript/starter_apps/node/README.md)
-- [typescript/starter_apps/nextjs/README.md](../../../typescript/starter_apps/nextjs/README.md)
diff --git a/python/examples/checkpoint_continuation/fastapi/README.md b/python/examples/checkpoint_continuation/fastapi/README.md
@@ -1,7 +1,8 @@
 # Checkpoint continuation with FastAPI
 
-This example demonstrates checkpoint continuation across stateless HTTP request
-boundaries.
+A saved checkpoint lets later HTTP requests resume or reject a pending
+itinerary change instead of starting over. This example shows checkpoint
+continuation across stateless HTTP request boundaries.
 
 ## Enforcement point
 

diff --git a/python/examples/execution_authorization/README.md b/python/examples/execution_authorization/README.md
@@ -26,15 +26,6 @@ The tests cover authorized execution, absent-state blocking, prohibited-state
 blocking, adversarial request text, and the runtime behavior change between
 blocked and authorized state.
 
-A FastAPI variant also shows the Tier 3 comparison boundary: a live model can
+A FastAPI variant also shows the live-model comparison boundary: a live model can
 say an expense is approved, but the compiler-mediated host still denies the
 protected mutation unless authoritative state authorizes it.
-
-## Related integrations
-
-The generic examples teach the execution-authorization enforcement point in a
-small host-owned flow.
-
-For a small TypeScript host runtime surface, see:
-
-- [typescript/starter_apps/node/README.md](../../../typescript/starter_apps/node/README.md)
diff --git a/python/examples/execution_authorization/expense_approval/README.md b/python/examples/execution_authorization/expense_approval/README.md
@@ -1,7 +1,8 @@
 # Expense approval
 
-This example demonstrates execution authorization for expense approval in plain
-Python.
+Authoritative state changes whether the host executes `submit_expense` for the
+same expense request. This example shows that execution-authorization behavior
+in plain Python.
 
 Model approval is not authorization.
 
@@ -46,20 +47,20 @@ derive state from model output. The runtime behavior changes only when explicit
 authoritative Context Compiler state changes. The host does not resolve
 conflicts itself and does not treat "last directive wins" as policy.
 
-## Tier 3 FastAPI variant
+## FastAPI variant
 
-Tier 2 already proves deterministic enforcement against local and adversarial
-stubs.
+The provider-free tests already prove deterministic enforcement against local
+and adversarial stubs.
 
-The FastAPI variant adds a Tier 3 comparison where a live model produces an
-approval-class claim:
+The FastAPI variant adds a live-model comparison where a live model produces an
+approval claim:
 
 - baseline path: a naive host trusts the model claim and writes the side effect
 - compiler-mediated path: the host sees the same claim but denies execution
   unless authoritative state authorizes `expense_approval`
 
 See
-[python/examples/execution_authorization/expense_approval/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/execution_authorization/expense_approval/fastapi/README.md).
+[fastapi/README.md](fastapi/README.md).
 
 ## Validation
 

diff --git a/python/examples/execution_authorization/expense_approval/fastapi/README.md b/python/examples/execution_authorization/expense_approval/fastapi/README.md
@@ -3,11 +3,11 @@
 This FastAPI variant provides provider-free runtime-boundary validation by
 default, plus an opt-in live-model validation path.
 
-Tier 2 already proves deterministic enforcement against local and adversarial
-stubs.
+The provider-free tests already prove deterministic enforcement against local
+and adversarial stubs.
 
 The default tests here prove the runtime boundary behavior with a visible
-approval-class claim present at the request surface.
+approval claim present at the request surface.
 
 If you also run the opt-in live-model validation with
 `RUN_EXPENSE_APPROVAL_LIVE_MODEL=1`, this variant demonstrates that the same
@@ -28,7 +28,7 @@ caller-supplied or model-supplied approval text.
 
 The observable proof is a host-owned append-only JSONL file:
 
-- baseline writes one record when the model returns an approval-class claim
+- baseline writes one record when the model returns an approval claim
 - compiler-mediated returns `403` and writes no record when state does not
   authorize execution
 - compiler-mediated writes one record only when authoritative state includes:
@@ -43,9 +43,9 @@ The host returns a conflict response and writes no record.
 
 ## Same request, different state
 
-The compiler-mediated proof uses the same endpoint, the same approval-class
-model claim, and the same expense action. Only authoritative Context Compiler
-state changes.
+The compiler-mediated proof uses the same endpoint, the same model approval
+claim, and the same expense action. Only authoritative Context Compiler state
+changes.
 
 | Endpoint | Model claim | Authoritative state | Compiler input | Outcome |
 | --- | --- | --- | --- | --- |
@@ -65,7 +65,7 @@ The compiler-mediated host does not treat the visible approval text as
 authorization.
 
 Context Compiler state is the only authorization source for the protected
-mutation after an approval-class claim is present in the compiler-mediated path.
+mutation after an approval claim is present in the compiler-mediated path.
 
 ## Validation
 
@@ -87,13 +87,8 @@ uv run --no-sync pytest python/tests/test_fastapi_expense_approval_live_model.py
 Unless you run that env-var-gated command, this repo has only validated the
 provider-free runtime-boundary path, not the live-provider path.
 
-The live-model path uses the same shared provider contract already used
-elsewhere in this repo:
-
-- `PROVIDER`
-- `MODEL`
-- `OPENAI_API_KEY`
-- `OPENAI_BASE_URL`
+The live-model path uses the shared provider contract documented in
+[PROVIDER_CONTRACT.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/PROVIDER_CONTRACT.md).
 
 ## Run locally
 

diff --git a/python/examples/gateway_middleware/customer_support_routing/README.md b/python/examples/gateway_middleware/customer_support_routing/README.md
@@ -1,12 +1,10 @@
 # Customer support routing
 
-This example demonstrates a host-owned gateway enforcing authoritative
-Context Compiler state before a downstream support handler runs.
+Authoritative state changes whether the gateway lets a billing request reach
+the downstream support handler. This example shows that gateway behavior in a
+host-owned customer support routing flow.
 
-The gateway reads authoritative state and decides whether a request that asks
-for `billing_support` may cross the middleware boundary.
-
-The downstream support service is called only after the gateway allows the
+The gateway calls the downstream support service only after it allows the
 request.
 
 ## Policy mapping

diff --git a/python/examples/prompt_construction/README.md b/python/examples/prompt_construction/README.md
@@ -17,9 +17,7 @@ These generic/examples-first docs teach the enforcement point.
 
 Related concrete runtime surfaces:
 
-- [python/examples/prompt_construction/litellm/README.md](litellm/README.md): LiteLLM-oriented prompt construction
 - [python/reference_integrations/openwebui_pipe/README.md](../../reference_integrations/openwebui_pipe/README.md): Open WebUI pipe integration
-- [typescript/starter_apps/nextjs/README.md](../../../typescript/starter_apps/nextjs/README.md): TypeScript Next.js starter variants for the same enforcement point
 
 ## Example requirements