diff --git a/README.md b/README.md
index 6088bbe..387ac1b 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,16 @@ Each example:
 - remains meaningful with an adversarial model stub
 - focuses on the enforcement point rather than the framework
 
+## Start here
+
+Start with [python/README.md](python/README.md) or [typescript/README.md](typescript/README.md) if you want language-level orientation first.
+
+Use the enforcement-point catalog below when you already know which runtime
+behavior you want to inspect.
+
+Both language tracks include generic examples. TypeScript also includes starter
+apps. Python also includes reference integrations.
+
 ## Ecosystem map
 
 | Repo | Question |
@@ -28,13 +38,13 @@ Each example:
 
 | Enforcement Point | Domain | Technology |
 | --- | --- | --- |
-| [Gateway middleware](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/gateway_middleware/README.md) | Customer support routing | generic Python / TypeScript, LiteLLM Proxy |
-| [Schema selection](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/README.md) | Order / incident intake | generic Python / TypeScript, Ollama, LiteLLM, Vercel AI SDK |
-| [Checkpoint continuation](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/README.md) | Travel booking | generic Python / TypeScript, FastAPI, Node, Next.js |
-| [Execution authorization](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/execution_authorization/README.md) | Expense approval | generic Python / TypeScript, Node |
-| [Retrieval filtering](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/README.md) | HR policy lookup | generic Python / TypeScript, ChromaDB |
-| [Request construction / context assembly](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/README.md) | Writing assistant | generic Python / TypeScript, LiteLLM, Open WebUI, Next.js |
-| [Tool gating](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/tool_gating/README.md) | Calendar / email / admin | generic Python / TypeScript, MCP |
+| [Gateway middleware](python/examples/gateway_middleware/README.md) | Customer support routing | generic Python / TypeScript, LiteLLM Proxy |
+| [Schema selection](python/examples/schema_selection/README.md) | Order / incident intake | generic Python / TypeScript, Ollama, LiteLLM, Vercel AI SDK |
+| [Checkpoint continuation](python/examples/checkpoint_continuation/README.md) | Travel booking | generic Python / TypeScript, FastAPI, Node, Next.js |
+| [Execution authorization](python/examples/execution_authorization/README.md) | Expense approval | generic Python / TypeScript, Node |
+| [Retrieval filtering](python/examples/retrieval_filtering/README.md) | HR policy lookup | generic Python / TypeScript, ChromaDB |
+| [Request construction / context assembly](python/examples/prompt_construction/README.md) | Writing assistant | generic Python / TypeScript, LiteLLM, Open WebUI, Next.js |
+| [Tool gating](python/examples/tool_gating/README.md) | Calendar / email / admin | generic Python / TypeScript, MCP |
 
 ## How this repo is organized
 
@@ -65,8 +75,8 @@ This repo is:
 
 ## Current layout
 
-- [python/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/README.md)
-- [typescript/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/README.md)
+- [python/README.md](python/README.md)
+- [typescript/README.md](typescript/README.md)
 
 ## Contribution expectations
 
@@ -77,7 +87,7 @@ Primary examples in this repo should:
 - remain meaningful with an adversarial stub
 - demonstrate observable runtime behavior changes
 
-See [CONTRIBUTING.md](/Users/rlippmann/Source/context-compiler-example-integrations/CONTRIBUTING.md) and [AGENTS.md](/Users/rlippmann/Source/context-compiler-example-integrations/AGENTS.md) for repository rules.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for repository rules.
 
 ## Validation
 
diff --git a/pyproject.toml b/pyproject.toml
index 5b623a5..93a10de 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 name = "context-compiler-example-integrations"
 version = "0.1.0"
 description = "Example integrations and enforcement-point demonstrations for Context Compiler."
-readme = "README.md"
+readme = "python/README.md"
 requires-python = ">=3.11"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Robert Lippmann" }]
@@ -52,7 +52,7 @@ proxy_runtime = [
 ]
 
 [tool.hatch.build.targets.wheel]
-only-include = ["python", "README.md", "LICENSE", "AGENTS.md", "CONTRIBUTING.md"]
+only-include = ["python", "LICENSE", "AGENTS.md", "CONTRIBUTING.md"]
 
 
 [tool.ruff]
