docs: clarify Python repository and package structure

AGENTS.md

@@ -56,15 +56,15 @@ Domains are teaching aids. Enforcement points are primary.
 
 ## Validation
 
-- Canonical Python validation: `uv run pre-commit run --all-files`
+- Canonical validation: `uv run pre-commit run --all-files`
 - Markdown validation: `npx --yes markdownlint-cli2`
 - Before reporting a task complete or opening a PR, run validation relevant to the changed files.
-- If Python files changed, run `uv run pre-commit run --all-files`.
+- If code files changed, run `uv run pre-commit run --all-files`.
 - If Markdown files changed, run `npx --yes markdownlint-cli2`.
 - If multiple areas changed, run all relevant checks.
 - Report the exact validation commands and results.
 - If a required or relevant validation command cannot be run, report why instead of saying the task is complete.
-- Python contributors may use local hooks: `uv run pre-commit run --all-files`
+- Contributors may use local hooks: `uv run pre-commit run --all-files`
 - CI is the authoritative validation path.
 
 ## Example design requirements
@@ -141,10 +141,7 @@ 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.
+The root README owns repository-level discovery.
 
 Do not treat documentation as merely illustrative unless explicitly stated.
 

README.md

@@ -1,4 +1,4 @@
-# Context Compiler Example Integrations
+# Context Compiler Python Example Integrations
 
 What runtime behavior changes when authoritative state exists?
 
@@ -21,14 +21,9 @@ Each example:
 - remains meaningful with an adversarial model stub
 - focuses on the enforcement point rather than the framework
 
-## Start here
-
-Start with the [Python guide](python/README.md).
-
-Use the enforcement-point catalog below when you already know which runtime
-behavior you want to inspect.
-
-Python includes generic examples and reference integrations.
+This repository contains the Python examples and reference integrations. Use
+the enforcement-point catalog below to find the runtime behavior you want to
+inspect.
 
 ## Ecosystem map
 
@@ -50,15 +45,39 @@ Python includes generic examples and reference integrations.
 | [Request construction / context assembly](python/examples/prompt_construction/README.md) | Writing assistant | Python, LiteLLM, Open WebUI |
 | [Tool gating](python/examples/tool_gating/README.md) | Calendar / email / admin | Python, MCP |
 
-## Organization
+## Install
+
+Install the package from PyPI for the shared examples and core dependency:
+
+```shell
+pip install "context-compiler-example-integrations"
+```
+
+Add an extra for the examples you want to run locally:
+
+- `pip install "context-compiler-example-integrations[drafter]"` for Directive Drafter examples
+- `pip install "context-compiler-example-integrations[retrieval]"` for ChromaDB retrieval examples
+- `pip install "context-compiler-example-integrations[fastapi]"` for FastAPI variants
+- `pip install "context-compiler-example-integrations[litellm]"` for LiteLLM examples and reference integrations
+- `pip install "context-compiler-example-integrations[all]"` for all package-managed optional dependencies
+
+Open WebUI is not installed by this package. Its reference integration assumes
+that Open WebUI is already installed and configured as the host runtime.
+
+## Reference integrations
+
+The repository also includes runtime-specific integrations for:
 
-Examples are organized by enforcement point.
+- [LiteLLM Proxy](python/reference_integrations/litellm_proxy/README.md)
+- [Open WebUI](python/reference_integrations/openwebui_pipe/README.md)
 
-- Python includes generic examples and reference integrations.
+## Run an example
 
-## Current layout
+Use a repository checkout to explore an example:
 
-- [python/README.md](python/README.md) - Python examples and reference integrations
+1. Choose an enforcement point from the catalog above.
+2. Open its README for setup, runtime, and validation instructions.
+3. Run the example from the repository root as documented.
 
 ## Adding examples
 
@@ -81,14 +100,14 @@ uv run pre-commit run --all-files
 npx --yes markdownlint-cli2
 ```
 
-Python contributors may install and run local pre-commit hooks:
+Contributors may install and run local pre-commit hooks:
 
 ```bash
 uv run pre-commit install
 uv run pre-commit run --all-files
 ```
 
-CI runs Python validation through pre-commit and Markdown lint separately.
+CI runs pre-commit and Markdown lint separately.
 
 ## License
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-compiler-example-integrations"
-version = "0.2.0"
+version = "0.2.1"
 description = "Example integrations and enforcement-point demonstrations for Context Compiler."
 readme = "python/README.md"
 requires-python = ">=3.11"

python/README.md

@@ -36,36 +36,12 @@ Open WebUI is not installed by this package. The Open WebUI reference
 integration assumes Open WebUI is already installed and configured as the host
 runtime.
 
-## Generic examples
+## Package contents
 
-- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted authoritative state changes 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
+The installed package exposes the Python examples and reference-integration
+modules under `context_compiler_example_integrations`.
 
-## 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:
-
-- [LiteLLM Proxy reference integration](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/litellm_proxy/README.md)
-- [Open WebUI pipe reference integration](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/openwebui_pipe/README.md)
-
-## Run an example
-
-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.
+For the enforcement-point catalog and repository navigation, see the [root
+README](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/README.md).
+Each example and reference integration has its own setup, runtime, and
+validation instructions.