docs: improve navigation and package-facing documentation (#51)

* docs: improve example navigation

* docs: use Python README for package publication

* docs: prepare TypeScript README for future npm package

* docs: normalize README links and fix Ollama commands

* docs: simplify language README navigation

* docs: clarify example discovery workflow

* docs: simplify dense Python integration READMEs

* docs: fix Open WebUI README troubleshooting heading

Author: rlippmann

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
 

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]

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.

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)

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)

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)

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
 

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.

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)

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)