diff --git a/python/README.md b/python/README.md
index e76611b..d0f3cbb 100644
--- a/python/README.md
+++ b/python/README.md
@@ -1,16 +1,68 @@
 # Python examples
 
-Python examples in this repo stay organized by enforcement point first.
+This package publishes Python example integrations organized by enforcement
+point first.
 
-Current generic Python examples include:
+Use it when you want concrete Python examples that show how authoritative
+Context Compiler state changes runtime behavior in a host application.
 
-- [python/examples/checkpoint_continuation/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/README.md)
-- [python/examples/execution_authorization/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/execution_authorization/README.md)
-- [python/examples/gateway_middleware/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/gateway_middleware/README.md)
-- [python/examples/prompt_construction/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/README.md)
-- [python/examples/retrieval_filtering/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/README.md)
-- [python/examples/schema_selection/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/README.md)
-- [python/examples/tool_gating/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/tool_gating/README.md)
+The core library lives in
+[`context-compiler`](https://github.com/rlippmann/context-compiler).
+Directive recognition can be added with
+[`context-compiler-directive-drafter`](https://github.com/rlippmann/context-compiler-directive-drafter),
+but that layer is optional. This package is the examples and integration
+patterns layer.
 
-Reference integrations and optional framework-specific examples remain
-secondary to the enforcement point.
+`context-compiler` defines the authority contract.
+`context-compiler-directive-drafter` is optional authority acquisition and
+drafting.
+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
+- [Prompt construction](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state
+- [Retrieval filtering](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/retrieval_filtering/README.md): the host changes which documents are eligible or relevant before returning results
+- [Schema selection](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/schema_selection/README.md): the host picks different workflow or response schemas from authoritative state
+- [Tool gating](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime
+
+## Reference integrations
+
+Python also includes reference integrations for runtime-specific behavior after
+the generic examples.
+
+Open a reference integration when you want to see the same kind of runtime
+behavior on a specific host or framework surface.
+
+Start with the generic example first, then use the Python reference
+integrations to inspect a runtime-specific path:
+
+- [python/reference_integrations/litellm_proxy/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/litellm_proxy/README.md)
+- [python/reference_integrations/openwebui_pipe/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/openwebui_pipe/README.md)
+
+## Run an example
+
+These published package docs are for discovery.
+
+To explore or run an example, use a repository checkout:
+
+1. Clone
+   [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
+2. Choose a generic example or a reference integration.
+3. Open that example's README.
+4. Follow the example-specific setup, runtime, and validation instructions.
diff --git a/python/examples/checkpoint_continuation/README.md b/python/examples/checkpoint_continuation/README.md
index 8305b14..af21145 100644
--- a/python/examples/checkpoint_continuation/README.md
+++ b/python/examples/checkpoint_continuation/README.md
@@ -72,7 +72,7 @@ uv run pytest python/tests/test_checkpoint_continuation_example.py
 ## FastAPI variant
 
 For a request-boundary example, see
-[python/examples/checkpoint_continuation/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/fastapi/README.md).
+[python/examples/checkpoint_continuation/fastapi/README.md](fastapi/README.md).
 
 ## Related integrations
 
@@ -81,6 +81,6 @@ requirements.
 
 Related runtime surfaces:
 
-- [python/examples/checkpoint_continuation/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/fastapi/README.md)
-- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md)
-- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md)
+- [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/execution_authorization/README.md b/python/examples/execution_authorization/README.md
index 3b49182..6533040 100644
--- a/python/examples/execution_authorization/README.md
+++ b/python/examples/execution_authorization/README.md
@@ -37,4 +37,4 @@ small host-owned flow.
 
 For a small TypeScript host runtime surface, see:
 
-- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md)
+- [typescript/starter_apps/node/README.md](../../../typescript/starter_apps/node/README.md)
diff --git a/python/examples/gateway_middleware/README.md b/python/examples/gateway_middleware/README.md
index 11d7dbb..dda01de 100644
--- a/python/examples/gateway_middleware/README.md
+++ b/python/examples/gateway_middleware/README.md
@@ -46,4 +46,4 @@ host-owned flow.
 For a concrete proxy runtime surface, see the LiteLLM Proxy reference
 integration:
 
-- [python/reference_integrations/litellm_proxy/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/litellm_proxy/README.md)
+- [python/reference_integrations/litellm_proxy/README.md](../../reference_integrations/litellm_proxy/README.md)
diff --git a/python/examples/prompt_construction/README.md b/python/examples/prompt_construction/README.md
index cd06d2b..aa83390 100644
--- a/python/examples/prompt_construction/README.md
+++ b/python/examples/prompt_construction/README.md
@@ -17,9 +17,9 @@ These generic/examples-first docs teach the enforcement point.
 
 Related concrete runtime surfaces:
 
-- [python/examples/prompt_construction/litellm/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/litellm/README.md): LiteLLM-oriented prompt construction
-- [python/reference_integrations/openwebui_pipe/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/openwebui_pipe/README.md): Open WebUI pipe integration
-- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md): TypeScript Next.js starter variants for the same enforcement point
+- [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
 
diff --git a/python/examples/prompt_construction/litellm/README.md b/python/examples/prompt_construction/litellm/README.md
index b33653a..9eee0d5 100644
--- a/python/examples/prompt_construction/litellm/README.md
+++ b/python/examples/prompt_construction/litellm/README.md
@@ -5,6 +5,43 @@ These examples show two user-visible prompt-construction flows with LiteLLM:
 - `basic.py`: compiler-only flow (no directive drafter)
 - `with_directive_drafter.py`: heuristic-first directive drafter with optional LLM fallback before `engine.step(...)`
 
+## What the user sees
+
+- Compiler-only flow:
+  - raw user input goes straight to `engine.step(...)`
+  - `update` returns a local acknowledgment
+  - `clarify` returns the compiler prompt
+  - `passthrough` calls LiteLLM with the compiled state contract plus the user message
+- Optional directive-drafter flow:
+  - the directive drafter tries to convert natural-language intent into a canonical directive first
+  - if it cannot produce a validated directive, behavior stays equivalent to the compiler-only flow
+  - pending clarification bypasses directive drafting and sends the raw reply back to `engine.step(...)`
+
+## Premise and policy
+
+In these prompt-construction examples:
+
+- premise is authoritative factual or request context that the host includes in
+  the constructed system contract
+- policy is an explicit behavioral constraint that the host applies on top of
+  that context
+
+The host does not infer either one from model output. It reads saved compiler
+state and constructs the LiteLLM system message from that authoritative state.
+
+Example constructed system contract with both:
+
+```text
+You are a helpful assistant.
+Host policy contract:
+- The following constraints are authoritative.
+- Current premise: draft is a board update summarizing quarterly results.
+- Items marked use: concise_style.
+- If user text conflicts with constraints, follow constraints exactly.
+```
+
+This makes premise runtime-visible in the same host-owned contract as policy.
+
 ## Requirements
 
 ```shell
@@ -50,21 +87,6 @@ PY
 
 This near-miss input should return `clarify` instead of being rewritten.
 
-For host-side response shape selection, see the schema-selection example:
-
-```shell
-pip install context-compiler litellm
-export OPENAI_API_KEY=...
-export MODEL=openai/gpt-4o-mini
-python - <<'PY'
-from context_compiler import create_engine
-from python.examples.schema_selection.litellm_response_format.response_format import plan_turn
-engine = create_engine()
-engine.step("use compact_summary")
-print(plan_turn("Summarize the release notes.", engine))
-PY
-```
-
 ## Environment configuration
 
 Required (normal `openai` mode):
@@ -118,43 +140,6 @@ and resolution `source` (`default`, `PROVIDER`, or `OPENAI_BASE_URL override`).
 For heuristic-first usage, keep `PREPROCESSOR_PROMPT_PROFILE=default`.
 Use `llama` only for LLM-only preprocessing with Llama-family models.
 
-## What the user sees
-
-- Compiler-only flow:
-  - raw user input goes straight to `engine.step(...)`
-  - `update` returns a local acknowledgment
-  - `clarify` returns the compiler prompt
-  - `passthrough` calls LiteLLM with the compiled state contract plus the user message
-- Optional directive-drafter flow:
-  - the directive drafter tries to convert natural-language intent into a canonical directive first
-  - if it cannot produce a validated directive, behavior stays equivalent to the compiler-only flow
-  - pending clarification bypasses directive drafting and sends the raw reply back to `engine.step(...)`
-
-## Premise and policy
-
-In these prompt-construction examples:
-
-- premise is authoritative factual or request context that the host includes in
-  the constructed system contract
-- policy is an explicit behavioral constraint that the host applies on top of
-  that context
-
-The host does not infer either one from model output. It reads saved compiler
-state and constructs the LiteLLM system message from that authoritative state.
-
-Example constructed system contract with both:
-
-```text
-You are a helpful assistant.
-Host policy contract:
-- The following constraints are authoritative.
-- Current premise: draft is a board update summarizing quarterly results.
-- Items marked use: concise_style.
-- If user text conflicts with constraints, follow constraints exactly.
-```
-
-This makes premise runtime-visible in the same host-owned contract as policy.
-
 ## Usage pattern
 
 Use these files as host-side integration references.
diff --git a/python/examples/retrieval_filtering/README.md b/python/examples/retrieval_filtering/README.md
index be4b9ed..31ee9a6 100644
--- a/python/examples/retrieval_filtering/README.md
+++ b/python/examples/retrieval_filtering/README.md
@@ -67,4 +67,4 @@ The generic examples teach the retrieval-filtering enforcement point first.
 
 Concrete runtime surface currently linked from this repo:
 
-- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md)
+- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](chromadb_hr_policy_lookup/README.md)
diff --git a/python/examples/schema_selection/README.md b/python/examples/schema_selection/README.md
index b519a92..855ca56 100644
--- a/python/examples/schema_selection/README.md
+++ b/python/examples/schema_selection/README.md
@@ -37,6 +37,6 @@ The generic examples teach the enforcement point first.
 
 Concrete runtime surfaces currently linked from this repo:
 
-- [python/examples/schema_selection/ollama_structured_output/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/ollama_structured_output/README.md)
+- [python/examples/schema_selection/ollama_structured_output/README.md](ollama_structured_output/README.md)
 - `python/examples/schema_selection/litellm_response_format/response_format.py`
-- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md)
+- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](../../../typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md)
diff --git a/python/examples/schema_selection/ollama_structured_output/README.md b/python/examples/schema_selection/ollama_structured_output/README.md
index d5d8129..6798664 100644
--- a/python/examples/schema_selection/ollama_structured_output/README.md
+++ b/python/examples/schema_selection/ollama_structured_output/README.md
@@ -44,7 +44,7 @@ Tests do not assert exact model wording.
 ## Run without Ollama
 
 ```shell
-uv run python examples/integrations/ollama_structured_output/example.py
+uv run python python/examples/schema_selection/ollama_structured_output/example.py
 ```
 
 ## Optional Ollama smoke run
@@ -52,7 +52,7 @@ uv run python examples/integrations/ollama_structured_output/example.py
 ```shell
 export RUN_OLLAMA_SMOKE=1
 export OLLAMA_MODEL=llama3.1
-uv run python examples/integrations/ollama_structured_output/example.py
+uv run python python/examples/schema_selection/ollama_structured_output/example.py
 ```
 
 When smoke mode is enabled, the host sends the selected JSON Schema through Ollama `format`.
diff --git a/python/reference_integrations/litellm_proxy/README.md b/python/reference_integrations/litellm_proxy/README.md
index ab231ac..08ebf9e 100644
--- a/python/reference_integrations/litellm_proxy/README.md
+++ b/python/reference_integrations/litellm_proxy/README.md
@@ -12,6 +12,27 @@ Available hook files:
 - Basic replay-only hook: `context_compiler_precall_hook.py`
 - Directive-drafter-enabled hook: `context_compiler_precall_hook_with_directive_drafter.py`
 
+## Runtime behavior
+
+- User messages are replayed through Context Compiler before the model call.
+- LiteLLM Proxy is the gateway surface; Context Compiler remains the authority layer for saved state.
+- If result is `confirm`, the proxy does not call the downstream model and LiteLLM surfaces the confirmation as an HTTP 400 response.
+- If result is `passthrough`, the proxy forwards the request normally.
+- If result is `update`, the proxy injects compiler state as a system message and then calls the model.
+- Unsupported LiteLLM callback `call_type` values return the original request data unchanged.
+
+Optional directive-drafter behavior:
+
+- Only the latest user transcript message is drafted for compiler replay input.
+- Heuristic runs first; if no directive is found, LLM fallback is attempted.
+- Forwarded upstream request messages are not rewritten (except injected compiler system message).
+
+Runtime verification boundary:
+
+- Basic hook: opt-in runtime smoke test covers proxy startup, blocked request behavior, and forwarded contract injection at the LiteLLM Proxy runtime boundary.
+- Directive-drafter hook: opt-in runtime smoke test covers the same proxy boundary behaviors, plus verifies drafting only changes compiler replay input and does not rewrite the forwarded upstream request payload.
+- Directive-drafter fallback model behavior remains environment-sensitive and is primarily covered by unit-style tests rather than this local stub runtime smoke path.
+
 ## Requirements
 
 ```shell
@@ -47,36 +68,6 @@ litellm --config python/reference_integrations/litellm_proxy/config.example.yaml
 `config.example.yaml` includes both OpenAI and Ollama model definitions.
 Use the Ollama model entry for local testing without API credentials.
 
-## Run proxy
-
-Typical startup command (environment-sensitive):
-
-```shell
-litellm --config python/reference_integrations/litellm_proxy/config.example.yaml
-```
-
-The reference integration is covered by unit tests and an opt-in runtime
-smoke test. See "Opt-in Runtime Smoke Test" below for details.
-
-Validated basic-hook behaviors:
-
-- passthrough: upstream model called normally
-- update: compiler state injected before upstream model call
-- confirm: request blocked before upstream model call and surfaced as HTTP 400
-
-The proxy runs on `http://localhost:4000` by default.
-By default, `config.example.yaml` points to the basic replay-only hook.
-To use the directive-drafter variant, switch the callback path in the config.
-The callback path must be importable by LiteLLM in the environment where the
-proxy process starts.
-
-When starting LiteLLM from the repo root, prefer fully qualified callback
-imports in automated configs, for example:
-
-```text
-python.reference_integrations.litellm_proxy.context_compiler_precall_hook.proxy_handler_instance
-```
-
 ## Make a request
 
 ```python
@@ -105,26 +96,23 @@ curl http://localhost:4000/v1/chat/completions \
   }'
 ```
 
-## Runtime behavior
-
-- User messages are replayed through Context Compiler before the model call.
-- LiteLLM Proxy is the gateway surface; Context Compiler remains the authority layer for saved state.
-- If result is `confirm`, the proxy does not call the downstream model and LiteLLM surfaces the confirmation as an HTTP 400 response.
-- If result is `passthrough`, the proxy forwards the request normally.
-- If result is `update`, the proxy injects compiler state as a system message and then calls the model.
-- Unsupported LiteLLM callback `call_type` values return the original request data unchanged.
+## Run proxy
 
-Optional directive-drafter behavior:
+The reference integration is covered by unit tests and an opt-in runtime
+smoke test. See "Opt-in Runtime Smoke Test" below for details.
 
-- Only the latest user transcript message is drafted for compiler replay input.
-- Heuristic runs first; if no directive is found, LLM fallback is attempted.
-- Forwarded upstream request messages are not rewritten (except injected compiler system message).
+The proxy runs on `http://localhost:4000` by default.
+By default, `config.example.yaml` points to the basic replay-only hook.
+To use the directive-drafter variant, switch the callback path in the config.
+The callback path must be importable by LiteLLM in the environment where the
+proxy process starts.
 
-Runtime verification boundary:
+When starting LiteLLM from the repo root, prefer fully qualified callback
+imports in automated configs, for example:
 
-- Basic hook: opt-in runtime smoke test covers proxy startup, blocked request behavior, and forwarded contract injection at the LiteLLM Proxy runtime boundary.
-- Directive-drafter hook: opt-in runtime smoke test covers the same proxy boundary behaviors, plus verifies drafting only changes compiler replay input and does not rewrite the forwarded upstream request payload.
-- Directive-drafter fallback model behavior remains environment-sensitive and is primarily covered by unit-style tests rather than this local stub runtime smoke path.
+```text
+python.reference_integrations.litellm_proxy.context_compiler_precall_hook.proxy_handler_instance
+```
 
 Optional env vars for directive-drafter fallback:
 
diff --git a/python/reference_integrations/openwebui_pipe/README.md b/python/reference_integrations/openwebui_pipe/README.md
index 84cb6f2..66765e7 100644
--- a/python/reference_integrations/openwebui_pipe/README.md
+++ b/python/reference_integrations/openwebui_pipe/README.md
@@ -3,17 +3,6 @@
 These examples show how an Open WebUI pipe changes runtime behavior with saved
 compiler state.
 
-Tested target: Open WebUI `v0.8.12`.
-Validated at runtime on stock Docker Open WebUI with a real backend model provider.
-
-Compatibility note: OpenWebUI `0.9.x` changed `Users.get_user_by_id` to async.
-These examples support both sync (`0.8.x`) and async (`0.9.x`) user lookup.
-
-## Files
-
-- `open_webui_pipe.py`: basic integration, no directive-drafter layer (recommended/default).
-- `open_webui_pipe_with_directive_drafter.py`: optional/experimental directive-drafter layer (rule-based check first, then optional model fallback) before `engine.step(...)`.
-
 ## Core behavior
 
 - Directive-only turns are handled locally and return a fixed response.
@@ -43,6 +32,11 @@ The host injects this block into the forwarded request. Premise is not only a
 syntax or lifecycle rule here; it is part of the runtime-visible state that
 shapes the downstream request.
 
+## Files
+
+- `open_webui_pipe.py`: basic integration, no directive-drafter layer (recommended/default).
+- `open_webui_pipe_with_directive_drafter.py`: optional/experimental directive-drafter layer (rule-based check first, then optional model fallback) before `engine.step(...)`.
+
 ## Setup
 
 Quick start for the base pipe:
@@ -211,6 +205,14 @@ If you want a slightly broader manual pass:
 - directive-drafter pipe: same clarify (near-miss is passed through unchanged)
 - why this matters: the app waits for explicit, valid directive text before changing state.
 
+## Compatibility
+
+Tested target: Open WebUI `v0.8.12`.
+Validated at runtime on stock Docker Open WebUI with a real backend model provider.
+
+Compatibility note: OpenWebUI `0.9.x` changed `Users.get_user_by_id` to async.
+These examples support both sync (`0.8.x`) and async (`0.9.x`) user lookup.
+
 ## Troubleshooting
 
 - `BASE_MODEL_ID is required`: set a valid Open WebUI model id in the function valves, or enable `ALLOW_MISSING_BASE_MODEL_FOR_DEBUG=true` only for local testing.
diff --git a/typescript/README.md b/typescript/README.md
index adc1566..c64dc51 100644
--- a/typescript/README.md
+++ b/typescript/README.md
@@ -1,22 +1,56 @@
 # TypeScript examples
 
-TypeScript examples in this repo stay organized by enforcement point first.
+This package will publish TypeScript example integrations organized by
+enforcement point first.
 
-Current generic TypeScript examples include:
+Use it when you want concrete TypeScript examples that show how authoritative
+Context Compiler state changes runtime behavior in a host application.
 
-- [typescript/examples/checkpoint_continuation/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/checkpoint_continuation/README.md)
-- [typescript/examples/execution_authorization/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/execution_authorization/README.md)
-- [typescript/examples/gateway_middleware/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/gateway_middleware/README.md)
-- [typescript/examples/prompt_construction/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/prompt_construction/README.md)
-- [typescript/examples/retrieval_filtering/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/retrieval_filtering/README.md)
-- [typescript/examples/schema_selection/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/README.md)
-- [typescript/examples/tool_gating/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/tool_gating/README.md)
+The core library lives in
+[`context-compiler-ts`](https://github.com/rlippmann/context-compiler-ts).
+Directive recognition can be added with
+[`context-compiler-directive-drafter-ts`](https://github.com/rlippmann/context-compiler-directive-drafter-ts),
+but that layer is optional. This package is the examples and integration
+patterns layer.
+
+`context-compiler-ts` defines the authority contract.
+`context-compiler-directive-drafter-ts` is optional authority acquisition and
+drafting.
+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 starter apps.
+
+## 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/typescript/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/typescript/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/typescript/examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
+- [Prompt construction](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state
+- [Retrieval filtering](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/retrieval_filtering/README.md): the host changes which documents are eligible or relevant before returning results
+- [Schema selection](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/schema_selection/README.md): the host picks different workflow or response schemas from authoritative state
+- [Tool gating](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime
+
+## Starter apps
 
 Starter apps are available when a small runnable host makes the enforcement
 point easier to see:
 
-- [starter_apps/node](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) - execution authorization starter variants for a small Node HTTP server
-- [starter_apps/nextjs](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md) - request construction and context assembly starter variants for a minimal Next.js App Router app
+- [starter_apps/node](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/starter_apps/node/README.md) - execution authorization starter variants for a small Node HTTP server
+- [starter_apps/nextjs](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/starter_apps/nextjs/README.md) - request construction and context assembly starter variants for a minimal Next.js App Router app
+
+Open a starter app when you want a minimal host runtime around the enforcement
+point instead of a generic example alone.
 
 In these starters:
 
@@ -30,3 +64,15 @@ Each starter app now comes in two variants:
 
 The compiler-only flow is always the baseline. If a starter includes
 directive-drafter, it is there to help acquisition, not to own state changes.
+
+## Run an example
+
+These published package docs are for discovery.
+
+To explore or run an example, use a repository checkout:
+
+1. Clone
+   [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
+2. Choose a generic example or a starter app.
+3. Open that example's README.
+4. Follow the example-specific setup, runtime, and validation instructions.
diff --git a/typescript/examples/checkpoint_continuation/README.md b/typescript/examples/checkpoint_continuation/README.md
index dcde06d..648299a 100644
--- a/typescript/examples/checkpoint_continuation/README.md
+++ b/typescript/examples/checkpoint_continuation/README.md
@@ -83,6 +83,6 @@ framework.
 
 Related runtime surfaces:
 
-- [python/examples/checkpoint_continuation/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/fastapi/README.md)
-- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md)
-- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md)
+- [python/examples/checkpoint_continuation/fastapi/README.md](../../../python/examples/checkpoint_continuation/fastapi/README.md)
+- [typescript/starter_apps/node/README.md](../../starter_apps/node/README.md)
+- [typescript/starter_apps/nextjs/README.md](../../starter_apps/nextjs/README.md)
diff --git a/typescript/examples/execution_authorization/README.md b/typescript/examples/execution_authorization/README.md
index cd7366a..447cfd9 100644
--- a/typescript/examples/execution_authorization/README.md
+++ b/typescript/examples/execution_authorization/README.md
@@ -33,4 +33,4 @@ small host-owned flow.
 
 For a small TypeScript host runtime surface, see:
 
-- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md)
+- [typescript/starter_apps/node/README.md](../../starter_apps/node/README.md)
diff --git a/typescript/examples/prompt_construction/README.md b/typescript/examples/prompt_construction/README.md
index 9b1d00a..1c36814 100644
--- a/typescript/examples/prompt_construction/README.md
+++ b/typescript/examples/prompt_construction/README.md
@@ -15,9 +15,9 @@ These generic/examples-first docs teach the enforcement point.
 
 Related concrete runtime surfaces:
 
-- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md): TypeScript Next.js starter variants
-- [python/examples/prompt_construction/litellm/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/litellm/README.md): Python LiteLLM-oriented prompt construction
-- [python/reference_integrations/openwebui_pipe/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/openwebui_pipe/README.md): Python Open WebUI pipe integration
+- [typescript/starter_apps/nextjs/README.md](../../starter_apps/nextjs/README.md): TypeScript Next.js starter variants
+- [python/examples/prompt_construction/litellm/README.md](../../../python/examples/prompt_construction/litellm/README.md): Python LiteLLM-oriented prompt construction
+- [python/reference_integrations/openwebui_pipe/README.md](../../../python/reference_integrations/openwebui_pipe/README.md): Python Open WebUI pipe integration
 
 ## Example requirements
 
diff --git a/typescript/examples/retrieval_filtering/README.md b/typescript/examples/retrieval_filtering/README.md
index 62236c2..5f1cf62 100644
--- a/typescript/examples/retrieval_filtering/README.md
+++ b/typescript/examples/retrieval_filtering/README.md
@@ -40,4 +40,4 @@ The generic examples teach the retrieval-filtering enforcement point first.
 
 Concrete runtime surface currently linked from this repo:
 
-- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md)
+- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](../../../python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md)
diff --git a/typescript/examples/schema_selection/README.md b/typescript/examples/schema_selection/README.md
index 41cac8d..214d2a4 100644
--- a/typescript/examples/schema_selection/README.md
+++ b/typescript/examples/schema_selection/README.md
@@ -37,6 +37,6 @@ The generic examples teach the enforcement point first.
 
 Concrete runtime surfaces currently linked from this repo:
 
-- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md)
-- [python/examples/schema_selection/ollama_structured_output/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/ollama_structured_output/README.md)
+- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](vercel_ai_sdk_generate_object/README.md)
+- [python/examples/schema_selection/ollama_structured_output/README.md](../../../python/examples/schema_selection/ollama_structured_output/README.md)
 - `python/examples/schema_selection/litellm_response_format/response_format.py`
