docs: vision page + messaging alignment (#47)

* chore: 0.1.0 release

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* docs: add vision page

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* docs: add column to project vision in main docs page

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* docs: add adopters table

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

---------

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

.gitignore

@@ -28,6 +28,7 @@ token.txt
 *.backup
 cpex.sbom.xml
 docs/docs/test/
+docs/resources/
 tmp
 *.tgz
 *.gz

ADOPTERS.md

@@ -0,0 +1,12 @@
+# CPEX Adopters
+
+Organizations and projects using CPEX in production or development.
+
+| Project | Description | Link |
+|---------|-------------|------|
+| ContextForge | MCP gateway with CPEX enforcement built in | https://github.com/IBM/mcp-context-forge |
+| Mellea | Agentic framework with CPEX plugin integration | https://github.com/generative-computing/mellea |
+
+## Adding Your Project
+
+Using CPEX? Open a pull request to add your project to this list.

README.md

@@ -4,13 +4,15 @@
 
 # CPEX — ContextForge Plugin Extensibility Framework
 
-<i>A lightweight, composable plugin framework for building extensible AI systems.</i>
+<i>A composable enforcement framework for AI agents and toolchains.</i>
 
 [![CI](https://github.com/contextforge-org/contextforge-plugins-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/contextforge-org/contextforge-plugins-framework/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/cpex.svg?color=blue)](https://pypi.org/project/cpex)
 
+> [**Read the project vision**](https://contextforge-org.github.io/contextforge-plugins-framework/docs/vision/) to learn why hooks, plugins, and policy are the path to agent security.
+
 ## What's CPEX?
 
 CPEX lets you intercept, enforce, and extend application behavior through plugins without modifying core logic.
@@ -41,7 +43,7 @@ pip install cpex
 
 ## Why CPEX?
 
-AI systems interact with tools, APIs, data sources, and other agents. Adding guardrails, observability, or policy checks typically means embedding that logic directly into application code, leading to duplication, tight coupling, and drift.
+AI agents execute across trust domains, calling tools, accessing data, and delegating to other agents. Adding security, governance, or policy enforcement typically means embedding that logic directly into application code, leading to duplication, tight coupling, and drift.
 
 CPEX introduces **standardized interception hooks** between your application and its operations. Plugins attach to these hooks and run automatically, keeping enforcement logic separate from business logic.
 

docs/content/_index.md

@@ -5,7 +5,7 @@ type: docs
 
 # CPEX
 
-**A lightweight plugin framework for building extensible AI systems**
+**A composable enforcement framework for AI agents and toolchains**
 
 CPEX lets you intercept, enforce, and extend application behavior through plugins — without modifying core logic. Define hook points in your application, write plugins that attach to them, and compose enforcement pipelines that run automatically.
 
@@ -46,4 +46,9 @@ Register the plugin, and it runs at every hook invocation. No changes to your ap
 
   [Overview &rarr;]({{< relref "/docs/overview" >}})
 
+- ### Project Vision
+  Why hooks, plugins, and policy are the path to agent security.
+
+  [Vision &rarr;]({{< relref "/docs/vision" >}})
+
 {{% /columns %}}

docs/content/docs/vision.md

@@ -0,0 +1,90 @@
+---
+title: "Vision"
+weight: 5
+---
+
+# Universal Extensibility for AI Security
+
+AI agents execute across trust domains, calling tools, accessing data, and delegating to other agents. No single policy engine or enforcement point is sufficient. The execution path spans LLM proxies, agent frameworks, gateways, and external services. Security policies must be injected across the entire stack.
+
+CPEX is the **composable enforcement framework** that makes this possible.
+
+---
+
+## Hooks Are the Enforcement Plane
+
+Hooks are standardized interception points placed at every boundary where an agent acts, before and after tool calls, LLM completions, prompt fetches, and protocol messages. Plugins attach to hooks and run automatically, keeping enforcement logic separate from business logic.
+
+This architecture deploys identically across the stack, inside LLM proxies, agent frameworks, and gateways. Each layer runs its own plugins. Prompt injection detection at the proxy. Tool authorization at the gateway. Data loss prevention at the agent.
+
+![CPEX hooks deployed across the agent stack](/contextforge-plugins-framework/images/distributed_hooks_control_plane.png)
+
+---
+
+## Hooks Need Policy. Policy Needs Context.
+
+Enforcement is a three-layer problem.
+
+| Layer | Role |
+|-------|------|
+| **Hooks** | Where enforcement happens. Interception, decision, transformation. |
+| **CMF** (Common Message Format) | What you evaluate. A protocol-agnostic context envelope carrying identity, security labels, delegation chains, and content. |
+| **APL** (Attribute Policy Language) | How you define policy. Declarative, attribute-based rules with explicit effects. |
+
+![Hooks, CMF, and APL form a unified enforcement stack](/contextforge-plugins-framework/images/overview_vision.png)
+
+Hooks make enforcement **possible**. Policy makes it **usable**. Context makes it **correct**.
+
+---
+
+## The Policy Spectrum
+
+Different policy types require different enforcement points. CPEX provides hooks at every layer, from soft stylistic policies enforced at the prompt level to hard compliance requirements enforced at infrastructure boundaries.
+
+![Policy spectrum: each policy type maps to a different enforcement point](/contextforge-plugins-framework/images/policy_spectrum.png)
+
+---
+
+## How It Works
+
+An application or framework invokes a hook at a critical operation boundary. The plugin manager dispatches registered plugins (sequentially, concurrently, or fire-and-forget) and returns a result. Plugins can **allow** execution to continue, **block** it with a violation, or **modify** the payload using copy-on-write isolation.
+
+![Plugin execution model: agent → middleware → hook → manager → plugins](/contextforge-plugins-framework/images/integration_execution_model.png)
+
+The plugin manager handles registration, ordering, timeouts, error isolation, and payload chaining. You get a deterministic enforcement pipeline with no surprises.
+
+---
+
+## Where We're Going
+
+CPEX is under active development. The current Python framework is production-ready. The roadmap extends the core in several directions.
+
+- **Rust core.** A shared plugin execution engine with type-safe CMF invariant enforcement, replacing convention-based rules with compile-time guarantees. Python (PyO3) and Go (cgo) bindings enable a single runtime across language consumers.
+
+- **WASM sandboxing.** Portable, capability-based isolation for third-party plugins. Zero-trust by default: no filesystem, network, or host memory unless explicitly granted.
+
+- **APL integration.** Declarative policy pipelines that compose built-in attribute checks with external policy engines (OPA, Cedar, AuthZEN, NeMo Guardrails) in a single evaluation.
+
+- **Plugin catalog.** Discovery, versioning, and installation of plugins from registries. Multiple instances from a single manifest, managed through the CLI.
+
+See the [GitHub milestones](https://github.com/contextforge-org/contextforge-plugins-framework/milestones) and [open issues](https://github.com/contextforge-org/contextforge-plugins-framework/issues) for details.
+
+---
+
+## Projects Using CPEX
+
+| Project | Description |
+|---------|-------------|
+| [ContextForge](https://github.com/IBM/mcp-context-forge) | MCP gateway with CPEX enforcement built in |
+| [Mellea](https://github.com/generative-computing/mellea) | Agentic framework with CPEX plugin integration |
+
+---
+
+## Get Involved
+
+CPEX is part of the [ContextForge](https://github.com/contextforge-org) ecosystem.
+
+- [CPEX Plugin Framework](https://github.com/contextforge-org/contextforge-plugins-framework) (this project)
+- [Contributing Guide](https://github.com/contextforge-org/contextforge-plugins-framework/blob/main/CONTRIBUTING.md)
+
+Contributions, feedback, and plugin ideas are welcome. Open an issue or submit a pull request.