diff --git a/typescript/starter_apps/nextjs/README.md b/typescript/starter_apps/nextjs/README.md
index 1f41188..8284aa2 100644
--- a/typescript/starter_apps/nextjs/README.md
+++ b/typescript/starter_apps/nextjs/README.md
@@ -1,9 +1,21 @@
 # Next.js starter apps
 
+Open this folder when you want a minimal App Router host around the examples
+instead of a generic example alone.
+
+This area teaches request construction first. It shows how a host restores
+saved state, builds a request payload from that state, and makes the runtime
+effect visible before any live model call.
+
 The Next.js starter app now comes in two small variants:
 
-- [basic](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/basic/README.md) - compiler-only baseline adapted from the last `nextjs-basic` example in `context-compiler-ts`
-- [with_drafter](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)`
+- [basic](basic/README.md) - compiler-only baseline adapted from the last `nextjs-basic` example in `context-compiler-ts`
+- [with_drafter](with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)`
+
+Open `basic` first if you want the smallest baseline.
+
+Open `with_drafter` when you want to compare that baseline with an optional
+acquisition layer that still leaves saved-state authority with the compiler.
 
 In both variants:
 
diff --git a/typescript/starter_apps/node/README.md b/typescript/starter_apps/node/README.md
index 6ace4c0..96fffa9 100644
--- a/typescript/starter_apps/node/README.md
+++ b/typescript/starter_apps/node/README.md
@@ -1,9 +1,21 @@
 # Node starter apps
 
+Open this folder when you want a small runnable Node host instead of a generic
+example alone.
+
+This area teaches execution authorization first. It shows how a host preserves
+saved state across requests and changes runtime behavior before any downstream
+model or tool path would continue.
+
 The Node starter app now comes in two small variants:
 
-- [basic](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/basic/README.md) - compiler-only baseline adapted from the last `node-basic` example in `context-compiler-ts`
-- [with_drafter](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)`
+- [basic](basic/README.md) - compiler-only baseline adapted from the last `node-basic` example in `context-compiler-ts`
+- [with_drafter](with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)`
+
+Open `basic` first if you want the smallest baseline.
+
+Open `with_drafter` when you want to compare that baseline with an optional
+acquisition layer that still leaves saved-state authority with the compiler.
 
 In both variants: